The problem described in 20010514.031 still wasn't

[p5sagit/p5-mst-13.2.git] / pod / perlfunc.pod

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 4f3c4d7..e959cd3 100644 (file)
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -2935,6 +2935,8 @@ See L<utf8> for more about Unicode.
 
 =item our EXPR
 
+=item our EXPR : ATTRIBUTES
+
 An C<our> declares the listed variables to be valid globals within
 the enclosing block, file, or C<eval>.  That is, it has the same
 scoping rules as a "my" declaration, but does not create a local
@@ -2973,6 +2975,28 @@ package, Perl will emit warnings if you have asked for them.
 
     our $bar;          # emits warning
 
+An C<our> declaration may also have a list of attributes associated
+with it.  B<WARNING>: This is an experimental feature that may be
+changed or removed in future releases of Perl.  It should not be
+relied upon.
+
+The only currently recognized attribute is C<shared> which indicates
+that a single copy of the global is to be used by all interpreters
+should the program happen to be running in a multi-interpreter
+environment. (The default behaviour would be for each interpreter to
+have its own copy of the global.)  In such an environment, this
+attribute also has the effect of making the global readonly.
+Examples:
+
+    our @EXPORT : shared = qw(foo);
+    our %EXPORT_TAGS : shared = (bar => [qw(aa bb cc)]);
+    our $VERSION : shared = "1.00";
+
+Multi-interpreter environments can come to being either through the
+fork() emulation on Windows platforms, or by embedding perl in a
+multi-threaded application.  The C<shared> attribute does nothing in
+all other environments.
+
 =item pack TEMPLATE,LIST
 
 Takes a LIST of values and converts it into a string using the rules
@@ -3508,8 +3532,8 @@ If EXPR is omitted, uses C<$_>.
 
 Returns a random fractional number greater than or equal to C<0> and less
 than the value of EXPR.  (EXPR should be positive.)  If EXPR is
-omitted, the value C<1> is used.  Automatically calls C<srand> unless
-C<srand> has already been called.  See also C<srand>.
+omitted, or a C<0>, the value C<1> is used.  Automatically calls C<srand> 
+unless C<srand> has already been called.  See also C<srand>.
 
 Apply C<int()> to the value returned by C<rand()> if you want random
 integers instead of random fractional numbers.  For example,
@@ -4409,11 +4433,15 @@ splits on whitespace (after skipping any leading whitespace).  Anything
 matching PATTERN is taken to be a delimiter separating the fields.  (Note
 that the delimiter may be longer than one character.)
 
-If LIMIT is specified and positive, splits into no more than that
-many fields (though it may split into fewer).  If LIMIT is unspecified
-or zero, trailing null fields are stripped (which potential users
-of C<pop> would do well to remember).  If LIMIT is negative, it is
-treated as if an arbitrarily large LIMIT had been specified.
+If LIMIT is specified and positive, it represents the maximum number
+of fields the EXPR will be split into, though the actual number of
+fields returned depends on the number of times PATTERN matches within
+EXPR.  If LIMIT is unspecified or zero, trailing null fields are
+stripped (which potential users of C<pop> would do well to remember).
+If LIMIT is negative, it is treated as if an arbitrarily large LIMIT
+had been specified.  Note that splitting an EXPR that evaluates to the
+empty string always returns the empty list, regardless of the LIMIT
+specified.
 
 A pattern matching the null string (not to be confused with
 a null pattern C<//>, which is just one member of the set of patterns