Initial bulk commit for "Git on MSys"
[msysgit/historical-msysgit.git] / lib / perl5 / 5.6.1 / pods / perlop.pod
blob9cae3a21636583482acfe1738899a3e64ea1ab83
1 =head1 NAME
3 perlop - Perl operators and precedence
5 =head1 SYNOPSIS
7 Perl operators have the following associativity and precedence,
8 listed from highest precedence to lowest.  Operators borrowed from
9 C keep the same precedence relationship with each other, even where
10 C's precedence is slightly screwy.  (This makes learning Perl easier
11 for C folks.)  With very few exceptions, these all operate on scalar
12 values only, not array values.
14     left        terms and list operators (leftward)
15     left        ->
16     nonassoc    ++ --
17     right       **
18     right       ! ~ \ and unary + and -
19     left        =~ !~
20     left        * / % x
21     left        + - .
22     left        << >>
23     nonassoc    named unary operators
24     nonassoc    < > <= >= lt gt le ge
25     nonassoc    == != <=> eq ne cmp
26     left        &
27     left        | ^
28     left        &&
29     left        ||
30     nonassoc    ..  ...
31     right       ?:
32     right       = += -= *= etc.
33     left        , =>
34     nonassoc    list operators (rightward)
35     right       not
36     left        and
37     left        or xor
39 In the following sections, these operators are covered in precedence order.
41 Many operators can be overloaded for objects.  See L<overload>.
43 =head1 DESCRIPTION
45 =head2 Terms and List Operators (Leftward)
47 A TERM has the highest precedence in Perl.  They include variables,
48 quote and quote-like operators, any expression in parentheses,
49 and any function whose arguments are parenthesized.  Actually, there
50 aren't really functions in this sense, just list operators and unary
51 operators behaving as functions because you put parentheses around
52 the arguments.  These are all documented in L<perlfunc>.
54 If any list operator (print(), etc.) or any unary operator (chdir(), etc.)
55 is followed by a left parenthesis as the next token, the operator and
56 arguments within parentheses are taken to be of highest precedence,
57 just like a normal function call.
59 In the absence of parentheses, the precedence of list operators such as
60 C<print>, C<sort>, or C<chmod> is either very high or very low depending on
61 whether you are looking at the left side or the right side of the operator.
62 For example, in
64     @ary = (1, 3, sort 4, 2);
65     print @ary;         # prints 1324
67 the commas on the right of the sort are evaluated before the sort,
68 but the commas on the left are evaluated after.  In other words,
69 list operators tend to gobble up all arguments that follow, and
70 then act like a simple TERM with regard to the preceding expression.
71 Be careful with parentheses:
73     # These evaluate exit before doing the print:
74     print($foo, exit);  # Obviously not what you want.
75     print $foo, exit;   # Nor is this.
77     # These do the print before evaluating exit:
78     (print $foo), exit; # This is what you want.
79     print($foo), exit;  # Or this.
80     print ($foo), exit; # Or even this.
82 Also note that
84     print ($foo & 255) + 1, "\n";
86 probably doesn't do what you expect at first glance.  See
87 L<Named Unary Operators> for more discussion of this.
89 Also parsed as terms are the C<do {}> and C<eval {}> constructs, as
90 well as subroutine and method calls, and the anonymous
91 constructors C<[]> and C<{}>.
93 See also L<Quote and Quote-like Operators> toward the end of this section,
94 as well as L<"I/O Operators">.
96 =head2 The Arrow Operator
98 "C<< -> >>" is an infix dereference operator, just as it is in C
99 and C++.  If the right side is either a C<[...]>, C<{...}>, or a
100 C<(...)> subscript, then the left side must be either a hard or
101 symbolic reference to an array, a hash, or a subroutine respectively.
102 (Or technically speaking, a location capable of holding a hard
103 reference, if it's an array or hash reference being used for
104 assignment.)  See L<perlreftut> and L<perlref>.
106 Otherwise, the right side is a method name or a simple scalar
107 variable containing either the method name or a subroutine reference,
108 and the left side must be either an object (a blessed reference)
109 or a class name (that is, a package name).  See L<perlobj>.
111 =head2 Auto-increment and Auto-decrement
113 "++" and "--" work as in C.  That is, if placed before a variable, they
114 increment or decrement the variable before returning the value, and if
115 placed after, increment or decrement the variable after returning the value.
117 The auto-increment operator has a little extra builtin magic to it.  If
118 you increment a variable that is numeric, or that has ever been used in
119 a numeric context, you get a normal increment.  If, however, the
120 variable has been used in only string contexts since it was set, and
121 has a value that is not the empty string and matches the pattern
122 C</^[a-zA-Z]*[0-9]*\z/>, the increment is done as a string, preserving each
123 character within its range, with carry:
125     print ++($foo = '99');      # prints '100'
126     print ++($foo = 'a0');      # prints 'a1'
127     print ++($foo = 'Az');      # prints 'Ba'
128     print ++($foo = 'zz');      # prints 'aaa'
130 The auto-decrement operator is not magical.
132 =head2 Exponentiation
134 Binary "**" is the exponentiation operator.  It binds even more
135 tightly than unary minus, so -2**4 is -(2**4), not (-2)**4. (This is
136 implemented using C's pow(3) function, which actually works on doubles
137 internally.)
139 =head2 Symbolic Unary Operators
141 Unary "!" performs logical negation, i.e., "not".  See also C<not> for a lower
142 precedence version of this.
144 Unary "-" performs arithmetic negation if the operand is numeric.  If
145 the operand is an identifier, a string consisting of a minus sign
146 concatenated with the identifier is returned.  Otherwise, if the string
147 starts with a plus or minus, a string starting with the opposite sign
148 is returned.  One effect of these rules is that C<-bareword> is equivalent
149 to C<"-bareword">.
151 Unary "~" performs bitwise negation, i.e., 1's complement.  For
152 example, C<0666 & ~027> is 0640.  (See also L<Integer Arithmetic> and
153 L<Bitwise String Operators>.)  Note that the width of the result is
154 platform-dependent: ~0 is 32 bits wide on a 32-bit platform, but 64
155 bits wide on a 64-bit platform, so if you are expecting a certain bit
156 width, remember use the & operator to mask off the excess bits.
158 Unary "+" has no effect whatsoever, even on strings.  It is useful
159 syntactically for separating a function name from a parenthesized expression
160 that would otherwise be interpreted as the complete list of function
161 arguments.  (See examples above under L<Terms and List Operators (Leftward)>.)
163 Unary "\" creates a reference to whatever follows it.  See L<perlreftut>
164 and L<perlref>.  Do not confuse this behavior with the behavior of
165 backslash within a string, although both forms do convey the notion
166 of protecting the next thing from interpolation.
168 =head2 Binding Operators
170 Binary "=~" binds a scalar expression to a pattern match.  Certain operations
171 search or modify the string $_ by default.  This operator makes that kind
172 of operation work on some other string.  The right argument is a search
173 pattern, substitution, or transliteration.  The left argument is what is
174 supposed to be searched, substituted, or transliterated instead of the default
175 $_.  When used in scalar context, the return value generally indicates the
176 success of the operation.  Behavior in list context depends on the particular
177 operator.  See L</"Regexp Quote-Like Operators"> for details.
179 If the right argument is an expression rather than a search pattern,
180 substitution, or transliteration, it is interpreted as a search pattern at run
181 time.  This can be less efficient than an explicit search, because the
182 pattern must be compiled every time the expression is evaluated.
184 Binary "!~" is just like "=~" except the return value is negated in
185 the logical sense.
187 =head2 Multiplicative Operators
189 Binary "*" multiplies two numbers.
191 Binary "/" divides two numbers.
193 Binary "%" computes the modulus of two numbers.  Given integer
194 operands C<$a> and C<$b>: If C<$b> is positive, then C<$a % $b> is
195 C<$a> minus the largest multiple of C<$b> that is not greater than
196 C<$a>.  If C<$b> is negative, then C<$a % $b> is C<$a> minus the
197 smallest multiple of C<$b> that is not less than C<$a> (i.e. the
198 result will be less than or equal to zero). 
199 Note than when C<use integer> is in scope, "%" gives you direct access
200 to the modulus operator as implemented by your C compiler.  This
201 operator is not as well defined for negative operands, but it will
202 execute faster.
204 Binary "x" is the repetition operator.  In scalar context or if the left
205 operand is not enclosed in parentheses, it returns a string consisting
206 of the left operand repeated the number of times specified by the right
207 operand.  In list context, if the left operand is enclosed in
208 parentheses, it repeats the list.
210     print '-' x 80;             # print row of dashes
212     print "\t" x ($tab/8), ' ' x ($tab%8);      # tab over
214     @ones = (1) x 80;           # a list of 80 1's
215     @ones = (5) x @ones;        # set all elements to 5
218 =head2 Additive Operators
220 Binary "+" returns the sum of two numbers.
222 Binary "-" returns the difference of two numbers.
224 Binary "." concatenates two strings.
226 =head2 Shift Operators
228 Binary "<<" returns the value of its left argument shifted left by the
229 number of bits specified by the right argument.  Arguments should be
230 integers.  (See also L<Integer Arithmetic>.)
232 Binary ">>" returns the value of its left argument shifted right by
233 the number of bits specified by the right argument.  Arguments should
234 be integers.  (See also L<Integer Arithmetic>.)
236 =head2 Named Unary Operators
238 The various named unary operators are treated as functions with one
239 argument, with optional parentheses.  These include the filetest
240 operators, like C<-f>, C<-M>, etc.  See L<perlfunc>.
242 If any list operator (print(), etc.) or any unary operator (chdir(), etc.)
243 is followed by a left parenthesis as the next token, the operator and
244 arguments within parentheses are taken to be of highest precedence,
245 just like a normal function call.  For example,
246 because named unary operators are higher precedence than ||:
248     chdir $foo    || die;       # (chdir $foo) || die
249     chdir($foo)   || die;       # (chdir $foo) || die
250     chdir ($foo)  || die;       # (chdir $foo) || die
251     chdir +($foo) || die;       # (chdir $foo) || die
253 but, because * is higher precedence than named operators:
255     chdir $foo * 20;    # chdir ($foo * 20)
256     chdir($foo) * 20;   # (chdir $foo) * 20
257     chdir ($foo) * 20;  # (chdir $foo) * 20
258     chdir +($foo) * 20; # chdir ($foo * 20)
260     rand 10 * 20;       # rand (10 * 20)
261     rand(10) * 20;      # (rand 10) * 20
262     rand (10) * 20;     # (rand 10) * 20
263     rand +(10) * 20;    # rand (10 * 20)
265 See also L<"Terms and List Operators (Leftward)">.
267 =head2 Relational Operators
269 Binary "<" returns true if the left argument is numerically less than
270 the right argument.
272 Binary ">" returns true if the left argument is numerically greater
273 than the right argument.
275 Binary "<=" returns true if the left argument is numerically less than
276 or equal to the right argument.
278 Binary ">=" returns true if the left argument is numerically greater
279 than or equal to the right argument.
281 Binary "lt" returns true if the left argument is stringwise less than
282 the right argument.
284 Binary "gt" returns true if the left argument is stringwise greater
285 than the right argument.
287 Binary "le" returns true if the left argument is stringwise less than
288 or equal to the right argument.
290 Binary "ge" returns true if the left argument is stringwise greater
291 than or equal to the right argument.
293 =head2 Equality Operators
295 Binary "==" returns true if the left argument is numerically equal to
296 the right argument.
298 Binary "!=" returns true if the left argument is numerically not equal
299 to the right argument.
301 Binary "<=>" returns -1, 0, or 1 depending on whether the left
302 argument is numerically less than, equal to, or greater than the right
303 argument.  If your platform supports NaNs (not-a-numbers) as numeric
304 values, using them with "<=>" returns undef.  NaN is not "<", "==", ">",
305 "<=" or ">=" anything (even NaN), so those 5 return false. NaN != NaN
306 returns true, as does NaN != anything else. If your platform doesn't
307 support NaNs then NaN is just a string with numeric value 0.
309     perl -le '$a = NaN; print "No NaN support here" if $a == $a'
310     perl -le '$a = NaN; print "NaN support here" if $a != $a'
312 Binary "eq" returns true if the left argument is stringwise equal to
313 the right argument.
315 Binary "ne" returns true if the left argument is stringwise not equal
316 to the right argument.
318 Binary "cmp" returns -1, 0, or 1 depending on whether the left
319 argument is stringwise less than, equal to, or greater than the right
320 argument.
322 "lt", "le", "ge", "gt" and "cmp" use the collation (sort) order specified
323 by the current locale if C<use locale> is in effect.  See L<perllocale>.
325 =head2 Bitwise And
327 Binary "&" returns its operators ANDed together bit by bit.
328 (See also L<Integer Arithmetic> and L<Bitwise String Operators>.)
330 =head2 Bitwise Or and Exclusive Or
332 Binary "|" returns its operators ORed together bit by bit.
333 (See also L<Integer Arithmetic> and L<Bitwise String Operators>.)
335 Binary "^" returns its operators XORed together bit by bit.
336 (See also L<Integer Arithmetic> and L<Bitwise String Operators>.)
338 =head2 C-style Logical And
340 Binary "&&" performs a short-circuit logical AND operation.  That is,
341 if the left operand is false, the right operand is not even evaluated.
342 Scalar or list context propagates down to the right operand if it
343 is evaluated.
345 =head2 C-style Logical Or
347 Binary "||" performs a short-circuit logical OR operation.  That is,
348 if the left operand is true, the right operand is not even evaluated.
349 Scalar or list context propagates down to the right operand if it
350 is evaluated.
352 The C<||> and C<&&> operators differ from C's in that, rather than returning
353 0 or 1, they return the last value evaluated.  Thus, a reasonably portable
354 way to find out the home directory (assuming it's not "0") might be:
356     $home = $ENV{'HOME'} || $ENV{'LOGDIR'} ||
357         (getpwuid($<))[7] || die "You're homeless!\n";
359 In particular, this means that you shouldn't use this
360 for selecting between two aggregates for assignment:
362     @a = @b || @c;              # this is wrong
363     @a = scalar(@b) || @c;      # really meant this
364     @a = @b ? @b : @c;          # this works fine, though
366 As more readable alternatives to C<&&> and C<||> when used for
367 control flow, Perl provides C<and> and C<or> operators (see below).
368 The short-circuit behavior is identical.  The precedence of "and" and
369 "or" is much lower, however, so that you can safely use them after a
370 list operator without the need for parentheses:
372     unlink "alpha", "beta", "gamma"
373             or gripe(), next LINE;
375 With the C-style operators that would have been written like this:
377     unlink("alpha", "beta", "gamma")
378             || (gripe(), next LINE);
380 Using "or" for assignment is unlikely to do what you want; see below.
382 =head2 Range Operators
384 Binary ".." is the range operator, which is really two different
385 operators depending on the context.  In list context, it returns an
386 array of values counting (up by ones) from the left value to the right
387 value.  If the left value is greater than the right value then it
388 returns the empty array.  The range operator is useful for writing
389 C<foreach (1..10)> loops and for doing slice operations on arrays.  In
390 the current implementation, no temporary array is created when the
391 range operator is used as the expression in C<foreach> loops, but older
392 versions of Perl might burn a lot of memory when you write something
393 like this:
395     for (1 .. 1_000_000) {
396         # code
397     }
399 In scalar context, ".." returns a boolean value.  The operator is
400 bistable, like a flip-flop, and emulates the line-range (comma) operator
401 of B<sed>, B<awk>, and various editors.  Each ".." operator maintains its
402 own boolean state.  It is false as long as its left operand is false.
403 Once the left operand is true, the range operator stays true until the
404 right operand is true, I<AFTER> which the range operator becomes false
405 again.  It doesn't become false till the next time the range operator is
406 evaluated.  It can test the right operand and become false on the same
407 evaluation it became true (as in B<awk>), but it still returns true once.
408 If you don't want it to test the right operand till the next
409 evaluation, as in B<sed>, just use three dots ("...") instead of
410 two.  In all other regards, "..." behaves just like ".." does.
412 The right operand is not evaluated while the operator is in the
413 "false" state, and the left operand is not evaluated while the
414 operator is in the "true" state.  The precedence is a little lower
415 than || and &&.  The value returned is either the empty string for
416 false, or a sequence number (beginning with 1) for true.  The
417 sequence number is reset for each range encountered.  The final
418 sequence number in a range has the string "E0" appended to it, which
419 doesn't affect its numeric value, but gives you something to search
420 for if you want to exclude the endpoint.  You can exclude the
421 beginning point by waiting for the sequence number to be greater
422 than 1.  If either operand of scalar ".." is a constant expression,
423 that operand is implicitly compared to the C<$.> variable, the
424 current line number.  Examples:
426 As a scalar operator:
428     if (101 .. 200) { print; }  # print 2nd hundred lines
429     next line if (1 .. /^$/);   # skip header lines
430     s/^/> / if (/^$/ .. eof()); # quote body
432     # parse mail messages
433     while (<>) {
434         $in_header =   1  .. /^$/;
435         $in_body   = /^$/ .. eof();
436         # do something based on those
437     } continue {
438         close ARGV if eof;              # reset $. each file
439     }
441 As a list operator:
443     for (101 .. 200) { print; } # print $_ 100 times
444     @foo = @foo[0 .. $#foo];    # an expensive no-op
445     @foo = @foo[$#foo-4 .. $#foo];      # slice last 5 items
447 The range operator (in list context) makes use of the magical
448 auto-increment algorithm if the operands are strings.  You
449 can say
451     @alphabet = ('A' .. 'Z');
453 to get all normal letters of the alphabet, or
455     $hexdigit = (0 .. 9, 'a' .. 'f')[$num & 15];
457 to get a hexadecimal digit, or
459     @z2 = ('01' .. '31');  print $z2[$mday];
461 to get dates with leading zeros.  If the final value specified is not
462 in the sequence that the magical increment would produce, the sequence
463 goes until the next value would be longer than the final value
464 specified.
466 =head2 Conditional Operator
468 Ternary "?:" is the conditional operator, just as in C.  It works much
469 like an if-then-else.  If the argument before the ? is true, the
470 argument before the : is returned, otherwise the argument after the :
471 is returned.  For example:
473     printf "I have %d dog%s.\n", $n,
474             ($n == 1) ? '' : "s";
476 Scalar or list context propagates downward into the 2nd
477 or 3rd argument, whichever is selected.
479     $a = $ok ? $b : $c;  # get a scalar
480     @a = $ok ? @b : @c;  # get an array
481     $a = $ok ? @b : @c;  # oops, that's just a count!
483 The operator may be assigned to if both the 2nd and 3rd arguments are
484 legal lvalues (meaning that you can assign to them):
486     ($a_or_b ? $a : $b) = $c;
488 Because this operator produces an assignable result, using assignments
489 without parentheses will get you in trouble.  For example, this:
491     $a % 2 ? $a += 10 : $a += 2
493 Really means this:
495     (($a % 2) ? ($a += 10) : $a) += 2
497 Rather than this:
499     ($a % 2) ? ($a += 10) : ($a += 2)
501 That should probably be written more simply as:
503     $a += ($a % 2) ? 10 : 2;
505 =head2 Assignment Operators
507 "=" is the ordinary assignment operator.
509 Assignment operators work as in C.  That is,
511     $a += 2;
513 is equivalent to
515     $a = $a + 2;
517 although without duplicating any side effects that dereferencing the lvalue
518 might trigger, such as from tie().  Other assignment operators work similarly.
519 The following are recognized:
521     **=    +=    *=    &=    <<=    &&=
522            -=    /=    |=    >>=    ||=
523            .=    %=    ^=
524                  x=
526 Although these are grouped by family, they all have the precedence
527 of assignment.
529 Unlike in C, the scalar assignment operator produces a valid lvalue.
530 Modifying an assignment is equivalent to doing the assignment and
531 then modifying the variable that was assigned to.  This is useful
532 for modifying a copy of something, like this:
534     ($tmp = $global) =~ tr [A-Z] [a-z];
536 Likewise,
538     ($a += 2) *= 3;
540 is equivalent to
542     $a += 2;
543     $a *= 3;
545 Similarly, a list assignment in list context produces the list of
546 lvalues assigned to, and a list assignment in scalar context returns
547 the number of elements produced by the expression on the right hand
548 side of the assignment.
550 =head2 Comma Operator
552 Binary "," is the comma operator.  In scalar context it evaluates
553 its left argument, throws that value away, then evaluates its right
554 argument and returns that value.  This is just like C's comma operator.
556 In list context, it's just the list argument separator, and inserts
557 both its arguments into the list.
559 The => digraph is mostly just a synonym for the comma operator.  It's useful for
560 documenting arguments that come in pairs.  As of release 5.001, it also forces
561 any word to the left of it to be interpreted as a string.
563 =head2 List Operators (Rightward)
565 On the right side of a list operator, it has very low precedence,
566 such that it controls all comma-separated expressions found there.
567 The only operators with lower precedence are the logical operators
568 "and", "or", and "not", which may be used to evaluate calls to list
569 operators without the need for extra parentheses:
571     open HANDLE, "filename"
572         or die "Can't open: $!\n";
574 See also discussion of list operators in L<Terms and List Operators (Leftward)>.
576 =head2 Logical Not
578 Unary "not" returns the logical negation of the expression to its right.
579 It's the equivalent of "!" except for the very low precedence.
581 =head2 Logical And
583 Binary "and" returns the logical conjunction of the two surrounding
584 expressions.  It's equivalent to && except for the very low
585 precedence.  This means that it short-circuits: i.e., the right
586 expression is evaluated only if the left expression is true.
588 =head2 Logical or and Exclusive Or
590 Binary "or" returns the logical disjunction of the two surrounding
591 expressions.  It's equivalent to || except for the very low precedence.
592 This makes it useful for control flow
594     print FH $data              or die "Can't write to FH: $!";
596 This means that it short-circuits: i.e., the right expression is evaluated
597 only if the left expression is false.  Due to its precedence, you should
598 probably avoid using this for assignment, only for control flow.
600     $a = $b or $c;              # bug: this is wrong
601     ($a = $b) or $c;            # really means this
602     $a = $b || $c;              # better written this way
604 However, when it's a list-context assignment and you're trying to use
605 "||" for control flow, you probably need "or" so that the assignment
606 takes higher precedence.
608     @info = stat($file) || die;     # oops, scalar sense of stat!
609     @info = stat($file) or die;     # better, now @info gets its due
611 Then again, you could always use parentheses. 
613 Binary "xor" returns the exclusive-OR of the two surrounding expressions.
614 It cannot short circuit, of course.
616 =head2 C Operators Missing From Perl
618 Here is what C has that Perl doesn't:
620 =over 8
622 =item unary &
624 Address-of operator.  (But see the "\" operator for taking a reference.)
626 =item unary *
628 Dereference-address operator. (Perl's prefix dereferencing
629 operators are typed: $, @, %, and &.)
631 =item (TYPE)
633 Type-casting operator.
635 =back
637 =head2 Quote and Quote-like Operators
639 While we usually think of quotes as literal values, in Perl they
640 function as operators, providing various kinds of interpolating and
641 pattern matching capabilities.  Perl provides customary quote characters
642 for these behaviors, but also provides a way for you to choose your
643 quote character for any of them.  In the following table, a C<{}> represents
644 any pair of delimiters you choose.  
646     Customary  Generic        Meaning        Interpolates
647         ''       q{}          Literal             no
648         ""      qq{}          Literal             yes
649         ``      qx{}          Command             yes (unless '' is delimiter)
650                 qw{}         Word list            no
651         //       m{}       Pattern match          yes (unless '' is delimiter)
652                 qr{}          Pattern             yes (unless '' is delimiter)
653                  s{}{}      Substitution          yes (unless '' is delimiter)
654                 tr{}{}    Transliteration         no (but see below)
656 Non-bracketing delimiters use the same character fore and aft, but the four
657 sorts of brackets (round, angle, square, curly) will all nest, which means
658 that 
660         q{foo{bar}baz} 
662 is the same as 
664         'foo{bar}baz'
666 Note, however, that this does not always work for quoting Perl code:
668         $s = q{ if($a eq "}") ... }; # WRONG
670 is a syntax error. The C<Text::Balanced> module on CPAN is able to do this
671 properly.
673 There can be whitespace between the operator and the quoting
674 characters, except when C<#> is being used as the quoting character.
675 C<q#foo#> is parsed as the string C<foo>, while C<q #foo#> is the
676 operator C<q> followed by a comment.  Its argument will be taken
677 from the next line.  This allows you to write:
679     s {foo}  # Replace foo
680       {bar}  # with bar.
682 For constructs that do interpolate, variables beginning with "C<$>"
683 or "C<@>" are interpolated, as are the following escape sequences.  Within
684 a transliteration, the first eleven of these sequences may be used.
686     \t          tab             (HT, TAB)
687     \n          newline         (NL)
688     \r          return          (CR)
689     \f          form feed       (FF)
690     \b          backspace       (BS)
691     \a          alarm (bell)    (BEL)
692     \e          escape          (ESC)
693     \033        octal char      (ESC)
694     \x1b        hex char        (ESC)
695     \x{263a}    wide hex char   (SMILEY)
696     \c[         control char    (ESC)
697     \N{name}    named char
699     \l          lowercase next char
700     \u          uppercase next char
701     \L          lowercase till \E
702     \U          uppercase till \E
703     \E          end case modification
704     \Q          quote non-word characters till \E
706 If C<use locale> is in effect, the case map used by C<\l>, C<\L>, C<\u>
707 and C<\U> is taken from the current locale.  See L<perllocale>.  For
708 documentation of C<\N{name}>, see L<charnames>.
710 All systems use the virtual C<"\n"> to represent a line terminator,
711 called a "newline".  There is no such thing as an unvarying, physical
712 newline character.  It is only an illusion that the operating system,
713 device drivers, C libraries, and Perl all conspire to preserve.  Not all
714 systems read C<"\r"> as ASCII CR and C<"\n"> as ASCII LF.  For example,
715 on a Mac, these are reversed, and on systems without line terminator,
716 printing C<"\n"> may emit no actual data.  In general, use C<"\n"> when
717 you mean a "newline" for your system, but use the literal ASCII when you
718 need an exact character.  For example, most networking protocols expect
719 and prefer a CR+LF (C<"\015\012"> or C<"\cM\cJ">) for line terminators,
720 and although they often accept just C<"\012">, they seldom tolerate just
721 C<"\015">.  If you get in the habit of using C<"\n"> for networking,
722 you may be burned some day.
724 You cannot include a literal C<$> or C<@> within a C<\Q> sequence. 
725 An unescaped C<$> or C<@> interpolates the corresponding variable, 
726 while escaping will cause the literal string C<\$> to be inserted.
727 You'll need to write something like C<m/\Quser\E\@\Qhost/>. 
729 Patterns are subject to an additional level of interpretation as a
730 regular expression.  This is done as a second pass, after variables are
731 interpolated, so that regular expressions may be incorporated into the
732 pattern from the variables.  If this is not what you want, use C<\Q> to
733 interpolate a variable literally.
735 Apart from the behavior described above, Perl does not expand
736 multiple levels of interpolation.  In particular, contrary to the
737 expectations of shell programmers, back-quotes do I<NOT> interpolate
738 within double quotes, nor do single quotes impede evaluation of
739 variables when used within double quotes.
741 =head2 Regexp Quote-Like Operators
743 Here are the quote-like operators that apply to pattern
744 matching and related activities.
746 =over 8
748 =item ?PATTERN?
750 This is just like the C</pattern/> search, except that it matches only
751 once between calls to the reset() operator.  This is a useful
752 optimization when you want to see only the first occurrence of
753 something in each file of a set of files, for instance.  Only C<??>
754 patterns local to the current package are reset.
756     while (<>) {
757         if (?^$?) {
758                             # blank line between header and body
759         }
760     } continue {
761         reset if eof;       # clear ?? status for next file
762     }
764 This usage is vaguely deprecated, which means it just might possibly
765 be removed in some distant future version of Perl, perhaps somewhere
766 around the year 2168.
768 =item m/PATTERN/cgimosx
770 =item /PATTERN/cgimosx
772 Searches a string for a pattern match, and in scalar context returns
773 true if it succeeds, false if it fails.  If no string is specified
774 via the C<=~> or C<!~> operator, the $_ string is searched.  (The
775 string specified with C<=~> need not be an lvalue--it may be the
776 result of an expression evaluation, but remember the C<=~> binds
777 rather tightly.)  See also L<perlre>.  See L<perllocale> for
778 discussion of additional considerations that apply when C<use locale>
779 is in effect.
781 Options are:
783     c   Do not reset search position on a failed match when /g is in effect.
784     g   Match globally, i.e., find all occurrences.
785     i   Do case-insensitive pattern matching.
786     m   Treat string as multiple lines.
787     o   Compile pattern only once.
788     s   Treat string as single line.
789     x   Use extended regular expressions.
791 If "/" is the delimiter then the initial C<m> is optional.  With the C<m>
792 you can use any pair of non-alphanumeric, non-whitespace characters 
793 as delimiters.  This is particularly useful for matching path names
794 that contain "/", to avoid LTS (leaning toothpick syndrome).  If "?" is
795 the delimiter, then the match-only-once rule of C<?PATTERN?> applies.
796 If "'" is the delimiter, no interpolation is performed on the PATTERN.
798 PATTERN may contain variables, which will be interpolated (and the
799 pattern recompiled) every time the pattern search is evaluated, except
800 for when the delimiter is a single quote.  (Note that C<$(>, C<$)>, and
801 C<$|> are not interpolated because they look like end-of-string tests.)
802 If you want such a pattern to be compiled only once, add a C</o> after
803 the trailing delimiter.  This avoids expensive run-time recompilations,
804 and is useful when the value you are interpolating won't change over
805 the life of the script.  However, mentioning C</o> constitutes a promise
806 that you won't change the variables in the pattern.  If you change them,
807 Perl won't even notice.  See also L<"qr/STRING/imosx">.
809 If the PATTERN evaluates to the empty string, the last
810 I<successfully> matched regular expression is used instead.
812 If the C</g> option is not used, C<m//> in list context returns a
813 list consisting of the subexpressions matched by the parentheses in the
814 pattern, i.e., (C<$1>, C<$2>, C<$3>...).  (Note that here C<$1> etc. are
815 also set, and that this differs from Perl 4's behavior.)  When there are
816 no parentheses in the pattern, the return value is the list C<(1)> for
817 success.  With or without parentheses, an empty list is returned upon
818 failure.
820 Examples:
822     open(TTY, '/dev/tty');
823     <TTY> =~ /^y/i && foo();    # do foo if desired
825     if (/Version: *([0-9.]*)/) { $version = $1; }
827     next if m#^/usr/spool/uucp#;
829     # poor man's grep
830     $arg = shift;
831     while (<>) {
832         print if /$arg/o;       # compile only once
833     }
835     if (($F1, $F2, $Etc) = ($foo =~ /^(\S+)\s+(\S+)\s*(.*)/))
837 This last example splits $foo into the first two words and the
838 remainder of the line, and assigns those three fields to $F1, $F2, and
839 $Etc.  The conditional is true if any variables were assigned, i.e., if
840 the pattern matched.
842 The C</g> modifier specifies global pattern matching--that is,
843 matching as many times as possible within the string.  How it behaves
844 depends on the context.  In list context, it returns a list of the
845 substrings matched by any capturing parentheses in the regular
846 expression.  If there are no parentheses, it returns a list of all
847 the matched strings, as if there were parentheses around the whole
848 pattern.
850 In scalar context, each execution of C<m//g> finds the next match,
851 returning true if it matches, and false if there is no further match.
852 The position after the last match can be read or set using the pos()
853 function; see L<perlfunc/pos>.   A failed match normally resets the
854 search position to the beginning of the string, but you can avoid that
855 by adding the C</c> modifier (e.g. C<m//gc>).  Modifying the target
856 string also resets the search position.
858 You can intermix C<m//g> matches with C<m/\G.../g>, where C<\G> is a
859 zero-width assertion that matches the exact position where the previous
860 C<m//g>, if any, left off.  Without the C</g> modifier, the C<\G> assertion
861 still anchors at pos(), but the match is of course only attempted once.
862 Using C<\G> without C</g> on a target string that has not previously had a
863 C</g> match applied to it is the same as using the C<\A> assertion to match
864 the beginning of the string.
866 Examples:
868     # list context
869     ($one,$five,$fifteen) = (`uptime` =~ /(\d+\.\d+)/g);
871     # scalar context
872     $/ = "";
873     while (defined($paragraph = <>)) {
874         while ($paragraph =~ /[a-z]['")]*[.!?]+['")]*\s/g) {
875             $sentences++;
876         }
877     }
878     print "$sentences\n";
880     # using m//gc with \G
881     $_ = "ppooqppqq";
882     while ($i++ < 2) {
883         print "1: '";
884         print $1 while /(o)/gc; print "', pos=", pos, "\n";
885         print "2: '";
886         print $1 if /\G(q)/gc;  print "', pos=", pos, "\n";
887         print "3: '";
888         print $1 while /(p)/gc; print "', pos=", pos, "\n";
889     }
890     print "Final: '$1', pos=",pos,"\n" if /\G(.)/;
892 The last example should print:
894     1: 'oo', pos=4
895     2: 'q', pos=5
896     3: 'pp', pos=7
897     1: '', pos=7
898     2: 'q', pos=8
899     3: '', pos=8
900     Final: 'q', pos=8
902 Notice that the final match matched C<q> instead of C<p>, which a match
903 without the C<\G> anchor would have done. Also note that the final match
904 did not update C<pos> -- C<pos> is only updated on a C</g> match. If the
905 final match did indeed match C<p>, it's a good bet that you're running an
906 older (pre-5.6.0) Perl.
908 A useful idiom for C<lex>-like scanners is C</\G.../gc>.  You can
909 combine several regexps like this to process a string part-by-part,
910 doing different actions depending on which regexp matched.  Each
911 regexp tries to match where the previous one leaves off.
913  $_ = <<'EOL';
914       $url = new URI::URL "http://www/";   die if $url eq "xXx";
915  EOL
916  LOOP:
917     {
918       print(" digits"),         redo LOOP if /\G\d+\b[,.;]?\s*/gc;
919       print(" lowercase"),      redo LOOP if /\G[a-z]+\b[,.;]?\s*/gc;
920       print(" UPPERCASE"),      redo LOOP if /\G[A-Z]+\b[,.;]?\s*/gc;
921       print(" Capitalized"),    redo LOOP if /\G[A-Z][a-z]+\b[,.;]?\s*/gc;
922       print(" MiXeD"),          redo LOOP if /\G[A-Za-z]+\b[,.;]?\s*/gc;
923       print(" alphanumeric"),   redo LOOP if /\G[A-Za-z0-9]+\b[,.;]?\s*/gc;
924       print(" line-noise"),     redo LOOP if /\G[^A-Za-z0-9]+/gc;
925       print ". That's all!\n";
926     }
928 Here is the output (split into several lines):
930  line-noise lowercase line-noise lowercase UPPERCASE line-noise
931  UPPERCASE line-noise lowercase line-noise lowercase line-noise
932  lowercase lowercase line-noise lowercase lowercase line-noise
933  MiXeD line-noise. That's all!
935 =item q/STRING/
937 =item C<'STRING'>
939 A single-quoted, literal string.  A backslash represents a backslash
940 unless followed by the delimiter or another backslash, in which case
941 the delimiter or backslash is interpolated.
943     $foo = q!I said, "You said, 'She said it.'"!;
944     $bar = q('This is it.');
945     $baz = '\n';                # a two-character string
947 =item qq/STRING/
949 =item "STRING"
951 A double-quoted, interpolated string.
953     $_ .= qq
954      (*** The previous line contains the naughty word "$1".\n)
955                 if /\b(tcl|java|python)\b/i;      # :-)
956     $baz = "\n";                # a one-character string
958 =item qr/STRING/imosx
960 This operator quotes (and possibly compiles) its I<STRING> as a regular
961 expression.  I<STRING> is interpolated the same way as I<PATTERN>
962 in C<m/PATTERN/>.  If "'" is used as the delimiter, no interpolation
963 is done.  Returns a Perl value which may be used instead of the
964 corresponding C</STRING/imosx> expression.
966 For example,
968     $rex = qr/my.STRING/is;
969     s/$rex/foo/;
971 is equivalent to
973     s/my.STRING/foo/is;
975 The result may be used as a subpattern in a match:
977     $re = qr/$pattern/;
978     $string =~ /foo${re}bar/;   # can be interpolated in other patterns
979     $string =~ $re;             # or used standalone
980     $string =~ /$re/;           # or this way
982 Since Perl may compile the pattern at the moment of execution of qr()
983 operator, using qr() may have speed advantages in some situations,
984 notably if the result of qr() is used standalone:
986     sub match {
987         my $patterns = shift;
988         my @compiled = map qr/$_/i, @$patterns;
989         grep {
990             my $success = 0;
991             foreach my $pat (@compiled) {
992                 $success = 1, last if /$pat/;
993             }
994             $success;
995         } @_;
996     }
998 Precompilation of the pattern into an internal representation at
999 the moment of qr() avoids a need to recompile the pattern every
1000 time a match C</$pat/> is attempted.  (Perl has many other internal
1001 optimizations, but none would be triggered in the above example if
1002 we did not use qr() operator.)
1004 Options are:
1006     i   Do case-insensitive pattern matching.
1007     m   Treat string as multiple lines.
1008     o   Compile pattern only once.
1009     s   Treat string as single line.
1010     x   Use extended regular expressions.
1012 See L<perlre> for additional information on valid syntax for STRING, and
1013 for a detailed look at the semantics of regular expressions.
1015 =item qx/STRING/
1017 =item `STRING`
1019 A string which is (possibly) interpolated and then executed as a
1020 system command with C</bin/sh> or its equivalent.  Shell wildcards,
1021 pipes, and redirections will be honored.  The collected standard
1022 output of the command is returned; standard error is unaffected.  In
1023 scalar context, it comes back as a single (potentially multi-line)
1024 string, or undef if the command failed.  In list context, returns a
1025 list of lines (however you've defined lines with $/ or
1026 $INPUT_RECORD_SEPARATOR), or an empty list if the command failed.
1028 Because backticks do not affect standard error, use shell file descriptor
1029 syntax (assuming the shell supports this) if you care to address this.
1030 To capture a command's STDERR and STDOUT together:
1032     $output = `cmd 2>&1`;
1034 To capture a command's STDOUT but discard its STDERR:
1036     $output = `cmd 2>/dev/null`;
1038 To capture a command's STDERR but discard its STDOUT (ordering is
1039 important here):
1041     $output = `cmd 2>&1 1>/dev/null`;
1043 To exchange a command's STDOUT and STDERR in order to capture the STDERR
1044 but leave its STDOUT to come out the old STDERR:
1046     $output = `cmd 3>&1 1>&2 2>&3 3>&-`;
1048 To read both a command's STDOUT and its STDERR separately, it's easiest
1049 and safest to redirect them separately to files, and then read from those
1050 files when the program is done:
1052     system("program args 1>/tmp/program.stdout 2>/tmp/program.stderr");
1054 Using single-quote as a delimiter protects the command from Perl's
1055 double-quote interpolation, passing it on to the shell instead:
1057     $perl_info  = qx(ps $$);            # that's Perl's $$
1058     $shell_info = qx'ps $$';            # that's the new shell's $$
1060 How that string gets evaluated is entirely subject to the command
1061 interpreter on your system.  On most platforms, you will have to protect
1062 shell metacharacters if you want them treated literally.  This is in
1063 practice difficult to do, as it's unclear how to escape which characters.
1064 See L<perlsec> for a clean and safe example of a manual fork() and exec()
1065 to emulate backticks safely.
1067 On some platforms (notably DOS-like ones), the shell may not be
1068 capable of dealing with multiline commands, so putting newlines in
1069 the string may not get you what you want.  You may be able to evaluate
1070 multiple commands in a single line by separating them with the command
1071 separator character, if your shell supports that (e.g. C<;> on many Unix
1072 shells; C<&> on the Windows NT C<cmd> shell).
1074 Beginning with v5.6.0, Perl will attempt to flush all files opened for
1075 output before starting the child process, but this may not be supported
1076 on some platforms (see L<perlport>).  To be safe, you may need to set
1077 C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method of
1078 C<IO::Handle> on any open handles.
1080 Beware that some command shells may place restrictions on the length
1081 of the command line.  You must ensure your strings don't exceed this
1082 limit after any necessary interpolations.  See the platform-specific
1083 release notes for more details about your particular environment.
1085 Using this operator can lead to programs that are difficult to port,
1086 because the shell commands called vary between systems, and may in
1087 fact not be present at all.  As one example, the C<type> command under
1088 the POSIX shell is very different from the C<type> command under DOS.
1089 That doesn't mean you should go out of your way to avoid backticks
1090 when they're the right way to get something done.  Perl was made to be
1091 a glue language, and one of the things it glues together is commands.
1092 Just understand what you're getting yourself into.
1094 See L<"I/O Operators"> for more discussion.
1096 =item qw/STRING/
1098 Evaluates to a list of the words extracted out of STRING, using embedded
1099 whitespace as the word delimiters.  It can be understood as being roughly
1100 equivalent to:
1102     split(' ', q/STRING/);
1104 the difference being that it generates a real list at compile time.  So
1105 this expression:
1107     qw(foo bar baz)
1109 is semantically equivalent to the list:
1111     'foo', 'bar', 'baz'
1113 Some frequently seen examples:
1115     use POSIX qw( setlocale localeconv )
1116     @EXPORT = qw( foo bar baz );
1118 A common mistake is to try to separate the words with comma or to
1119 put comments into a multi-line C<qw>-string.  For this reason, the
1120 C<use warnings> pragma and the B<-w> switch (that is, the C<$^W> variable) 
1121 produces warnings if the STRING contains the "," or the "#" character.
1123 =item s/PATTERN/REPLACEMENT/egimosx
1125 Searches a string for a pattern, and if found, replaces that pattern
1126 with the replacement text and returns the number of substitutions
1127 made.  Otherwise it returns false (specifically, the empty string).
1129 If no string is specified via the C<=~> or C<!~> operator, the C<$_>
1130 variable is searched and modified.  (The string specified with C<=~> must
1131 be scalar variable, an array element, a hash element, or an assignment
1132 to one of those, i.e., an lvalue.)
1134 If the delimiter chosen is a single quote, no interpolation is
1135 done on either the PATTERN or the REPLACEMENT.  Otherwise, if the
1136 PATTERN contains a $ that looks like a variable rather than an
1137 end-of-string test, the variable will be interpolated into the pattern
1138 at run-time.  If you want the pattern compiled only once the first time
1139 the variable is interpolated, use the C</o> option.  If the pattern
1140 evaluates to the empty string, the last successfully executed regular
1141 expression is used instead.  See L<perlre> for further explanation on these.
1142 See L<perllocale> for discussion of additional considerations that apply
1143 when C<use locale> is in effect.
1145 Options are:
1147     e   Evaluate the right side as an expression.
1148     g   Replace globally, i.e., all occurrences.
1149     i   Do case-insensitive pattern matching.
1150     m   Treat string as multiple lines.
1151     o   Compile pattern only once.
1152     s   Treat string as single line.
1153     x   Use extended regular expressions.
1155 Any non-alphanumeric, non-whitespace delimiter may replace the
1156 slashes.  If single quotes are used, no interpretation is done on the
1157 replacement string (the C</e> modifier overrides this, however).  Unlike
1158 Perl 4, Perl 5 treats backticks as normal delimiters; the replacement
1159 text is not evaluated as a command.  If the
1160 PATTERN is delimited by bracketing quotes, the REPLACEMENT has its own
1161 pair of quotes, which may or may not be bracketing quotes, e.g.,
1162 C<s(foo)(bar)> or C<< s<foo>/bar/ >>.  A C</e> will cause the
1163 replacement portion to be treated as a full-fledged Perl expression
1164 and evaluated right then and there.  It is, however, syntax checked at
1165 compile-time. A second C<e> modifier will cause the replacement portion
1166 to be C<eval>ed before being run as a Perl expression.
1168 Examples:
1170     s/\bgreen\b/mauve/g;                # don't change wintergreen
1172     $path =~ s|/usr/bin|/usr/local/bin|;
1174     s/Login: $foo/Login: $bar/; # run-time pattern
1176     ($foo = $bar) =~ s/this/that/;      # copy first, then change
1178     $count = ($paragraph =~ s/Mister\b/Mr./g);  # get change-count
1180     $_ = 'abc123xyz';
1181     s/\d+/$&*2/e;               # yields 'abc246xyz'
1182     s/\d+/sprintf("%5d",$&)/e;  # yields 'abc  246xyz'
1183     s/\w/$& x 2/eg;             # yields 'aabbcc  224466xxyyzz'
1185     s/%(.)/$percent{$1}/g;      # change percent escapes; no /e
1186     s/%(.)/$percent{$1} || $&/ge;       # expr now, so /e
1187     s/^=(\w+)/&pod($1)/ge;      # use function call
1189     # expand variables in $_, but dynamics only, using
1190     # symbolic dereferencing
1191     s/\$(\w+)/${$1}/g;
1193     # Add one to the value of any numbers in the string
1194     s/(\d+)/1 + $1/eg;
1196     # This will expand any embedded scalar variable
1197     # (including lexicals) in $_ : First $1 is interpolated
1198     # to the variable name, and then evaluated
1199     s/(\$\w+)/$1/eeg;
1201     # Delete (most) C comments.
1202     $program =~ s {
1203         /\*     # Match the opening delimiter.
1204         .*?     # Match a minimal number of characters.
1205         \*/     # Match the closing delimiter.
1206     } []gsx;
1208     s/^\s*(.*?)\s*$/$1/;        # trim white space in $_, expensively
1210     for ($variable) {           # trim white space in $variable, cheap
1211         s/^\s+//;
1212         s/\s+$//;
1213     }
1215     s/([^ ]*) *([^ ]*)/$2 $1/;  # reverse 1st two fields
1217 Note the use of $ instead of \ in the last example.  Unlike
1218 B<sed>, we use the \<I<digit>> form in only the left hand side.
1219 Anywhere else it's $<I<digit>>.
1221 Occasionally, you can't use just a C</g> to get all the changes
1222 to occur that you might want.  Here are two common cases:
1224     # put commas in the right places in an integer
1225     1 while s/(\d)(\d\d\d)(?!\d)/$1,$2/g;  
1227     # expand tabs to 8-column spacing
1228     1 while s/\t+/' ' x (length($&)*8 - length($`)%8)/e;
1230 =item tr/SEARCHLIST/REPLACEMENTLIST/cds
1232 =item y/SEARCHLIST/REPLACEMENTLIST/cds
1234 Transliterates all occurrences of the characters found in the search list
1235 with the corresponding character in the replacement list.  It returns
1236 the number of characters replaced or deleted.  If no string is
1237 specified via the =~ or !~ operator, the $_ string is transliterated.  (The
1238 string specified with =~ must be a scalar variable, an array element, a
1239 hash element, or an assignment to one of those, i.e., an lvalue.)
1241 A character range may be specified with a hyphen, so C<tr/A-J/0-9/> 
1242 does the same replacement as C<tr/ACEGIBDFHJ/0246813579/>.
1243 For B<sed> devotees, C<y> is provided as a synonym for C<tr>.  If the
1244 SEARCHLIST is delimited by bracketing quotes, the REPLACEMENTLIST has
1245 its own pair of quotes, which may or may not be bracketing quotes,
1246 e.g., C<tr[A-Z][a-z]> or C<tr(+\-*/)/ABCD/>.
1248 Note that C<tr> does B<not> do regular expression character classes
1249 such as C<\d> or C<[:lower:]>.  The <tr> operator is not equivalent to
1250 the tr(1) utility.  If you want to map strings between lower/upper
1251 cases, see L<perlfunc/lc> and L<perlfunc/uc>, and in general consider
1252 using the C<s> operator if you need regular expressions.
1254 Note also that the whole range idea is rather unportable between
1255 character sets--and even within character sets they may cause results
1256 you probably didn't expect.  A sound principle is to use only ranges
1257 that begin from and end at either alphabets of equal case (a-e, A-E),
1258 or digits (0-4).  Anything else is unsafe.  If in doubt, spell out the
1259 character sets in full.
1261 Options:
1263     c   Complement the SEARCHLIST.
1264     d   Delete found but unreplaced characters.
1265     s   Squash duplicate replaced characters.
1267 If the C</c> modifier is specified, the SEARCHLIST character set
1268 is complemented.  If the C</d> modifier is specified, any characters
1269 specified by SEARCHLIST not found in REPLACEMENTLIST are deleted.
1270 (Note that this is slightly more flexible than the behavior of some
1271 B<tr> programs, which delete anything they find in the SEARCHLIST,
1272 period.) If the C</s> modifier is specified, sequences of characters
1273 that were transliterated to the same character are squashed down
1274 to a single instance of the character.
1276 If the C</d> modifier is used, the REPLACEMENTLIST is always interpreted
1277 exactly as specified.  Otherwise, if the REPLACEMENTLIST is shorter
1278 than the SEARCHLIST, the final character is replicated till it is long
1279 enough.  If the REPLACEMENTLIST is empty, the SEARCHLIST is replicated.
1280 This latter is useful for counting characters in a class or for
1281 squashing character sequences in a class.
1283 Examples:
1285     $ARGV[1] =~ tr/A-Z/a-z/;    # canonicalize to lower case
1287     $cnt = tr/*/*/;             # count the stars in $_
1289     $cnt = $sky =~ tr/*/*/;     # count the stars in $sky
1291     $cnt = tr/0-9//;            # count the digits in $_
1293     tr/a-zA-Z//s;               # bookkeeper -> bokeper
1295     ($HOST = $host) =~ tr/a-z/A-Z/;
1297     tr/a-zA-Z/ /cs;             # change non-alphas to single space
1299     tr [\200-\377]
1300        [\000-\177];             # delete 8th bit
1302 If multiple transliterations are given for a character, only the
1303 first one is used:
1305     tr/AAA/XYZ/
1307 will transliterate any A to X.
1309 Because the transliteration table is built at compile time, neither
1310 the SEARCHLIST nor the REPLACEMENTLIST are subjected to double quote
1311 interpolation.  That means that if you want to use variables, you
1312 must use an eval():
1314     eval "tr/$oldlist/$newlist/";
1315     die $@ if $@;
1317     eval "tr/$oldlist/$newlist/, 1" or die $@;
1319 =back
1321 =head2 Gory details of parsing quoted constructs
1323 When presented with something that might have several different
1324 interpretations, Perl uses the B<DWIM> (that's "Do What I Mean")
1325 principle to pick the most probable interpretation.  This strategy
1326 is so successful that Perl programmers often do not suspect the
1327 ambivalence of what they write.  But from time to time, Perl's
1328 notions differ substantially from what the author honestly meant.
1330 This section hopes to clarify how Perl handles quoted constructs.
1331 Although the most common reason to learn this is to unravel labyrinthine
1332 regular expressions, because the initial steps of parsing are the
1333 same for all quoting operators, they are all discussed together.
1335 The most important Perl parsing rule is the first one discussed
1336 below: when processing a quoted construct, Perl first finds the end
1337 of that construct, then interprets its contents.  If you understand
1338 this rule, you may skip the rest of this section on the first
1339 reading.  The other rules are likely to contradict the user's
1340 expectations much less frequently than this first one.
1342 Some passes discussed below are performed concurrently, but because
1343 their results are the same, we consider them individually.  For different
1344 quoting constructs, Perl performs different numbers of passes, from
1345 one to five, but these passes are always performed in the same order.
1347 =over 4
1349 =item Finding the end
1351 The first pass is finding the end of the quoted construct, whether
1352 it be a multicharacter delimiter C<"\nEOF\n"> in the C<<<EOF>
1353 construct, a C</> that terminates a C<qq//> construct, a C<]> which
1354 terminates C<qq[]> construct, or a C<< > >> which terminates a
1355 fileglob started with C<< < >>.
1357 When searching for single-character non-pairing delimiters, such
1358 as C</>, combinations of C<\\> and C<\/> are skipped.  However,
1359 when searching for single-character pairing delimiter like C<[>,
1360 combinations of C<\\>, C<\]>, and C<\[> are all skipped, and nested
1361 C<[>, C<]> are skipped as well.  When searching for multicharacter
1362 delimiters, nothing is skipped.
1364 For constructs with three-part delimiters (C<s///>, C<y///>, and
1365 C<tr///>), the search is repeated once more.
1367 During this search no attention is paid to the semantics of the construct.
1368 Thus:
1370     "$hash{"$foo/$bar"}"
1374     m/ 
1375       bar       # NOT a comment, this slash / terminated m//!
1376      /x
1378 do not form legal quoted expressions.   The quoted part ends on the
1379 first C<"> and C</>, and the rest happens to be a syntax error.
1380 Because the slash that terminated C<m//> was followed by a C<SPACE>,
1381 the example above is not C<m//x>, but rather C<m//> with no C</x>
1382 modifier.  So the embedded C<#> is interpreted as a literal C<#>.
1384 =item Removal of backslashes before delimiters
1386 During the second pass, text between the starting and ending
1387 delimiters is copied to a safe location, and the C<\> is removed
1388 from combinations consisting of C<\> and delimiter--or delimiters,
1389 meaning both starting and ending delimiters will should these differ.
1390 This removal does not happen for multi-character delimiters.
1391 Note that the combination C<\\> is left intact, just as it was.
1393 Starting from this step no information about the delimiters is
1394 used in parsing.
1396 =item Interpolation
1398 The next step is interpolation in the text obtained, which is now
1399 delimiter-independent.  There are four different cases.
1401 =over 4
1403 =item C<<<'EOF'>, C<m''>, C<s'''>, C<tr///>, C<y///>
1405 No interpolation is performed.
1407 =item C<''>, C<q//>
1409 The only interpolation is removal of C<\> from pairs C<\\>.
1411 =item C<"">, C<``>, C<qq//>, C<qx//>, C<< <file*glob> >>
1413 C<\Q>, C<\U>, C<\u>, C<\L>, C<\l> (possibly paired with C<\E>) are
1414 converted to corresponding Perl constructs.  Thus, C<"$foo\Qbaz$bar">
1415 is converted to C<$foo . (quotemeta("baz" . $bar))> internally.
1416 The other combinations are replaced with appropriate expansions.
1418 Let it be stressed that I<whatever falls between C<\Q> and C<\E>>
1419 is interpolated in the usual way.  Something like C<"\Q\\E"> has
1420 no C<\E> inside.  instead, it has C<\Q>, C<\\>, and C<E>, so the
1421 result is the same as for C<"\\\\E">.  As a general rule, backslashes
1422 between C<\Q> and C<\E> may lead to counterintuitive results.  So,
1423 C<"\Q\t\E"> is converted to C<quotemeta("\t")>, which is the same
1424 as C<"\\\t"> (since TAB is not alphanumeric).  Note also that:
1426   $str = '\t';
1427   return "\Q$str";
1429 may be closer to the conjectural I<intention> of the writer of C<"\Q\t\E">.
1431 Interpolated scalars and arrays are converted internally to the C<join> and
1432 C<.> catenation operations.  Thus, C<"$foo XXX '@arr'"> becomes:
1434   $foo . " XXX '" . (join $", @arr) . "'";
1436 All operations above are performed simultaneously, left to right.
1438 Because the result of C<"\Q STRING \E"> has all metacharacters
1439 quoted, there is no way to insert a literal C<$> or C<@> inside a
1440 C<\Q\E> pair.  If protected by C<\>, C<$> will be quoted to became
1441 C<"\\\$">; if not, it is interpreted as the start of an interpolated
1442 scalar.
1444 Note also that the interpolation code needs to make a decision on
1445 where the interpolated scalar ends.  For instance, whether 
1446 C<< "a $b -> {c}" >> really means:
1448   "a " . $b . " -> {c}";
1452   "a " . $b -> {c};
1454 Most of the time, the longest possible text that does not include
1455 spaces between components and which contains matching braces or
1456 brackets.  because the outcome may be determined by voting based
1457 on heuristic estimators, the result is not strictly predictable.
1458 Fortunately, it's usually correct for ambiguous cases.
1460 =item C<?RE?>, C</RE/>, C<m/RE/>, C<s/RE/foo/>, 
1462 Processing of C<\Q>, C<\U>, C<\u>, C<\L>, C<\l>, and interpolation
1463 happens (almost) as with C<qq//> constructs, but the substitution
1464 of C<\> followed by RE-special chars (including C<\>) is not
1465 performed.  Moreover, inside C<(?{BLOCK})>, C<(?# comment )>, and
1466 a C<#>-comment in a C<//x>-regular expression, no processing is
1467 performed whatsoever.  This is the first step at which the presence
1468 of the C<//x> modifier is relevant.
1470 Interpolation has several quirks: C<$|>, C<$(>, and C<$)> are not
1471 interpolated, and constructs C<$var[SOMETHING]> are voted (by several
1472 different estimators) to be either an array element or C<$var>
1473 followed by an RE alternative.  This is where the notation
1474 C<${arr[$bar]}> comes handy: C</${arr[0-9]}/> is interpreted as
1475 array element C<-9>, not as a regular expression from the variable
1476 C<$arr> followed by a digit, which would be the interpretation of
1477 C</$arr[0-9]/>.  Since voting among different estimators may occur,
1478 the result is not predictable.
1480 It is at this step that C<\1> is begrudgingly converted to C<$1> in
1481 the replacement text of C<s///> to correct the incorrigible
1482 I<sed> hackers who haven't picked up the saner idiom yet.  A warning
1483 is emitted if the C<use warnings> pragma or the B<-w> command-line flag
1484 (that is, the C<$^W> variable) was set.
1486 The lack of processing of C<\\> creates specific restrictions on
1487 the post-processed text.  If the delimiter is C</>, one cannot get
1488 the combination C<\/> into the result of this step.  C</> will
1489 finish the regular expression, C<\/> will be stripped to C</> on
1490 the previous step, and C<\\/> will be left as is.  Because C</> is
1491 equivalent to C<\/> inside a regular expression, this does not
1492 matter unless the delimiter happens to be character special to the
1493 RE engine, such as in C<s*foo*bar*>, C<m[foo]>, or C<?foo?>; or an
1494 alphanumeric char, as in:
1496   m m ^ a \s* b mmx;
1498 In the RE above, which is intentionally obfuscated for illustration, the
1499 delimiter is C<m>, the modifier is C<mx>, and after backslash-removal the
1500 RE is the same as for C<m/ ^ a s* b /mx>).  There's more than one 
1501 reason you're encouraged to restrict your delimiters to non-alphanumeric,
1502 non-whitespace choices.
1504 =back
1506 This step is the last one for all constructs except regular expressions,
1507 which are processed further.
1509 =item Interpolation of regular expressions
1511 Previous steps were performed during the compilation of Perl code,
1512 but this one happens at run time--although it may be optimized to
1513 be calculated at compile time if appropriate.  After preprocessing
1514 described above, and possibly after evaluation if catenation,
1515 joining, casing translation, or metaquoting are involved, the
1516 resulting I<string> is passed to the RE engine for compilation.
1518 Whatever happens in the RE engine might be better discussed in L<perlre>,
1519 but for the sake of continuity, we shall do so here.
1521 This is another step where the presence of the C<//x> modifier is
1522 relevant.  The RE engine scans the string from left to right and
1523 converts it to a finite automaton.
1525 Backslashed characters are either replaced with corresponding
1526 literal strings (as with C<\{>), or else they generate special nodes
1527 in the finite automaton (as with C<\b>).  Characters special to the
1528 RE engine (such as C<|>) generate corresponding nodes or groups of
1529 nodes.  C<(?#...)> comments are ignored.  All the rest is either
1530 converted to literal strings to match, or else is ignored (as is
1531 whitespace and C<#>-style comments if C<//x> is present).
1533 Parsing of the bracketed character class construct, C<[...]>, is
1534 rather different than the rule used for the rest of the pattern.
1535 The terminator of this construct is found using the same rules as
1536 for finding the terminator of a C<{}>-delimited construct, the only
1537 exception being that C<]> immediately following C<[> is treated as
1538 though preceded by a backslash.  Similarly, the terminator of
1539 C<(?{...})> is found using the same rules as for finding the
1540 terminator of a C<{}>-delimited construct.
1542 It is possible to inspect both the string given to RE engine and the
1543 resulting finite automaton.  See the arguments C<debug>/C<debugcolor>
1544 in the C<use L<re>> pragma, as well as Perl's B<-Dr> command-line
1545 switch documented in L<perlrun/"Command Switches">.
1547 =item Optimization of regular expressions
1549 This step is listed for completeness only.  Since it does not change
1550 semantics, details of this step are not documented and are subject
1551 to change without notice.  This step is performed over the finite
1552 automaton that was generated during the previous pass.
1554 It is at this stage that C<split()> silently optimizes C</^/> to
1555 mean C</^/m>.
1557 =back
1559 =head2 I/O Operators
1561 There are several I/O operators you should know about.
1563 A string enclosed by backticks (grave accents) first undergoes
1564 double-quote interpolation.  It is then interpreted as an external
1565 command, and the output of that command is the value of the
1566 backtick string, like in a shell.  In scalar context, a single string
1567 consisting of all output is returned.  In list context, a list of
1568 values is returned, one per line of output.  (You can set C<$/> to use
1569 a different line terminator.)  The command is executed each time the
1570 pseudo-literal is evaluated.  The status value of the command is
1571 returned in C<$?> (see L<perlvar> for the interpretation of C<$?>).
1572 Unlike in B<csh>, no translation is done on the return data--newlines
1573 remain newlines.  Unlike in any of the shells, single quotes do not
1574 hide variable names in the command from interpretation.  To pass a
1575 literal dollar-sign through to the shell you need to hide it with a
1576 backslash.  The generalized form of backticks is C<qx//>.  (Because
1577 backticks always undergo shell expansion as well, see L<perlsec> for
1578 security concerns.)
1580 In scalar context, evaluating a filehandle in angle brackets yields
1581 the next line from that file (the newline, if any, included), or
1582 C<undef> at end-of-file or on error.  When C<$/> is set to C<undef>
1583 (sometimes known as file-slurp mode) and the file is empty, it
1584 returns C<''> the first time, followed by C<undef> subsequently.
1586 Ordinarily you must assign the returned value to a variable, but
1587 there is one situation where an automatic assignment happens.  If
1588 and only if the input symbol is the only thing inside the conditional
1589 of a C<while> statement (even if disguised as a C<for(;;)> loop),
1590 the value is automatically assigned to the global variable $_,
1591 destroying whatever was there previously.  (This may seem like an
1592 odd thing to you, but you'll use the construct in almost every Perl
1593 script you write.)  The $_ variable is not implicitly localized.
1594 You'll have to put a C<local $_;> before the loop if you want that
1595 to happen.
1597 The following lines are equivalent:
1599     while (defined($_ = <STDIN>)) { print; }
1600     while ($_ = <STDIN>) { print; }
1601     while (<STDIN>) { print; }
1602     for (;<STDIN>;) { print; }
1603     print while defined($_ = <STDIN>);
1604     print while ($_ = <STDIN>);
1605     print while <STDIN>;
1607 This also behaves similarly, but avoids $_ :
1609     while (my $line = <STDIN>) { print $line }    
1611 In these loop constructs, the assigned value (whether assignment
1612 is automatic or explicit) is then tested to see whether it is
1613 defined.  The defined test avoids problems where line has a string
1614 value that would be treated as false by Perl, for example a "" or
1615 a "0" with no trailing newline.  If you really mean for such values
1616 to terminate the loop, they should be tested for explicitly:
1618     while (($_ = <STDIN>) ne '0') { ... }
1619     while (<STDIN>) { last unless $_; ... }
1621 In other boolean contexts, C<< <I<filehandle>> >> without an
1622 explicit C<defined> test or comparison elicit a warning if the 
1623 C<use warnings> pragma or the B<-w>
1624 command-line switch (the C<$^W> variable) is in effect.
1626 The filehandles STDIN, STDOUT, and STDERR are predefined.  (The
1627 filehandles C<stdin>, C<stdout>, and C<stderr> will also work except
1628 in packages, where they would be interpreted as local identifiers
1629 rather than global.)  Additional filehandles may be created with
1630 the open() function, amongst others.  See L<perlopentut> and
1631 L<perlfunc/open> for details on this.
1633 If a <FILEHANDLE> is used in a context that is looking for
1634 a list, a list comprising all input lines is returned, one line per
1635 list element.  It's easy to grow to a rather large data space this
1636 way, so use with care.
1638 <FILEHANDLE> may also be spelled C<readline(*FILEHANDLE)>.
1639 See L<perlfunc/readline>.
1641 The null filehandle <> is special: it can be used to emulate the
1642 behavior of B<sed> and B<awk>.  Input from <> comes either from
1643 standard input, or from each file listed on the command line.  Here's
1644 how it works: the first time <> is evaluated, the @ARGV array is
1645 checked, and if it is empty, C<$ARGV[0]> is set to "-", which when opened
1646 gives you standard input.  The @ARGV array is then processed as a list
1647 of filenames.  The loop
1649     while (<>) {
1650         ...                     # code for each line
1651     }
1653 is equivalent to the following Perl-like pseudo code:
1655     unshift(@ARGV, '-') unless @ARGV;
1656     while ($ARGV = shift) {
1657         open(ARGV, $ARGV);
1658         while (<ARGV>) {
1659             ...         # code for each line
1660         }
1661     }
1663 except that it isn't so cumbersome to say, and will actually work.
1664 It really does shift the @ARGV array and put the current filename
1665 into the $ARGV variable.  It also uses filehandle I<ARGV>
1666 internally--<> is just a synonym for <ARGV>, which
1667 is magical.  (The pseudo code above doesn't work because it treats
1668 <ARGV> as non-magical.)
1670 You can modify @ARGV before the first <> as long as the array ends up
1671 containing the list of filenames you really want.  Line numbers (C<$.>)
1672 continue as though the input were one big happy file.  See the example
1673 in L<perlfunc/eof> for how to reset line numbers on each file.
1675 If you want to set @ARGV to your own list of files, go right ahead.  
1676 This sets @ARGV to all plain text files if no @ARGV was given:
1678     @ARGV = grep { -f && -T } glob('*') unless @ARGV;
1680 You can even set them to pipe commands.  For example, this automatically
1681 filters compressed arguments through B<gzip>:
1683     @ARGV = map { /\.(gz|Z)$/ ? "gzip -dc < $_ |" : $_ } @ARGV;
1685 If you want to pass switches into your script, you can use one of the
1686 Getopts modules or put a loop on the front like this:
1688     while ($_ = $ARGV[0], /^-/) {
1689         shift;
1690         last if /^--$/;
1691         if (/^-D(.*)/) { $debug = $1 }
1692         if (/^-v/)     { $verbose++  }
1693         # ...           # other switches
1694     }
1696     while (<>) {
1697         # ...           # code for each line
1698     }
1700 The <> symbol will return C<undef> for end-of-file only once.  
1701 If you call it again after this, it will assume you are processing another 
1702 @ARGV list, and if you haven't set @ARGV, will read input from STDIN.
1704 If angle brackets contain is a simple scalar variable (e.g.,
1705 <$foo>), then that variable contains the name of the
1706 filehandle to input from, or its typeglob, or a reference to the
1707 same.  For example:
1709     $fh = \*STDIN;
1710     $line = <$fh>;
1712 If what's within the angle brackets is neither a filehandle nor a simple
1713 scalar variable containing a filehandle name, typeglob, or typeglob
1714 reference, it is interpreted as a filename pattern to be globbed, and
1715 either a list of filenames or the next filename in the list is returned,
1716 depending on context.  This distinction is determined on syntactic
1717 grounds alone.  That means C<< <$x> >> is always a readline() from
1718 an indirect handle, but C<< <$hash{key}> >> is always a glob().
1719 That's because $x is a simple scalar variable, but C<$hash{key}> is
1720 not--it's a hash element.
1722 One level of double-quote interpretation is done first, but you can't
1723 say C<< <$foo> >> because that's an indirect filehandle as explained
1724 in the previous paragraph.  (In older versions of Perl, programmers
1725 would insert curly brackets to force interpretation as a filename glob:
1726 C<< <${foo}> >>.  These days, it's considered cleaner to call the
1727 internal function directly as C<glob($foo)>, which is probably the right
1728 way to have done it in the first place.)  For example:
1730     while (<*.c>) {
1731         chmod 0644, $_;
1732     }
1734 is roughly equivalent to:
1736     open(FOO, "echo *.c | tr -s ' \t\r\f' '\\012\\012\\012\\012'|");
1737     while (<FOO>) {
1738         chomp;
1739         chmod 0644, $_;
1740     }
1742 except that the globbing is actually done internally using the standard
1743 C<File::Glob> extension.  Of course, the shortest way to do the above is:
1745     chmod 0644, <*.c>;
1747 A (file)glob evaluates its (embedded) argument only when it is
1748 starting a new list.  All values must be read before it will start
1749 over.  In list context, this isn't important because you automatically
1750 get them all anyway.  However, in scalar context the operator returns
1751 the next value each time it's called, or C<undef> when the list has
1752 run out.  As with filehandle reads, an automatic C<defined> is
1753 generated when the glob occurs in the test part of a C<while>,
1754 because legal glob returns (e.g. a file called F<0>) would otherwise
1755 terminate the loop.  Again, C<undef> is returned only once.  So if
1756 you're expecting a single value from a glob, it is much better to
1759     ($file) = <blurch*>;
1761 than
1763     $file = <blurch*>;
1765 because the latter will alternate between returning a filename and
1766 returning false.
1768 It you're trying to do variable interpolation, it's definitely better
1769 to use the glob() function, because the older notation can cause people
1770 to become confused with the indirect filehandle notation.
1772     @files = glob("$dir/*.[ch]");
1773     @files = glob($files[$i]);
1775 =head2 Constant Folding
1777 Like C, Perl does a certain amount of expression evaluation at
1778 compile time whenever it determines that all arguments to an
1779 operator are static and have no side effects.  In particular, string
1780 concatenation happens at compile time between literals that don't do
1781 variable substitution.  Backslash interpolation also happens at
1782 compile time.  You can say
1784     'Now is the time for all' . "\n" .
1785         'good men to come to.'
1787 and this all reduces to one string internally.  Likewise, if
1788 you say
1790     foreach $file (@filenames) {
1791         if (-s $file > 5 + 100 * 2**16) {  }
1792     }
1794 the compiler will precompute the number which that expression
1795 represents so that the interpreter won't have to.
1797 =head2 Bitwise String Operators
1799 Bitstrings of any size may be manipulated by the bitwise operators
1800 (C<~ | & ^>).
1802 If the operands to a binary bitwise op are strings of different
1803 sizes, B<|> and B<^> ops act as though the shorter operand had
1804 additional zero bits on the right, while the B<&> op acts as though
1805 the longer operand were truncated to the length of the shorter.
1806 The granularity for such extension or truncation is one or more
1807 bytes.
1809     # ASCII-based examples 
1810     print "j p \n" ^ " a h";            # prints "JAPH\n"
1811     print "JA" | "  ph\n";              # prints "japh\n"
1812     print "japh\nJunk" & '_____';       # prints "JAPH\n";
1813     print 'p N$' ^ " E<H\n";            # prints "Perl\n";
1815 If you are intending to manipulate bitstrings, be certain that
1816 you're supplying bitstrings: If an operand is a number, that will imply
1817 a B<numeric> bitwise operation.  You may explicitly show which type of
1818 operation you intend by using C<""> or C<0+>, as in the examples below.
1820     $foo =  150  |  105 ;       # yields 255  (0x96 | 0x69 is 0xFF)
1821     $foo = '150' |  105 ;       # yields 255
1822     $foo =  150  | '105';       # yields 255
1823     $foo = '150' | '105';       # yields string '155' (under ASCII)
1825     $baz = 0+$foo & 0+$bar;     # both ops explicitly numeric
1826     $biz = "$foo" ^ "$bar";     # both ops explicitly stringy
1828 See L<perlfunc/vec> for information on how to manipulate individual bits
1829 in a bit vector.
1831 =head2 Integer Arithmetic
1833 By default, Perl assumes that it must do most of its arithmetic in
1834 floating point.  But by saying
1836     use integer;
1838 you may tell the compiler that it's okay to use integer operations
1839 (if it feels like it) from here to the end of the enclosing BLOCK.
1840 An inner BLOCK may countermand this by saying
1842     no integer;
1844 which lasts until the end of that BLOCK.  Note that this doesn't
1845 mean everything is only an integer, merely that Perl may use integer
1846 operations if it is so inclined.  For example, even under C<use
1847 integer>, if you take the C<sqrt(2)>, you'll still get C<1.4142135623731>
1848 or so.
1850 Used on numbers, the bitwise operators ("&", "|", "^", "~", "<<",
1851 and ">>") always produce integral results.  (But see also 
1852 L<Bitwise String Operators>.)  However, C<use integer> still has meaning for
1853 them.  By default, their results are interpreted as unsigned integers, but
1854 if C<use integer> is in effect, their results are interpreted
1855 as signed integers.  For example, C<~0> usually evaluates to a large
1856 integral value.  However, C<use integer; ~0> is C<-1> on twos-complement
1857 machines.
1859 =head2 Floating-point Arithmetic
1861 While C<use integer> provides integer-only arithmetic, there is no
1862 analogous mechanism to provide automatic rounding or truncation to a
1863 certain number of decimal places.  For rounding to a certain number
1864 of digits, sprintf() or printf() is usually the easiest route.
1865 See L<perlfaq4>.
1867 Floating-point numbers are only approximations to what a mathematician
1868 would call real numbers.  There are infinitely more reals than floats,
1869 so some corners must be cut.  For example:
1871     printf "%.20g\n", 123456789123456789;
1872     #        produces 123456789123456784
1874 Testing for exact equality of floating-point equality or inequality is
1875 not a good idea.  Here's a (relatively expensive) work-around to compare
1876 whether two floating-point numbers are equal to a particular number of
1877 decimal places.  See Knuth, volume II, for a more robust treatment of
1878 this topic.
1880     sub fp_equal {
1881         my ($X, $Y, $POINTS) = @_;
1882         my ($tX, $tY);
1883         $tX = sprintf("%.${POINTS}g", $X);
1884         $tY = sprintf("%.${POINTS}g", $Y);
1885         return $tX eq $tY;
1886     }
1888 The POSIX module (part of the standard perl distribution) implements
1889 ceil(), floor(), and other mathematical and trigonometric functions.
1890 The Math::Complex module (part of the standard perl distribution)
1891 defines mathematical functions that work on both the reals and the
1892 imaginary numbers.  Math::Complex not as efficient as POSIX, but
1893 POSIX can't work with complex numbers.
1895 Rounding in financial applications can have serious implications, and
1896 the rounding method used should be specified precisely.  In these
1897 cases, it probably pays not to trust whichever system rounding is
1898 being used by Perl, but to instead implement the rounding function you
1899 need yourself.
1901 =head2 Bigger Numbers
1903 The standard Math::BigInt and Math::BigFloat modules provide
1904 variable-precision arithmetic and overloaded operators, although
1905 they're currently pretty slow. At the cost of some space and
1906 considerable speed, they avoid the normal pitfalls associated with
1907 limited-precision representations.
1909     use Math::BigInt;
1910     $x = Math::BigInt->new('123456789123456789');
1911     print $x * $x;
1913     # prints +15241578780673678515622620750190521
1915 There are several modules that let you calculate with (bound only by
1916 memory and cpu-time) unlimited or fixed precision. There are also
1917 some non-standard modules that provide faster implementations via
1918 external C libraries.
1920 Here is a short, but incomplete summary:
1922         Math::Fraction          big, unlimited fractions like 9973 / 12967
1923         Math::String            treat string sequences like numbers
1924         Math::FixedPrecision    calculate with a fixed precision
1925         Math::Currency          for currency calculations
1926         Bit::Vector             manipulate bit vectors fast (uses C)
1927         Math::BigIntFast        Bit::Vector wrapper for big numbers
1928         Math::Pari              provides access to the Pari C library
1929         Math::BigInteger        uses an external C library
1930         Math::Cephes            uses external Cephes C library (no big numbers)
1931         Math::Cephes::Fraction  fractions via the Cephes library
1932         Math::GMP               another one using an external C library
1934 Choose wisely.
1936 =cut