documentation update from tchrist

	Message-Id: <199806140419.WAA20549@chthon.perl.com>
	Subject: doc patches

p4raw-id: //depot/perl@1132

1 files changed, 67 insertions, 30 deletions

diff --git a/pod/perldata.pod b/pod/perldata.pod
index dc2975a7d4..58c11234b4 100644
--- a/pod/perldata.pod
+++ b/pod/perldata.pod
@@ -22,15 +22,15 @@ that's deprecated); all but the last are interpreted as names of
 packages, to locate the namespace in which to look
 up the final identifier (see L<perlmod/Packages> for details).
 It's possible to substitute for a simple identifier an expression
-which produces a reference to the value at runtime; this is
+that produces a reference to the value at runtime; this is
 described in more detail below, and in L<perlref>.
 
 There are also special variables whose names don't follow these
 rules, so that they don't accidentally collide with one of your
-normal variables.  Strings which match parenthesized parts of a
+normal variables.  Strings that match parenthesized parts of a
 regular expression are saved under names containing only digits after
 the C<$> (see L<perlop> and L<perlre>).  In addition, several special
-variables which provide windows into the inner working of Perl have names
+variables that provide windows into the inner working of Perl have names
 containing punctuation characters (see L<perlvar>).
 
 Scalar values are always named with '$', even when referring to a scalar
@@ -81,7 +81,7 @@ that returns a reference to an object of that type.  For a description
 of this, see L<perlref>.
 
 Names that start with a digit may contain only more digits.  Names
-which do not start with a letter, underscore,  or digit are limited to
+that do not start with a letter, underscore, or digit are limited to
 one character, e.g.,  C<$%> or C<$$>.  (Most of these one character names
 have a predefined significance to Perl.  For instance, C<$$> is the
 current process id.)
@@ -171,13 +171,15 @@ numbers count as 0, just as they do in B<awk>:
 
 That's usually preferable because otherwise you won't treat IEEE notations
 like C<NaN> or C<Infinity> properly.  At other times you might prefer to
-use a regular expression to check whether data is numeric.  See L<perlre>
-for details on regular expressions.
+use the POSIX::strtod function or a regular expression to check whether
+data is numeric.  See L<perlre> for details on regular expressions.
 
     warn "has nondigits"	if     /\D/;
-    warn "not a whole number"   unless /^\d+$/;
-    warn "not an integer"       unless /^[+-]?\d+$/
-    warn "not a decimal number" unless /^[+-]?\d+\.?\d*$/
+    warn "not a natural number" unless /^\d+$/;             # rejects -3
+    warn "not an integer"       unless /^-?\d+$/;           # rejects +3
+    warn "not an integer"       unless /^[+-]?\d+$/;
+    warn "not a decimal number" unless /^-?\d+\.?\d*$/;     # rejects .2
+    warn "not a decimal number" unless /^-?(?:\d+(?:\.\d*)?|\.\d+)$/;
     warn "not a C float"
 	unless /^([+-]?)(?=\d|\.\d)\d*(\.\d*)?([Ee]([+-]?\d+))?$/;
 
@@ -189,7 +191,7 @@ length of the array.  Shortening an array by this method destroys
 intervening values.  Lengthening an array that was previously shortened
 I<NO LONGER> recovers the values that were in those elements.  (It used to
 in Perl 4, but we had to break this to make sure destructors were
-called when expected.)  You can also gain some measure of efficiency by
+called when expected.)  You can also gain some miniscule measure of efficiency by
 pre-extending an array that is going to get big.  (You can also extend
 an array by assigning to an element that is off the end of the array.)
 You can truncate an array down to nothing by assigning the null list ()
@@ -200,7 +202,8 @@ to it.  The following are equivalent:
 
 If you evaluate a named array in a scalar context, it returns the length of
 the array.  (Note that this is not true of lists, which return the
-last value, like the C comma operator.)  The following is always true:
+last value, like the C comma operator, nor of built-in functions, which return
+whatever they feel like returning.)  The following is always true:
 
     scalar(@whatever) == $#whatever - $[ + 1;
 
@@ -216,7 +219,7 @@ left to doubt:
 
     $element_count = scalar(@whatever);
 
-If you evaluate a hash in a scalar context, it returns a value which is
+If you evaluate a hash in a scalar context, it returns a value that is
 true if and only if the hash contains any key/value pairs.  (If there
 are any key/value pairs, the value returned is a string consisting of
 the number of used buckets and the number of allocated buckets, separated
@@ -227,6 +230,11 @@ scalar context reveals "1/16", which means only one out of sixteen buckets
 has been touched, and presumably contains all 10,000 of your items.  This
 isn't supposed to happen.)
 
+You can preallocate space for a hash by assigning to the keys() function.
+This rounds up the allocated bucked to the next power of two:
+
+    keys(%users) = 1000;		# allocate 1024 buckets
+
 =head2 Scalar value constructors
 
 Numeric literals are specified in any of the customary floating point or
@@ -288,7 +296,7 @@ Three special literals are __FILE__, __LINE__, and __PACKAGE__, which
 represent the current filename, line number, and package name at that
 point in your program.  They may be used only as separate tokens; they
 will not be interpolated into strings.  If there is no current package
-(due to a C<package;> directive), __PACKAGE__ is the undefined value.
+(due to an empty C<package;> directive), __PACKAGE__ is the undefined value.
 
 The tokens __END__ and __DATA__ may be used to indicate the logical end
 of the script before the actual end of file.  Any following text is
@@ -421,14 +429,14 @@ list literal, so that you can say:
 LISTs do automatic interpolation of sublists.  That is, when a LIST is
 evaluated, each element of the list is evaluated in a list context, and
 the resulting list value is interpolated into LIST just as if each
-individual element were a member of LIST.  Thus arrays lose their
+individual element were a member of LIST.  Thus arrays and hashes lose their
 identity in a LIST--the list
 
-    (@foo,@bar,&SomeSub)
+    (@foo,@bar,&SomeSub,%glarch)
 
 contains all the elements of @foo followed by all the elements of @bar,
-followed by all the elements returned by the subroutine named SomeSub when
-it's called in a list context.
+followed by all the elements returned by the subroutine named SomeSub 
+called in a list context, followed by the key/value pairs of %glarch.
 To make a list reference that does I<NOT> interpolate, see L<perlref>.
 
 The null list is represented by ().  Interpolating it in a list
@@ -476,7 +484,7 @@ which when assigned produces a 0, which is interpreted as FALSE.
 The final element may be an array or a hash:
 
     ($a, $b, @rest) = split;
-    local($a, $b, %rest) = @_;
+    my($a, $b, %rest) = @_;
 
 You can actually put an array or hash anywhere in the list, but the first one
 in the list will soak up all the values, and anything after it will get
@@ -498,7 +506,7 @@ key/value pairs.  That's why it's good to use references sometimes.
 It is often more readable to use the C<=E<gt>> operator between key/value
 pairs.  The C<=E<gt>> operator is mostly just a more visually distinctive
 synonym for a comma, but it also arranges for its left-hand operand to be
-interpreted as a string, if it's a bareword which would be a legal identifier.
+interpreted as a string--if it's a bareword that would be a legal identifier.
 This makes it nice for initializing hashes:
 
     %map = (
@@ -535,13 +543,28 @@ Perl uses an internal type called a I<typeglob> to hold an entire
 symbol table entry.  The type prefix of a typeglob is a C<*>, because
 it represents all types.  This used to be the preferred way to
 pass arrays and hashes by reference into a function, but now that
-we have real references, this is seldom needed.  It also used to be the
-preferred way to pass filehandles into a function, but now
-that we have the *foo{THING} notation it isn't often needed for that,
-either.  It is still needed to pass new filehandles into functions
-(*HANDLE{IO} only works if HANDLE has already been used).
+we have real references, this is seldom needed.  
+
+The main use of typeglobs in modern Perl is create symbol table aliases.
+This assignment:
+
+    *this = *that;
+
+makes $this an alias for $that, @this an alias for @that, %this an alias
+for %that, &this an alias for &that, etc.  Much safer is to use a reference.
+This:
 
-If you need to use a typeglob to save away a filehandle, do it this way:
+    local *Here::blue = \$There::green;
+
+temporarily makes $Here::blue an alias for $There::green, but doesn't
+make @Here::blue an alias for @There::green, or %Here::blue an alias for
+%There::green, etc.  See L<perlmod/"Symbol Tables"> for more examples
+of this.  Strange though this may seem, this is the basis for the whole
+module import/export system.
+
+Another use for typeglobs is to to pass filehandles into a function or
+to create new filehandles.  If you need to use a typeglob to save away
+a filehandle, do it this way:
 
     $fh = *STDOUT;
 
@@ -549,18 +572,32 @@ or perhaps as a real reference, like this:
 
     $fh = \*STDOUT;
 
-This is also a way to create a local filehandle.  For example:
+See L<perlsub> for examples of using these as indirect filehandles
+in functions.
+
+Typeglobs are also a way to create a local filehandle using the local()
+operator.  These last until their block is exited, but may be passed back.
+For example:
 
     sub newopen {
 	my $path = shift;
 	local *FH;  # not my!
-	open (FH, $path) || return undef;
+	open   (FH, $path) 	    or  return undef;
 	return *FH;
     }
     $fh = newopen('/etc/passwd');
 
-Another way to create local filehandles is with IO::Handle and its ilk,
-see the bottom of L<perlfunc/open()>.
+Now that we have the *foo{THING} notation, typeglobs aren't used as much
+for filehandle manipulations, although they're still needed to pass brand
+new file and directory handles into or out of functions. That's because
+*HANDLE{IO} only works if HANDLE has already been used as a handle.
+In other words, *FH can be used to create new symbol table entries,
+but *foo{THING} cannot.
+
+Another way to create anonymous filehandles is with the IO::Handle
+module and its ilk.  These modules have the advantage of not hiding
+different types of the same name during the local().  See the bottom of
+L<perlfunc/open()> for an example.
 
 See L<perlref>, L<perlsub>, and L<perlmod/"Symbol Tables"> for more
-discussion on typeglobs.
+discussion on typeglobs and the *foo{THING} syntax.