X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=db90b86879c33faf931691ea0e06b949f66c1b3a;hb=91331b4fc62e0ad9094741aa6359fb89e2fc5554;hp=25269d4fa74733bf1cf8fbf1f0c992d71b3a9838;hpb=bd80725ccf9c8f2dfa64206c02cfc79e98f071be;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index 25269d4..db90b86 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -612,6 +612,8 @@ If VARIABLE is omitted, it chomps C<$_>. Example: # ... } +If VARIABLE is a hash, it chomps the hash's values, but not its keys. + You can actually chomp anything that's an lvalue, including an assignment: chomp($cwd = `pwd`); @@ -638,6 +640,8 @@ Example: #... } +If VARIABLE is a hash, it chops the hash's values, but not its keys. + You can actually chop anything that's an lvalue, including an assignment: chop($cwd = `pwd`); @@ -688,8 +692,11 @@ On POSIX systems, you can detect this condition this way: Returns the character represented by that NUMBER in the character set. For example, C is C<"A"> in either ASCII or Unicode, and -chr(0x263a) is a Unicode smiley face (but only within the scope of -a C). For the reverse, use L. +chr(0x263a) is a Unicode smiley face. Within the scope of C, +characters higher than 127 are encoded in Unicode; if you don't want +this, temporarily C or use C + +For the reverse, use L. See L for more about Unicode. If NUMBER is omitted, uses C<$_>. @@ -792,6 +799,8 @@ to check the condition at the top of the loop. =item cos EXPR +=item cos + Returns the cosine of EXPR (expressed in radians). If EXPR is omitted, takes cosine of C<$_>. @@ -2078,9 +2087,9 @@ or equivalently, @foo = grep {!/^#/} @bar; # weed out comments -Note that, because C<$_> is a reference into the list value, it can -be used to modify the elements of the array. While this is useful and -supported, it can cause bizarre results if the LIST is not a named array. +Note that C<$_> is an alias to the list value, so it can be used to +modify the elements of the LIST. While this is useful and supported, +it can cause bizarre results if the elements of LIST are not variables. Similarly, grep returns aliases into the original list, much as a for loop's index variable aliases the list elements. That is, modifying an element of a list returned by grep (for example, in a C, C @@ -2421,8 +2430,6 @@ divided by the natural log of N. For example: See also L for the inverse operation. -=item lstat FILEHANDLE - =item lstat EXPR =item lstat @@ -2462,9 +2469,9 @@ is just a funny way to write $hash{getkey($_)} = $_; } -Note that, because C<$_> is a reference into the list value, it can -be used to modify the elements of the array. While this is useful and -supported, it can cause bizarre results if the LIST is not a named array. +Note that C<$_> is an alias to the list value, so it can be used to +modify the elements of the LIST. While this is useful and supported, +it can cause bizarre results if the elements of LIST are not variables. Using a regular C loop for this purpose would be clearer in most cases. See also L for an array composed of those items of the original list for which the BLOCK or EXPR evaluates to true. @@ -2495,13 +2502,13 @@ first to get the correct constant definitions. If CMD is C, then ARG must be a variable which will hold the returned C structure. Returns like C: the undefined value for error, C<"0 but true"> for zero, or the actual return value otherwise. See also -C and C documentation. +L, C, and C documentation. =item msgget KEY,FLAGS Calls the System V IPC function msgget(2). Returns the message queue -id, or the undefined value if there is an error. See also C -and C documentation. +id, or the undefined value if there is an error. See also +L and C and C documentation. =item msgrcv ID,VAR,SIZE,TYPE,FLAGS @@ -2511,7 +2518,8 @@ SIZE. Note that when a message is received, the message type as a native long integer will be the first thing in VAR, followed by the actual message. This packing may be opened with C. Taints the variable. Returns true if successful, or false if there is -an error. See also C and C documentation. +an error. See also L, C, and +C documentation. =item msgsnd ID,MSG,FLAGS @@ -2815,7 +2823,7 @@ otherwise it's necessary to protect any leading and trailing whitespace: $file =~ s#^(\s)#./$1#; open(FOO, "< $file\0"); -(this may not work on some bizzare filesystems). One should +(this may not work on some bizarre filesystems). One should conscientiously choose between the I and 3-arguments form of open(): @@ -3149,13 +3157,13 @@ because they obey the native byteorder and endianness. For example a 4-byte integer 0x12345678 (305419896 decimal) be ordered natively (arranged in and handled by the CPU registers) into bytes as - 0x12 0x34 0x56 0x78 # little-endian - 0x78 0x56 0x34 0x12 # big-endian + 0x12 0x34 0x56 0x78 # big-endian + 0x78 0x56 0x34 0x12 # little-endian -Basically, the Intel, Alpha, and VAX CPUs are little-endian, while -everybody else, for example Motorola m68k/88k, PPC, Sparc, HP PA, -Power, and Cray are big-endian. MIPS can be either: Digital used it -in little-endian mode; SGI uses it in big-endian mode. +Basically, the Intel and VAX CPUs are little-endian, while everybody +else, for example Motorola m68k/88k, PPC, Sparc, HP PA, Power, and +Cray are big-endian. Alpha and MIPS can be either: Digital/Compaq +used/uses them in little-endian mode; SGI/Cray uses them in big-endian mode. The names `big-endian' and `little-endian' are comic references to the classic "Gulliver's Travels" (via the paper "On Holy Wars and a @@ -3281,10 +3289,10 @@ Examples: The same template may generally also be used in unpack(). -=item package - =item package NAMESPACE +=item package + Declares the compilation unit as being in the given namespace. The scope of the package declaration is from the declaration itself through the end of the enclosing block, file, or eval (the same as the C operator). @@ -3342,7 +3350,7 @@ array in subroutines, just like C. =item pos Returns the offset of where the last C search left off for the variable -is in question (C<$_> is used when the variable is not specified). May be +in question (C<$_> is used when the variable is not specified). May be modified to change that offset. Such modification will also influence the C<\G> zero-width assertion in regular expressions. See L and L. @@ -3943,13 +3951,15 @@ semid_ds structure or semaphore value array. Returns like C: the undefined value for error, "C<0 but true>" for zero, or the actual return value otherwise. The ARG must consist of a vector of native short integers, which may be created with C. -See also C and C documentation. +See also L, C, C +documentation. =item semget KEY,NSEMS,FLAGS Calls the System V IPC function semget. Returns the semaphore id, or -the undefined value if there is an error. See also C and -C documentation. +the undefined value if there is an error. See also +L, C, C +documentation. =item semop KEY,OPSTRING @@ -3964,8 +3974,9 @@ following code waits on semaphore $semnum of semaphore id $semid: $semop = pack("sss", $semnum, -1, 0); die "Semaphore trouble: $!\n" unless semop($semid, $semop); -To signal the semaphore, replace C<-1> with C<1>. See also C -and C documentation. +To signal the semaphore, replace C<-1> with C<1>. See also +L, C, and C +documentation. =item send SOCKET,MSG,FLAGS,TO @@ -4011,7 +4022,7 @@ C<@ARGV> array at file scopes or within the lexical scopes established by the C, C, C, C, and C constructs. -See also C, C, and C. C and C do the +See also C, C, and C. C and C do the same thing to the left end of an array that C and C do to the right end. @@ -4025,13 +4036,13 @@ first to get the correct constant definitions. If CMD is C, then ARG must be a variable which will hold the returned C structure. Returns like ioctl: the undefined value for error, "C<0> but true" for zero, or the actual return value otherwise. -See also C documentation. +See also L and C documentation. =item shmget KEY,SIZE,FLAGS Calls the System V IPC function shmget. Returns the shared memory segment id, or the undefined value if there is an error. -See also C documentation. +See also L and C documentation. =item shmread ID,VAR,POS,SIZE @@ -4043,8 +4054,8 @@ detaching from it. When reading, VAR must be a variable that will hold the data read. When writing, if STRING is too long, only SIZE bytes are used; if STRING is too short, nulls are written to fill out SIZE bytes. Return true if successful, or false if there is an error. -shmread() taints the variable. See also C documentation and -the C module from CPAN. +shmread() taints the variable. See also L, +C documentation, and the C module from CPAN. =item shutdown SOCKET,HOW @@ -4094,7 +4105,7 @@ C interface to access setitimer(2) if your system supports it, or else see L above. The Time::HiRes module from CPAN may also help. -See also the POSIX module's C function. +See also the POSIX module's C function. =item socket SOCKET,DOMAIN,TYPE,PROTOCOL @@ -4246,15 +4257,12 @@ Examples: If you're using strict, you I declare $a and $b as lexicals. They are package globals. That means -if you're in the C
package, it's - - @articles = sort {$main::b <=> $main::a} @files; - -or just - - @articles = sort {$::b <=> $::a} @files; - -but if you're in the C package, it's +if you're in the C
package and type + + @articles = sort {$b <=> $a} @files; + +then C<$a> and C<$b> are C<$main::a> and C<$main::b> (or C<$::a> and C<$::b>), +but if you're in the C package, it's the same as typing @articles = sort {$FooPack::b <=> $FooPack::a} @files; @@ -4374,6 +4382,9 @@ A C on C is like a C except that any leading whitespace produces a null first field. A C with no arguments really does a C internally. +A PATTERN of C is treated as if it were C, since it isn't +much use otherwise. + Example: open(PASSWD, '/etc/passwd'); @@ -4407,6 +4418,12 @@ numbers, and even then only the standard modifiers are allowed). As a result, any non-standard extensions in your local C are not available from Perl. +Unlike C, C does not do what you probably mean when you +pass it an array as your first argument. The array is given scalar context, +and instead of using the 0th element of the array as the format, Perl will +use the count of elements in the array as the format, which is almost never +useful. + Perl's C permits the following universally-known conversions: %% a percent sign @@ -4439,6 +4456,12 @@ permits these unnecessary but widely-supported conversions: %O a synonym for %lo %F a synonym for %f +Note that the number of exponent digits in the scientific notation by +C<%e>, C<%E>, C<%g> and C<%G> for numbers with the modulus of the +exponent less than 100 is system-dependent: it may be three or less +(zero-padded as necessary). In other words, 1.23 times ten to the +99th may be either "1.23e99" or "1.23e099". + Perl permits the following universally-known flags between the C<%> and the conversion letter: @@ -5068,6 +5091,7 @@ A class implementing a hash should have the following methods: FIRSTKEY this NEXTKEY this, lastkey DESTROY this + UNTIE this A class implementing an ordinary array should have the following methods: @@ -5084,6 +5108,7 @@ A class implementing an ordinary array should have the following methods: SPLICE this, offset, length, LIST EXTEND this, count DESTROY this + UNTIE this A class implementing a file handle should have the following methods: @@ -5094,8 +5119,15 @@ A class implementing a file handle should have the following methods: WRITE this, scalar, length, offset PRINT this, LIST PRINTF this, format, LIST + BINMODE this + EOF this + FILENO this + SEEK this, position, whence + TELL this + OPEN this, mode, LIST CLOSE this DESTROY this + UNTIE this A class implementing a scalar should have the following methods: @@ -5103,6 +5135,7 @@ A class implementing a scalar should have the following methods: FETCH this, STORE this, value DESTROY this + UNTIE this Not all methods indicated above need be implemented. See L, L, L, L, and L. @@ -5371,7 +5404,8 @@ derive their C method via inheritance from the C class that is defined in the C module. See L. If no C method can be found then the call is skipped. -If you don't want your namespace altered, explicitly supply an empty list: +If you do not want to call the package's C method (for instance, +to stop your namespace from being altered), explicitly supply the empty list: use Module (); @@ -5392,8 +5426,9 @@ called). Note that there is no comma after VERSION! Because this is a wide-open interface, pragmas (compiler directives) are also implemented this way. Currently implemented pragmas are: - use integer; + use constant; use diagnostics; + use integer; use sigtrap qw(SEGV BUS); use strict qw(subs vars refs); use subs qw(afunc blurfl); @@ -5413,7 +5448,9 @@ by C, i.e., it calls C instead of C. If no C method can be found the call fails with a fatal error. -See L for a list of standard modules and pragmas. +See L for a list of standard modules and pragmas. See L +for the C<-M> and C<-m> command-line options to perl that give C +functionality from the command-line. =item utime LIST @@ -5459,7 +5496,7 @@ If BITS is 8, "elements" coincide with bytes of the input string. If BITS is 16 or more, bytes of the input string are grouped into chunks of size BITS/8, and each group is converted to a number as with -pack()/unpack() with big-endian formats C/C (and analoguously +pack()/unpack() with big-endian formats C/C (and analogously for BITS==64). See L<"pack"> for details. If bits is 4 or less, the string is broken into bytes, then the bits @@ -5474,9 +5511,18 @@ to give the expression the correct precedence as in vec($image, $max_x * $x + $y, 8) = 3; -If the selected element is off the end of the string, the value 0 is -returned. If an element off the end of the string is written to, -Perl will first extend the string with sufficiently many zero bytes. +If the selected element is outside the string, the value 0 is returned. +If an element off the end of the string is written to, Perl will first +extend the string with sufficiently many zero bytes. It is an error +to try to write off the beginning of the string (i.e. negative OFFSET). + +The string should not contain any character with the value > 255 (which +can only happen if you're using UTF8 encoding). If it does, it will be +treated as something which is not UTF8 encoded. When the C was +assigned to, other parts of your program will also no longer consider the +string to be UTF8 encoded. In other words, if you do have such characters +in your string, vec() will operate on the actual byte string, and not the +conceptual character string. Strings created with C can also be manipulated with the logical operators C<|>, C<&>, C<^>, and C<~>. These operators will assume a bit