X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=dbefd85ee438c7de358949b019c896efab880b38;hb=2decb4fb82e001e3c9671c57b61232c651a9c22c;hp=9ee2b5f1fa1c8a936b1a3562fa25c3c5654a5580;hpb=1d7c184104c076988718a01b77c8706aae05b092;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index 9ee2b5f..dbefd85 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -925,35 +925,55 @@ See also L, L, L. =item delete EXPR -Deletes the specified key(s) and their associated values from a hash. -For each key, returns the deleted value associated with that key, or -the undefined value if there was no such key. Deleting from C<$ENV{}> -modifies the environment. Deleting from a hash tied to a DBM file -deletes the entry from the DBM file. (But deleting from a Cd hash -doesn't necessarily return anything.) +Given an expression that specifies a hash element, array element, hash slice, +or array slice, deletes the specified element(s) from the hash or array. +If the array elements happen to be at the end of the array, the size +of the array will shrink by that number of elements. -The following deletes all the values of a hash: +Returns each element so deleted or the undefined value if there was no such +element. Deleting from C<$ENV{}> modifies the environment. Deleting from +a hash tied to a DBM file deletes the entry from the DBM file. Deleting +from a Cd hash or array may not necessarily return anything. + +Deleting an array element effectively returns that position of the array +to its initial, uninitialized state. Subsequently testing for the same +element with exists() will return false. See L. + +The following (inefficiently) deletes all the values of %HASH and @ARRAY: foreach $key (keys %HASH) { delete $HASH{$key}; } -And so does this: + foreach $index (0 .. $#ARRAY) { + delete $ARRAY[$index]; + } + +And so do these: - delete @HASH{keys %HASH} + delete @HASH{keys %HASH}; + + delete @ARRAY[0 .. $#ARRAY]; But both of these are slower than just assigning the empty list -or undefining it: +or undefining %HASH or @ARRAY: + + %HASH = (); # completely empty %HASH + undef %HASH; # forget %HASH ever existed - %hash = (); # completely empty %hash - undef %hash; # forget %hash every existed + @ARRAY = (); # completely empty @ARRAY + undef @ARRAY; # forget @ARRAY ever existed Note that the EXPR can be arbitrarily complicated as long as the final -operation is a hash element lookup or hash slice: +operation is a hash element, array element, hash slice, or array slice +lookup: delete $ref->[$x][$y]{$key}; delete @{$ref->[$x][$y]}{$key1, $key2, @morekeys}; + delete $ref->[$x][$y][$index]; + delete @{$ref->[$x][$y]}[$index1, $index2, @moreindices]; + =item die LIST Outside an C, prints the value of LIST to C and @@ -1172,13 +1192,17 @@ interactive context.) Do not read from a terminal file (or call C on it) after end-of-file is reached. File types such as terminals may lose the end-of-file condition if you do. -An C without an argument uses the last file read as argument. -Using C with empty parentheses is very different. It indicates -the pseudo file formed of the files listed on the command line, -i.e., C is reasonable to use inside a CE)> -loop to detect the end of only the last file. Use C or -C without the parentheses to test I file in a while -(EE) loop. Examples: +An C without an argument uses the last file read. Using C +with empty parentheses is very different. It refers to the pseudo file +formed from the files listed on the command line and accessed via the +CE> operator. Since CE> isn't explicitly opened, +as a normal filehandle is, an C before CE> has been +used will cause C<@ARGV> to be examined to determine if input is +available. + +In a CE)> loop, C or C can be used to +detect the end of each file, C will only detect the end of the +last file. Examples: # reset line numbering on each input file while (<>) { @@ -1382,27 +1406,46 @@ any C methods in your objects. =item exists EXPR -Returns true if the specified hash key exists in its hash, even -if the corresponding value is undefined. +Given an expression that specifies a hash element or array element, +returns true if the specified element in the hash or array has ever +been initialized, even if the corresponding value is undefined. The +element is not autovivified if it doesn't exist. - print "Exists\n" if exists $array{$key}; - print "Defined\n" if defined $array{$key}; - print "True\n" if $array{$key}; + print "Exists\n" if exists $hash{$key}; + print "Defined\n" if defined $hash{$key}; + print "True\n" if $hash{$key}; -A hash element can be true only if it's defined, and defined if + print "Exists\n" if exists $array[$index]; + print "Defined\n" if defined $array[$index]; + print "True\n" if $array[$index]; + +A hash or array element can be true only if it's defined, and defined if it exists, but the reverse doesn't necessarily hold true. +Given an expression that specifies the name of a subroutine, +returns true if the specified subroutine has ever been declared, even +if it is undefined. Mentioning a subroutine name for exists or defined +does not count as declaring it. + + print "Exists\n" if exists &subroutine; + print "Defined\n" if defined &subroutine; + Note that the EXPR can be arbitrarily complicated as long as the final -operation is a hash key lookup: +operation is a hash or array key lookup or subroutine name: if (exists $ref->{A}->{B}->{$key}) { } if (exists $hash{A}{B}{$key}) { } -Although the last element will not spring into existence just because -its existence was tested, intervening ones will. Thus C<$ref-E{"A"}> -and C<$ref-E{"A"}-E{"B"}> will spring into existence due to the -existence test for a $key element. This happens anywhere the arrow -operator is used, including even + if (exists $ref->{A}->{B}->[$ix]) { } + if (exists $hash{A}{B}[$ix]) { } + + if (exists &{$ref->{A}{B}{$key}}) { } + +Although the deepest nested array or hash will not spring into existence +just because its existence was tested, any intervening ones will. +Thus C<$ref-E{"A"}> and C<$ref-E{"A"}-E{"B"}> will spring +into existence due to the existence test for the $key element above. +This happens anywhere the arrow operator is used, including even: undef $ref; if (exists $ref->{"Some key"}) { } @@ -1415,6 +1458,12 @@ release. See L for specifics on how exists() acts when used on a pseudo-hash. +Use of a subroutine call, rather than a subroutine name, as an argument +to exists() is an error. + + exists ⊂ # OK + exists &sub(); # Error + =item exit EXPR Evaluates EXPR and exits immediately with that value. Example: @@ -1884,6 +1933,14 @@ I simply the last two digits of the year. If you assume it is, then you create non-Y2K-compliant programs--and you wouldn't want to do that, would you? +The proper way to get a complete 4-digit year is simply: + + $year += 1900; + +And to get the last two digits of the year (e.g., '01' in 2001) do: + + $year = sprintf("%02d", $year % 100); + If EXPR is omitted, does C. In scalar context, returns the ctime(3) value: @@ -2239,6 +2296,14 @@ and I simply the last two digits of the year. If you assume it is, then you create non-Y2K-compliant programs--and you wouldn't want to do that, would you? +The proper way to get a complete 4-digit year is simply: + + $year += 1900; + +And to get the last two digits of the year (e.g., '01' in 2001) do: + + $year = sprintf("%02d", $year % 100); + If EXPR is omitted, uses the current time (C). In scalar context, returns the ctime(3) value: @@ -2739,6 +2804,34 @@ declared global variable without qualifying it with a package name. (But only within the lexical scope of the C declaration. In this it differs from "use vars", which is package scoped.) +An C declaration declares a global variable that will be visible +across its entire lexical scope, even across package boundaries. The +package in which the variable is entered is determined at the point +of the declaration, not at the point of use. This means the following +behavior holds: + + package Foo; + our $bar; # declares $Foo::bar for rest of lexical scope + $bar = 20; + + package Bar; + print $bar; # prints 20 + +Multiple C declarations in the same lexical scope are allowed +if they are in different packages. If they happened to be in the same +package, Perl will emit warnings if you have asked for them. + + use warnings; + package Foo; + our $bar; # declares $Foo::bar for rest of lexical scope + $bar = 20; + + package Bar; + our $bar = 30; # declares $Bar::bar for rest of lexical scope + print $bar; # prints 30 + + our $bar; # emits warning + =item pack TEMPLATE,LIST Takes a LIST of values and converts it into a string using the rules @@ -4370,9 +4463,9 @@ meaning of the fields: 5 gid numeric group ID of file's owner 6 rdev the device identifier (special files only) 7 size total size of file, in bytes - 8 atime last access time since the epoch - 9 mtime last modify time since the epoch - 10 ctime inode change time (NOT creation time!) since the epoch + 8 atime last access time in seconds since the epoch + 9 mtime last modify time in seconds since the epoch + 10 ctime inode change time (NOT creation time!) in seconds since the epoch 11 blksize preferred block size for file system I/O 12 blocks actual number of blocks allocated