X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=1e3151a423c62667cfee97ef53c21a7512097760;hb=47223a367d95f4dc59ba3d4c168a2648263556ab;hp=4e67506e267b98aeacccb6df4e0b95a0b2bc879b;hpb=ee8c7f5465f003860e2347a2946abacac39bd9b9;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index 4e67506..1e3151a 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -1265,11 +1265,11 @@ there was an error. In the first form, the return value of EXPR is parsed and executed as if it were a little Perl program. The value of the expression (which is itself determined within scalar context) is first parsed, and if there weren't any -errors, executed in the context of the current Perl program, so that any -variable settings or subroutine and format definitions remain afterwards. -Note that the value is parsed every time the eval executes. If EXPR is -omitted, evaluates C<$_>. This form is typically used to delay parsing -and subsequent execution of the text of EXPR until run time. +errors, executed in the lexical context of the current Perl program, so +that any variable settings or subroutine and format definitions remain +afterwards. Note that the value is parsed every time the eval executes. +If EXPR is omitted, evaluates C<$_>. This form is typically used to +delay parsing and subsequent execution of the text of EXPR until run time. In the second form, the code within the BLOCK is parsed only once--at the same time the code surrounding the eval itself was parsed--and executed @@ -2078,9 +2078,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 @@ -2462,9 +2462,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 +2495,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 +2511,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 @@ -3202,6 +3203,15 @@ equal $foo). =item * +If the pattern begins with a C, the resulting string will be treated +as Unicode-encoded. You can force UTF8 encoding on in a string with an +initial C, and the bytes that follow will be interpreted as Unicode +characters. If you don't want this to happen, you can begin your pattern +with C (or anything else) to force Perl not to UTF8 encode your +string, and then follow this with a C somewhere in your pattern. + +=item * + You must yourself do any alignment or padding by inserting for example enough C<'x'>es while packing. There is no way to pack() and unpack() could know where the bytes are going to or coming from. Therefore @@ -3426,7 +3436,7 @@ Generalized quotes. See L. =item quotemeta -Returns the value of EXPR with all non-alphanumeric +Returns the value of EXPR with all non-"word" characters backslashed. (That is, all characters not matching C will be preceded by a backslash in the returned string, regardless of any locale settings.) @@ -3934,13 +3944,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 @@ -3955,8 +3967,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 @@ -4002,7 +4015,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. @@ -4016,13 +4029,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 @@ -4034,8 +4047,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 @@ -4237,15 +4250,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; @@ -4304,11 +4314,9 @@ Example, assuming array lengths are passed before arrays: Splits a string into a list of strings and returns that list. By default, empty leading fields are preserved, and empty trailing ones are deleted. -If not in list context, returns the number of fields found and splits into -the C<@_> array. (In list context, you can force the split into C<@_> by -using C as the pattern delimiters, but it still returns the list -value.) The use of implicit split to C<@_> is deprecated, however, because -it clobbers your subroutine arguments. +In scalar context, returns the number of fields found and splits into +the C<@_> array. Use of split in scalar context is deprecated, however, +because it clobbers your subroutine arguments. If EXPR is omitted, splits the C<$_> string. If PATTERN is also omitted, splits on whitespace (after skipping any leading whitespace). Anything @@ -4367,6 +4375,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'); @@ -4381,9 +4392,18 @@ L, and L.) =item sprintf FORMAT, LIST -Returns a string formatted by the usual C conventions of the -C library function C. See L or L -on your system for an explanation of the general principles. +Returns a string formatted by the usual C conventions of the C +library function C. See below for more details +and see L or L on your system for an explanation of +the general principles. + +For example: + + # Format number with up to 8 leading zeroes + $result = sprintf("%08d", $number); + + # Round number to 3 digits after decimal point + $rounded = sprintf("%.3f", $number); Perl does its own C formatting--it emulates the C function C, but it doesn't use it (except for floating-point