Debian Codegraph @

upstream/debian-unstable/man1/perlop.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "PERLOP 1"
58 .TH PERLOP 1 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 perlop \- Perl expressions: operators, precedence, string literals
65 .IX Xref "operator"
66 .SH DESCRIPTION
67 .IX Header "DESCRIPTION"
68 In Perl, the operator determines what operation is performed,
69 independent of the type of the operands. For example \f(CW\*(C`$x\ +\ $y\*(C'\fR
70 is always a numeric addition, and if \f(CW$x\fR or \f(CW$y\fR do not contain
71 numbers, an attempt is made to convert them to numbers first.
72 .PP
73 This is in contrast to many other dynamic languages, where the
74 operation is determined by the type of the first argument. It also
75 means that Perl has two versions of some operators, one for numeric
76 and one for string comparison. For example \f(CW\*(C`$x\ ==\ $y\*(C'\fR compares
77 two numbers for equality, and \f(CW\*(C`$x\ eq\ $y\*(C'\fR compares two strings.
78 .PP
79 There are a few exceptions though: \f(CW\*(C`x\*(C'\fR can be either string
80 repetition or list repetition, depending on the type of the left
81 operand, and \f(CW\*(C`&\*(C'\fR, \f(CW\*(C`|\*(C'\fR, \f(CW\*(C`^\*(C'\fR and \f(CW\*(C`~\*(C'\fR can be either string or numeric bit
82 operations.
83 .SS "Operator Precedence and Associativity"
84 .IX Xref "operator, precedence precedence associativity"
85 .IX Subsection "Operator Precedence and Associativity"
86 Operator precedence and associativity work in Perl more or less like
87 they do in mathematics.
88 .PP
89 \&\fIOperator precedence\fR means some operators group more tightly than others.
90 For example, in \f(CW\*(C`2 + 4 * 5\*(C'\fR, the multiplication has higher precedence, so \f(CW\*(C`4
91 * 5\*(C'\fR is grouped together as the right-hand operand of the addition, rather
92 than \f(CW\*(C`2 + 4\*(C'\fR being grouped together as the left-hand operand of the
93 multiplication. It is as if the expression were written \f(CW\*(C`2 + (4 * 5)\*(C'\fR, not
94 \&\f(CW\*(C`(2 + 4) * 5\*(C'\fR. So the expression yields \f(CW\*(C`2 + 20 == 22\*(C'\fR, rather than
95 \&\f(CW\*(C`6 * 5 == 30\*(C'\fR.
96 .PP
97 \&\fIOperator associativity\fR defines what happens if a sequence of the same
98 operators is used one after another:
99 usually that they will be grouped at the left
100 or the right. For example, in \f(CW\*(C`9 \- 3 \- 2\*(C'\fR, subtraction is left associative,
101 so \f(CW\*(C`9 \- 3\*(C'\fR is grouped together as the left-hand operand of the second
102 subtraction, rather than \f(CW\*(C`3 \- 2\*(C'\fR being grouped together as the right-hand
103 operand of the first subtraction. It is as if the expression were written
104 \&\f(CW\*(C`(9 \- 3) \- 2\*(C'\fR, not \f(CW\*(C`9 \- (3 \- 2)\*(C'\fR. So the expression yields \f(CW\*(C`6 \- 2 == 4\*(C'\fR,
105 rather than \f(CW\*(C`9 \- 1 == 8\*(C'\fR.
106 .PP
107 For simple operators that evaluate all their operands and then combine the
108 values in some way, precedence and associativity (and parentheses) imply some
109 ordering requirements on those combining operations. For example, in \f(CW2 + 4 *
110 5\fR, the grouping implied by precedence means that the multiplication of 4 and
111 5 must be performed before the addition of 2 and 20, simply because the result
112 of that multiplication is required as one of the operands of the addition. But
113 the order of operations is not fully determined by this: in \f(CW\*(C`2 * 2 + 4 * 5\*(C'\fR
114 both multiplications must be performed before the addition, but the grouping
115 does not say anything about the order in which the two multiplications are
116 performed. In fact Perl has a general rule that the operands of an operator
117 are evaluated in left-to-right order. A few operators such as \f(CW\*(C`&&=\*(C'\fR have
118 special evaluation rules that can result in an operand not being evaluated at
119 all; in general, the top-level operator in an expression has control of
120 operand evaluation.
121 .PP
122 Some comparison operators, as their associativity, \fIchain\fR with some
123 operators of the same precedence (but never with operators of different
124 precedence). This chaining means that each comparison is performed
125 on the two arguments surrounding it, with each interior argument taking
126 part in two comparisons, and the comparison results are implicitly ANDed.
127 Thus \f(CW"$x\ <\ $y\ <=\ $z"\fR behaves exactly like \f(CW"$x\ <\ $y\ &&\ $y\ <=\ $z"\fR, assuming that \f(CW"$y"\fR is as simple a scalar as
128 it looks. The ANDing short-circuits just like \f(CW"&&"\fR does, stopping
129 the sequence of comparisons as soon as one yields false.
130 .PP
131 In a chained comparison, each argument expression is evaluated at most
132 once, even if it takes part in two comparisons, but the result of the
133 evaluation is fetched for each comparison. (It is not evaluated
134 at all if the short-circuiting means that it's not required for any
135 comparisons.) This matters if the computation of an interior argument
136 is expensive or non-deterministic. For example,
137 .PP
138 .Vb 1
139 \& if($x < expensive_sub() <= $z) { ...
140 .Ve
141 .PP
142 is not entirely like
143 .PP
144 .Vb 1
145 \& if($x < expensive_sub() && expensive_sub() <= $z) { ...
146 .Ve
147 .PP
148 but instead closer to
149 .PP
150 .Vb 2
151 \& my $tmp = expensive_sub();
152 \& if($x < $tmp && $tmp <= $z) { ...
153 .Ve
154 .PP
155 in that the subroutine is only called once. However, it's not exactly
156 like this latter code either, because the chained comparison doesn't
157 actually involve any temporary variable (named or otherwise): there is
158 no assignment. This doesn't make much difference where the expression
159 is a call to an ordinary subroutine, but matters more with an lvalue
160 subroutine, or if the argument expression yields some unusual kind of
161 scalar by other means. For example, if the argument expression yields
162 a tied scalar, then the expression is evaluated to produce that scalar
163 at most once, but the value of that scalar may be fetched up to twice,
164 once for each comparison in which it is actually used.
165 .PP
166 In this example, the expression is evaluated only once, and the tied
167 scalar (the result of the expression) is fetched for each comparison that
168 uses it.
169 .PP
170 .Vb 1
171 \& if ($x < $tied_scalar < $z) { ...
172 .Ve
173 .PP
174 In the next example, the expression is evaluated only once, and the tied
175 scalar is fetched once as part of the operation within the expression.
176 The result of that operation is fetched for each comparison, which
177 normally doesn't matter unless that expression result is also magical due
178 to operator overloading.
179 .PP
180 .Vb 1
181 \& if ($x < $tied_scalar + 42 < $z) { ...
182 .Ve
183 .PP
184 Some operators are instead non-associative, meaning that it is a syntax
185 error to use a sequence of those operators of the same precedence.
186 For example, \f(CW"$x\ ..\ $y\ ..\ $z"\fR is an error.
187 .PP
188 Perl operators have the following associativity and precedence,
189 listed from highest precedence to lowest. Operators borrowed from
190 C keep the same precedence relationship with each other, even where
191 C's precedence is slightly screwy. (This makes learning Perl easier
192 for C folks.) With very few exceptions, these all operate on scalar
193 values only, not array values.
194 .PP
195 .Vb 10
196 \& left terms and list operators (leftward)
197 \& left \->
198 \& nonassoc ++ \-\-
199 \& right **
200 \& right ! ~ ~. \e and unary + and \-
201 \& left =~ !~
202 \& left * / % x
203 \& left + \- .
204 \& left << >>
205 \& nonassoc named unary operators
206 \& nonassoc isa
207 \& chained < > <= >= lt gt le ge
208 \& chain/na == != eq ne <=> cmp ~~
209 \& left & &.
210 \& left | |. ^ ^.
211 \& left &&
212 \& left || ^^ //
213 \& nonassoc .. ...
214 \& right ?:
215 \& right = += \-= *= etc. goto last next redo dump
216 \& left , =>
217 \& nonassoc list operators (rightward)
218 \& right not
219 \& left and
220 \& left or xor
221 .Ve
222 .PP
223 In the following sections, these operators are covered in detail, in the
224 same order in which they appear in the table above.
225 .PP
226 Many operators can be overloaded for objects. See overload.
227 .SS "Terms and List Operators (Leftward)"
228 .IX Xref "list operator operator, list term"
229 .IX Subsection "Terms and List Operators (Leftward)"
230 A TERM has the highest precedence in Perl. They include variables,
231 quote and quote-like operators, any expression in parentheses,
232 and any function whose arguments are parenthesized. Actually, there
233 aren't really functions in this sense, just list operators and unary
234 operators behaving as functions because you put parentheses around
235 the arguments. These are all documented in perlfunc.
236 .PP
237 If any list operator (\f(CWprint()\fR, etc.) or any unary operator (\f(CWchdir()\fR, etc.)
238 is followed by a left parenthesis as the next token, the operator and
239 arguments within parentheses are taken to be of highest precedence,
240 just like a normal function call.
241 .PP
242 In the absence of parentheses, the precedence of list operators such as
243 \&\f(CW\*(C`print\*(C'\fR, \f(CW\*(C`sort\*(C'\fR, or \f(CW\*(C`chmod\*(C'\fR is either very high or very low depending on
244 whether you are looking at the left side or the right side of the operator.
245 For example, in
246 .PP
247 .Vb 2
248 \& @ary = (1, 3, sort 4, 2);
249 \& print @ary; # prints 1324
250 .Ve
251 .PP
252 the commas on the right of the \f(CW\*(C`sort\*(C'\fR are evaluated before the \f(CW\*(C`sort\*(C'\fR,
253 but the commas on the left are evaluated after. In other words,
254 list operators tend to gobble up all arguments that follow, and
255 then act like a simple TERM with regard to the preceding expression.
256 Be careful with parentheses:
257 .PP
258 .Vb 3
259 \& # These evaluate exit before doing the print:
260 \& print($foo, exit); # Obviously not what you want.
261 \& print $foo, exit; # Nor is this.
262 \&
263 \& # These do the print before evaluating exit:
264 \& (print $foo), exit; # This is what you want.
265 \& print($foo), exit; # Or this.
266 \& print ($foo), exit; # Or even this.
267 .Ve
268 .PP
269 Also note that
270 .PP
271 .Vb 1
272 \& print ($foo & 255) + 1, "\en";
273 .Ve
274 .PP
275 probably doesn't do what you expect at first glance. The parentheses
276 enclose the argument list for \f(CW\*(C`print\*(C'\fR which is evaluated (printing
277 the result of \f(CW\*(C`$foo\ &\ 255\*(C'\fR). Then one is added to the return value
278 of \f(CW\*(C`print\*(C'\fR (usually 1). The result is something like this:
279 .PP
280 .Vb 1
281 \& 1 + 1, "\en"; # Obviously not what you meant.
282 .Ve
283 .PP
284 To do what you meant properly, you must write:
285 .PP
286 .Vb 1
287 \& print(($foo & 255) + 1, "\en");
288 .Ve
289 .PP
290 See "Named Unary Operators" for more discussion of this.
291 .PP
292 Also parsed as terms are the \f(CW\*(C`do\ {}\*(C'\fR and \f(CW\*(C`eval\ {}\*(C'\fR constructs, as
293 well as subroutine and method calls, and the anonymous
294 constructors \f(CW\*(C`[]\*(C'\fR and \f(CW\*(C`{}\*(C'\fR.
295 .PP
296 See also "Quote and Quote-like Operators" toward the end of this section,
297 as well as "I/O Operators".
298 .SS "The Arrow Operator"
299 .IX Xref "arrow dereference ->"
300 .IX Subsection "The Arrow Operator"
301 "\f(CW\*(C`\->\*(C'\fR" is an infix dereference operator, just as it is in C
302 and C++. If the right side is either a \f(CW\*(C`[...]\*(C'\fR, \f(CW\*(C`{...}\*(C'\fR, or a
303 \&\f(CW\*(C`(...)\*(C'\fR subscript, then the left side must be either a hard or
304 symbolic reference to an array, a hash, or a subroutine respectively.
305 (Or technically speaking, a location capable of holding a hard
306 reference, if it's an array or hash reference being used for
307 assignment.) See perlreftut and perlref.
308 .PP
309 Otherwise, the right side is a method name or a simple scalar
310 variable containing either the method name or a subroutine reference,
311 and (if it is a method name) the left side must be either an object (a
312 blessed reference) or a class name (that is, a package name). See
313 perlobj.
314 .PP
315 The dereferencing cases (as opposed to method-calling cases) are
316 somewhat extended by the \f(CW\*(C`postderef\*(C'\fR feature. For the
317 details of that feature, consult "Postfix Dereference Syntax" in perlref.
318 .SS "Auto-increment and Auto-decrement"
319 .IX Xref "increment auto-increment ++ decrement auto-decrement --"
320 .IX Subsection "Auto-increment and Auto-decrement"
321 \&\f(CW"++"\fR and \f(CW"\-\-"\fR work as in C. That is, if placed before a variable,
322 they increment or decrement the variable by one before returning the
323 value, and if placed after, increment or decrement after returning the
324 value.
325 .PP
326 .Vb 3
327 \& $i = 0; $j = 0;
328 \& print $i++; # prints 0
329 \& print ++$j; # prints 1
330 .Ve
331 .PP
332 Note that just as in C, Perl doesn't define \fBwhen\fR the variable is
333 incremented or decremented. You just know it will be done sometime
334 before or after the value is returned. This also means that modifying
335 a variable twice in the same statement will lead to undefined behavior.
336 Avoid statements like:
337 .PP
338 .Vb 2
339 \& $i = $i ++;
340 \& print ++ $i + $i ++;
341 .Ve
342 .PP
343 Perl will not guarantee what the result of the above statements is.
344 .PP
345 The auto-increment operator has a little extra builtin magic to it. If
346 you increment a variable that is numeric, or that has ever been used in
347 a numeric context, you get a normal increment. If, however, the
348 variable has been used in only string contexts since it was set, and
349 has a value that is not the empty string and matches the pattern
350 \&\f(CW\*(C`/^[a\-zA\-Z]*[0\-9]*\ez/\*(C'\fR, the increment is done as a string, preserving each
351 character within its range, with carry:
352 .PP
353 .Vb 4
354 \& print ++($foo = "99"); # prints "100"
355 \& print ++($foo = "a0"); # prints "a1"
356 \& print ++($foo = "Az"); # prints "Ba"
357 \& print ++($foo = "zz"); # prints "aaa"
358 .Ve
359 .PP
360 \&\f(CW\*(C`undef\*(C'\fR is always treated as numeric, and in particular is changed
361 to \f(CW0\fR before incrementing (so that a post-increment of an undef value
362 will return \f(CW0\fR rather than \f(CW\*(C`undef\*(C'\fR).
363 .PP
364 The auto-decrement operator is not magical.
365 .SS Exponentiation
366 .IX Xref "** exponentiation power"
367 .IX Subsection "Exponentiation"
368 Binary \f(CW"**"\fR is the exponentiation operator. It binds even more
369 tightly than unary minus, so \f(CW\*(C`\-2**4\*(C'\fR is \f(CW\*(C`\-(2**4)\*(C'\fR, not \f(CW\*(C`(\-2)**4\*(C'\fR.
370 (This is
371 implemented using C's \f(CWpow(3)\fR function, which actually works on doubles
372 internally.)
373 .PP
374 Note that certain exponentiation expressions are ill-defined:
375 these include \f(CW\*(C`0**0\*(C'\fR, \f(CW\*(C`1**Inf\*(C'\fR, and \f(CW\*(C`Inf**0\*(C'\fR. Do not expect
376 any particular results from these special cases, the results
377 are platform-dependent.
378 .SS "Symbolic Unary Operators"
379 .IX Xref "unary operator operator, unary"
380 .IX Subsection "Symbolic Unary Operators"
381 Unary \f(CW"!"\fR performs logical negation, that is, "not". See also
382 \&\f(CW\*(C`not\*(C'\fR for a lower precedence version of this.
383 .IX Xref "!"
384 .PP
385 Unary \f(CW"\-"\fR performs arithmetic negation if the operand is numeric,
386 including any string that looks like a number. If the operand is
387 an identifier, a string consisting of a minus sign concatenated
388 with the identifier is returned. Otherwise, if the string starts
389 with a plus or minus, a string starting with the opposite sign is
390 returned. One effect of these rules is that \f(CW\*(C`\-bareword\*(C'\fR is equivalent
391 to the string \f(CW"\-bareword"\fR. If, however, the string begins with a
392 non-alphabetic character (excluding \f(CW"+"\fR or \f(CW"\-"\fR), Perl will attempt
393 to convert
394 the string to a numeric, and the arithmetic negation is performed. If the
395 string cannot be cleanly converted to a numeric, Perl will give the warning
396 \&\fBArgument "the string" isn't numeric in negation (\-) at ...\fR.
397 .IX Xref "- negation, arithmetic"
398 .PP
399 Unary \f(CW"~"\fR performs bitwise negation, that is, 1's complement. For
400 example, \f(CW\*(C`0666\ &\ ~027\*(C'\fR is 0640. (See also "Integer Arithmetic" and
401 "Bitwise String Operators".) Note that the width of the result is
402 platform-dependent: \f(CW\*(C`~0\*(C'\fR is 32 bits wide on a 32\-bit platform, but 64
403 bits wide on a 64\-bit platform, so if you are expecting a certain bit
404 width, remember to use the \f(CW"&"\fR operator to mask off the excess bits.
405 .IX Xref "~ negation, binary"
406 .PP
407 Starting in Perl 5.28, it is a fatal error to try to complement a string
408 containing a character with an ordinal value above 255.
409 .PP
410 If the "bitwise" feature is enabled via \f(CW\*(C`use\ feature\ \*(Aqbitwise\*(Aq\*(C'\fR or \f(CW\*(C`use v5.28\*(C'\fR, then unary
411 \&\f(CW"~"\fR always treats its argument as a number, and an
412 alternate form of the operator, \f(CW"~."\fR, always treats its argument as a
413 string. So \f(CW\*(C`~0\*(C'\fR and \f(CW\*(C`~"0"\*(C'\fR will both give 2**32\-1 on 32\-bit platforms,
414 whereas \f(CW\*(C`~.0\*(C'\fR and \f(CW\*(C`~."0"\*(C'\fR will both yield \f(CW"\exff"\fR. Until Perl 5.28,
415 this feature produced a warning in the \f(CW"experimental::bitwise"\fR category.
416 .PP
417 Unary \f(CW"+"\fR has no effect whatsoever, even on strings. It is useful
418 syntactically for separating a function name from a parenthesized expression
419 that would otherwise be interpreted as the complete list of function
420 arguments. (See examples above under "Terms and List Operators (Leftward)".)
421 .IX Xref "+"
422 .PP
423 Unary \f(CW"\e"\fR creates references. If its operand is a single sigilled
424 thing, it creates a reference to that object. If its operand is a
425 parenthesised list, then it creates references to the things mentioned
426 in the list. Otherwise it puts its operand in list context, and creates
427 a list of references to the scalars in the list provided by the operand.
428 See perlreftut
429 and perlref. Do not confuse this behavior with the behavior of
430 backslash within a string, although both forms do convey the notion
431 of protecting the next thing from interpolation.
432 .IX Xref "\\ reference backslash"
433 .SS "Binding Operators"
434 .IX Xref "binding operator, binding =~ !~"
435 .IX Subsection "Binding Operators"
436 Binary \f(CW"=~"\fR binds a scalar expression to a pattern match. Certain operations
437 search or modify the string \f(CW$_\fR by default. This operator makes that kind
438 of operation work on some other string. The right argument is a search
439 pattern, substitution, or transliteration. The left argument is what is
440 supposed to be searched, substituted, or transliterated instead of the default
441 \&\f(CW$_\fR. When used in scalar context, the return value generally indicates the
442 success of the operation. The exceptions are substitution (\f(CW\*(C`s///\*(C'\fR)
443 and transliteration (\f(CW\*(C`y///\*(C'\fR) with the \f(CW\*(C`/r\*(C'\fR (non-destructive) option,
444 which cause the \fBr\fReturn value to be the result of the substitution.
445 Behavior in list context depends on the particular operator.
446 See "Regexp Quote-Like Operators" for details and perlretut for
447 examples using these operators.
448 .PP
449 If the right argument is an expression rather than a search pattern,
450 substitution, or transliteration, it is interpreted as a search pattern at run
451 time. Note that this means that its
452 contents will be interpolated twice, so
453 .PP
454 .Vb 1
455 \& \*(Aq\e\e\*(Aq =~ q\*(Aq\e\e\*(Aq;
456 .Ve
457 .PP
458 is not ok, as the regex engine will end up trying to compile the
459 pattern \f(CW\*(C`\e\*(C'\fR, which it will consider a syntax error.
460 .PP
461 Binary \f(CW"!~"\fR is just like \f(CW"=~"\fR except the return value is negated in
462 the logical sense.
463 .PP
464 Binary \f(CW"!~"\fR with a non-destructive substitution (\f(CW\*(C`s///r\*(C'\fR) or transliteration
465 (\f(CW\*(C`y///r\*(C'\fR) is a syntax error.
466 .SS "Multiplicative Operators"
467 .IX Xref "operator, multiplicative"
468 .IX Subsection "Multiplicative Operators"
469 Binary \f(CW"*"\fR multiplies two numbers.
470 .IX Xref "*"
471 .PP
472 Binary \f(CW"/"\fR divides two numbers.
473 .IX Xref "slash"
474 .PP
475 Binary \f(CW"%"\fR is the modulo operator, which computes the division
476 remainder of its first argument with respect to its second argument.
477 Given integer
478 operands \f(CW$m\fR and \f(CW$n\fR: If \f(CW$n\fR is positive, then \f(CW\*(C`$m\ %\ $n\*(C'\fR is
479 \&\f(CW$m\fR minus the largest multiple of \f(CW$n\fR less than or equal to
480 \&\f(CW$m\fR. If \f(CW$n\fR is negative, then \f(CW\*(C`$m\ %\ $n\*(C'\fR is \f(CW$m\fR minus the
481 smallest multiple of \f(CW$n\fR that is not less than \f(CW$m\fR (that is, the
482 result will be less than or equal to zero). If the operands
483 \&\f(CW$m\fR and \f(CW$n\fR are floating point values and the absolute value of
484 \&\f(CW$n\fR (that is \f(CWabs($n)\fR) is less than \f(CW\*(C`(UV_MAX\ +\ 1)\*(C'\fR, only
485 the integer portion of \f(CW$m\fR and \f(CW$n\fR will be used in the operation
486 (Note: here \f(CW\*(C`UV_MAX\*(C'\fR means the maximum of the unsigned integer type).
487 If the absolute value of the right operand (\f(CWabs($n)\fR) is greater than
488 or equal to \f(CW\*(C`(UV_MAX\ +\ 1)\*(C'\fR, \f(CW"%"\fR computes the floating-point remainder
489 \&\f(CW$r\fR in the equation \f(CW\*(C`($r\ =\ $m\ \-\ $i*$n)\*(C'\fR where \f(CW$i\fR is a certain
490 integer that makes \f(CW$r\fR have the same sign as the right operand
491 \&\f(CW$n\fR (\fBnot\fR as the left operand \f(CW$m\fR like C function \f(CWfmod()\fR)
492 and the absolute value less than that of \f(CW$n\fR.
493 Note that when \f(CW\*(C`use\ integer\*(C'\fR is in scope, \f(CW"%"\fR gives you direct access
494 to the modulo operator as implemented by your C compiler. This
495 operator is not as well defined for negative operands, but it will
496 execute faster.
497 .IX Xref "% remainder modulo mod"
498 .PP
499 Binary \f(CW\*(C`x\*(C'\fR is the repetition operator. In scalar context, or if the
500 left operand is neither enclosed in parentheses nor a \f(CW\*(C`qw//\*(C'\fR list,
501 it performs a string repetition. In that case it supplies scalar
502 context to the left operand, and returns a string consisting of the
503 left operand string repeated the number of times specified by the right
504 operand. If the \f(CW\*(C`x\*(C'\fR is in list context, and the left operand is either
505 enclosed in parentheses or a \f(CW\*(C`qw//\*(C'\fR list, it performs a list repetition.
506 In that case it supplies list context to the left operand, and returns
507 a list consisting of the left operand list repeated the number of times
508 specified by the right operand.
509 If the right operand is zero or negative (raising a warning on
510 negative), it returns an empty string
511 or an empty list, depending on the context.
512 .IX Xref "x"
513 .PP
514 .Vb 1
515 \& print \*(Aq\-\*(Aq x 80; # print row of dashes
516 \&
517 \& print "\et" x ($tab/8), \*(Aq \*(Aq x ($tab%8); # tab over
518 \&
519 \& @ones = (1) x 80; # a list of 80 1\*(Aqs
520 \& @ones = (5) x @ones; # set all elements to 5
521 .Ve
522 .SS "Additive Operators"
523 .IX Xref "operator, additive"
524 .IX Subsection "Additive Operators"
525 Binary \f(CW"+"\fR returns the sum of two numbers.
526 .IX Xref "+"
527 .PP
528 Binary \f(CW"\-"\fR returns the difference of two numbers.
529 .IX Xref "-"
530 .PP
531 Binary \f(CW"."\fR concatenates two strings.
532 .IX Xref "string, concatenation concatenation cat concat concatenate ."
533 .SS "Shift Operators"
534 .IX Xref "shift operator operator, shift << >> right shift left shift bitwise shift shl shr shift, right shift, left"
535 .IX Subsection "Shift Operators"
536 Binary \f(CW"<<"\fR returns the value of its left argument shifted left by the
537 number of bits specified by the right argument. Arguments should be
538 integers. (See also "Integer Arithmetic".)
539 .PP
540 Binary \f(CW">>"\fR returns the value of its left argument shifted right by
541 the number of bits specified by the right argument. Arguments should
542 be integers. (See also "Integer Arithmetic".)
543 .PP
544 If \f(CW\*(C`use\ integer\*(C'\fR (see "Integer Arithmetic") is in force then
545 signed C integers are used (\fIarithmetic shift\fR), otherwise unsigned C
546 integers are used (\fIlogical shift\fR), even for negative shiftees.
547 In arithmetic right shift the sign bit is replicated on the left,
548 in logical shift zero bits come in from the left.
549 .PP
550 Either way, the implementation isn't going to generate results larger
551 than the size of the integer type Perl was built with (32 bits or 64 bits).
552 .PP
553 Shifting by negative number of bits means the reverse shift: left
554 shift becomes right shift, right shift becomes left shift. This is
555 unlike in C, where negative shift is undefined.
556 .PP
557 Shifting by more bits than the size of the integers means most of the
558 time zero (all bits fall off), except that under \f(CW\*(C`use\ integer\*(C'\fR
559 right overshifting a negative shiftee results in \-1. This is unlike
560 in C, where shifting by too many bits is undefined. A common C
561 behavior is "shift by modulo wordbits", so that for example
562 .PP
563 .Vb 1
564 \& 1 >> 64 == 1 >> (64 % 64) == 1 >> 0 == 1 # Common C behavior.
565 .Ve
566 .PP
567 but that is completely accidental.
568 .PP
569 If you get tired of being subject to your platform's native integers,
570 the \f(CW\*(C`use\ bigint\*(C'\fR pragma neatly sidesteps the issue altogether:
571 .PP
572 .Vb 5
573 \& print 20 << 20; # 20971520
574 \& print 20 << 40; # 5120 on 32\-bit machines,
575 \& # 21990232555520 on 64\-bit machines
576 \& use bigint;
577 \& print 20 << 100; # 25353012004564588029934064107520
578 .Ve
579 .SS "Named Unary Operators"
580 .IX Xref "operator, named unary"
581 .IX Subsection "Named Unary Operators"
582 The various named unary operators are treated as functions with one
583 argument, with optional parentheses.
584 .PP
585 If any list operator (\f(CWprint()\fR, etc.) or any unary operator (\f(CWchdir()\fR, etc.)
586 is followed by a left parenthesis as the next token, the operator and
587 arguments within parentheses are taken to be of highest precedence,
588 just like a normal function call. For example,
589 because named unary operators are higher precedence than \f(CW\*(C`||\*(C'\fR:
590 .PP
591 .Vb 4
592 \& chdir $foo || die; # (chdir $foo) || die
593 \& chdir($foo) || die; # (chdir $foo) || die
594 \& chdir ($foo) || die; # (chdir $foo) || die
595 \& chdir +($foo) || die; # (chdir $foo) || die
596 .Ve
597 .PP
598 but, because \f(CW"*"\fR is higher precedence than named operators:
599 .PP
600 .Vb 4
601 \& chdir $foo * 20; # chdir ($foo * 20)
602 \& chdir($foo) * 20; # (chdir $foo) * 20
603 \& chdir ($foo) * 20; # (chdir $foo) * 20
604 \& chdir +($foo) * 20; # chdir ($foo * 20)
605 \&
606 \& rand 10 * 20; # rand (10 * 20)
607 \& rand(10) * 20; # (rand 10) * 20
608 \& rand (10) * 20; # (rand 10) * 20
609 \& rand +(10) * 20; # rand (10 * 20)
610 .Ve
611 .PP
612 Regarding precedence, the filetest operators, like \f(CW\*(C`\-f\*(C'\fR, \f(CW\*(C`\-M\*(C'\fR, etc. are
613 treated like named unary operators, but they don't follow this functional
614 parenthesis rule. That means, for example, that \f(CW\*(C`\-f($file).".bak"\*(C'\fR is
615 equivalent to \f(CW\*(C`\-f\ "$file.bak"\*(C'\fR.
616 .IX Xref "-X filetest operator, filetest"
617 .PP
618 See also "Terms and List Operators (Leftward)".
619 .SS "Relational Operators"
620 .IX Xref "relational operator operator, relational"
621 .IX Subsection "Relational Operators"
622 Perl operators that return true or false generally return values
623 that can be safely used as numbers. For example, the relational
624 operators in this section and the equality operators in the next
625 one return \f(CW1\fR for true and a special version of the defined empty
626 string, \f(CW""\fR, which counts as a zero but is exempt from warnings
627 about improper numeric conversions, just as \f(CW"0\ but\ true"\fR is.
628 .PP
629 Binary \f(CW"<"\fR returns true if the left argument is numerically less than
630 the right argument.
631 .IX Xref "<"
632 .PP
633 Binary \f(CW">"\fR returns true if the left argument is numerically greater
634 than the right argument.
635 .IX Xref ">"
636 .PP
637 Binary \f(CW"<="\fR returns true if the left argument is numerically less than
638 or equal to the right argument.
639 .IX Xref "<="
640 .PP
641 Binary \f(CW">="\fR returns true if the left argument is numerically greater
642 than or equal to the right argument.
643 .IX Xref ">="
644 .PP
645 Binary \f(CW"lt"\fR returns true if the left argument is stringwise less than
646 the right argument.
647 .IX Xref "lt"
648 .PP
649 Binary \f(CW"gt"\fR returns true if the left argument is stringwise greater
650 than the right argument.
651 .IX Xref "gt"
652 .PP
653 Binary \f(CW"le"\fR returns true if the left argument is stringwise less than
654 or equal to the right argument.
655 .IX Xref "le"
656 .PP
657 Binary \f(CW"ge"\fR returns true if the left argument is stringwise greater
658 than or equal to the right argument.
659 .IX Xref "ge"
660 .PP
661 A sequence of relational operators, such as \f(CW"$x\ <\ $y\ <=\ $z"\fR, performs chained comparisons, in the manner described above in
662 the section "Operator Precedence and Associativity".
663 Beware that they do not chain with equality operators, which have lower
664 precedence.
665 .SS "Equality Operators"
666 .IX Xref "equality equal equals operator, equality"
667 .IX Subsection "Equality Operators"
668 Binary \f(CW"=="\fR returns true if the left argument is numerically equal to
669 the right argument.
670 .IX Xref "=="
671 .PP
672 Binary \f(CW"!="\fR returns true if the left argument is numerically not equal
673 to the right argument.
674 .IX Xref "!="
675 .PP
676 Binary \f(CW"eq"\fR returns true if the left argument is stringwise equal to
677 the right argument.
678 .IX Xref "eq"
679 .PP
680 Binary \f(CW"ne"\fR returns true if the left argument is stringwise not equal
681 to the right argument.
682 .IX Xref "ne"
683 .PP
684 A sequence of the above equality operators, such as \f(CW"$x\ ==\ $y\ ==\ $z"\fR, performs chained comparisons, in the manner described above in
685 the section "Operator Precedence and Associativity".
686 Beware that they do not chain with relational operators, which have
687 higher precedence.
688 .PP
689 Binary \f(CW"<=>"\fR returns \-1, 0, or 1 depending on whether the left
690 argument is numerically less than, equal to, or greater than the right
691 argument. If your platform supports \f(CW\*(C`NaN\*(C'\fR's (not-a-numbers) as numeric
692 values, using them with \f(CW"<=>"\fR returns undef. \f(CW\*(C`NaN\*(C'\fR is not
693 \&\f(CW"<"\fR, \f(CW"=="\fR, \f(CW">"\fR, \f(CW"<="\fR or \f(CW">="\fR anything
694 (even \f(CW\*(C`NaN\*(C'\fR), so those 5 return false. \f(CW\*(C`NaN\ !=\ NaN\*(C'\fR returns
695 true, as does \f(CW\*(C`NaN\ !=\*(C'\fR\ \fIanything\ else\fR. If your platform doesn't
696 support \f(CW\*(C`NaN\*(C'\fR's then \f(CW\*(C`NaN\*(C'\fR is just a string with numeric value 0.
697 .IX Xref "<=> spaceship"
698 .PP
699 .Vb 2
700 \& $ perl \-le \*(Aq$x = "NaN"; print "No NaN support here" if $x == $x\*(Aq
701 \& $ perl \-le \*(Aq$x = "NaN"; print "NaN support here" if $x != $x\*(Aq
702 .Ve
703 .PP
704 (Note that the bigint, bigrat, and bignum pragmas all
705 support \f(CW"NaN"\fR.)
706 .PP
707 Binary \f(CW"cmp"\fR returns \-1, 0, or 1 depending on whether the left
708 argument is stringwise less than, equal to, or greater than the right
709 argument.
710 .PP
711 Here we can see the difference between <=> and cmp,
712 .PP
713 .Vb 2
714 \& print 10 <=> 2 #prints 1
715 \& print 10 cmp 2 #prints \-1
716 .Ve
717 .PP
718 (likewise between gt and >, lt and <, etc.)
719 .IX Xref "cmp"
720 .PP
721 Binary \f(CW"~~"\fR does a smartmatch between its arguments. Smart matching
722 is described in the next section.
723 .IX Xref "~~"
724 .PP
725 The two-sided ordering operators \f(CW"<=>"\fR and \f(CW"cmp"\fR, and the
726 smartmatch operator \f(CW"~~"\fR, are non-associative with respect to each
727 other and with respect to the equality operators of the same precedence.
728 .PP
729 \&\f(CW"lt"\fR, \f(CW"le"\fR, \f(CW"ge"\fR, \f(CW"gt"\fR and \f(CW"cmp"\fR use the collation (sort)
730 order specified by the current \f(CW\*(C`LC_COLLATE\*(C'\fR locale if a \f(CW\*(C`use\ locale\*(C'\fR form that includes collation is in effect. See perllocale.
731 Do not mix these with Unicode,
732 only use them with legacy 8\-bit locale encodings.
733 The standard \f(CW\*(C`Unicode::Collate\*(C'\fR and
734 \&\f(CW\*(C`Unicode::Collate::Locale\*(C'\fR modules offer much more powerful
735 solutions to collation issues.
736 .PP
737 For case-insensitive comparisons, look at the "fc" in perlfunc case-folding
738 function, available in Perl v5.16 or later:
739 .PP
740 .Vb 1
741 \& if ( fc($x) eq fc($y) ) { ... }
742 .Ve
743 .SS "Class Instance Operator"
744 .IX Xref "isa operator"
745 .IX Subsection "Class Instance Operator"
746 Binary \f(CW\*(C`isa\*(C'\fR evaluates to true when the left argument is an object instance of
747 the class (or a subclass derived from that class) given by the right argument.
748 If the left argument is not defined, not a blessed object instance, nor does
749 not derive from the class given by the right argument, the operator evaluates
750 as false. The right argument may give the class either as a bareword or a
751 scalar expression that yields a string class name:
752 .PP
753 .Vb 1
754 \& if( $obj isa Some::Class ) { ... }
755 \&
756 \& if( $obj isa "Different::Class" ) { ... }
757 \& if( $obj isa $name_of_class ) { ... }
758 .Ve
759 .PP
760 This feature is available from Perl 5.31.6 onwards when enabled by
761 \&\f(CW\*(C`use feature \*(Aqisa\*(Aq\*(C'\fR. This feature is enabled automatically by a
762 \&\f(CW\*(C`use v5.36\*(C'\fR (or higher) declaration in the current scope.
763 .SS "Smartmatch Operator"
764 .IX Subsection "Smartmatch Operator"
765 First available in Perl 5.10.1 (the 5.10.0 version behaved differently),
766 binary \f(CW\*(C`~~\*(C'\fR does a "smartmatch" between its arguments. This is mostly
767 used implicitly in the \f(CW\*(C`when\*(C'\fR construct described in perlsyn, although
768 not all \f(CW\*(C`when\*(C'\fR clauses call the smartmatch operator. Unique among all of
769 Perl's operators, the smartmatch operator can recurse. The smartmatch
770 operator is experimental and its behavior is
771 subject to change.
772 .PP
773 It is also unique in that all other Perl operators impose a context
774 (usually string or numeric context) on their operands, autoconverting
775 those operands to those imposed contexts. In contrast, smartmatch
776 \&\fIinfers\fR contexts from the actual types of its operands and uses that
777 type information to select a suitable comparison mechanism.
778 .PP
779 The \f(CW\*(C`~~\*(C'\fR operator compares its operands "polymorphically", determining how
780 to compare them according to their actual types (numeric, string, array,
781 hash, etc.). Like the equality operators with which it shares the same
782 precedence, \f(CW\*(C`~~\*(C'\fR returns 1 for true and \f(CW""\fR for false. It is often best
783 read aloud as "in", "inside of", or "is contained in", because the left
784 operand is often looked for \fIinside\fR the right operand. That makes the
785 order of the operands to the smartmatch operand often opposite that of
786 the regular match operator. In other words, the "smaller" thing is usually
787 placed in the left operand and the larger one in the right.
788 .PP
789 The behavior of a smartmatch depends on what type of things its arguments
790 are, as determined by the following table. The first row of the table
791 whose types apply determines the smartmatch behavior. Because what
792 actually happens is mostly determined by the type of the second operand,
793 the table is sorted on the right operand instead of on the left.
794 .PP
795 .Vb 4
796 \& Left Right Description and pseudocode
797 \& ===============================================================
798 \& Any undef check whether Any is undefined
799 \& like: !defined Any
800 \&
801 \& Any Object invoke ~~ overloading on Object, or die
802 \&
803 \& Right operand is an ARRAY:
804 \&
805 \& Left Right Description and pseudocode
806 \& ===============================================================
807 \& ARRAY1 ARRAY2 recurse on paired elements of ARRAY1 and ARRAY2[2]
808 \& like: (ARRAY1[0] ~~ ARRAY2[0])
809 \& && (ARRAY1[1] ~~ ARRAY2[1]) && ...
810 \& HASH ARRAY any ARRAY elements exist as HASH keys
811 \& like: grep { exists HASH\->{$_} } ARRAY
812 \& Regexp ARRAY any ARRAY elements pattern match Regexp
813 \& like: grep { /Regexp/ } ARRAY
814 \& undef ARRAY undef in ARRAY
815 \& like: grep { !defined } ARRAY
816 \& Any ARRAY smartmatch each ARRAY element[3]
817 \& like: grep { Any ~~ $_ } ARRAY
818 \&
819 \& Right operand is a HASH:
820 \&
821 \& Left Right Description and pseudocode
822 \& ===============================================================
823 \& HASH1 HASH2 all same keys in both HASHes
824 \& like: keys HASH1 ==
825 \& grep { exists HASH2\->{$_} } keys HASH1
826 \& ARRAY HASH any ARRAY elements exist as HASH keys
827 \& like: grep { exists HASH\->{$_} } ARRAY
828 \& Regexp HASH any HASH keys pattern match Regexp
829 \& like: grep { /Regexp/ } keys HASH
830 \& undef HASH always false (undef cannot be a key)
831 \& like: 0 == 1
832 \& Any HASH HASH key existence
833 \& like: exists HASH\->{Any}
834 \&
835 \& Right operand is CODE:
836 \&
837 \& Left Right Description and pseudocode
838 \& ===============================================================
839 \& ARRAY CODE sub returns true on all ARRAY elements[1]
840 \& like: !grep { !CODE\->($_) } ARRAY
841 \& HASH CODE sub returns true on all HASH keys[1]
842 \& like: !grep { !CODE\->($_) } keys HASH
843 \& Any CODE sub passed Any returns true
844 \& like: CODE\->(Any)
845 \&
846 \& Right operand is a Regexp:
847 \&
848 \& Left Right Description and pseudocode
849 \& ===============================================================
850 \& ARRAY Regexp any ARRAY elements match Regexp
851 \& like: grep { /Regexp/ } ARRAY
852 \& HASH Regexp any HASH keys match Regexp
853 \& like: grep { /Regexp/ } keys HASH
854 \& Any Regexp pattern match
855 \& like: Any =~ /Regexp/
856 \&
857 \& Other:
858 \&
859 \& Left Right Description and pseudocode
860 \& ===============================================================
861 \& Object Any invoke ~~ overloading on Object,
862 \& or fall back to...
863 \&
864 \& Any Num numeric equality
865 \& like: Any == Num
866 \& Num nummy[4] numeric equality
867 \& like: Num == nummy
868 \& undef Any check whether undefined
869 \& like: !defined(Any)
870 \& Any Any string equality
871 \& like: Any eq Any
872 .Ve
873 .PP
874 Notes:
875 .IP "1. Empty hashes or arrays match." 4
876 .IX Item "1. Empty hashes or arrays match."
877 .PD 0
878 .IP "2. That is, each element smartmatches the element of the same index in the other array.[3]" 4
879 .IX Item "2. That is, each element smartmatches the element of the same index in the other array.[3]"
880 .IP "3. If a circular reference is found, fall back to referential equality." 4
881 .IX Item "3. If a circular reference is found, fall back to referential equality."
882 .IP "4. Either an actual number, or a string that looks like one." 4
883 .IX Item "4. Either an actual number, or a string that looks like one."
884 .PD
885 .PP
886 The smartmatch implicitly dereferences any non-blessed hash or array
887 reference, so the \f(CW\*(C`\fR\f(CIHASH\fR\f(CW\*(C'\fR and \f(CW\*(C`\fR\f(CIARRAY\fR\f(CW\*(C'\fR entries apply in those cases.
888 For blessed references, the \f(CW\*(C`\fR\f(CIObject\fR\f(CW\*(C'\fR entries apply. Smartmatches
889 involving hashes only consider hash keys, never hash values.
890 .PP
891 The "like" code entry is not always an exact rendition. For example, the
892 smartmatch operator short-circuits whenever possible, but \f(CW\*(C`grep\*(C'\fR does
893 not. Also, \f(CW\*(C`grep\*(C'\fR in scalar context returns the number of matches, but
894 \&\f(CW\*(C`~~\*(C'\fR returns only true or false.
895 .PP
896 Unlike most operators, the smartmatch operator knows to treat \f(CW\*(C`undef\*(C'\fR
897 specially:
898 .PP
899 .Vb 3
900 \& use v5.10.1;
901 \& @array = (1, 2, 3, undef, 4, 5);
902 \& say "some elements undefined" if undef ~~ @array;
903 .Ve
904 .PP
905 Each operand is considered in a modified scalar context, the modification
906 being that array and hash variables are passed by reference to the
907 operator, which implicitly dereferences them. Both elements
908 of each pair are the same:
909 .PP
910 .Vb 1
911 \& use v5.10.1;
912 \&
913 \& my %hash = (red => 1, blue => 2, green => 3,
914 \& orange => 4, yellow => 5, purple => 6,
915 \& black => 7, grey => 8, white => 9);
916 \&
917 \& my @array = qw(red blue green);
918 \&
919 \& say "some array elements in hash keys" if @array ~~ %hash;
920 \& say "some array elements in hash keys" if \e@array ~~ \e%hash;
921 \&
922 \& say "red in array" if "red" ~~ @array;
923 \& say "red in array" if "red" ~~ \e@array;
924 \&
925 \& say "some keys end in e" if /e$/ ~~ %hash;
926 \& say "some keys end in e" if /e$/ ~~ \e%hash;
927 .Ve
928 .PP
929 Two arrays smartmatch if each element in the first array smartmatches
930 (that is, is "in") the corresponding element in the second array,
931 recursively.
932 .PP
933 .Vb 6
934 \& use v5.10.1;
935 \& my @little = qw(red blue green);
936 \& my @bigger = ("red", "blue", [ "orange", "green" ] );
937 \& if (@little ~~ @bigger) { # true!
938 \& say "little is contained in bigger";
939 \& }
940 .Ve
941 .PP
942 Because the smartmatch operator recurses on nested arrays, this
943 will still report that "red" is in the array.
944 .PP
945 .Vb 4
946 \& use v5.10.1;
947 \& my @array = qw(red blue green);
948 \& my $nested_array = [[[[[[[ @array ]]]]]]];
949 \& say "red in array" if "red" ~~ $nested_array;
950 .Ve
951 .PP
952 If two arrays smartmatch each other, then they are deep
953 copies of each others' values, as this example reports:
954 .PP
955 .Vb 3
956 \& use v5.12.0;
957 \& my @a = (0, 1, 2, [3, [4, 5], 6], 7);
958 \& my @b = (0, 1, 2, [3, [4, 5], 6], 7);
959 \&
960 \& if (@a ~~ @b && @b ~~ @a) {
961 \& say "a and b are deep copies of each other";
962 \& }
963 \& elsif (@a ~~ @b) {
964 \& say "a smartmatches in b";
965 \& }
966 \& elsif (@b ~~ @a) {
967 \& say "b smartmatches in a";
968 \& }
969 \& else {
970 \& say "a and b don\*(Aqt smartmatch each other at all";
971 \& }
972 .Ve
973 .PP
974 If you were to set \f(CW\*(C`$b[3]\ =\ 4\*(C'\fR, then instead of reporting that "a and b
975 are deep copies of each other", it now reports that \f(CW"b smartmatches in a"\fR.
976 That's because the corresponding position in \f(CW@a\fR contains an array that
977 (eventually) has a 4 in it.
978 .PP
979 Smartmatching one hash against another reports whether both contain the
980 same keys, no more and no less. This could be used to see whether two
981 records have the same field names, without caring what values those fields
982 might have. For example:
983 .PP
984 .Vb 3
985 \& use v5.10.1;
986 \& sub make_dogtag {
987 \& state $REQUIRED_FIELDS = { name=>1, rank=>1, serial_num=>1 };
988 \&
989 \& my ($class, $init_fields) = @_;
990 \&
991 \& die "Must supply (only) name, rank, and serial number"
992 \& unless $init_fields ~~ $REQUIRED_FIELDS;
993 \&
994 \& ...
995 \& }
996 .Ve
997 .PP
998 However, this only does what you mean if \f(CW$init_fields\fR is indeed a hash
999 reference. The condition \f(CW\*(C`$init_fields ~~ $REQUIRED_FIELDS\*(C'\fR also allows the
1000 strings \f(CW"name"\fR, \f(CW"rank"\fR, \f(CW"serial_num"\fR as well as any array reference
1001 that contains \f(CW"name"\fR or \f(CW"rank"\fR or \f(CW"serial_num"\fR anywhere to pass
1002 through.
1003 .PP
1004 The smartmatch operator is most often used as the implicit operator of a
1005 \&\f(CW\*(C`when\*(C'\fR clause. See the section on "Switch Statements" in perlsyn.
1006 .PP
1007 \fISmartmatching of Objects\fR
1008 .IX Subsection "Smartmatching of Objects"
1009 .PP
1010 To avoid relying on an object's underlying representation, if the
1011 smartmatch's right operand is an object that doesn't overload \f(CW\*(C`~~\*(C'\fR,
1012 it raises the exception "\f(CW\*(C`Smartmatching a non\-overloaded object
1013 breaks encapsulation\*(C'\fR". That's because one has no business digging
1014 around to see whether something is "in" an object. These are all
1015 illegal on objects without a \f(CW\*(C`~~\*(C'\fR overload:
1016 .PP
1017 .Vb 3
1018 \& %hash ~~ $object
1019 \& 42 ~~ $object
1020 \& "fred" ~~ $object
1021 .Ve
1022 .PP
1023 However, you can change the way an object is smartmatched by overloading
1024 the \f(CW\*(C`~~\*(C'\fR operator. This is allowed to
1025 extend the usual smartmatch semantics.
1026 For objects that do have an \f(CW\*(C`~~\*(C'\fR overload, see overload.
1027 .PP
1028 Using an object as the left operand is allowed, although not very useful.
1029 Smartmatching rules take precedence over overloading, so even if the
1030 object in the left operand has smartmatch overloading, this will be
1031 ignored. A left operand that is a non-overloaded object falls back on a
1032 string or numeric comparison of whatever the \f(CW\*(C`ref\*(C'\fR operator returns. That
1033 means that
1034 .PP
1035 .Vb 1
1036 \& $object ~~ X
1037 .Ve
1038 .PP
1039 does \fInot\fR invoke the overload method with \f(CW\*(C`\fR\f(CIX\fR\f(CW\*(C'\fR as an argument.
1040 Instead the above table is consulted as normal, and based on the type of
1041 \&\f(CW\*(C`\fR\f(CIX\fR\f(CW\*(C'\fR, overloading may or may not be invoked. For simple strings or
1042 numbers, "in" becomes equivalent to this:
1043 .PP
1044 .Vb 2
1045 \& $object ~~ $number ref($object) == $number
1046 \& $object ~~ $string ref($object) eq $string
1047 .Ve
1048 .PP
1049 For example, this reports that the handle smells IOish
1050 (but please don't really do this!):
1051 .PP
1052 .Vb 5
1053 \& use IO::Handle;
1054 \& my $fh = IO::Handle\->new();
1055 \& if ($fh ~~ /\ebIO\eb/) {
1056 \& say "handle smells IOish";
1057 \& }
1058 .Ve
1059 .PP
1060 That's because it treats \f(CW$fh\fR as a string like
1061 \&\f(CW"IO::Handle=GLOB(0x8039e0)"\fR, then pattern matches against that.
1062 .SS "Bitwise And"
1063 .IX Xref "operator, bitwise, and bitwise and &"
1064 .IX Subsection "Bitwise And"
1065 Binary \f(CW"&"\fR returns its operands ANDed together bit by bit. Although no
1066 warning is currently raised, the result is not well defined when this operation
1067 is performed on operands that aren't either numbers (see
1068 "Integer Arithmetic") nor bitstrings (see "Bitwise String Operators").
1069 .PP
1070 Note that \f(CW"&"\fR has lower priority than relational operators, so for example
1071 the parentheses are essential in a test like
1072 .PP
1073 .Vb 1
1074 \& print "Even\en" if ($x & 1) == 0;
1075 .Ve
1076 .PP
1077 If the "bitwise" feature is enabled via \f(CW\*(C`use\ feature\ \*(Aqbitwise\*(Aq\*(C'\fR or
1078 \&\f(CW\*(C`use v5.28\*(C'\fR, then this operator always treats its operands as numbers.
1079 Before Perl 5.28 this feature produced a warning in the
1080 \&\f(CW"experimental::bitwise"\fR category.
1081 .SS "Bitwise Or and Exclusive Or"
1082 .IX Xref "operator, bitwise, or bitwise or | operator, bitwise, xor bitwise xor ^"
1083 .IX Subsection "Bitwise Or and Exclusive Or"
1084 Binary \f(CW"|"\fR returns its operands ORed together bit by bit.
1085 .PP
1086 Binary \f(CW"^"\fR returns its operands XORed together bit by bit.
1087 .PP
1088 Although no warning is currently raised, the results are not well
1089 defined when these operations are performed on operands that aren't either
1090 numbers (see "Integer Arithmetic") nor bitstrings (see "Bitwise String
1091 Operators").
1092 .PP
1093 Note that \f(CW"|"\fR and \f(CW"^"\fR have lower priority than relational operators, so
1094 for example the parentheses are essential in a test like
1095 .PP
1096 .Vb 1
1097 \& print "false\en" if (8 | 2) != 10;
1098 .Ve
1099 .PP
1100 If the "bitwise" feature is enabled via \f(CW\*(C`use\ feature\ \*(Aqbitwise\*(Aq\*(C'\fR or
1101 \&\f(CW\*(C`use v5.28\*(C'\fR, then this operator always treats its operands as numbers.
1102 Before Perl 5.28. this feature produced a warning in the
1103 \&\f(CW"experimental::bitwise"\fR category.
1104 .SS "C\-style Logical And"
1105 .IX Xref "&& logical and operator, logical, and"
1106 .IX Subsection "C-style Logical And"
1107 Binary \f(CW"&&"\fR performs a short-circuit logical AND operation. That is,
1108 if the left operand is false, the right operand is not even evaluated.
1109 Scalar or list context propagates down to the right operand if it
1110 is evaluated.
1111 .SS "C\-style Logical Or"
1112 .IX Xref "|| operator, logical, or"
1113 .IX Subsection "C-style Logical Or"
1114 Binary \f(CW"||"\fR performs a short-circuit logical OR operation. That is,
1115 if the left operand is true, the right operand is not even evaluated.
1116 Scalar or list context propagates down to the right operand if it
1117 is evaluated.
1118 .SS "C\-style Logical Xor"
1119 .IX Xref "^^ operator, logical, xor"
1120 .IX Subsection "C-style Logical Xor"
1121 Binary \f(CW"^^"\fR performs a logical XOR operation. Both operands are
1122 evaluated and the result is true only if exactly one of the operands is true.
1123 Scalar or list context propagates down to the right operand.
1124 .SS "Logical Defined-Or"
1125 .IX Xref "operator, logical, defined-or"
1126 .IX Subsection "Logical Defined-Or"
1127 Although it has no direct equivalent in C, Perl's \f(CW\*(C`//\*(C'\fR operator is related
1128 to its C\-style "or". In fact, it's exactly the same as \f(CW\*(C`||\*(C'\fR, except that it
1129 tests the left hand side's definedness instead of its truth. Thus,
1130 \&\f(CW\*(C`EXPR1\ //\ EXPR2\*(C'\fR returns the value of \f(CW\*(C`EXPR1\*(C'\fR if it's defined,
1131 otherwise, the value of \f(CW\*(C`EXPR2\*(C'\fR is returned.
1132 (\f(CW\*(C`EXPR1\*(C'\fR is evaluated in scalar context, \f(CW\*(C`EXPR2\*(C'\fR
1133 in the context of \f(CW\*(C`//\*(C'\fR itself). Usually,
1134 this is the same result as \f(CW\*(C`defined(EXPR1)\ ?\ EXPR1\ :\ EXPR2\*(C'\fR (except that
1135 the ternary-operator form can be used as a lvalue, while \f(CW\*(C`EXPR1\ //\ EXPR2\*(C'\fR
1136 cannot). This is very useful for
1137 providing default values for variables. If you actually want to test if
1138 at least one of \f(CW$x\fR and \f(CW$y\fR is defined, use \f(CW\*(C`defined($x\ //\ $y)\*(C'\fR.
1139 .PP
1140 The \f(CW\*(C`||\*(C'\fR, \f(CW\*(C`//\*(C'\fR and \f(CW\*(C`&&\*(C'\fR operators return the last value evaluated
1141 (unlike C's \f(CW\*(C`||\*(C'\fR and \f(CW\*(C`&&\*(C'\fR, which return 0 or 1). Thus, a reasonably
1142 portable way to find out the home directory might be:
1143 .PP
1144 .Vb 4
1145 \& $home = $ENV{HOME}
1146 \& // $ENV{LOGDIR}
1147 \& // (getpwuid($<))[7]
1148 \& // die "You\*(Aqre homeless!\en";
1149 .Ve
1150 .PP
1151 In particular, this means that you shouldn't use this
1152 for selecting between two aggregates for assignment:
1153 .PP
1154 .Vb 3
1155 \& @a = @b || @c; # This doesn\*(Aqt do the right thing
1156 \& @a = scalar(@b) || @c; # because it really means this.
1157 \& @a = @b ? @b : @c; # This works fine, though.
1158 .Ve
1159 .PP
1160 As alternatives to \f(CW\*(C`&&\*(C'\fR and \f(CW\*(C`||\*(C'\fR when used for
1161 control flow, Perl provides the \f(CW\*(C`and\*(C'\fR and \f(CW\*(C`or\*(C'\fR operators (see below).
1162 The short-circuit behavior is identical. The precedence of \f(CW"and"\fR
1163 and \f(CW"or"\fR is much lower, however, so that you can safely use them after a
1164 list operator without the need for parentheses:
1165 .PP
1166 .Vb 2
1167 \& unlink "alpha", "beta", "gamma"
1168 \& or gripe(), next LINE;
1169 .Ve
1170 .PP
1171 With the C\-style operators that would have been written like this:
1172 .PP
1173 .Vb 2
1174 \& unlink("alpha", "beta", "gamma")
1175 \& || (gripe(), next LINE);
1176 .Ve
1177 .PP
1178 It would be even more readable to write that this way:
1179 .PP
1180 .Vb 4
1181 \& unless(unlink("alpha", "beta", "gamma")) {
1182 \& gripe();
1183 \& next LINE;
1184 \& }
1185 .Ve
1186 .PP
1187 Using \f(CW"or"\fR for assignment is unlikely to do what you want; see below.
1188 .SS "Range Operators"
1189 .IX Xref "operator, range range .. ..."
1190 .IX Subsection "Range Operators"
1191 Binary \f(CW".."\fR is the range operator, which is really two different
1192 operators depending on the context. In list context, it returns a
1193 list of values counting (up by ones) from the left value to the right
1194 value. If the left value is greater than the right value then it
1195 returns the empty list. The range operator is useful for writing
1196 \&\f(CW\*(C`foreach\ (1..10)\*(C'\fR loops and for doing slice operations on arrays. In
1197 the current implementation, no temporary array is created when the
1198 range operator is used as the expression in \f(CW\*(C`foreach\*(C'\fR loops, but older
1199 versions of Perl might burn a lot of memory when you write something
1200 like this:
1201 .PP
1202 .Vb 3
1203 \& for (1 .. 1_000_000) {
1204 \& # code
1205 \& }
1206 .Ve
1207 .PP
1208 The range operator also works on strings, using the magical
1209 auto-increment, see below.
1210 .PP
1211 In scalar context, \f(CW".."\fR returns a boolean value. The operator is
1212 bistable, like a flip-flop, and emulates the line-range (comma)
1213 operator of \fBsed\fR, \fBawk\fR, and various editors. Each \f(CW".."\fR operator
1214 maintains its own boolean state, even across calls to a subroutine
1215 that contains it. It is false as long as its left operand is false.
1216 Once the left operand is true, the range operator stays true until the
1217 right operand is true, \fIAFTER\fR which the range operator becomes false
1218 again. It doesn't become false till the next time the range operator
1219 is evaluated. It can test the right operand and become false on the
1220 same evaluation it became true (as in \fBawk\fR), but it still returns
1221 true once. If you don't want it to test the right operand until the
1222 next evaluation, as in \fBsed\fR, just use three dots (\f(CW"..."\fR) instead of
1223 two. In all other regards, \f(CW"..."\fR behaves just like \f(CW".."\fR does.
1224 .PP
1225 The right operand is not evaluated while the operator is in the
1226 "false" state, and the left operand is not evaluated while the
1227 operator is in the "true" state. The precedence is a little lower
1228 than || and &&. The value returned is either the empty string for
1229 false, or a sequence number (beginning with 1) for true. The sequence
1230 number is reset for each range encountered. The final sequence number
1231 in a range has the string \f(CW"E0"\fR appended to it, which doesn't affect
1232 its numeric value, but gives you something to search for if you want
1233 to exclude the endpoint. You can exclude the beginning point by
1234 waiting for the sequence number to be greater than 1.
1235 .PP
1236 If either operand of scalar \f(CW".."\fR is a constant expression,
1237 that operand is considered true if it is equal (\f(CW\*(C`==\*(C'\fR) to the current
1238 input line number (the \f(CW$.\fR variable).
1239 .PP
1240 To be pedantic, the comparison is actually \f(CW\*(C`int(EXPR)\ ==\ int(EXPR)\*(C'\fR,
1241 but that is only an issue if you use a floating point expression; when
1242 implicitly using \f(CW$.\fR as described in the previous paragraph, the
1243 comparison is \f(CW\*(C`int(EXPR)\ ==\ int($.)\*(C'\fR which is only an issue when \f(CW$.\fR
1244 is set to a floating point value and you are not reading from a file.
1245 Furthermore, \f(CW"span"\ ..\ "spat"\fR or \f(CW\*(C`2.18\ ..\ 3.14\*(C'\fR will not do what
1246 you want in scalar context because each of the operands are evaluated
1247 using their integer representation.
1248 .PP
1249 Examples:
1250 .PP
1251 As a scalar operator:
1252 .PP
1253 .Vb 2
1254 \& if (101 .. 200) { print; } # print 2nd hundred lines, short for
1255 \& # if ($. == 101 .. $. == 200) { print; }
1256 \&
1257 \& next LINE if (1 .. /^$/); # skip header lines, short for
1258 \& # next LINE if ($. == 1 .. /^$/);
1259 \& # (typically in a loop labeled LINE)
1260 \&
1261 \& s/^/> / if (/^$/ .. eof()); # quote body
1262 \&
1263 \& # parse mail messages
1264 \& while (<>) {
1265 \& $in_header = 1 .. /^$/;
1266 \& $in_body = /^$/ .. eof;
1267 \& if ($in_header) {
1268 \& # do something
1269 \& } else { # in body
1270 \& # do something else
1271 \& }
1272 \& } continue {
1273 \& close ARGV if eof; # reset $. each file
1274 \& }
1275 .Ve
1276 .PP
1277 Here's a simple example to illustrate the difference between
1278 the two range operators:
1279 .PP
1280 .Vb 4
1281 \& @lines = (" \- Foo",
1282 \& "01 \- Bar",
1283 \& "1 \- Baz",
1284 \& " \- Quux");
1285 \&
1286 \& foreach (@lines) {
1287 \& if (/0/ .. /1/) {
1288 \& print "$_\en";
1289 \& }
1290 \& }
1291 .Ve
1292 .PP
1293 This program will print only the line containing "Bar". If
1294 the range operator is changed to \f(CW\*(C`...\*(C'\fR, it will also print the
1295 "Baz" line.
1296 .PP
1297 And now some examples as a list operator:
1298 .PP
1299 .Vb 3
1300 \& for (101 .. 200) { print } # print $_ 100 times
1301 \& @foo = @foo[0 .. $#foo]; # an expensive no\-op
1302 \& @foo = @foo[$#foo\-4 .. $#foo]; # slice last 5 items
1303 .Ve
1304 .PP
1305 Because each operand is evaluated in integer form, \f(CW\*(C`2.18\ ..\ 3.14\*(C'\fR will
1306 return two elements in list context.
1307 .PP
1308 .Vb 1
1309 \& @list = (2.18 .. 3.14); # same as @list = (2 .. 3);
1310 .Ve
1311 .PP
1312 The range operator in list context can make use of the magical
1313 auto-increment algorithm if both operands are strings, subject to the
1314 following rules:
1315 .IP \(bu 4
1316 With one exception (below), if both strings look like numbers to Perl,
1317 the magic increment will not be applied, and the strings will be treated
1318 as numbers (more specifically, integers) instead.
1319 .Sp
1320 For example, \f(CW"\-2".."2"\fR is the same as \f(CW\-2..2\fR, and
1321 \&\f(CW"2.18".."3.14"\fR produces \f(CW\*(C`2, 3\*(C'\fR.
1322 .IP \(bu 4
1323 The exception to the above rule is when the left-hand string begins with
1324 \&\f(CW0\fR and is longer than one character, in this case the magic increment
1325 \&\fIwill\fR be applied, even though strings like \f(CW"01"\fR would normally look
1326 like a number to Perl.
1327 .Sp
1328 For example, \f(CW"01".."04"\fR produces \f(CW"01", "02", "03", "04"\fR, and
1329 \&\f(CW"00".."\-1"\fR produces \f(CW"00"\fR through \f(CW"99"\fR \- this may seem
1330 surprising, but see the following rules for why it works this way.
1331 To get dates with leading zeros, you can say:
1332 .Sp
1333 .Vb 2
1334 \& @z2 = ("01" .. "31");
1335 \& print $z2[$mday];
1336 .Ve
1337 .Sp
1338 If you want to force strings to be interpreted as numbers, you could say
1339 .Sp
1340 .Vb 1
1341 \& @numbers = ( 0+$first .. 0+$last );
1342 .Ve
1343 .Sp
1344 \&\fBNote:\fR In Perl versions 5.30 and below, \fIany\fR string on the left-hand
1345 side beginning with \f(CW"0"\fR, including the string \f(CW"0"\fR itself, would
1346 cause the magic string increment behavior. This means that on these Perl
1347 versions, \f(CW"0".."\-1"\fR would produce \f(CW"0"\fR through \f(CW"99"\fR, which was
1348 inconsistent with \f(CW\*(C`0..\-1\*(C'\fR, which produces the empty list. This also means
1349 that \f(CW"0".."9"\fR now produces a list of integers instead of a list of
1350 strings.
1351 .IP \(bu 4
1352 If the initial value specified isn't part of a magical increment
1353 sequence (that is, a non-empty string matching \f(CW\*(C`/^[a\-zA\-Z]*[0\-9]*\ez/\*(C'\fR),
1354 only the initial value will be returned.
1355 .Sp
1356 For example, \f(CW"ax".."az"\fR produces \f(CW"ax", "ay", "az"\fR, but
1357 \&\f(CW"*x".."az"\fR produces only \f(CW"*x"\fR.
1358 .IP \(bu 4
1359 For other initial values that are strings that do follow the rules of the
1360 magical increment, the corresponding sequence will be returned.
1361 .Sp
1362 For example, you can say
1363 .Sp
1364 .Vb 1
1365 \& @alphabet = ("A" .. "Z");
1366 .Ve
1367 .Sp
1368 to get all normal letters of the English alphabet, or
1369 .Sp
1370 .Vb 1
1371 \& $hexdigit = (0 .. 9, "a" .. "f")[$num & 15];
1372 .Ve
1373 .Sp
1374 to get a hexadecimal digit.
1375 .IP \(bu 4
1376 If the final value specified is not in the sequence that the magical
1377 increment would produce, the sequence goes until the next value would
1378 be longer than the final value specified. If the length of the final
1379 string is shorter than the first, the empty list is returned.
1380 .Sp
1381 For example, \f(CW"a".."\-\-"\fR is the same as \f(CW"a".."zz"\fR, \f(CW"0".."xx"\fR
1382 produces \f(CW"0"\fR through \f(CW"99"\fR, and \f(CW"aaa".."\-\-"\fR returns the empty
1383 list.
1384 .PP
1385 As of Perl 5.26, the list-context range operator on strings works as expected
1386 in the scope of \f(CW"use\ feature\ \*(Aqunicode_strings"\fR. In previous versions, and outside the scope of
1387 that feature, it exhibits "The "Unicode Bug"" in perlunicode: its behavior
1388 depends on the internal encoding of the range endpoint.
1389 .PP
1390 Because the magical increment only works on non-empty strings matching
1391 \&\f(CW\*(C`/^[a\-zA\-Z]*[0\-9]*\ez/\*(C'\fR, the following will only return an alpha:
1392 .PP
1393 .Vb 2
1394 \& use charnames "greek";
1395 \& my @greek_small = ("\eN{alpha}" .. "\eN{omega}");
1396 .Ve
1397 .PP
1398 To get the 25 traditional lowercase Greek letters, including both sigmas,
1399 you could use this instead:
1400 .PP
1401 .Vb 5
1402 \& use charnames "greek";
1403 \& my @greek_small = map { chr } ( ord("\eN{alpha}")
1404 \& ..
1405 \& ord("\eN{omega}")
1406 \& );
1407 .Ve
1408 .PP
1409 However, because there are \fImany\fR other lowercase Greek characters than
1410 just those, to match lowercase Greek characters in a regular expression,
1411 you could use the pattern \f(CW\*(C`/(?:(?=\ep{Greek})\ep{Lower})+/\*(C'\fR (or the
1412 experimental feature \f(CW\*(C`/(?[\ \ep{Greek}\ &\ \ep{Lower}\ ])+/\*(C'\fR).
1413 .SS "Conditional Operator"
1414 .IX Xref "operator, conditional operator, ternary ternary ?:"
1415 .IX Subsection "Conditional Operator"
1416 Ternary \f(CW"?:"\fR is the conditional operator, just as in C. It works much
1417 like an if-then-else. If the argument before the \f(CW\*(C`?\*(C'\fR is true, the
1418 argument before the \f(CW\*(C`:\*(C'\fR is returned, otherwise the argument after the
1419 \&\f(CW\*(C`:\*(C'\fR is returned. For example:
1420 .PP
1421 .Vb 2
1422 \& printf "I have %d dog%s.\en", $n,
1423 \& ($n == 1) ? "" : "s";
1424 .Ve
1425 .PP
1426 Scalar or list context propagates downward into the 2nd
1427 or 3rd argument, whichever is selected.
1428 .PP
1429 .Vb 3
1430 \& $x = $ok ? $y : $z; # get a scalar
1431 \& @x = $ok ? @y : @z; # get an array
1432 \& $x = $ok ? @y : @z; # oops, that\*(Aqs just a count!
1433 .Ve
1434 .PP
1435 The operator may be assigned to if both the 2nd and 3rd arguments are
1436 legal lvalues (meaning that you can assign to them):
1437 .PP
1438 .Vb 1
1439 \& ($x_or_y ? $x : $y) = $z;
1440 .Ve
1441 .PP
1442 Because this operator produces an assignable result, using assignments
1443 without parentheses will get you in trouble. For example, this:
1444 .PP
1445 .Vb 1
1446 \& $x % 2 ? $x += 10 : $x += 2
1447 .Ve
1448 .PP
1449 Really means this:
1450 .PP
1451 .Vb 1
1452 \& (($x % 2) ? ($x += 10) : $x) += 2
1453 .Ve
1454 .PP
1455 Rather than this:
1456 .PP
1457 .Vb 1
1458 \& ($x % 2) ? ($x += 10) : ($x += 2)
1459 .Ve
1460 .PP
1461 That should probably be written more simply as:
1462 .PP
1463 .Vb 1
1464 \& $x += ($x % 2) ? 10 : 2;
1465 .Ve
1466 .SS "Assignment Operators"
1467 .IX Xref "assignment operator, assignment = **= += *= &= <<= &&= -= = |= >>= ||= = .= %= ^= x= &.= |.= ^.="
1468 .IX Subsection "Assignment Operators"
1469 \&\f(CW"="\fR is the ordinary assignment operator.
1470 .PP
1471 Assignment operators work as in C. That is,
1472 .PP
1473 .Vb 1
1474 \& $x += 2;
1475 .Ve
1476 .PP
1477 is equivalent to
1478 .PP
1479 .Vb 1
1480 \& $x = $x + 2;
1481 .Ve
1482 .PP
1483 although without duplicating any side effects that dereferencing the lvalue
1484 might trigger, such as from \f(CWtie()\fR. Other assignment operators work similarly.
1485 The following are recognized:
1486 .PP
1487 .Vb 4
1488 \& **= += *= &= &.= <<= &&=
1489 \& \-= /= |= |.= >>= ||=
1490 \& .= %= ^= ^.= //=
1491 \& x=
1492 .Ve
1493 .PP
1494 Although these are grouped by family, they all have the precedence
1495 of assignment. These combined assignment operators can only operate on
1496 scalars, whereas the ordinary assignment operator can assign to arrays,
1497 hashes, lists and even references. (See "Context"
1498 and "List value constructors" in perldata, and "Assigning to
1499 References" in perlref.)
1500 .PP
1501 Unlike in C, the scalar assignment operator produces a valid lvalue.
1502 Modifying an assignment is equivalent to doing the assignment and
1503 then modifying the variable that was assigned to. This is useful
1504 for modifying a copy of something, like this:
1505 .PP
1506 .Vb 1
1507 \& ($tmp = $global) =~ tr/13579/24680/;
1508 .Ve
1509 .PP
1510 Although as of 5.14, that can be also be accomplished this way:
1511 .PP
1512 .Vb 2
1513 \& use v5.14;
1514 \& $tmp = ($global =~ tr/13579/24680/r);
1515 .Ve
1516 .PP
1517 Likewise,
1518 .PP
1519 .Vb 1
1520 \& ($x += 2) *= 3;
1521 .Ve
1522 .PP
1523 is equivalent to
1524 .PP
1525 .Vb 2
1526 \& $x += 2;
1527 \& $x *= 3;
1528 .Ve
1529 .PP
1530 Similarly, a list assignment in list context produces the list of
1531 lvalues assigned to, and a list assignment in scalar context returns
1532 the number of elements produced by the expression on the right hand
1533 side of the assignment.
1534 .PP
1535 The three dotted bitwise assignment operators (\f(CW\*(C`&.=\*(C'\fR \f(CW\*(C`|.=\*(C'\fR \f(CW\*(C`^.=\*(C'\fR) are new in
1536 Perl 5.22. See "Bitwise String Operators".
1537 .SS "Comma Operator"
1538 .IX Xref "comma operator, comma ,"
1539 .IX Subsection "Comma Operator"
1540 Binary \f(CW","\fR is the comma operator. In scalar context it evaluates
1541 its left argument, throws that value away, then evaluates its right
1542 argument and returns that value. This is just like C's comma operator.
1543 .PP
1544 In list context, it's just the list argument separator, and inserts
1545 both its arguments into the list. These arguments are also evaluated
1546 from left to right.
1547 .PP
1548 The \f(CW\*(C`=>\*(C'\fR operator (sometimes pronounced "fat comma") is a synonym
1549 for the comma except that it causes a
1550 word on its left to be interpreted as a string if it begins with a letter
1551 or underscore and is composed only of letters, digits and underscores.
1552 This includes operands that might otherwise be interpreted as operators,
1553 constants, single number v\-strings or function calls. If in doubt about
1554 this behavior, the left operand can be quoted explicitly.
1555 .PP
1556 Otherwise, the \f(CW\*(C`=>\*(C'\fR operator behaves exactly as the comma operator
1557 or list argument separator, according to context.
1558 .PP
1559 For example:
1560 .PP
1561 .Vb 1
1562 \& use constant FOO => "something";
1563 \&
1564 \& my %h = ( FOO => 23 );
1565 .Ve
1566 .PP
1567 is equivalent to:
1568 .PP
1569 .Vb 1
1570 \& my %h = ("FOO", 23);
1571 .Ve
1572 .PP
1573 It is \fINOT\fR:
1574 .PP
1575 .Vb 1
1576 \& my %h = ("something", 23);
1577 .Ve
1578 .PP
1579 The \f(CW\*(C`=>\*(C'\fR operator is helpful in documenting the correspondence
1580 between keys and values in hashes, and other paired elements in lists.
1581 .PP
1582 .Vb 2
1583 \& %hash = ( $key => $value );
1584 \& login( $username => $password );
1585 .Ve
1586 .PP
1587 The special quoting behavior ignores precedence, and hence may apply to
1588 \&\fIpart\fR of the left operand:
1589 .PP
1590 .Vb 1
1591 \& print time.shift => "bbb";
1592 .Ve
1593 .PP
1594 That example prints something like \f(CW"1314363215shiftbbb"\fR, because the
1595 \&\f(CW\*(C`=>\*(C'\fR implicitly quotes the \f(CW\*(C`shift\*(C'\fR immediately on its left, ignoring
1596 the fact that \f(CW\*(C`time.shift\*(C'\fR is the entire left operand.
1597 .SS "List Operators (Rightward)"
1598 .IX Xref "operator, list, rightward list operator"
1599 .IX Subsection "List Operators (Rightward)"
1600 On the right side of a list operator, the comma has very low precedence,
1601 such that it controls all comma-separated expressions found there.
1602 The only operators with lower precedence are the logical operators
1603 \&\f(CW"and"\fR, \f(CW"or"\fR, and \f(CW"not"\fR, which may be used to evaluate calls to list
1604 operators without the need for parentheses:
1605 .PP
1606 .Vb 2
1607 \& open HANDLE, "< :encoding(UTF\-8)", "filename"
1608 \& or die "Can\*(Aqt open: $!\en";
1609 .Ve
1610 .PP
1611 However, some people find that code harder to read than writing
1612 it with parentheses:
1613 .PP
1614 .Vb 2
1615 \& open(HANDLE, "< :encoding(UTF\-8)", "filename")
1616 \& or die "Can\*(Aqt open: $!\en";
1617 .Ve
1618 .PP
1619 in which case you might as well just use the more customary \f(CW"||"\fR operator:
1620 .PP
1621 .Vb 2
1622 \& open(HANDLE, "< :encoding(UTF\-8)", "filename")
1623 \& || die "Can\*(Aqt open: $!\en";
1624 .Ve
1625 .PP
1626 See also discussion of list operators in "Terms and List Operators (Leftward)".
1627 .SS "Logical Not"
1628 .IX Xref "operator, logical, not not"
1629 .IX Subsection "Logical Not"
1630 Unary \f(CW"not"\fR returns the logical negation of the expression to its right.
1631 It's the equivalent of \f(CW"!"\fR except for the very low precedence.
1632 .SS "Logical And"
1633 .IX Xref "operator, logical, and and"
1634 .IX Subsection "Logical And"
1635 Binary \f(CW"and"\fR returns the logical conjunction of the two surrounding
1636 expressions. It's equivalent to \f(CW\*(C`&&\*(C'\fR except for the very low
1637 precedence. This means that it short-circuits: the right
1638 expression is evaluated only if the left expression is true.
1639 .SS "Logical or and Exclusive Or"
1640 .IX Xref "operator, logical, or operator, logical, xor operator, logical, exclusive or or xor"
1641 .IX Subsection "Logical or and Exclusive Or"
1642 Binary \f(CW"or"\fR returns the logical disjunction of the two surrounding
1643 expressions. It's equivalent to \f(CW\*(C`||\*(C'\fR except for the very low precedence.
1644 This makes it useful for control flow:
1645 .PP
1646 .Vb 1
1647 \& print FH $data or die "Can\*(Aqt write to FH: $!";
1648 .Ve
1649 .PP
1650 This means that it short-circuits: the right expression is evaluated
1651 only if the left expression is false. Due to its precedence, you must
1652 be careful to avoid using it as replacement for the \f(CW\*(C`||\*(C'\fR operator.
1653 It usually works out better for flow control than in assignments:
1654 .PP
1655 .Vb 3
1656 \& $x = $y or $z; # bug: this is wrong
1657 \& ($x = $y) or $z; # really means this
1658 \& $x = $y || $z; # better written this way
1659 .Ve
1660 .PP
1661 However, when it's a list-context assignment and you're trying to use
1662 \&\f(CW\*(C`||\*(C'\fR for control flow, you probably need \f(CW"or"\fR so that the assignment
1663 takes higher precedence.
1664 .PP
1665 .Vb 2
1666 \& @info = stat($file) || die; # oops, scalar sense of stat!
1667 \& @info = stat($file) or die; # better, now @info gets its due
1668 .Ve
1669 .PP
1670 Then again, you could always use parentheses.
1671 .PP
1672 Binary \f(CW"xor"\fR returns the exclusive-OR of the two surrounding expressions.
1673 It cannot short-circuit (of course).
1674 .PP
1675 There is no low precedence operator for defined-OR.
1676 .SS "C Operators Missing From Perl"
1677 .IX Xref "operator, missing from perl & * typecasting (TYPE)"
1678 .IX Subsection "C Operators Missing From Perl"
1679 Here is what C has that Perl doesn't:
1680 .IP "unary &" 8
1681 .IX Item "unary &"
1682 Address-of operator. (But see the \f(CW"\e"\fR operator for taking a reference.)
1683 .IP "unary *" 8
1684 .IX Item "unary *"
1685 Dereference-address operator. (Perl's prefix dereferencing
1686 operators are typed: \f(CW\*(C`$\*(C'\fR, \f(CW\*(C`@\*(C'\fR, \f(CW\*(C`%\*(C'\fR, and \f(CW\*(C`&\*(C'\fR.)
1687 .IP (TYPE) 8
1688 .IX Item "(TYPE)"
1689 Type-casting operator.
1690 .SS "Quote and Quote-like Operators"
1691 .IX Xref "operator, quote operator, quote-like q qq qx qw m qr s tr ' '' "" """" ` `` << escape sequence escape"
1692 .IX Subsection "Quote and Quote-like Operators"
1693 While we usually think of quotes as literal values, in Perl they
1694 function as operators, providing various kinds of interpolating and
1695 pattern matching capabilities. Perl provides customary quote characters
1696 for these behaviors, but also provides a way for you to choose your
1697 quote character for any of them. In the following table, a \f(CW\*(C`{}\*(C'\fR represents
1698 any pair of delimiters you choose.
1699 .PP
1700 .Vb 11
1701 \& Customary Generic Meaning Interpolates
1702 \& \*(Aq\*(Aq q{} Literal no
1703 \& "" qq{} Literal yes
1704 \& \`\` qx{} Command yes*
1705 \& qw{} Word list no
1706 \& // m{} Pattern match yes*
1707 \& qr{} Pattern yes*
1708 \& s{}{} Substitution yes*
1709 \& tr{}{} Transliteration no (but see below)
1710 \& y{}{} Transliteration no (but see below)
1711 \& <<EOF here\-doc yes*
1712 \&
1713 \& * unless the delimiter is \*(Aq\*(Aq.
1714 .Ve
1715 .PP
1716 Non-bracketing delimiters use the same character fore and aft, but the four
1717 sorts of ASCII brackets (round, angle, square, curly) all nest, which means
1718 that
1719 .PP
1720 .Vb 1
1721 \& q{foo{bar}baz}
1722 .Ve
1723 .PP
1724 is the same as
1725 .PP
1726 .Vb 1
1727 \& \*(Aqfoo{bar}baz\*(Aq
1728 .Ve
1729 .PP
1730 Note, however, that this does not always work for quoting Perl code:
1731 .PP
1732 .Vb 1
1733 \& $s = q{ if($x eq "}") ... }; # WRONG
1734 .Ve
1735 .PP
1736 is a syntax error. The \f(CW\*(C`Text::Balanced\*(C'\fR module (standard as of v5.8,
1737 and from CPAN before then) is able to do this properly.
1738 .PP
1739 If the \f(CW\*(C`extra_paired_delimiters\*(C'\fR feature is enabled, then Perl will
1740 additionally recognise a variety of Unicode characters as being paired. For
1741 a full list, see the "List of Extra Paired Delimiters" at the end of this
1742 document.
1743 .PP
1744 There can (and in some cases, must) be whitespace between the operator
1745 and the quoting
1746 characters, except when \f(CW\*(C`#\*(C'\fR is being used as the quoting character.
1747 \&\f(CW\*(C`q#foo#\*(C'\fR is parsed as the string \f(CW\*(C`foo\*(C'\fR, while \f(CW\*(C`q\ #foo#\*(C'\fR is the
1748 operator \f(CW\*(C`q\*(C'\fR followed by a comment. Its argument will be taken
1749 from the next line. This allows you to write:
1750 .PP
1751 .Vb 2
1752 \& s {foo} # Replace foo
1753 \& {bar} # with bar.
1754 .Ve
1755 .PP
1756 The cases where whitespace must be used are when the quoting character
1757 is a word character (meaning it matches \f(CW\*(C`/\ew/\*(C'\fR):
1758 .PP
1759 .Vb 2
1760 \& q XfooX # Works: means the string \*(Aqfoo\*(Aq
1761 \& qXfooX # WRONG!
1762 .Ve
1763 .PP
1764 The following escape sequences are available in constructs that interpolate,
1765 and in transliterations whose delimiters aren't single quotes (\f(CW"\*(Aq"\fR).
1766 In all the ones with braces, any number of blanks and/or tabs adjoining
1767 and within the braces are allowed (and ignored).
1768 .IX Xref "\\t \\n \\r \\f \\b \\a \\e \\x \\0 \\c \\N \\N{} \\o{}"
1769 .PP
1770 .Vb 10
1771 \& Sequence Note Description
1772 \& \et tab (HT, TAB)
1773 \& \en newline (NL)
1774 \& \er return (CR)
1775 \& \ef form feed (FF)
1776 \& \eb backspace (BS)
1777 \& \ea alarm (bell) (BEL)
1778 \& \ee escape (ESC)
1779 \& \ex{263A} [1,8] hex char (example shown: SMILEY)
1780 \& \ex{ 263A } Same, but shows optional blanks inside and
1781 \& adjoining the braces
1782 \& \ex1b [2,8] restricted range hex char (example: ESC)
1783 \& \eN{name} [3] named Unicode character or character sequence
1784 \& \eN{U+263D} [4,8] Unicode character (example: FIRST QUARTER MOON)
1785 \& \ec[ [5] control char (example: chr(27))
1786 \& \eo{23072} [6,8] octal char (example: SMILEY)
1787 \& \e033 [7,8] restricted range octal char (example: ESC)
1788 .Ve
1789 .PP
1790 Note that any escape sequence using braces inside interpolated
1791 constructs may have optional blanks (tab or space characters) adjoining
1792 with and inside of the braces, as illustrated above by the second
1793 \&\f(CW\*(C`\ex{\ }\*(C'\fR example.
1794 .IP [1] 4
1795 .IX Item "[1]"
1796 The result is the character specified by the hexadecimal number between
1797 the braces. See "[8]" below for details on which character.
1798 .Sp
1799 Blanks (tab or space characters) may separate the number from either or
1800 both of the braces.
1801 .Sp
1802 Otherwise, only hexadecimal digits are valid between the braces. If an
1803 invalid character is encountered, a warning will be issued and the
1804 invalid character and all subsequent characters (valid or invalid)
1805 within the braces will be discarded.
1806 .Sp
1807 If there are no valid digits between the braces, the generated character is
1808 the NULL character (\f(CW\*(C`\ex{00}\*(C'\fR). However, an explicit empty brace (\f(CW\*(C`\ex{}\*(C'\fR)
1809 will not cause a warning (currently).
1810 .IP [2] 4
1811 .IX Item "[2]"
1812 The result is the character specified by the hexadecimal number in the range
1813 0x00 to 0xFF. See "[8]" below for details on which character.
1814 .Sp
1815 Only hexadecimal digits are valid following \f(CW\*(C`\ex\*(C'\fR. When \f(CW\*(C`\ex\*(C'\fR is followed
1816 by fewer than two valid digits, any valid digits will be zero-padded. This
1817 means that \f(CW\*(C`\ex7\*(C'\fR will be interpreted as \f(CW\*(C`\ex07\*(C'\fR, and a lone \f(CW"\ex"\fR will be
1818 interpreted as \f(CW\*(C`\ex00\*(C'\fR. Except at the end of a string, having fewer than
1819 two valid digits will result in a warning. Note that although the warning
1820 says the illegal character is ignored, it is only ignored as part of the
1821 escape and will still be used as the subsequent character in the string.
1822 For example:
1823 .Sp
1824 .Vb 5
1825 \& Original Result Warns?
1826 \& "\ex7" "\ex07" no
1827 \& "\ex" "\ex00" no
1828 \& "\ex7q" "\ex07q" yes
1829 \& "\exq" "\ex00q" yes
1830 .Ve
1831 .IP [3] 4
1832 .IX Item "[3]"
1833 The result is the Unicode character or character sequence given by \fIname\fR.
1834 See charnames.
1835 .IP [4] 4
1836 .IX Item "[4]"
1837 \&\f(CW\*(C`\eN{U+\fR\f(CIhexadecimal\ number\fR\f(CW}\*(C'\fR means the Unicode character whose Unicode code
1838 point is \fIhexadecimal number\fR.
1839 .IP [5] 4
1840 .IX Item "[5]"
1841 The character following \f(CW\*(C`\ec\*(C'\fR is mapped to some other character as shown in the
1842 table:
1843 .Sp
1844 .Vb 10
1845 \& Sequence Value
1846 \& \ec@ chr(0)
1847 \& \ecA chr(1)
1848 \& \eca chr(1)
1849 \& \ecB chr(2)
1850 \& \ecb chr(2)
1851 \& ...
1852 \& \ecZ chr(26)
1853 \& \ecz chr(26)
1854 \& \ec[ chr(27)
1855 \& # See below for chr(28)
1856 \& \ec] chr(29)
1857 \& \ec^ chr(30)
1858 \& \ec_ chr(31)
1859 \& \ec? chr(127) # (on ASCII platforms; see below for link to
1860 \& # EBCDIC discussion)
1861 .Ve
1862 .Sp
1863 In other words, it's the character whose code point has had 64 xor'd with
1864 its uppercase. \f(CW\*(C`\ec?\*(C'\fR is DELETE on ASCII platforms because
1865 \&\f(CW\*(C`ord("?")\ ^\ 64\*(C'\fR is 127, and
1866 \&\f(CW\*(C`\ec@\*(C'\fR is NULL because the ord of \f(CW"@"\fR is 64, so xor'ing 64 itself produces 0.
1867 .Sp
1868 Also, \f(CW\*(C`\ec\e\fR\f(CIX\fR\f(CW\*(C'\fR yields \f(CW\*(C`\ chr(28)\ .\ "\fR\f(CIX\fR\f(CW"\*(C'\fR for any \fIX\fR, but cannot come at the
1869 end of a string, because the backslash would be parsed as escaping the end
1870 quote.
1871 .Sp
1872 On ASCII platforms, the resulting characters from the list above are the
1873 complete set of ASCII controls. This isn't the case on EBCDIC platforms; see
1874 "OPERATOR DIFFERENCES" in perlebcdic for a full discussion of the
1875 differences between these for ASCII versus EBCDIC platforms.
1876 .Sp
1877 Use of any other character following the \f(CW"c"\fR besides those listed above is
1878 discouraged, and as of Perl v5.20, the only characters actually allowed
1879 are the printable ASCII ones, minus the left brace \f(CW"{"\fR. What happens
1880 for any of the allowed other characters is that the value is derived by
1881 xor'ing with the seventh bit, which is 64, and a warning raised if
1882 enabled. Using the non-allowed characters generates a fatal error.
1883 .Sp
1884 To get platform independent controls, you can use \f(CW\*(C`\eN{...}\*(C'\fR.
1885 .IP [6] 4
1886 .IX Item "[6]"
1887 The result is the character specified by the octal number between the braces.
1888 See "[8]" below for details on which character.
1889 .Sp
1890 Blanks (tab or space characters) may separate the number from either or
1891 both of the braces.
1892 .Sp
1893 Otherwise, if a character that isn't an octal digit is encountered, a
1894 warning is raised, and the value is based on the octal digits before it,
1895 discarding it and all following characters up to the closing brace. It
1896 is a fatal error if there are no octal digits at all.
1897 .IP [7] 4
1898 .IX Item "[7]"
1899 The result is the character specified by the three-digit octal number in the
1900 range 000 to 777 (but best to not use above 077, see next paragraph). See
1901 "[8]" below for details on which character.
1902 .Sp
1903 Some contexts allow 2 or even 1 digit, but any usage without exactly
1904 three digits, the first being a zero, may give unintended results. (For
1905 example, in a regular expression it may be confused with a backreference;
1906 see "Octal escapes" in perlrebackslash.) Starting in Perl 5.14, you may
1907 use \f(CW\*(C`\eo{}\*(C'\fR instead, which avoids all these problems. Otherwise, it is best to
1908 use this construct only for ordinals \f(CW\*(C`\e077\*(C'\fR and below, remembering to pad to
1909 the left with zeros to make three digits. For larger ordinals, either use
1910 \&\f(CW\*(C`\eo{}\*(C'\fR, or convert to something else, such as to hex and use \f(CW\*(C`\eN{U+}\*(C'\fR
1911 (which is portable between platforms with different character sets) or
1912 \&\f(CW\*(C`\ex{}\*(C'\fR instead.
1913 .IP [8] 4
1914 .IX Item "[8]"
1915 Several constructs above specify a character by a number. That number
1916 gives the character's position in the character set encoding (indexed from 0).
1917 This is called synonymously its ordinal, code position, or code point. Perl
1918 works on platforms that have a native encoding currently of either ASCII/Latin1
1919 or EBCDIC, each of which allow specification of 256 characters. In general, if
1920 the number is 255 (0xFF, 0377) or below, Perl interprets this in the platform's
1921 native encoding. If the number is 256 (0x100, 0400) or above, Perl interprets
1922 it as a Unicode code point and the result is the corresponding Unicode
1923 character. For example \f(CW\*(C`\ex{50}\*(C'\fR and \f(CW\*(C`\eo{120}\*(C'\fR both are the number 80 in
1924 decimal, which is less than 256, so the number is interpreted in the native
1925 character set encoding. In ASCII the character in the 80th position (indexed
1926 from 0) is the letter \f(CW"P"\fR, and in EBCDIC it is the ampersand symbol \f(CW"&"\fR.
1927 \&\f(CW\*(C`\ex{100}\*(C'\fR and \f(CW\*(C`\eo{400}\*(C'\fR are both 256 in decimal, so the number is interpreted
1928 as a Unicode code point no matter what the native encoding is. The name of the
1929 character in the 256th position (indexed by 0) in Unicode is
1930 \&\f(CW\*(C`LATIN CAPITAL LETTER A WITH MACRON\*(C'\fR.
1931 .Sp
1932 An exception to the above rule is that \f(CW\*(C`\eN{U+\fR\f(CIhex\ number\fR\f(CW}\*(C'\fR is
1933 always interpreted as a Unicode code point, so that \f(CW\*(C`\eN{U+0050}\*(C'\fR is \f(CW"P"\fR even
1934 on EBCDIC platforms.
1935 .PP
1936 \&\fBNOTE\fR: Unlike C and other languages, Perl has no \f(CW\*(C`\ev\*(C'\fR escape sequence for
1937 the vertical tab (VT, which is 11 in both ASCII and EBCDIC), but you may
1938 use \f(CW\*(C`\eN{VT}\*(C'\fR, \f(CW\*(C`\eck\*(C'\fR, \f(CW\*(C`\eN{U+0b}\*(C'\fR, or \f(CW\*(C`\ex0b\*(C'\fR. (\f(CW\*(C`\ev\*(C'\fR
1939 does have meaning in regular expression patterns in Perl, see perlre.)
1940 .PP
1941 The following escape sequences are available in constructs that interpolate,
1942 but not in transliterations.
1943 .IX Xref "\\l \\u \\L \\U \\E \\Q \\F"
1944 .PP
1945 .Vb 9
1946 \& \el lowercase next character only
1947 \& \eu titlecase (not uppercase!) next character only
1948 \& \eL lowercase all characters till \eE or end of string
1949 \& \eU uppercase all characters till \eE or end of string
1950 \& \eF foldcase all characters till \eE or end of string
1951 \& \eQ quote (disable) pattern metacharacters till \eE or
1952 \& end of string
1953 \& \eE end either case modification or quoted section
1954 \& (whichever was last seen)
1955 .Ve
1956 .PP
1957 See "quotemeta" in perlfunc for the exact definition of characters that
1958 are quoted by \f(CW\*(C`\eQ\*(C'\fR.
1959 .PP
1960 \&\f(CW\*(C`\eL\*(C'\fR, \f(CW\*(C`\eU\*(C'\fR, \f(CW\*(C`\eF\*(C'\fR, and \f(CW\*(C`\eQ\*(C'\fR can stack, in which case you need one
1961 \&\f(CW\*(C`\eE\*(C'\fR for each. For example:
1962 .PP
1963 .Vb 2
1964 \& say "This \eQquoting \eubusiness \eUhere isn\*(Aqt quite\eE done yet,\eE is it?";
1965 \& This quoting\e Business\e HERE\e ISN\e\*(AqT\e QUITE\e done\e yet\e, is it?
1966 .Ve
1967 .PP
1968 If a \f(CW\*(C`use\ locale\*(C'\fR form that includes \f(CW\*(C`LC_CTYPE\*(C'\fR is in effect (see
1969 perllocale), the case map used by \f(CW\*(C`\el\*(C'\fR, \f(CW\*(C`\eL\*(C'\fR, \f(CW\*(C`\eu\*(C'\fR, and \f(CW\*(C`\eU\*(C'\fR is
1970 taken from the current locale. If Unicode (for example, \f(CW\*(C`\eN{}\*(C'\fR or code
1971 points of 0x100 or beyond) is being used, the case map used by \f(CW\*(C`\el\*(C'\fR,
1972 \&\f(CW\*(C`\eL\*(C'\fR, \f(CW\*(C`\eu\*(C'\fR, and \f(CW\*(C`\eU\*(C'\fR is as defined by Unicode. That means that
1973 case-mapping a single character can sometimes produce a sequence of
1974 several characters.
1975 Under \f(CW\*(C`use\ locale\*(C'\fR, \f(CW\*(C`\eF\*(C'\fR produces the same results as \f(CW\*(C`\eL\*(C'\fR
1976 for all locales but a UTF\-8 one, where it instead uses the Unicode
1977 definition.
1978 .PP
1979 All systems use the virtual \f(CW"\en"\fR to represent a line terminator,
1980 called a "newline". There is no such thing as an unvarying, physical
1981 newline character. It is only an illusion that the operating system,
1982 device drivers, C libraries, and Perl all conspire to preserve. Not all
1983 systems read \f(CW"\er"\fR as ASCII CR and \f(CW"\en"\fR as ASCII LF. For example,
1984 on the ancient Macs (pre-MacOS X) of yesteryear, these used to be reversed,
1985 and on systems without a line terminator,
1986 printing \f(CW"\en"\fR might emit no actual data. In general, use \f(CW"\en"\fR when
1987 you mean a "newline" for your system, but use the literal ASCII when you
1988 need an exact character. For example, most networking protocols expect
1989 and prefer a CR+LF (\f(CW"\e015\e012"\fR or \f(CW"\ecM\ecJ"\fR) for line terminators,
1990 and although they often accept just \f(CW"\e012"\fR, they seldom tolerate just
1991 \&\f(CW"\e015"\fR. If you get in the habit of using \f(CW"\en"\fR for networking,
1992 you may be burned some day.
1993 .IX Xref "newline line terminator eol end of line \\n \\r \\r\\n"
1994 .PP
1995 For constructs that do interpolate, variables beginning with "\f(CW\*(C`$\*(C'\fR"
1996 or "\f(CW\*(C`@\*(C'\fR" are interpolated. Subscripted variables such as \f(CW$a[3]\fR or
1997 \&\f(CW\*(C`$href\->{key}[0]\*(C'\fR are also interpolated, as are array and hash slices.
1998 But method calls such as \f(CW\*(C`$obj\->meth\*(C'\fR are not.
1999 .PP
2000 Interpolating an array or slice interpolates the elements in order,
2001 separated by the value of \f(CW$"\fR, so is equivalent to interpolating
2002 \&\f(CW\*(C`join\ $",\ @array\*(C'\fR. "Punctuation" arrays such as \f(CW\*(C`@*\*(C'\fR are usually
2003 interpolated only if the name is enclosed in braces \f(CW\*(C`@{*}\*(C'\fR, but the
2004 arrays \f(CW@_\fR, \f(CW\*(C`@+\*(C'\fR, and \f(CW\*(C`@\-\*(C'\fR are interpolated even without braces.
2005 .PP
2006 For double-quoted strings, the quoting from \f(CW\*(C`\eQ\*(C'\fR is applied after
2007 interpolation and escapes are processed.
2008 .PP
2009 .Vb 1
2010 \& "abc\eQfoo\etbar$s\eExyz"
2011 .Ve
2012 .PP
2013 is equivalent to
2014 .PP
2015 .Vb 1
2016 \& "abc" . quotemeta("foo\etbar$s") . "xyz"
2017 .Ve
2018 .PP
2019 For the pattern of regex operators (\f(CW\*(C`qr//\*(C'\fR, \f(CW\*(C`m//\*(C'\fR and \f(CW\*(C`s///\*(C'\fR),
2020 the quoting from \f(CW\*(C`\eQ\*(C'\fR is applied after interpolation is processed,
2021 but before escapes are processed. This allows the pattern to match
2022 literally (except for \f(CW\*(C`$\*(C'\fR and \f(CW\*(C`@\*(C'\fR). For example, the following matches:
2023 .PP
2024 .Vb 1
2025 \& \*(Aq\es\et\*(Aq =~ /\eQ\es\et/
2026 .Ve
2027 .PP
2028 Because \f(CW\*(C`$\*(C'\fR or \f(CW\*(C`@\*(C'\fR trigger interpolation, you'll need to use something
2029 like \f(CW\*(C`/\eQuser\eE\e@\eQhost/\*(C'\fR to match them literally.
2030 .PP
2031 Patterns are subject to an additional level of interpretation as a
2032 regular expression. This is done as a second pass, after variables are
2033 interpolated, so that regular expressions may be incorporated into the
2034 pattern from the variables. If this is not what you want, use \f(CW\*(C`\eQ\*(C'\fR to
2035 interpolate a variable literally.
2036 .PP
2037 Apart from the behavior described above, Perl does not expand
2038 multiple levels of interpolation. In particular, contrary to the
2039 expectations of shell programmers, back-quotes do \fINOT\fR interpolate
2040 within double quotes, nor do single quotes impede evaluation of
2041 variables when used within double quotes.
2042 .SS "Regexp Quote-Like Operators"
2043 .IX Xref "operator, regexp"
2044 .IX Subsection "Regexp Quote-Like Operators"
2045 Here are the quote-like operators that apply to pattern
2046 matching and related activities.
2047 .ie n .IP """qr/\fISTRING\fR/msixpodualn""" 8
2048 .el .IP \f(CWqr/\fR\f(CISTRING\fR\f(CW/msixpodualn\fR 8
2049 .IX Xref "qr i m o s x p"
2050 .IX Item "qr/STRING/msixpodualn"
2051 This operator quotes (and possibly compiles) its \fISTRING\fR as a regular
2052 expression. \fISTRING\fR is interpolated the same way as \fIPATTERN\fR
2053 in \f(CW\*(C`m/\fR\f(CIPATTERN\fR\f(CW/\*(C'\fR. If \f(CW"\*(Aq"\fR is used as the delimiter, no variable
2054 interpolation is done. Returns a Perl value which may be used instead of the
2055 corresponding \f(CW\*(C`/\fR\f(CISTRING\fR\f(CW/msixpodualn\*(C'\fR expression. The returned value is a
2056 normalized version of the original pattern. It magically differs from
2057 a string containing the same characters: \f(CWref(qr/x/)\fR returns "Regexp";
2058 however, dereferencing it is not well defined (you currently get the
2059 normalized version of the original pattern, but this may change).
2060 .Sp
2061 For example,
2062 .Sp
2063 .Vb 3
2064 \& $rex = qr/my.STRING/is;
2065 \& print $rex; # prints (?si\-xm:my.STRING)
2066 \& s/$rex/foo/;
2067 .Ve
2068 .Sp
2069 is equivalent to
2070 .Sp
2071 .Vb 1
2072 \& s/my.STRING/foo/is;
2073 .Ve
2074 .Sp
2075 The result may be used as a subpattern in a match:
2076 .Sp
2077 .Vb 5
2078 \& $re = qr/$pattern/;
2079 \& $string =~ /foo${re}bar/; # can be interpolated in other
2080 \& # patterns
2081 \& $string =~ $re; # or used standalone
2082 \& $string =~ /$re/; # or this way
2083 .Ve
2084 .Sp
2085 Since Perl may compile the pattern at the moment of execution of the \f(CWqr()\fR
2086 operator, using \f(CWqr()\fR may have speed advantages in some situations,
2087 notably if the result of \f(CWqr()\fR is used standalone:
2088 .Sp
2089 .Vb 11
2090 \& sub match {
2091 \& my $patterns = shift;
2092 \& my @compiled = map qr/$_/i, @$patterns;
2093 \& grep {
2094 \& my $success = 0;
2095 \& foreach my $pat (@compiled) {
2096 \& $success = 1, last if /$pat/;
2097 \& }
2098 \& $success;
2099 \& } @_;
2100 \& }
2101 .Ve
2102 .Sp
2103 Precompilation of the pattern into an internal representation at
2104 the moment of \f(CWqr()\fR avoids the need to recompile the pattern every
2105 time a match \f(CW\*(C`/$pat/\*(C'\fR is attempted. (Perl has many other internal
2106 optimizations, but none would be triggered in the above example if
2107 we did not use \f(CWqr()\fR operator.)
2108 .Sp
2109 Options (specified by the following modifiers) are:
2110 .Sp
2111 .Vb 10
2112 \& m Treat string as multiple lines.
2113 \& s Treat string as single line. (Make . match a newline)
2114 \& i Do case\-insensitive pattern matching.
2115 \& x Use extended regular expressions; specifying two
2116 \& x\*(Aqs means \et and the SPACE character are ignored within
2117 \& square\-bracketed character classes
2118 \& p When matching preserve a copy of the matched string so
2119 \& that ${^PREMATCH}, ${^MATCH}, ${^POSTMATCH} will be
2120 \& defined (ignored starting in v5.20 as these are always
2121 \& defined starting in that release)
2122 \& o Compile pattern only once.
2123 \& a ASCII\-restrict: Use ASCII for \ed, \es, \ew and [[:posix:]]
2124 \& character classes; specifying two a\*(Aqs adds the further
2125 \& restriction that no ASCII character will match a
2126 \& non\-ASCII one under /i.
2127 \& l Use the current run\-time locale\*(Aqs rules.
2128 \& u Use Unicode rules.
2129 \& d Use Unicode or native charset, as in 5.12 and earlier.
2130 \& n Non\-capture mode. Don\*(Aqt let () fill in $1, $2, etc...
2131 .Ve
2132 .Sp
2133 If a precompiled pattern is embedded in a larger pattern then the effect
2134 of \f(CW"msixpluadn"\fR will be propagated appropriately. The effect that the
2135 \&\f(CW\*(C`/o\*(C'\fR modifier has is not propagated, being restricted to those patterns
2136 explicitly using it.
2137 .Sp
2138 The \f(CW\*(C`/a\*(C'\fR, \f(CW\*(C`/d\*(C'\fR, \f(CW\*(C`/l\*(C'\fR, and \f(CW\*(C`/u\*(C'\fR modifiers (added in Perl 5.14)
2139 control the character set rules, but \f(CW\*(C`/a\*(C'\fR is the only one you are likely
2140 to want to specify explicitly; the other three are selected
2141 automatically by various pragmas.
2142 .Sp
2143 See perlre for additional information on valid syntax for \fISTRING\fR, and
2144 for a detailed look at the semantics of regular expressions. In
2145 particular, all modifiers except the largely obsolete \f(CW\*(C`/o\*(C'\fR are further
2146 explained in "Modifiers" in perlre. \f(CW\*(C`/o\*(C'\fR is described in the next section.
2147 .ie n .IP """m/\fIPATTERN\fR/msixpodualngc""" 8
2148 .el .IP \f(CWm/\fR\f(CIPATTERN\fR\f(CW/msixpodualngc\fR 8
2149 .IX Xref "m operator, match regexp, options regexp regex, options regex m s i x p o g c"
2150 .IX Item "m/PATTERN/msixpodualngc"
2151 .PD 0
2152 .ie n .IP """/\fIPATTERN\fR/msixpodualngc""" 8
2153 .el .IP \f(CW/\fR\f(CIPATTERN\fR\f(CW/msixpodualngc\fR 8
2154 .IX Item "/PATTERN/msixpodualngc"
2155 .PD
2156 Searches a string for a pattern match, and in scalar context returns
2157 true if it succeeds, false if it fails. If no string is specified
2158 via the \f(CW\*(C`=~\*(C'\fR or \f(CW\*(C`!~\*(C'\fR operator, the \f(CW$_\fR string is searched. (The
2159 string specified with \f(CW\*(C`=~\*(C'\fR need not be an lvalue\-\-it may be the
2160 result of an expression evaluation, but remember the \f(CW\*(C`=~\*(C'\fR binds
2161 rather tightly.) See also perlre.
2162 .Sp
2163 Options are as described in \f(CW\*(C`qr//\*(C'\fR above; in addition, the following match
2164 process modifiers are available:
2165 .Sp
2166 .Vb 3
2167 \& g Match globally, i.e., find all occurrences.
2168 \& c Do not reset search position on a failed match when /g is
2169 \& in effect.
2170 .Ve
2171 .Sp
2172 If \f(CW"/"\fR is the delimiter then the initial \f(CW\*(C`m\*(C'\fR is optional. With the \f(CW\*(C`m\*(C'\fR
2173 you can use any pair of non-whitespace (ASCII) characters
2174 as delimiters. This is particularly useful for matching path names
2175 that contain \f(CW"/"\fR, to avoid LTS (leaning toothpick syndrome). If \f(CW"?"\fR is
2176 the delimiter, then a match-only-once rule applies,
2177 described in \f(CW\*(C`m?\fR\f(CIPATTERN\fR\f(CW?\*(C'\fR below. If \f(CW"\*(Aq"\fR (single quote) is the delimiter,
2178 no variable interpolation is performed on the \fIPATTERN\fR.
2179 When using a delimiter character valid in an identifier, whitespace is required
2180 after the \f(CW\*(C`m\*(C'\fR.
2181 .Sp
2182 \&\fIPATTERN\fR may contain variables, which will be interpolated
2183 every time the pattern search is evaluated, except
2184 for when the delimiter is a single quote. (Note that \f(CW$(\fR, \f(CW$)\fR, and
2185 \&\f(CW$|\fR are not interpolated because they look like end-of-string tests.)
2186 Perl will not recompile the pattern unless an interpolated
2187 variable that it contains changes. You can force Perl to skip the
2188 test and never recompile by adding a \f(CW\*(C`/o\*(C'\fR (which stands for "once")
2189 after the trailing delimiter.
2190 Once upon a time, Perl would recompile regular expressions
2191 unnecessarily, and this modifier was useful to tell it not to do so, in the
2192 interests of speed. But now, the only reasons to use \f(CW\*(C`/o\*(C'\fR are one of:
2193 .RS 8
2194 .IP 1. 4
2195 The variables are thousands of characters long and you know that they
2196 don't change, and you need to wring out the last little bit of speed by
2197 having Perl skip testing for that. (There is a maintenance penalty for
2198 doing this, as mentioning \f(CW\*(C`/o\*(C'\fR constitutes a promise that you won't
2199 change the variables in the pattern. If you do change them, Perl won't
2200 even notice.)
2201 .IP 2. 4
2202 you want the pattern to use the initial values of the variables
2203 regardless of whether they change or not. (But there are saner ways
2204 of accomplishing this than using \f(CW\*(C`/o\*(C'\fR.)
2205 .IP 3. 4
2206 If the pattern contains embedded code, such as
2207 .Sp
2208 .Vb 3
2209 \& use re \*(Aqeval\*(Aq;
2210 \& $code = \*(Aqfoo(?{ $x })\*(Aq;
2211 \& /$code/
2212 .Ve
2213 .Sp
2214 then perl will recompile each time, even though the pattern string hasn't
2215 changed, to ensure that the current value of \f(CW$x\fR is seen each time.
2216 Use \f(CW\*(C`/o\*(C'\fR if you want to avoid this.
2217 .RE
2218 .RS 8
2219 .Sp
2220 The bottom line is that using \f(CW\*(C`/o\*(C'\fR is almost never a good idea.
2221 .RE
2222 .ie n .IP "The empty pattern ""//""" 8
2223 .el .IP "The empty pattern \f(CW//\fR" 8
2224 .IX Item "The empty pattern //"
2225 If the \fIPATTERN\fR evaluates to the empty string, the last
2226 \&\fIsuccessfully\fR matched regular expression in the current dynamic
2227 scope is used instead (see also "Scoping Rules of Regex Variables" in perlvar).
2228 In this case, only the \f(CW\*(C`g\*(C'\fR and \f(CW\*(C`c\*(C'\fR flags on the empty pattern are
2229 honored; the other flags are taken from the original pattern. If no
2230 match has previously succeeded, this will (silently) act instead as a
2231 genuine empty pattern (which will always match). Using a user supplied
2232 string as a pattern has the risk that if the string is empty that it
2233 triggers the "last successful match" behavior, which can be very
2234 confusing. In such cases you are recommended to replace \f(CW\*(C`m/$pattern/\*(C'\fR
2235 with \f(CW\*(C`m/(?:$pattern)/\*(C'\fR to avoid this behavior.
2236 .Sp
2237 The last successful pattern may be accessed as a variable via
2238 \&\f(CW\*(C`${^LAST_SUCCESSFUL_PATTERN}\*(C'\fR. Matching against it, or the empty
2239 pattern should have the same effect, with the exception that when there
2240 is no last successful pattern the empty pattern will silently match,
2241 whereas using the \f(CW\*(C`${^LAST_SUCCESSFUL_PATTERN}\*(C'\fR variable will produce
2242 undefined warnings (if warnings are enabled). You can check
2243 \&\f(CWdefined(${^LAST_SUCCESSFUL_PATTERN})\fR to test if there is a "last
2244 successful match" in the current scope.
2245 .Sp
2246 Note that it's possible to confuse Perl into thinking \f(CW\*(C`//\*(C'\fR (the empty
2247 regex) is really \f(CW\*(C`//\*(C'\fR (the defined-or operator). Perl is usually pretty
2248 good about this, but some pathological cases might trigger this, such as
2249 \&\f(CW\*(C`$x///\*(C'\fR (is that \f(CW\*(C`($x)\ /\ (//)\*(C'\fR or \f(CW\*(C`$x\ //\ /\*(C'\fR?) and \f(CW\*(C`print\ $fh\ //\*(C'\fR
2250 (\f(CW\*(C`print\ $fh(//\*(C'\fR or \f(CW\*(C`print($fh\ //\*(C'\fR?). In all of these examples, Perl
2251 will assume you meant defined-or. If you meant the empty regex, just
2252 use parentheses or spaces to disambiguate, or even prefix the empty
2253 regex with an \f(CW\*(C`m\*(C'\fR (so \f(CW\*(C`//\*(C'\fR becomes \f(CW\*(C`m//\*(C'\fR).
2254 .IP "Matching in list context" 8
2255 .IX Item "Matching in list context"
2256 If the \f(CW\*(C`/g\*(C'\fR option is not used, \f(CW\*(C`m//\*(C'\fR in list context returns a
2257 list consisting of the subexpressions matched by the parentheses in the
2258 pattern, that is, (\f(CW$1\fR, \f(CW$2\fR, \f(CW$3\fR...) (Note that here \f(CW$1\fR etc. are
2259 also set). When there are no parentheses in the pattern, the return
2260 value is the list \f(CW\*(C`(1)\*(C'\fR for success.
2261 With or without parentheses, an empty list is returned upon failure.
2262 .Sp
2263 Examples:
2264 .Sp
2265 .Vb 2
2266 \& open(TTY, "+</dev/tty")
2267 \& || die "can\*(Aqt access /dev/tty: $!";
2268 \&
2269 \& <TTY> =~ /^y/i && foo(); # do foo if desired
2270 \&
2271 \& if (/Version: *([0\-9.]*)/) { $version = $1; }
2272 \&
2273 \& next if m#^/usr/spool/uucp#;
2274 \&
2275 \& # poor man\*(Aqs grep
2276 \& $arg = shift;
2277 \& while (<>) {
2278 \& print if /$arg/;
2279 \& }
2280 \& if (($F1, $F2, $Etc) = ($foo =~ /^(\eS+)\es+(\eS+)\es*(.*)/))
2281 .Ve
2282 .Sp
2283 This last example splits \f(CW$foo\fR into the first two words and the
2284 remainder of the line, and assigns those three fields to \f(CW$F1\fR, \f(CW$F2\fR, and
2285 \&\f(CW$Etc\fR. The conditional is true if any variables were assigned; that is,
2286 if the pattern matched.
2287 .Sp
2288 The \f(CW\*(C`/g\*(C'\fR modifier specifies global pattern matching\-\-that is,
2289 matching as many times as possible within the string. How it behaves
2290 depends on the context. In list context, it returns a list of the
2291 substrings matched by any capturing parentheses in the regular
2292 expression. If there are no parentheses, it returns a list of all
2293 the matched strings, as if there were parentheses around the whole
2294 pattern.
2295 .Sp
2296 In scalar context, each execution of \f(CW\*(C`m//g\*(C'\fR finds the next match,
2297 returning true if it matches, and false if there is no further match.
2298 The position after the last match can be read or set using the \f(CWpos()\fR
2299 function; see "pos" in perlfunc. A failed match normally resets the
2300 search position to the beginning of the string, but you can avoid that
2301 by adding the \f(CW\*(C`/c\*(C'\fR modifier (for example, \f(CW\*(C`m//gc\*(C'\fR). Modifying the target
2302 string also resets the search position.
2303 .ie n .IP """\eG \fIassertion\fR""" 8
2304 .el .IP "\f(CW\eG \fR\f(CIassertion\fR\f(CW\fR" 8
2305 .IX Item "G assertion"
2306 You can intermix \f(CW\*(C`m//g\*(C'\fR matches with \f(CW\*(C`m/\eG.../g\*(C'\fR, where \f(CW\*(C`\eG\*(C'\fR is a
2307 zero-width assertion that matches the exact position where the
2308 previous \f(CW\*(C`m//g\*(C'\fR, if any, left off. Without the \f(CW\*(C`/g\*(C'\fR modifier, the
2309 \&\f(CW\*(C`\eG\*(C'\fR assertion still anchors at \f(CWpos()\fR as it was at the start of
2310 the operation (see "pos" in perlfunc), but the match is of course only
2311 attempted once. Using \f(CW\*(C`\eG\*(C'\fR without \f(CW\*(C`/g\*(C'\fR on a target string that has
2312 not previously had a \f(CW\*(C`/g\*(C'\fR match applied to it is the same as using
2313 the \f(CW\*(C`\eA\*(C'\fR assertion to match the beginning of the string. Note also
2314 that, currently, \f(CW\*(C`\eG\*(C'\fR is only properly supported when anchored at the
2315 very beginning of the pattern.
2316 .Sp
2317 Examples:
2318 .Sp
2319 .Vb 2
2320 \& # list context
2321 \& ($one,$five,$fifteen) = (\`uptime\` =~ /(\ed+\e.\ed+)/g);
2322 \&
2323 \& # scalar context
2324 \& local $/ = "";
2325 \& while ($paragraph = <>) {
2326 \& while ($paragraph =~ /\ep{Ll}[\*(Aq")]*[.!?]+[\*(Aq")]*\es/g) {
2327 \& $sentences++;
2328 \& }
2329 \& }
2330 \& say $sentences;
2331 .Ve
2332 .Sp
2333 Here's another way to check for sentences in a paragraph:
2334 .Sp
2335 .Vb 10
2336 \& my $sentence_rx = qr{
2337 \& (?: (?<= ^ ) | (?<= \es ) ) # after start\-of\-string or
2338 \& # whitespace
2339 \& \ep{Lu} # capital letter
2340 \& .*? # a bunch of anything
2341 \& (?<= \eS ) # that ends in non\-
2342 \& # whitespace
2343 \& (?<! \eb [DMS]r ) # but isn\*(Aqt a common abbr.
2344 \& (?<! \eb Mrs )
2345 \& (?<! \eb Sra )
2346 \& (?<! \eb St )
2347 \& [.?!] # followed by a sentence
2348 \& # ender
2349 \& (?= $ | \es ) # in front of end\-of\-string
2350 \& # or whitespace
2351 \& }sx;
2352 \& local $/ = "";
2353 \& while (my $paragraph = <>) {
2354 \& say "NEW PARAGRAPH";
2355 \& my $count = 0;
2356 \& while ($paragraph =~ /($sentence_rx)/g) {
2357 \& printf "\etgot sentence %d: <%s>\en", ++$count, $1;
2358 \& }
2359 \& }
2360 .Ve
2361 .Sp
2362 Here's how to use \f(CW\*(C`m//gc\*(C'\fR with \f(CW\*(C`\eG\*(C'\fR:
2363 .Sp
2364 .Vb 10
2365 \& $_ = "ppooqppqq";
2366 \& while ($i++ < 2) {
2367 \& print "1: \*(Aq";
2368 \& print $1 while /(o)/gc; print "\*(Aq, pos=", pos, "\en";
2369 \& print "2: \*(Aq";
2370 \& print $1 if /\eG(q)/gc; print "\*(Aq, pos=", pos, "\en";
2371 \& print "3: \*(Aq";
2372 \& print $1 while /(p)/gc; print "\*(Aq, pos=", pos, "\en";
2373 \& }
2374 \& print "Final: \*(Aq$1\*(Aq, pos=",pos,"\en" if /\eG(.)/;
2375 .Ve
2376 .Sp
2377 The last example should print:
2378 .Sp
2379 .Vb 7
2380 \& 1: \*(Aqoo\*(Aq, pos=4
2381 \& 2: \*(Aqq\*(Aq, pos=5
2382 \& 3: \*(Aqpp\*(Aq, pos=7
2383 \& 1: \*(Aq\*(Aq, pos=7
2384 \& 2: \*(Aqq\*(Aq, pos=8
2385 \& 3: \*(Aq\*(Aq, pos=8
2386 \& Final: \*(Aqq\*(Aq, pos=8
2387 .Ve
2388 .Sp
2389 Notice that the final match matched \f(CW\*(C`q\*(C'\fR instead of \f(CW\*(C`p\*(C'\fR, which a match
2390 without the \f(CW\*(C`\eG\*(C'\fR anchor would have done. Also note that the final match
2391 did not update \f(CW\*(C`pos\*(C'\fR. \f(CW\*(C`pos\*(C'\fR is only updated on a \f(CW\*(C`/g\*(C'\fR match. If the
2392 final match did indeed match \f(CW\*(C`p\*(C'\fR, it's a good bet that you're running an
2393 ancient (pre\-5.6.0) version of Perl.
2394 .Sp
2395 A useful idiom for \f(CW\*(C`lex\*(C'\fR\-like scanners is \f(CW\*(C`/\eG.../gc\*(C'\fR. You can
2396 combine several regexps like this to process a string part-by-part,
2397 doing different actions depending on which regexp matched. Each
2398 regexp tries to match where the previous one leaves off.
2399 .Sp
2400 .Vb 4
2401 \& $_ = <<\*(AqEOL\*(Aq;
2402 \& $url = URI::URL\->new( "http://example.com/" );
2403 \& die if $url eq "xXx";
2404 \& EOL
2405 \&
2406 \& LOOP: {
2407 \& print(" digits"), redo LOOP if /\eG\ed+\eb[,.;]?\es*/gc;
2408 \& print(" lowercase"), redo LOOP
2409 \& if /\eG\ep{Ll}+\eb[,.;]?\es*/gc;
2410 \& print(" UPPERCASE"), redo LOOP
2411 \& if /\eG\ep{Lu}+\eb[,.;]?\es*/gc;
2412 \& print(" Capitalized"), redo LOOP
2413 \& if /\eG\ep{Lu}\ep{Ll}+\eb[,.;]?\es*/gc;
2414 \& print(" MiXeD"), redo LOOP if /\eG\epL+\eb[,.;]?\es*/gc;
2415 \& print(" alphanumeric"), redo LOOP
2416 \& if /\eG[\ep{Alpha}\epN]+\eb[,.;]?\es*/gc;
2417 \& print(" line\-noise"), redo LOOP if /\eG\eW+/gc;
2418 \& print ". That\*(Aqs all!\en";
2419 \& }
2420 .Ve
2421 .Sp
2422 Here is the output (split into several lines):
2423 .Sp
2424 .Vb 4
2425 \& line\-noise lowercase line\-noise UPPERCASE line\-noise UPPERCASE
2426 \& line\-noise lowercase line\-noise lowercase line\-noise lowercase
2427 \& lowercase line\-noise lowercase lowercase line\-noise lowercase
2428 \& lowercase line\-noise MiXeD line\-noise. That\*(Aqs all!
2429 .Ve
2430 .ie n .IP """m?\fIPATTERN\fR?msixpodualngc""" 8
2431 .el .IP \f(CWm?\fR\f(CIPATTERN\fR\f(CW?msixpodualngc\fR 8
2432 .IX Xref "? operator, match-once"
2433 .IX Item "m?PATTERN?msixpodualngc"
2434 This is just like the \f(CW\*(C`m/\fR\f(CIPATTERN\fR\f(CW/\*(C'\fR search, except that it matches
2435 only once between calls to the \f(CWreset()\fR operator. This is a useful
2436 optimization when you want to see only the first occurrence of
2437 something in each file of a set of files, for instance. Only \f(CW\*(C`m??\*(C'\fR
2438 patterns local to the current package are reset.
2439 .Sp
2440 .Vb 7
2441 \& while (<>) {
2442 \& if (m?^$?) {
2443 \& # blank line between header and body
2444 \& }
2445 \& } continue {
2446 \& reset if eof; # clear m?? status for next file
2447 \& }
2448 .Ve
2449 .Sp
2450 Another example switched the first "latin1" encoding it finds
2451 to "utf8" in a pod file:
2452 .Sp
2453 .Vb 1
2454 \& s//utf8/ if m? ^ =encoding \eh+ \eK latin1 ?x;
2455 .Ve
2456 .Sp
2457 The match-once behavior is controlled by the match delimiter being
2458 \&\f(CW\*(C`?\*(C'\fR; with any other delimiter this is the normal \f(CW\*(C`m//\*(C'\fR operator.
2459 .Sp
2460 In the past, the leading \f(CW\*(C`m\*(C'\fR in \f(CW\*(C`m?\fR\f(CIPATTERN\fR\f(CW?\*(C'\fR was optional, but omitting it
2461 would produce a deprecation warning. As of v5.22.0, omitting it produces a
2462 syntax error. If you encounter this construct in older code, you can just add
2463 \&\f(CW\*(C`m\*(C'\fR.
2464 .ie n .IP """s/\fIPATTERN\fR/\fIREPLACEMENT\fR/msixpodualngcer""" 8
2465 .el .IP \f(CWs/\fR\f(CIPATTERN\fR\f(CW/\fR\f(CIREPLACEMENT\fR\f(CW/msixpodualngcer\fR 8
2466 .IX Xref "s substitute substitution replace regexp, replace regexp, substitute m s i x p o g c e r"
2467 .IX Item "s/PATTERN/REPLACEMENT/msixpodualngcer"
2468 Searches a string for a pattern, and if found, replaces that pattern
2469 with the replacement text and returns the number of substitutions
2470 made. Otherwise it returns false (a value that is both an empty string (\f(CW""\fR)
2471 and numeric zero (\f(CW0\fR) as described in "Relational Operators").
2472 .Sp
2473 If the \f(CW\*(C`/r\*(C'\fR (non-destructive) option is used then it runs the
2474 substitution on a copy of the string and instead of returning the
2475 number of substitutions, it returns the copy whether or not a
2476 substitution occurred. The original string is never changed when
2477 \&\f(CW\*(C`/r\*(C'\fR is used. The copy will always be a plain string, even if the
2478 input is an object or a tied variable.
2479 .Sp
2480 If no string is specified via the \f(CW\*(C`=~\*(C'\fR or \f(CW\*(C`!~\*(C'\fR operator, the \f(CW$_\fR
2481 variable is searched and modified. Unless the \f(CW\*(C`/r\*(C'\fR option is used,
2482 the string specified must be a scalar variable, an array element, a
2483 hash element, or an assignment to one of those; that is, some sort of
2484 scalar lvalue.
2485 .Sp
2486 If the delimiter chosen is a single quote, no variable interpolation is
2487 done on either the \fIPATTERN\fR or the \fIREPLACEMENT\fR. Otherwise, if the
2488 \&\fIPATTERN\fR contains a \f(CW\*(C`$\*(C'\fR that looks like a variable rather than an
2489 end-of-string test, the variable will be interpolated into the pattern
2490 at run-time. If you want the pattern compiled only once the first time
2491 the variable is interpolated, use the \f(CW\*(C`/o\*(C'\fR option. If the pattern
2492 evaluates to the empty string, the last successfully executed regular
2493 expression is used instead. See perlre for further explanation on these.
2494 .Sp
2495 Options are as with \f(CW\*(C`m//\*(C'\fR with the addition of the following replacement
2496 specific options:
2497 .Sp
2498 .Vb 5
2499 \& e Evaluate the right side as an expression.
2500 \& ee Evaluate the right side as a string then eval the
2501 \& result.
2502 \& r Return substitution and leave the original string
2503 \& untouched.
2504 .Ve
2505 .Sp
2506 Any non-whitespace delimiter may replace the slashes. Add space after
2507 the \f(CW\*(C`s\*(C'\fR when using a character allowed in identifiers. If single quotes
2508 are used, no interpretation is done on the replacement string (the \f(CW\*(C`/e\*(C'\fR
2509 modifier overrides this, however). Note that Perl treats backticks
2510 as normal delimiters; the replacement text is not evaluated as a command.
2511 If the \fIPATTERN\fR is delimited by bracketing quotes, the \fIREPLACEMENT\fR has
2512 its own pair of quotes, which may or may not be bracketing quotes, for example,
2513 \&\f(CW\*(C`s(foo)(bar)\*(C'\fR or \f(CW\*(C`s<foo>/bar/\*(C'\fR. A \f(CW\*(C`/e\*(C'\fR will cause the
2514 replacement portion to be treated as a full-fledged Perl expression
2515 and evaluated right then and there. It is, however, syntax checked at
2516 compile-time. A second \f(CW\*(C`e\*(C'\fR modifier will cause the replacement portion
2517 to be \f(CW\*(C`eval\*(C'\fRed before being run as a Perl expression.
2518 .Sp
2519 Examples:
2520 .Sp
2521 .Vb 1
2522 \& s/\ebgreen\eb/mauve/g; # don\*(Aqt change wintergreen
2523 \&
2524 \& $path =~ s|/usr/bin|/usr/local/bin|;
2525 \&
2526 \& s/Login: $foo/Login: $bar/; # run\-time pattern
2527 \&
2528 \& ($foo = $bar) =~ s/this/that/; # copy first, then
2529 \& # change
2530 \& ($foo = "$bar") =~ s/this/that/; # convert to string,
2531 \& # copy, then change
2532 \& $foo = $bar =~ s/this/that/r; # Same as above using /r
2533 \& $foo = $bar =~ s/this/that/r
2534 \& =~ s/that/the other/r; # Chained substitutes
2535 \& # using /r
2536 \& @foo = map { s/this/that/r } @bar # /r is very useful in
2537 \& # maps
2538 \&
2539 \& $count = ($paragraph =~ s/Mister\eb/Mr./g); # get change\-cnt
2540 \&
2541 \& $_ = \*(Aqabc123xyz\*(Aq;
2542 \& s/\ed+/$&*2/e; # yields \*(Aqabc246xyz\*(Aq
2543 \& s/\ed+/sprintf("%5d",$&)/e; # yields \*(Aqabc 246xyz\*(Aq
2544 \& s/\ew/$& x 2/eg; # yields \*(Aqaabbcc 224466xxyyzz\*(Aq
2545 \&
2546 \& s/%(.)/$percent{$1}/g; # change percent escapes; no /e
2547 \& s/%(.)/$percent{$1} || $&/ge; # expr now, so /e
2548 \& s/^=(\ew+)/pod($1)/ge; # use function call
2549 \&
2550 \& $_ = \*(Aqabc123xyz\*(Aq;
2551 \& $x = s/abc/def/r; # $x is \*(Aqdef123xyz\*(Aq and
2552 \& # $_ remains \*(Aqabc123xyz\*(Aq.
2553 \&
2554 \& # expand variables in $_, but dynamics only, using
2555 \& # symbolic dereferencing
2556 \& s/\e$(\ew+)/${$1}/g;
2557 \&
2558 \& # Add one to the value of any numbers in the string
2559 \& s/(\ed+)/1 + $1/eg;
2560 \&
2561 \& # Titlecase words in the last 30 characters only (presuming
2562 \& # that the substring doesn\*(Aqt start in the middle of a word)
2563 \& substr($str, \-30) =~ s/\eb(\ep{Alpha})(\ep{Alpha}*)\eb/\eu$1\eL$2/g;
2564 \&
2565 \& # This will expand any embedded scalar variable
2566 \& # (including lexicals) in $_ : First $1 is interpolated
2567 \& # to the variable name, and then evaluated
2568 \& s/(\e$\ew+)/$1/eeg;
2569 \&
2570 \& # Delete (most) C comments.
2571 \& $program =~ s {
2572 \& /\e* # Match the opening delimiter.
2573 \& .*? # Match a minimal number of characters.
2574 \& \e*/ # Match the closing delimiter.
2575 \& } []gsx;
2576 \&
2577 \& s/^\es*(.*?)\es*$/$1/; # trim whitespace in $_,
2578 \& # expensively
2579 \&
2580 \& for ($variable) { # trim whitespace in $variable,
2581 \& # cheap
2582 \& s/^\es+//;
2583 \& s/\es+$//;
2584 \& }
2585 \&
2586 \& s/([^ ]*) *([^ ]*)/$2 $1/; # reverse 1st two fields
2587 \&
2588 \& $foo !~ s/A/a/g; # Lowercase all A\*(Aqs in $foo; return
2589 \& # 0 if any were found and changed;
2590 \& # otherwise return 1
2591 .Ve
2592 .Sp
2593 Note the use of \f(CW\*(C`$\*(C'\fR instead of \f(CW\*(C`\e\*(C'\fR in the last example. Unlike
2594 \&\fBsed\fR, we use the \e<\fIdigit\fR> form only in the left hand side.
2595 Anywhere else it's $<\fIdigit\fR>.
2596 .Sp
2597 Occasionally, you can't use just a \f(CW\*(C`/g\*(C'\fR to get all the changes
2598 to occur that you might want. Here are two common cases:
2599 .Sp
2600 .Vb 2
2601 \& # put commas in the right places in an integer
2602 \& 1 while s/(\ed)(\ed\ed\ed)(?!\ed)/$1,$2/g;
2603 \&
2604 \& # expand tabs to 8\-column spacing
2605 \& 1 while s/\et+/\*(Aq \*(Aq x (length($&)*8 \- length($\`)%8)/e;
2606 .Ve
2607 .Sp
2608 While \f(CW\*(C`s///\*(C'\fR accepts the \f(CW\*(C`/c\*(C'\fR flag, it has no effect beyond
2609 producing a warning if warnings are enabled.
2610 .IX Xref " c"
2611 .SS "Quote-Like Operators"
2612 .IX Xref "operator, quote-like"
2613 .IX Subsection "Quote-Like Operators"
2614 .ie n .IP """q/\fISTRING\fR/""" 4
2615 .el .IP \f(CWq/\fR\f(CISTRING\fR\f(CW/\fR 4
2616 .IX Xref "q quote, single ' ''"
2617 .IX Item "q/STRING/"
2618 .PD 0
2619 .ie n .IP \*(Aq\fISTRING\fR\*(Aq 4
2620 .el .IP \f(CW\*(Aq\fR\f(CISTRING\fR\f(CW\*(Aq\fR 4
2621 .IX Item "STRING"
2622 .PD
2623 A single-quoted, literal string. A backslash represents a backslash
2624 unless followed by the delimiter or another backslash, in which case
2625 the delimiter or backslash is interpolated.
2626 .Sp
2627 .Vb 3
2628 \& $foo = q!I said, "You said, \*(AqShe said it.\*(Aq"!;
2629 \& $bar = q(\*(AqThis is it.\*(Aq);
2630 \& $baz = \*(Aq\en\*(Aq; # a two\-character string
2631 .Ve
2632 .ie n .IP """qq/\fISTRING\fR/""" 4
2633 .el .IP \f(CWqq/\fR\f(CISTRING\fR\f(CW/\fR 4
2634 .IX Xref "qq quote, double "" """""
2635 .IX Item "qq/STRING/"
2636 .PD 0
2637 .ie n .IP """\fISTRING\fR""" 4
2638 .el .IP "\f(CW""\fR\f(CISTRING\fR\f(CW""\fR" 4
2639 .IX Item """STRING"""
2640 .PD
2641 A double-quoted, interpolated string.
2642 .Sp
2643 .Vb 4
2644 \& $_ .= qq
2645 \& (*** The previous line contains the naughty word "$1".\en)
2646 \& if /\eb(tcl|java|python)\eb/i; # :\-)
2647 \& $baz = "\en"; # a one\-character string
2648 .Ve
2649 .ie n .IP """qx/\fISTRING\fR/""" 4
2650 .el .IP \f(CWqx/\fR\f(CISTRING\fR\f(CW/\fR 4
2651 .IX Xref "qx ` `` backtick"
2652 .IX Item "qx/STRING/"
2653 .PD 0
2654 .ie n .IP \`\fISTRING\fR\` 4
2655 .el .IP \f(CW\`\fR\f(CISTRING\fR\f(CW\`\fR 4
2656 .IX Item "STRING"
2657 .PD
2658 A string which is (possibly) interpolated and then executed as a
2659 system command, via \fI/bin/sh\fR or its equivalent if required. Shell
2660 wildcards, pipes, and redirections will be honored. Similarly to
2661 \&\f(CW\*(C`system\*(C'\fR, if the string contains no shell metacharacters then it will
2662 executed directly. The collected standard output of the command is
2663 returned; standard error is unaffected. In scalar context, it comes
2664 back as a single (potentially multi-line) string, or \f(CW\*(C`undef\*(C'\fR if the
2665 shell (or command) could not be started. In list context, returns a
2666 list of lines (however you've defined lines with \f(CW$/\fR or
2667 \&\f(CW$INPUT_RECORD_SEPARATOR\fR), or an empty list if the shell (or command)
2668 could not be started.
2669 .Sp
2670 .Vb 1
2671 \& print qx/date/; # prints "Sun Jan 28 06:16:19 CST 2024"
2672 .Ve
2673 .Sp
2674 Because backticks do not affect standard error, use shell file descriptor
2675 syntax (assuming the shell supports this) if you care to address this.
2676 To capture a command's STDERR and STDOUT together:
2677 .Sp
2678 .Vb 1
2679 \& $output = \`cmd 2>&1\`;
2680 .Ve
2681 .Sp
2682 To capture a command's STDOUT but discard its STDERR:
2683 .Sp
2684 .Vb 1
2685 \& $output = \`cmd 2>/dev/null\`;
2686 .Ve
2687 .Sp
2688 To capture a command's STDERR but discard its STDOUT (ordering is
2689 important here):
2690 .Sp
2691 .Vb 1
2692 \& $output = \`cmd 2>&1 1>/dev/null\`;
2693 .Ve
2694 .Sp
2695 To exchange a command's STDOUT and STDERR in order to capture the STDERR
2696 but leave its STDOUT to come out the old STDERR:
2697 .Sp
2698 .Vb 1
2699 \& $output = \`cmd 3>&1 1>&2 2>&3 3>&\-\`;
2700 .Ve
2701 .Sp
2702 To read both a command's STDOUT and its STDERR separately, it's easiest
2703 to redirect them separately to files, and then read from those files
2704 when the program is done:
2705 .Sp
2706 .Vb 1
2707 \& system("program args 1>program.stdout 2>program.stderr");
2708 .Ve
2709 .Sp
2710 The STDIN filehandle used by the command is inherited from Perl's STDIN.
2711 For example:
2712 .Sp
2713 .Vb 3
2714 \& open(SPLAT, "stuff") || die "can\*(Aqt open stuff: $!";
2715 \& open(STDIN, "<&SPLAT") || die "can\*(Aqt dupe SPLAT: $!";
2716 \& print STDOUT \`sort\`;
2717 .Ve
2718 .Sp
2719 will print the sorted contents of the file named \fI"stuff"\fR.
2720 .Sp
2721 Using single-quote as a delimiter protects the command from Perl's
2722 double-quote interpolation, passing it on to the shell instead:
2723 .Sp
2724 .Vb 2
2725 \& $perl_info = qx(ps $$); # that\*(Aqs Perl\*(Aqs $$
2726 \& $shell_info = qx\*(Aqps $$\*(Aq; # that\*(Aqs the new shell\*(Aqs $$
2727 .Ve
2728 .Sp
2729 How that string gets evaluated is entirely subject to the command
2730 interpreter on your system. On most platforms, you will have to protect
2731 shell metacharacters if you want them treated literally. This is in
2732 practice difficult to do, as it's unclear how to escape which characters.
2733 See perlsec for a clean and safe example of a manual \f(CWfork()\fR and \f(CWexec()\fR
2734 to emulate backticks safely.
2735 .Sp
2736 On some platforms (notably DOS-like ones), the shell may not be
2737 capable of dealing with multiline commands, so putting newlines in
2738 the string may not get you what you want. You may be able to evaluate
2739 multiple commands in a single line by separating them with the command
2740 separator character, if your shell supports that (for example, \f(CW\*(C`;\*(C'\fR on
2741 many Unix shells and \f(CW\*(C`&\*(C'\fR on the Windows NT \f(CW\*(C`cmd\*(C'\fR shell).
2742 .Sp
2743 Perl will attempt to flush all files opened for
2744 output before starting the child process, but this may not be supported
2745 on some platforms (see perlport). To be safe, you may need to set
2746 \&\f(CW$|\fR (\f(CW$AUTOFLUSH\fR in \f(CW\*(C`English\*(C'\fR) or call the \f(CWautoflush()\fR method of
2747 \&\f(CW\*(C`IO::Handle\*(C'\fR on any open handles.
2748 .Sp
2749 Beware that some command shells may place restrictions on the length
2750 of the command line. You must ensure your strings don't exceed this
2751 limit after any necessary interpolations. See the platform-specific
2752 release notes for more details about your particular environment.
2753 .Sp
2754 Using this operator can lead to programs that are difficult to port,
2755 because the shell commands called vary between systems, and may in
2756 fact not be present at all. As one example, the \f(CW\*(C`type\*(C'\fR command under
2757 the POSIX shell is very different from the \f(CW\*(C`type\*(C'\fR command under DOS.
2758 That doesn't mean you should go out of your way to avoid backticks
2759 when they're the right way to get something done. Perl was made to be
2760 a glue language, and one of the things it glues together is commands.
2761 Just understand what you're getting yourself into.
2762 .Sp
2763 Like \f(CW\*(C`system\*(C'\fR, backticks put the child process exit code in \f(CW$?\fR.
2764 If you'd like to manually inspect failure, you can check all possible
2765 failure modes by inspecting \f(CW$?\fR like this:
2766 .Sp
2767 .Vb 10
2768 \& if ($? == \-1) {
2769 \& print "failed to execute: $!\en";
2770 \& }
2771 \& elsif ($? & 127) {
2772 \& printf "child died with signal %d, %s coredump\en",
2773 \& ($? & 127), ($? & 128) ? \*(Aqwith\*(Aq : \*(Aqwithout\*(Aq;
2774 \& }
2775 \& else {
2776 \& printf "child exited with value %d\en", $? >> 8;
2777 \& }
2778 .Ve
2779 .Sp
2780 Use the open pragma to control the I/O layers used when reading the
2781 output of the command, for example:
2782 .Sp
2783 .Vb 2
2784 \& use open IN => ":encoding(UTF\-8)";
2785 \& my $x = \`cmd\-producing\-utf\-8\`;
2786 .Ve
2787 .Sp
2788 \&\f(CW\*(C`qx//\*(C'\fR can also be called like a function with "readpipe" in perlfunc.
2789 .Sp
2790 See "I/O Operators" for more discussion.
2791 .ie n .IP """qw/\fISTRING\fR/""" 4
2792 .el .IP \f(CWqw/\fR\f(CISTRING\fR\f(CW/\fR 4
2793 .IX Xref "qw quote, list quote, words"
2794 .IX Item "qw/STRING/"
2795 Evaluates to a list of the words extracted out of \fISTRING\fR, using embedded
2796 whitespace as the word delimiters. It can be understood as being roughly
2797 equivalent to:
2798 .Sp
2799 .Vb 1
2800 \& split(" ", q/STRING/);
2801 .Ve
2802 .Sp
2803 the differences being that it only splits on ASCII whitespace,
2804 generates a real list at compile time, and
2805 in scalar context it returns the last element in the list. So
2806 this expression:
2807 .Sp
2808 .Vb 1
2809 \& qw(foo bar baz)
2810 .Ve
2811 .Sp
2812 is semantically equivalent to the list:
2813 .Sp
2814 .Vb 1
2815 \& "foo", "bar", "baz"
2816 .Ve
2817 .Sp
2818 Some frequently seen examples:
2819 .Sp
2820 .Vb 2
2821 \& use POSIX qw( setlocale localeconv )
2822 \& @EXPORT = qw( foo bar baz );
2823 .Ve
2824 .Sp
2825 A common mistake is to try to separate the words with commas or to
2826 put comments into a multi-line \f(CW\*(C`qw\*(C'\fR\-string. For this reason, the
2827 \&\f(CW\*(C`use\ warnings\*(C'\fR pragma and the \fB\-w\fR switch (that is, the \f(CW$^W\fR variable)
2828 produces warnings if the \fISTRING\fR contains the \f(CW","\fR or the \f(CW"#"\fR character.
2829 .ie n .IP """tr/\fISEARCHLIST\fR/\fIREPLACEMENTLIST\fR/cdsr""" 4
2830 .el .IP \f(CWtr/\fR\f(CISEARCHLIST\fR\f(CW/\fR\f(CIREPLACEMENTLIST\fR\f(CW/cdsr\fR 4
2831 .IX Xref "tr y transliterate c d s"
2832 .IX Item "tr/SEARCHLIST/REPLACEMENTLIST/cdsr"
2833 .PD 0
2834 .ie n .IP """y/\fISEARCHLIST\fR/\fIREPLACEMENTLIST\fR/cdsr""" 4
2835 .el .IP \f(CWy/\fR\f(CISEARCHLIST\fR\f(CW/\fR\f(CIREPLACEMENTLIST\fR\f(CW/cdsr\fR 4
2836 .IX Item "y/SEARCHLIST/REPLACEMENTLIST/cdsr"
2837 .PD
2838 Transliterates all occurrences of the characters found (or not found
2839 if the \f(CW\*(C`/c\*(C'\fR modifier is specified) in the search list with the
2840 positionally corresponding character in the replacement list, possibly
2841 deleting some, depending on the modifiers specified. It returns the
2842 number of characters replaced or deleted. If no string is specified via
2843 the \f(CW\*(C`=~\*(C'\fR or \f(CW\*(C`!~\*(C'\fR operator, the \f(CW$_\fR string is transliterated.
2844 .Sp
2845 For \fBsed\fR devotees, \f(CW\*(C`y\*(C'\fR is provided as a synonym for \f(CW\*(C`tr\*(C'\fR.
2846 .Sp
2847 If the \f(CW\*(C`/r\*(C'\fR (non-destructive) option is present, a new copy of the string
2848 is made and its characters transliterated, and this copy is returned no
2849 matter whether it was modified or not: the original string is always
2850 left unchanged. The new copy is always a plain string, even if the input
2851 string is an object or a tied variable.
2852 .Sp
2853 Unless the \f(CW\*(C`/r\*(C'\fR option is used, the string specified with \f(CW\*(C`=~\*(C'\fR must be a
2854 scalar variable, an array element, a hash element, or an assignment to one
2855 of those; in other words, an lvalue.
2856 .Sp
2857 The characters delimitting \fISEARCHLIST\fR and \fIREPLACEMENTLIST\fR
2858 can be any printable character, not just forward slashes. If they
2859 are single quotes (\f(CW\*(C`tr\*(Aq\fR\f(CISEARCHLIST\fR\f(CW\*(Aq\fR\f(CIREPLACEMENTLIST\fR\f(CW\*(Aq\*(C'\fR), the only
2860 interpolation is removal of \f(CW\*(C`\e\*(C'\fR from pairs of \f(CW\*(C`\e\e\*(C'\fR; so hyphens are
2861 interpreted literally rather than specifying a character range.
2862 .Sp
2863 Otherwise, a character range may be specified with a hyphen, so
2864 \&\f(CW\*(C`tr/A\-J/0\-9/\*(C'\fR does the same replacement as
2865 \&\f(CW\*(C`tr/ACEGIBDFHJ/0246813579/\*(C'\fR.
2866 .Sp
2867 If the \fISEARCHLIST\fR is delimited by bracketing quotes, the
2868 \&\fIREPLACEMENTLIST\fR must have its own pair of quotes, which may or may
2869 not be bracketing quotes; for example, \f(CW\*(C`tr(aeiouy)(yuoiea)\*(C'\fR or
2870 \&\f(CW\*(C`tr[+\e\-*/]"ABCD"\*(C'\fR. This final example shows a way to visually clarify
2871 what is going on for people who are more familiar with regular
2872 expression patterns than with \f(CW\*(C`tr\*(C'\fR, and who may think forward slash
2873 delimiters imply that \f(CW\*(C`tr\*(C'\fR is more like a regular expression pattern
2874 than it actually is. (Another option might be to use \f(CW\*(C`tr[...][...]\*(C'\fR.)
2875 .Sp
2876 \&\f(CW\*(C`tr\*(C'\fR isn't fully like bracketed character classes, just
2877 (significantly) more like them than it is to full patterns. For
2878 example, characters appearing more than once in either list behave
2879 differently here than in patterns, and \f(CW\*(C`tr\*(C'\fR lists do not allow
2880 backslashed character classes such as \f(CW\*(C`\ed\*(C'\fR or \f(CW\*(C`\epL\*(C'\fR, nor variable
2881 interpolation, so \f(CW"$"\fR and \f(CW"@"\fR are always treated as literals.
2882 .Sp
2883 The allowed elements are literals plus \f(CW\*(C`\e\*(Aq\*(C'\fR (meaning a single quote).
2884 If the delimiters aren't single quotes, also allowed are any of the
2885 escape sequences accepted in double-quoted strings. Escape sequence
2886 details are in the table near the beginning of this section.
2887 .Sp
2888 A hyphen at the beginning or end, or preceded by a backslash is also
2889 always considered a literal. Precede a delimiter character with a
2890 backslash to allow it.
2891 .Sp
2892 The \f(CW\*(C`tr\*(C'\fR operator is not equivalent to the \f(CWtr(1)\fR utility.
2893 \&\f(CW\*(C`tr[a\-z][A\-Z]\*(C'\fR will uppercase the 26 letters "a" through "z", but for
2894 case changing not confined to ASCII, use \f(CW\*(C`lc\*(C'\fR,
2895 \&\f(CW\*(C`uc\*(C'\fR, \f(CW\*(C`lcfirst\*(C'\fR,
2896 \&\f(CW\*(C`ucfirst\*(C'\fR (all documented in perlfunc), or the
2897 substitution operator
2898 \&\f(CW\*(C`s/\fR\f(CIPATTERN\fR\f(CW/\fR\f(CIREPLACEMENT\fR\f(CW/\*(C'\fR
2899 (with \f(CW\*(C`\eU\*(C'\fR, \f(CW\*(C`\eu\*(C'\fR, \f(CW\*(C`\eL\*(C'\fR, and \f(CW\*(C`\el\*(C'\fR string-interpolation escapes in the
2900 \&\fIREPLACEMENT\fR portion).
2901 .Sp
2902 Most ranges are unportable between character sets, but certain ones
2903 signal Perl to do special handling to make them portable. There are two
2904 classes of portable ranges. The first are any subsets of the ranges
2905 \&\f(CW\*(C`A\-Z\*(C'\fR, \f(CW\*(C`a\-z\*(C'\fR, and \f(CW\*(C`0\-9\*(C'\fR, when expressed as literal characters.
2906 .Sp
2907 .Vb 1
2908 \& tr/h\-k/H\-K/
2909 .Ve
2910 .Sp
2911 capitalizes the letters \f(CW"h"\fR, \f(CW"i"\fR, \f(CW"j"\fR, and \f(CW"k"\fR and nothing
2912 else, no matter what the platform's character set is. In contrast, all
2913 of
2914 .Sp
2915 .Vb 3
2916 \& tr/\ex68\-\ex6B/\ex48\-\ex4B/
2917 \& tr/h\-\ex6B/H\-\ex4B/
2918 \& tr/\ex68\-k/\ex48\-K/
2919 .Ve
2920 .Sp
2921 do the same capitalizations as the previous example when run on ASCII
2922 platforms, but something completely different on EBCDIC ones.
2923 .Sp
2924 The second class of portable ranges is invoked when one or both of the
2925 range's end points are expressed as \f(CW\*(C`\eN{...}\*(C'\fR
2926 .Sp
2927 .Vb 1
2928 \& $string =~ tr/\eN{U+20}\-\eN{U+7E}//d;
2929 .Ve
2930 .Sp
2931 removes from \f(CW$string\fR all the platform's characters which are
2932 equivalent to any of Unicode U+0020, U+0021, ... U+007D, U+007E. This
2933 is a portable range, and has the same effect on every platform it is
2934 run on. In this example, these are the ASCII
2935 printable characters. So after this is run, \f(CW$string\fR has only
2936 controls and characters which have no ASCII equivalents.
2937 .Sp
2938 But, even for portable ranges, it is not generally obvious what is
2939 included without having to look things up in the manual. A sound
2940 principle is to use only ranges that both begin from, and end at, either
2941 ASCII alphabetics of equal case (\f(CW\*(C`b\-e\*(C'\fR, \f(CW\*(C`B\-E\*(C'\fR), or digits (\f(CW\*(C`1\-4\*(C'\fR).
2942 Anything else is unclear (and unportable unless \f(CW\*(C`\eN{...}\*(C'\fR is used). If
2943 in doubt, spell out the character sets in full.
2944 .Sp
2945 Options:
2946 .Sp
2947 .Vb 5
2948 \& c Complement the SEARCHLIST.
2949 \& d Delete found but unreplaced characters.
2950 \& r Return the modified string and leave the original string
2951 \& untouched.
2952 \& s Squash duplicate replaced characters.
2953 .Ve
2954 .Sp
2955 If the \f(CW\*(C`/d\*(C'\fR modifier is specified, any characters specified by
2956 \&\fISEARCHLIST\fR not found in \fIREPLACEMENTLIST\fR are deleted. (Note that
2957 this is slightly more flexible than the behavior of some \fBtr\fR programs,
2958 which delete anything they find in the \fISEARCHLIST\fR, period.)
2959 .Sp
2960 If the \f(CW\*(C`/s\*(C'\fR modifier is specified, sequences of characters, all in a
2961 row, that were transliterated to the same character are squashed down to
2962 a single instance of that character.
2963 .Sp
2964 .Vb 2
2965 \& my $x = "aaabbbca";
2966 \& $x =~ tr/ab/dd/s; # $x now is "dcd"
2967 .Ve
2968 .Sp
2969 If the \f(CW\*(C`/d\*(C'\fR modifier is used, the \fIREPLACEMENTLIST\fR is always interpreted
2970 exactly as specified. Otherwise, if the \fIREPLACEMENTLIST\fR is shorter
2971 than the \fISEARCHLIST\fR, the final character, if any, is replicated until
2972 it is long enough. There won't be a final character if and only if the
2973 \&\fIREPLACEMENTLIST\fR is empty, in which case \fIREPLACEMENTLIST\fR is
2974 copied from \fISEARCHLIST\fR. An empty \fIREPLACEMENTLIST\fR is useful
2975 for counting characters in a class, or for squashing character sequences
2976 in a class.
2977 .Sp
2978 .Vb 4
2979 \& tr/abcd// tr/abcd/abcd/
2980 \& tr/abcd/AB/ tr/abcd/ABBB/
2981 \& tr/abcd//d s/[abcd]//g
2982 \& tr/abcd/AB/d (tr/ab/AB/ + s/[cd]//g) \- but run together
2983 .Ve
2984 .Sp
2985 If the \f(CW\*(C`/c\*(C'\fR modifier is specified, the characters to be transliterated
2986 are the ones NOT in \fISEARCHLIST\fR, that is, it is complemented. If
2987 \&\f(CW\*(C`/d\*(C'\fR and/or \f(CW\*(C`/s\*(C'\fR are also specified, they apply to the complemented
2988 \&\fISEARCHLIST\fR. Recall, that if \fIREPLACEMENTLIST\fR is empty (except
2989 under \f(CW\*(C`/d\*(C'\fR) a copy of \fISEARCHLIST\fR is used instead. That copy is made
2990 after complementing under \f(CW\*(C`/c\*(C'\fR. \fISEARCHLIST\fR is sorted by code point
2991 order after complementing, and any \fIREPLACEMENTLIST\fR is applied to
2992 that sorted result. This means that under \f(CW\*(C`/c\*(C'\fR, the order of the
2993 characters specified in \fISEARCHLIST\fR is irrelevant. This can
2994 lead to different results on EBCDIC systems if \fIREPLACEMENTLIST\fR
2995 contains more than one character, hence it is generally non-portable to
2996 use \f(CW\*(C`/c\*(C'\fR with such a \fIREPLACEMENTLIST\fR.
2997 .Sp
2998 Another way of describing the operation is this:
2999 If \f(CW\*(C`/c\*(C'\fR is specified, the \fISEARCHLIST\fR is sorted by code point order,
3000 then complemented. If \fIREPLACEMENTLIST\fR is empty and \f(CW\*(C`/d\*(C'\fR is not
3001 specified, \fIREPLACEMENTLIST\fR is replaced by a copy of \fISEARCHLIST\fR (as
3002 modified under \f(CW\*(C`/c\*(C'\fR), and these potentially modified lists are used as
3003 the basis for what follows. Any character in the target string that
3004 isn't in \fISEARCHLIST\fR is passed through unchanged. Every other
3005 character in the target string is replaced by the character in
3006 \&\fIREPLACEMENTLIST\fR that positionally corresponds to its mate in
3007 \&\fISEARCHLIST\fR, except that under \f(CW\*(C`/s\*(C'\fR, the 2nd and following characters
3008 are squeezed out in a sequence of characters in a row that all translate
3009 to the same character. If \fISEARCHLIST\fR is longer than
3010 \&\fIREPLACEMENTLIST\fR, characters in the target string that match a
3011 character in \fISEARCHLIST\fR that doesn't have a correspondence in
3012 \&\fIREPLACEMENTLIST\fR are either deleted from the target string if \f(CW\*(C`/d\*(C'\fR is
3013 specified; or replaced by the final character in \fIREPLACEMENTLIST\fR if
3014 \&\f(CW\*(C`/d\*(C'\fR isn't specified.
3015 .Sp
3016 Some examples:
3017 .Sp
3018 .Vb 1
3019 \& $ARGV[1] =~ tr/A\-Z/a\-z/; # canonicalize to lower case ASCII
3020 \&
3021 \& $cnt = tr/*/*/; # count the stars in $_
3022 \& $cnt = tr/*//; # same thing
3023 \&
3024 \& $cnt = $sky =~ tr/*/*/; # count the stars in $sky
3025 \& $cnt = $sky =~ tr/*//; # same thing
3026 \&
3027 \& $cnt = $sky =~ tr/*//c; # count all the non\-stars in $sky
3028 \& $cnt = $sky =~ tr/*/*/c; # same, but transliterate each non\-star
3029 \& # into a star, leaving the already\-stars
3030 \& # alone. Afterwards, everything in $sky
3031 \& # is a star.
3032 \&
3033 \& $cnt = tr/0\-9//; # count the ASCII digits in $_
3034 \&
3035 \& tr/a\-zA\-Z//s; # bookkeeper \-> bokeper
3036 \& tr/o/o/s; # bookkeeper \-> bokkeeper
3037 \& tr/oe/oe/s; # bookkeeper \-> bokkeper
3038 \& tr/oe//s; # bookkeeper \-> bokkeper
3039 \& tr/oe/o/s; # bookkeeper \-> bokkopor
3040 \&
3041 \& ($HOST = $host) =~ tr/a\-z/A\-Z/;
3042 \& $HOST = $host =~ tr/a\-z/A\-Z/r; # same thing
3043 \&
3044 \& $HOST = $host =~ tr/a\-z/A\-Z/r # chained with s///r
3045 \& =~ s/:/ \-p/r;
3046 \&
3047 \& tr/a\-zA\-Z/ /cs; # change non\-alphas to single space
3048 \&
3049 \& @stripped = map tr/a\-zA\-Z/ /csr, @original;
3050 \& # /r with map
3051 \&
3052 \& tr [\e200\-\e377]
3053 \& [\e000\-\e177]; # wickedly delete 8th bit
3054 \&
3055 \& $foo !~ tr/A/a/ # transliterate all the A\*(Aqs in $foo to \*(Aqa\*(Aq,
3056 \& # return 0 if any were found and changed.
3057 \& # Otherwise return 1
3058 .Ve
3059 .Sp
3060 If multiple transliterations are given for a character, only the
3061 first one is used:
3062 .Sp
3063 .Vb 1
3064 \& tr/AAA/XYZ/
3065 .Ve
3066 .Sp
3067 will transliterate any A to X.
3068 .Sp
3069 Because the transliteration table is built at compile time, neither
3070 the \fISEARCHLIST\fR nor the \fIREPLACEMENTLIST\fR are subjected to double quote
3071 interpolation. That means that if you want to use variables, you
3072 must use an \f(CWeval()\fR:
3073 .Sp
3074 .Vb 2
3075 \& eval "tr/$oldlist/$newlist/";
3076 \& die $@ if $@;
3077 \&
3078 \& eval "tr/$oldlist/$newlist/, 1" or die $@;
3079 .Ve
3080 .ie n .IP """<<\fIEOF\fR""" 4
3081 .el .IP \f(CW<<\fR\f(CIEOF\fR\f(CW\fR 4
3082 .IX Xref "here-doc heredoc here-document <<"
3083 .IX Item "<<EOF"
3084 A line-oriented form of quoting is based on the shell "here-document"
3085 syntax. Following a \f(CW\*(C`<<\*(C'\fR you specify a string to terminate
3086 the quoted material, and all lines following the current line down to
3087 the terminating string are the value of the item.
3088 .Sp
3089 Prefixing the terminating string with a \f(CW\*(C`~\*(C'\fR specifies that you
3090 want to use "Indented Here-docs" (see below).
3091 .Sp
3092 The terminating string may be either an identifier (a word), or some
3093 quoted text. An unquoted identifier works like double quotes.
3094 There may not be a space between the \f(CW\*(C`<<\*(C'\fR and the identifier,
3095 unless the identifier is explicitly quoted. The terminating string
3096 must appear by itself (unquoted and with no surrounding whitespace)
3097 on the terminating line.
3098 .Sp
3099 If the terminating string is quoted, the type of quotes used determine
3100 the treatment of the text.
3101 .RS 4
3102 .IP "Double Quotes" 4
3103 .IX Item "Double Quotes"
3104 Double quotes indicate that the text will be interpolated using exactly
3105 the same rules as normal double quoted strings.
3106 .Sp
3107 .Vb 3
3108 \& print <<EOF;
3109 \& The price is $Price.
3110 \& EOF
3111 \&
3112 \& print << "EOF"; # same as above
3113 \& The price is $Price.
3114 \& EOF
3115 .Ve
3116 .IP "Single Quotes" 4
3117 .IX Item "Single Quotes"
3118 Single quotes indicate the text is to be treated literally with no
3119 interpolation of its content. This is similar to single quoted
3120 strings except that backslashes have no special meaning, with \f(CW\*(C`\e\e\*(C'\fR
3121 being treated as two backslashes and not one as they would in every
3122 other quoting construct.
3123 .Sp
3124 Just as in the shell, a backslashed bareword following the \f(CW\*(C`<<\*(C'\fR
3125 means the same thing as a single-quoted string does:
3126 .Sp
3127 .Vb 3
3128 \& $cost = <<\*(AqVISTA\*(Aq; # hasta la ...
3129 \& That\*(Aqll be $10 please, ma\*(Aqam.
3130 \& VISTA
3131 \&
3132 \& $cost = <<\eVISTA; # Same thing!
3133 \& That\*(Aqll be $10 please, ma\*(Aqam.
3134 \& VISTA
3135 .Ve
3136 .Sp
3137 This is the only form of quoting in perl where there is no need
3138 to worry about escaping content, something that code generators
3139 can and do make good use of.
3140 .IP Backticks 4
3141 .IX Item "Backticks"
3142 The content of the here doc is treated just as it would be if the
3143 string were embedded in backticks. Thus the content is interpolated
3144 as though it were double quoted and then executed via the shell, with
3145 the results of the execution returned.
3146 .Sp
3147 .Vb 3
3148 \& print << \`EOC\`; # execute command and get results
3149 \& echo hi there
3150 \& EOC
3151 .Ve
3152 .RE
3153 .RS 4
3154 .IP "Indented Here-docs" 4
3155 .IX Item "Indented Here-docs"
3156 The here-doc modifier \f(CW\*(C`~\*(C'\fR allows you to indent your here-docs to make
3157 the code more readable:
3158 .Sp
3159 .Vb 5
3160 \& if ($some_var) {
3161 \& print <<~EOF;
3162 \& This is a here\-doc
3163 \& EOF
3164 \& }
3165 .Ve
3166 .Sp
3167 This will print...
3168 .Sp
3169 .Vb 1
3170 \& This is a here\-doc
3171 .Ve
3172 .Sp
3173 \&...with no leading whitespace.
3174 .Sp
3175 The line containing the delimiter that marks the end of the here-doc
3176 determines the indentation template for the whole thing. Compilation
3177 croaks if any non-empty line inside the here-doc does not begin with the
3178 precise indentation of the terminating line. (An empty line consists of
3179 the single character "\en".) For example, suppose the terminating line
3180 begins with a tab character followed by 4 space characters. Every
3181 non-empty line in the here-doc must begin with a tab followed by 4
3182 spaces. They are stripped from each line, and any leading white space
3183 remaining on a line serves as the indentation for that line. Currently,
3184 only the TAB and SPACE characters are treated as whitespace for this
3185 purpose. Tabs and spaces may be mixed, but are matched exactly; tabs
3186 remain tabs and are not expanded.
3187 .Sp
3188 Additional beginning whitespace (beyond what preceded the
3189 delimiter) will be preserved:
3190 .Sp
3191 .Vb 5
3192 \& print <<~EOF;
3193 \& This text is not indented
3194 \& This text is indented with two spaces
3195 \& This text is indented with two tabs
3196 \& EOF
3197 .Ve
3198 .Sp
3199 Finally, the modifier may be used with all of the forms
3200 mentioned above:
3201 .Sp
3202 .Vb 4
3203 \& <<~\eEOF;
3204 \& <<~\*(AqEOF\*(Aq
3205 \& <<~"EOF"
3206 \& <<~\`EOF\`
3207 .Ve
3208 .Sp
3209 And whitespace may be used between the \f(CW\*(C`~\*(C'\fR and quoted delimiters:
3210 .Sp
3211 .Vb 1
3212 \& <<~ \*(AqEOF\*(Aq; # ... "EOF", \`EOF\`
3213 .Ve
3214 .RE
3215 .RS 4
3216 .Sp
3217 It is possible to stack multiple here-docs in a row:
3218 .Sp
3219 .Vb 5
3220 \& print <<"foo", <<"bar"; # you can stack them
3221 \& I said foo.
3222 \& foo
3223 \& I said bar.
3224 \& bar
3225 \&
3226 \& myfunc(<< "THIS", 23, <<\*(AqTHAT\*(Aq);
3227 \& Here\*(Aqs a line
3228 \& or two.
3229 \& THIS
3230 \& and here\*(Aqs another.
3231 \& THAT
3232 .Ve
3233 .Sp
3234 Just don't forget that you have to put a semicolon on the end
3235 to finish the statement, as Perl doesn't know you're not going to
3236 try to do this:
3237 .Sp
3238 .Vb 4
3239 \& print <<ABC
3240 \& 179231
3241 \& ABC
3242 \& + 20;
3243 .Ve
3244 .Sp
3245 If you want to remove the line terminator from your here-docs,
3246 use \f(CWchomp()\fR.
3247 .Sp
3248 .Vb 3
3249 \& chomp($string = <<\*(AqEND\*(Aq);
3250 \& This is a string.
3251 \& END
3252 .Ve
3253 .Sp
3254 If you want your here-docs to be indented with the rest of the code,
3255 use the \f(CW\*(C`<<~FOO\*(C'\fR construct described under "Indented Here-docs":
3256 .Sp
3257 .Vb 4
3258 \& $quote = <<~\*(AqFINIS\*(Aq;
3259 \& The Road goes ever on and on,
3260 \& down from the door where it began.
3261 \& FINIS
3262 .Ve
3263 .Sp
3264 If you use a here-doc within a delimited construct, such as in \f(CW\*(C`s///eg\*(C'\fR,
3265 the quoted material must still come on the line following the
3266 \&\f(CW\*(C`<<FOO\*(C'\fR marker, which means it may be inside the delimited
3267 construct:
3268 .Sp
3269 .Vb 4
3270 \& s/this/<<E . \*(Aqthat\*(Aq
3271 \& the other
3272 \& E
3273 \& . \*(Aqmore \*(Aq/eg;
3274 .Ve
3275 .Sp
3276 It works this way as of Perl 5.18. Historically, it was inconsistent, and
3277 you would have to write
3278 .Sp
3279 .Vb 4
3280 \& s/this/<<E . \*(Aqthat\*(Aq
3281 \& . \*(Aqmore \*(Aq/eg;
3282 \& the other
3283 \& E
3284 .Ve
3285 .Sp
3286 outside of string evals.
3287 .Sp
3288 Additionally, quoting rules for the end-of-string identifier are
3289 unrelated to Perl's quoting rules. \f(CWq()\fR, \f(CWqq()\fR, and the like are not
3290 supported in place of \f(CW\*(Aq\*(Aq\fR and \f(CW""\fR, and the only interpolation is for
3291 backslashing the quoting character:
3292 .Sp
3293 .Vb 3
3294 \& print << "abc\e"def";
3295 \& testing...
3296 \& abc"def
3297 .Ve
3298 .Sp
3299 Finally, quoted strings cannot span multiple lines. The general rule is
3300 that the identifier must be a string literal. Stick with that, and you
3301 should be safe.
3302 .RE
3303 .SS "Gory details of parsing quoted constructs"
3304 .IX Xref "quote, gory details"
3305 .IX Subsection "Gory details of parsing quoted constructs"
3306 When presented with something that might have several different
3307 interpretations, Perl uses the \fBDWIM\fR (that's "Do What I Mean")
3308 principle to pick the most probable interpretation. This strategy
3309 is so successful that Perl programmers often do not suspect the
3310 ambivalence of what they write. But from time to time, Perl's
3311 notions differ substantially from what the author honestly meant.
3312 .PP
3313 This section hopes to clarify how Perl handles quoted constructs.
3314 Although the most common reason to learn this is to unravel labyrinthine
3315 regular expressions, because the initial steps of parsing are the
3316 same for all quoting operators, they are all discussed together.
3317 .PP
3318 The most important Perl parsing rule is the first one discussed
3319 below: when processing a quoted construct, Perl first finds the end
3320 of that construct, then interprets its contents. If you understand
3321 this rule, you may skip the rest of this section on the first
3322 reading. The other rules are likely to contradict the user's
3323 expectations much less frequently than this first one.
3324 .PP
3325 Some passes discussed below are performed concurrently, but because
3326 their results are the same, we consider them individually. For different
3327 quoting constructs, Perl performs different numbers of passes, from
3328 one to four, but these passes are always performed in the same order.
3329 .IP "Finding the end" 4
3330 .IX Item "Finding the end"
3331 The first pass is finding the end of the quoted construct. This results
3332 in saving to a safe location a copy of the text (between the starting
3333 and ending delimiters), normalized as necessary to avoid needing to know
3334 what the original delimiters were.
3335 .Sp
3336 If the construct is a here-doc, the ending delimiter is a line
3337 that has a terminating string as the content. Therefore \f(CW\*(C`<<EOF\*(C'\fR is
3338 terminated by \f(CW\*(C`EOF\*(C'\fR immediately followed by \f(CW"\en"\fR and starting
3339 from the first column of the terminating line.
3340 When searching for the terminating line of a here-doc, nothing
3341 is skipped. In other words, lines after the here-doc syntax
3342 are compared with the terminating string line by line.
3343 .Sp
3344 For the constructs except here-docs, single characters are used as starting
3345 and ending delimiters. If the starting delimiter is an opening punctuation
3346 (that is \f(CW\*(C`(\*(C'\fR, \f(CW\*(C`[\*(C'\fR, \f(CW\*(C`{\*(C'\fR, or \f(CW\*(C`<\*(C'\fR), the ending delimiter is the
3347 corresponding closing punctuation (that is \f(CW\*(C`)\*(C'\fR, \f(CW\*(C`]\*(C'\fR, \f(CW\*(C`}\*(C'\fR, or \f(CW\*(C`>\*(C'\fR).
3348 If the starting delimiter is an unpaired character like \f(CW\*(C`/\*(C'\fR or a closing
3349 punctuation, the ending delimiter is the same as the starting delimiter.
3350 Therefore a \f(CW\*(C`/\*(C'\fR terminates a \f(CW\*(C`qq//\*(C'\fR construct, while a \f(CW\*(C`]\*(C'\fR terminates
3351 both \f(CW\*(C`qq[]\*(C'\fR and \f(CW\*(C`qq]]\*(C'\fR constructs.
3352 .Sp
3353 When searching for single-character delimiters, escaped delimiters
3354 and \f(CW\*(C`\e\e\*(C'\fR are skipped. For example, while searching for terminating \f(CW\*(C`/\*(C'\fR,
3355 combinations of \f(CW\*(C`\e\e\*(C'\fR and \f(CW\*(C`\e/\*(C'\fR are skipped. If the delimiters are
3356 bracketing, nested pairs are also skipped. For example, while searching
3357 for a closing \f(CW\*(C`]\*(C'\fR paired with the opening \f(CW\*(C`[\*(C'\fR, combinations of \f(CW\*(C`\e\e\*(C'\fR, \f(CW\*(C`\e]\*(C'\fR,
3358 and \f(CW\*(C`\e[\*(C'\fR are all skipped, and nested \f(CW\*(C`[\*(C'\fR and \f(CW\*(C`]\*(C'\fR are skipped as well.
3359 However, when backslashes are used as the delimiters (like \f(CW\*(C`qq\e\e\*(C'\fR and
3360 \&\f(CW\*(C`tr\e\e\e\*(C'\fR), nothing is skipped.
3361 During the search for the end, backslashes that escape delimiters or
3362 other backslashes are removed (exactly speaking, they are not copied to the
3363 safe location).
3364 .Sp
3365 For constructs with three-part delimiters (\f(CW\*(C`s///\*(C'\fR, \f(CW\*(C`y///\*(C'\fR, and
3366 \&\f(CW\*(C`tr///\*(C'\fR), the search is repeated once more.
3367 If the first delimiter is not an opening punctuation, the three delimiters must
3368 be the same, such as \f(CW\*(C`s!!!\*(C'\fR and \f(CW\*(C`tr)))\*(C'\fR,
3369 in which case the second delimiter
3370 terminates the left part and starts the right part at once.
3371 If the left part is delimited by bracketing punctuation (that is \f(CW\*(C`()\*(C'\fR,
3372 \&\f(CW\*(C`[]\*(C'\fR, \f(CW\*(C`{}\*(C'\fR, or \f(CW\*(C`<>\*(C'\fR), the right part needs another pair of
3373 delimiters such as \f(CW\*(C`s(){}\*(C'\fR and \f(CW\*(C`tr[]//\*(C'\fR. In these cases, whitespace
3374 and comments are allowed between the two parts, although the comment must follow
3375 at least one whitespace character; otherwise a character expected as the
3376 start of the comment may be regarded as the starting delimiter of the right part.
3377 .Sp
3378 During this search no attention is paid to the semantics of the construct.
3379 Thus:
3380 .Sp
3381 .Vb 1
3382 \& "$hash{"$foo/$bar"}"
3383 .Ve
3384 .Sp
3385 or:
3386 .Sp
3387 .Vb 3
3388 \& m/
3389 \& bar # NOT a comment, this slash / terminated m//!
3390 \& /x
3391 .Ve
3392 .Sp
3393 do not form legal quoted expressions. The quoted part ends on the
3394 first \f(CW\*(C`"\*(C'\fR and \f(CW\*(C`/\*(C'\fR, and the rest happens to be a syntax error.
3395 Because the slash that terminated \f(CW\*(C`m//\*(C'\fR was followed by a \f(CW\*(C`SPACE\*(C'\fR,
3396 the example above is not \f(CW\*(C`m//x\*(C'\fR, but rather \f(CW\*(C`m//\*(C'\fR with no \f(CW\*(C`/x\*(C'\fR
3397 modifier. So the embedded \f(CW\*(C`#\*(C'\fR is interpreted as a literal \f(CW\*(C`#\*(C'\fR.
3398 .Sp
3399 Also no attention is paid to \f(CW\*(C`\ec\e\*(C'\fR (multichar control char syntax) during
3400 this search. Thus the second \f(CW\*(C`\e\*(C'\fR in \f(CW\*(C`qq/\ec\e/\*(C'\fR is interpreted as a part
3401 of \f(CW\*(C`\e/\*(C'\fR, and the following \f(CW\*(C`/\*(C'\fR is not recognized as a delimiter.
3402 Instead, use \f(CW\*(C`\e034\*(C'\fR or \f(CW\*(C`\ex1c\*(C'\fR at the end of quoted constructs.
3403 .IP Interpolation 4
3404 .IX Xref "interpolation"
3405 .IX Item "Interpolation"
3406 The next step is interpolation in the text obtained, which is now
3407 delimiter-independent. There are multiple cases.
3408 .RS 4
3409 .ie n .IP """<<\*(AqEOF\*(Aq""" 4
3410 .el .IP \f(CW<<\*(AqEOF\*(Aq\fR 4
3411 .IX Item "<<EOF"
3412 No interpolation is performed.
3413 Note that the combination \f(CW\*(C`\e\e\*(C'\fR is left intact, since escaped delimiters
3414 are not available for here-docs.
3415 .ie n .IP """m\*(Aq\*(Aq"", the pattern of ""s\*(Aq\*(Aq\*(Aq""" 4
3416 .el .IP "\f(CWm\*(Aq\*(Aq\fR, the pattern of \f(CWs\*(Aq\*(Aq\*(Aq\fR" 4
3417 .IX Item "m, the pattern of s"
3418 No interpolation is performed at this stage.
3419 Any backslashed sequences including \f(CW\*(C`\e\e\*(C'\fR are treated at the stage
3420 of "Parsing regular expressions".
3421 .ie n .IP "\*(Aq\*(Aq, ""q//"", ""tr\*(Aq\*(Aq\*(Aq"", ""y\*(Aq\*(Aq\*(Aq"", the replacement of ""s\*(Aq\*(Aq\*(Aq""" 4
3422 .el .IP "\f(CW\*(Aq\*(Aq\fR, \f(CWq//\fR, \f(CWtr\*(Aq\*(Aq\*(Aq\fR, \f(CWy\*(Aq\*(Aq\*(Aq\fR, the replacement of \f(CWs\*(Aq\*(Aq\*(Aq\fR" 4
3423 .IX Item ", q//, tr, y, the replacement of s"
3424 The only interpolation is removal of \f(CW\*(C`\e\*(C'\fR from pairs of \f(CW\*(C`\e\e\*(C'\fR.
3425 Therefore \f(CW"\-"\fR in \f(CW\*(C`tr\*(Aq\*(Aq\*(Aq\*(C'\fR and \f(CW\*(C`y\*(Aq\*(Aq\*(Aq\*(C'\fR is treated literally
3426 as a hyphen and no character range is available.
3427 \&\f(CW\*(C`\e1\*(C'\fR in the replacement of \f(CW\*(C`s\*(Aq\*(Aq\*(Aq\*(C'\fR does not work as \f(CW$1\fR.
3428 .ie n .IP """tr///"", ""y///""" 4
3429 .el .IP "\f(CWtr///\fR, \f(CWy///\fR" 4
3430 .IX Item "tr///, y///"
3431 No variable interpolation occurs. String modifying combinations for
3432 case and quoting such as \f(CW\*(C`\eQ\*(C'\fR, \f(CW\*(C`\eU\*(C'\fR, and \f(CW\*(C`\eE\*(C'\fR are not recognized.
3433 The other escape sequences such as \f(CW\*(C`\e200\*(C'\fR and \f(CW\*(C`\et\*(C'\fR and backslashed
3434 characters such as \f(CW\*(C`\e\e\*(C'\fR and \f(CW\*(C`\e\-\*(C'\fR are converted to appropriate literals.
3435 The character \f(CW"\-"\fR is treated specially and therefore \f(CW\*(C`\e\-\*(C'\fR is treated
3436 as a literal \f(CW"\-"\fR.
3437 .ie n .IP """"", \`\`, ""qq//"", ""qx//"", ""<file*glob>"", ""<<""EOF""""" 4
3438 .el .IP "\f(CW""""\fR, \f(CW\`\`\fR, \f(CWqq//\fR, \f(CWqx//\fR, \f(CW<file*glob>\fR, \f(CW<<""EOF""\fR" 4
3439 .IX Item """"", , qq//, qx//, <file*glob>, <<""EOF"""
3440 \&\f(CW\*(C`\eQ\*(C'\fR, \f(CW\*(C`\eU\*(C'\fR, \f(CW\*(C`\eu\*(C'\fR, \f(CW\*(C`\eL\*(C'\fR, \f(CW\*(C`\el\*(C'\fR, \f(CW\*(C`\eF\*(C'\fR (possibly paired with \f(CW\*(C`\eE\*(C'\fR) are
3441 converted to corresponding Perl constructs. Thus, \f(CW"$foo\eQbaz$bar"\fR
3442 is converted to \f(CW\*(C`$foo\ .\ (quotemeta("baz"\ .\ $bar))\*(C'\fR internally.
3443 The other escape sequences such as \f(CW\*(C`\e200\*(C'\fR and \f(CW\*(C`\et\*(C'\fR and backslashed
3444 characters such as \f(CW\*(C`\e\e\*(C'\fR and \f(CW\*(C`\e\-\*(C'\fR are replaced with appropriate
3445 expansions.
3446 .Sp
3447 Let it be stressed that \fIwhatever falls between \fR\f(CI\*(C`\eQ\*(C'\fR\fI and \fR\f(CI\*(C`\eE\*(C'\fR
3448 is interpolated in the usual way. Something like \f(CW"\eQ\e\eE"\fR has
3449 no \f(CW\*(C`\eE\*(C'\fR inside. Instead, it has \f(CW\*(C`\eQ\*(C'\fR, \f(CW\*(C`\e\e\*(C'\fR, and \f(CW\*(C`E\*(C'\fR, so the
3450 result is the same as for \f(CW"\e\e\e\eE"\fR. As a general rule, backslashes
3451 between \f(CW\*(C`\eQ\*(C'\fR and \f(CW\*(C`\eE\*(C'\fR may lead to counterintuitive results. So,
3452 \&\f(CW"\eQ\et\eE"\fR is converted to \f(CWquotemeta("\et")\fR, which is the same
3453 as \f(CW"\e\e\et"\fR (since TAB is not alphanumeric). Note also that:
3454 .Sp
3455 .Vb 2
3456 \& $str = \*(Aq\et\*(Aq;
3457 \& return "\eQ$str";
3458 .Ve
3459 .Sp
3460 may be closer to the conjectural \fIintention\fR of the writer of \f(CW"\eQ\et\eE"\fR.
3461 .Sp
3462 Interpolated scalars and arrays are converted internally to the \f(CW\*(C`join\*(C'\fR and
3463 \&\f(CW"."\fR catenation operations. Thus, \f(CW"$foo\ XXX\ \*(Aq@arr\*(Aq"\fR becomes:
3464 .Sp
3465 .Vb 1
3466 \& $foo . " XXX \*(Aq" . (join $", @arr) . "\*(Aq";
3467 .Ve
3468 .Sp
3469 All operations above are performed simultaneously, left to right.
3470 .Sp
3471 Because the result of \f(CW"\eQ\ \fR\f(CISTRING\fR\f(CW\ \eE"\fR has all metacharacters
3472 quoted, there is no way to insert a literal \f(CW\*(C`$\*(C'\fR or \f(CW\*(C`@\*(C'\fR inside a
3473 \&\f(CW\*(C`\eQ\eE\*(C'\fR pair. If protected by \f(CW\*(C`\e\*(C'\fR, \f(CW\*(C`$\*(C'\fR will be quoted to become
3474 \&\f(CW"\e\e\e$"\fR; if not, it is interpreted as the start of an interpolated
3475 scalar.
3476 .Sp
3477 Note also that the interpolation code needs to make a decision on
3478 where the interpolated scalar ends. For instance, whether
3479 \&\f(CW"a\ $x\ \->\ {c}"\fR really means:
3480 .Sp
3481 .Vb 1
3482 \& "a " . $x . " \-> {c}";
3483 .Ve
3484 .Sp
3485 or:
3486 .Sp
3487 .Vb 1
3488 \& "a " . $x \-> {c};
3489 .Ve
3490 .Sp
3491 Most of the time, the longest possible text that does not include
3492 spaces between components and which contains matching braces or
3493 brackets. because the outcome may be determined by voting based
3494 on heuristic estimators, the result is not strictly predictable.
3495 Fortunately, it's usually correct for ambiguous cases.
3496 .ie n .IP "The replacement of ""s///""" 4
3497 .el .IP "The replacement of \f(CWs///\fR" 4
3498 .IX Item "The replacement of s///"
3499 Processing of \f(CW\*(C`\eQ\*(C'\fR, \f(CW\*(C`\eU\*(C'\fR, \f(CW\*(C`\eu\*(C'\fR, \f(CW\*(C`\eL\*(C'\fR, \f(CW\*(C`\el\*(C'\fR, \f(CW\*(C`\eF\*(C'\fR and interpolation
3500 happens as with \f(CW\*(C`qq//\*(C'\fR constructs.
3501 .Sp
3502 It is at this step that \f(CW\*(C`\e1\*(C'\fR is begrudgingly converted to \f(CW$1\fR in
3503 the replacement text of \f(CW\*(C`s///\*(C'\fR, in order to correct the incorrigible
3504 \&\fIsed\fR hackers who haven't picked up the saner idiom yet. A warning
3505 is emitted if the \f(CW\*(C`use\ warnings\*(C'\fR pragma or the \fB\-w\fR command-line flag
3506 (that is, the \f(CW$^W\fR variable) was set.
3507 .ie n .IP """RE"" in ""m?RE?"", ""/RE/"", ""m/RE/"", ""s/RE/foo/""," 4
3508 .el .IP "\f(CWRE\fR in \f(CWm?RE?\fR, \f(CW/RE/\fR, \f(CWm/RE/\fR, \f(CWs/RE/foo/\fR," 4
3509 .IX Item "RE in m?RE?, /RE/, m/RE/, s/RE/foo/,"
3510 Processing of \f(CW\*(C`\eQ\*(C'\fR, \f(CW\*(C`\eU\*(C'\fR, \f(CW\*(C`\eu\*(C'\fR, \f(CW\*(C`\eL\*(C'\fR, \f(CW\*(C`\el\*(C'\fR, \f(CW\*(C`\eF\*(C'\fR, \f(CW\*(C`\eE\*(C'\fR,
3511 and interpolation happens (almost) as with \f(CW\*(C`qq//\*(C'\fR constructs.
3512 .Sp
3513 Processing of \f(CW\*(C`\eN{...}\*(C'\fR is also done here, and compiled into an intermediate
3514 form for the regex compiler. (This is because, as mentioned below, the regex
3515 compilation may be done at execution time, and \f(CW\*(C`\eN{...}\*(C'\fR is a compile-time
3516 construct.)
3517 .Sp
3518 However any other combinations of \f(CW\*(C`\e\*(C'\fR followed by a character
3519 are not substituted but only skipped, in order to parse them
3520 as regular expressions at the following step.
3521 As \f(CW\*(C`\ec\*(C'\fR is skipped at this step, \f(CW\*(C`@\*(C'\fR of \f(CW\*(C`\ec@\*(C'\fR in RE is possibly
3522 treated as an array symbol (for example \f(CW@foo\fR),
3523 even though the same text in \f(CW\*(C`qq//\*(C'\fR gives interpolation of \f(CW\*(C`\ec@\*(C'\fR.
3524 .Sp
3525 Code blocks such as \f(CW\*(C`(?{BLOCK})\*(C'\fR are handled by temporarily passing control
3526 back to the perl parser, in a similar way that an interpolated array
3527 subscript expression such as \f(CW"foo$array[1+f("[xyz")]bar"\fR would be.
3528 .Sp
3529 Moreover, inside \f(CW\*(C`(?{BLOCK})\*(C'\fR, \f(CW\*(C`(?#\ comment\ )\*(C'\fR, and
3530 a \f(CW\*(C`#\*(C'\fR\-comment in a \f(CW\*(C`/x\*(C'\fR\-regular expression, no processing is
3531 performed whatsoever. This is the first step at which the presence
3532 of the \f(CW\*(C`/x\*(C'\fR modifier is relevant.
3533 .Sp
3534 Interpolation in patterns has several quirks: \f(CW$|\fR, \f(CW$(\fR, \f(CW$)\fR, \f(CW\*(C`@+\*(C'\fR
3535 and \f(CW\*(C`@\-\*(C'\fR are not interpolated, and constructs \f(CW$var[SOMETHING]\fR are
3536 voted (by several different estimators) to be either an array element
3537 or \f(CW$var\fR followed by an RE alternative. This is where the notation
3538 \&\f(CW\*(C`${arr[$bar]}\*(C'\fR comes handy: \f(CW\*(C`/${arr[0\-9]}/\*(C'\fR is interpreted as
3539 array element \f(CW\-9\fR, not as a regular expression from the variable
3540 \&\f(CW$arr\fR followed by a digit, which would be the interpretation of
3541 \&\f(CW\*(C`/$arr[0\-9]/\*(C'\fR. Since voting among different estimators may occur,
3542 the result is not predictable.
3543 .Sp
3544 The lack of processing of \f(CW\*(C`\e\e\*(C'\fR creates specific restrictions on
3545 the post-processed text. If the delimiter is \f(CW\*(C`/\*(C'\fR, one cannot get
3546 the combination \f(CW\*(C`\e/\*(C'\fR into the result of this step. \f(CW\*(C`/\*(C'\fR will
3547 finish the regular expression, \f(CW\*(C`\e/\*(C'\fR will be stripped to \f(CW\*(C`/\*(C'\fR on
3548 the previous step, and \f(CW\*(C`\e\e/\*(C'\fR will be left as is. Because \f(CW\*(C`/\*(C'\fR is
3549 equivalent to \f(CW\*(C`\e/\*(C'\fR inside a regular expression, this does not
3550 matter unless the delimiter happens to be character special to the
3551 RE engine, such as in \f(CW\*(C`s*foo*bar*\*(C'\fR, \f(CW\*(C`m[foo]\*(C'\fR, or \f(CW\*(C`m?foo?\*(C'\fR; or an
3552 alphanumeric char, as in:
3553 .Sp
3554 .Vb 1
3555 \& m m ^ a \es* b mmx;
3556 .Ve
3557 .Sp
3558 In the RE above, which is intentionally obfuscated for illustration, the
3559 delimiter is \f(CW\*(C`m\*(C'\fR, the modifier is \f(CW\*(C`mx\*(C'\fR, and after delimiter-removal the
3560 RE is the same as for \f(CW\*(C`m/\ ^\ a\ \es*\ b\ /mx\*(C'\fR. There's more than one
3561 reason you're encouraged to restrict your delimiters to non-alphanumeric,
3562 non-whitespace choices.
3563 .RE
3564 .RS 4
3565 .Sp
3566 This step is the last one for all constructs except regular expressions,
3567 which are processed further.
3568 .RE
3569 .IP "Parsing regular expressions" 4
3570 .IX Xref "regexp, parse"
3571 .IX Item "Parsing regular expressions"
3572 Previous steps were performed during the compilation of Perl code,
3573 but this one happens at run time, although it may be optimized to
3574 be calculated at compile time if appropriate. After preprocessing
3575 described above, and possibly after evaluation if concatenation,
3576 joining, casing translation, or metaquoting are involved, the
3577 resulting \fIstring\fR is passed to the RE engine for compilation.
3578 .Sp
3579 Whatever happens in the RE engine might be better discussed in perlre,
3580 but for the sake of continuity, we shall do so here.
3581 .Sp
3582 This is another step where the presence of the \f(CW\*(C`/x\*(C'\fR modifier is
3583 relevant. The RE engine scans the string from left to right and
3584 converts it into a finite automaton.
3585 .Sp
3586 Backslashed characters are either replaced with corresponding
3587 literal strings (as with \f(CW\*(C`\e{\*(C'\fR), or else they generate special nodes
3588 in the finite automaton (as with \f(CW\*(C`\eb\*(C'\fR). Characters special to the
3589 RE engine (such as \f(CW\*(C`|\*(C'\fR) generate corresponding nodes or groups of
3590 nodes. \f(CW\*(C`(?#...)\*(C'\fR comments are ignored. All the rest is either
3591 converted to literal strings to match, or else is ignored (as is
3592 whitespace and \f(CW\*(C`#\*(C'\fR\-style comments if \f(CW\*(C`/x\*(C'\fR is present).
3593 .Sp
3594 Parsing of the bracketed character class construct, \f(CW\*(C`[...]\*(C'\fR, is
3595 rather different than the rule used for the rest of the pattern.
3596 The terminator of this construct is found using the same rules as
3597 for finding the terminator of a \f(CW\*(C`{}\*(C'\fR\-delimited construct, the only
3598 exception being that \f(CW\*(C`]\*(C'\fR immediately following \f(CW\*(C`[\*(C'\fR is treated as
3599 though preceded by a backslash.
3600 .Sp
3601 The terminator of runtime \f(CW\*(C`(?{...})\*(C'\fR is found by temporarily switching
3602 control to the perl parser, which should stop at the point where the
3603 logically balancing terminating \f(CW\*(C`}\*(C'\fR is found.
3604 .Sp
3605 It is possible to inspect both the string given to RE engine and the
3606 resulting finite automaton. See the arguments \f(CW\*(C`debug\*(C'\fR/\f(CW\*(C`debugcolor\*(C'\fR
3607 in the \f(CW\*(C`use\ re\*(C'\fR pragma, as well as Perl's \fB\-Dr\fR command-line
3608 switch documented in "Command Switches" in perlrun.
3609 .IP "Optimization of regular expressions" 4
3610 .IX Xref "regexp, optimization"
3611 .IX Item "Optimization of regular expressions"
3612 This step is listed for completeness only. Since it does not change
3613 semantics, details of this step are not documented and are subject
3614 to change without notice. This step is performed over the finite
3615 automaton that was generated during the previous pass.
3616 .Sp
3617 It is at this stage that \f(CWsplit()\fR silently optimizes \f(CW\*(C`/^/\*(C'\fR to
3618 mean \f(CW\*(C`/^/m\*(C'\fR.
3619 .SS "I/O Operators"
3620 .IX Xref "operator, i o operator, io io while filehandle <> <<>> @ARGV"
3621 .IX Subsection "I/O Operators"
3622 There are several I/O operators you should know about.
3623 .PP
3624 A string enclosed by backticks (grave accents) first undergoes
3625 double-quote interpolation. It is then interpreted as an external
3626 command, and the output of that command is the value of the
3627 backtick string, like in a shell. In scalar context, a single string
3628 consisting of all output is returned. In list context, a list of
3629 values is returned, one per line of output. (You can set \f(CW$/\fR to use
3630 a different line terminator.) The command is executed each time the
3631 pseudo-literal is evaluated. The status value of the command is
3632 returned in \f(CW$?\fR (see perlvar for the interpretation of \f(CW$?\fR).
3633 Unlike in \fBcsh\fR, no translation is done on the return data\-\-newlines
3634 remain newlines. Unlike in any of the shells, single quotes do not
3635 hide variable names in the command from interpretation. To pass a
3636 literal dollar-sign through to the shell you need to hide it with a
3637 backslash. The generalized form of backticks is \f(CW\*(C`qx//\*(C'\fR, or you can
3638 call the "readpipe" in perlfunc function. (Because
3639 backticks always undergo shell expansion as well, see perlsec for
3640 security concerns.)
3641 .IX Xref "qx ` `` backtick glob"
3642 .PP
3643 In scalar context, evaluating a filehandle in angle brackets yields
3644 the next line from that file (the newline, if any, included), or
3645 \&\f(CW\*(C`undef\*(C'\fR at end-of-file or on error. When \f(CW$/\fR is set to \f(CW\*(C`undef\*(C'\fR
3646 (sometimes known as file-slurp mode) and the file is empty, it
3647 returns \f(CW\*(Aq\*(Aq\fR the first time, followed by \f(CW\*(C`undef\*(C'\fR subsequently.
3648 .PP
3649 Ordinarily you must assign the returned value to a variable, but
3650 there is one situation where an automatic assignment happens. If
3651 and only if the input symbol is the only thing inside the conditional
3652 of a \f(CW\*(C`while\*(C'\fR statement (even if disguised as a \f(CWfor(;;)\fR loop),
3653 the value is automatically assigned to the global variable \f(CW$_\fR,
3654 destroying whatever was there previously. (This may seem like an
3655 odd thing to you, but you'll use the construct in almost every Perl
3656 script you write.) The \f(CW$_\fR variable is not implicitly localized.
3657 You'll have to put a \f(CW\*(C`local\ $_;\*(C'\fR before the loop if you want that
3658 to happen. Furthermore, if the input symbol or an explicit assignment
3659 of the input symbol to a scalar is used as a \f(CW\*(C`while\*(C'\fR/\f(CW\*(C`for\*(C'\fR condition,
3660 then the condition actually tests for definedness of the expression's
3661 value, not for its regular truth value.
3662 .PP
3663 Thus the following lines are equivalent:
3664 .PP
3665 .Vb 7
3666 \& while (defined($_ = <STDIN>)) { print; }
3667 \& while ($_ = <STDIN>) { print; }
3668 \& while (<STDIN>) { print; }
3669 \& for (;<STDIN>;) { print; }
3670 \& print while defined($_ = <STDIN>);
3671 \& print while ($_ = <STDIN>);
3672 \& print while <STDIN>;
3673 .Ve
3674 .PP
3675 This also behaves similarly, but assigns to a lexical variable
3676 instead of to \f(CW$_\fR:
3677 .PP
3678 .Vb 1
3679 \& while (my $line = <STDIN>) { print $line }
3680 .Ve
3681 .PP
3682 In these loop constructs, the assigned value (whether assignment
3683 is automatic or explicit) is then tested to see whether it is
3684 defined. The defined test avoids problems where the line has a string
3685 value that would be treated as false by Perl; for example a "" or
3686 a \f(CW"0"\fR with no trailing newline. If you really mean for such values
3687 to terminate the loop, they should be tested for explicitly:
3688 .PP
3689 .Vb 2
3690 \& while (($_ = <STDIN>) ne \*(Aq0\*(Aq) { ... }
3691 \& while (<STDIN>) { last unless $_; ... }
3692 .Ve
3693 .PP
3694 In other boolean contexts, \f(CW\*(C`<\fR\f(CIFILEHANDLE\fR\f(CW>\*(C'\fR without an
3695 explicit \f(CW\*(C`defined\*(C'\fR test or comparison elicits a warning if the
3696 \&\f(CW\*(C`use\ warnings\*(C'\fR pragma or the \fB\-w\fR
3697 command-line switch (the \f(CW$^W\fR variable) is in effect.
3698 .PP
3699 The filehandles STDIN, STDOUT, and STDERR are predefined. (The
3700 filehandles \f(CW\*(C`stdin\*(C'\fR, \f(CW\*(C`stdout\*(C'\fR, and \f(CW\*(C`stderr\*(C'\fR will also work except
3701 in packages, where they would be interpreted as local identifiers
3702 rather than global.) Additional filehandles may be created with
3703 the \f(CWopen()\fR function, amongst others. See perlopentut and
3704 "open" in perlfunc for details on this.
3705 .IX Xref "stdin stdout sterr"
3706 .PP
3707 If a \f(CW\*(C`<\fR\f(CIFILEHANDLE\fR\f(CW>\*(C'\fR is used in a context that is looking for
3708 a list, a list comprising all input lines is returned, one line per
3709 list element. It's easy to grow to a rather large data space this
3710 way, so use with care.
3711 .PP
3712 \&\f(CW\*(C`<\fR\f(CIFILEHANDLE\fR\f(CW>\*(C'\fR may also be spelled \f(CWreadline(*\fR\f(CIFILEHANDLE\fR\f(CW)\fR.
3713 See "readline" in perlfunc.
3714 .PP
3715 The null filehandle \f(CW\*(C`<>\*(C'\fR (sometimes called the diamond operator) is
3716 special: it can be used to emulate the
3717 behavior of \fBsed\fR and \fBawk\fR, and any other Unix filter program
3718 that takes a list of filenames, doing the same to each line
3719 of input from all of them. Input from \f(CW\*(C`<>\*(C'\fR comes either from
3720 standard input, or from each file listed on the command line. Here's
3721 how it works: the first time \f(CW\*(C`<>\*(C'\fR is evaluated, the \f(CW@ARGV\fR array is
3722 checked, and if it is empty, \f(CW$ARGV[0]\fR is set to \f(CW"\-"\fR, which when opened
3723 gives you standard input. The \f(CW@ARGV\fR array is then processed as a list
3724 of filenames. The loop
3725 .PP
3726 .Vb 3
3727 \& while (<>) {
3728 \& ... # code for each line
3729 \& }
3730 .Ve
3731 .PP
3732 is equivalent to the following Perl-like pseudo code:
3733 .PP
3734 .Vb 7
3735 \& unshift(@ARGV, \*(Aq\-\*(Aq) unless @ARGV;
3736 \& while ($ARGV = shift) {
3737 \& open(ARGV, $ARGV);
3738 \& while (<ARGV>) {
3739 \& ... # code for each line
3740 \& }
3741 \& }
3742 .Ve
3743 .PP
3744 except that it isn't so cumbersome to say, and will actually work.
3745 It really does shift the \f(CW@ARGV\fR array and put the current filename
3746 into the \f(CW$ARGV\fR variable. It also uses filehandle \fIARGV\fR
3747 internally. \f(CW\*(C`<>\*(C'\fR is just a synonym for \f(CW\*(C`<ARGV>\*(C'\fR, which
3748 is magical. (The pseudo code above doesn't work because it treats
3749 \&\f(CW\*(C`<ARGV>\*(C'\fR as non-magical.)
3750 .PP
3751 Since the null filehandle uses the two argument form of "open" in perlfunc
3752 it interprets special characters, so if you have a script like this:
3753 .PP
3754 .Vb 3
3755 \& while (<>) {
3756 \& print;
3757 \& }
3758 .Ve
3759 .PP
3760 and call it with \f(CW\*(C`perl\ dangerous.pl\ \*(Aqrm\ \-rfv\ *|\*(Aq\*(C'\fR, it actually opens a
3761 pipe, executes the \f(CW\*(C`rm\*(C'\fR command and reads \f(CW\*(C`rm\*(C'\fR's output from that pipe.
3762 If you want all items in \f(CW@ARGV\fR to be interpreted as file names, you
3763 can use the module \f(CW\*(C`ARGV::readonly\*(C'\fR from CPAN, or use the double
3764 diamond bracket:
3765 .PP
3766 .Vb 3
3767 \& while (<<>>) {
3768 \& print;
3769 \& }
3770 .Ve
3771 .PP
3772 Using double angle brackets inside of a while causes the open to use the
3773 three argument form (with the second argument being \f(CW\*(C`<\*(C'\fR), so all
3774 arguments in \f(CW\*(C`ARGV\*(C'\fR are treated as literal filenames (including \f(CW"\-"\fR).
3775 (Note that for convenience, if you use \f(CW\*(C`<<>>\*(C'\fR and if \f(CW@ARGV\fR is
3776 empty, it will still read from the standard input.)
3777 .PP
3778 You can modify \f(CW@ARGV\fR before the first \f(CW\*(C`<>\*(C'\fR as long as the array ends up
3779 containing the list of filenames you really want. Line numbers (\f(CW$.\fR)
3780 continue as though the input were one big happy file. See the example
3781 in "eof" in perlfunc for how to reset line numbers on each file.
3782 .PP
3783 If you want to set \f(CW@ARGV\fR to your own list of files, go right ahead.
3784 This sets \f(CW@ARGV\fR to all plain text files if no \f(CW@ARGV\fR was given:
3785 .PP
3786 .Vb 1
3787 \& @ARGV = grep { \-f && \-T } glob(\*(Aq*\*(Aq) unless @ARGV;
3788 .Ve
3789 .PP
3790 You can even set them to pipe commands. For example, this automatically
3791 filters compressed arguments through \fBgzip\fR:
3792 .PP
3793 .Vb 1
3794 \& @ARGV = map { /\e.(gz|Z)$/ ? "gzip \-dc < $_ |" : $_ } @ARGV;
3795 .Ve
3796 .PP
3797 If you want to pass switches into your script, you can use one of the
3798 \&\f(CW\*(C`Getopts\*(C'\fR modules or put a loop on the front like this:
3799 .PP
3800 .Vb 7
3801 \& while ($_ = $ARGV[0], /^\-/) {
3802 \& shift;
3803 \& last if /^\-\-$/;
3804 \& if (/^\-D(.*)/) { $debug = $1 }
3805 \& if (/^\-v/) { $verbose++ }
3806 \& # ... # other switches
3807 \& }
3808 \&
3809 \& while (<>) {
3810 \& # ... # code for each line
3811 \& }
3812 .Ve
3813 .PP
3814 The \f(CW\*(C`<>\*(C'\fR symbol will return \f(CW\*(C`undef\*(C'\fR for end-of-file only once.
3815 If you call it again after this, it will assume you are processing another
3816 \&\f(CW@ARGV\fR list, and if you haven't set \f(CW@ARGV\fR, will read input from STDIN.
3817 .PP
3818 If what the angle brackets contain is a simple scalar variable (for example,
3819 \&\f(CW$foo\fR), then that variable contains the name of the
3820 filehandle to input from, or its typeglob, or a reference to the
3821 same. For example:
3822 .PP
3823 .Vb 2
3824 \& $fh = \e*STDIN;
3825 \& $line = <$fh>;
3826 .Ve
3827 .PP
3828 If what's within the angle brackets is neither a filehandle nor a simple
3829 scalar variable containing a filehandle name, typeglob, or typeglob
3830 reference, it is interpreted as a filename pattern to be globbed, and
3831 either a list of filenames or the next filename in the list is returned,
3832 depending on context. This distinction is determined on syntactic
3833 grounds alone. That means \f(CW\*(C`<$x>\*(C'\fR is always a \f(CWreadline()\fR from
3834 an indirect handle, but \f(CW\*(C`<$hash{key}>\*(C'\fR is always a \f(CWglob()\fR.
3835 That's because \f(CW$x\fR is a simple scalar variable, but \f(CW$hash{key}\fR is
3836 not\-\-it's a hash element. Even \f(CW\*(C`<$x >\*(C'\fR (note the extra space)
3837 is treated as \f(CW\*(C`glob("$x ")\*(C'\fR, not \f(CWreadline($x)\fR.
3838 .PP
3839 One level of double-quote interpretation is done first, but you can't
3840 say \f(CW\*(C`<$foo>\*(C'\fR because that's an indirect filehandle as explained
3841 in the previous paragraph. (In older versions of Perl, programmers
3842 would insert curly brackets to force interpretation as a filename glob:
3843 \&\f(CW\*(C`<${foo}>\*(C'\fR. These days, it's considered cleaner to call the
3844 internal function directly as \f(CWglob($foo)\fR, which is probably the right
3845 way to have done it in the first place.) For example:
3846 .PP
3847 .Vb 3
3848 \& while (<*.c>) {
3849 \& chmod 0644, $_;
3850 \& }
3851 .Ve
3852 .PP
3853 is roughly equivalent to:
3854 .PP
3855 .Vb 5
3856 \& open(FOO, "echo *.c | tr \-s \*(Aq \et\er\ef\*(Aq \*(Aq\e\e012\e\e012\e\e012\e\e012\*(Aq|");
3857 \& while (<FOO>) {
3858 \& chomp;
3859 \& chmod 0644, $_;
3860 \& }
3861 .Ve
3862 .PP
3863 except that the globbing is actually done internally using the standard
3864 \&\f(CW\*(C`File::Glob\*(C'\fR extension. Of course, the shortest way to do the above is:
3865 .PP
3866 .Vb 1
3867 \& chmod 0644, <*.c>;
3868 .Ve
3869 .PP
3870 A (file)glob evaluates its (embedded) argument only when it is
3871 starting a new list. All values must be read before it will start
3872 over. In list context, this isn't important because you automatically
3873 get them all anyway. However, in scalar context the operator returns
3874 the next value each time it's called, or \f(CW\*(C`undef\*(C'\fR when the list has
3875 run out. As with filehandle reads, an automatic \f(CW\*(C`defined\*(C'\fR is
3876 generated when the glob occurs in the test part of a \f(CW\*(C`while\*(C'\fR,
3877 because legal glob returns (for example,
3878 a file called \fI0\fR) would otherwise
3879 terminate the loop. Again, \f(CW\*(C`undef\*(C'\fR is returned only once. So if
3880 you're expecting a single value from a glob, it is much better to
3881 say
3882 .PP
3883 .Vb 1
3884 \& ($file) = <blurch*>;
3885 .Ve
3886 .PP
3887 than
3888 .PP
3889 .Vb 1
3890 \& $file = <blurch*>;
3891 .Ve
3892 .PP
3893 because the latter will alternate between returning a filename and
3894 returning false.
3895 .PP
3896 If you're trying to do variable interpolation, it's definitely better
3897 to use the \f(CWglob()\fR function, because the older notation can cause people
3898 to become confused with the indirect filehandle notation.
3899 .PP
3900 .Vb 2
3901 \& @files = glob("$dir/*.[ch]");
3902 \& @files = glob($files[$i]);
3903 .Ve
3904 .PP
3905 If an angle-bracket-based globbing expression is used as the condition of
3906 a \f(CW\*(C`while\*(C'\fR or \f(CW\*(C`for\*(C'\fR loop, then it will be implicitly assigned to \f(CW$_\fR.
3907 If either a globbing expression or an explicit assignment of a globbing
3908 expression to a scalar is used as a \f(CW\*(C`while\*(C'\fR/\f(CW\*(C`for\*(C'\fR condition, then
3909 the condition actually tests for definedness of the expression's value,
3910 not for its regular truth value.
3911 .SS "Constant Folding"
3912 .IX Xref "constant folding folding"
3913 .IX Subsection "Constant Folding"
3914 Like C, Perl does a certain amount of expression evaluation at
3915 compile time whenever it determines that all arguments to an
3916 operator are static and have no side effects. In particular, string
3917 concatenation happens at compile time between literals that don't do
3918 variable substitution. Backslash interpolation also happens at
3919 compile time. You can say
3920 .PP
3921 .Vb 3
3922 \& \*(AqNow is the time for all\*(Aq
3923 \& . "\en"
3924 \& . \*(Aqgood men to come to.\*(Aq
3925 .Ve
3926 .PP
3927 and this all reduces to one string internally. Likewise, if
3928 you say
3929 .PP
3930 .Vb 3
3931 \& foreach $file (@filenames) {
3932 \& if (\-s $file > 5 + 100 * 2**16) { }
3933 \& }
3934 .Ve
3935 .PP
3936 the compiler precomputes the number which that expression
3937 represents so that the interpreter won't have to.
3938 .SS No-ops
3939 .IX Xref "no-op nop"
3940 .IX Subsection "No-ops"
3941 Perl doesn't officially have a no-op operator, but the bare constants
3942 \&\f(CW0\fR and \f(CW1\fR are special-cased not to produce a warning in void
3943 context, so you can for example safely do
3944 .PP
3945 .Vb 1
3946 \& 1 while foo();
3947 .Ve
3948 .SS "Bitwise String Operators"
3949 .IX Xref "operator, bitwise, string &. |. ^. ~."
3950 .IX Subsection "Bitwise String Operators"
3951 Bitstrings of any size may be manipulated by the bitwise operators
3952 (\f(CW\*(C`~ | & ^\*(C'\fR).
3953 .PP
3954 If the operands to a binary bitwise op are strings of different
3955 sizes, \fB|\fR and \fB^\fR ops act as though the shorter operand had
3956 additional zero bits on the right, while the \fB&\fR op acts as though
3957 the longer operand were truncated to the length of the shorter.
3958 The granularity for such extension or truncation is one or more
3959 bytes.
3960 .PP
3961 .Vb 5
3962 \& # ASCII\-based examples
3963 \& print "j p \en" ^ " a h"; # prints "JAPH\en"
3964 \& print "JA" | " ph\en"; # prints "japh\en"
3965 \& print "japh\enJunk" & \*(Aq_\|_\|_\|_\|_\*(Aq; # prints "JAPH\en";
3966 \& print \*(Aqp N$\*(Aq ^ " E<H\en"; # prints "Perl\en";
3967 .Ve
3968 .PP
3969 If you are intending to manipulate bitstrings, be certain that
3970 you're supplying bitstrings: If an operand is a number, that will imply
3971 a \fBnumeric\fR bitwise operation. You may explicitly show which type of
3972 operation you intend by using \f(CW""\fR or \f(CW\*(C`0+\*(C'\fR, as in the examples below.
3973 .PP
3974 .Vb 4
3975 \& $foo = 150 | 105; # yields 255 (0x96 | 0x69 is 0xFF)
3976 \& $foo = \*(Aq150\*(Aq | 105; # yields 255
3977 \& $foo = 150 | \*(Aq105\*(Aq; # yields 255
3978 \& $foo = \*(Aq150\*(Aq | \*(Aq105\*(Aq; # yields string \*(Aq155\*(Aq (under ASCII)
3979 \&
3980 \& $baz = 0+$foo & 0+$bar; # both ops explicitly numeric
3981 \& $biz = "$foo" ^ "$bar"; # both ops explicitly stringy
3982 .Ve
3983 .PP
3984 This somewhat unpredictable behavior can be avoided with the "bitwise"
3985 feature, new in Perl 5.22. You can enable it via \f(CWuse\ feature\ \*(Aqbitwise\*(Aq\fR or \f(CW\*(C`use v5.28\*(C'\fR. Before Perl 5.28, it used to emit a warning
3986 in the \f(CW"experimental::bitwise"\fR category. Under this feature, the four
3987 standard bitwise operators (\f(CW\*(C`~ | & ^\*(C'\fR) are always numeric. Adding a dot
3988 after each operator (\f(CW\*(C`~. |. &. ^.\*(C'\fR) forces it to treat its operands as
3989 strings:
3990 .PP
3991 .Vb 9
3992 \& use feature "bitwise";
3993 \& $foo = 150 | 105; # yields 255 (0x96 | 0x69 is 0xFF)
3994 \& $foo = \*(Aq150\*(Aq | 105; # yields 255
3995 \& $foo = 150 | \*(Aq105\*(Aq; # yields 255
3996 \& $foo = \*(Aq150\*(Aq | \*(Aq105\*(Aq; # yields 255
3997 \& $foo = 150 |. 105; # yields string \*(Aq155\*(Aq
3998 \& $foo = \*(Aq150\*(Aq |. 105; # yields string \*(Aq155\*(Aq
3999 \& $foo = 150 |.\*(Aq105\*(Aq; # yields string \*(Aq155\*(Aq
4000 \& $foo = \*(Aq150\*(Aq |.\*(Aq105\*(Aq; # yields string \*(Aq155\*(Aq
4001 \&
4002 \& $baz = $foo & $bar; # both operands numeric
4003 \& $biz = $foo ^. $bar; # both operands stringy
4004 .Ve
4005 .PP
4006 The assignment variants of these operators (\f(CW\*(C`&= |= ^= &.= |.= ^.=\*(C'\fR)
4007 behave likewise under the feature.
4008 .PP
4009 It is a fatal error if an operand contains a character whose ordinal
4010 value is above 0xFF, and hence not expressible except in UTF\-8. The
4011 operation is performed on a non\-UTF\-8 copy for other operands encoded in
4012 UTF\-8. See "Byte and Character Semantics" in perlunicode.
4013 .PP
4014 See "vec" in perlfunc for information on how to manipulate individual bits
4015 in a bit vector.
4016 .SS "Integer Arithmetic"
4017 .IX Xref "integer"
4018 .IX Subsection "Integer Arithmetic"
4019 By default, Perl assumes that it must do most of its arithmetic in
4020 floating point. But by saying
4021 .PP
4022 .Vb 1
4023 \& use integer;
4024 .Ve
4025 .PP
4026 you may tell the compiler to use integer operations
4027 (see integer for a detailed explanation) from here to the end of
4028 the enclosing BLOCK. An inner BLOCK may countermand this by saying
4029 .PP
4030 .Vb 1
4031 \& no integer;
4032 .Ve
4033 .PP
4034 which lasts until the end of that BLOCK. Note that this doesn't
4035 mean everything is an integer, merely that Perl will use integer
4036 operations for arithmetic, comparison, and bitwise operators. For
4037 example, even under \f(CW\*(C`use\ integer\*(C'\fR, if you take the \f(CWsqrt(2)\fR, you'll
4038 still get \f(CW1.4142135623731\fR or so.
4039 .PP
4040 Used on numbers, the bitwise operators (\f(CW\*(C`&\*(C'\fR \f(CW\*(C`|\*(C'\fR \f(CW\*(C`^\*(C'\fR \f(CW\*(C`~\*(C'\fR \f(CW\*(C`<<\*(C'\fR
4041 \&\f(CW\*(C`>>\*(C'\fR) always produce integral results. (But see also
4042 "Bitwise String Operators".) However, \f(CW\*(C`use\ integer\*(C'\fR still has meaning for
4043 them. By default, their results are interpreted as unsigned integers, but
4044 if \f(CW\*(C`use\ integer\*(C'\fR is in effect, their results are interpreted
4045 as signed integers. For example, \f(CW\*(C`~0\*(C'\fR usually evaluates to a large
4046 integral value. However, \f(CW\*(C`use\ integer;\ ~0\*(C'\fR is \f(CW\-1\fR on two's-complement
4047 machines.
4048 .SS "Floating-point Arithmetic"
4049 .IX Subsection "Floating-point Arithmetic"
4050
4051 .IX Xref "floating-point floating point float real"
4052 .PP
4053 While \f(CW\*(C`use\ integer\*(C'\fR provides integer-only arithmetic, there is no
4054 analogous mechanism to provide automatic rounding or truncation to a
4055 certain number of decimal places. For rounding to a certain number
4056 of digits, \f(CWsprintf()\fR or \f(CWprintf()\fR is usually the easiest route.
4057 See perlfaq4.
4058 .PP
4059 Floating-point numbers are only approximations to what a mathematician
4060 would call real numbers. There are infinitely more reals than floats,
4061 so some corners must be cut. For example:
4062 .PP
4063 .Vb 2
4064 \& printf "%.20g\en", 123456789123456789;
4065 \& # produces 123456789123456784
4066 .Ve
4067 .PP
4068 Testing for exact floating-point equality or inequality is not a
4069 good idea. Here's a (relatively expensive) work-around to compare
4070 whether two floating-point numbers are equal to a particular number of
4071 decimal places. See Knuth, volume II, for a more robust treatment of
4072 this topic.
4073 .PP
4074 .Vb 7
4075 \& sub fp_equal {
4076 \& my ($X, $Y, $POINTS) = @_;
4077 \& my ($tX, $tY);
4078 \& $tX = sprintf("%.${POINTS}g", $X);
4079 \& $tY = sprintf("%.${POINTS}g", $Y);
4080 \& return $tX eq $tY;
4081 \& }
4082 .Ve
4083 .PP
4084 The POSIX module (part of the standard perl distribution) implements
4085 \&\f(CWceil()\fR, \f(CWfloor()\fR, and other mathematical and trigonometric functions.
4086 The \f(CW\*(C`Math::Complex\*(C'\fR module (part of the standard perl distribution)
4087 defines mathematical functions that work on both the reals and the
4088 imaginary numbers. \f(CW\*(C`Math::Complex\*(C'\fR is not as efficient as POSIX, but
4089 POSIX can't work with complex numbers.
4090 .PP
4091 Rounding in financial applications can have serious implications, and
4092 the rounding method used should be specified precisely. In these
4093 cases, it probably pays not to trust whichever system rounding is
4094 being used by Perl, but to instead implement the rounding function you
4095 need yourself.
4096 .SS "Bigger Numbers"
4097 .IX Xref "number, arbitrary precision"
4098 .IX Subsection "Bigger Numbers"
4099 The standard \f(CW\*(C`Math::BigInt\*(C'\fR, \f(CW\*(C`Math::BigRat\*(C'\fR, and
4100 \&\f(CW\*(C`Math::BigFloat\*(C'\fR modules,
4101 along with the \f(CW\*(C`bignum\*(C'\fR, \f(CW\*(C`bigint\*(C'\fR, and \f(CW\*(C`bigrat\*(C'\fR pragmas, provide
4102 variable-precision arithmetic and overloaded operators, although
4103 they're currently pretty slow. At the cost of some space and
4104 considerable speed, they avoid the normal pitfalls associated with
4105 limited-precision representations.
4106 .PP
4107 .Vb 5
4108 \& use 5.010;
4109 \& use bigint; # easy interface to Math::BigInt
4110 \& $x = 123456789123456789;
4111 \& say $x * $x;
4112 \& +15241578780673678515622620750190521
4113 .Ve
4114 .PP
4115 Or with rationals:
4116 .PP
4117 .Vb 8
4118 \& use 5.010;
4119 \& use bigrat;
4120 \& $x = 3/22;
4121 \& $y = 4/6;
4122 \& say "x/y is ", $x/$y;
4123 \& say "x*y is ", $x*$y;
4124 \& x/y is 9/44
4125 \& x*y is 1/11
4126 .Ve
4127 .PP
4128 Several modules let you calculate with unlimited or fixed precision
4129 (bound only by memory and CPU time). There
4130 are also some non-standard modules that
4131 provide faster implementations via external C libraries.
4132 .PP
4133 Here is a short, but incomplete summary:
4134 .PP
4135 .Vb 10
4136 \& Math::String treat string sequences like numbers
4137 \& Math::FixedPrecision calculate with a fixed precision
4138 \& Math::Currency for currency calculations
4139 \& Bit::Vector manipulate bit vectors fast (uses C)
4140 \& Math::BigIntFast Bit::Vector wrapper for big numbers
4141 \& Math::Pari provides access to the Pari C library
4142 \& Math::Cephes uses the external Cephes C library (no
4143 \& big numbers)
4144 \& Math::Cephes::Fraction fractions via the Cephes library
4145 \& Math::GMP another one using an external C library
4146 \& Math::GMPz an alternative interface to libgmp\*(Aqs big ints
4147 \& Math::GMPq an interface to libgmp\*(Aqs fraction numbers
4148 \& Math::GMPf an interface to libgmp\*(Aqs floating point numbers
4149 .Ve
4150 .PP
4151 Choose wisely.
4152 .SH APPENDIX
4153 .IX Header "APPENDIX"
4154 .SS "List of Extra Paired Delimiters"
4155 .IX Subsection "List of Extra Paired Delimiters"
4156 The complete list of accepted paired delimiters as of Unicode 14.0 is:
4157 .PP
4158 .Vb 10
4159 \& ( ) U+0028, U+0029 LEFT/RIGHT PARENTHESIS
4160 \& < > U+003C, U+003E LESS\-THAN/GREATER\-THAN SIGN
4161 \& [ ] U+005B, U+005D LEFT/RIGHT SQUARE BRACKET
4162 \& { } U+007B, U+007D LEFT/RIGHT CURLY BRACKET
4163 \& « » U+00AB, U+00BB LEFT/RIGHT\-POINTING DOUBLE ANGLE QUOTATION MARK
4164 \& » « U+00BB, U+00AB RIGHT/LEFT\-POINTING DOUBLE ANGLE QUOTATION MARK
4165 \& ༺ ༻ U+0F3A, U+0F3B TIBETAN MARK GUG RTAGS GYON, TIBETAN MARK GUG
4166 \& RTAGS GYAS
4167 \& ༼ ༽ U+0F3C, U+0F3D TIBETAN MARK ANG KHANG GYON, TIBETAN MARK ANG
4168 \& KHANG GYAS
4169 \& ᚛ ᚜ U+169B, U+169C OGHAM FEATHER MARK, OGHAM REVERSED FEATHER MARK
4170 \& ‘ ’ U+2018, U+2019 LEFT/RIGHT SINGLE QUOTATION MARK
4171 \& ’ ‘ U+2019, U+2018 RIGHT/LEFT SINGLE QUOTATION MARK
4172 \& “ ” U+201C, U+201D LEFT/RIGHT DOUBLE QUOTATION MARK
4173 \& ” “ U+201D, U+201C RIGHT/LEFT DOUBLE QUOTATION MARK
4174 \& ‵ ′ U+2035, U+2032 REVERSED PRIME, PRIME
4175 \& ‶ ″ U+2036, U+2033 REVERSED DOUBLE PRIME, DOUBLE PRIME
4176 \& ‷ ‴ U+2037, U+2034 REVERSED TRIPLE PRIME, TRIPLE PRIME
4177 \& ‹ › U+2039, U+203A SINGLE LEFT/RIGHT\-POINTING ANGLE QUOTATION MARK
4178 \& › ‹ U+203A, U+2039 SINGLE RIGHT/LEFT\-POINTING ANGLE QUOTATION MARK
4179 \& ⁅ ⁆ U+2045, U+2046 LEFT/RIGHT SQUARE BRACKET WITH QUILL
4180 \& ⁍ ⁌ U+204D, U+204C BLACK RIGHT/LEFTWARDS BULLET
4181 \& ⁽ ⁾ U+207D, U+207E SUPERSCRIPT LEFT/RIGHT PARENTHESIS
4182 \& ₍ ₎ U+208D, U+208E SUBSCRIPT LEFT/RIGHT PARENTHESIS
4183 \& → ← U+2192, U+2190 RIGHT/LEFTWARDS ARROW
4184 \& ↛ ↚ U+219B, U+219A RIGHT/LEFTWARDS ARROW WITH STROKE
4185 \& ↝ ↜ U+219D, U+219C RIGHT/LEFTWARDS WAVE ARROW
4186 \& ↠ ↞ U+21A0, U+219E RIGHT/LEFTWARDS TWO HEADED ARROW
4187 \& ↣ ↢ U+21A3, U+21A2 RIGHT/LEFTWARDS ARROW WITH TAIL
4188 \& ↦ ↤ U+21A6, U+21A4 RIGHT/LEFTWARDS ARROW FROM BAR
4189 \& ↪ ↩ U+21AA, U+21A9 RIGHT/LEFTWARDS ARROW WITH HOOK
4190 \& ↬ ↫ U+21AC, U+21AB RIGHT/LEFTWARDS ARROW WITH LOOP
4191 \& ↱ ↰ U+21B1, U+21B0 UPWARDS ARROW WITH TIP RIGHT/LEFTWARDS
4192 \& ↳ ↲ U+21B3, U+21B2 DOWNWARDS ARROW WITH TIP RIGHT/LEFTWARDS
4193 \& ⇀ ↼ U+21C0, U+21BC RIGHT/LEFTWARDS HARPOON WITH BARB UPWARDS
4194 \& ⇁ ↽ U+21C1, U+21BD RIGHT/LEFTWARDS HARPOON WITH BARB DOWNWARDS
4195 \& ⇉ ⇇ U+21C9, U+21C7 RIGHT/LEFTWARDS PAIRED ARROWS
4196 \& ⇏ ⇍ U+21CF, U+21CD RIGHT/LEFTWARDS DOUBLE ARROW WITH STROKE
4197 \& ⇒ ⇐ U+21D2, U+21D0 RIGHT/LEFTWARDS DOUBLE ARROW
4198 \& ⇛ ⇚ U+21DB, U+21DA RIGHT/LEFTWARDS TRIPLE ARROW
4199 \& ⇝ ⇜ U+21DD, U+21DC RIGHT/LEFTWARDS SQUIGGLE ARROW
4200 \& ⇢ ⇠ U+21E2, U+21E0 RIGHT/LEFTWARDS DASHED ARROW
4201 \& ⇥ ⇤ U+21E5, U+21E4 RIGHT/LEFTWARDS ARROW TO BAR
4202 \& ⇨ ⇦ U+21E8, U+21E6 RIGHT/LEFTWARDS WHITE ARROW
4203 \& ⇴ ⬰ U+21F4, U+2B30 RIGHT/LEFT ARROW WITH SMALL CIRCLE
4204 \& ⇶ ⬱ U+21F6, U+2B31 THREE RIGHT/LEFTWARDS ARROWS
4205 \& ⇸ ⇷ U+21F8, U+21F7 RIGHT/LEFTWARDS ARROW WITH VERTICAL STROKE
4206 \& ⇻ ⇺ U+21FB, U+21FA RIGHT/LEFTWARDS ARROW WITH DOUBLE VERTICAL
4207 \& STROKE
4208 \& ⇾ ⇽ U+21FE, U+21FD RIGHT/LEFTWARDS OPEN\-HEADED ARROW
4209 \& ∈ ∋ U+2208, U+220B ELEMENT OF, CONTAINS AS MEMBER
4210 \& ∉ ∌ U+2209, U+220C NOT AN ELEMENT OF, DOES NOT CONTAIN AS MEMBER
4211 \& ∊ ∍ U+220A, U+220D SMALL ELEMENT OF, SMALL CONTAINS AS MEMBER
4212 \& ≤ ≥ U+2264, U+2265 LESS\-THAN/GREATER\-THAN OR EQUAL TO
4213 \& ≦ ≧ U+2266, U+2267 LESS\-THAN/GREATER\-THAN OVER EQUAL TO
4214 \& ≨ ≩ U+2268, U+2269 LESS\-THAN/GREATER\-THAN BUT NOT EQUAL TO
4215 \& ≪ ≫ U+226A, U+226B MUCH LESS\-THAN/GREATER\-THAN
4216 \& ≮ ≯ U+226E, U+226F NOT LESS\-THAN/GREATER\-THAN
4217 \& ≰ ≱ U+2270, U+2271 NEITHER LESS\-THAN/GREATER\-THAN NOR EQUAL TO
4218 \& ≲ ≳ U+2272, U+2273 LESS\-THAN/GREATER\-THAN OR EQUIVALENT TO
4219 \& ≴ ≵ U+2274, U+2275 NEITHER LESS\-THAN/GREATER\-THAN NOR EQUIVALENT TO
4220 \& ≺ ≻ U+227A, U+227B PRECEDES/SUCCEEDS
4221 \& ≼ ≽ U+227C, U+227D PRECEDES/SUCCEEDS OR EQUAL TO
4222 \& ≾ ≿ U+227E, U+227F PRECEDES/SUCCEEDS OR EQUIVALENT TO
4223 \& ⊀ ⊁ U+2280, U+2281 DOES NOT PRECEDE/SUCCEED
4224 \& ⊂ ⊃ U+2282, U+2283 SUBSET/SUPERSET OF
4225 \& ⊄ ⊅ U+2284, U+2285 NOT A SUBSET/SUPERSET OF
4226 \& ⊆ ⊇ U+2286, U+2287 SUBSET/SUPERSET OF OR EQUAL TO
4227 \& ⊈ ⊉ U+2288, U+2289 NEITHER A SUBSET/SUPERSET OF NOR EQUAL TO
4228 \& ⊊ ⊋ U+228A, U+228B SUBSET/SUPERSET OF WITH NOT EQUAL TO
4229 \& ⊣ ⊢ U+22A3, U+22A2 LEFT/RIGHT TACK
4230 \& ⊦ ⫞ U+22A6, U+2ADE ASSERTION, SHORT LEFT TACK
4231 \& ⊨ ⫤ U+22A8, U+2AE4 TRUE, VERTICAL BAR DOUBLE LEFT TURNSTILE
4232 \& ⊩ ⫣ U+22A9, U+2AE3 FORCES, DOUBLE VERTICAL BAR LEFT TURNSTILE
4233 \& ⊰ ⊱ U+22B0, U+22B1 PRECEDES/SUCCEEDS UNDER RELATION
4234 \& ⋐ ⋑ U+22D0, U+22D1 DOUBLE SUBSET/SUPERSET
4235 \& ⋖ ⋗ U+22D6, U+22D7 LESS\-THAN/GREATER\-THAN WITH DOT
4236 \& ⋘ ⋙ U+22D8, U+22D9 VERY MUCH LESS\-THAN/GREATER\-THAN
4237 \& ⋜ ⋝ U+22DC, U+22DD EQUAL TO OR LESS\-THAN/GREATER\-THAN
4238 \& ⋞ ⋟ U+22DE, U+22DF EQUAL TO OR PRECEDES/SUCCEEDS
4239 \& ⋠ ⋡ U+22E0, U+22E1 DOES NOT PRECEDE/SUCCEED OR EQUAL
4240 \& ⋦ ⋧ U+22E6, U+22E7 LESS\-THAN/GREATER\-THAN BUT NOT EQUIVALENT TO
4241 \& ⋨ ⋩ U+22E8, U+22E9 PRECEDES/SUCCEEDS BUT NOT EQUIVALENT TO
4242 \& ⋲ ⋺ U+22F2, U+22FA ELEMENT OF/CONTAINS WITH LONG HORIZONTAL STROKE
4243 \& ⋳ ⋻ U+22F3, U+22FB ELEMENT OF/CONTAINS WITH VERTICAL BAR AT END OF
4244 \& HORIZONTAL STROKE
4245 \& ⋴ ⋼ U+22F4, U+22FC SMALL ELEMENT OF/CONTAINS WITH VERTICAL BAR AT
4246 \& END OF HORIZONTAL STROKE
4247 \& ⋶ ⋽ U+22F6, U+22FD ELEMENT OF/CONTAINS WITH OVERBAR
4248 \& ⋷ ⋾ U+22F7, U+22FE SMALL ELEMENT OF/CONTAINS WITH OVERBAR
4249 \& ⌈ ⌉ U+2308, U+2309 LEFT/RIGHT CEILING
4250 \& ⌊ ⌋ U+230A, U+230B LEFT/RIGHT FLOOR
4251 \& ⌦ ⌫ U+2326, U+232B ERASE TO THE RIGHT/LEFT
4252 \& 〈 〉 U+2329, U+232A LEFT/RIGHT\-POINTING ANGLE BRACKET
4253 \& ⍈ ⍇ U+2348, U+2347 APL FUNCTIONAL SYMBOL QUAD RIGHT/LEFTWARDS ARROW
4254 \& ⏩ ⏪ U+23E9, U+23EA BLACK RIGHT/LEFT\-POINTING DOUBLE TRIANGLE
4255 \& ⏭ ⏮ U+23ED, U+23EE BLACK RIGHT/LEFT\-POINTING DOUBLE TRIANGLE WITH
4256 \& VERTICAL BAR
4257 \& ☛ ☚ U+261B, U+261A BLACK RIGHT/LEFT POINTING INDEX
4258 \& ☞ ☜ U+261E, U+261C WHITE RIGHT/LEFT POINTING INDEX
4259 \& ⚞ ⚟ U+269E, U+269F THREE LINES CONVERGING RIGHT/LEFT
4260 \& ❨ ❩ U+2768, U+2769 MEDIUM LEFT/RIGHT PARENTHESIS ORNAMENT
4261 \& ❪ ❫ U+276A, U+276B MEDIUM FLATTENED LEFT/RIGHT PARENTHESIS ORNAMENT
4262 \& ❬ ❭ U+276C, U+276D MEDIUM LEFT/RIGHT\-POINTING ANGLE BRACKET
4263 \& ORNAMENT
4264 \& ❮ ❯ U+276E, U+276F HEAVY LEFT/RIGHT\-POINTING ANGLE QUOTATION MARK
4265 \& ORNAMENT
4266 \& ❰ ❱ U+2770, U+2771 HEAVY LEFT/RIGHT\-POINTING ANGLE BRACKET ORNAMENT
4267 \& ❲ ❳ U+2772, U+2773 LIGHT LEFT/RIGHT TORTOISE SHELL BRACKET ORNAMENT
4268 \& ❴ ❵ U+2774, U+2775 MEDIUM LEFT/RIGHT CURLY BRACKET ORNAMENT
4269 \& ⟃ ⟄ U+27C3, U+27C4 OPEN SUBSET/SUPERSET
4270 \& ⟅ ⟆ U+27C5, U+27C6 LEFT/RIGHT S\-SHAPED BAG DELIMITER
4271 \& ⟈ ⟉ U+27C8, U+27C9 REVERSE SOLIDUS PRECEDING SUBSET, SUPERSET
4272 \& PRECEDING SOLIDUS
4273 \& ⟞ ⟝ U+27DE, U+27DD LONG LEFT/RIGHT TACK
4274 \& ⟦ ⟧ U+27E6, U+27E7 MATHEMATICAL LEFT/RIGHT WHITE SQUARE BRACKET
4275 \& ⟨ ⟩ U+27E8, U+27E9 MATHEMATICAL LEFT/RIGHT ANGLE BRACKET
4276 \& ⟪ ⟫ U+27EA, U+27EB MATHEMATICAL LEFT/RIGHT DOUBLE ANGLE BRACKET
4277 \& ⟬ ⟭ U+27EC, U+27ED MATHEMATICAL LEFT/RIGHT WHITE TORTOISE SHELL
4278 \& BRACKET
4279 \& ⟮ ⟯ U+27EE, U+27EF MATHEMATICAL LEFT/RIGHT FLATTENED PARENTHESIS
4280 \& ⟴ ⬲ U+27F4, U+2B32 RIGHT/LEFT ARROW WITH CIRCLED PLUS
4281 \& ⟶ ⟵ U+27F6, U+27F5 LONG RIGHT/LEFTWARDS ARROW
4282 \& ⟹ ⟸ U+27F9, U+27F8 LONG RIGHT/LEFTWARDS DOUBLE ARROW
4283 \& ⟼ ⟻ U+27FC, U+27FB LONG RIGHT/LEFTWARDS ARROW FROM BAR
4284 \& ⟾ ⟽ U+27FE, U+27FD LONG RIGHT/LEFTWARDS DOUBLE ARROW FROM BAR
4285 \& ⟿ ⬳ U+27FF, U+2B33 LONG RIGHT/LEFTWARDS SQUIGGLE ARROW
4286 \& ⤀ ⬴ U+2900, U+2B34 RIGHT/LEFTWARDS TWO\-HEADED ARROW WITH VERTICAL
4287 \& STROKE
4288 \& ⤁ ⬵ U+2901, U+2B35 RIGHT/LEFTWARDS TWO\-HEADED ARROW WITH DOUBLE
4289 \& VERTICAL STROKE
4290 \& ⤃ ⤂ U+2903, U+2902 RIGHT/LEFTWARDS DOUBLE ARROW WITH VERTICAL
4291 \& STROKE
4292 \& ⤅ ⬶ U+2905, U+2B36 RIGHT/LEFTWARDS TWO\-HEADED ARROW FROM BAR
4293 \& ⤇ ⤆ U+2907, U+2906 RIGHT/LEFTWARDS DOUBLE ARROW FROM BAR
4294 \& ⤍ ⤌ U+290D, U+290C RIGHT/LEFTWARDS DOUBLE DASH ARROW
4295 \& ⤏ ⤎ U+290F, U+290E RIGHT/LEFTWARDS TRIPLE DASH ARROW
4296 \& ⤐ ⬷ U+2910, U+2B37 RIGHT/LEFTWARDS TWO\-HEADED TRIPLE DASH ARROW
4297 \& ⤑ ⬸ U+2911, U+2B38 RIGHT/LEFTWARDS ARROW WITH DOTTED STEM
4298 \& ⤔ ⬹ U+2914, U+2B39 RIGHT/LEFTWARDS ARROW WITH TAIL WITH VERTICAL
4299 \& STROKE
4300 \& ⤕ ⬺ U+2915, U+2B3A RIGHT/LEFTWARDS ARROW WITH TAIL WITH DOUBLE
4301 \& VERTICAL STROKE
4302 \& ⤖ ⬻ U+2916, U+2B3B RIGHT/LEFTWARDS TWO\-HEADED ARROW WITH TAIL
4303 \& ⤗ ⬼ U+2917, U+2B3C RIGHT/LEFTWARDS TWO\-HEADED ARROW WITH TAIL WITH
4304 \& VERTICAL STROKE
4305 \& ⤘ ⬽ U+2918, U+2B3D RIGHT/LEFTWARDS TWO\-HEADED ARROW WITH TAIL WITH
4306 \& DOUBLE VERTICAL STROKE
4307 \& ⤚ ⤙ U+291A, U+2919 RIGHT/LEFTWARDS ARROW\-TAIL
4308 \& ⤜ ⤛ U+291C, U+291B RIGHT/LEFTWARDS DOUBLE ARROW\-TAIL
4309 \& ⤞ ⤝ U+291E, U+291D RIGHT/LEFTWARDS ARROW TO BLACK DIAMOND
4310 \& ⤠ ⤟ U+2920, U+291F RIGHT/LEFTWARDS ARROW FROM BAR TO BLACK DIAMOND
4311 \& ⤳ ⬿ U+2933, U+2B3F WAVE ARROW POINTING DIRECTLY RIGHT/LEFT
4312 \& ⤷ ⤶ U+2937, U+2936 ARROW POINTING DOWNWARDS THEN CURVING RIGHT/
4313 \& LEFTWARDS
4314 \& ⥅ ⥆ U+2945, U+2946 RIGHT/LEFTWARDS ARROW WITH PLUS BELOW
4315 \& ⥇ ⬾ U+2947, U+2B3E RIGHT/LEFTWARDS ARROW THROUGH X
4316 \& ⥓ ⥒ U+2953, U+2952 RIGHT/LEFTWARDS HARPOON WITH BARB UP TO BAR
4317 \& ⥗ ⥖ U+2957, U+2956 RIGHT/LEFTWARDS HARPOON WITH BARB DOWN TO BAR
4318 \& ⥛ ⥚ U+295B, U+295A RIGHT/LEFTWARDS HARPOON WITH BARB UP FROM BAR
4319 \& ⥟ ⥞ U+295F, U+295E RIGHT/LEFTWARDS HARPOON WITH BARB DOWN FROM BAR
4320 \& ⥤ ⥢ U+2964, U+2962 RIGHT/LEFTWARDS HARPOON WITH BARB UP ABOVE
4321 \& RIGHT/LEFTWARDS HARPOON WITH BARB DOWN
4322 \& ⥬ ⥪ U+296C, U+296A RIGHT/LEFTWARDS HARPOON WITH BARB UP ABOVE LONG
4323 \& DASH
4324 \& ⥭ ⥫ U+296D, U+296B RIGHT/LEFTWARDS HARPOON WITH BARB DOWN BELOW
4325 \& LONG DASH
4326 \& ⥱ ⭀ U+2971, U+2B40 EQUALS SIGN ABOVE RIGHT/LEFTWARDS ARROW
4327 \& ⥲ ⭁ U+2972, U+2B41 TILDE OPERATOR ABOVE RIGHTWARDS ARROW, REVERSE
4328 \& TILDE OPERATOR ABOVE LEFTWARDS ARROW
4329 \& ⥴ ⭋ U+2974, U+2B4B RIGHTWARDS ARROW ABOVE TILDE OPERATOR,
4330 \& LEFTWARDS ARROW ABOVE REVERSE TILDE OPERATOR
4331 \& ⥵ ⭂ U+2975, U+2B42 RIGHTWARDS ARROW ABOVE ALMOST EQUAL TO,
4332 \& LEFTWARDS ARROW ABOVE REVERSE ALMOST EQUAL TO
4333 \& ⥹ ⥻ U+2979, U+297B SUBSET/SUPERSET ABOVE RIGHT/LEFTWARDS ARROW
4334 \& ⦃ ⦄ U+2983, U+2984 LEFT/RIGHT WHITE CURLY BRACKET
4335 \& ⦅ ⦆ U+2985, U+2986 LEFT/RIGHT WHITE PARENTHESIS
4336 \& ⦇ ⦈ U+2987, U+2988 Z NOTATION LEFT/RIGHT IMAGE BRACKET
4337 \& ⦉ ⦊ U+2989, U+298A Z NOTATION LEFT/RIGHT BINDING BRACKET
4338 \& ⦋ ⦌ U+298B, U+298C LEFT/RIGHT SQUARE BRACKET WITH UNDERBAR
4339 \& ⦍ ⦐ U+298D, U+2990 LEFT/RIGHT SQUARE BRACKET WITH TICK IN TOP
4340 \& CORNER
4341 \& ⦏ ⦎ U+298F, U+298E LEFT/RIGHT SQUARE BRACKET WITH TICK IN BOTTOM
4342 \& CORNER
4343 \& ⦑ ⦒ U+2991, U+2992 LEFT/RIGHT ANGLE BRACKET WITH DOT
4344 \& ⦓ ⦔ U+2993, U+2994 LEFT/RIGHT ARC LESS\-THAN/GREATER\-THAN BRACKET
4345 \& ⦕ ⦖ U+2995, U+2996 DOUBLE LEFT/RIGHT ARC GREATER\-THAN/LESS\-THAN
4346 \& BRACKET
4347 \& ⦗ ⦘ U+2997, U+2998 LEFT/RIGHT BLACK TORTOISE SHELL BRACKET
4348 \& ⦨ ⦩ U+29A8, U+29A9 MEASURED ANGLE WITH OPEN ARM ENDING IN ARROW
4349 \& POINTING UP AND RIGHT/LEFT
4350 \& ⦪ ⦫ U+29AA, U+29AB MEASURED ANGLE WITH OPEN ARM ENDING IN ARROW
4351 \& POINTING DOWN AND RIGHT/LEFT
4352 \& ⦳ ⦴ U+29B3, U+29B4 EMPTY SET WITH RIGHT/LEFT ARROW ABOVE
4353 \& ⧀ ⧁ U+29C0, U+29C1 CIRCLED LESS\-THAN/GREATER\-THAN
4354 \& ⧘ ⧙ U+29D8, U+29D9 LEFT/RIGHT WIGGLY FENCE
4355 \& ⧚ ⧛ U+29DA, U+29DB LEFT/RIGHT DOUBLE WIGGLY FENCE
4356 \& ⧼ ⧽ U+29FC, U+29FD LEFT/RIGHT\-POINTING CURVED ANGLE BRACKET
4357 \& ⩹ ⩺ U+2A79, U+2A7A LESS\-THAN/GREATER\-THAN WITH CIRCLE INSIDE
4358 \& ⩻ ⩼ U+2A7B, U+2A7C LESS\-THAN/GREATER\-THAN WITH QUESTION MARK ABOVE
4359 \& ⩽ ⩾ U+2A7D, U+2A7E LESS\-THAN/GREATER\-THAN OR SLANTED EQUAL TO
4360 \& ⩿ ⪀ U+2A7F, U+2A80 LESS\-THAN/GREATER\-THAN OR SLANTED EQUAL TO WITH
4361 \& DOT INSIDE
4362 \& ⪁ ⪂ U+2A81, U+2A82 LESS\-THAN/GREATER\-THAN OR SLANTED EQUAL TO WITH
4363 \& DOT ABOVE
4364 \& ⪃ ⪄ U+2A83, U+2A84 LESS\-THAN/GREATER\-THAN OR SLANTED EQUAL TO WITH
4365 \& DOT ABOVE RIGHT/LEFT
4366 \& ⪅ ⪆ U+2A85, U+2A86 LESS\-THAN/GREATER\-THAN OR APPROXIMATE
4367 \& ⪇ ⪈ U+2A87, U+2A88 LESS\-THAN/GREATER\-THAN AND SINGLE\-LINE NOT
4368 \& EQUAL TO
4369 \& ⪉ ⪊ U+2A89, U+2A8A LESS\-THAN/GREATER\-THAN AND NOT APPROXIMATE
4370 \& ⪍ ⪎ U+2A8D, U+2A8E LESS\-THAN/GREATER\-THAN ABOVE SIMILAR OR EQUAL
4371 \& ⪕ ⪖ U+2A95, U+2A96 SLANTED EQUAL TO OR LESS\-THAN/GREATER\-THAN
4372 \& ⪗ ⪘ U+2A97, U+2A98 SLANTED EQUAL TO OR LESS\-THAN/GREATER\-THAN WITH
4373 \& DOT INSIDE
4374 \& ⪙ ⪚ U+2A99, U+2A9A DOUBLE\-LINE EQUAL TO OR LESS\-THAN/GREATER\-THAN
4375 \& ⪛ ⪜ U+2A9B, U+2A9C DOUBLE\-LINE SLANTED EQUAL TO OR LESS\-THAN/
4376 \& GREATER\-THAN
4377 \& ⪝ ⪞ U+2A9D, U+2A9E SIMILAR OR LESS\-THAN/GREATER\-THAN
4378 \& ⪟ ⪠ U+2A9F, U+2AA0 SIMILAR ABOVE LESS\-THAN/GREATER\-THAN ABOVE
4379 \& EQUALS SIGN
4380 \& ⪡ ⪢ U+2AA1, U+2AA2 DOUBLE NESTED LESS\-THAN/GREATER\-THAN
4381 \& ⪦ ⪧ U+2AA6, U+2AA7 LESS\-THAN/GREATER\-THAN CLOSED BY CURVE
4382 \& ⪨ ⪩ U+2AA8, U+2AA9 LESS\-THAN/GREATER\-THAN CLOSED BY CURVE ABOVE
4383 \& SLANTED EQUAL
4384 \& ⪪ ⪫ U+2AAA, U+2AAB SMALLER THAN/LARGER THAN
4385 \& ⪬ ⪭ U+2AAC, U+2AAD SMALLER THAN/LARGER THAN OR EQUAL TO
4386 \& ⪯ ⪰ U+2AAF, U+2AB0 PRECEDES/SUCCEEDS ABOVE SINGLE\-LINE EQUALS SIGN
4387 \& ⪱ ⪲ U+2AB1, U+2AB2 PRECEDES/SUCCEEDS ABOVE SINGLE\-LINE NOT EQUAL TO
4388 \& ⪳ ⪴ U+2AB3, U+2AB4 PRECEDES/SUCCEEDS ABOVE EQUALS SIGN
4389 \& ⪵ ⪶ U+2AB5, U+2AB6 PRECEDES/SUCCEEDS ABOVE NOT EQUAL TO
4390 \& ⪷ ⪸ U+2AB7, U+2AB8 PRECEDES/SUCCEEDS ABOVE ALMOST EQUAL TO
4391 \& ⪹ ⪺ U+2AB9, U+2ABA PRECEDES/SUCCEEDS ABOVE NOT ALMOST EQUAL TO
4392 \& ⪻ ⪼ U+2ABB, U+2ABC DOUBLE PRECEDES/SUCCEEDS
4393 \& ⪽ ⪾ U+2ABD, U+2ABE SUBSET/SUPERSET WITH DOT
4394 \& ⪿ ⫀ U+2ABF, U+2AC0 SUBSET/SUPERSET WITH PLUS SIGN BELOW
4395 \& ⫁ ⫂ U+2AC1, U+2AC2 SUBSET/SUPERSET WITH MULTIPLICATION SIGN BELOW
4396 \& ⫃ ⫄ U+2AC3, U+2AC4 SUBSET/SUPERSET OF OR EQUAL TO WITH DOT ABOVE
4397 \& ⫅ ⫆ U+2AC5, U+2AC6 SUBSET/SUPERSET OF ABOVE EQUALS SIGN
4398 \& ⫇ ⫈ U+2AC7, U+2AC8 SUBSET/SUPERSET OF ABOVE TILDE OPERATOR
4399 \& ⫉ ⫊ U+2AC9, U+2ACA SUBSET/SUPERSET OF ABOVE ALMOST EQUAL TO
4400 \& ⫋ ⫌ U+2ACB, U+2ACC SUBSET/SUPERSET OF ABOVE NOT EQUAL TO
4401 \& ⫏ ⫐ U+2ACF, U+2AD0 CLOSED SUBSET/SUPERSET
4402 \& ⫑ ⫒ U+2AD1, U+2AD2 CLOSED SUBSET/SUPERSET OR EQUAL TO
4403 \& ⫕ ⫖ U+2AD5, U+2AD6 SUBSET/SUPERSET ABOVE SUBSET/SUPERSET
4404 \& ⫥ ⊫ U+2AE5, U+22AB DOUBLE VERTICAL BAR DOUBLE LEFT/RIGHT TURNSTILE
4405 \& ⫷ ⫸ U+2AF7, U+2AF8 TRIPLE NESTED LESS\-THAN/GREATER\-THAN
4406 \& ⫹ ⫺ U+2AF9, U+2AFA DOUBLE\-LINE SLANTED LESS\-THAN/GREATER\-THAN OR
4407 \& EQUAL TO
4408 \& ⭆ ⭅ U+2B46, U+2B45 RIGHT/LEFTWARDS QUADRUPLE ARROW
4409 \& ⭇ ⭉ U+2B47, U+2B49 REVERSE TILDE OPERATOR ABOVE RIGHTWARDS ARROW,
4410 \& TILDE OPERATOR ABOVE LEFTWARDS ARROW
4411 \& ⭈ ⭊ U+2B48, U+2B4A RIGHTWARDS ARROW ABOVE REVERSE ALMOST EQUAL
4412 \& TO, LEFTWARDS ARROW ABOVE ALMOST EQUAL TO
4413 \& ⭌ ⥳ U+2B4C, U+2973 RIGHTWARDS ARROW ABOVE REVERSE TILDE OPERATOR,
4414 \& LEFTWARDS ARROW ABOVE TILDE OPERATOR
4415 \& ⭢ ⭠ U+2B62, U+2B60 RIGHT/LEFTWARDS TRIANGLE\-HEADED ARROW
4416 \& ⭬ ⭪ U+2B6C, U+2B6A RIGHT/LEFTWARDS TRIANGLE\-HEADED DASHED ARROW
4417 \& ⭲ ⭰ U+2B72, U+2B70 RIGHT/LEFTWARDS TRIANGLE\-HEADED ARROW TO BAR
4418 \& ⭼ ⭺ U+2B7C, U+2B7A RIGHT/LEFTWARDS TRIANGLE\-HEADED ARROW WITH
4419 \& DOUBLE VERTICAL STROKE
4420 \& ⮆ ⮄ U+2B86, U+2B84 RIGHT/LEFTWARDS TRIANGLE\-HEADED PAIRED ARROWS
4421 \& ⮊ ⮈ U+2B8A, U+2B88 RIGHT/LEFTWARDS BLACK CIRCLED WHITE ARROW
4422 \& ⮕ ⬅ U+2B95, U+2B05 RIGHT/LEFTWARDS BLACK ARROW
4423 \& ⮚ ⮘ U+2B9A, U+2B98 THREE\-D TOP\-LIGHTED RIGHT/LEFTWARDS EQUILATERAL
4424 \& ARROWHEAD
4425 \& ⮞ ⮜ U+2B9E, U+2B9C BLACK RIGHT/LEFTWARDS EQUILATERAL ARROWHEAD
4426 \& ⮡ ⮠ U+2BA1, U+2BA0 DOWNWARDS TRIANGLE\-HEADED ARROW WITH LONG TIP
4427 \& RIGHT/LEFTWARDS
4428 \& ⮣ ⮢ U+2BA3, U+2BA2 UPWARDS TRIANGLE\-HEADED ARROW WITH LONG TIP
4429 \& RIGHT/LEFTWARDS
4430 \& ⮩ ⮨ U+2BA9, U+2BA8 BLACK CURVED DOWNWARDS AND RIGHT/LEFTWARDS ARROW
4431 \& ⮫ ⮪ U+2BAB, U+2BAA BLACK CURVED UPWARDS AND RIGHT/LEFTWARDS ARROW
4432 \& ⮱ ⮰ U+2BB1, U+2BB0 RIBBON ARROW DOWN RIGHT/LEFT
4433 \& ⮳ ⮲ U+2BB3, U+2BB2 RIBBON ARROW UP RIGHT/LEFT
4434 \& ⯮ ⯬ U+2BEE, U+2BEC RIGHT/LEFTWARDS TWO\-HEADED ARROW WITH TRIANGLE
4435 \& ARROWHEADS
4436 \& ⸂ ⸃ U+2E02, U+2E03 LEFT/RIGHT SUBSTITUTION BRACKET
4437 \& ⸃ ⸂ U+2E03, U+2E02 RIGHT/LEFT SUBSTITUTION BRACKET
4438 \& ⸄ ⸅ U+2E04, U+2E05 LEFT/RIGHT DOTTED SUBSTITUTION BRACKET
4439 \& ⸅ ⸄ U+2E05, U+2E04 RIGHT/LEFT DOTTED SUBSTITUTION BRACKET
4440 \& ⸉ ⸊ U+2E09, U+2E0A LEFT/RIGHT TRANSPOSITION BRACKET
4441 \& ⸊ ⸉ U+2E0A, U+2E09 RIGHT/LEFT TRANSPOSITION BRACKET
4442 \& ⸌ ⸍ U+2E0C, U+2E0D LEFT/RIGHT RAISED OMISSION BRACKET
4443 \& ⸍ ⸌ U+2E0D, U+2E0C RIGHT/LEFT RAISED OMISSION BRACKET
4444 \& ⸑ ⸐ U+2E11, U+2E10 REVERSED FORKED PARAGRAPHOS, FORKED PARAGRAPHOS
4445 \& ⸜ ⸝ U+2E1C, U+2E1D LEFT/RIGHT LOW PARAPHRASE BRACKET
4446 \& ⸝ ⸜ U+2E1D, U+2E1C RIGHT/LEFT LOW PARAPHRASE BRACKET
4447 \& ⸠ ⸡ U+2E20, U+2E21 LEFT/RIGHT VERTICAL BAR WITH QUILL
4448 \& ⸡ ⸠ U+2E21, U+2E20 RIGHT/LEFT VERTICAL BAR WITH QUILL
4449 \& ⸢ ⸣ U+2E22, U+2E23 TOP LEFT/RIGHT HALF BRACKET
4450 \& ⸤ ⸥ U+2E24, U+2E25 BOTTOM LEFT/RIGHT HALF BRACKET
4451 \& ⸦ ⸧ U+2E26, U+2E27 LEFT/RIGHT SIDEWAYS U BRACKET
4452 \& ⸨ ⸩ U+2E28, U+2E29 LEFT/RIGHT DOUBLE PARENTHESIS
4453 \& ⸶ ⸷ U+2E36, U+2E37 DAGGER WITH LEFT/RIGHT GUARD
4454 \& ⹂ „ U+2E42, U+201E DOUBLE LOW\-REVERSED\-9 QUOTATION MARK, DOUBLE
4455 \& LOW\-9 QUOTATION MARK
4456 \& ⹕ ⹖ U+2E55, U+2E56 LEFT/RIGHT SQUARE BRACKET WITH STROKE
4457 \& ⹗ ⹘ U+2E57, U+2E58 LEFT/RIGHT SQUARE BRACKET WITH DOUBLE STROKE
4458 \& ⹙ ⹚ U+2E59, U+2E5A TOP HALF LEFT/RIGHT PARENTHESIS
4459 \& ⹛ ⹜ U+2E5B, U+2E5C BOTTOM HALF LEFT/RIGHT PARENTHESIS
4460 \& 〈 〉 U+3008, U+3009 LEFT/RIGHT ANGLE BRACKET
4461 \& 《 》 U+300A, U+300B LEFT/RIGHT DOUBLE ANGLE BRACKET
4462 \& 「 」 U+300C, U+300D LEFT/RIGHT CORNER BRACKET
4463 \& 『 』 U+300E, U+300F LEFT/RIGHT WHITE CORNER BRACKET
4464 \& 【 】 U+3010, U+3011 LEFT/RIGHT BLACK LENTICULAR BRACKET
4465 \& 〔 〕 U+3014, U+3015 LEFT/RIGHT TORTOISE SHELL BRACKET
4466 \& 〖 〗 U+3016, U+3017 LEFT/RIGHT WHITE LENTICULAR BRACKET
4467 \& 〘 〙 U+3018, U+3019 LEFT/RIGHT WHITE TORTOISE SHELL BRACKET
4468 \& 〚 〛 U+301A, U+301B LEFT/RIGHT WHITE SQUARE BRACKET
4469 \& 〝 〞 U+301D, U+301E REVERSED DOUBLE PRIME QUOTATION MARK, DOUBLE
4470 \& PRIME QUOTATION MARK
4471 \& ꧁ ꧂ U+A9C1, U+A9C2 JAVANESE LEFT/RIGHT RERENGGAN
4472 \& ﴾ ﴿ U+FD3E, U+FD3F ORNATE LEFT/RIGHT PARENTHESIS
4473 \& ﹙ ﹚ U+FE59, U+FE5A SMALL LEFT/RIGHT PARENTHESIS
4474 \& ﹛ ﹜ U+FE5B, U+FE5C SMALL LEFT/RIGHT CURLY BRACKET
4475 \& ﹝ ﹞ U+FE5D, U+FE5E SMALL LEFT/RIGHT TORTOISE SHELL BRACKET
4476 \& ﹤ ﹥ U+FE64, U+FE65 SMALL LESS\-THAN/GREATER\-THAN SIGN
4477 \& ( ) U+FF08, U+FF09 FULLWIDTH LEFT/RIGHT PARENTHESIS
4478 \& < > U+FF1C, U+FF1E FULLWIDTH LESS\-THAN/GREATER\-THAN SIGN
4479 \& [ ] U+FF3B, U+FF3D FULLWIDTH LEFT/RIGHT SQUARE BRACKET
4480 \& { } U+FF5B, U+FF5D FULLWIDTH LEFT/RIGHT CURLY BRACKET
4481 \& ⦅ ⦆ U+FF5F, U+FF60 FULLWIDTH LEFT/RIGHT WHITE PARENTHESIS
4482 \& 「 」 U+FF62, U+FF63 HALFWIDTH LEFT/RIGHT CORNER BRACKET
4483 \& → ← U+FFEB, U+FFE9 HALFWIDTH RIGHT/LEFTWARDS ARROW
4484 \& 𝄃 𝄂 U+1D103, U+1D102 MUSICAL SYMBOL REVERSE FINAL BARLINE, MUSICAL
4485 \& SYMBOL FINAL BARLINE
4486 \& 𝄆 𝄇 U+1D106, U+1D107 MUSICAL SYMBOL LEFT/RIGHT REPEAT SIGN
4487 \& 👉 👈 U+1F449, U+1F448 WHITE RIGHT/LEFT POINTING BACKHAND INDEX
4488 \& 🔈 🕨 U+1F508, U+1F568 SPEAKER, RIGHT SPEAKER
4489 \& 🔉 🕩 U+1F509, U+1F569 SPEAKER WITH ONE SOUND WAVE, RIGHT SPEAKER WITH
4490 \& ONE SOUND WAVE
4491 \& 🔊 🕪 U+1F50A, U+1F56A SPEAKER WITH THREE SOUND WAVES, RIGHT SPEAKER
4492 \& WITH THREE SOUND WAVES
4493 \& 🕻 🕽 U+1F57B, U+1F57D LEFT/RIGHT HAND TELEPHONE RECEIVER
4494 \& 🖙 🖘 U+1F599, U+1F598 SIDEWAYS WHITE RIGHT/LEFT POINTING INDEX
4495 \& 🖛 🖚 U+1F59B, U+1F59A SIDEWAYS BLACK RIGHT/LEFT POINTING INDEX
4496 \& 🖝 🖜 U+1F59D, U+1F59C BLACK RIGHT/LEFT POINTING BACKHAND INDEX
4497 \& 🗦 🗧 U+1F5E6, U+1F5E7 THREE RAYS LEFT/RIGHT
4498 \& 🠂 🠀 U+1F802, U+1F800 RIGHT/LEFTWARDS ARROW WITH SMALL TRIANGLE
4499 \& ARROWHEAD
4500 \& 🠆 🠄 U+1F806, U+1F804 RIGHT/LEFTWARDS ARROW WITH MEDIUM TRIANGLE
4501 \& ARROWHEAD
4502 \& 🠊 🠈 U+1F80A, U+1F808 RIGHT/LEFTWARDS ARROW WITH LARGE TRIANGLE
4503 \& ARROWHEAD
4504 \& 🠒 🠐 U+1F812, U+1F810 RIGHT/LEFTWARDS ARROW WITH SMALL EQUILATERAL
4505 \& ARROWHEAD
4506 \& 🠖 🠔 U+1F816, U+1F814 RIGHT/LEFTWARDS ARROW WITH EQUILATERAL ARROWHEAD
4507 \& 🠚 🠘 U+1F81A, U+1F818 HEAVY RIGHT/LEFTWARDS ARROW WITH EQUILATERAL
4508 \& ARROWHEAD
4509 \& 🠞 🠜 U+1F81E, U+1F81C HEAVY RIGHT/LEFTWARDS ARROW WITH LARGE
4510 \& EQUILATERAL ARROWHEAD
4511 \& 🠢 🠠 U+1F822, U+1F820 RIGHT/LEFTWARDS TRIANGLE\-HEADED ARROW WITH
4512 \& NARROW SHAFT
4513 \& 🠦 🠤 U+1F826, U+1F824 RIGHT/LEFTWARDS TRIANGLE\-HEADED ARROW WITH
4514 \& MEDIUM SHAFT
4515 \& 🠪 🠨 U+1F82A, U+1F828 RIGHT/LEFTWARDS TRIANGLE\-HEADED ARROW WITH BOLD
4516 \& SHAFT
4517 \& 🠮 🠬 U+1F82E, U+1F82C RIGHT/LEFTWARDS TRIANGLE\-HEADED ARROW WITH
4518 \& HEAVY SHAFT
4519 \& 🠲 🠰 U+1F832, U+1F830 RIGHT/LEFTWARDS TRIANGLE\-HEADED ARROW WITH VERY
4520 \& HEAVY SHAFT
4521 \& 🠶 🠴 U+1F836, U+1F834 RIGHT/LEFTWARDS FINGER\-POST ARROW
4522 \& 🠺 🠸 U+1F83A, U+1F838 RIGHT/LEFTWARDS SQUARED ARROW
4523 \& 🠾 🠼 U+1F83E, U+1F83C RIGHT/LEFTWARDS COMPRESSED ARROW
4524 \& 🡂 🡀 U+1F842, U+1F840 RIGHT/LEFTWARDS HEAVY COMPRESSED ARROW
4525 \& 🡆 🡄 U+1F846, U+1F844 RIGHT/LEFTWARDS HEAVY ARROW
4526 \& 🡒 🡐 U+1F852, U+1F850 RIGHT/LEFTWARDS SANS\-SERIF ARROW
4527 \& 🡢 🡠 U+1F862, U+1F860 WIDE\-HEADED RIGHT/LEFTWARDS LIGHT BARB ARROW
4528 \& 🡪 🡨 U+1F86A, U+1F868 WIDE\-HEADED RIGHT/LEFTWARDS BARB ARROW
4529 \& 🡲 🡰 U+1F872, U+1F870 WIDE\-HEADED RIGHT/LEFTWARDS MEDIUM BARB ARROW
4530 \& 🡺 🡸 U+1F87A, U+1F878 WIDE\-HEADED RIGHT/LEFTWARDS HEAVY BARB ARROW
4531 \& 🢂 🢀 U+1F882, U+1F880 WIDE\-HEADED RIGHT/LEFTWARDS VERY HEAVY BARB
4532 \& ARROW
4533 \& 🢒 🢐 U+1F892, U+1F890 RIGHT/LEFTWARDS TRIANGLE ARROWHEAD
4534 \& 🢖 🢔 U+1F896, U+1F894 RIGHT/LEFTWARDS WHITE ARROW WITHIN TRIANGLE
4535 \& ARROWHEAD
4536 \& 🢚 🢘 U+1F89A, U+1F898 RIGHT/LEFTWARDS ARROW WITH NOTCHED TAIL
4537 \& 🢡 🢠 U+1F8A1, U+1F8A0 RIGHTWARDS BOTTOM SHADED WHITE ARROW,
4538 \& LEFTWARDS BOTTOM\-SHADED WHITE ARROW
4539 \& 🢣 🢢 U+1F8A3, U+1F8A2 RIGHT/LEFTWARDS TOP SHADED WHITE ARROW
4540 \& 🢥 🢦 U+1F8A5, U+1F8A6 RIGHT/LEFTWARDS RIGHT\-SHADED WHITE ARROW
4541 \& 🢧 🢤 U+1F8A7, U+1F8A4 RIGHT/LEFTWARDS LEFT\-SHADED WHITE ARROW
4542 \& 🢩 🢨 U+1F8A9, U+1F8A8 RIGHT/LEFTWARDS BACK\-TILTED SHADOWED WHITE ARROW
4543 \& 🢫 🢪 U+1F8AB, U+1F8AA RIGHT/LEFTWARDS FRONT\-TILTED SHADOWED WHITE
4544 \& ARROW
4545 .Ve