xsubpp および xsubpp 内部関数で作成された変数-*- buffer-read-only: t -*-
!!!!!!! DO NOT EDIT THIS FILE !!!!!!! This file is built by autodoc.pl extracting documentation from the C source files.
perlapi - perl public API の自動生成ドキュメント
このファイルは embed.pl で生成された perl の公式な API のドキュメントです; 特にエクステンションの作者が使うかもしれない関数、マクロ、フラグ、変数の 一覧です。 ここに挙げられていないどの関数のインターフェースも予告なしに 変更されることがあります。 この理由により、エクステンションを書くときに proto.h に挙げられている関数を 盲目的に使うことは避けるべきです。
全ての Perl API グローバル変数は PL_ という接頭辞をつけて 参照しなければならないということに注意してください。 一部のマクロは以前のものとの互換性を確保していてはいますが、それは将来の リリースにおいては無効になるかもしれません。
Perl はもともとも US-ASCII (つまり番号が 0 - 127 の範囲の文字)のみを 扱うように書かれていました。 そして文書とコメントは、実際には 0 - 255 の範囲全体を意味しているときに、 未だに ASCII という用語を使っているかもしれません。
Perl は EBCDIC (perlebcdic 参照) または ASCII でコンパイルおよび 実行できます。 ほとんどの文書は(およびコードのコメントさえも) EBCDIC の可能性を 無視しています。 ほとんどあらゆる用途で違いは透過的です。 例えば、EBCDIC では、Unicode 文字列をエンコードするのに UTF-8 ではなく UTF-EBCDIC が使われ、この文書で utf8 (および関数名を含むこの名前の 変形) を参照している場所ではどこでも UTF-EBCDIC を意味します。 しかし文字の番号は ASCII, EBCDIC, UTF- エンコーディングで異なり、 UTF-EBCDIC でエンコードされた文字列は UTF-8 よりも多くのバイト数を 使うことがあります。
また、一部の EBCDIC マシンでは、US-ASCII (または Unicode の用語では Basic Latin) を操作すると文書化されている関数は実際には対応する US-ASCII の サブセットではなく、EBCDIC の範囲の 256 文字全てを操作することがあります。
以下のリストは大文字小文字を無視したアルファベット順です。
G_SCALAR か G_ARRAY しか返さないような GIMME_V の、過去互換性の ためのものです; 無効コンテキストでは、これは G_SCALAR を返します。 廃止予定です。 代わりに GIMME_V を使ってください。
U32 GIMMEXSUB 作成者のための、Perl の wantarray に透過なものです。 G_VOID、G_SCALAR、G_ARRAY をそれぞれ、無効コンテキスト、スカラ コンテキスト、リストコンテキストのときに返します。
U32 GIMME_Vリストコンテキストを示すために使われます。 GIMME_V、GIMME、perlcall を参照してください。
コールバックから返される引数が破棄されるべきものであることを示します。 perlcall を参照してください。
コールバックを Perl の eval で囲むのを強制するために使われます。 perlcall を参照してください。
コールバックに渡す引数がないことを示します。 perlcall を参照してください。
スカラコンテキストを示すのに使われます。 GIMME_V, GIMME, perlcall を参照してください。
無効コンテキストを示すために使われます。 GIMME_V と perlcall を参照してください。
av_len() と同様です。 廃止予定なので、代わりに av_len() を使ってください。
int AvFILL(AV* av)配列をクリアし、空にします。 配列自身が使っているメモリの解放はしません。
void av_clear(AV *av)SV を配列の最後にプッシュします; もし必要なら配列を作ります。 一般的に複製された慣用句を削除するための小さい内部ヘルパーです。
注意: この関数は実験的で、予告なしに変更あるいは削除されるかもしれません。
void av_create_and_push(AV **const avp, SV *const val)SV を配列の最初に unshift します; もし必要なら配列を作ります。 一般的に複製された慣用句を削除するための小さい内部ヘルパーです。
注意: この関数は実験的で、予告なしに変更あるいは削除されるかもしれません。
SV** av_create_and_unshift_one(AV **const avp, SV *const val)配列から、添え字が key の要素を削除します。 削除された要素を返します。 もし flags が G_DISCARD なら、要素は解放されて NULL が返されます。
SV* av_delete(AV *av, I32 key, I32 flags)添え字が key の要素が既に初期化されているなら真を返します。
これは、初期化されていない配列要素は &PL_sv_undef が セットされているという事実に依存しています。
bool av_exists(AV *av, I32 key)配列を事前拡張します。 key は、拡張された後の配列の添え字です。
void av_extend(AV *av, I32 key)配列中の指定された添え字にある SV を返します。 key は添え字です。 lval がセットされている場合、フェッチはストアの一部となります。 戻り値の SV* に対して参照外しをする場合にそれがヌルでないかを チェックしてください。
この関数をどのように tie されたハッシュに使うかに関するさらなる情報は "Understanding the Magic of Tied Hashes and Arrays" in perlguts を 参照してください。
SV** av_fetch(AV *av, I32 key, I32 lval)配列の最大の添え字を与えられた数値にセットします; Perl の $#array = $fill; と等価です。
av_fill() から返った後、配列の要素数は fill + 1 になります。 配列が以前より短くなった場合は、追加された要素は PL_sv_undef が セットされます。 配列がより長くなった場合は、超過した要素は解放されます。 av_fill(av, -1) は av_clear(av) と同じです。
void av_fill(AV *av, I32 fill)配列中で最大の添え字を返します。 配列の要素数は av_len(av) + 1 です。 配列が空である場合には -1 を返します。
I32 av_len(AV *av)新しい AV を生成して、SV のリストで埋めます。 その SV は配列へとコピーされるので、av_make を呼び出した後で 解放することもできます。 新たな AV はその参照カウントとして 1 を持ちます。
AV* av_make(I32 size, SV **strp)配列の最後にある SV をポップします。 配列が空である場合には &PL_sv_undef を返します。
SV* av_pop(AV *av)配列の末尾に SV をプッシュします。 追加されたものにあわせて、配列は自動的に大きくなります。 av_store と同様、一つの参照カウントの所有権を持ちます。
void av_push(AV *av, SV *val)配列の先頭にある SV をシフトして取り出します。 配列が空なら &PL_sv_undef を返します。
SV* av_shift(AV *av)SV を配列に格納します。 配列の添え字は key で指定します。 戻り値は操作が失敗したり、(tie されている配列の場合のように)値を実際に 配列に格納する必要がないような場合には NULL になります。 さもなければ、取得したオリジナルの SV* の参照外しをすることができます。 呼び出し側は、呼び出しの前に val の参照カウントを適切にインクリメントし、 関数が NULL を返した場合には参照カウントをデクリメントする責任が あるということに注意してください。
この関数をどのように tie されたハッシュに使うかに関するさらなる情報は "Understanding the Magic of Tied Hashes and Arrays" in perlguts を 参照してください。
SV** av_store(AV *av, I32 key, SV *val)配列を undefine します。 配列自身が使っていたメモリーを解放します。
void av_undef(AV *av)配列の先頭に、与えられた数だけの undef 値を unsfhit します。 追加されたものにあわせて、配列は自動的に大きくなります。 追加された新しい要素に対して値を代入するには、この後で av_store を 使わなければなりません。
void av_unshift(AV *av, I32 num)指定された Perl 配列の AV を返します。 flags は gv_fetchpv に渡されます。 GV_ADD がセットされていて、指定された変数が存在していなければ、新たに 生成されます。 flags がゼロで、かつ、指定された変数がなかった場合には NULL が返されます。
注意: この関数の perl_ の形は廃止予定です。
AV* get_av(const char *name, I32 flags)新たな AV を生成します。 参照カウントは 1 に設定されます。
AV* newAV()配列をソートします。 以下は例です:
sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale);現在のところ、これは常にマージソートを使います。 さらに柔軟なルーチンのためには sortsv_flags を参照してください。
void sortsv(SV** array, size_t num_elts, SVCOMPARE_t cmp)様々なオプション付きで配列をソートします。
void sortsv_flags(SV** array, size_t num_elts, SVCOMPARE_t cmp, U32 flags)指定された Perl サブルーチンに対するコールバックを呼び出します。 perlcall を参照してください。
注意: この関数の perl_ の形は廃止予定です。
I32 call_argv(const char* sub_name, I32 flags, char** argv)指定された Perl サブルーチンに対するコールバックを呼び出します。 bless されたオブジェクトがスタック上になければなりません。 perlcall を参照してください。
注意: この関数の perl_ の形は廃止予定です。
I32 call_method(const char* methname, I32 flags)指定された Perl サブルーチンに対するコールバックを呼び出します。 perlcall を参照してください。
注意: この関数の perl_ の形は廃止予定です。
I32 call_pv(const char* sub_name, I32 flags)SV にある名前を持った Perl サブルーチンに対するコールバックを呼び出します。 perlcall を参照してください。
注意: この関数の perl_ の形は廃止予定です。
I32 call_sv(SV* sv, VOL I32 flags)コールバックにあるブラケットを開きます。 LEAVE と perlcall を参照してください。
ENTER;Perl に対して、与えられた文字列を eval してその結果をSV* に返すように 指示します。
注意: この関数の perl_ の形は廃止予定です。
SV* eval_pv(const char* p, I32 croak_on_error)Perl に対し、SV にある文字列を eval するように指示します。
注意: この関数の perl_ の形は廃止予定です。
I32 eval_sv(SV* sv, I32 flags)コールバックにある一時変数のためのブラケットを閉じます。 SAVETMPS と perlcall を参照してください。
FREETMPS;コールバック上のブラケットを閉じます。 ENTER と perlcall を参照してください。
LEAVE;コールバックにある一時変数のためにブラケットを開けます。 FREETMPS と perlcall を参照してください。
SAVETMPS;char が US-ASCII (Basic Latin) 英数字(下線を含む)、もしくは数字で あるかどうかを表わす真偽値を返します。
bool isALNUM(char ch)char が US-ASCII (Basic Latin) 英数字であるかどうかを表わす真偽値を 返します。
bool isALPHA(char ch)char が US-ASCII (Basic Latin) 数字であるかどうかを表わす真偽値を 返します。
bool isDIGIT(char ch)char が US-ASCII (Basic Latin) 小文字であるかどうかを表わす真偽値を 返します。
bool isLOWER(char ch)char が US-ASCII (Basic Latin) 空白であるかどうかを表わす真偽値を 返します。
bool isSPACE(char ch)char が US-ASCII (Basic Latin) 大文字であるかどうかを表わす真偽値を 返します。
bool isUPPER(char ch)指定された文字を小文字に変換します。 US-ASCII (Basic Latin) の範囲の外側の文字は大文字小文字はないものとします。
char toLOWER(char ch)指定された文字を大文字に変換します。 US-ASCII (Basic Latin) の範囲の外側の文字は大文字小文字はないものとします。
char toUPPER(char ch)現在のものをクローン化することによって新しいインタプリタを作成し、 それを返します。
perl_clone は以下のフラグを引数として受け取ります:
CLONEf_COPY_STACKS - これは、つまり、スタックもコピーするために使います; これがない場合、データのみをクローンし、スタックはしません; これがある場合、スタックをコピーして、新しいインタプリタは以前のものと まったく同じ位置から実行する準備が出来ています。 疑似 fork コードは COPY_STACKS を使いますが、threads->create は使いません。
CLONEf_KEEP_PTR_TABLE perl_clone は、古い変数へのポインタをキーとして、新しい変数を値として ptr_table を保持します; これにより、何かがクローンされて、再び クローンされないけれども単に値を使って参照カウントを増やしているかを チェックできるようにします。 KEEP_PTR_TABLE がセットされていないと、perl_clone は ptr_table_free(PL_ptr_table); PL_ptr_table = NULL; を使って ptr_table を削除します; これを保持し続ける理由は、図示する perl が スキャンする外側の変数の一部を複製したい場合; このコードの例は threads.xs create にあります。
CLONEf_CLONE_HOST これは win32 のもので、unix では無視されます; perl に、自身を クローンするのに(c++ である)win32host コードを知らせます; これは、 二つのスレッドを同時に実行したいなら、win32 で必要です; 単に何かを別々の perl インタプリタで実行したいなら、これは捨てて元のものを返します; 何もする 必要はありません。
PerlInterpreter* perl_clone(PerlInterpreter *proto_perl, UV flags)CV のスタッシュを返します。
HV* CvSTASH(CV* cv)name の長さを得るために strlen を使い、それから get_cvn_flags を 呼び出します。
注意: この関数の perl_ の形は廃止予定です。
CV* get_cv(const char* name, I32 flags)指定された Perl サブルーチンの CV を返します。 flags は gv_fetchpvn_flags に渡されます。 GV_ADD がセットされ、Perl サブルーチンが存在しない場合は、これが 宣言されます(これは sub name; と同じ効果です)。 GV_ADD がセットされず、Perl サブルーチンが存在しない場合は、NULL が 返されます。
注意: この関数の perl_ の形は廃止予定です。
CV* get_cvn_flags(const char* name, STRLEN len, I32 flags)CV の全ての有効な要素を片付けます。 これは明示的な undef &foo によってか、参照カウントが 0 になることによって 起こります。 前者の場合、CvOUTSIDE ポインタは維持するので、全ての無名の子は完全な レキシカルスコープチェーンに従ったままです。
void cv_undef(CV* cv)name の文字列部で示された名前のモジュールを読み込みます。 ファイル名ではなく実際のモジュール名を指定することに注意してください; つまり、"Foo/Bar.pm" ではなく "Foo::Bar" です。 flags は PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT, PERL_LOADMOD_IMPORT_OPS の いずれか(あるいはフラグなしなら 0)です。 ver が指定されると、use Foo::Bar VERSION と同様のバージョン意味論を 提供します。 オプションで引き続く SV* 引数は、use Foo::Bar VERSION LIST と同様に、 モジュールの import() メソッドへの引数を指定するために使われます。 これらは最後の NULL ポインタで終端されていなければなりません。 このリストは PERL_LOADMOD_NOIMPORT フラグが使われている場合にのみ 省略できます。 さもなければ少なくともデフォルトインポートリストを指定するための単一の NULL ポインタが必要です。
void load_module(U32 flags, SV* name, SV* ver, ...)スレッドがないときの perl_destruct のためのスレッドフックを提供する スタブです。
int nothreadhook()新たなPerl インタプリタを割り付けます。 perlembed を参照してください。
PerlInterpreter* perl_alloc()新しいPerl インタプリタの初期化を行います。 perlembed を参照してください。
void perl_construct(PerlInterpreter *my_perl)Perl インタプリタをシャットダウンします。 perlembed を参照してください。
int perl_destruct(PerlInterpreter *my_perl)Perl インタプリタを解放します。 perlembed を参照してください。
void perl_free(PerlInterpreter *my_perl)Perl インタプリタに Perl スクリプトを解析するよう指示します。 perlembed を参照してください。
int perl_parse(PerlInterpreter *my_perl, XSINIT_t xsinit, int argc, char** argv, char** env)Perl インタプリタに実行するよう指示します。 perlembed を参照してください。
int perl_run(PerlInterpreter *my_perl)文字列引数の名前のファイルを require するように Perl に伝えます。 Perl コード eval "require '$file'" に類似しています。 実際このように実装されています; 代わりに load_module を使うことを 考慮してください。
注意: この関数の perl_ の形は廃止予定です。
void require_pv(const char* pv)以下と似ています:
pv_escape(dsv,pv,cur,pvlim,PERL_PV_ESCAPE_QUOTE);は、len > cur で pv[cur] が "\0" なら、文字列に追加の "\0" が 追加されることを想定します。
最終的な文字列は pvlim より最大 7 文字長くなる可能性があることに 注意してください。
char* pv_display(SV *dsv, const char *pv, STRLEN cur, STRLEN len, STRLEN pvlim)多くても pv の最初の "count" 文字をエスケープして、エスケープされた文字列の サイズは "max" は "max" 文字を超えず、不完全なエスケープシーケンスが 含まれないような結果を dsv に入れます。
flags に PERL_PV_ESCAPE_QUOTE が含まれているなら、文字列中のダブルクォートも エスケープされます。
通常は SV はエスケープされた文字列が準備される前にクリアされますが、 PERL_PV_ESCAPE_NOCLEAR がセットされているとこれは起こりません。
PERL_PV_ESCAPE_UNI がセットされているなら入力文字列は Unicode として 扱われます。 PERL_PV_ESCAPE_UNI_DETECT がセットされているなら入力文字列は Unicode かどうか 決定するために is_utf8_string() を使ってスキャンされます。
PERL_PV_ESCAPE_ALL がセットされていると、全ての入力文字は \x01F1 形式の エスケープを使って出力され、さもなければ 255 を超える文字のみがこの形式で エスケープされ、その他の表示できない文字は 8 進数か \n のような一般的な エスケープパターンを使います。 PERL_PV_ESCAPE_NOBACKSLASH なら、255 以下の全ての文字は表示可能として 扱われてリテラルとして出力されます。
PERL_PV_ESCAPE_FIRSTCHAR がセットされると、max に関わらず文字列の最初の 文字だけがエスケープされます。 文字列が utf8 で文字の値が >255 なら、普通の 16 進シーケンスとして 返されます。 従って出力は単一の文字、8 進エスケープシーケンス、\n のような 特殊エスケープ、3 桁以上の 16 進数のいずれかです。
PERL_PV_ESCAPE_RE が設定されると、使われるエスケープ文字は '\\' ではなく '%' になります。 これは正規表現がとてもしばしばバックスラッシュ並びを含んでいて、一方 '%' は パターン中で特に一般的な文字というわけではないからです。
dsv によって保持されている、エスケープされたテキストへのポインタを返します。
char* pv_escape(SV *dsv, char const * const str, const STRLEN count, const STRLEN max, STRLEN * const escaped, const U32 flags)文字列を何か表現可能なものに変換します; pv_escape() によるエスケープを扱い、 クォートと省略に対応しています。
PERL_PV_PRETTY_QUOTE フラグがセットされると、文字列中のダブルクォートが エスケープされて、全体がダブルクォートで囲まれます。 さもなければ、PERL_PV_PRETTY_LTGT がセットされていれば結果は山かっこで 囲まれます。
PERL_PV_PRETTY_ELLIPSES がセットされて、文字列中の全ての文字が 出力されないときは、省略記号 ... が文字列に追加されます。 これはクォートされた「後」に起きることに注意してください。
start_color が非 NULL なら、(もしあれば) 開きクォートの後、エスケープされた テキストの前に挿入されます。 end_color が非 NULL なら、エスケープされたテキストの後、クォートや 省略記号の前に挿入されます。
dsv によって保持されている、飾り付けられたテキストへのポインタを返します。
char* pv_pretty(SV *dsv, char const * const str, const STRLEN count, const STRLEN max, char const * const start_color, char const * const end_color, const U32 flags)gv_fetchmethod_autoload を参照してください。
GV* gv_fetchmethod(HV* stash, const char* name)Perl 関数 pack() を実装しているエンジンです。 注意: 引数 next_in_list と flags は使われません。 この呼び出しは使うべきではなりません; 代わりに packlist を使ってください。
void pack_cat(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags)SV のバイトエンコードされた表現へのポインタを返します。 副作用として、SV が UTF-8 から降格するかもしれません。
通常は SvPVbyte_nolen マクロ経由でアクセスします。
char* sv_2pvbyte_nolen(SV* sv)SV の UTF-8 エンコードされた表現へのポインタを返します。 副作用として、SV が UTF-8 へ昇格するかもしれません。
通常は SvPVutf8_nolen マクロ経由でアクセスします。
char* sv_2pvutf8_nolen(SV* sv)sv_2pv() と同様ですが、長さも返しません。 普通は代わりにマクロラッパー SvPV_nolen(sv) を使うべきです。
char* sv_2pv_nolen(SV* sv)sv_catpvn に似ていますが、'set' magic もハンドルします。
void sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len)sv_catsv に似ていますが、'set' magic もハンドルします。
void sv_catsv_mg(SV *dsv, SV *ssv)SV への様々な種類のごまかしを巻き戻します; PV が共有文字列なら、 プライベートなコピーを作ります; リファレンスなら、リファレンスを止めます; グロブなら、xpvmg に降格します。 sv_force_normal_flags も参照してください。
void sv_force_normal(SV *sv)複雑なマクロ式を扱えないコンパイラのための、SvIVx マクロの プライベート実装です。 代わりに、常にマクロを使ってください。
IV sv_iv(SV* sv)ロックモジュールがないときに SV を「ロックする」ダミールーチンです。 NULL 関数をテストして、あるレベルでの strict での潜在的な警告を 回避するために存在します。
sv_nosharing() で「置き換え」られました。
void sv_nolocking(SV *sv)ロックモジュールがないときに SV を「アンロックする」ダミールーチンです。 NULL 関数をテストして、あるレベルでの strict での潜在的な警告を 回避するために存在します。
sv_nosharing() で「置き換え」られました。
void sv_nounlocking(SV *sv)複雑なマクロ式を扱えないコンパイラのための、SvNVx マクロの プライベート実装です。 代わりに、常にマクロを使ってください。
NV sv_nv(SV* sv)代わりに SvPV_nolen マクロを使ってください。
char* sv_pv(SV *sv)代わりに SvPVbyte_nolen マクロを使ってください。
char* sv_pvbyte(SV *sv)複雑なマクロ式を扱えないコンパイラのための、SvPVbyte マクロの プライベート実装です。 代わりに、常にマクロを使ってください。
char* sv_pvbyten(SV *sv, STRLEN *lp)複雑なマクロ式を扱えないコンパイラのための、SvPV マクロの プライベート実装です。 代わりに、常にマクロを使ってください。
char* sv_pvn(SV *sv, STRLEN *lp)代わりに SvPVutf8_nolen マクロを使ってください。
char* sv_pvutf8(SV *sv)複雑なマクロ式を扱えないコンパイラのための、SvPVutf8 マクロの プライベート実装です。 代わりに、常にマクロを使ってください。
char* sv_pvutf8n(SV *sv, STRLEN *lp)SV を汚染します。 代わりに SvTAINTED_on を使ってください。
void sv_taint(SV* sv)SV の RV ステータスをアンセットし、RV によって参照されているものの 参照カウントを減じます。 これは newSVrv の反転したものであると考えられます。 これは、flag がゼロのときの sv_unref_flags です。 SvROK_off を参照してください。
void sv_unref(SV* sv)自身の文字列値を得るのに ptr を使うように SV に指示します。 flags を 0 にして sv_usepvn_flags を呼び出すことで実装されているので、 'set' magic をハンドルしません。 sv_usepvn_mg を参照してください。
void sv_usepvn(SV* sv, char* ptr, STRLEN len)sv_usepvn に似ていますが、'set' magic をハンドルします。
void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)複雑なマクロ式を扱えないコンパイラのための、SvUVx マクロの プライベート実装です。 代わりに、常にマクロを使ってください。
UV sv_uv(SV* sv)Perl 関数 unpack() を実装しているエンジンです。 注意: 引数 strbeg, new_s, ocnt は使われません。 この呼び出しは使うべきではなりません; 代わりに unpackstring を 使ってください。
I32 unpack_str(const char *pat, const char *patend, const char *s, const char *strbeg, const char *strend, char **new_s, I32 ocnt, U32 flags)Perl インタプリタを実行するのに必要な C ランタイム環境のシステム固有の 調整を提供します。 これは一度だけ、Perl インタプリタが作成される前に呼び出されるべきです。
void PERL_SYS_INIT(int argc, char** argv)Perl インタプリタを実行するのに必要な C ランタイム環境のシステム固有の 調整を提供します。 これは一度だけ、Perl インタプリタが作成される前に呼び出されるべきです。
void PERL_SYS_INIT3(int argc, char** argv, char** env)Perl インタプリタを実行するのに必要な C ランタイム環境のシステム固有の 調整を提供します。 これは一度だけ、Perl インタプリタが作成される前に呼び出されるべきです。
void PERL_SYS_TERM()現在実行しているサブルーチンや eval に対応する CV の場所を調べます。 db_seqp が非 null なら、DB パッケージの CV は飛ばして、 *db_seqp を、DB:: コードが入った時点での cop シーケンス番号にします。 (デバッガが、デバッガ自身のスコープではなく、ブレークポイントのスコープで eval できるようにします)。
CV* find_runcv(U32 *db_seqp)Perl 関数 pack() を実装しているエンジンです。
void packlist(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist)Perl 関数 unpack() を実装しているエンジンです。 unpackstring は展開されたリスト要素をスタックに設定して、要素数を 返します。 この関数を呼ぶ前には PUTBACK を、呼んだ後には SPAGAIN を 使ってください。
I32 unpackstring(const char *pat, const char *patend, const char *s, const char *strend, U32 flags)Sets PL_defoutgv, the default file handle for output, to the passed in typeglob. As PL_defoutgv "owns" a reference on its typeglob, the reference count of the passed in typeglob is increased by one, and the reference count of the typeglob that PL_defoutgv points to is decreased by one. (TBT)
void setdefout(GV* gv)Function pointer, pointing at a function used to handle extended keywords. 関数は以下のように宣言されている必要があります (TBT)
int keyword_plugin_function(pTHX_
char *keyword_ptr, STRLEN keyword_len,
OP **op_ptr)The function is called from the tokeniser, whenever a possible keyword is seen. keyword_ptr points at the word in the parser's input buffer, and keyword_len gives its length; it is not null-terminated. The function is expected to examine the word, and possibly other state such as %^H, to decide whether it wants to handle it as an extended keyword. If it does not, the function should return KEYWORD_PLUGIN_DECLINE, and the normal parser process will continue. (TBT)
If the function wants to handle the keyword, it first must parse anything following the keyword that is part of the syntax introduced by the keyword. See "Lexer interface" for details. (TBT)
When a keyword is being handled, the plugin function must build a tree of OP structures, representing the code that was parsed. The root of the tree must be stored in *op_ptr. The function then returns a contant indicating the syntactic role of the construct that it has parsed: KEYWORD_PLUGIN_STMT if it is a complete statement, or KEYWORD_PLUGIN_EXPR if it is an expression. Note that a statement construct cannot be used inside an expression (except via do BLOCK and similar), and an expression is not a complete statement (it requires at least a terminating semicolon). (TBT)
When a keyword is handled, the plugin function may also have (compile-time) side effects. It may modify %^H, define functions, and so on. Typically, if side effects are the main purpose of a handler, it does not wish to generate any ops to be included in the normal compilation. In this case it is still required to supply an op tree, but it suffices to generate a single null op. (TBT)
That's how the *PL_keyword_plugin function needs to behave overall. Conventionally, however, one does not completely replace the existing handler function. Instead, take a copy of PL_keyword_plugin before assigning your own function pointer to it. Your handler function should look for keywords that it is interested in and handle those. Where it is not interested, it should call the saved plugin function, passing on the arguments it received. Thus PL_keyword_plugin actually points at a chain of handler functions, all of which have an opportunity to handle keywords, and only the last function in the chain (built into the Perl core) will normally return KEYWORD_PLUGIN_DECLINE. (TBT)
注意: この関数は実験的で、予告なしに変更あるいは削除されるかもしれません。
GV から SV を返します。
SV* GvSV(GV* gv)gv がサブルーチンエントリがインライン化可能な定数サブルーチンである 型グロブであるか、gv がそのような型グロブに昇格するリファレンスの プレースホルダの場合、そのサブルーチンから返される値を返します。 さもなければ NULL を返します。
SV* gv_const_sv(GV* gv)与えられた name と、定義されたサブルーチンか NULL を使ったグロブを 返します。 このグロブは、与えられた stash か、@ISA や UNIVERSAL:: を通じて アクセスできるスタッシュにあります。
引数 level は 0 か -1 であるべきです。 level==0 の場合、副作用として(サブルーチンに対するエイリアスを 含むことに成功した場合に)与えられた stash にある name に対する glob を生成し、さらにこの glob に対するキャッシュ情報のセットアップを 行います。
この関数はスタッシュ名のポストフィックスとして、トークン "SUPER" を 受け付けます。 gv_fetchmeth から返された GV は、Perl プログラムからは参照することの できないような、メソッドキャッシュのエントリである可能性があります。 このため、perl_call_sv を呼び出したとき、GV を直接 使うべきではありません; その代わりに、GV に対して GvCV マクロを使って 得ることのできる、メソッドの CV を使うべきです。
GV* gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level)stash にあるメソッドを起動するために呼び出すサブルーチンを含むグロブを 返します。 事実、オートローディングの直前でこれは "AUTOLOAD" に対するグロブとなる 可能性があります。 その場合、$AUTOLOAD に対応する変数が既にセットアップされています。
gv_fetchmethod_autoload の第三引数は、与えられたメソッドが 存在していなかった場合に AUTLOAD のルックアップをするかしないかを決定します; ゼロでないときは AUTOLOAD の検索を行い、ゼロのときには行いません。 gv_fetchmethod の呼び出しは gv_fetchmethod_autoload に ゼロでない autoload パラメーターを渡したときと等価です。
これらの関数は、トークン "SUPER" をメソッド名の接頭辞として許します。 返された glob を長い間保存しておきたいのなら、"AUTOLOAD" の存在を チェックする必要があるということに注意してください。 これは、後での呼び出しが $AUTOALOD の値が変化したことによって、異なる サブルーチンをロードしてしまうかもしれないからです。
これらの関数は、gv_fetchmeth に level==0 を渡したときと同じ副作用を 持っています。 name は、その内容に ':' か '\'' が含まれている場合には書き込み 可能であるべきです。 gv_fetchmeth から返された GV を call_sv に渡したことに対する警告は、 これらの関数についても同じく適用されます。
GV* gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload)gv_fetchmeth() と同じですが、オートロードされたサブルーチンも探します。 サブルーチンのグロブを返します。
GV なしのオートロードされたサブルーチンのために、level < 0 でも GV を 作成します。 スタブのないオートロードされたサブルーチンのために、結果の GvCV() は ゼロかもしれません。
GV* gv_fetchmeth_autoload(HV* stash, const char* name, STRLEN len, I32 level)指定されたパッケージに対するスタッシュへのポインタを返します。 name の長さを決定するために strlen を使い、それから gv_stashpvn() を呼び出します。
HV* gv_stashpv(const char* name, I32 flags)指定されたパッケージに対するスタッシュへのポインタを返します。 namelen 引数は name の長さをバイトで示します。 flags は gv_fetchpvn_flags() に渡されるので、GV_ADD を設定すると パッケージが既に存在していない場合は作成されます。 パッケージが存在しておらず、 flags が 0 (またはパッケージを作成しない その他の値)の場合は NULL が返されます。
HV* gv_stashpvn(const char* name, U32 namelen, I32 flags)gv_stashpvn と同様ですが、文字列/長さの組ではなく、リテラルな文字列を 取ります。
HV* gv_stashpvs(const char* name, I32 create)指定されたパッケージに対するスタッシュへのポインタを返します。 gv_stashpvn を参照してください。
HV* gv_stashsv(SV* sv, I32 flags)AVのヌルポインタ。
(廃止予定 - 代わりに (AV *)NULL を使ってください)
ヌル文字ポインタ。 (PERL_CORE が定義されているときはもはや利用できません。)
CVのヌルポインタ。
(廃止予定 - 代わりに (CV *)NULL を使ってください)
HVのヌルポインタ。
(廃止予定 - 代わりに (HV *)NULL を使ってください)
ヌル SV ポインタ。 (PERL_CORE が定義されているときはもはや利用できません。)
指定された Perl ハッシュの HV を返します。 flags は gv_fetchpv に渡されます。 GV_ADD がセットされていて、指定された変数が存在していなければ、新たに 生成されます。 flags がゼロで、かつ、指定された変数がなかった場合には NULL が返されます。
注意: この関数の perl_ の形は廃止予定です。
HV* get_hv(const char *name, I32 flags)このフラグは、ハッシュエントリの length slot や magic structures で使われ、 char* ポインタであることを期待されている SV* ポインタを含む構造体を 指定します。 (情報のみ -- 使われません)。
ハッシュエントリに格納されている計算済みハッシュを返します。
U32 HeHASH(HE* he)ハッシュエントリのキー スロットにあるポインタを返します。 このポインタは char* か SV* のいずれかで、これは HeKLEN() の 値に依存します。 これは代入することができます。 HePV() や HeSVKEY() といったマクロはキーの値を検索するために、 通常望ましいものです。
void* HeKEY(HE* he)これが負であり、かつ HEf_SVKEY に等しければ、エントリが SV* キーを 保持していることを示します。 そうでなければ、これはキーの実際の長さを保持しています。 これは代入することができます。 マクロ HePV() はキーの長さを検出するのに、通常望ましいものです。
STRLEN HeKLEN(HE* he)char * としてのハッシュエントリのキースロットを返し、SV* キーで 必要となるような参照外しなどを行います。 文字列の長さは len に置かれます(これはマクロなので、&len を 使ってはいけません)。 キーの長さがどうなのかを気にしないのであれば、グローバル変数 PL_na を 使うことができますが、これはローカル変数を使うよりも非効率的です。 しかし忘れないで欲しいのは、そういった perl におけるハッシュのキーは 埋め込まれているヌル文字に対して自由であり、そのため strlen() などを使って ハッシュキーの長さを調べるのは良い方法ではないということです。 これは他の場所で説明している SvPV() マクロについても同様です。 HeUTF8 も参照してください。
新しい SV を作るために newSVpvn() に渡すための値を得るのに HePV を 使っている場合、より効率的な newSVhek(HeKEY_hek(he)) を使うことを 考慮するべきです。
char* HePV(HE* he, STRLEN len)SV* としてのキー、もしくはハッシュエントリに SV* キーがない場合には NULL を返します。
SV* HeSVKEY(HE* he)SV* としてのキーを返します。 ハッシュエントリに char* キーしかない場合には、一時的な揮発性 SV* が 生成されて返されます。
SV* HeSVKEY_force(HE* he)与えられた SV* にキーをセットし、SV* キーの存在を表わす適切な フラグを注意深くセットし、同じ SV* を返します。
SV* HeSVKEY_set(HE* he, SV* sv)Returns whether the char * value returned by HePV is encoded in UTF-8, doing any necessary dereferencing of possibly SV* keys. 返される値は 0 または非 0 で、1 である必要(あるいは最下位ビットが設定されている 必要すら)はないので、これを盲目的に bool 変数に代入 しないでください; bool は char への typedef かもしれないからです。
char* HeUTF8(HE* he)ハッシュエントリに格納されている(型 SV* の)値スロットを返します。
SV* HeVAL(HE* he)スタッシュのパッケージ名を返します; stash がスタッシュでない場合は NULL を返します。 SvSTASH, CvSTASH を参照してください。
char* HvNAME(HV* stash)ハッシュが内部的に一貫した状態であるかを調べます。
void hv_assert(HV *hv)ハッシュをクリアし、空にします。
void hv_clear(HV *hv)ハッシュからのプレースホルダをクリアします。 制限ハッシュに読み込み専用とマークされたキーがあって、その後キーが 削除されると、キーは実際には削除されず、&PL_sv_placeholder の値を 代入することでマークされます。 これはハッシュの反復のようなその後の操作では無視されるようになりますが、 将来の時点でキーに再代入されることで値を持てるようになっています。 この関数はこのようなハッシュからのプレースホルダキーをクリアします。 この使用例は Hash::Util::lock_keys() を参照してください。
void hv_clear_placeholders(HV *hv)ハッシュにあるキー/値のペアを削除します。 値 SV はハッシュから取り除かれて、呼び出し元に返されます。 klen はキーの長さです。 flags の値は通常はゼロとなります; これに G_DISCARD をセットした場合には NULL が返されます。
SV* hv_delete(HV *hv, const char *key, I32 klen, I32 flags)ハッシュにあるキー/値のペアを削除します。 値 SV はハッシュから取り除かれて、呼び出し元に返されます。 flags の値は通常はゼロとなります; これに G_DISCARD をセットした場合には NULL が返されます。 hash はあらかじめ計算されたハッシュ値を置きますが、計算結果を 問い合わせるには 0 とします。
SV* hv_delete_ent(HV *hv, SV *keysv, I32 flags, U32 hash)指定されたハッシュキーが存在するかどうかを表わす真偽値を返します。 klen はキーの長さです。
bool hv_exists(HV *hv, const char *key, I32 klen)指定されたハッシュキーが存在するかどうかを表わす真偽値を返します。 hash はあらかじめ計算されたハッシュ値を置きますが、計算結果を 問い合わせるには 0 とします。
bool hv_exists_ent(HV *hv, SV *keysv, U32 hash)指定されたキーに対応する、ハッシュ中の SV を返します。 klen はキーの長さです。 lval がセットされている場合、フェッチはストアの一部となります。 戻り値 SV* の参照外しをする前に、それがヌルでないことを チェックしてください。
この関数をどのように tie されたハッシュに使うかに関するさらなる情報は "Understanding the Magic of Tied Hashes and Arrays" in perlguts を 参照してください。
SV** hv_fetch(HV *hv, const char *key, I32 klen, I32 lval)hv_fetch と同様ですが、文字列/長さの組ではなく、リテラルな文字列を 取ります。
SV** hv_fetchs(HV* tb, const char* key, I32 lval)指定されたキーに対応する、ハッシュ中のハッシュエントリを返します。 hash は、key に対する正当な計算済みハッシュ値でなければなりません; もしくは、この関数にハッシュ値を計算させたいのであればここに 0 を置きます。 lval がセットされていると、フェッチはストアの一部分となります。 tb が tie されているハッシュの場合の戻り値は静的な位置 (static location)へのポインタです。 したがって、何かを格納する必要があるのなら、その構造体のコピーを 取るようにしてください。
この関数をどのように tie されたハッシュに使うかに関するさらなる情報は "Understanding the Magic of Tied Hashes and Arrays" in perlguts を 参照してください。
HE* hv_fetch_ent(HV *hv, SV *keysv, I32 lval, U32 hash)ハッシュテーブルをたどるための開始点を準備します。 ハッシュの中に存在しているキーの数を返します(HvKEYS(tb) と同じです)。 この戻り値は現状では tie magic なしのハッシュに対してのみ意味があります。
注意: 5.004_65 より前のバージョンでは、hv_iterinit は使用中の ハッシュバケツの数を返すのに使われていました。 もしあなたがそのような値を必要としているのなら、HvFILL(tb) という マクロを使って得ることができます。
I32 hv_iterinit(HV *hv)ハッシュイテレーターの現在位置からキーを返します。 hv_iterinit を参照してください。
char* hv_iterkey(HE* entry, I32* retlen)ハッシュイテレーターの現在位置から、SV* としてキーを返します。 この戻り値は常にキーの揮発性コピーとなります。 hv_iterinit を参照してください。
SV* hv_iterkeysv(HE* entry)ハッシュ反復子からエントリを返します。 hv_iterinit を参照してください。
反復子が位置を失ったり無効になったりすることなく、反復子が現在指している ハッシュエントリに対して hv_delete または hv_delete_ent を 呼び出すことができます。 この場合現在のエントリは、これへの最後の参照を保持している反復子の ハッシュから削除されることに注意してください。 反復子は次の hv_iternext の呼び出しでエントリが解放されるようにマークが 付けられるので、すぐに反復子を捨ててはいけません; さもなければエントリは リークします; リソースの割り当て解除を引き起こすには hv_iternext を 呼び出してください。
HE* hv_iternext(HV *hv)一つの操作で hv_iternext、hv_iterkey、hv_iterval を 呼び出します。
SV* hv_iternextsv(HV *hv, char **key, I32 *retlen)ハッシュ反復子からエントリを返します。 hv_iterinit と hv_iternext を参照してください。 flags の値は普通はゼロです; HV_ITERNEXT_WANTPLACEHOLDERS が セットされていると、(制限ハッシュのための) プレースホルダキーは通常のキーに 追加して返されます。 デフォルトではプレースホルダは自動的に飛ばされます。 現在のところプレースホルダは &Perl_sv_placeholder の値として 実装されています。 プレースホルダと制限ハッシュの実装は変更されるかも知れず、現在の実装は 整理するための変更には抽象化が不十分であることに注意してください。
注意: この関数は実験的で、予告なしに変更あるいは削除されるかもしれません。
HE* hv_iternext_flags(HV *hv, I32 flags)ハッシュ反復子の現在位置から値を返します。 hv_iterkey を参照してください。
SV* hv_iterval(HV *hv, HE *entry)ハッシュに magic を付加します。 sv_magic を参照してください。
void hv_magic(HV *hv, GV *gv, int how)ハッシュをスカラコンテキストで評価して、結果を返します。 ハッシュが tie された場合は magic を扱います。
SV* hv_scalar(HV *hv)ハッシュに SV を格納します。 そのハッシュキーは key で指定され、klen はキーの長さです。 hash パラメーターはあらかじめ計算したハッシュ値です; 0 にすると Perl がこれを計算します。 戻り値は、操作が失敗したり(tie されているハッシュのように)ハッシュに 実際に値を格納する必要のない場合には NULL になります。 さもなければ、取得したオリジナルの SV* の参照外しをすることができます。 呼び出し側は、呼び出しの前に val の参照カウントを適切にインクリメントし、 関数が NULL を返した場合には参照カウントをデクリメントする責任が あるということに注意してください。 事実上成功した hv_store は val へのリファレンスを取得します。 これは通常あなたの求めているものです; 新しく作られた SV は参照カウント 1 を 持つので、あなたのコードがすることが SV を作成してハッシュを 保管することだけなら、hv_store は新しい SV へのリファレンスだけを所有し、 あなたのコードは整理のためにさらなる何かをする必要はありません。 hv_store は hv_store_ent の呼び出しとして実装されておらず、キーのための 一時的な SV を作成しないので、キーデータがすでに SV 形式に なっているのでなければ、hv_store_ent よりも hv_store を使ってください。
この関数をどのように tie されたハッシュに使うかに関するさらなる情報は "Understanding the Magic of Tied Hashes and Arrays" in perlguts を 参照してください。
SV** hv_store(HV *hv, const char *key, I32 klen, SV *val, U32 hash)hv_store と同様ですが、文字列/長さの組ではなく、リテラルな文字列を 取り、ハッシュパラメータを除外します。
SV** hv_stores(HV* tb, const char* key, NULLOK SV* val)val をハッシュに格納します。 ハッシュキーは key で指定します。 hash パラメーターはあらかじめ計算したハッシュ値です; 0 にすると Perl がこれを計算します。 戻り値は生成された新しいハッシュエントリです。 操作が失敗したり、(tie されているハッシュのように)ハッシュに実際に値を 格納する必要のない場合には NULL になります。 そうでない場合には、戻り値の内容に He? マクロを使ってアクセスすることが 可能です。 呼び出し側は、呼び出しの前に val の参照カウントを適切にインクリメントし、 関数が NULL を返した場合には参照カウントをデクリメントする責任が あるということに注意してください。 事実上成功した hv_store_ent は val へのリファレンスを取得します。 これは通常あなたの求めているものです; 新しく作られた SV は参照カウント 1 を 持つので、あなたのコードがすることが SV を作成してハッシュを 保管することだけなら、hv_store は新しい SV へのリファレンスだけを所有し、 あなたのコードは整理のためにさらなる何かをする必要はありません。 hv_store_ent は key だけを読み込むことに注意してください; val と違って 所有権を取らないので、key の参照カウントを正しく保守するのは全て 呼び出し側に責任があります。 hv_store は hv_store_ent の呼び出しとして実装されておらず、キーのための 一時的な SV を作成しないので、キーデータがすでに SV 形式に なっているのでなければ、hv_store_ent よりも hv_store を使ってください。
この関数をどのように tie されたハッシュに使うかに関するさらなる情報は "Understanding the Magic of Tied Hashes and Arrays" in perlguts を 参照してください。
HE* hv_store_ent(HV *hv, SV *key, SV *val, U32 hash)ハッシュを undefine します。
void hv_undef(HV *hv)新たな HV を生成します。 参照カウントは 1 に設定されます。
HV* newHV()Indicates whether the octets in the lexer buffer ("PL_parser->linestr") should be interpreted as the UTF-8 encoding of Unicode characters. If not, they should be interpreted as Latin-1 characters. This is analogous to the SvUTF8 flag for scalars. (TBT)
In UTF-8 mode, it is not guaranteed that the lexer buffer actually contains valid UTF-8. Lexing code must be robust in the face of invalid encoding. (TBT)
The actual SvUTF8 flag of the "PL_parser->linestr" scalar is significant, but not the whole story regarding the input character encoding. Normally, when a file is being read, the scalar contains octets and its SvUTF8 flag is off, but the octets should be interpreted as UTF-8 if the use utf8 pragma is in effect. During a string eval, however, the scalar may have the SvUTF8 flag on, and in this case its octets should be interpreted as UTF-8 unless the use bytes pragma is in effect. This logic may change in the future; use this function instead of implementing the logic yourself. (TBT)
注意: この関数は実験的で、予告なしに変更あるいは削除されるかもしれません。
bool lex_bufutf8()Discards the first part of the "PL_parser->linestr" buffer, up to ptr. The remaining content of the buffer will be moved, and all pointers into the buffer updated appropriately. ptr must not be later in the buffer than the position of "PL_parser->bufptr": it is not permitted to discard text that has yet to be lexed. (TBT)
Normally it is not necessarily to do this directly, because it suffices to use the implicit discarding behaviour of "lex_next_chunk" and things based on it. However, if a token stretches across multiple lines, and the lexing code has kept multiple lines of text in the buffer fof that purpose, then after completion of the token it would be wise to explicitly discard the now-unneeded earlier lines, to avoid future multi-line tokens growing the buffer without bound. (TBT)
注意: この関数は実験的で、予告なしに変更あるいは削除されるかもしれません。
void lex_discard_to(char *ptr)Reallocates the lexer buffer ("PL_parser->linestr") to accommodate at least len octets (including terminating NUL). Returns a pointer to the reallocated buffer. This is necessary before making any direct modification of the buffer that would increase its length. "lex_stuff_pvn" provides a more convenient way to insert text into the buffer. (TBT)
Do not use SvGROW or sv_grow directly on PL_parser->linestr; this function updates all of the lexer's variables that point directly into the buffer. (TBT)
注意: この関数は実験的で、予告なしに変更あるいは削除されるかもしれません。
char * lex_grow_linestr(STRLEN len)Reads in the next chunk of text to be lexed, appending it to "PL_parser->linestr". This should be called when lexing code has looked to the end of the current chunk and wants to know more. It is usual, but not necessary, for lexing to have consumed the entirety of the current chunk at this time. (TBT)
If "PL_parser->bufptr" is pointing to the very end of the current chunk (i.e., the current chunk has been entirely consumed), normally the current chunk will be discarded at the same time that the new chunk is read in. If flags includes LEX_KEEP_PREVIOUS, the current chunk will not be discarded. If the current chunk has not been entirely consumed, then it will not be discarded regardless of the flag. (TBT)
Returns true if some new text was added to the buffer, or false if the buffer has reached the end of the input text. (TBT)
注意: この関数は実験的で、予告なしに変更あるいは削除されるかもしれません。
bool lex_next_chunk(U32 flags)Looks ahead one (Unicode) character in the text currently being lexed. Returns the codepoint (unsigned integer value) of the next character, or -1 if lexing has reached the end of the input text. To consume the peeked character, use "lex_read_unichar". (TBT)
If the next character is in (or extends into) the next chunk of input text, the next chunk will be read in. Normally the current chunk will be discarded at the same time, but if flags includes LEX_KEEP_PREVIOUS then the current chunk will not be discarded. (TBT)
If the input is being interpreted as UTF-8 and a UTF-8 encoding error is encountered, an exception is generated. (TBT)
注意: この関数は実験的で、予告なしに変更あるいは削除されるかもしれません。
I32 lex_peek_unichar(U32 flags)Reads optional spaces, in Perl style, in the text currently being lexed. The spaces may include ordinary whitespace characters and Perl-style comments. #line directives are processed if encountered. "PL_parser->bufptr" is moved past the spaces, so that it points at a non-space character (or the end of the input text). (TBT)
If spaces extend into the next chunk of input text, the next chunk will be read in. Normally the current chunk will be discarded at the same time, but if flags includes LEX_KEEP_PREVIOUS then the current chunk will not be discarded. (TBT)
注意: この関数は実験的で、予告なしに変更あるいは削除されるかもしれません。
void lex_read_space(U32 flags)Consume text in the lexer buffer, from "PL_parser->bufptr" up to ptr. This advances "PL_parser->bufptr" to match ptr, performing the correct bookkeeping whenever a newline character is passed. This is the normal way to consume lexed text. (TBT)
Interpretation of the buffer's octets can be abstracted out by using the slightly higher-level functions "lex_peek_unichar" and "lex_read_unichar". (TBT)
注意: この関数は実験的で、予告なしに変更あるいは削除されるかもしれません。
void lex_read_to(char *ptr)Reads the next (Unicode) character in the text currently being lexed. Returns the codepoint (unsigned integer value) of the character read, and moves "PL_parser->bufptr" past the character, or returns -1 if lexing has reached the end of the input text. To non-destructively examine the next character, use "lex_peek_unichar" instead. (TBT)
If the next character is in (or extends into) the next chunk of input text, the next chunk will be read in. Normally the current chunk will be discarded at the same time, but if flags includes LEX_KEEP_PREVIOUS then the current chunk will not be discarded. (TBT)
If the input is being interpreted as UTF-8 and a UTF-8 encoding error is encountered, an exception is generated. (TBT)
注意: この関数は実験的で、予告なしに変更あるいは削除されるかもしれません。
I32 lex_read_unichar(U32 flags)Insert characters into the lexer buffer ("PL_parser->linestr"), immediately after the current lexing point ("PL_parser->bufptr"), reallocating the buffer if necessary. This means that lexing code that runs later will see the characters as if they had appeared in the input. It is not recommended to do this as part of normal parsing, and most uses of this facility run the risk of the inserted characters being interpreted in an unintended manner. (TBT)
The string to be inserted is represented by len octets starting at pv. These octets are interpreted as either UTF-8 or Latin-1, according to whether the LEX_STUFF_UTF8 flag is set in flags. The characters are recoded for the lexer buffer, according to how the buffer is currently being interpreted ("lex_bufutf8"). If a string to be interpreted is available as a Perl scalar, the "lex_stuff_sv" function is more convenient. (TBT)
注意: この関数は実験的で、予告なしに変更あるいは削除されるかもしれません。
void lex_stuff_pvn(char *pv, STRLEN len, U32 flags)Insert characters into the lexer buffer ("PL_parser->linestr"), immediately after the current lexing point ("PL_parser->bufptr"), reallocating the buffer if necessary. This means that lexing code that runs later will see the characters as if they had appeared in the input. It is not recommended to do this as part of normal parsing, and most uses of this facility run the risk of the inserted characters being interpreted in an unintended manner. (TBT)
The string to be inserted is the string value of sv. The characters are recoded for the lexer buffer, according to how the buffer is currently being interpreted ("lex_bufutf8"). If a string to be interpreted is not already a Perl scalar, the "lex_stuff_pvn" function avoids the need to construct a scalar. (TBT)
注意: この関数は実験的で、予告なしに変更あるいは削除されるかもしれません。
void lex_stuff_sv(SV *sv, U32 flags)Discards text about to be lexed, from "PL_parser->bufptr" up to ptr. Text following ptr will be moved, and the buffer shortened. This hides the discarded text from any lexing code that runs later, as if the text had never appeared. (TBT)
これは構文解析されたテキストを消費する通常の方法ではありません。 そのためには、"lex_read_to" を使ってください。
注意: この関数は実験的で、予告なしに変更あるいは削除されるかもしれません。
void lex_unstuff(char *ptr)Pointer to a structure encapsulating the state of the parsing operation currently in progress. The pointer can be locally changed to perform a nested parse without interfering with the state of an outer parse. Individual members of PL_parser have their own documentation. (TBT)
Direct pointer to the end of the chunk of text currently being lexed, the end of the lexer buffer. This is equal to SvPVX(PL_parser->linestr) + SvCUR(PL_parser->linestr). A NUL character (zero octet) is always located at the end of the buffer, and does not count as part of the buffer's contents. (TBT)
注意: この関数は実験的で、予告なしに変更あるいは削除されるかもしれません。
Points to the current position of lexing inside the lexer buffer. Characters around this point may be freely examined, within the range delimited by SvPVX("PL_parser->linestr") and "PL_parser->bufend". The octets of the buffer may be intended to be interpreted as either UTF-8 or Latin-1, as indicated by "lex_bufutf8". (TBT)
Lexing code (whether in the Perl core or not) moves this pointer past the characters that it consumes. It is also expected to perform some bookkeeping whenever a newline character is consumed. This movement can be more conveniently performed by the function "lex_read_to", which handles newlines appropriately. (TBT)
Interpretation of the buffer's octets can be abstracted out by using the slightly higher-level functions "lex_peek_unichar" and "lex_read_unichar". (TBT)
注意: この関数は実験的で、予告なしに変更あるいは削除されるかもしれません。
Points to the start of the current line inside the lexer buffer. This is useful for indicating at which column an error occurred, and not much else. This must be updated by any lexing code that consumes a newline; the function "lex_read_to" handles this detail. (TBT)
注意: この関数は実験的で、予告なしに変更あるいは削除されるかもしれません。
Buffer scalar containing the chunk currently under consideration of the text currently being lexed. This is always a plain string scalar (for which SvPOK is true). It is not intended to be used as a scalar by normal scalar means; instead refer to the buffer directly by the pointer variables described below. (TBT)
The lexer maintains various char* pointers to things in the PL_parser->linestr buffer. If PL_parser->linestr is ever reallocated, all of these pointers must be updated. Don't attempt to do this manually, but rather use "lex_grow_linestr" if you need to reallocate the buffer. (TBT)
The content of the text chunk in the buffer is commonly exactly one complete line of input, up to and including a newline terminator, but there are situations where it is otherwise. The octets of the buffer may be intended to be interpreted as either UTF-8 or Latin-1. The function "lex_bufutf8" tells you which. Do not use the SvUTF8 flag on this scalar, which may disagree with it. (TBT)
For direct examination of the buffer, the variable "PL_parser->bufend" points to the end of the buffer. The current lexing position is pointed to by "PL_parser->bufptr". Direct use of these pointers is usually preferable to examination of the scalar through normal scalar means. (TBT)
注意: この関数は実験的で、予告なしに変更あるいは削除されるかもしれません。
SV が表わしている magical をクリアします。 sv_magic を参照してください。
int mg_clear(SV* sv)ある SV から別の SV へ magic をコピーします。 sv_magic を参照してください。
int mg_copy(SV *sv, SV *nsv, const char *key, I32 klen)type にマッチする SV への magic ポインタを検索します。 sv_magic を参照してください。
MAGIC* mg_find(const SV* sv, int type)SV が使用しているすべての magic storage を解放します。 sv_magic を参照してください。
int mg_free(SV* sv)SV から値を取得した後で magic を行います。 sv_magic を参照してください。
int mg_get(SV* sv)SV の長さを報告します。 sv_magic を参照してください。
U32 mg_length(SV* sv)SV の magical status をオンにします。 sv_magic を参照してください。
void mg_magical(SV* sv)SV に値を代入した後で magic を行います。 sv_magic を参照してください。
int mg_set(SV* sv)SV が 'get' magic を有している場合には mg_get を起動します。 このマクロは二回以上引数を評価します。
void SvGETMAGIC(SV* sv)適切なモジュールが読み込まれていれば、sv を得るための相互排他ロックを 準備します。
void SvLOCK(SV* sv)SV が 'set' magic を持っている場合に、その SV に対して mg_set を 起動します。 このマクロは二回以上引数を評価します。
void SvSETMAGIC(SV* sv)SvSetSV と同様ですが、後で set magic が必要です。
void SvSetMagicSV(SV* dsb, SV* ssv)SvSetSV_nosteal と同様ですが、後で set magic が必要です。
void SvSetMagicSV_nosteal(SV* dsv, SV* ssv)dsv が ssv と等しくなかったときに sv_setsv を呼び出します。 引数は二回以上評価される可能性があります。
void SvSetSV(SV* dsb, SV* ssv)dsv と ssv が等しくなかったときに呼び出される、非破壊的バージョンの sv_setsv を呼び出します。 引数は二回以上評価される可能性があります。
void SvSetSV_nosteal(SV* dsv, SV* ssv)適切なモジュールが読み込まれていれば、sv をスレッド間で共有するための 準備をします。
void SvSHARE(SV* sv)適切なモジュールが読み込まれていれば、sv の相互排他ロックを解放します。
void SvUNLOCK(SV* sv)C の memcpy 関数に対する XSUB 作成者のためのインターフェースです。 src は転送元、dest は転送先、nitems はアイテムの数、type は アイテムの型です。 領域がオーバーラップしているコピーの場合は失敗します。 Move を参照してください。
void Copy(void* src, void* dest, int nitems, type)Copy と同様ですが、dest を返します。 末尾呼び出し最適化を行うコンパイラで便利です。
void * CopyD(void* src, void* dest, int nitems, type)C の memmove 関数に対する XSUB 作成者のためのインターフェースです。 src は転送元、dest は転送先、nitems はアイテムの数、type は アイテムの型です。 オーバーラップした移動も可能です。 Copy を参照してください。
void Move(void* src, void* dest, int nitems, type)Move と同様ですが、dest を返します。 末尾呼び出し最適化を行うコンパイラで便利です。
void * MoveD(void* src, void* dest, int nitems, type)XSUB 作成者のための malloc 関数のインターフェースです。
5.9.3 から、Newx() とその同類は古い New() API を置き換え、呼び出し側が 自分自身を識別できるようにデバッグの助けをするための最初の引数 x が なくなりました。 この助けは新しいビルドオプション PERL_MEM_LOG ("PERL_MEM_LOG" in perlhack 参照) で置き換えられました。 古い API は、古い perl に対応している XS モジュールが使えるように まだ存在しています。
void Newx(void* ptr, int nitems, type)C の malloc 関数に対する XSUB 作成者のためのキャスト付き インターフェースです。 Newx も参照してください。
void Newxc(void* ptr, int nitems, type, cast)XSUB 作成者のための malloc 関数のインターフェースです。 割り付けられた領域は memzero によってゼロで埋められます。 Newx も参照してください。
void Newxz(void* ptr, int nitems, type)解放されたメモリへのアクセスを捕捉するための PoisonWith(0xEF) です。
void Poison(void* dest, int nitems, type)解放されたメモリへのアクセスを捕捉するための PoisonWith(0xEF) です。
void PoisonFree(void* dest, int nitems, type)割り当てられたけれども未初期化のメモリへのアクセスを捕捉するための PoisonWith(0xAB)。
void PoisonNew(void* dest, int nitems, type)うまくいけば未初期化メモリへのアクセスを捕捉するためにメモリを (あるバイトが繰り返される)バイトパターンで埋めます。
void PoisonWith(void* dest, int nitems, type, U8 byte)C の realloc 関数に対する XSUB 作成者のためのインターフェースです。
void Renew(void* ptr, int nitems, type)キャスト付きの、C の realloc 関数に対する XSUB 作成者のための インターフェースです。
void Renewc(void* ptr, int nitems, type, cast)C の free 関数に対する XSUB 作成者のためのインターフェースです。
void Safefree(void* ptr)Perl 版の strdup()。 pv の複製である、新しく割り当てられた文字列へのポインタを返します。 文字列のサイズは strlen() によって決定されます。 新しい文字列のために割り当てられたメモリは Safefree() 関数で解放できます。
char* savepv(const char* pv)もしあれば strndup() が行うことの Perl 版。 pv から len バイトの複製に加えて末尾の NUL バイトからなる、新しく 割り当てられた文字列へのポインタを返します。 新しい文字列のために割り当てられたメモリは Safefree() 関数で解放できます。
char* savepvn(const char* pv, I32 len)savepvn と同様ですが、文字列/長さの組ではなく、リテラルな文字列を 取ります。
char* savepvs(const char* s)スレッド間で共有しているメモリで複製された文字列を割り当てるバージョンの savepv()。
char* savesharedpv(const char* pv)スレッド間で共有したメモリに複製した文字列を割り当てるバージョンの savepvn() です。 (NULL ポインタを受け付けないという違いもあります)
char* savesharedpvn(const char *const pv, const STRLEN len)SvPV() を使った SV で渡されたものから複製した文字列を取得するバージョンの savepv()/savepvn() です。
char* savesvpv(SV* sv)これはある構造体をもう一つにコピーするためのアーキテクチャに依存しない マクロです。
void StructCopy(type src, type dest, type)C の memzero 関数に対する XSUB 作成者のためのインターフェースです。 dest は対象となる場所、nitems はアイテムの数、type は アイテムの型です。
void Zero(void* dest, int nitems, type)Zero と同様ですが、dest を返します。 末尾呼び出し最適化を行うコンパイラで便利です。
void * ZeroD(void* dest, int nitems, type)Boyer-Moore アルゴリズムを使った fbm_instr() による高速検索が できるようにするために文字列を解析します。
void fbm_compile(SV* sv, U32 flags)str と strend によって区切られる文字列中にある SV の位置を返します。 文字列が見つからなかった場合には NULL を返します。 sv は fbm_compile されている必要はありませんが、その場合にはある場合に 比べると検索速度は遅くなります。
char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlestr, U32 flags)sprintf 形式のフォーマットパターンと形式的な (非 SV) 引数を取って、 フォーマットされた文字列を返します。
(char *) Perl_form(pTHX_ const char* pat, ...)は文字列 (char *) が必要なあらゆる場所で使えます:
char * s = Perl_form("%d.%d",major,minor);単一のプライベートなバッファを使うので、いくつかの文字列を フォーマットしたいなら、以前の文字列を明示的にコピーしなければなりません (そして使い終わったらコピーを解放しなければなりません)。
char* form(const char* pat, ...)sv をカレントワーキングディレクトリで埋めます
int getcwd_sv(SV* sv)利用可能で標準に準拠していれば、C ライブラリの snprintf の機能です (実際には vsnprintf を使います)。 しかし、vsnprintf が利用不可能なら、残念ながらバッファをオーバーランする 可能性のある安全でない vsprintf を使います (オーバーランチェックは ありますが、遅すぎるかもしれません)。 代わりに sv_vcatpvf を使うか、vsnprintf を使うことを考慮してください。
int my_snprintf(char *buffer, const Size_t len, const char *format, ...)バッファに書き込んだ文字列の長さが確実に返されるように、もし必要なら ラップされた、C ライブラリの sprintf です。 稀な ANSI 以前のシステムのみがラッパー関数を必要とします - 通常はこれは直接 sprintf を呼び出します。
int my_sprintf(char *buffer, const char *pat, ...)利用可能で標準に準拠していれば、C ライブラリの snprintf です。 しかし、vsnprintf が利用不可能なら、残念ながらバッファをオーバーランする 可能性のある安全でない vsprintf を使います (オーバーランチェックは ありますが、遅すぎるかもしれません)。 代わりに sv_vcatpvf を使うか、vsnprintf を使うことを考慮してください。
int my_vsnprintf(char *buffer, const Size_t len, const char *format, va_list ap)SV で渡されたものを基として新しいバージョンオブジェクトを返します:
SV *sv = new_version(SV *ver);渡された ver SV は変更されません。 SV を昇格したいなら "upg_version" を参照してください。
SV* new_version(SV *ver) const char* prescan_version(const char *s, bool strict, const char** errstr, bool *sqv, int *ssaw_decimal, int *swidth, bool *salpha)バージョン文字列をパースした後の次の文字へのポインタを返します; また、SV に 渡されたものを RV に昇格させます。
関数は以下のように、既に存在する SV と共に呼び出されなければなりません
sv = newSV(0);
s = scan_version(s, SV *sv, bool qv);バージョンとして正しい特性を持つように文字列に前処理を行います。 下線が含まれている(これがαバージョンであることを示します)なら、 オブジェクトにマークを付けます。 真偽値 qv は、たとえそうではなくても、バージョンに複数の小数点が 含まれているかのように解釈するべきであることを示します。
const char* scan_version(const char *s, SV *rv, bool qv)二つの文字列が等しいかどうかを検査します。 真か偽を返します。
bool strEQ(char* s1, char* s2)二つの文字列を、s1 が s2 よりも大きい、もしくは両者が等しいかどうかの 検査をします。 真か偽を返します。
bool strGE(char* s1, char* s2)二つの文字列を、s1 が s2 よりも大きいかどうかの検査をします。 真か偽を返します。
bool strGT(char* s1, char* s2)二つの文字列を、s1 が s2 よりも小さい、もしくは両者が等しいか どうかの検査をします。 真か偽を返します。
bool strLE(char* s1, char* s2)二つの文字列を、s1 が s2 よりも小さいかどうかの検査をします。 真か偽を返します。
bool strLT(char* s1, char* s2)二つの文字列が異なるかどうかを検査します。 真か偽を返します。
bool strNE(char* s1, char* s2)二つの文字列が等しいかどうかを検査します。 パラメーター len は、比較を行うバイト数を指定します。 真か偽を返します。 (strncmp へのラッパーです)
bool strnEQ(char* s1, char* s2, STRLEN len)二つの文字列が異なるかどうかを検査します。 パラメーター len は、比較を行うバイト数を指定します。 真か偽を返します。 (strncmp へのラッパーです)
bool strnNE(char* s1, char* s2, STRLEN len)共有モジュールがないときにオブジェクトを破壊可能であると報告するダミー ルーチンです。 これは SV 引数を無視して、真を返します。 NULL 関数をテストして、あるレベルでの strict での潜在的な警告を 回避するために存在します。
bool sv_destroyable(SV *sv)共有モジュールがないときに SV を「共有する」ダミールーチンです。 あるいは「ロックします」。 あるいは「アンロックします」。 言い換えると、単一の SV 引数を無視します。 NULL 関数をテストして、あるレベルでの strict での潜在的な警告を 回避するために存在します。
void sv_nosharing(SV *sv)SV をバージョンオブジェクトにその場で昇格します。
SV *sv = upg_version(SV *sv, bool qv);昇格された SV へのポインタを返します。 この SV が「拡張」版として解釈されることを強制したいなら、真偽値 qv を セットします。
SV* upg_version(SV *ver, bool qv)バージョンオブジェクトを認識する cmp。 両方のオペランドは既にバージョンオブジェクトに 変換されていなければなりません。
int vcmp(SV *lhv, SV *rhv)バージョンオブジェクトを受け付けて正規化された文字列表現を返します。 以下のように呼び出します:
sv = vnormal(rv);注意: オブジェクトを直接と、RV に含まれている SV のどちらでも渡せます。
SV* vnormal(SV *vs)バージョンオブジェクトを受け付けて正規化された浮動小数点表現を返します。 以下のように呼び出します:
sv = vnumify(rv);注意: オブジェクトを直接と、RV に含まれている SV のどちらでも渡せます。
SV* vnumify(SV *vs)以前のバージョンの Perl との最大限の互換性を維持するために、この関数は 元のバージョンにドットが一つだけか複数あるかに依存して、浮動小数点表記か 複数ドット表記のどちらかを返します。
SV* vstringify(SV *vs)SV が正当なバージョンオブジェクトを含んでいるかを検証します。
bool vverify(SV *vobj);これは生の最小限の構造体だけを確認することに注意してください (従って 追加のハッシュエントリを含んでいるかもしれない派生クラスによって 混乱しません):
bool vverify(SV *vs)このスタッシュに対して MRO が有効かどうかに依存して、スタッシュに対する mro_get_linear_isa_c3 か mro_get_linear_isa_dfs のどちらかを 返します。 返り値は読み込み専用の AV* です。
半永久的にどこかにこれを保管する計画がある場合、返り値に対する SvREFCNT_inc() に対して責任があります。 (さもなければ、次回キャッシュが無効化されるときに削除されるかもしれません)。
AV* mro_get_linear_isa(HV* stash)スタッシュの全ての子クラスのメソッドキャッシュを無効にして、これによる 変更が通知されます。
理想的には、mro.c の外側の perl ソースの PL_sub_generation++ の全ての 実体はこれへの呼び出しで置き換えられるべきです。
Perl はメソッドが再定義されるかもしれない一般的な方法のほとんどを自動的に 扱います。 しかしキャッシュコードが気付くことなくスタッシュのメソッドを変更する いくつかの方法があります; この場合後でこのメソッドを呼び出す必要があります:
1) XS コードからスタッシュ HV エントリを直接操作する。
2) 読み込み専用スカラ定数へのリファレンスを、(constant.pm がしているように) 定数サブルーチンを作成するためにスタッシュエントリに代入する。
同じメソッドはピュア perl から mro::method_changed_in(classname) 経由で 利用可能です。
void mro_method_changed_in(HV* stash)多重呼び出しのための局所変数を宣言します。 "Lightweight Callbacks" in perlcall を参照してください。
dMULTICALL;軽量コールバックを作ります。 "Lightweight Callbacks" in perlcall を参照してください。
MULTICALL;軽量コールバックのための大かっこを閉じます。 "Lightweight Callbacks" in perlcall を参照してください。
POP_MULTICALL;軽量コールバックのための大かっこを開きます。 "Lightweight Callbacks" in perlcall を参照してください。
PUSH_MULTICALL;2 進数を表現した文字列を数値形式に変換します。
エントリ start と *len はスキャンする文字列を指定し、*flags は 変換フラグ、result は NULL か NV へのポインタです。 スキャンは文字列の末尾か、最初の不正な文字で停止します。 *flags に PERL_SCAN_SILENT_ILLDIGIT がセットされていなければ、不正な 文字に遭遇すると警告も引き起こされます。 返るときに、*len はスキャンした文字列の長さにセットされ、 *flags は出力フラグになります。
値が <= UV_MAX なら、出力フラグがクリアされ、*result に何も書かない UV として返されます。 値が > UV_MAX なら、grok_bin は出力フラグに PERL_SCAN_GREATER_THAN_UV_MAX をセットし、値を *result に書き込んで、 UV_MAX を返します (あるいは result が NULL なら値は捨てられます)。
エントリの *flags に PERL_SCAN_DISALLOW_PREFIX が セットされていなければ、2 進数にオプションとして "0b" または "b" を 前置できます。 *flags で PERL_SCAN_ALLOW_UNDERSCORES がセットされていると、2 進数で 数値を区切るのに '_' 文字が使えます。
UV grok_bin(const char* start, STRLEN* len_p, I32* flags, NV *result)16 進数を表現した文字列を数値形式に変換します。
エントリ start と *len はスキャンする文字列を指定し、*flags は 変換フラグ、result は NULL か NV へのポインタです。 スキャンは文字列の末尾か、最初の不正な文字で停止します。 *flags に PERL_SCAN_SILENT_ILLDIGIT がセットされていなければ、不正な 文字に遭遇すると警告も引き起こされます。 返るときに、*len はスキャンした文字列の長さにセットされ、 *flags は出力フラグになります。
値が <= UV_MAX なら、出力フラグがクリアされ、*result に何も書かない UV として返されます。 値が > UV_MAX なら、grok_hex は出力フラグに PERL_SCAN_GREATER_THAN_UV_MAX をセットし、値を *result に書き込んで、 UV_MAX を返します (あるいは result が NULL なら値は捨てられます)。
エントリの *flags に PERL_SCAN_DISALLOW_PREFIX が セットされていなければ、16 進数にオプションとして "0x" または "x" を 前置できます。 *flags で PERL_SCAN_ALLOW_UNDERSCORES がセットされていると、2 進数で 数値を区切るのに '_' 文字が使えます。
UV grok_hex(const char* start, STRLEN* len_p, I32* flags, NV *result)数値を認識します(またはしません)。 数値の型(認識されなかった場合は 0)が返され、さもなければ (perl.h に定義されている) IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT, IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN を ビット単位で OR したものです。
数値の値が UV に収まるなら、*valuep に返され、*valuep が有効であることを 示すために IS_NUMBER_IN_UV がセットされます; *valuep が有効でなければ IS_NUMBER_IN_UV がセットされることはありませんが、返る時点で IS_NUMBER_IN_UV がセットされていないとしても、処理中に *valuep に値が 代入されるかもしれません。 valuep が NULL なら、valuep が非 NULL の場合と同様に IS_NUMBER_IN_UV が セットされますが、実際の代入(または SEGV)は起こりません。
引き続く数字がある(この場合 *valuep には整数に切り詰められた真の値が入ります) の場合、IS_NUMBER_NOT_INT が IS_NUMBER_IN_UV と共にセットされ、値が負数 (この場合 *value には絶対値が入ります)の場合、IS_NUMBER_NEG が セットされます。 e 記法が使われたり数値が UV よりも大きいなら、IS_NUMBER_IN_UV は セットされません。
int grok_number(const char *pv, STRLEN len, UV *valuep)小数点をスキャンして、読み飛ばします。
bool grok_numeric_radix(const char **sp, const char *send)8 進数を表現した文字列を数値形式に変換します。
エントリ start と *len はスキャンする文字列を指定し、*flags は 変換フラグ、result は NULL か NV へのポインタです。 スキャンは文字列の末尾か、最初の不正な文字で停止します。 *flags に PERL_SCAN_SILENT_ILLDIGIT がセットされていなければ、不正な 文字に遭遇すると警告も引き起こされます。 返るときに、*len はスキャンした文字列の長さにセットされ、 *flags は出力フラグになります。
値が <= UV_MAX なら、出力フラグがクリアされ、*result に何も書かない UV として返されます。 値が > UV_MAX なら、grok_oct は出力フラグに PERL_SCAN_GREATER_THAN_UV_MAX をセットし、値を *result に書き込んで、 UV_MAX を返します (あるいは result が NULL なら値は捨てられます)。
*flags で PERL_SCAN_ALLOW_UNDERSCORES が設定されると、8 進数は 数値を区切るのに '_' 文字を使えます。
UV grok_oct(const char* start, STRLEN* len_p, I32* flags, NV *result)もし NV の符号ビットがセットされていれば非 0 の整数を、そうでなければ 0 を返します。
Configure は、このシステムの NV に動作する signbit() が持っていることを 検出します。 それから単にこれを perl.h の #define 経由で使います。 さもなければ、この実装にフォールバックします。 第 1 パスとして、これは -0.0 以外の全てを取ります。 悲しいかな、-0.0 の捕捉はこの関数の主な使用法なので、これはまだあまり 役には立ちません。 それでも、少なくとも便利であるとわかる他のシステムに対応する足場になります。
Configure の注意: この関数は、単なる 'signbit' ではなく 'Perl_signbit' と 呼ばれます; なぜなら たまたま NV の特定の選択で動作しない signbit() 関数やマクロを持つシステムを 想像するのは容易だからです。 単に signbit を Perl_signbit と再 #define して、標準システムヘッダがうまく 動くことを想定するべきではありません。 また、これは(pTHX_ なしの)コンテキストなし関数はありません; なぜなら Perl_signbit() は通常 perl.h でシステムの signbit() への単純なマクロ 呼び出しに再 #defined されるからです。 ユーザーは単に常に Perl_signbit() を呼び出してください。
注意: この関数は実験的で、予告なしに変更あるいは削除されるかもしれません。
int Perl_signbit(NV f)後方互換性のためのものです。 代わりに grok_bin を使ってください。
NV scan_bin(const char* start, STRLEN len, STRLEN* retlen)後方互換性のためのものです。 代わりに grok_hex を使ってください。
NV scan_hex(const char* start, STRLEN len, STRLEN* retlen)後方互換性のためのものです。 代わりに grok_oct を使ってください。
NV scan_oct(const char* start, STRLEN len, STRLEN* retlen)cv がインライン化可能な定数サブルーチンなら、サブルーチンから返される 定数値を返します。 さもなければ NULL を返します。
定数サブルーチンは newCONSTSUB か、"Constant Functions" in perlsub で 記述されている方法で作成されます。
SV* cv_const_sv(const CV *const cv)Perl での sub FOO () { 123 } と等価な定数サブルーチンを生成します。
Passing NULL for SV creates a constant sub equivalent to sub BAR () {}, which won't be called if used as a destructor, but will suppress the overhead of a call to AUTOLOAD. (This form, however, isn't eligible for inlining at compile time.) (TBT)
CV* newCONSTSUB(HV* stash, const char* name, SV* sv)Perl サブルーチンのように XSUB をフックするために xsubpp が使います。 filename は静的なストレージである必要があります; なぜならこれはコピーされることなく直接 CvFILE() で使われるからです。
Given a lexical name, try to find its offset, first in the current pad, or failing that, in the pads of any lexically enclosing subs (including the complications introduced by eval). If the name is found in an outer pad, then a fake entry is added to the current pad. Returns the offset in the current pad, or NOT_IN_PAD on failure. (TBT)
注意: この関数は実験的で、予告なしに変更あるいは削除されるかもしれません。
PADOFFSET pad_findmy(const char* name, STRLEN len, U32 flags)現在のパッドのオフセット po の値を返します。 この関数を直接呼び出さずにマクロ PAD_SV を使ってください。
SV* pad_sv(PADOFFSET po)PL_modglobal は、汎用の、インタプリタグローバルの HV で、 インタプリタ毎の情報を保持するような エクステンションによって使われるものです。 場合によっては、データの共有をおこなうために エクステンションのシンボルテーブルとして使うことも可能です。 エクステンションのパッケージ名を、エクステンション固有のデータの名前の 接頭辞として使うのは良い考えです。
HV* PL_modglobal文字列の長さについて考慮しないような場合の SvPV と共に使われるような 変数です。 通常はローカル変数を宣言してそれを使うか、 SvPV_nolen マクロを使った方が効率が良いです。
STRLEN PL_naWhen non-NULL, the function pointed by this variable will be called each time an OP is freed with the corresponding OP as the argument. This allows extensions to free any extra attribute they have locally attached to an OP. It is also assured to first fire for the parent OP and then for its kids. (TBT)
この変数を置き換えるときは、 it is considered a good practice to store the possibly previously installed hook and that you recall it inside your own. (TBT)
Perl_ophook_t PL_opfreehookこれは false の SV です。 PL_sv_yes を参照してください。 常に &PL_sv_no として参照してください。
SV PL_sv_noこれは undef SV です。 常に &PL_sv_undef として参照してください。
SV PL_sv_undefこれは true SV です。 PL_sv_no を参照してくさい。 これは常に &PL_sv_yes として参照してください。
SV PL_sv_yesSV から REGEXP を得るための便利なマクロです。 これはほぼ以下のコード片と等価です:
if (SvMAGICAL(sv))
mg_get(sv);
if (SvROK(sv) &&
(tmpsv = (SV*)SvRV(sv)) &&
SvTYPE(tmpsv) == SVt_PVMG &&
(tmpmg = mg_find(tmpsv, PERL_MAGIC_qr)))
{
return (REGEXP *)tmpmg->mg_obj;
}もし REGEXP* が見つからなければ NULL を返します。
REGEXP * SvRX(SV *sv)SV が qr magic (PERL_MAGIC_qr) を含んでいるかどうかを示す真偽値を返します。
後で REGEXP* で何かをしたいなら、代わりに SvRX を使って、NULL を チェックしてください。
bool SvRXOK(SV* sv)例外処理のために必要なローカル変数を設定します。 "Exception Handling" in perlguts を参照してください。
dXCPT;catch ブロックを導入します。 "Exception Handling" in perlguts を参照してください。
以前に捕捉した例外を再 throw します。 "Exception Handling" in perlguts を参照してください。
XCPT_RETHROW;try ブロックを終了します。 "Exception Handling" in perlguts を参照してください。
try ブロックを開始します。 "Exception Handling" in perlguts を参照してください。
スタックマーカー変数 mark を XSUB のために宣言します。 MARK と dORIGMARK を参照してください。
dMARK;XSUB のためのオリジナルのスタックマークを保存します。 ORIGMARK を参照してください。
dORIGMARK;マクロ SP を使ってアクセス可能な XSUB のためのスタックポインタのローカルな コピーを宣言します。 SP を参照してください。
dSP;XSUB の戻り値のために引数スタックを拡張するのに使われます。 一度使うと、少なくとも nitems をスタックにプッシュするだけの空きが 出来ます。
void EXTEND(SP, int nitems)XSUB に対するスタックマーカーの変数です。 dMARK を参照してください。
整数をスタックにプッシュします。 スタックにはこの要素を収めるだけの空きがなければなりません。 TARG を使いません。 PUSHi, mXPUSHi, XPUSHi も参照してください。
void mPUSHi(IV iv)倍精度実数をスタックにプッシュします。 スタックにはこの要素を収めるだけの空きがなければなりません。 'set' magic をハンドルします。 TARG を使いません。 PUSHn, mXPUSHn, XPUSHn も参照してください。
void mPUSHn(NV nv)文字列をスタックにプッシュします。 スタックにはこの要素を収めるだけの空きがなければなりません。 len は文字列の長さを示します。 TARG を使いません。 PUSHp, mXPUSHp, XPUSHp も参照してください。
void mPUSHp(char* str, STRLEN len)SV をスタックにプッシュして SV を揮発化します。 スタックはこの要素を納めるだけの空きがなければなりません。 TARG を使いません。 PUSHs と mXPUSHs も参照してください。
void mPUSHs(SV* sv)符号なし整数をスタックにプッシュします。 スタックにはこの要素を収めるだけの空きがなければなりません。 TARG を使いません。 PUSHu, mXPUSHu, XPUSHu も参照してください。
void mPUSHu(UV uv)整数をスタックにプッシュし、必要があればスタックを拡張します。 TARG を使いません。 XPUSHi, mPUSHi, PUSHi も参照してください。
void mXPUSHi(IV iv)倍精度数値をスタックにプッシュし、必要があればスタックを拡張します。 TARG を使いません。 XPUSHn, mPUSHn, PUSHn も参照してください。
void mXPUSHn(NV nv)文字列をスタックにプッシュし、必要があればスタックを拡張します。 len は文字列の長さを示します。 TARG を使いません。 XPUSHp, mPUSHp, PUSHp も参照してください。
void mXPUSHp(char* str, STRLEN len)必要があればスタックを拡張し、SV をスタックにプッシュして、SV を 揮発化します。 TARG を使いません。 XPUSHs と mPUSHs も参照してください。
void mXPUSHs(SV* sv)符号なし整数をスタックにプッシュし、必要があればスタックを拡張します。 'set' magic をハンドルします。 TARG を使いません。 XPUSHu, mPUSHu, PUSHu も参照してください。
void mXPUSHu(UV uv)XSUB のためのオリジナルスタックマークです。 dORIGMARK を参照してください。
スタックから整数をポップします。
IV POPiスタックから long をポップします。
long POPlスタックから倍精度実数をポップします。
NV POPnスタックから文字列をポップします。 廃止予定です。 新しいコードは POPpx を使うべきです。
char* POPpバイト列で構成されていなければならない(つまり文字 < 256 な)文字列を スタックからポップします。
char* POPpbytexスタックから文字列をポップします。
char* POPpxスタックから SV をポップします。
SV* POPs整数をスタックにプッシュします。 スタックにはこの要素を収めるだけの空きがなければなりません。 'set' magic をハンドルします。 TARG を使うので、これを宣言するために dTARGET または dXSTARG が 呼び出されるべきです。 XSUB からリストを返すために複数回 TARG 指向のマクロを 呼び出さないでください - 代わりに mPUSHi を参照してください。 XPUSHi と mXPUSHi も参照してください。
void PUSHi(IV iv)コールバックにある引数のためのブラケットを開きます。 PUTBACK と perlcall を参照してください。
void PUSHMARK(SP)新しい揮発性の SV をスタックにプッシュします。 スタックにはこの要素を収めるだけの空きがなければなりません。 TARG を使いません。 PUSHs, XPUSHmortal, XPUSHs も参照してください。
void PUSHmortal()倍精度実数をスタックにプッシュします。 スタックにはこの要素を収めるだけの空きがなければなりません。 'set' magic をハンドルします。 TARG を使うので、これを宣言するために dTARGET または dXSTARG が 呼び出されるべきです。 XSUB からリストを返すために複数回 TARG 指向のマクロを 呼び出さないでください - 代わりに mPUSHn を参照してください。 XPUSHn と mXPUSHn も参照してください。
void PUSHn(NV nv)文字列をスタックにプッシュします。 スタックにはこの要素を収めるだけの空きがなければなりません。 len は文字列の長さを示します。 'set' magic をハンドルします。 TARG を使うので、これを宣言するために dTARGET または dXSTARG が 呼び出されるべきです。 XSUB からリストを返すために複数回 TARG 指向のマクロを 呼び出さないでください - 代わりに mPUSHp を参照してください。 XPUSHp と mXPUSHp も参照してください。
void PUSHp(char* str, STRLEN len)SV をスタックへプッシュします。 スタックにはこの要素を収めるだけの空きがなければなりません。 'set' magic をハンドルしません。 TARG を使いません。 PUSHmortal, XPUSHs, XPUSHmortal も参照してください。
void PUSHs(SV* sv)符号なし整数をスタックにプッシュします。 スタックにはこの要素を収めるだけの空きがなければなりません。 'set' magic をハンドルします。 TARG を使うので、これを宣言するために dTARGET または dXSTARG が 呼び出されるべきです。 XSUB からリストを返すために複数回 TARG 指向のマクロを 呼び出さないでください - 代わりに mPUSHu を参照してください。 XPUSHu と mXPUSHu も参照してください。
void PUSHu(UV uv)XSUB 引数のためのブラケットを閉じます。 これは通常、xsubpp によって扱われます。 他の使い方については PUSHMARKと perlcall を参照してください。
PUTBACK;スタックポインタです。 これは通常、xsubpp によって扱われます。 dSP と SPAGAIN を参照してください。
スタックポインタの再フェッチします。 コールバックの後で使われます。 perlcall を参照してください。
SPAGAIN;整数をスタックにプッシュし、必要があればスタックを拡張します。 'set' magic をハンドルします。 TARG を使うので、これを宣言するために dTARGET または dXSTARG が 呼び出されるべきです。 XSUB からリストを返すために複数回 TARG 指向のマクロを 呼び出さないでください - 代わりに mXPUSHi を参照してください。 PUSHi と mPUSHi も参照してください。
void XPUSHi(IV iv)必要ならスタックを拡張して、新しく揮発性の SV をスタックにプッシュします。 TARG を使いません。 XPUSHs, PUSHmortal, PUSHs も参照してください。
void XPUSHmortal()倍精度数値をスタックにプッシュし、必要があればスタックを拡張します。 'set' magic をハンドルします。 TARG を使うので、これを宣言するために dTARGET または dXSTARG が 呼び出されるべきです。 XSUB からリストを返すために複数回 TARG 指向のマクロを 呼び出さないでください - 代わりに mXPUSHn を参照してください。 PUSHn と mPUSHn も参照してください。
void XPUSHn(NV nv)文字列をスタックにプッシュし、必要があればスタックを拡張します。 len は文字列の長さを示します。 'set' magic をハンドルします。 TARG を使うので、これを宣言するために dTARGET または dXSTARG が 呼び出されるべきです。 XSUB からリストを返すために複数回 TARG 指向のマクロを 呼び出さないでください - 代わりに mXPUSHp を参照してください。 PUSHp と mPUSHp も参照してください。
void XPUSHp(char* str, STRLEN len)SV をスタックにプッシュし、必要があればスタックを拡張します。 'set' magic をハンドルしません。 TARG を使いません。 XPUSHmortal, PUSHs, PUSHmortal も参照してください。
void XPUSHs(SV* sv)符号なし整数をスタックにプッシュし、必要があればスタックを拡張します。 'set' magic をハンドルします。 TARG を使うので、これを宣言するために dTARGET または dXSTARG が 呼び出されるべきです。 XSUB からリストを返すために複数回 TARG 指向のマクロを 呼び出さないでください - 代わりに mXPUSHu を参照してください。 PUSHu と mPUSHu も参照してください。
void XPUSHu(UV uv)XSUB から戻され、スタックにあるアイテムの数を示します。 これは通常、xsubpp によって扱われます。
void XSRETURN(int nitems)XSUB から即座に空リストを返します。
XSRETURN_EMPTY;XSUB から即座に整数を返します。 XST_mIV を使います。
void XSRETURN_IV(IV iv)XSUB から即座に &PL_sv_no を返します。 XST_mNO を使います。
XSRETURN_NO;XSUB から即座に倍精度数値を返します。 XST_mNV を使います。
void XSRETURN_NV(NV nv)XSUB から即座に文字列のコピーを返します。 XST_mPV を使います。
void XSRETURN_PV(char* str)XSUB から即座に &PL_sv_undef を返します。 XST_mUNDEF を使います。
XSRETURN_UNDEF;XSUB から即座に整数を返します。 XST_mUV を使います。
void XSRETURN_UV(IV uv)XSUB から即座に &PL_sv_yes を返します。 XST_mYES を使います。
XSRETURN_YES;整数値をスタックの pos で指定される場所に置きます。 その値は新しい揮発性 SV (mortal SV) に格納されます。
void XST_mIV(int pos, IV iv)&PL_sv_no をスタックの pos で指定される場所に置きます。
void XST_mNO(int pos)倍精度数値をスタックの pos で指定される場所に置きます。 その値は新しい揮発性 SV (mortal SV) に格納されます。
void XST_mNV(int pos, NV nv)文字列のコピーをスタックの pos で指定される場所に置きます。 その値は新しい揮発性 SV (mortal SV) に格納されます。
void XST_mPV(int pos, char* str)&PL_sv_undef をスタックの pos で指定される場所に置きます。
void XST_mUNDEF(int pos)&PL_sv_yes をスタックの pos で指定される場所に置きます。
void XST_mYES(int pos)Perl の型のためのフラグの列挙です。 sv.h というファイル中の svtype という列挙にあります。 これらのフラグは、SvTYPE というマクロを使って検査を行います。
スカラに対する整数型。 svtype を参照してください。
スカラに対する倍精度の型フラグ。 svtype を参照してください。
スカラに対するポインタ型。 svtype を参照してください。
配列に対する型フラグ。 svtype を参照してください。
コードリファレンスのための型フラグ。 svtype を参照してください。
ハッシュに対する型フラグ。 svtype を参照してください。
blessされたスカラに対する型フラグ。 svtype を参照してください。
xsubs のための使用法メッセージを出力するために専門化された croak()
croak_xs_usage(cv, "eee_yow");cv からパッケージ名とサブルーチン名を取り出して、croak() を 呼び出します。 従って cv が &ouch::awk なら、croak を以下のようにして呼び出します:
Perl_croak(aTHX_ "Usage %s::%s(%s)", "ouch" "awk", "eee_yow");
void croak_xs_usage(const CV *const cv, const char *const params)指定された Perl スカラの SV を返します。 flags は gv_fetchpv に渡されます。 GV_ADD がセットされていて、指定された変数が存在していなければ、新たに 生成されます。 flags がゼロで、かつ、指定された変数がなかった場合には NULL が返されます。
注意: この関数の perl_ の形は廃止予定です。
SV* get_sv(const char *name, I32 flags)SV に対する RV ラッパーを生成します。 元の SV の参照カウントはインクリメントされます。
SV* newRV_inc(SV* sv)新しい SV を作成して文字列をこれにコピーします。 utf8 が真なら、新しい SV に対して SvUTF8_on を呼び出します。 newSVpvn_flags へのラッパとして実装されています。
SV* newSVpvn_utf8(NULLOK const char* s, STRLEN len, U32 utf8)SV にある文字列の長さを返します。 SvLEN を参照してください。
STRLEN SvCUR(SV* sv)SV にある文字列の現在の長さを設定します。 SvCUR を参照してください。
void SvCUR_set(SV* sv, STRLEN len)SV にある文字列の終端のキャラクタへのポインタを返します。 SvCUR を参照してください。 文字へは *(SvEND(sv)) としてアクセスします。
char* SvEND(SV* sv)SV が get magic かオーバーロードであれば真を返します。 どちらかが真なら、スカラはアクティブなデータで、アクセスされる度に新しい値を 返す可能性があります。 従って、ユーザーの論理的な操作につき一回だけ読み込んで、返された値に対して 作業をするように注意しなければなりません。 どちらも真でなければ、書き込まれるまでスカラの値は変更できません。
U32 SvGAMAGIC(SV* sv)指定されたバイト数だけの空間があるように SV にある文字バッファを拡張します (予約分の空間は NUL 文字で埋められることを思い出してください)。 必要であれば、拡張のために sv_grow を呼び出します。 文字バッファへのポインタを返します。
char * SvGROW(SV* sv, STRLEN len)SV が整数を含んでいるかどうかを表わす U32 値を返します。
U32 SvIOK(SV* sv)SV が整数を含んでいるかどうかを表わす U32 値を返します。 private な設定を検査します。 代わりに SvIOK を使ってください。
U32 SvIOKp(SV* sv)SV が符号付き整数を含んでいるかどうかを示す真偽値を返します。
bool SvIOK_notUV(SV* sv)SV の IV ステータスをアンセットします。
void SvIOK_off(SV* sv)SV に対し、その SV が整数であるように指示します。
void SvIOK_on(SV* sv)SV に対し、その SV が整数であり、他の OK ビットをすべてディセーブルに するように指示します。
void SvIOK_only(SV* sv)SV に対し、その SV が符号なし整数であり、他の OK ビットをすべてディセーブルに するように指示します。
void SvIOK_only_UV(SV* sv)SV が符号なし整数を含んでいるかどうかを示す真偽値を返します。
bool SvIOK_UV(SV* sv)SV がコピーオンライトかどうかを示す真偽値を返します。 (共有ハッシュキースカラか、5.9.0 がコピーオンライト用に設定されていれば 完全なコピーオンライトスカラのどちらかです)
bool SvIsCOW(SV* sv)SV が Copy-On-Write 共有ハッシュキースカラかどうかを示す真偽値を返します。
bool SvIsCOW_shared_hash(SV* sv)SV を強制的に整数に変換し、それを返します。 sv を一度だけ評価することが保証されているバージョンについては SvIVx を 参照してください。
IV SvIV(SV* sv)SV の IV スロットの生の値を、チェックや変換なしに返します。 SvIOK が真であることを確認した後にのみ使えます。 SvIV() も参照してください。
IV SvIVX(SV* sv)SV を強制的に整数に変換し、それを返します。 sv を一度だけ評価することを保証します。 sv が副作用のある式の時にのみこれを使ってください; さもなければより 効率的な SvIV を使ってください。
IV SvIVx(SV* sv)SvIV と同様ですが、magic を処理しません。
IV SvIV_nomg(SV* sv)sv の IV ポインタの値を val にセットします。 SvIVX への左辺値代入によってこのマクロと同じ機能を行うことが可能です。 しかし、将来の Perl では、SvIVX への左辺値代入の代わりに、SvIV_set を 使う方がより効率的になります。
void SvIV_set(SV* sv, IV val)(SvOOK に起因する部分を含まない)SV にある文字列バッファのサイズを返します。 SvCUR を参照してください。
STRLEN SvLEN(SV* sv)SV に含まれている文字列の実際の長さを設定します。 SvIV_set を参照してください。
void SvLEN_set(SV* sv, STRLEN len)sv の MAGIC ポインタの値を val にセットします。 SvIV_set を参照してください。
void SvMAGIC_set(SV* sv, MAGIC* val)SV が数値、つまり整数値か倍精度実数値を含んでいるかどうかを表わす U32 値を返します。
U32 SvNIOK(SV* sv)SV が数値、つまり整数値か倍精度実数値を含んでいるかどうかを表わす U32 値を返します。 private な設定を検査します。 代わりに SvNIOK を使ってください。
U32 SvNIOKp(SV* sv)SV の NT/IV ステータスをアンセットします。
void SvNIOK_off(SV* sv)SV が倍精度実数値を含んでいるかどうかを示す U32 値を返します。
U32 SvNOK(SV* sv)SV が倍精度実数値を含んでいるかどうかを示す U32 値を返します。 private な設定を検査します。 代わりに SvNOK を使ってください。
U32 SvNOKp(SV* sv)SV にある NT ステータスをアンセットします。
void SvNOK_off(SV* sv)SV に対して、自分が倍精度実数であることを指示します。
void SvNOK_on(SV* sv)SV に対し、その SV が倍精度実数であり、その他の OK フラグをディセーブルに するよう指示します。
void SvNOK_only(SV* sv)SV を強制的に倍精度数値に変換し、それを返します。 sv を一度しか評価されないことが保証されているバージョンについては SvNVx を参照してください。
NV SvNV(SV* sv)SV の NV スロットの生の値を、チェックや変換なしに返します。 SvNOK が真であると分かっているときにだけ使ってください。 SvNV() も参照してください。
NV SvNVX(SV* sv)SV を強制的に倍精度数値に変換し、それを返します。 sv を一度だけ評価することを保証します。 sv が副作用のある式の時にのみこれを使ってください; さもなければ より効率的な SvNV を使ってください。
NV SvNVx(SV* sv)sv の NV ポインタの値を val にセットします。 SvIV_set を参照してください。
void SvNV_set(SV* sv, NV val)値が定義されているかどうかを示す U32 値を返します。 これはスカラでのみ意味があります。
U32 SvOK(SV* sv)文字列バッファへのポインタがオフセットであるかどうかを示す U32 値を 返します。 この hack は SvPV の先頭から文字を取り除くスピードを向上するために内部的に 使われます。 SvOOK が真であるとき、割り当てられた文字列バッファの開始点は実際には SvPVX から SvOOK_offset() バイト前になります。 このオフセットは SvIVX に保管されていましたが、今ではバッファの予備部分に 保管されます。
U32 SvOOK(SV* sv)Reads into len the offset from SvPVX back to the true start of the allocated buffer, which will be non-zero if sv_chop has been used to efficiently remove characters from start of the buffer. Implemented as a macro, which takes the address of len, which must be of type STRLEN. Evaluates sv more than once. Sets len to 0 if SvOOK(sv) is false. (TBT)
void SvOOK_offset(NN SV*sv, STRLEN len)SV が文字文字列を保持しているかどうかの U32 値を返します。
U32 SvPOK(SV* sv)SV が文字文字列を保持しているかどうかの U32 値を返します。 private な設定を検査します。 代わりに SvPOK を使ってください。
U32 SvPOKp(SV* sv)SV の PV ステータスをアンセットします。
void SvPOK_off(SV* sv)SV に対して、自分が文字列であることを指示します。
void SvPOK_on(SV* sv)SV に対し、その SV が文字列であり、他の OK ビットをすべてディセーブルに するように指示します。 また、UTF-8 ステータスをオフにします。
void SvPOK_only(SV* sv)SV に対し、その SV が文字列であり、他の OK ビットをディセーブルに して、UTF-8 ステータスがそのままにするように指示します。
void SvPOK_only_UTF8(SV* sv)SV にある文字列へのポインタか、SVが文字列を保持していない場合には SV の文字列化形式を返します。 SV は SvPOK になった文字列化バージョンをキャッシュするかもしれません。 'get' magic をハンドルします。 sv が一度しか評価されないことが保証されているバージョンについては SvPVx も参照してください。
char* SvPV(SV* sv, STRLEN len)SvPV と同様ですが、もし必要ならまず sv をバイト表現に変換します。
char* SvPVbyte(SV* sv, STRLEN len)SvPV と同様ですが、もし必要ならまず sv をバイト表現に変換します。 sv を 1 度だけ評価することを保証します; さもなければより効率のよい SvPVbyte を使ってください。
char* SvPVbytex(SV* sv, STRLEN len)SvPV_force と同様ですが、もし必要ならまず sv をバイト表現に変換します。 sv を 1 度だけ評価することを保証します; さもなければより効率のよい SvPVbyte_force を使ってください。
char* SvPVbytex_force(SV* sv, STRLEN len)SvPV_force と同様ですが、もし必要ならまず sv をバイト表現に変換します。
char* SvPVbyte_force(SV* sv, STRLEN len)SvPV_nolen と同様ですが、もし必要ならまず sv をバイト表現に変換します。
char* SvPVbyte_nolen(SV* sv)SvPV と同様ですが、もし必要ならまず sv を utf8 に変換します。
char* SvPVutf8(SV* sv, STRLEN len)SvPV と同様ですが、もし必要ならまず sv を utf8 に変換します。 sv を 1 度だけ評価することを保証します; さもなければより効率のよい SvPVutf8 を使ってください。
char* SvPVutf8x(SV* sv, STRLEN len)SvPV_force と同様ですが、もし必要ならまず sv を utf8 に変換します。 sv を 1 度だけ評価することを保証します; さもなければより効率のよい SvPVutf8_force を使ってください。
char* SvPVutf8x_force(SV* sv, STRLEN len)SvPV_force と同様ですが、もし必要ならまず sv を utf8 に変換します。
char* SvPVutf8_force(SV* sv, STRLEN len)SvPV_nolen と同様ですが、もし必要ならまず sv を utf8 に変換します。
char* SvPVutf8_nolen(SV* sv)SV にある物理文字列へのポインタを返します。 SV は文字列を保持していなければなりません。
char* SvPVX(SV* sv)sv を一度だけ評価することを保証するバージョンの SvPV です。 sv が副作用のある式の時にのみこれを使ってください; さもなければ より効率的な SvPVV を使ってください。
char* SvPVx(SV* sv, STRLEN len)SvPV と同様ですが、SV が単に文字列(SvPOK_only)を含むことを強制します。 SvPVX を直接更新したい場合には強制したいでしょう。
char* SvPV_force(SV* sv, STRLEN len)SvPV と同様ですが、SV が単に文字列(SvPOK_only)を含むことを強制します。 SvPVX を直接更新したい場合には強制したいでしょう。 magic を処理しません。
char* SvPV_force_nomg(SV* sv, STRLEN len)SV にある文字列へのポインタか、SVが文字列を保持していない場合には SV の文字列化形式を返します。 SV は SvPOK になった文字列化形式をキャッシュするかもしれません。 'get' magic をハンドルします。
char* SvPV_nolen(SV* sv)SvPV と同様ですが、magic を処理しません。
char* SvPV_nomg(SV* sv, STRLEN len)sv の PV ポインタの値を val にセットします。 SvIV_set を参照してください。
void SvPV_set(SV* sv, char* val)オブジェクトの参照カウントの値を返します。
U32 SvREFCNT(SV* sv)SV で与えられたものの参照カウントを減じます。
void SvREFCNT_dec(SV* sv)SV で与えられたものの参照カウントを増やします。
以下の SvREFCNT_inc* マクロ全ては SvREFCNT_inc の最適化バージョンで、 SvREFCNT_inc に置き換えられます。
SV* SvREFCNT_inc(SV* sv)SvREFCNT_inc と同じですが、sv が NULL ではないと分かっている場合にのみ 使えます。 NULL かどうかをチェックする必要がないので、より速くより小さいです。
SV* SvREFCNT_inc_NN(SV* sv)SvREFCNT_inc と同じですが、式に副作用がない場合にのみ使えます。 一時的な値を保管する必要がないので、より速いです。
SV* SvREFCNT_inc_simple(SV* sv)SvREFCNT_inc_simple と同じですが、sv が NULL ではないと分かっている 場合にのみ使えます。 NULL かどうかをチェックする必要がないので、より速くより小さいです。
SV* SvREFCNT_inc_simple_NN(SV* sv)SvREFCNT_inc_simple と同じですが、返り値が不要な場合にのみ使えます。 このマクロは意味のある値を返す必要はありません。
void SvREFCNT_inc_simple_void(SV* sv)SvREFCNT_inc と同じですが、返り値が不要で、sv が NULL ではないと 分かっている場合にのみ使えます。 このマクロは意味のある値を返す必要が無く、NULL をチェックする必要もないので、 より速くより小さいです。
void SvREFCNT_inc_simple_void_NN(SV* sv)SvREFCNT_inc と同じですが、返り値が不要な場合にのみ使えます。 このマクロは意味のある値を返す必要はありません。
void SvREFCNT_inc_void(SV* sv)SvREFCNT_inc と同じですが、返り値が不要で、sv が NULL ではないと 分かっている場合にのみ使えます。 このマクロは意味のある値を返す必要が無く、NULL をチェックする必要もないので、 より速くより小さいです。
void SvREFCNT_inc_void_NN(SV* sv)SV が RV であるかを検査します。
U32 SvROK(SV* sv)SV の RV ステータスをリセットします。
void SvROK_off(SV* sv)SV に、自分が RV であると指示します。
void SvROK_on(SV* sv)SV を返すために RV を参照はずしします。
SV* SvRV(SV* sv)sv の RV ポインタの値を val にセットします。 SvIV_set を参照してください。
void SvRV_set(SV* sv, SV* val)SV のスタッシュを返します。
HV* SvSTASH(SV* sv)sv の STASH ポインタの値を val にセットします。 SvIV_set を参照してください。
void SvSTASH_set(SV* sv, HV* val)汚染検査が有効なときに SV を汚染検査します。
void SvTAINT(SV* sv)SV が汚染されているかどうかをチェックします。 汚染されていれば TRUE を、そうでなければ FALSE を返します。
bool SvTAINTED(SV* sv)SV を汚染除去します。 Perl の基本的セキュリティ機構と同様 このルーチンを使うときは特に注意してください。 XS モジュールの作者は、汚染除去について良く理解しない限りは この関数を使うべきではありません。 perl 標準のやり方では直接変数の汚染除去するのではなく、 注意深く構築された正規表現を使って汚染除去が行われます。
void SvTAINTED_off(SV* sv)汚染チェックが有効な場合、汚染されているという印を SV につけます。
void SvTAINTED_on(SV* sv)Perl が SV を真と評価するか偽と評価するかを示す真偽値を返します。 定義/未定義のテストには SvOK() を参照してください。 'set' magic をハンドルしません。
bool SvTRUE(SV* sv)SV の型を返します。 svtype を参照してください。
svtype SvTYPE(SV* sv)SV が符号なし整数を含んでいるかどうかを示す真偽値を返します。
bool SvUOK(SV* sv)SV をより複雑なフォームにするために使われます。 必要であればアップグレードのために sv_upgrade を使用します。 svtype を参照してください。
void SvUPGRADE(SV* sv, svtype type)SV が UTF-8 エンコードされたデータを含んでいるかどうかを示す U32 値を 返します。 オーバーロードが内部フラグを更新する文字列に対して呼び出すときは SvPV() の後にこれを呼び出してください。
U32 SvUTF8(SV* sv)SV の UTF-8 状態をリセットします。
void SvUTF8_off(SV *sv)SV の UTF-8 状態をオンにします (データは変更されません; フラグだけです)。 軽率に使わないでください。
void SvUTF8_on(SV *sv)SV を強制的に符号なし整数に変換し、それを返します。 sv が 1 度だけ評価されることを保証しているバージョンについては SvUVx を参照してください。
UV SvUV(SV* sv)SV の UV スロットの生の値を、チェックや変換なしに返します。 SvIOK が真であることを確認した後にのみ使えます。 SvUV() も参照してください。
UV SvUVX(SV* sv)SV を強制的に符号なし整数に変換し、それを返します。 sv を一度だけ評価することを保証します。 sv が副作用のある式の時にのみこれを使ってください; さもなければ より効率的な SvUV を使ってください。
UV SvUVx(SV* sv)SvUV と同様ですが、magic を処理しません。
UV SvUV_nomg(SV* sv)sv の UV ポインタの値を val にセットします。 SvIV_set を参照してください。
void SvUV_set(SV* sv, UV val)SV がv-文字列を含んでいるかどうかを示す真偽値を返します。
bool SvVOK(SV* sv)sv_catpvn と同様ですが、magic を処理しません。
void sv_catpvn_nomg(SV* sv, const char* ptr, STRLEN len)sv_catsv と同様ですが、magic を処理しません。
void sv_catsv_nomg(SV* dsv, SV* ssv)C のレベルで SV が指定したクラスから派生したものであるかどうかを示す 真偽値を返します。 Perl レベルの派生をチェックするには、通常の Perl メソッドとして isa() を 呼び出してください。
bool sv_derived_from(SV* sv, const char *const name)SV が特定の名前付きのロールを行うかどうかを示す真偽値を返します。 SV は Perl オブジェクトか Perl クラスの名前です。
bool sv_does(SV* sv, const char *const name)開放されていない全ての SV の内容をダンプします。 (デバッグの助けとなります)。
void sv_report_used()sv_setsv と同様ですが、magic を処理しません。
void sv_setsv_nomg(SV* dsv, SV* ssv)sv_utf8_upgrade と同様ですが sv にマジックを適用しません。
STRLEN sv_utf8_upgrade_nomg(NN SV *sv)SV の内容が数値のようにみなせるか(あるいは数値であるか)を検査します。 たとえ atof() が認識しなくても、Inf と Infinity は数値として 扱われます(従って非数値警告は発生しません)。
I32 looks_like_number(SV *const sv)SV に対する RV ラッパーを生成します。 元の SV の参照カウントはインクリメント されません。
SV* newRV_noinc(SV *const sv)新たな SV を生成します。 非ゼロの len パラメーターは SV が持つべき割り当てずみ文字列空間の大きさを 示します。 余分な空間には NUL が埋められ、予約されます。 (SvPOK は文字列が割り当てられていたとしても SV をセットしません。) 新しい SV の参照カウントは 1 に設定されます。
5.9.3 で、newSV() は古い NEWSV() API を置き換え、呼び出し側が自分自身を 識別できるようにデバッグの助けをするための最初の引数 x がなくなりました。 この助けは新しいビルドオプション PERL_MEM_LOG ("PERL_MEM_LOG" in perlhack 参照) で置き換えられました。 古い API は、古い perl に対応している XS モジュールが使えるように まだ存在しています。
SV* newSV(const STRLEN len)ハッシュキー構造体から新しい SV を作成します。 可能なら共有文字列テーブルを指しているスカラを生成します。 hek が NULL なら、新しい(未定義値の) SV を返します。
SV* newSVhek(const HEK *const hek)新たな SV を生成し、整数値をそこにコピーします。 SV の参照カウントは 1 に設定されます。
SV* newSViv(const IV i)新たな SV を生成し、不動小数点数値をそこにコピーします。 SV の参照カウントは 1 に設定されます。
SV* newSVnv(const NV n)新たな SV を生成し、文字列をそこにコピーします。 SV の参照カウントは 1 に設定されます。 len がゼロの場合、Perl が strlen() を使って長さを計算します。 効率のために、代わりに newSVpvn を使うことを考慮してください。
SV* newSVpv(const char *const s, const STRLEN len)新たな SV を生成し、sprintf のような文字列書式によって初期化します。
SV* newSVpvf(const char *const pat, ...)新たな SV を生成し、文字列をそこにコピーします。 SV の参照カウントは 1 に設定されます。 len がゼロであった場合には長さゼロの文字列が生成されることに 注意してください。 ソース文字列が少なくとも len の長さがあることを保証する責任があります。 s 引数が NULL なら 新しい SV は未定義値です。
SV* newSVpvn(const char *const s, const STRLEN len)Creates a new SV and copies a string into it. The reference count for the SV is set to 1. Note that if len is zero, Perl will create a zero length string. You are responsible for ensuring that the source string is at least len bytes long. If the s argument is NULL the new SV will be undefined. Currently the only flag bits accepted are SVf_UTF8 and SVs_TEMP. If SVs_TEMP is set, then sv2mortal() is called on the result before returning. If SVf_UTF8 is set, s is considered to be in UTF-8 and the SVf_UTF8 flag will be set on the new SV. newSVpvn_utf8() is a convenience wrapper for this function, defined as (TBT)
#define newSVpvn_utf8(s, len, u) \
newSVpvn_flags((s), (len), (u) ? SVf_UTF8 : 0)
SV* newSVpvn_flags(const char *const s, const STRLEN len, const U32 flags)SvPVX_const が文字列テーブルの共有文字列を指している新しい SV を作成します。 文字列がまだテーブルに存在していないなら、まず作成されます。 READONLY と FAKE を有効にします。 hash 引数が非ゼロなら、その値が使われます; さもなければハッシュは 計算されます。 文字列のハッシュは、後で SvSHARED_HASH() マクロで SV から取得できます。 ここでの考え方は、文字列テーブルは共有ハッシュキーのために使われるので、 これらの文字列は SvPVX_const == HeKEY であって、ハッシュの検索は 文字列比較を防ぐと言うことです。
SV* newSVpvn_share(const char* s, I32 len, U32 hash)newSVpvn と同様ですが、文字列/長さの組ではなく、リテラルな文字列を 取ります。
SV* newSVpvs(const char* s)newSVpvn_flags と同様ですが、文字列/長さの組ではなくリテラルな文字列を 取ります。
SV* newSVpvs_flags(const char* s, U32 flags)newSVpvn_share と同様ですが、文字列/長さの組ではなく、リテラルな文字列を 取り、ハッシュパラメータを除外します。
SV* newSVpvs_share(const char* s)SV を指し示す RV の rv に対する新たな SV を生成します。 rv が RV でない場合には、それは RV に昇格します。 classname がヌルでない場合には、生成された SV は指定されたパッケージに bless されます。 参照カウントが 1 に設定された SV が返されます。
SV* newSVrv(SV *const rv, const char *const classname)元の SV を正確に複製した SV を生成します。 (sv_setsv を使います)。
SV* newSVsv(SV *const old)新しい SV を作成して、そこに符号なし整数をコピーします。 SV の参照カウントは 1 に設定されます。
SV* newSVuv(const UV u)指定された型の新しい SV を作成します。 新しい SV の参照カウントは 1 に設定されます。
SV* newSV_type(const svtype type)この関数は magical なアイテムからのみ呼び出され、sv_true() や等価な マクロからのみ使われます。
bool sv_2bool(SV *const sv)様々な作戦を使って、SV から CV を得ようとします; さらに、もし可能なら、 *st と *gvp に、それと関連づけられているスタッシュと GV に セットしようとします。 lref のフラグは gv_fetchsv に渡されます。
CV* sv_2cv(SV* sv, HV **const st, GV **const gvp, const I32 lref)様々な作戦を使って、SV から CV を得ようとします; GV なら IO スロット; RV なら再帰した結果; 文字列なら PV の後のシンボル名の IO スロットです。
IO* sv_2io(SV *const sv)必要な文字列変換を行って、SV の整数値を返します。 フラグに SV_GMAGIC が含まれていると、最初に mg_get() を行います。 通常は SvIV(sv) と SvIVx(sv) マクロ経由で使われます。
IV sv_2iv_flags(SV *const sv, const I32 flags)SV を揮発性にします。 SV は FREETMPS の明示的な呼び出しか、文の境界のような場所での暗黙の 呼び出しによって「すぐに」破壊されます。 この SV がコピーされると、SvTEMP() は SV の文字列バッファが「盗まれた」ことを 示すために音になります。 sv_newmortal と sv_mortalcopy も参照してください。
SV* sv_2mortal(SV *const sv)必要な文字列変換や整数変換、magic などを行って、SV の数値を返します。 通常は SvNV(sv) と SvNVx(sv) のマクロ経由で使います。
NV sv_2nv(SV *const sv)SV のバイトエンコードされた表現へのポインタを返し、その長さを *lp に セットします。 副作用として、SV が UTF-8 から降格するかもしれません。
普通は SvPVbyte マクロ経由でアクセスされます。
char* sv_2pvbyte(SV *const sv, STRLEN *const lp)SV の UTF-8 エンコードされた表現へのポインタを返し、その長さを *lp に セットします。 副作用として、SV が UTF-8 へ昇格するかもしれません。
普通は SvPVutf8 マクロ経由でアクセスされます。
char* sv_2pvutf8(SV *const sv, STRLEN *const lp)SV の文字列値へのポインタを返し、*lp にその長さをセットします。 フラグに SV_GMAGIC が含まれていると、最初に mg_get() を行います。 必要なら sv を文字列に強制します。 通常は SvPV_flags マクロ経由で起動されます。 sv_2pv() と sv_2pv_nomg も普通はここで終わります。
char* sv_2pv_flags(SV *const sv, STRLEN *const lp, const I32 flags)必要な文字列変換を行って、SV の符号なし整数値を返します。 フラグに SV_GMAGIC が含まれていると、最初に mg_get() を行います。 通常は SvUV(sv) と SvUVx(sv) マクロ経由で使われます。
UV sv_2uv_flags(SV *const sv, const I32 flags)文字列オフセットを取り除きます。 通常は代わりに SvOOK_off マクロラッパーを使うべきです。
int sv_backoff(SV *const sv)SV を指定したパッケージに bless します。 SV は RV でなければなりません。 パッケージは、そのスタッシュ(gv_stashpv() 参照)によって 指示されていなければなりません。 SV の参照カウントは影響を受けません。
SV* sv_bless(SV *const sv, HV *const stash)文字列を、SV にある文字列の終端に連結します。 SV の UTF-8 ステータスが設定されているなら、追加されるバイト列は妥当な UTF-8 であるべきです。 'get' magic をハンドルしますが、'set' magic はハンドルしません。 sv_catpv_mg を参照してください。
void sv_catpv(SV *const sv, const char* ptr)引数を sprintf のように処理し、SV にその結果を追加します。 追加するデータに「ワイド」文字(%s でフォーマットされた UTF-8 PV や %c でフォーマットされた >255 の文字の SV を含みますが、それに 限定されません)が含まれている場合、元の SV は UTF-8 に 昇格されるかもしれません。 'get' magic をハンドルしますが、'set' magic はハンドルしません。 sv_catpvf_mg を参照してください。 元の SV が UTF-8 なら、パターンは妥当な UTF-8 であるべきです; 元の SV が バイト列なら、パターンもそうあるべきです。
void sv_catpvf(SV *const sv, const char *const pat, ...)sv_catpvf と同様ですが、'set' magic もハンドルします。
void sv_catpvf_mg(SV *const sv, const char *const pat, ...)文字列を、SV にある文字列の終端に連結します。 len はコピーするバイト数を示します。 SV の UTF-8 ステータスが設定されているなら、追加されるバイト列は妥当な UTF-8 であるべきです。 'get' magic をハンドルしますが、'set' magic はハンドルしません。 sv_catpvn_mg を参照してください。
void sv_catpvn(SV *dsv, const char *sstr, STRLEN len)文字列を、SV にある文字列の終端に連結します。 len はコピーするバイト数を示します。 SV の UTF-8 ステータスが設定されているなら、追加されるバイト列は妥当な UTF-8 であるべきです。 flags の SV_GMAGIC ビットがセットされていると、適切なら dsv に mg_get し、さもなければしません。 sv_catpvn と sv_catpvn_nomg はこの関数に関して実装されています。
void sv_catpvn_flags(SV *const dstr, const char *sstr, const STRLEN len, const I32 flags)sv_catpvn と同様ですが、文字列/長さの組ではなく、リテラルな文字列を 取ります。
void sv_catpvs(SV* sv, const char* s)sv_catpv と同様ですが、'set' magic もハンドルします。
void sv_catpv_mg(SV *const sv, const char *const ptr)SV ssv にある文字列を、SV dsv にある文字列の終端へ連結します。 dsv を変更しますが ssv は変更しません。 'get' magic をハンドルしますが、'set' magic はハンドルしません。 sv_catsv_mg を参照してください。
void sv_catsv(SV *dstr, SV *sstr)SV ssv にある文字列を、SV dsv にある文字列の終端へ連結します。 dsv を変更しますが ssv は変更しません。 flags の SV_GMAGIC ビットがセットされていると、適切なら SV に mg_get し、さもなければしません。 sv_catsv と sv_catsv_nomg はこの関数に関して実装されています。
void sv_catsv_flags(SV *const dsv, SV *const ssv, const I32 flags)文字列バッファの先頭から文字を効率的に削除します。 SvPOK(sv) が真でなければならず、ptr は文字列バッファの 内側のどこかを指し示すポインタでなければなりません。 ptr は調整後の文字列の先頭となります。 "OOK hack" を使います。 注意: この関数から返った後、ptr と SvPVX_const(sv) はもはや同じデータの 塊を参照していません。
void sv_chop(SV *const sv, const char *const ptr)SV をクリアします: デストラクタを呼び出し、ボディで使われたメモリを解放し、 ボディ自身を解放します。 SV のヘッダは解放 されません が、 its type is set to all 1's so that it won't inadvertently be assumed to be live during global destruction etc. この関数は REFCNT がゼロになったときにのみ呼び出されるべきです。 ほとんどの場合 sv_free() (またはそのマクロラッパー SvREFCNT_dec) を 呼び出したいでしょう。
void sv_clear(SV *const sv)二つの SV にある文字列を比較します。 sv1 が sv2 より小さいときには -1 を、両者が等しいときには 0 を、 sv1 が sv2 より大きいときには 1 を返します。 UTF-8 と 'use bytes' を認識し、get magic をハンドルし、必要なら引数を 文字列に強制します。 sv_cmp_locale も参照してください。
I32 sv_cmp(SV *const sv1, SV *const sv2)二つの SV の文字列をロケールを認識するような形で比較します。 UTF-8 と 'use bytes' が有効で、get magic を扱い、必要なら引数を文字列に 強制します。 sv_cmp も参照してください。
I32 sv_cmp_locale(SV *const sv1, SV *const sv2)まだなければ、照合変換 magic を SV に追加します。
任意のスカラ値は変数のスカラデータを含む PERL_MAGIC_collxfrm magic を 保持しているかもしれませんが、ロケール設定に従った比較に通常のメモリ比較が 使えるようなフォーマットに変換されます。
char* sv_collxfrm(SV *const sv, STRLEN *const nxp)ソース SV の文字列化表現をデスティネーション SV にコピーします。 必要な mg_get と数値から文字列への強制を自動的に行います。 オーバーロードされたオブジェクトからであっても UTF8 フラグが 保存されることを保証します。 事実上 sv_2pv[_flags] と似ていますが、単なる文字列ではなく SV に対して 直接操作します。 この作業を行うためにほとんどは sv_2pv_flags フラグを使います; 例外は PV の UTF-8 性が失われるときです。
void sv_copypv(SV *const dsv, SV *const ssv)SV にある値の自動デクリメントを行います; 必要なら文字列から数値への変換を 行います。 'get' magic をハンドルします。
void sv_dec(SV *const sv)二つの SV にある文字列が同一のものであるかどうかをあらわす真偽値を 返します。 UTF-8 と 'use bytes' を認識し、get magic をハンドルし、必要なら引数を 文字列に強制します。
I32 sv_eq(SV* sv1, SV* sv2)SV に対する様々な種類のごまかしを元に戻します: PV が共有文字列なら、プライベートなコピーを作ります; 参照しているなら 参照を止めます; グロブなら、xpvmg に降格します; コピーオンライト スカラなら、コピーは書き込み時に行われ、ローカルに使われます。 SV_COW_DROP_PV がセットされているなら、コピーオンライトスカラは (もしあれば)PV バッファを落として、コピーを作る代わりに SvPOK_off に なります。 (このスカラが何か他の値にセットされようとした場所で使われます。) さらに、参照を止めるときに sv_unref_flags() に flags 引数が 渡されます。 sv_force_normal は flags に 0 をセットしてこの関数を呼び出します。
void sv_force_normal_flags(SV *const sv, const U32 flags)SV の参照カウントをデクリメントして、ゼロになったら、デストラクタを起動して ボディによって使われているメモリを解放するために sv_clear を呼び出します; 最後に、SV のヘッド地震を割り当て解除します。 通常はラッパーマクロ SvREFCNT_dec 経由で呼び出されます。
void sv_free(SV *const sv)ファイルハンドルから 1 行読み込んで SV に保管し、オプションで既に 保管されている文字列に追記します。
char* sv_gets(SV *const sv, PerlIO *const fp, I32 append)SV にある文字バッファを拡張します。 もし必要なら、sv_unref を使用して、SV を SVt_PV へ昇格します。 文字バッファへのポインタを返します。 代わりに SvGROW ラッパーを使用してください。
char* sv_grow(SV *const sv, STRLEN newlen)SV にある値の自動インクリメントを行います; もし必要なら、文字列から数値への変換を行います。 'get' magic をハンドルします。
void sv_inc(SV *const sv)文字列を、SV 中の指定されたオフセット/長さの位置に挿入します。 Perl の substr() 関数と同様のものです。 get magic をハンドルします。
void sv_insert(SV *const bigstr, const STRLEN offset, const STRLEN len, const char *const little, const STRLEN littlelen)sv_insert と同様ですが追加の flags が bigstr に適用される SvPV_force_flags に渡されます。
void sv_insert_flags(SV *const bigstr, const STRLEN offset, const STRLEN len, const char *const little, const STRLEN littlelen, const U32 flags)SV が指定したクラスに bless されているかどうかを表わす真偽値を 返します。 これは、subtype をどのようにチェックするかを知らないので、 継承関係に確認するのに sv_derived_from を使います。
int sv_isa(SV* sv, const char *const name)SV が、bless されているオブジェクトを指す RV であるかどうかを表わす 真偽値を返します。 SV が RV でない場合、もしくはオブジェクトが bless されていない場合にはこれは false を返します。
int sv_isobject(SV* sv)SV にある文字列の長さを返します。 magic と型強制をハンドルします。 xpv_cur スロットへの生アクセスを提供する SvCUR も参照してください。
STRLEN sv_len(SV *const sv)SV にある文字列の文字数を返します; ワイド UTF-8 バイトは一文字として 数えます。 magic と型強制をハンドルします。
STRLEN sv_len_utf8(SV *const sv)SV に magic を追加します。 必要ならまず sv を型 SVt_PVMG に昇格して、それから magic リストの 先頭に型 how の新しい magic アイテムを追加します。
name と namlen 引数の扱いに関する記述については (sv_magic が 呼び出す) sv_magicext を参照してください。
SvREADONLY SV に magic を追加したり同じ 'how' の複数の実体を追加するには sv_magicext を使う必要があります。
void sv_magic(SV *const sv, SV *const obj, const int how, const char *const name, const I32 namlen)SV に magic を追加して、必要なら昇格させます。 提供された vtable を適用して、追加した magic へのポインタを返します。
sv_magicext は、sv_magic が出来ないことが出来ると言うことに 注意してください。 特に、SvREADONLY SV に magic を追加したり、同じ 'how' の複数の実体を 追加したりできます。
namlen がゼロ以上なら、savepvn に name の コピー が保管されます; namlen がゼロなら name はそのまま保管されて - もう一つの特殊な 場合として - (name && namlen == HEf_SVKEY) なら name は SV* を 含んでいるものと仮定されて、その REFCNT をインクリメントして、そのまま 保管されます。
(これは今では sv_magic によってサブルーチンとして使われます。)
MAGIC * sv_magicext(SV *const sv, SV *const obj, const int how, const MGVTBL *const vtbl, const char *const name, const I32 namlen)(sv_setsv を使って)元の SV のコピーである、新しい SV を生成します。 生成された SV は揮発性である目印が付けられます。 これは FREETMPS の明示的な呼び出しか、文の境界のような場所での暗黙の 呼び出しによって「すぐに」破壊されます。 sv_newmortal と sv_2mortal も参照してください。
SV* sv_mortalcopy(SV *const oldsv)揮発性である新たな null SV を生成します。 新たに作られた SV の参照カウントは 1 に設定されます。 これは FREETMPS の明示的な呼び出しか、文の境界のような場所での暗黙の 呼び出しによって「すぐに」破壊されます。 sv_mortalcopy と sv_2mortal も参照してください。
SV* sv_newmortal()SV の参照カウントをインクリメントします。 代わりに SvREFCNT_inc() ラッパーを使ってください。
SV* sv_newref(SV *const sv)文字列の先頭からバイト数で offsetp 離れたところから、UTF-8 文字として等価な 数の分だけ変換します。 magic と型強制をハンドルします。
void sv_pos_b2u(SV *const sv, I32 *const offsetp)文字列の先頭から UTF-8 の文字数で offsetp 離れたところから、 等価なバイト数の分だけのところまでの値を変換します; lenp が非ゼロなら、これは lenp と同じですが、この場合は文字列の 先頭からではなく offset から始めます。 magic と型強制をハンドルします。
2Gb より長い文字列を正しく扱える sv_pos_u2b_flags を優先して 使ってください。
void sv_pos_u2b(SV *const sv, I32 *const offsetp, I32 *const lenp)Converts the value pointed to by offsetp from a count of UTF-8 chars from the start of the string, to a count of the equivalent number of bytes; if lenp is non-zero, it does the same to lenp, but this time starting from the offset, rather than from the start of the string. Handles type coercion. flags is passed to SvPV_flags, and usually should be SV_GMAGIC|SV_CONST_RETURN to handle magic. (TBT)
STRLEN sv_pos_u2b_flags(SV *const sv, STRLEN uoffset, STRLEN *const lenp, U32 flags)SvPVbytex_force マクロのバックエンドです。 代わりに、常にマクロを使ってください。
char* sv_pvbyten_force(SV *const sv, STRLEN *const lp)SV から何か識別できる文字列を取り出します。 複雑なマクロ式を扱えないコンパイラのための、SvPV_force マクロの プライベート実装です。 代わりに、常にマクロを使ってください。
char* sv_pvn_force(SV* sv, STRLEN* lp)SV から何か識別できる文字列を取り出します。 flags の SV_GMAGIC ビットがセットされていると、適切なら sv に mg_get し、さもなければしません。 sv_pvn_force と sv_pvn_force_nomg はこの関数に関して実装されています。 通常は代わりに様々なラッパーマクロを使いたいでしょう: SvPV_force と SvPV_force_nomg を参照してください。
char* sv_pvn_force_flags(SV *const sv, STRLEN *const lp, const I32 flags)SvPVutf8x_force マクロのバックエンドです。 代わりに、常にマクロを使ってください。
char* sv_pvutf8n_force(SV *const sv, STRLEN *const lp)SV がリファレンスしているものを記述した文字列を返します。
const char* sv_reftype(const SV *const sv, const int ob)最初の引数を二つ目の引数のコピーにして、元のデータを削除します。 ターゲット SV は物理的にソース SV のボディの所有権を受け取って、フラグを 継承します; しかし、ターゲットは magic を保持したままで、ソースの magic は 捨てられます。 これは特殊な SV コピー操作であることに注意してください; ほとんどの場合 sv_setsv か多くのこれのマクロフロントエンドを使いたいでしょう。
void sv_replace(SV *const sv, SV *const nsv)reset Perl 関数の基礎となる実装です。 perl レベルの関数は漠然と廃止予定であることに注意してください。
void sv_reset(const char* s, HV *const stash)参照を弱めます: この RV の SvWEAKREF フラグをセットします; まだなければ 参照されている SB に PERL_MAGIC_backref magic を与えます; そしてこの RV への後方参照を magic と関連づけられた後方参照の配列に プッシュします。 RV がマジカルなら、set magic は RV がクリアした後呼び出されます。
SV* sv_rvweaken(SV *const sv)整数を与えられた SV へコピーします; 必要なら最初に昇格します。 'set' magic をハンドルしません。 sv_setiv_mg も参照してください。
void sv_setiv(SV *const sv, const IV num)sv_setiv と同様ですが、'set' magic をハンドルします。
void sv_setiv_mg(SV *const sv, const IV i)倍精度浮動小数点数を与えられた SV へコピーします; 必要なら最初に昇格します。 'set' magic をハンドルしません。 sv_setnv_mg も参照してください。
void sv_setnv(SV *const sv, const NV num)sv_setnv と同様ですが、'set' magic をハンドルします。
void sv_setnv_mg(SV *const sv, const NV num)文字列を SV へコピーします。 文字列は null で終端されていなければなりません。 'set' magic をハンドルしません。 sv_setpv_mg を参照してください。
void sv_setpv(SV *const sv, const char *const ptr)sv_catpvf のように動作しますが、SV にテキストを追加するのではなく コピーします。 'set' magic をハンドルしません。 sv_setpvf_mg を参照してください。
void sv_setpvf(SV *const sv, const char *const pat, ...)sv_setpvf と同様ですが、'set' magic をハンドルします。
void sv_setpvf_mg(SV *const sv, const char *const pat, ...)整数値を与えられた SV をコピーし、同様にその文字列値を更新します。 'set' magic をハンドルしません。 sv_setpviv_mg を参照してください。
void sv_setpviv(SV *const sv, const IV num)sv_setpviv と同様ですが、'set' magic をハンドルします。
void sv_setpviv_mg(SV *const sv, const IV iv)文字列を SV へコピーします。 パラメーター len はコピーされるバイト数を指示します。 ptr 引数が NULL なら SV は未定義値になります。 'set' magic をハンドルしません。 sv_setpvn_mg を参照してください。
void sv_setpvn(SV *const sv, const char *const ptr, const STRLEN len)sv_setpvn と同様ですが、'set' magic をハンドルします。
void sv_setpvn_mg(SV *const sv, const char *const ptr, const STRLEN len)sv_setpvn と同様ですが、文字列/長さの組ではなく、リテラルな文字列を 取ります。
void sv_setpvs(SV* sv, const char* s)sv_setpv と同様ですが、'set' magic をハンドルします。
void sv_setpv_mg(SV *const sv, const char *const ptr)整数値を、bless することもできる新たな SV へコピーします。 引数 rv は RV へと昇格します。 この RV は新たな SV を指し示すように変更されます。 引数 classname は bless するパッケージを指示するものです。 bless をしないためには、classname に NULL をセットします。 新しい SV の参照カウントは 1 となり、RV が返されます。
SV* sv_setref_iv(SV *const rv, const char *const classname, const IV iv)倍精度実数値を、bless することもできる新たな SV へコピーします。 引数 rv は RV へと昇格します。 この RV は新たな SV を指し示すように変更されます。 引数 classname は bless するパッケージを指示するものです。 bless をしないためには、classname に NULL をセットします。 新しい SV の参照カウントは 1 となり、RV が返されます。
SV* sv_setref_nv(SV *const rv, const char *const classname, const NV nv)ポインタを、bless することもできる新たな SV へコピーします。 引数 rv は RV へと昇格します。 この RV は新たな SV を指し示すように変更されます。 引数 pv が NULL であれば、PL_sv_undef が新たな SV に格納されます。 引数 classname は bless するパッケージを指示するものです。 bless をしないためには、classname に NULL をセットします。 新しい SV の参照カウントは 1 となり、RV が返されます。
HV, AV, SV, CV のような Perl の他の type を使わないようにしてください; これは、そういったオブジェクトにポインタのコピー処理を 行うことでおかしくなってしまうからです。
sv_setref_pvn は、このポインタのコピーではなく文字列を コピーしているということに注意してください。
SV* sv_setref_pv(SV *const rv, const char *const classname, void *const pv)文字列を、bless することもできる新たな SV へコピーします。 文字列の長さを n で指定しなければなりません。 引数 rv は RV へと昇格します。 この RV は新たな SV を指し示すように変更されます。 引数 classname は bless するパッケージを指示するものです。 bless をしないためには、classname に NULL をセットします。 新しい SV の参照カウントは 1 となり、RV が返されます。
sv_setref_pv は、文字列をコピーするのではなくポインタを コピーするということに注意してください。
SV* sv_setref_pvn(SV *const rv, const char *const classname, const char *const pv, const STRLEN n)整数値を、bless することもできる新たな SV へコピーします。 引数 rv は RV へと昇格します。 この RV は新たな SV を指し示すように変更されます。 引数 classname は bless するパッケージを指示するものです。 bless をしないためには、classname に NULL をセットします。 新しい SV の参照カウントは 1 となり、RV が返されます。
SV* sv_setref_uv(SV *const rv, const char *const classname, const UV uv)送り元の SV ssv の内容を、送り先の SV dsv にコピーします。 送り元の SV は、それが揮発性であった場合には破壊されるかもしれません; 従ってソース SV を再利用する必要がある場合にはこの関数は使わないでください。 'set' magic をハンドルしません。 大まかに言うと、送り先の以前の内容を消して、値としてのコピーを行います。
おそらく SvSetSV, SvSetSV_nosteal, SvSetMagicSV, SvSetMagicSV_nosteal のようなラッパーの一つを使いたいでしょう。
void sv_setsv(SV *dstr, SV *sstr)送り元の SV ssv の内容を、送り先の SV dsv にコピーします。 送り元の SV は、それが揮発性であった場合には破壊されるかもしれません; 従って ソース SV を再利用する必要がある場合にはこの関数は使わないでください 'set' magic をハンドルしません。 大まかに言うと、送り先の以前の内容を消して、値としてのコピーを行います。 flags の SV_GMAGIC ビットがセットされていると、適切なら ssv に mg_get し、さもなければしません。 flags 引数の NOSTEAL ビットがセットされているなら、temps の バッファは盗まれません。 <sv_setsv> と sv_setsv_nomg はこの関数に関して実装されています。
おそらく SvSetSV, SvSetSV_nosteal, SvSetMagicSV, SvSetMagicSV_nosteal のようなラッパーの一つを使いたいでしょう。
これはスカラをコピーする基本的な関数で、その他のほとんどのコピー的な 関数とマクロは基礎としてこれを使っています。
void sv_setsv_flags(SV *dstr, SV *sstr, const I32 flags)sv_setsv と同様ですが、'set' magic をハンドルします。
void sv_setsv_mg(SV *const dstr, SV *const sstr)符号なし整数を与えられた SV へコピーします; 必要ならまず昇格します。 'set' magic をハンドルしません。 sv_setuv_mg も参照してください。
void sv_setuv(SV *const sv, const UV num)sv_setsv と同様ですが、'set' magic をハンドルします。
void sv_setuv_mg(SV *const sv, const UV u)SV の汚染を調べます。 代わりに SvTAINTED を使ってください。
bool sv_tainted(SV *const sv)SV が Perl の規則で真の値を持っていれば真を返します。 sv_true() を呼び出すかも知れないし代わりにインライン版を使うかも知れない SvTRUE マクロを代わりに使ってください。
I32 sv_true(SV *const sv)SV から type 型の全ての magic を取り除きます。
int sv_unmagic(SV *const sv, const int type)SV の RV ステータスをアンセットし、RV によって参照されているものの 参照カウントを減じます。 これは newSVrv の反転したものであると考えられます。 cflags 引数は、参照カウントをデクリメントすることを強制するために SV_IMMEDIATE_UNREF を含むことができます (さもなければデクリメントは参照カウントが 1 ではないか、読み込み専用 SV を 参照しているという条件で行われます)。 SvROK_off を参照してください。
void sv_unref_flags(SV *const ref, const U32 flags)SV を被汚染化します。 代わりに SvTAINTED_off を使ってください。
void sv_untaint(SV *const sv)SV をより複雑な形式へと昇格させます。 一般的に新しいボディ型を SV に追加して、古いボディから出来るだけ多くの情報を コピーします。 一般的には SvUPGRADE マクロラッパーを使いたいでしょう。 svtype も参照してください。
void sv_upgrade(SV *const sv, svtype new_type)自身の文字列値を得るのに ptr を使うように SV に指示します。 通常文字列は SV の内側に保管されますが、sv_usepvn によって SV が外側の 文字列を使えるようにできます。 ptr は malloc によって割り当てられたメモリを指しているべきです。 文字列の長さ len を指定しなければなりません。 デフォルトではこの関数は ptr で指されているメモリを realloc (つまり移動) するので、ポインタは sv_usepvn に与えられた後で解放されたりプログラマによって 使われたりするべきではありませんし、このポインタの「背後」(例えば ptr + 1) からのポインタを使うべきではありません。
flags & SV_SMAGIC が真なら、SvSETMAGIC を呼び出します。 flags & SV_HAS_TRAILING_NUL が真なら、ptr[len] は NUL で なければならず、realloc はスキップされます。 (つまりバッファは実際には少なくとも len より 1 バイト長く、既に SvPVX を保管する条件を満たしています。)
void sv_usepvn_flags(SV *const sv, char* ptr, const STRLEN len, const U32 flags)SV の PV が UTF-8 のオクテット並びで複数バイト文字を含んでいるなら、 文字のように見えるように SvUTF8 フラグがオンになります。 PV が単一バイト文字だけを含んでいるなら、SvUTF8 フラグはオフのママです。 PV の妥当性をスキャンして、PV が妥当な UTF-8 ではないなら偽を返します。
注意: この関数は実験的で、予告なしに変更あるいは削除されるかもしれません。
bool sv_utf8_decode(SV *const sv)SV の PV を文字からバイトに変換しようとします。 PV にバイトに収まらない文字が含まれているなら、この変換は失敗します; この場合、偽を返すか、fail_ok が真でないなら、croak します。
これは汎用の Unicode からバイトエンコーディングへのインターフェースでは ありません: そのような目的には Encode エクステンションを使ってください。
注意: この関数は実験的で、予告なしに変更あるいは削除されるかもしれません。
bool sv_utf8_downgrade(SV *const sv, const bool fail_ok)SV の PV を UTF-8 に変換しますが、再びオクテットのように見えるように SvUTF8 フラグをオフにします。
void sv_utf8_encode(SV *const sv)SV の PV を UTF-8 エンコードされた形式に変換します。 もしまだ行われていなければ、SV を文字列形式に強制します。 例え文字列全体が UTF-8 で同じでも、将来の正当性チェックを 避けるために、常に SvUTF8 フラグがセットされます。 変換した文字列のバイト数を返します。
これは汎用のバイトエンコーディングから Unicode へのインターフェースでは ありません: そのような目的には Encode エクステンションを使ってください。
STRLEN sv_utf8_upgrade(SV *sv)SV の PV を UTF-8 エンコードされた形式に変換します。 もしまだ行われていなければ、SV を文字列形式に強制します。 例え全てのバイトが UTF-8 と変わらなくても、将来の正当性チェックを 避けるために、常に SvUTF8 フラグがセットされます。 flags の SV_GMAGIC ビットがセットされていると、適切なら sv に mg_get し、さもなければしません。 変換した文字列のバイト数を返します。 sv_utf8_upgrade と sv_utf8_upgrade_nomg はこの関数に関して 実装されています。
これは汎用のバイトエンコーディングから Unicode へのインターフェースでは ありません: そのような目的には Encode エクステンションを使ってください。
STRLEN sv_utf8_upgrade_flags(SV *const sv, const I32 flags)sv_utf8_upgrade と同様ですが sv にマジックを適用しません。
STRLEN sv_utf8_upgrade_nomg(SV *sv)引数を vsprintf のように処理してフォーマットした出力を SV に追加します。 'set' magic をハンドルしません。 sv_vcatpvf_mg を参照してください。
普通はフロントエンドである sv_catpvf 経由で使われます。
void sv_vcatpvf(SV *const sv, const char *const pat, va_list *const args)引数を vsprintf のように処理してフォーマットした出力を SV に追加します。 C スタイルの変数引数リストがない(NULL)場合には Sv の配列を使用します。 汚染チェックが有効の状態で実行すると、(しばしばロケールの使用によって 結果が信頼できないものなら、maybe_tainted 経由で示します。
普通はフロントエンドである sv_vcatpvf や sv_vcatpvf_mg 経由で 使われます。
void sv_vcatpvfn(SV *const sv, const char *const pat, const STRLEN patlen, va_list *const args, SV **const svargs, const I32 svmax, bool *const maybe_tainted)sv_vcatpvf と同様ですが、'set' magic をハンドルします。
普通はフロントエンドである sv_catpvf_mg 経由で使われます。
void sv_vcatpvf_mg(SV *const sv, const char *const pat, va_list *const args)sv_vcatpvf と同様に動作しますが、追加するのではなく SV にテキストを コピーします。 'set' magic をハンドルしません。 sv_vsetpvf_mg を参照してください。
普通はフロントエンドである sv_setpvf 経由で使われます。
void sv_vsetpvf(SV *const sv, const char *const pat, va_list *const args)vatpvfn のように動作しますが、SV にテキストを追加するのではなく コピーします。
普通はフロントエンドである sv_vsetpvf や sv_vsetpvf_mg 経由で 使われます。
void sv_vsetpvfn(SV *const sv, const char *const pat, const STRLEN patlen, va_list *const args, SV **const svargs, const I32 svmax, bool *const maybe_tainted)sv_vsetpvf と同様ですが、'set' magic をハンドルします。
普通はフロントエンドである sv_setpvf_mg 経由で使われます。
void sv_vsetpvf_mg(SV *const sv, const char *const pat, va_list *const args)長さ len の文字列 s を UTF-8 からネイティブなバイトエンコーディングに 変換します。 utf8_to_bytes と異なりますが bytes_to_utf8 と同様、 新しく作成された文字列へのポインタを返し、len を新しい長さで更新します。 変換が行われなければ元の文字列を返し、len は変更されません。 is_utf8 が 0 を指しているなら何もしません。 s が変換されたか、utf8 でも変わらない文字だけで構成されているなら (つまり非 EBCDIC マシンでの US-ASCII なら) is_utf8 を 0 にセットします。
注意: この関数は実験的で、予告なしに変更あるいは削除されるかもしれません。
U8* bytes_from_utf8(const U8 *s, STRLEN *len, bool *is_utf8)長さ len の文字列 s を、ネイティブなエンコーディングから UTF-8 エンコーディングに変換します。 新しく作成された文字列へのポインタを返し、len に新しい長さを 反映させます。
文字列の末尾に NUL 文字が書かれます。
ネイティブ以外のエンコーディング (Latin1 または EBCDIC) から UTF-8 に 変換したいなら、sv_recode_to_utf8() を参照してください。
注意: この関数は実験的で、予告なしに変更あるいは削除されるかもしれません。
U8* bytes_to_utf8(const U8 *s, STRLEN *len)文字列 s1 と s2 が大文字小文字を無視しても違いがあれば真を返し、 さもなければ (大文字小文字を無視して同じなら) 偽を返します。 u1 が真なら、文字列 s1 は UTF-8 エンコードされた Unicode であると 仮定されます。 u2 が真なら、文字列 s2 は UTF-8 エンコードされた Unicode であると 仮定されます。 u1 か u2 が偽なら、対応する文字列はネイティブな 8 ビットエンコーディングで あると仮定されます。
pe1 と pe2 が非 NULL なら、スキャンポインタはここにコピーされます (これらは next 文字の先頭を指します)。 pe1 または pe2 の背後のポインタが非 NULL なら、これらはどのような場合でも スキャンが継続されないエンドポインタです。 バイト長 l1 と l2 が非ゼロなら、s1+l1 と s2+l2 がスキャンを停止して 成功したマッチングを定義するための条件となるゴール端ポインタとして 使われます: 明示的な長さを定義した全てのスキャンはマッチングが 成功するためにゴールポインタに到達しなければなりません)。
大文字小文字の虫に関して、Unicode の「畳み込み化」は文字の大文字化/小文字化の 両方の代わりに使われます; http://www.unicode.org/unicode/reports/tr21/ (Case Mappings) を 参照してください。
I32 ibcmp_utf8(const char *s1, char **pe1, UV l1, bool u1, const char *s2, char **pe2, UV l2, bool u2)Returns true if first len bytes of the given string are ASCII (i.e. none of them even raise the question of UTF-8-ness). (TBT)
is_utf8_string(), is_utf8_string_loclen(), is_utf8_string_loc() も 参照してください。
bool is_ascii_string(const U8 *s, STRLEN len)任意の数のバイト列が妥当な UTF-8 文字から始まるかどうかをテストします。 INVARIANT (つまり 非 EBCDIC マシンでは ASCII) は妥当な UTF-8 文字であることに 注意してください。 妥当であれば UTF-8 文字の実際のバイト数が返され、さもなければ 0 が 返されます。
STRLEN is_utf8_char(const U8 *s)文字列の最初の len バイトが妥当な UTF-8 文字列なら真を返し、さもなければ 偽を返します。 「妥当な UTF-8 文字列」は「UTF-8 でエンコードされた、0x7F を超える符号位置の 文字を含む文字列」という意味ではないことに注意してください; なぜなら 妥当な ASCII 文字列は妥当な UTF-8 文字列だからです。
is_ascii_string(), is_utf8_string_loclen(), is_utf8_string_loc() も 参照してください。
bool is_utf8_string(const U8 *s, STRLEN len)is_utf8_string() と同様ですが、ep に、(「utf8 失敗」の場合)失敗した 位置を、(「utf8 成功」の場合) s+len の位置を保管します。
is_utf8_string_loclen() と is_utf8_string() も参照してください。
bool is_utf8_string_loc(const U8 *s, STRLEN len, const U8 **p)is_utf8_string() と同様ですが、ep に、(「utf8 失敗」の場合)失敗した 位置を、(「utf8 成功」の場合) s+len の位置を保管し、UTF-8 エンコードされた 文字の数を el に保管します。
is_utf8_string_loc() と is_utf8_string() も参照してください。
bool is_utf8_string_loclen(const U8 *s, STRLEN len, const U8 **ep, STRLEN *el)スカラ dsv を文字列 spv 長さ len の表示可能なバージョンに構築します; 表示可能なバージョンは最大でも pvlim バイトの長さです (もしより長ければ、 残りは切り詰められて "..." が追加されます)。
flags 引数には、isPRINT() 可能な文字をそのまま表示する UNI_DISPLAY_ISPRINT、 \\[nrfta\\] を ('\n' のように) バックスラッシュ版として表示する UNI_DISPLAY_BACKSLASH を含むことができます (UNI_DISPLAY_BACKSLASH は \\ に関して UNI_DISPLAY_ISPRINT より優先されます)。 UNI_DISPLAY_QQ (およびその別名である UNI_DISPLAY_REGEX) は UNI_DISPLAY_BACKSLASH と UNI_DISPLAY_ISPRINT の両方をオンにします。
dsv の PV へのポインタが返されます。
char* pv_uni_display(SV *dsv, const U8 *spv, STRLEN len, STRLEN pvlim, UV flags)encoding は Encode オブジェクトであると仮定して、また ssv の PV は そのエンコーディングのオクテットであると仮定して、入力のデコードは (PV + *offset) が指す位置から開始されます。 dsv は ssv からデコードされた UTF-8 文字列と連結されます。 デコードは文字列 str がデコード出力に現れるか、ssv の PV の入力が 終わったときに終了します。 オフセットが指す値は ssv の最後の入力位置によって修正されます。
終端子が見付かれば TRUE を、さもなければ FALSE を返します。
bool sv_cat_decode(SV* dsv, SV *encoding, SV *ssv, int *offset, char* tstr, int tlen)encoding は Encode オブジェクトであると仮定して、また sv の PV のエントリは そのエンコーディングのオクテットであると仮定して、sv を Unicode (と UTF-8) に 変換します。
sv が既に UTF-8 なら(または POK でなければ)、あるいは encoding が リファレンスでなければ、sv に対して何もしません。 encoding が Encode::XS エンコーディングオブジェクトでなければ、 悪いことが起こります。 (lib/encoding.pm と Encode を参照してください)。
sv の PV が返されます。
char* sv_recode_to_utf8(SV* sv, SV *encoding)スカラ dsv をスカラ sv の表示可能なバージョンに構築します; 表示可能な バージョンは最大でも pvlim バイトの長さです (もしより長ければ、残りは 切り詰められて "..." が追加されます)。
flags 引数は pv_uni_display() と同様です。
dsv の PV へのポインタが返されます。
char* sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags)"p" は、変換された UTF-8 文字列エンコーディングの文字へのポインタを 含みます。
"ustrp" は変換結果を入れた文字バッファへのポインタです。 "lenp" は結果の長さへのポインタです。
"swashp" は使う swash へのポインタです。
特殊と通常の両方のマッピングは lib/unicore/To/Foo.pl に保管され、 lib/utf8_heavy.pl を使って SWASHNEW によって読み込まれます。 特殊(普通は複数文字マッピングですが常にそうというわけではありません)を 先に試します。
「特殊」とは、ハッシュ %utf8::ToSpecLower を意味する "utf8::ToSpecLower" のような文字列です。 ハッシュへのアクセスは Perl_to_utf8_case() を通します。
「通常」とは、swash %utf8::ToLower を意味する "ToLower" のような文字列です。
UV to_utf8_case(const U8 *p, U8* ustrp, STRLEN *lenp, SV **swashp, const char *normal, const char *special)p にある UTF-8 エンコードされた文字を畳み込み文字版に変換して、UTF-8 エンコードしたものを ustrp に、そのバイト数を lenp に保管します。 畳み込み文字版は元の文字より(最大 3 文字)長くなるかも知れないので、ustrp は 少なくとも UTF8_MAXBYTES_CASE+1 バイト必要であることに注意してください。
最初の文字の畳み込み文字版が返されます(しかし、上述の通り、もっとあるかも しれません。)
UV to_utf8_fold(const U8 *p, U8* ustrp, STRLEN *lenp)p にある UTF-8 エンコードされた文字を小文字版に変換して、UTF-8 エンコードしたものを ustrp に、そのバイト数を lenp に保管します。 小文字版は元の文字より長くなるかも知れないので、ustrp は少なくとも UTF8_MAXBYTES_CASE+1 バイト必要であることに注意してください。
最初の文字の小文字版が返されます(しかし、上述の通り、もっとあるかも しれません。)
UV to_utf8_lower(const U8 *p, U8* ustrp, STRLEN *lenp)p にある UTF-8 エンコードされた文字をタイトル文字版に変換して、UTF-8 エンコードしたものを ustrp に、そのバイト数を lenp に保管します。 タイトル文字版は元の文字より長くなるかも知れないので、ustrp は少なくとも UTF8_MAXBYTES_CASE+1 バイト必要であることに注意してください。
最初の文字のタイトル文字版が返されます(しかし、上述の通り、もっとあるかも しれません。)
UV to_utf8_title(const U8 *p, U8* ustrp, STRLEN *lenp)p にある UTF-8 エンコードされた文字を大文字版に変換して、UTF-8 エンコードしたものを ustrp に、そのバイト数を lenp に保管します。 小文字版は元の文字より長くなるかも知れないので、ustrp は少なくとも UTF8_MAXBYTES_CASE+1 バイト必要であることに注意してください。
最初の文字の大文字版が返されます(しかし、上述の通り、もっとあるかも しれません。)
UV to_utf8_upper(const U8 *p, U8* ustrp, STRLEN *lenp)flags
UTF-8 エンコーディングされていると仮定されている文字列 s の最初の文字の ネイティブな符号位置を返します; retlen にはその文字のバイト数が セットされます。
長さとフラグは低レベルルーチンに渡されることを許しています。
UV utf8n_to_uvchr(const U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags)最低レベルの UTF-8 デコードルーチンです。 UTF-8 エンコーディングされていて curlen より長くはないと仮定されている 文字列 s の最初の文字のUnicode 符号位置を返します; retlen には その文字のバイト数がセットされます。
s が整形された UTF-8 文字を指していない場合、振る舞いは flags の値に 依存します: UTF8_CHECK_ONLY を含んでいれば、呼び出し側が警告を発生させて、 この関数は暗黙に retlen を -1 にセットしてゼロを返すことを仮定します。 flags に UTF8_CHECK_ONLY が含まれていなければ、不正な文字に関する警告が 与えられ、retlen は想定される UTF-8 文字のバイト数がセットされ、ゼロが 返されます。
flags は、厳密な UTF-8 エンコーディングからの逸脱を認める様々なフラグを 含めることもできます (utf8.h を参照してください)。
ほとんどのコードではこれを直接呼び出さずに utf8_to_uvchr() を使うべきです。
UV utf8n_to_uvuni(const U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags)UTF-8 ポインタ a と b の間の UTF-8 文字の数を返します。
警告: ポインタが同じ UTF-8 バッファの中を指していることを「知っている」 場合にのみ使ってください。
IV utf8_distance(const U8 *a, const U8 *b)前または後ろに off 文字だけずらした UTF-8 ポインタ s を返します。
警告: off が s で指されている UTF-8 データの内側であることと、 エントリ s が文字の最初のバイトか文字の最後のバイトの直後に 位置合わせされているということが「分かっている」場合以外は 使わないでください。
U8* utf8_hop(const U8 *s, I32 off)UTF-8 文字エンコードされた文字列 s の文字数を返します。 e で停止します(これも含みます)。 e < s であったり、スキャンが e を超えて停止すると、croak します。
STRLEN utf8_length(const U8* s, const U8 *e)長さ len の文字列 s を UTF-8 からネイティブなバイトエンコーディングに 変換します。 bytes_to_utf8 と違って、これは元の文字列を上書きし、新しい長さで len を 更新します。 失敗時にはゼロを返し、len に -1 をセットします。
文字列のコピーが必要なら、bytes_from_utf8 を参照してください。
注意: この関数は実験的で、予告なしに変更あるいは削除されるかもしれません。
U8* utf8_to_bytes(U8 *s, STRLEN *len)UTF-8 エンコーディングされていると仮定されている文字列 s の最初の文字の ネイティブな符号位置を返します; retlen にはその文字のバイト数が セットされます。
s が整形された UTF-8 文字を指していない場合、ゼロが返され、もし可能なら retlen は -1 がセットされます。
UV utf8_to_uvchr(const U8 *s, STRLEN *retlen)UTF-8 エンコーディングされていると仮定されている文字列 s の最初の文字の Unicode 符号位置を返します; retlen にはその文字のバイト数が セットされます。
この関数は、返された UV が Unicode 意味論テーブル (つまり swash) への インデックスとして考えられる場合にのみ使われるべきです。
s が整形された UTF-8 文字を指していない場合、ゼロが返され、もし可能なら retlen は -1 がセットされます。
UV utf8_to_uvuni(const U8 *s, STRLEN *retlen)ネイティブ符号位置 uv の UTF-8 表現を文字列 d の末尾に追加します; d は少なくとも UTF8_MAXBYTES+1 バイトの空きが必要です。 返り値は新しい文字の末尾の次のバイトへのポインタです。 言い換えると:
d = uvchr_to_utf8(d, uv);が、ネイティブな文字を認識した形で以下のようなことをするときの推奨する 方法です:
*(d++) = uv;
U8* uvchr_to_utf8(U8 *d, UV uv)Unicode 符号位置 uv の UTF-8 表現を文字列 d の末尾に追加します; d は少なくとも UTF8_MAXBYTES+1 バイトの空きが必要です。 返り値は新しい文字の末尾の次のバイトへのポインタです。 言い換えると:
d = uvuni_to_utf8_flags(d, uv, flags);または、ほとんどの場合では、
d = uvuni_to_utf8(d, uv);(これは以下と等価です)
d = uvuni_to_utf8_flags(d, uv, 0);というのものが、以下のようなものの Unicode を考慮に入れた方法として 推奨されます。
*(d++) = uv;
U8* uvuni_to_utf8_flags(U8 *d, UV uv, UV flags)xsubpp および xsubpp 内部関数で作成された変数ST, XSprePUSH, XSRETURN マクロによって使われるスタックベース オフセットを示すために xsubpp によってセットアップされる変数。 dMARK マクロは MARK 変数をセットアップする前に 呼び出されなければなりません。
I32 axxsubpp によってセットアップされる、C++ の XS コンストラクターに 対するクラス名を表わす変数です。 これは常に char* です。 THIS を参照してください。
char* CLASSax 変数をセットアップします。 これは普通 dXSARGS を呼び出すことで xsubpp によって自動的に 扱われます。
dAX;ax 変数とスタックマーカー変数 mark をセットアップします。 これは普通 dXSARGS を呼び出すことで xsubpp によって自動的に 扱われます。
dAXMARK;items 変数をセットアップします。 これは普通 dXSARGS を呼び出すことで xsubpp によって自動的に 扱われます。
dITEMS;UNDERBAR を使いたい XSUB のために padoff_du 変数をセットアップします。
dUNDERBAR;XSUB のために、スタックポインタとマークポインタをセットアップし、 dSP と dMARK を呼び出します。 dAX と dITEMS を呼び出すことで変数 ax と items を セットアップします。 これは通常、xsubpp によって自動的に扱われます。
dXSARGS;エイリアスを持つ XSUB のために変数 ix をセットアップします。 これは通常、xsubpp によって自動的に扱われます。
dXSI32;xsubpp によりセットアップされ、スタックにあるアイテムの数を表わす 変数です。 "Variable-length Parameter Lists" in perlxs を参照してください。
I32 itemsxsubpp によりセットアップされ、それを起動するのに使われた XSUB の エイリアスを表わす変数です。 "The ALIAS: Keyword" in perlxs を参照してください。
I32 ixPerl サブルーチンのように XSUB をフックするために xsubpp が使います。 サブルーチンに対して Perl のプロトタイプを追加します。
xsubpp によってセットアップされ、XSUB の戻り値を保持する変数です。 これは、常に XSUB にとって正しい型になります。 "The RETVAL Variable" in perlxs を参照してください。
(whatever) RETVALXSUB のスタック上にある要素にアクセスするために使われます。
SV* ST(int ix)C++ の XSUB におけるオブジェクトを指定する、xsubpp によって設定される 変数です。 これは常に C++ オブジェクトとして適切な型です。 CLASS および "Using XS With C++" in perlxs を参照してください。
(whatever) THIS$_ 変数に対応する SV*。 たとえスコープ内にレキシカルな $_ があっても動作します。
XSUB とその C のパラメーターリストを宣言するためのマクロです。 これは xsubpp によって扱われます。
XS モジュールに対するバージョン識別子。 これは通常、ExtUtils::MakeMaker によって自動的に使われます。 XS_VERSION_BOOTCHECK を参照してください。
PM モジュールのバージョン変数と、XS モジュールの XS_VERSION 変数とが マッチするかを検査するためのマクロです。 これは通常、xsubpp によって自動的に扱われます。 "The VERSIONCHECK: Keyword" in perlxs を参照してください。
XS_VERSION_BOOTCHECK;Perl の die 関数に対する XSUB 作成者のためのインターフェースです。 この関数は C の関数 printf と同じように呼び出します。 croak の呼び出しは制御を直ちに Perl に返し、通常の C の実行順序を 回避します。 warn を参照してください。
例外オブジェクトを投げたいなら、オブジェクトを $@ に代入してから、 croak() に NULL を渡します:
errsv = get_sv("@", GV_ADD);
sv_setsv(errsv, exception_object);
croak(NULL);
void croak(const char* pat, ...)これは XSUB 作成者のための、Perl の warn 関数に対するインターフェースです。 この関数は C の関数 printf と同じように呼び出します。 croak() を参照してください。
void warn(const char* pat, ...)以下の関数は現在のところ文書化されていません:
1997 年 5 月まで、このドキュメントは Jeff Okamoto <okamoto@corp.hp.com> によって管理されていました。 今では Perl 自身の一部として管理されています。
Dean Roehrich, Malcolm Beattie, Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer, Stephen McCamant, Gurusamy Sarathy から多くの助力と提案を受けました。
元の API 一覧は Dean Roehrich <roehrich@cray.com> によるものです。
Benjamin Stuhl によって、ソースのコメントから自動生成するように 更新されました。