diff options
| -rw-r--r-- | gnu/usr.bin/perl/pod/perlclib.pod | 206 |
1 files changed, 83 insertions, 123 deletions
diff --git a/gnu/usr.bin/perl/pod/perlclib.pod b/gnu/usr.bin/perl/pod/perlclib.pod index 0cdee249119..a0f4a80eecd 100644 --- a/gnu/usr.bin/perl/pod/perlclib.pod +++ b/gnu/usr.bin/perl/pod/perlclib.pod @@ -48,76 +48,71 @@ types. Don't forget that with the new PerlIO layered I/O abstraction C<FILE*> types may not even be available. See also the C<perlapio> documentation for more information about the following functions: - Instead Of: Use: + Instead Of: Use: - stdin PerlIO_stdin() - stdout PerlIO_stdout() - stderr PerlIO_stderr() + 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) + fopen(fn, mode) PerlIO_open(fn, mode) + freopen(fn, mode, stream) PerlIO_reopen(fn, mode, perlio) (Deprecated) + fflush(stream) PerlIO_flush(perlio) + fclose(stream) PerlIO_close(perlio) =head2 File Input and Output - Instead Of: Use: + Instead Of: Use: - fprintf(stream, fmt, ...) PerlIO_printf(perlio, fmt, ...) + 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) + [f]getc(stream) PerlIO_getc(perlio) + [f]putc(stream, n) PerlIO_putc(perlio, n) + ungetc(n, stream) PerlIO_ungetc(perlio, n) Note that the PerlIO equivalents of C<fread> and C<fwrite> are slightly different from their C library counterparts: - fread(p, size, n, stream) PerlIO_read(perlio, buf, numbytes) - fwrite(p, size, n, stream) PerlIO_write(perlio, buf, numbytes) + 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) + fputs(s, stream) PerlIO_puts(perlio, s) There is no equivalent to C<fgets>; one should use C<sv_gets> instead: - fgets(s, n, stream) sv_gets(sv, perlio, append) + fgets(s, n, stream) sv_gets(sv, perlio, append) =head2 File Positioning - Instead Of: Use: + Instead Of: Use: - feof(stream) PerlIO_eof(perlio) - fseek(stream, n, whence) PerlIO_seek(perlio, n, whence) - rewind(stream) PerlIO_rewind(perlio) + 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) + fgetpos(stream, p) PerlIO_getpos(perlio, sv) + fsetpos(stream, p) PerlIO_setpos(perlio, sv) - ferror(stream) PerlIO_error(perlio) - clearerr(stream) PerlIO_clearerr(perlio) + ferror(stream) PerlIO_error(perlio) + clearerr(stream) PerlIO_clearerr(perlio) =head2 Memory Management and String Handling - Instead Of: Use: + 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) + t* p = malloc(n) New(id, p, n, t) + t* p = calloc(n, s) Newz(id, 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/*(struct foo *) StructCopy(src, dst, t) + free(p) Safefree(p) - strdup(p) savepv(p) - strndup(p, n) savepvn(p, n) (Hey, strndup doesn't - exist!) + 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) + 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) Notice the different order of arguments to C<Copy> and C<Move> than used in C<memcpy> and C<memmove>. @@ -125,88 +120,53 @@ in C<memcpy> and C<memmove>. Most of the time, though, you'll want to be dealing with SVs internally instead of raw C<char *> strings: - 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, ...) + 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, ...) -Note also the existence of C<sv_catpvf> and C<sv_vcatpvfn>, combining +Note also the existence of C<sv_catpvf> and C<sv_catpvfn>, combining concatenation with formatting. -Sometimes instead of zeroing the allocated heap by using Newxz() you -should consider "poisoning" the data. This means writing a bit -pattern into it that should be illegal as pointers (and floating point -numbers), and also hopefully surprising enough as integers, so that -any code attempting to use the data without forethought will break -sooner rather than later. Poisoning can be done using the Poison() -macros, which have similar arguments to Zero(): - - 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) - =head2 Character Class Tests -There are several types of character class tests that Perl implements. -The only ones described here are those that directly correspond to C -library functions that operate on 8-bit characters, but there are -equivalents that operate on wide characters, and UTF-8 encoded strings. -All are more fully described in L<perlapi/Character classes> and -L<perlapi/Character case changing>. - -The C library routines listed in the table below return values based on -the current locale. Use the entries in the final column for that -functionality. The other two columns always assume a POSIX (or C) -locale. The entries in the ASCII column are only meaningful for ASCII -inputs, returning FALSE for anything else. Use these only when you -B<know> that is what you want. The entries in the Latin1 column assume -that the non-ASCII 8-bit characters are as Unicode defines, them, the -same as ISO-8859-1, often called Latin 1. - - Instead Of: Use for ASCII: Use for Latin1: Use for locale: - - 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) toLOWER_LC(c) - toupper(c) toUPPER(c) toUPPER_LC(c) - -To emphasize that you are operating only on ASCII characters, you can -append C<_A> to each of the macros in the ASCII column: C<isALPHA_A>, -C<isDIGIT_A>, and so on. - -(There is no entry in the Latin1 column for C<isascii> even though there -is an C<isASCII_L1>, which is identical to C<isASCII>; the -latter name is clearer. There is no entry in the Latin1 column for -C<toupper> because the result can be non-Latin1. You have to use -C<toUPPER_uni>, as described in L<perlapi/Character case changing>.) +There are two types of character class tests that Perl implements: one +type deals in C<char>s and are thus B<not> Unicode aware (and hence +deprecated unless you B<know> you should use them) and the other type +deal in C<UV>s and know about Unicode properties. In the following +table, C<c> is a C<char>, and C<u> is a Unicode codepoint. + + Instead Of: Use: But better use: + + isalnum(c) isALNUM(c) isALNUM_uni(u) + isalpha(c) isALPHA(c) isALPHA_uni(u) + iscntrl(c) isCNTRL(c) isCNTRL_uni(u) + isdigit(c) isDIGIT(c) isDIGIT_uni(u) + isgraph(c) isGRAPH(c) isGRAPH_uni(u) + islower(c) isLOWER(c) isLOWER_uni(u) + isprint(c) isPRINT(c) isPRINT_uni(u) + ispunct(c) isPUNCT(c) isPUNCT_uni(u) + isspace(c) isSPACE(c) isSPACE_uni(u) + isupper(c) isUPPER(c) isUPPER_uni(u) + isxdigit(c) isXDIGIT(c) isXDIGIT_uni(u) + + tolower(c) toLOWER(c) toLOWER_uni(u) + toupper(c) toUPPER(c) toUPPER_uni(u) =head2 F<stdlib.h> functions - Instead Of: Use: + Instead Of: Use: - atof(s) Atof(s) - atol(s) Atol(s) - strtod(s, &p) Nothing. Just don't use it. - strtol(s, &p, n) Strtol(s, &p, n) - strtoul(s, &p, n) Strtoul(s, &p, n) + atof(s) Atof(s) + atol(s) Atol(s) + strtod(s, *p) Nothing. Just don't use it. + strtol(s, *p, n) Strtol(s, *p, n) + strtoul(s, *p, n) Strtoul(s, *p, n) -Notice also the C<grok_bin>, C<grok_hex>, and C<grok_oct> functions in -F<numeric.c> for converting strings representing numbers in the respective +Notice also the C<scan_bin>, C<scan_hex>, and C<scan_oct> functions in +F<util.c> for converting strings representing numbers in the respective bases into C<NV>s. In theory C<Strtol> and C<Strtoul> may not be defined if the machine perl is @@ -214,15 +174,15 @@ built on doesn't actually have strtol and strtoul. But as those 2 functions are part of the 1989 ANSI C spec we suspect you'll find them everywhere by now. - int rand() double Drand01() - srand(n) { seedDrand01((Rand_seed_t)n); - PL_srand_called = TRUE; } + 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 + 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_putenv(s, val) + getenv(s) PerlEnv_getenv(s) + setenv(s, val) my_putenv(s, val) =head2 Miscellaneous functions @@ -233,5 +193,5 @@ For C<signal>/C<sigaction>, use C<rsignal(signo, handler)>. =head1 SEE ALSO -L<perlapi>, L<perlapio>, L<perlguts> +C<perlapi>, C<perlapio>, C<perlguts> |