From: brian d foy Date: Wed, 13 Jan 2010 20:29:54 +0000 (+0100) Subject: * Tom's latest perlfunc cleanups, to ensure we're on the same track X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=8bdbc703cb0af3faf2163ebce618944c51f180a0;p=p5sagit%2Fp5-mst-13.2.git * Tom's latest perlfunc cleanups, to ensure we're on the same track --- diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index 468822e..faa3eea 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -26,7 +26,7 @@ with LIST as an argument. Such a list may consist of any combination of scalar arguments or list values; the list values will be included in the list as if each individual element were interpolated at that point in the list, forming a longer single-dimensional list value. -Commas should separate individual elements in the LIST. +Commas should separate literal elements of the LIST. Any function in the list below may be used either with or without parentheses around its arguments. (The syntax descriptions omit the @@ -2689,61 +2689,12 @@ X X =item lc Returns a lowercased version of EXPR. This is the internal function -implementing the C<\L> escape in double-quoted strings. +implementing the C<\L> escape in double-quoted strings. Respects +current LC_CTYPE locale if C in force. See L +and L for more details about locale and Unicode support. If EXPR is omitted, uses C<$_>. -What gets returned depends on several factors: - -=over - -=item If C is in effect: - -=over - -=item On EBCDIC platforms - -The results are what the C language system call C returns. - -=item On ASCII platforms - -The results follow ASCII semantics. Only characters C change, to C -respectively. - -=back - -=item Otherwise, If EXPR has the UTF8 flag set - -If the current package has a subroutine named C, it will be used to -change the case (See L.) -Otherwise Unicode semantics are used for the case change. - -=item Otherwise, if C is in effect - -Respects current LC_CTYPE locale. See L. - -=item Otherwise, if C is in effect: - -Unicode semantics are used for the case change. Any subroutine named -C will not be used. - -=item Otherwise: - -=over - -=item On EBCDIC platforms - -The results are what the C language system call C returns. - -=item On ASCII platforms - -ASCII semantics are used for the case change. The lowercase of any character -outside the ASCII range is the character itself. - -=back - -=back - =item lcfirst EXPR X X @@ -2751,13 +2702,12 @@ X X Returns the value of EXPR with the first character lowercased. This is the internal function implementing the C<\l> escape in -double-quoted strings. +double-quoted strings. Respects current LC_CTYPE locale if C in force. See L and L for more +details about locale and Unicode support. If EXPR is omitted, uses C<$_>. -This function behaves the same way under various pragma, such as in a locale, -as L does. - =item length EXPR X X @@ -3630,10 +3580,8 @@ Takes a LIST of values and converts it into a string using the rules given by the TEMPLATE. The resulting string is the concatenation of the converted values. Typically, each converted value looks like its machine-level representation. For example, on 32-bit machines -an integer may be represented by a sequence of 4 bytes, which will in -Perl be presented as a string that's 4 characters long. - -See L for an introduction to this function. +an integer may be represented by a sequence of 4 bytes, which will in +Perl be presented as a string that's 4 characters long. The TEMPLATE is a sequence of characters that give the order and type of values, as follows: @@ -4400,32 +4348,6 @@ the C<\Q> escape in double-quoted strings. If EXPR is omitted, uses C<$_>. -quotemeta (and C<\Q> ... C<\E>) are useful when interpolating strings into -regular expressions, because by default an interpolated variable will be -considered a mini-regular expression. For example: - - my $sentence = 'The quick brown fox jumped over the lazy dog'; - my $substring = 'quick.*?fox'; - $sentence =~ s{$substring}{big bad wolf}; - -Will cause C<$sentence> to become C<'The big bad wolf jumped over...'>. - -On the other hand: - - my $sentence = 'The quick brown fox jumped over the lazy dog'; - my $substring = 'quick.*?fox'; - $sentence =~ s{\Q$substring\E}{big bad wolf}; - -Or: - - my $sentence = 'The quick brown fox jumped over the lazy dog'; - my $substring = 'quick.*?fox'; - my $quoted_substring = quotemeta($substring); - $sentence =~ s{$quoted_substring}{big bad wolf}; - -Will both leave the sentence as is. Normally, when accepting string input from -the user, quotemeta() or C<\Q> must be used. - =item rand EXPR X X @@ -6922,15 +6844,14 @@ X X X =item uc Returns an uppercased version of EXPR. This is the internal function -implementing the C<\U> escape in double-quoted strings. +implementing the C<\U> escape in double-quoted strings. Respects +current LC_CTYPE locale if C in force. See L +and L for more details about locale and Unicode support. It does not attempt to do titlecase mapping on initial letters. See C for that. If EXPR is omitted, uses C<$_>. -This function behaves the same way under various pragma, such as in a locale, -as L does. - =item ucfirst EXPR X X @@ -6938,13 +6859,12 @@ X X Returns the value of EXPR with the first character in uppercase (titlecase in Unicode). This is the internal function implementing -the C<\u> escape in double-quoted strings. +the C<\u> escape in double-quoted strings. Respects current LC_CTYPE +locale if C in force. See L and L +for more details about locale and Unicode support. If EXPR is omitted, uses C<$_>. -This function behaves the same way under various pragma, such as in a locale, -as L does. - =item umask EXPR X @@ -7048,9 +6968,7 @@ C does the reverse of C: it takes a string and expands it out into a list of values. (In scalar context, it returns merely the first value produced.) -If EXPR is omitted, unpacks the C<$_> string. for an introduction to this function. - -See L for an introduction to this function. +If EXPR is omitted, unpacks the C<$_> string. The string is broken into chunks described by the TEMPLATE. Each chunk is converted separately to a value. Typically, either the string is a result