NAME

perlclib - 標準 C ライブラリ関数の内部的な代用品

DESCRIPTION

Perl porters が注意するべき事のひとつは、perl は内部で C 標準ライブラリを あまり使わないようにしていると言うことです; 例えば、ctype.h 関数は ほとんど使われていないことに気付くでしょう。 これは、どのような操作をしようとしているかを正確に知るために、Perl は 標準ライブラリ関数を再実装したり抽象化したりしようとするからです。

これは C ライブラリに慣れていて Perl 方式で何かをしたい人々のための リファレンスカードです; より普通の C 関数の代わりに使うべき関数を示します。

規約

以下の表で:

t

は型です。

p

はポインタです。

n

は数値です。

s

は文字列です。

sv, av, hv などはそれぞれ対応する型の変数です。

ファイル操作

stdio.h 関数の代わりに、Perl 抽象層を使うべきです。 FILE* 型の代わりに、PerlIO* 型を扱う必要があります。 新しい PerlIO 層の I/O 抽象化では FILE* 型は利用できないかも知れないことを 忘れないでください。 以下の関数に関するさらなる詳細については perlapio 文書を 参照してください:

 Instead Of:                 Use:

 stdin                       PerlIO_stdin()
 stdout                      PerlIO_stdout()
 stderr                      PerlIO_stderr()

 fopen(fn, mode)             PerlIO_open(fn, mode)
 freopen(fn, mode, stream)   PerlIO_reopen(fn, mode, perlio) (Dep-
                               recated)
 fflush(stream)              PerlIO_flush(perlio)
 fclose(stream)              PerlIO_close(perlio)

ファイル入力と出力

 Instead Of:                 Use:

 fprintf(stream, fmt, ...)   PerlIO_printf(perlio, fmt, ...)

 [f]getc(stream)             PerlIO_getc(perlio)
 [f]putc(stream, n)          PerlIO_putc(perlio, n)
 ungetc(n, stream)           PerlIO_ungetc(perlio, n)

freadfwrite の PerlIO の代用品は C ライブラリの対応物とは 少し違うことに注意してください:

 fread(p, size, n, stream)   PerlIO_read(perlio, buf, numbytes)
 fwrite(p, size, n, stream)  PerlIO_write(perlio, buf, numbytes)

 fputs(s, stream)            PerlIO_puts(perlio, s)

fgets の等価物はありません; 代わりに sv_gets を使うべきです:

 fgets(s, n, stream)         sv_gets(sv, perlio, append)

ファイル位置

 Instead Of:                 Use:

 feof(stream)                PerlIO_eof(perlio)
 fseek(stream, n, whence)    PerlIO_seek(perlio, n, whence)
 rewind(stream)              PerlIO_rewind(perlio)

 fgetpos(stream, p)          PerlIO_getpos(perlio, sv)
 fsetpos(stream, p)          PerlIO_setpos(perlio, sv)

 ferror(stream)              PerlIO_error(perlio)
 clearerr(stream)            PerlIO_clearerr(perlio)

メモリ管理と文字列操作

 Instead Of:                    Use:

 t* p = malloc(n)               Newx(p, n, t)
 t* p = calloc(n, s)            Newxz(p, n, t)
 p = realloc(p, n)              Renew(p, n, t)
 memcpy(dst, src, n)            Copy(src, dst, n, t)
 memmove(dst, src, n)           Move(src, dst, n, t)
 memcpy(dst, src, sizeof(t))    StructCopy(src, dst, t)
 memset(dst, 0, n * sizeof(t))  Zero(dst, n, t)
 memzero(dst, 0)                Zero(dst, n, char)
 free(p)                        Safefree(p)

 strdup(p)                      savepv(p)
 strndup(p, n)                  savepvn(p, n) (Hey, strndup doesn't
                                               exist!)

 strstr(big, little)            instr(big, little)
 strcmp(s1, s2)                 strLE(s1, s2) / strEQ(s1, s2)
                                              / strGT(s1,s2)
 strncmp(s1, s2, n)             strnNE(s1, s2, n) / strnEQ(s1, s2, n)

 memcmp(p1, p2, n)              memNE(p1, p2, n)
 !memcmp(p1, p2, n)             memEQ(p1, p2, n)

Copy および Move の引数の順番は memcpy および memmove と異なる ことに注意してください。

しかし、大抵の場合、生の char * 文字列ではなく内部的に SV を 扱いたいでしょう:

 strlen(s)                   sv_len(sv)
 strcpy(dt, src)             sv_setpv(sv, s)
 strncpy(dt, src, n)         sv_setpvn(sv, s, n)
 strcat(dt, src)             sv_catpv(sv, s)
 strncat(dt, src)            sv_catpvn(sv, s)
 sprintf(s, fmt, ...)        sv_setpvf(sv, fmt, ...)

連結とフォーマッティングを結合した sv_catpvf および sv_vcatpvfn が あることにも注意してください。

時々、Newxz() を使って割り当てられたヒープをゼロにする代わりにデータに 「毒入れ」したいかもしれません。 これは、ポインタ(および浮動小数点数)として不正になり、できれば整数としても 十分に驚くべきビットパターンを書き込んで、考えなしにデータを使おうとする コードが早めに壊れるようにすることです。 毒入れは Zero() と似たような引数を持つ Poison() マクロで行えます:

 PoisonWith(dst, n, t, b)    scribble memory with byte b
 PoisonNew(dst, n, t)        equal to PoisonWith(dst, n, t, 0xAB)
 PoisonFree(dst, n, t)       equal to PoisonWith(dst, n, t, 0xEF)
 Poison(dst, n, t)           equal to PoisonFree(dst, n, t)

文字クラステスト

Perl が実装しているいくつか種類の文字クラステストがあります。 ここで記述しているのは 8 ビット文字を操作する C ライブライブラリに直接 対応しているもののみですが、ワイド文字、UTF-8 エンコード文字を操作する 等価物もあります。 全ては "Character classification" in perlapi"Character case changing" in perlapi でより完全に記述されています。

後述する表に挙げられている C ライブラリルーチンは現在のロケールを基にした 値を返します。 この機能のためには最後の列のエントリを使ってください。 残りの二つの列は常に POSIX (あるいは C) ロケールを仮定します。 ASCII 列のエントリは ASCII 入力でのみ意味を持ち、それ以外では FALSE を 返します。 これが望んでいるものであると 分かっている 場合にのみこれを使ってください。 Latin1 列のエントリは、非 ASCII 8 ビット文字は Unicode が定義しているように、 ISO-8859-1 (しばしば Latin 1 と呼ばれます) であると仮定します。

 元:         ASCII 用:         Latin1 用:           ロケール用:

 isalnum(c)  isALPHANUMERIC(c) isALPHANUMERIC_L1(c) isALPHANUMERIC_LC(c)
 isalpha(c)  isALPHA(c)        isALPHA_L1(c)        isALPHA_LC(u )
 isascii(c)  isASCII(c)                             isASCII_LC(c)
 isblank(c)  isBLANK(c)        isBLANK_L1(c)        isBLANK_LC(c)
 iscntrl(c)  isCNTRL(c)        isCNTRL_L1(c)        isCNTRL_LC(c)
 isdigit(c)  isDIGIT(c)        isDIGIT_L1(c)        isDIGIT_LC(c)
 isgraph(c)  isGRAPH(c)        isGRAPH_L1(c)        isGRAPH_LC(c)
 islower(c)  isLOWER(c)        isLOWER_L1(c)        isLOWER_LC(c)
 isprint(c)  isPRINT(c)        isPRINT_L1(c)        isPRINT_LC(c)
 ispunct(c)  isPUNCT(c)        isPUNCT_L1(c)        isPUNCT_LC(c)
 isspace(c)  isSPACE(c)        isSPACE_L1(c)        isSPACE_LC(c)
 isupper(c)  isUPPER(c)        isUPPER_L1(c)        isUPPER_LC(c)
 isxdigit(c) isXDIGIT(c)       isXDIGIT_L1(c)       isXDIGIT_LC(c)

 tolower(c)  toLOWER(c)        toLOWER_L1(c)
 toupper(c)  toUPPER(c)

念を押しておくと、ASCII 文字のみを操作するなら、ASCII の列のそれぞれの マクロに _A を追加したものが使えます: isALPHA_A, isDIGIT_A などです。

(isASCII と等価な isASCII_L1 というものはありますが、isascii の Latin1 の列はありません; 前者の名前の方が明確です。 toupper の Latin1 の列はありません; 結果は非 Latin1 に なるかもしれないからです。 "Character case changing" in perlapi に記述されている toUPPER_uvchr を 使う必要があります。)

stdlib.h 関数

 Instead Of:                 Use:

 atof(s)                     Atof(s)
 atoi(s)                     grok_atoUV(s, &uv, &e)
 atol(s)                     grok_atoUV(s, &uv, &e)
 strtod(s, &p)               Strtod(s, &p)
 strtol(s, &p, n)            Strtol(s, &p, b)
 strtoul(s, &p, n)           Strtoul(s, &p, b)

典型的な使用法は、キャストする前の uv の範囲チェックです:

  int i; UV uv;
  char* end_ptr = input_end;
  if (grok_atoUV(input, &uv, &end_ptr)
      && uv <= INT_MAX)
    i = (int)uv;
    ... /* continue parsing from end_ptr */
  } else {
    ... /* parse error: not a decimal integer in range 0 .. MAX_IV */
  }

それぞれの基数で数値を表現している文字列を NV に変換するための numeric.c にある grok_bin, grok_hex, grok_oct 関数にも 注目してください。 grok_atoUV() は負の入力や銭湯の空白を扱わないことに注意してください (意図的に厳密にしています)。

strtol() と strtoul() は Strtol(), Strtoul(), Atol(), Atoul() と言う形に 偽装しているかもしれないことに注意してください。 これらも避けてください。

理論的には、perl がビルドされたマシンに実際に strtol や strtoul がない 場合、StrtolStrtoul は定義されないかもしれません。 しかしこれらの 2 関数は 1989 ANSI C 使用の一部なので、今のところどこでも これらを見つけられると思われます。

 int rand()                  double Drand01()
 srand(n)                    { seedDrand01((Rand_seed_t)n);
                               PL_srand_called = TRUE; }

 exit(n)                     my_exit(n)
 system(s)                   Don't. Look at pp_system or use my_popen.

 getenv(s)                   PerlEnv_getenv(s)
 setenv(s, val)              my_setenv(s, val)

さまざまな関数

setjmp.h 関数を使おうと 思う ことすらするべきではありませんが、もし そう考えているなら、代わりに scope.hJMPENV スタックを 使ってください。

signal/sigaction については、rsignal(signo, handler) を 使ってください。

SEE ALSO

perlapi, perlapio, perlguts