diff options
Diffstat (limited to 'pod/perlfunc.pod')
| -rw-r--r-- | pod/perlfunc.pod | 132 |
1 files changed, 66 insertions, 66 deletions
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index 6825d22e7d..9d21587696 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -622,31 +622,31 @@ their own password: Of course, typing in your own password to whomever asks you for it is unwise. -=item dbmclose ASSOC_ARRAY +=item dbmclose HASH [This function has been superseded by the untie() function.] -Breaks the binding between a DBM file and an associative array. +Breaks the binding between a DBM file and a hash. -=item dbmopen ASSOC,DBNAME,MODE +=item dbmopen HASH,DBNAME,MODE [This function has been superseded by the tie() function.] -This binds a dbm(3), ndbm(3), sdbm(3), gdbm(), or Berkeley DB file to an -associative array. ASSOC is the name of the associative array. (Unlike -normal open, the first argument is I<NOT> a filehandle, even though it -looks like one). DBNAME is the name of the database (without the F<.dir> -or F<.pag> extension if any). If the database does not exist, it is -created with protection specified by MODE (as modified by the umask()). -If your system supports only the older DBM functions, you may perform only -one dbmopen() in your program. In older versions of Perl, if your system -had neither DBM nor ndbm, calling dbmopen() produced a fatal error; it now -falls back to sdbm(3). - -If you don't have write access to the DBM file, you can only read -associative array variables, not set them. If you want to test whether -you can write, either use file tests or try setting a dummy array entry -inside an eval(), which will trap the error. +This binds a dbm(3), ndbm(3), sdbm(3), gdbm(), or Berkeley DB file to a +hash. HASH is the name of the hash. (Unlike normal open, the first +argument is I<NOT> a filehandle, even though it looks like one). DBNAME +is the name of the database (without the F<.dir> or F<.pag> extension if +any). If the database does not exist, it is created with protection +specified by MODE (as modified by the umask()). If your system supports +only the older DBM functions, you may perform only one dbmopen() in your +program. In older versions of Perl, if your system had neither DBM nor +ndbm, calling dbmopen() produced a fatal error; it now falls back to +sdbm(3). + +If you don't have write access to the DBM file, you can only read hash +variables, not set them. If you want to test whether you can write, +either use file tests or try setting a dummy hash entry inside an eval(), +which will trap the error. Note that functions such as keys() and values() may return huge array values when used on large DBM files. You may prefer to use the each() @@ -677,8 +677,8 @@ a real null string, such as referencing elements of an array. You may also check to see if arrays or subroutines exist. Use of defined on predefined variables is not guaranteed to produce intuitive results. -When used on a hash array element, it tells you whether the value -is defined, not whether the key exists in the hash. Use exists() for that. +When used on a hash array element, it tells you whether the value is +defined, not whether the key exists in the hash. Use exists() for that. Examples: @@ -727,14 +727,14 @@ changed, fixed, or broken in a future release of Perl. =item delete EXPR -Deletes the specified key(s) and their associated values from a hash -array. 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 an array tied to a DBM file +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 tie()d hash doesn't necessarily return anything.) -The following deletes all the values of an associative array: +The following deletes all the values of a hash: foreach $key (keys %HASH) { delete $HASH{$key}; @@ -854,22 +854,23 @@ Example: QUICKSTART: Getopt('f'); -=item each ASSOC_ARRAY - -When called in a list context, returns a 2-element array consisting -of the key and value for the next element of an associative array, -so that you can iterate over it. When called in a scalar context, -returns the key for only the next element in the associative array. -Entries are returned in an apparently random order. When the array is -entirely read, a null array is returned in list context (which when -assigned produces a FALSE (0) value), and C<undef> is returned in a -scalar context. The next call to each() after that will start -iterating again. The iterator can be reset only by reading all the -elements from the array. You should not add elements to an array while -you're iterating over it. There is a single iterator for each -associative array, shared by all each(), keys(), and values() function -calls in the program. The following prints out your environment like -the printenv(1) program, only in a different order: +=item each HASH + +When called in a list context, returns a 2-element array consisting of the +key and value for the next element of a hash, so that you can iterate over +it. When called in a scalar context, returns the key for only the next +element in the hash. Entries are returned in an apparently random order. +When the hash is entirely read, a null array is returned in list context +(which when assigned produces a FALSE (0) value), and C<undef> is returned +in a scalar context. The next call to each() after that will start +iterating again. There is a single iterator for each hash, shared by all +each(), keys(), and values() function calls in the program; it can be +reset by reading all the elements from the hash, or by evaluating C<keys +HASH> or C<values HASH> in a scalar context. You should not add elements +to an hash while you're iterating over it. + +The following prints out your environment like the printenv(1) program, +only in a different order: while (($key,$value) = each %ENV) { print "$key=$value\n"; @@ -1573,14 +1574,15 @@ Example: See L<perlfunc/split>. -=item keys ASSOC_ARRAY +=item keys HASH + +Returns a normal array consisting of all the keys of the named hash. (In +a scalar context, returns the number of keys.) The keys are returned in +an apparently random order, but it is the same order as either the +values() or each() function produces (given that the hash has not been +modified). As a side effect, it resets HASH's iterator. -Returns a normal array consisting of all the keys of the named -associative array. (In a scalar context, returns the number of keys.) -The keys are returned in an apparently random order, but it is the same -order as either the values() or each() function produces (given that -the associative array has not been modified). Here is yet another way -to print your environment: +Here is yet another way to print your environment: @keys = keys %ENV; @values = values %ENV; @@ -1594,18 +1596,17 @@ or how about sorted by key: print $key, '=', $ENV{$key}, "\n"; } -To sort an array by value, you'll need to use a C<sort{}> -function. Here's a descending numeric sort of a hash by its values: +To sort an array by value, you'll need to use a C<sort{}> function. +Here's a descending numeric sort of a hash by its values: foreach $key (sort { $hash{$b} <=> $hash{$a} } keys %hash)) { printf "%4d %s\n", $hash{$key}, $key; } As an lvalue C<keys> allows you to increase the number of hash buckets -allocated for the given associative array. This can gain you a measure -of efficiency if you know the hash is going to get big. (This is -similar to pre-extending an array by assigning a larger number to -$#array.) If you say +allocated for the given hash. This can gain you a measure of efficiency if +you know the hash is going to get big. (This is similar to pre-extending +an array by assigning a larger number to $#array.) If you say keys %hash = 200; @@ -2377,7 +2378,7 @@ If the referenced object has been blessed into a package, then that package name is returned instead. You can think of ref() as a typeof() operator. if (ref($r) eq "HASH") { - print "r is a reference to an associative array.\n"; + print "r is a reference to a hash.\n"; } if (!ref ($r) { print "r is not a reference at all.\n"; @@ -2832,8 +2833,8 @@ Examples: } @sortedclass = sort byage @class; - # this sorts the %age associative arrays by value - # instead of key using an in-line function + # this sorts the %age hash by value instead of key + # using an in-line function @eldest = sort { $age{$b} <=> $age{$a} } keys %age; sub backwards { $b cmp $a; } @@ -3369,8 +3370,7 @@ use the each() function to iterate over such. Example: } untie(%HIST); -A class implementing an associative array should have the following -methods: +A class implementing a hash should have the following methods: TIEHASH classname, LIST DESTROY this @@ -3475,7 +3475,7 @@ subroutine. Examples: undef $foo; undef $bar{'blurfl'}; undef @ary; - undef %assoc; + undef %hash; undef &mysub; return (wantarray ? () : undef) if $they_blew_it; @@ -3629,13 +3629,13 @@ to the current time. Example of a "touch" command: $now = time; utime $now, $now, @ARGV; -=item values ASSOC_ARRAY +=item values HASH -Returns a normal array consisting of all the values of the named -associative array. (In a scalar context, returns the number of -values.) The values are returned in an apparently random order, but it -is the same order as either the keys() or each() function would produce -on the same array. See also keys(), each(), and sort(). +Returns a normal array consisting of all the values of the named hash. +(In a scalar context, returns the number of values.) The values are +returned in an apparently random order, but it is the same order as either +the keys() or each() function would produce on the same hash. As a side +effect, it resets HASH's iterator. See also keys(), each(), and sort(). =item vec EXPR,OFFSET,BITS |