Debian Codegraph @

upstream/opensuse-tumbleweed/man1/perlfaq4.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (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 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "PERLFAQ4 1"
61 .TH PERLFAQ4 1 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 perlfaq4 \- Data Manipulation
68 .SH VERSION
69 .IX Header "VERSION"
70 version 5.20250619
71 .SH DESCRIPTION
72 .IX Header "DESCRIPTION"
73 This section of the FAQ answers questions related to manipulating
74 numbers, dates, strings, arrays, hashes, and miscellaneous data issues.
75 .SH "Data: Numbers"
76 .IX Header "Data: Numbers"
77 .SS "Why am I getting long decimals (eg, 19.9499999999999) instead of the numbers I should be getting (eg, 19.95)?"
78 .IX Subsection "Why am I getting long decimals (eg, 19.9499999999999) instead of the numbers I should be getting (eg, 19.95)?"
79 For the long explanation, see David Goldberg\*(Aqs "What Every Computer
80 Scientist Should Know About Floating\-Point Arithmetic"
81 (<http://web.cse.msu.edu/~cse320/Documents/FloatingPoint.pdf>).
82 .PP
83 Internally, your computer represents floating\-point numbers in binary.
84 Digital (as in powers of two) computers cannot store all numbers
85 exactly. Some real numbers lose precision in the process. This is a
86 problem with how computers store numbers and affects all computer
87 languages, not just Perl.
88 .PP
89 perlnumber shows the gory details of number representations and
90 conversions.
91 .PP
92 To limit the number of decimal places in your numbers, you can use the
93 \&\f(CW\*(C`printf\*(C'\fR or \f(CW\*(C`sprintf\*(C'\fR function. See
94 "Floating\-point Arithmetic" in perlop for more details.
95 .PP
96 .Vb 1
97 \& printf "%.2f", 10/3;
98 \&
99 \& my $number = sprintf "%.2f", 10/3;
100 .Ve
101 .SS "Why is \fBint()\fP broken?"
102 .IX Subsection "Why is int() broken?"
103 Your \f(CWint()\fR is most probably working just fine. It\*(Aqs the numbers that
104 aren\*(Aqt quite what you think.
105 .PP
106 First, see the answer to "Why am I getting long decimals
107 (eg, 19.9499999999999) instead of the numbers I should be getting
108 (eg, 19.95)?".
109 .PP
110 For example, this
111 .PP
112 .Vb 1
113 \& print int(0.6/0.2\-2), "\en";
114 .Ve
115 .PP
116 will in most computers print 0, not 1, because even such simple
117 numbers as 0.6 and 0.2 cannot be presented exactly by floating\-point
118 numbers. What you think in the above as \*(Aqthree\*(Aq is really more like
119 2.9999999999999995559.
120 .SS "Why isn\*(Aqt my octal data interpreted correctly?"
121 .IX Subsection "Why isn't my octal data interpreted correctly?"
122 (contributed by brian d foy)
123 .PP
124 You\*(Aqre probably trying to convert a string to a number, which Perl only
125 converts as a decimal number. When Perl converts a string to a number, it
126 ignores leading spaces and zeroes, then assumes the rest of the digits
127 are in base 10:
128 .PP
129 .Vb 1
130 \& my $string = \*(Aq0644\*(Aq;
131 \&
132 \& print $string + 0; # prints 644
133 \&
134 \& print $string + 44; # prints 688, certainly not octal!
135 .Ve
136 .PP
137 This problem usually involves one of the Perl built\-ins that has the
138 same name as a Unix command that uses octal numbers as arguments on the
139 command line. In this example, \f(CW\*(C`chmod\*(C'\fR on the command line knows that
140 its first argument is octal because that\*(Aqs what it does:
141 .PP
142 .Vb 1
143 \& %prompt> chmod 644 file
144 .Ve
145 .PP
146 If you want to use the same literal digits (644) in Perl, you have to tell
147 Perl to treat them as octal numbers either by prefixing the digits with
148 a \f(CW0\fR or using \f(CW\*(C`oct\*(C'\fR:
149 .PP
150 .Vb 2
151 \& chmod( 0644, $filename ); # right, has leading zero
152 \& chmod( oct(644), $filename ); # also correct
153 .Ve
154 .PP
155 The problem comes in when you take your numbers from something that Perl
156 thinks is a string, such as a command line argument in \f(CW@ARGV\fR:
157 .PP
158 .Vb 1
159 \& chmod( $ARGV[0], $filename ); # wrong, even if "0644"
160 \&
161 \& chmod( oct($ARGV[0]), $filename ); # correct, treat string as octal
162 .Ve
163 .PP
164 You can always check the value you\*(Aqre using by printing it in octal
165 notation to ensure it matches what you think it should be. Print it
166 in octal and decimal format:
167 .PP
168 .Vb 1
169 \& printf "0%o %d", $number, $number;
170 .Ve
171 .SS "Does Perl have a \fBround()\fP function? What about \fBceil()\fP and \fBfloor()\fP? Trig functions?"
172 .IX Subsection "Does Perl have a round() function? What about ceil() and floor()? Trig functions?"
173 Remember that \f(CWint()\fR merely truncates toward 0. For rounding to a
174 certain number of digits, \f(CWsprintf()\fR or \f(CWprintf()\fR is usually the
175 easiest route.
176 .PP
177 .Vb 1
178 \& printf("%.3f", 3.1415926535); # prints 3.142
179 .Ve
180 .PP
181 The POSIX module (part of the standard Perl distribution)
182 implements \f(CWceil()\fR, \f(CWfloor()\fR, and a number of other mathematical
183 and trigonometric functions.
184 .PP
185 .Vb 3
186 \& use POSIX;
187 \& my $ceil = ceil(3.5); # 4
188 \& my $floor = floor(3.5); # 3
189 .Ve
190 .PP
191 In 5.000 to 5.003 perls, trigonometry was done in the Math::Complex
192 module. With 5.004, the Math::Trig module (part of the standard Perl
193 distribution) implements the trigonometric functions. Internally it
194 uses the Math::Complex module and some functions can break out from
195 the real axis into the complex plane, for example the inverse sine of
196 2.
197 .PP
198 Rounding in financial applications can have serious implications, and
199 the rounding method used should be specified precisely. In these
200 cases, it probably pays not to trust whichever system of rounding is
201 being used by Perl, but instead to implement the rounding function you
202 need yourself.
203 .PP
204 To see why, notice how you\*(Aqll still have an issue on half\-way\-point
205 alternation:
206 .PP
207 .Vb 1
208 \& for (my $i = \-5; $i <= 5; $i += 0.5) { printf "%.0f ",$i }
209 \&
210 \& \-5 \-4 \-4 \-4 \-3 \-2 \-2 \-2 \-1 \-0 0 0 1 2 2 2 3 4 4 4 5
211 .Ve
212 .PP
213 Don\*(Aqt blame Perl. It\*(Aqs the same as in C. IEEE says we have to do
214 this. Perl numbers whose absolute values are integers under 2**31 (on
215 32\-bit machines) will work pretty much like mathematical integers.
216 Other numbers are not guaranteed.
217 .SS "How do I convert between numeric representations/bases/radixes?"
218 .IX Subsection "How do I convert between numeric representations/bases/radixes?"
219 As always with Perl there is more than one way to do it. Below are a
220 few examples of approaches to making common conversions between number
221 representations. This is intended to be representational rather than
222 exhaustive.
223 .PP
224 Some of the examples later in perlfaq4 use the Bit::Vector
225 module from CPAN. The reason you might choose Bit::Vector over the
226 perl built\-in functions is that it works with numbers of ANY size,
227 that it is optimized for speed on some operations, and for at least
228 some programmers the notation might be familiar.
229 .IP "How do I convert hexadecimal into decimal" 4
230 .IX Item "How do I convert hexadecimal into decimal"
231 Using perl\*(Aqs built in conversion of \f(CW\*(C`0x\*(C'\fR notation:
232 .Sp
233 .Vb 1
234 \& my $dec = 0xDEADBEEF;
235 .Ve
236 .Sp
237 Using the \f(CW\*(C`hex\*(C'\fR function:
238 .Sp
239 .Vb 1
240 \& my $dec = hex("DEADBEEF");
241 .Ve
242 .Sp
243 Using \f(CW\*(C`pack\*(C'\fR:
244 .Sp
245 .Vb 1
246 \& my $dec = unpack("N", pack("H8", substr("0" x 8 . "DEADBEEF", \-8)));
247 .Ve
248 .Sp
249 Using the CPAN module \f(CW\*(C`Bit::Vector\*(C'\fR:
250 .Sp
251 .Vb 3
252 \& use Bit::Vector;
253 \& my $vec = Bit::Vector\->new_Hex(32, "DEADBEEF");
254 \& my $dec = $vec\->to_Dec();
255 .Ve
256 .IP "How do I convert from decimal to hexadecimal" 4
257 .IX Item "How do I convert from decimal to hexadecimal"
258 Using \f(CW\*(C`sprintf\*(C'\fR:
259 .Sp
260 .Vb 2
261 \& my $hex = sprintf("%X", 3735928559); # upper case A\-F
262 \& my $hex = sprintf("%x", 3735928559); # lower case a\-f
263 .Ve
264 .Sp
265 Using \f(CW\*(C`unpack\*(C'\fR:
266 .Sp
267 .Vb 1
268 \& my $hex = unpack("H*", pack("N", 3735928559));
269 .Ve
270 .Sp
271 Using Bit::Vector:
272 .Sp
273 .Vb 3
274 \& use Bit::Vector;
275 \& my $vec = Bit::Vector\->new_Dec(32, \-559038737);
276 \& my $hex = $vec\->to_Hex();
277 .Ve
278 .Sp
279 And Bit::Vector supports odd bit counts:
280 .Sp
281 .Vb 4
282 \& use Bit::Vector;
283 \& my $vec = Bit::Vector\->new_Dec(33, 3735928559);
284 \& $vec\->Resize(32); # suppress leading 0 if unwanted
285 \& my $hex = $vec\->to_Hex();
286 .Ve
287 .IP "How do I convert from octal to decimal" 4
288 .IX Item "How do I convert from octal to decimal"
289 Using Perl\*(Aqs built in conversion of numbers with leading zeros:
290 .Sp
291 .Vb 1
292 \& my $dec = 033653337357; # note the leading 0!
293 .Ve
294 .Sp
295 Using the \f(CW\*(C`oct\*(C'\fR function:
296 .Sp
297 .Vb 1
298 \& my $dec = oct("33653337357");
299 .Ve
300 .Sp
301 Using Bit::Vector:
302 .Sp
303 .Vb 4
304 \& use Bit::Vector;
305 \& my $vec = Bit::Vector\->new(32);
306 \& $vec\->Chunk_List_Store(3, split(//, reverse "33653337357"));
307 \& my $dec = $vec\->to_Dec();
308 .Ve
309 .IP "How do I convert from decimal to octal" 4
310 .IX Item "How do I convert from decimal to octal"
311 Using \f(CW\*(C`sprintf\*(C'\fR:
312 .Sp
313 .Vb 1
314 \& my $oct = sprintf("%o", 3735928559);
315 .Ve
316 .Sp
317 Using Bit::Vector:
318 .Sp
319 .Vb 3
320 \& use Bit::Vector;
321 \& my $vec = Bit::Vector\->new_Dec(32, \-559038737);
322 \& my $oct = reverse join(\*(Aq\*(Aq, $vec\->Chunk_List_Read(3));
323 .Ve
324 .IP "How do I convert from binary to decimal" 4
325 .IX Item "How do I convert from binary to decimal"
326 Perl 5.6 lets you write binary numbers directly with
327 the \f(CW\*(C`0b\*(C'\fR notation:
328 .Sp
329 .Vb 1
330 \& my $number = 0b10110110;
331 .Ve
332 .Sp
333 Using \f(CW\*(C`oct\*(C'\fR:
334 .Sp
335 .Vb 2
336 \& my $input = "10110110";
337 \& my $decimal = oct( "0b$input" );
338 .Ve
339 .Sp
340 Using \f(CW\*(C`pack\*(C'\fR and \f(CW\*(C`ord\*(C'\fR:
341 .Sp
342 .Vb 1
343 \& my $decimal = ord(pack(\*(AqB8\*(Aq, \*(Aq10110110\*(Aq));
344 .Ve
345 .Sp
346 Using \f(CW\*(C`pack\*(C'\fR and \f(CW\*(C`unpack\*(C'\fR for larger strings:
347 .Sp
348 .Vb 3
349 \& my $int = unpack("N", pack("B32",
350 \& substr("0" x 32 . "11110101011011011111011101111", \-32)));
351 \& my $dec = sprintf("%d", $int);
352 \&
353 \& # substr() is used to left\-pad a 32\-character string with zeros.
354 .Ve
355 .Sp
356 Using Bit::Vector:
357 .Sp
358 .Vb 2
359 \& my $vec = Bit::Vector\->new_Bin(32, "11011110101011011011111011101111");
360 \& my $dec = $vec\->to_Dec();
361 .Ve
362 .IP "How do I convert from decimal to binary" 4
363 .IX Item "How do I convert from decimal to binary"
364 Using \f(CW\*(C`sprintf\*(C'\fR (perl 5.6+):
365 .Sp
366 .Vb 1
367 \& my $bin = sprintf("%b", 3735928559);
368 .Ve
369 .Sp
370 Using \f(CW\*(C`unpack\*(C'\fR:
371 .Sp
372 .Vb 1
373 \& my $bin = unpack("B*", pack("N", 3735928559));
374 .Ve
375 .Sp
376 Using Bit::Vector:
377 .Sp
378 .Vb 3
379 \& use Bit::Vector;
380 \& my $vec = Bit::Vector\->new_Dec(32, \-559038737);
381 \& my $bin = $vec\->to_Bin();
382 .Ve
383 .Sp
384 The remaining transformations (e.g. hex \-> oct, bin \-> hex, etc.)
385 are left as an exercise to the inclined reader.
386 .SS "Why doesn\*(Aqt & work the way I want it to?"
387 .IX Subsection "Why doesn't & work the way I want it to?"
388 Perl\*(Aqs \f(CW\*(C`&\*(C'\fR bitwise operator works on both numbers and strings,
389 sometimes producing surprising results when you expected a number
390 but received a string. You probably expected perl to automatically
391 convert the operands to numbers like the mathematical operators would.
392 Instead, perl treats string operands as bitvectors.
393 .PP
394 Consider the bitwise difference between the number 3 and the bitvector
395 represented by "3". A number has the bit pattern for its magnitude. The
396 number 3 is 0b11 (a 2 and a 1). The bitvector has the bit pattern that
397 is the ordinal value for each octet, and that value is unrelated to any
398 numeric value that the digit represents. The character "3" is the
399 bitvector 0b0011_0011.
400 .PP
401 These operations have different results even though you might think they
402 look like the same "number":
403 .PP
404 .Vb 4
405 \& 11 & 3; # 0b0000_1011 & 0b0000_0011
406 \& # \-> 0b0000_0011 (number 3)
407 \& "11" & "3"; # 0b0011_0001_0011_0001 & 0b0011_0011
408 \& # \-> 0b0011_0001 (ASCII char "1")
409 .Ve
410 .PP
411 Note that if any operand has a numeric value, perl uses numeric
412 semantics (although you should not count on this):
413 .PP
414 .Vb 3
415 \& my($i, $j) = ( 11, 3 ); # $i & $j # 11 & 3 \-> 3
416 \& my($i, $j) = ("11", 3 ); # $i & $j # 11 & 3 \-> 3
417 \& my($i, $j) = ("11", "3"); # $i & $j # "11" & "3" \-> 1
418 .Ve
419 .PP
420 Remember that a perl scalar can have both string and numeric values at
421 the same time. A value that starts as a string and has never encountered
422 a numeric operation has no numeric value yet. Perl does this to save
423 time and work so it doesn\*(Aqt have to decide a numeric value for a scalar
424 it might never use as a number. In that case, string semantics wins. But,
425 if there is a numeric value already, numeric semantics win. Force perl
426 to compute the numeric value by adding 0:
427 .PP
428 .Vb 1
429 \& my($i, $j) = ("11", "3"); $j += 0; # $i & $j # "11" & 3 \-> 3
430 .Ve
431 .PP
432 However, this is not a documented feature, or as perlop says, it "is not
433 well defined". One way to ensure numeric semantics is to explicitly
434 convert both of values to numbers:
435 .PP
436 .Vb 1
437 \& (0+$i) & (0+$j)
438 .Ve
439 .PP
440 To fix this annoyance, Perl v5.22 separated the string and number
441 behavior. The \f(CW\*(C`bitwise\*(C'\fR feature introduced four new operators that
442 would work with only string semantics: \f(CW\*(C`&.\*(C'\fR, \f(CW\*(C`|.\*(C'\fR, \f(CW\*(C`^.\*(C'\fR, and \f(CW\*(C`~.\*(C'\fR.
443 The original operators, \f(CW\*(C`&\*(C'\fR, \f(CW\*(C`|\*(C'\fR, \f(CW\*(C`^\*(C'\fR, and \f(CW\*(C`~\*(C'\fR, would then apply
444 only numeric semantics.
445 .PP
446 Enable this feature explicitly with feature:
447 .PP
448 .Vb 1
449 \& use feature qw(bitwise);
450 .Ve
451 .PP
452 Or, as of v5.28, require the minimum version of perl with \f(CW\*(C`use\*(C'\fR:
453 .PP
454 .Vb 1
455 \& use v5.28; # bitwise feature for free
456 .Ve
457 .SS "How do I multiply matrices?"
458 .IX Subsection "How do I multiply matrices?"
459 Use the Math::Matrix or Math::MatrixReal modules (available from CPAN)
460 or the PDL extension (also available from CPAN).
461 .SS "How do I perform an operation on a series of integers?"
462 .IX Subsection "How do I perform an operation on a series of integers?"
463 To call a function on each element in an array, and collect the
464 results, use:
465 .PP
466 .Vb 1
467 \& my @results = map { my_func($_) } @array;
468 .Ve
469 .PP
470 For example:
471 .PP
472 .Vb 1
473 \& my @triple = map { 3 * $_ } @single;
474 .Ve
475 .PP
476 To call a function on each element of an array, but ignore the
477 results:
478 .PP
479 .Vb 3
480 \& foreach my $iterator (@array) {
481 \& some_func($iterator);
482 \& }
483 .Ve
484 .PP
485 To call a function on each integer in a (small) range, you \fBcan\fR use:
486 .PP
487 .Vb 1
488 \& my @results = map { some_func($_) } (5 .. 25);
489 .Ve
490 .PP
491 but you should be aware that in this form, the \f(CW\*(C`..\*(C'\fR operator
492 creates a list of all integers in the range, which can take a lot of
493 memory for large ranges. However, the problem does not occur when
494 using \f(CW\*(C`..\*(C'\fR within a \f(CW\*(C`for\*(C'\fR loop, because in that case the range
495 operator is optimized to \fIiterate\fR over the range, without creating
496 the entire list. So
497 .PP
498 .Vb 4
499 \& my @results = ();
500 \& for my $i (5 .. 500_005) {
501 \& push(@results, some_func($i));
502 \& }
503 .Ve
504 .PP
505 or even
506 .PP
507 .Vb 1
508 \& push(@results, some_func($_)) for 5 .. 500_005;
509 .Ve
510 .PP
511 will not create an intermediate list of 500,000 integers.
512 .SS "How can I output Roman numerals?"
513 .IX Subsection "How can I output Roman numerals?"
514 Get the <http://www.cpan.org/modules/by\-module/Roman> module.
515 .SS "Why aren\*(Aqt my random numbers random?"
516 .IX Subsection "Why aren't my random numbers random?"
517 If you\*(Aqre using a version of Perl before 5.004, you must call \f(CW\*(C`srand\*(C'\fR
518 once at the start of your program to seed the random number generator.
519 .PP
520 .Vb 1
521 \& BEGIN { srand() if $] < 5.004 }
522 .Ve
523 .PP
524 5.004 and later automatically call \f(CW\*(C`srand\*(C'\fR at the beginning. Don\*(Aqt
525 call \f(CW\*(C`srand\*(C'\fR more than once\-\-you make your numbers less random,
526 rather than more.
527 .PP
528 Computers are good at being predictable and bad at being random
529 (despite appearances caused by bugs in your programs :\-). The
530 \&\fIrandom\fR article in the "Far More Than You Ever Wanted To Know"
531 collection in <http://www.cpan.org/misc/olddoc/FMTEYEWTK.tgz>, courtesy
532 of Tom Phoenix, talks more about this. John von Neumann said, "Anyone
533 who attempts to generate random numbers by deterministic means is, of
534 course, living in a state of sin."
535 .PP
536 Perl relies on the underlying system for the implementation of
537 \&\f(CW\*(C`rand\*(C'\fR and \f(CW\*(C`srand\*(C'\fR; on some systems, the generated numbers are
538 not random enough (especially on Windows: see
539 <http://www.perlmonks.org/?node_id=803632>).
540 Several CPAN modules in the \f(CW\*(C`Math\*(C'\fR namespace implement better
541 pseudorandom generators; see for example
542 Math::Random::MT ("Mersenne Twister", fast).
543 More algorithms for random numbers are described in
544 "Numerical Recipes in C" at <http://www.nr.com/>
545 .PP
546 There are several modules to sample system sources of random numbers,
547 which are useful for security tokens and cryptography. For example,
548 Crypt::URandom.
549 See the "CPAN Author\*(Aqs Guide to Random Data for Security" at
550 <https://security.metacpan.org/docs/guides/random\-data\-for\-security.html>
551 .SS "How do I get a random number between X and Y?"
552 .IX Subsection "How do I get a random number between X and Y?"
553 To get a random number between two values, you can use the \f(CWrand()\fR
554 built\-in to get a random number between 0 and 1. From there, you shift
555 that into the range that you want.
556 .PP
557 \&\f(CWrand($x)\fR returns a number such that \f(CW\*(C`0 <= rand($x) < $x\*(C'\fR. Thus
558 what you want to have perl figure out is a random number in the range
559 from 0 to the difference between your \fIX\fR and \fIY\fR.
560 .PP
561 That is, to get a number between 10 and 15, inclusive, you want a
562 random number between 0 and 5 that you can then add to 10.
563 .PP
564 .Vb 1
565 \& my $number = 10 + int rand( 15\-10+1 ); # ( 10,11,12,13,14, or 15 )
566 .Ve
567 .PP
568 Hence you derive the following simple function to abstract
569 that. It selects a random integer between the two given
570 integers (inclusive). For example: \f(CW\*(C`random_int_between(50,120)\*(C'\fR.
571 .PP
572 .Vb 7
573 \& sub random_int_between {
574 \& my($min, $max) = @_;
575 \& # Assumes that the two arguments are integers themselves!
576 \& return $min if $min == $max;
577 \& ($min, $max) = ($max, $min) if $min > $max;
578 \& return $min + int rand(1 + $max \- $min);
579 \& }
580 .Ve
581 .SH "Data: Dates"
582 .IX Header "Data: Dates"
583 .SS "How do I find the day or week of the year?"
584 .IX Subsection "How do I find the day or week of the year?"
585 The day of the year is in the list returned
586 by the \f(CW\*(C`localtime\*(C'\fR function. Without an
587 argument \f(CW\*(C`localtime\*(C'\fR uses the current time.
588 .PP
589 .Vb 1
590 \& my $day_of_year = (localtime)[7];
591 .Ve
592 .PP
593 The POSIX module can also format a date as the day of the year or
594 week of the year.
595 .PP
596 .Vb 3
597 \& use POSIX qw/strftime/;
598 \& my $day_of_year = strftime "%j", localtime;
599 \& my $week_of_year = strftime "%W", localtime;
600 .Ve
601 .PP
602 To get the day of year for any date, use POSIX\*(Aqs \f(CW\*(C`mktime\*(C'\fR to get
603 a time in epoch seconds for the argument to \f(CW\*(C`localtime\*(C'\fR.
604 .PP
605 .Vb 3
606 \& use POSIX qw/mktime strftime/;
607 \& my $day_of_year = strftime "%j",
608 \& localtime( mktime( 0, 0, 0, 18, 11, 87 ) );
609 .Ve
610 .PP
611 You can also use Time::Piece, which comes with Perl and provides a
612 \&\f(CW\*(C`localtime\*(C'\fR that returns an object:
613 .PP
614 .Vb 3
615 \& use Time::Piece;
616 \& my $day_of_year = localtime\->yday;
617 \& my $week_of_year = localtime\->week;
618 .Ve
619 .PP
620 The Date::Calc module provides two functions to calculate these, too:
621 .PP
622 .Vb 3
623 \& use Date::Calc;
624 \& my $day_of_year = Day_of_Year( 1987, 12, 18 );
625 \& my $week_of_year = Week_of_Year( 1987, 12, 18 );
626 .Ve
627 .SS "How do I find the current century or millennium?"
628 .IX Subsection "How do I find the current century or millennium?"
629 Use the following simple functions:
630 .PP
631 .Vb 3
632 \& sub get_century {
633 \& return int((((localtime(shift || time))[5] + 1999))/100);
634 \& }
635 \&
636 \& sub get_millennium {
637 \& return 1+int((((localtime(shift || time))[5] + 1899))/1000);
638 \& }
639 .Ve
640 .PP
641 On some systems, the POSIX module\*(Aqs \f(CWstrftime()\fR function has been
642 extended in a non\-standard way to use a \f(CW%C\fR format, which they
643 sometimes claim is the "century". It isn\*(Aqt, because on most such
644 systems, this is only the first two digits of the four\-digit year, and
645 thus cannot be used to determine reliably the current century or
646 millennium.
647 .SS "How can I compare two dates and find the difference?"
648 .IX Subsection "How can I compare two dates and find the difference?"
649 (contributed by brian d foy)
650 .PP
651 You could just store all your dates as a number and then subtract.
652 Life isn\*(Aqt always that simple though.
653 .PP
654 The Time::Piece module, which comes with Perl, replaces \f(CW\*(C`localtime\*(C'\fR
655 with a version that returns an object. It also overloads the comparison
656 operators so you can compare them directly:
657 .PP
658 .Vb 3
659 \& use Time::Piece;
660 \& my $date1 = localtime( $some_time );
661 \& my $date2 = localtime( $some_other_time );
662 \&
663 \& if( $date1 < $date2 ) {
664 \& print "The date was in the past\en";
665 \& }
666 .Ve
667 .PP
668 You can also get differences with a subtraction, which returns a
669 Time::Seconds object:
670 .PP
671 .Vb 2
672 \& my $date_diff = $date1 \- $date2;
673 \& print "The difference is ", $date_diff\->days, " days\en";
674 .Ve
675 .PP
676 If you want to work with formatted dates, the Date::Manip,
677 Date::Calc, or DateTime modules can help you.
678 .SS "How can I take a string and turn it into epoch seconds?"
679 .IX Subsection "How can I take a string and turn it into epoch seconds?"
680 If it\*(Aqs a regular enough string that it always has the same format,
681 you can split it up and pass the parts to \f(CW\*(C`timelocal\*(C'\fR in the standard
682 Time::Local module. Otherwise, you should look into the Date::Calc,
683 Date::Parse, and Date::Manip modules from CPAN.
684 .SS "How can I find the Julian Day?"
685 .IX Subsection "How can I find the Julian Day?"
686 (contributed by brian d foy and Dave Cross)
687 .PP
688 You can use the Time::Piece module, part of the Standard Library,
689 which can convert a date/time to a Julian Day:
690 .PP
691 .Vb 2
692 \& $ perl \-MTime::Piece \-le \*(Aqprint localtime\->julian_day\*(Aq
693 \& 2455607.7959375
694 .Ve
695 .PP
696 Or the modified Julian Day:
697 .PP
698 .Vb 2
699 \& $ perl \-MTime::Piece \-le \*(Aqprint localtime\->mjd\*(Aq
700 \& 55607.2961226851
701 .Ve
702 .PP
703 Or even the day of the year (which is what some people think of as a
704 Julian day):
705 .PP
706 .Vb 2
707 \& $ perl \-MTime::Piece \-le \*(Aqprint localtime\->yday\*(Aq
708 \& 45
709 .Ve
710 .PP
711 You can also do the same things with the DateTime module:
712 .PP
713 .Vb 6
714 \& $ perl \-MDateTime \-le\*(Aqprint DateTime\->today\->jd\*(Aq
715 \& 2453401.5
716 \& $ perl \-MDateTime \-le\*(Aqprint DateTime\->today\->mjd\*(Aq
717 \& 53401
718 \& $ perl \-MDateTime \-le\*(Aqprint DateTime\->today\->doy\*(Aq
719 \& 31
720 .Ve
721 .PP
722 You can use the Time::JulianDay module available on CPAN. Ensure
723 that you really want to find a Julian day, though, as many people have
724 different ideas about Julian days (see <http://www.hermetic.ch/cal_stud/jdn.htm>
725 for instance):
726 .PP
727 .Vb 2
728 \& $ perl \-MTime::JulianDay \-le \*(Aqprint local_julian_day( time )\*(Aq
729 \& 55608
730 .Ve
731 .SS "How do I find yesterday\*(Aqs date?"
732 .IX Xref "date yesterday DateTime Date::Calc Time::Local daylight saving time day Today_and_Now localtime timelocal"
733 .IX Subsection "How do I find yesterday's date?"
734 (contributed by brian d foy)
735 .PP
736 To do it correctly, you can use one of the \f(CW\*(C`Date\*(C'\fR modules since they
737 work with calendars instead of times. The DateTime module makes it
738 simple, and gives you the same time of day, only the day before,
739 despite daylight saving time changes:
740 .PP
741 .Vb 1
742 \& use DateTime;
743 \&
744 \& my $yesterday = DateTime\->now\->subtract( days => 1 );
745 \&
746 \& print "Yesterday was $yesterday\en";
747 .Ve
748 .PP
749 You can also use the Date::Calc module using its \f(CW\*(C`Today_and_Now\*(C'\fR
750 function.
751 .PP
752 .Vb 1
753 \& use Date::Calc qw( Today_and_Now Add_Delta_DHMS );
754 \&
755 \& my @date_time = Add_Delta_DHMS( Today_and_Now(), \-1, 0, 0, 0 );
756 \&
757 \& print "@date_time\en";
758 .Ve
759 .PP
760 Most people try to use the time rather than the calendar to figure out
761 dates, but that assumes that days are twenty\-four hours each. For
762 most people, there are two days a year when they aren\*(Aqt: the switch to
763 and from summer time throws this off. For example, the rest of the
764 suggestions will be wrong sometimes:
765 .PP
766 Starting with Perl 5.10, Time::Piece and Time::Seconds are part
767 of the standard distribution, so you might think that you could do
768 something like this:
769 .PP
770 .Vb 2
771 \& use Time::Piece;
772 \& use Time::Seconds;
773 \&
774 \& my $yesterday = localtime() \- ONE_DAY; # WRONG
775 \& print "Yesterday was $yesterday\en";
776 .Ve
777 .PP
778 The Time::Piece module exports a new \f(CW\*(C`localtime\*(C'\fR that returns an
779 object, and Time::Seconds exports the \f(CW\*(C`ONE_DAY\*(C'\fR constant that is a
780 set number of seconds. This means that it always gives the time 24
781 hours ago, which is not always yesterday. This can cause problems
782 around the end of daylight saving time when there\*(Aqs one day that is 25
783 hours long.
784 .PP
785 You have the same problem with Time::Local, which will give the wrong
786 answer for those same special cases:
787 .PP
788 .Vb 5
789 \& # contributed by Gunnar Hjalmarsson
790 \& use Time::Local;
791 \& my $today = timelocal 0, 0, 12, ( localtime )[3..5];
792 \& my ($d, $m, $y) = ( localtime $today\-86400 )[3..5]; # WRONG
793 \& printf "Yesterday: %d\-%02d\-%02d\en", $y+1900, $m+1, $d;
794 .Ve
795 .SS "Does Perl have a Year 2000 or 2038 problem? Is Perl Y2K compliant?"
796 .IX Subsection "Does Perl have a Year 2000 or 2038 problem? Is Perl Y2K compliant?"
797 (contributed by brian d foy)
798 .PP
799 Perl itself never had a Y2K problem, although that never stopped people
800 from creating Y2K problems on their own. See the documentation for
801 \&\f(CW\*(C`localtime\*(C'\fR for its proper use.
802 .PP
803 Starting with Perl 5.12, \f(CW\*(C`localtime\*(C'\fR and \f(CW\*(C`gmtime\*(C'\fR can handle dates past
804 03:14:08 January 19, 2038, when a 32\-bit based time would overflow. You
805 still might get a warning on a 32\-bit \f(CW\*(C`perl\*(C'\fR:
806 .PP
807 .Vb 3
808 \& % perl5.12 \-E \*(Aqsay scalar localtime( 0x9FFF_FFFFFFFF )\*(Aq
809 \& Integer overflow in hexadecimal number at \-e line 1.
810 \& Wed Nov 1 19:42:39 5576711
811 .Ve
812 .PP
813 On a 64\-bit \f(CW\*(C`perl\*(C'\fR, you can get even larger dates for those really long
814 running projects:
815 .PP
816 .Vb 2
817 \& % perl5.12 \-E \*(Aqsay scalar gmtime( 0x9FFF_FFFFFFFF )\*(Aq
818 \& Thu Nov 2 00:42:39 5576711
819 .Ve
820 .PP
821 You\*(Aqre still out of luck if you need to keep track of decaying protons
822 though.
823 .SH "Data: Strings"
824 .IX Header "Data: Strings"
825 .SS "How do I validate input?"
826 .IX Subsection "How do I validate input?"
827 (contributed by brian d foy)
828 .PP
829 There are many ways to ensure that values are what you expect or
830 want to accept. Besides the specific examples that we cover in the
831 perlfaq, you can also look at the modules with "Assert" and "Validate"
832 in their names, along with other modules such as Regexp::Common.
833 .PP
834 Some modules have validation for particular types of input, such
835 as Business::ISBN, Business::CreditCard, Email::Valid,
836 and Data::Validate::IP.
837 .SS "How do I unescape a string?"
838 .IX Subsection "How do I unescape a string?"
839 It depends just what you mean by "escape". URL escapes are dealt
840 with in perlfaq9. Shell escapes with the backslash (\f(CW\*(C`\e\*(C'\fR)
841 character are removed with
842 .PP
843 .Vb 1
844 \& s/\e\e(.)/$1/g;
845 .Ve
846 .PP
847 This won\*(Aqt expand \f(CW"\en"\fR or \f(CW"\et"\fR or any other special escapes.
848 .SS "How do I remove consecutive pairs of characters?"
849 .IX Subsection "How do I remove consecutive pairs of characters?"
850 (contributed by brian d foy)
851 .PP
852 You can use the substitution operator to find pairs of characters (or
853 runs of characters) and replace them with a single instance. In this
854 substitution, we find a character in \f(CW\*(C`(.)\*(C'\fR. The memory parentheses
855 store the matched character in the back\-reference \f(CW\*(C`\eg1\*(C'\fR and we use
856 that to require that the same thing immediately follow it. We replace
857 that part of the string with the character in \f(CW$1\fR.
858 .PP
859 .Vb 1
860 \& s/(.)\eg1/$1/g;
861 .Ve
862 .PP
863 We can also use the transliteration operator, \f(CW\*(C`tr///\*(C'\fR. In this
864 example, the search list side of our \f(CW\*(C`tr///\*(C'\fR contains nothing, but
865 the \f(CW\*(C`c\*(C'\fR option complements that so it contains everything. The
866 replacement list also contains nothing, so the transliteration is
867 almost a no\-op since it won\*(Aqt do any replacements (or more exactly,
868 replace the character with itself). However, the \f(CW\*(C`s\*(C'\fR option squashes
869 duplicated and consecutive characters in the string so a character
870 does not show up next to itself
871 .PP
872 .Vb 2
873 \& my $str = \*(AqHaarlem\*(Aq; # in the Netherlands
874 \& $str =~ tr///cs; # Now Harlem, like in New York
875 .Ve
876 .SS "How do I expand function calls in a string?"
877 .IX Subsection "How do I expand function calls in a string?"
878 (contributed by brian d foy)
879 .PP
880 This is documented in perlref, and although it\*(Aqs not the easiest
881 thing to read, it does work. In each of these examples, we call the
882 function inside the braces used to dereference a reference. If we
883 have more than one return value, we can construct and dereference an
884 anonymous array. In this case, we call the function in list context.
885 .PP
886 .Vb 1
887 \& print "The time values are @{ [localtime] }.\en";
888 .Ve
889 .PP
890 If we want to call the function in scalar context, we have to do a bit
891 more work. We can really have any code we like inside the braces, so
892 we simply have to end with the scalar reference, although how you do
893 that is up to you, and you can use code inside the braces. Note that
894 the use of parens creates a list context, so we need \f(CW\*(C`scalar\*(C'\fR to
895 force the scalar context on the function:
896 .PP
897 .Vb 1
898 \& print "The time is ${\e(scalar localtime)}.\en"
899 \&
900 \& print "The time is ${ my $x = localtime; \e$x }.\en";
901 .Ve
902 .PP
903 If your function already returns a reference, you don\*(Aqt need to create
904 the reference yourself.
905 .PP
906 .Vb 1
907 \& sub timestamp { my $t = localtime; \e$t }
908 \&
909 \& print "The time is ${ timestamp() }.\en";
910 .Ve
911 .PP
912 The \f(CW\*(C`Interpolation\*(C'\fR module can also do a lot of magic for you. You can
913 specify a variable name, in this case \f(CW\*(C`E\*(C'\fR, to set up a tied hash that
914 does the interpolation for you. It has several other methods to do this
915 as well.
916 .PP
917 .Vb 2
918 \& use Interpolation E => \*(Aqeval\*(Aq;
919 \& print "The time values are $E{localtime()}.\en";
920 .Ve
921 .PP
922 In most cases, it is probably easier to simply use string concatenation,
923 which also forces scalar context.
924 .PP
925 .Vb 1
926 \& print "The time is " . localtime() . ".\en";
927 .Ve
928 .SS "How do I find matching/nesting anything?"
929 .IX Subsection "How do I find matching/nesting anything?"
930 To find something between two single
931 characters, a pattern like \f(CW\*(C`/x([^x]*)x/\*(C'\fR will get the intervening
932 bits in \f(CW$1\fR. For multiple ones, then something more like
933 \&\f(CW\*(C`/alpha(.*?)omega/\*(C'\fR would be needed. For nested patterns
934 and/or balanced expressions, see the so\-called
935 (?PARNO)
936 construct (available since perl 5.10).
937 The CPAN module Regexp::Common can help to build such
938 regular expressions (see in particular
939 Regexp::Common::balanced and Regexp::Common::delimited).
940 .PP
941 More complex cases will require to write a parser, probably
942 using a parsing module from CPAN, like
943 Regexp::Grammars, Parse::RecDescent, Parse::Yapp,
944 Text::Balanced, or Marpa::R2.
945 .SS "How do I reverse a string?"
946 .IX Subsection "How do I reverse a string?"
947 Use \f(CWreverse()\fR in scalar context, as documented in
948 "reverse" in perlfunc.
949 .PP
950 .Vb 1
951 \& my $reversed = reverse $string;
952 .Ve
953 .SS "How do I expand tabs in a string?"
954 .IX Subsection "How do I expand tabs in a string?"
955 You can do it yourself:
956 .PP
957 .Vb 1
958 \& 1 while $string =~ s/\et+/\*(Aq \*(Aq x (length($&) * 8 \- length($\`) % 8)/e;
959 .Ve
960 .PP
961 Or you can just use the Text::Tabs module (part of the standard Perl
962 distribution).
963 .PP
964 .Vb 2
965 \& use Text::Tabs;
966 \& my @expanded_lines = expand(@lines_with_tabs);
967 .Ve
968 .SS "How do I reformat a paragraph?"
969 .IX Subsection "How do I reformat a paragraph?"
970 Use Text::Wrap (part of the standard Perl distribution):
971 .PP
972 .Vb 2
973 \& use Text::Wrap;
974 \& print wrap("\et", \*(Aq \*(Aq, @paragraphs);
975 .Ve
976 .PP
977 The paragraphs you give to Text::Wrap should not contain embedded
978 newlines. Text::Wrap doesn\*(Aqt justify the lines (flush\-right).
979 .PP
980 Or use the CPAN module Text::Autoformat. Formatting files can be
981 easily done by making a shell alias, like so:
982 .PP
983 .Vb 2
984 \& alias fmt="perl \-i \-MText::Autoformat \-n0777 \e
985 \& \-e \*(Aqprint autoformat $_, {all=>1}\*(Aq $*"
986 .Ve
987 .PP
988 See the documentation for Text::Autoformat to appreciate its many
989 capabilities.
990 .SS "How can I access or change N characters of a string?"
991 .IX Subsection "How can I access or change N characters of a string?"
992 You can access the first characters of a string with \fBsubstr()\fR.
993 To get the first character, for example, start at position 0
994 and grab the string of length 1.
995 .PP
996 .Vb 2
997 \& my $string = "Just another Perl Hacker";
998 \& my $first_char = substr( $string, 0, 1 ); # \*(AqJ\*(Aq
999 .Ve
1000 .PP
1001 To change part of a string, you can use the optional fourth
1002 argument which is the replacement string.
1003 .PP
1004 .Vb 1
1005 \& substr( $string, 13, 4, "Perl 5.8.0" );
1006 .Ve
1007 .PP
1008 You can also use \fBsubstr()\fR as an lvalue.
1009 .PP
1010 .Vb 1
1011 \& substr( $string, 13, 4 ) = "Perl 5.8.0";
1012 .Ve
1013 .SS "How do I change the Nth occurrence of something?"
1014 .IX Subsection "How do I change the Nth occurrence of something?"
1015 You have to keep track of N yourself. For example, let\*(Aqs say you want
1016 to change the fifth occurrence of \f(CW"whoever"\fR or \f(CW"whomever"\fR into
1017 \&\f(CW"whosoever"\fR or \f(CW"whomsoever"\fR, case insensitively. These
1018 all assume that \f(CW$_\fR contains the string to be altered.
1019 .PP
1020 .Vb 6
1021 \& $count = 0;
1022 \& s{((whom?)ever)}{
1023 \& ++$count == 5 # is it the 5th?
1024 \& ? "${2}soever" # yes, swap
1025 \& : $1 # renege and leave it there
1026 \& }ige;
1027 .Ve
1028 .PP
1029 In the more general case, you can use the \f(CW\*(C`/g\*(C'\fR modifier in a \f(CW\*(C`while\*(C'\fR
1030 loop, keeping count of matches.
1031 .PP
1032 .Vb 8
1033 \& $WANT = 3;
1034 \& $count = 0;
1035 \& $_ = "One fish two fish red fish blue fish";
1036 \& while (/(\ew+)\es+fish\eb/gi) {
1037 \& if (++$count == $WANT) {
1038 \& print "The third fish is a $1 one.\en";
1039 \& }
1040 \& }
1041 .Ve
1042 .PP
1043 That prints out: \f(CW"The third fish is a red one."\fR You can also use a
1044 repetition count and repeated pattern like this:
1045 .PP
1046 .Vb 1
1047 \& /(?:\ew+\es+fish\es+){2}(\ew+)\es+fish/i;
1048 .Ve
1049 .SS "How can I count the number of occurrences of a substring within a string?"
1050 .IX Subsection "How can I count the number of occurrences of a substring within a string?"
1051 There are a number of ways, with varying efficiency. If you want a
1052 count of a certain single character (X) within a string, you can use the
1053 \&\f(CW\*(C`tr///\*(C'\fR function like so:
1054 .PP
1055 .Vb 3
1056 \& my $string = "ThisXlineXhasXsomeXx\*(AqsXinXit";
1057 \& my $count = ($string =~ tr/X//);
1058 \& print "There are $count X characters in the string";
1059 .Ve
1060 .PP
1061 This is fine if you are just looking for a single character. However,
1062 if you are trying to count multiple character substrings within a
1063 larger string, \f(CW\*(C`tr///\*(C'\fR won\*(Aqt work. What you can do is wrap a \fBwhile()\fR
1064 loop around a global pattern match. For example, let\*(Aqs count negative
1065 integers:
1066 .PP
1067 .Vb 4
1068 \& my $string = "\-9 55 48 \-2 23 \-76 4 14 \-44";
1069 \& my $count = 0;
1070 \& while ($string =~ /\-\ed+/g) { $count++ }
1071 \& print "There are $count negative numbers in the string";
1072 .Ve
1073 .PP
1074 Another version uses a global match in list context, then assigns the
1075 result to a scalar, producing a count of the number of matches.
1076 .PP
1077 .Vb 1
1078 \& my $count = () = $string =~ /\-\ed+/g;
1079 .Ve
1080 .SS "How do I capitalize all the words on one line?"
1081 .IX Xref "Text::Autoformat capitalize case, title case, sentence"
1082 .IX Subsection "How do I capitalize all the words on one line?"
1083 (contributed by brian d foy)
1084 .PP
1085 Damian Conway\*(Aqs Text::Autoformat handles all of the thinking
1086 for you:
1087 .PP
1088 .Vb 2
1089 \& use Text::Autoformat;
1090 \& my $s = "Going to the desert with a camel";
1091 \&
1092 \& printf "%\-10s %s\en", "original:", $s;
1093 \& for my $style (qw( sentence title highlight )) {
1094 \& printf "%\-10s %s\en",
1095 \& "$style:",
1096 \& autoformat($s, { case => $style }) =~ s/\eR+\ez//r;
1097 \& }
1098 .Ve
1099 .PP
1100 Each style has a different idea of what it should do with small words:
1101 .PP
1102 .Vb 4
1103 \& original: Going to the desert with a camel
1104 \& sentence: Going to the desert with a camel
1105 \& title: Going To The Desert With A Camel
1106 \& highlight: Going to the Desert with a Camel
1107 .Ve
1108 .PP
1109 Trying this yourself in a simple regex has more than a few pitfalls.
1110 Perl "words" are groups of \f(CW\*(C`\ew+\*(C'\fR, but that\*(Aqs not what you want to
1111 capitalize. Some of those characters aren\*(Aqt even letters. What if you
1112 used a word boundary, \f(CW\*(C`\eb\*(C'\fR?
1113 .PP
1114 .Vb 2
1115 \& my $string = "A camel\*(Aqs journey";
1116 \& $string =~ s/\eb(\ew)/\eU$1/g; # A Camel\*(AqS Journey
1117 .Ve
1118 .PP
1119 How is Perl supposed to know not to capitalize that \f(CW\*(C`s\*(C'\fR? You could work
1120 harder to look for preceding whitespace or the beginning of the string:
1121 .PP
1122 .Vb 1
1123 \& $string =~ s/( (?:^|\es) \ew ) /\eU$1/xg; # A Camel\*(Aqs Journey
1124 .Ve
1125 .PP
1126 Or maybe you match the entire group, lowercase it all (\f(CW\*(C`L\*(C'\fR), then
1127 uppercase the first letter (\f(CW\*(C`\eu\*(C'\fR):
1128 .PP
1129 .Vb 1
1130 \& $string =~ s/([\ew\*(Aq]+)/\eu\eL$1/g;
1131 .Ve
1132 .PP
1133 Each of these have their annoying edge cases. Perl v5.22 added fancier
1134 Unicode word and sentence boundaries to fix this sort of problem. The
1135 \&\f(CW\*(C`\eb{wb}\*(C'\fR word boundary ignores some things that it doesn\*(Aqt think start
1136 or end "human" words:
1137 .PP
1138 .Vb 3
1139 \& use v5.22;
1140 \& my $string = "A camel\*(Aqs journey";
1141 \& $string =~ s/\eb{wb}(\ew)/\eU$1/g; # A Camel\*(Aqs Journey
1142 .Ve
1143 .PP
1144 The details are in Unicode Technical Report #29
1145 (<https://unicode.org/reports/tr29/>), and you should make sure that
1146 its idea of a word boundary corresponds to yours.
1147 .PP
1148 Now, what if you don\*(Aqt want to capitalize that "and" or "the"? Just use
1149 Text::Autoformat and get on with the next problem. :)
1150 .SS "How can I split a [character]\-delimited string except when inside [character]?"
1151 .IX Subsection "How can I split a [character]-delimited string except when inside [character]?"
1152 Several modules can handle this sort of parsing\-\-Text::Balanced,
1153 Text::CSV, Text::CSV_XS, and Text::ParseWords, among others.
1154 .PP
1155 Take the example case of trying to split a string that is
1156 comma\-separated into its different fields. You can\*(Aqt use \f(CW\*(C`split(/,/)\*(C'\fR
1157 because you shouldn\*(Aqt split if the comma is inside quotes. For
1158 example, take a data line like this:
1159 .PP
1160 .Vb 1
1161 \& SAR001,"","Cimetrix, Inc","Bob Smith","CAM",N,8,1,0,7,"Error, Core Dumped"
1162 .Ve
1163 .PP
1164 Due to the restriction of the quotes, this is a fairly complex
1165 problem. Thankfully, we have Jeffrey Friedl, author of
1166 \&\fIMastering Regular Expressions\fR, to handle these for us. He
1167 suggests (assuming your string is contained in \f(CW$text\fR):
1168 .PP
1169 .Vb 7
1170 \& my @new = ();
1171 \& push(@new, $+) while $text =~ m{
1172 \& "([^\e"\e\e]*(?:\e\e.[^\e"\e\e]*)*)",? # groups the phrase inside the quotes
1173 \& | ([^,]+),?
1174 \& | ,
1175 \& }gx;
1176 \& push(@new, undef) if substr($text,\-1,1) eq \*(Aq,\*(Aq;
1177 .Ve
1178 .PP
1179 If you want to represent quotation marks inside a
1180 quotation\-mark\-delimited field, escape them with backslashes (eg,
1181 \&\f(CW"like \e"this\e""\fR.
1182 .PP
1183 Alternatively, the Text::ParseWords module (part of the standard
1184 Perl distribution) lets you say:
1185 .PP
1186 .Vb 2
1187 \& use Text::ParseWords;
1188 \& @new = quotewords(",", 0, $text);
1189 .Ve
1190 .PP
1191 For parsing or generating CSV, though, using Text::CSV rather than
1192 implementing it yourself is highly recommended; you\*(Aqll save yourself odd bugs
1193 popping up later by just using code which has already been tried and tested in
1194 production for years.
1195 .SS "How do I strip blank space from the beginning/end of a string?"
1196 .IX Subsection "How do I strip blank space from the beginning/end of a string?"
1197 (contributed by brian d foy)
1198 .PP
1199 A substitution can do this for you. For a single line, you want to
1200 replace all the leading or trailing whitespace with nothing. You
1201 can do that with a pair of substitutions:
1202 .PP
1203 .Vb 2
1204 \& s/^\es+//;
1205 \& s/\es+$//;
1206 .Ve
1207 .PP
1208 You can also write that as a single substitution, although it turns
1209 out the combined statement is slower than the separate ones. That
1210 might not matter to you, though:
1211 .PP
1212 .Vb 1
1213 \& s/^\es+|\es+$//g;
1214 .Ve
1215 .PP
1216 In this regular expression, the alternation matches either at the
1217 beginning or the end of the string since the anchors have a lower
1218 precedence than the alternation. With the \f(CW\*(C`/g\*(C'\fR flag, the substitution
1219 makes all possible matches, so it gets both. Remember, the trailing
1220 newline matches the \f(CW\*(C`\es+\*(C'\fR, and the \f(CW\*(C`$\*(C'\fR anchor can match to the
1221 absolute end of the string, so the newline disappears too. Just add
1222 the newline to the output, which has the added benefit of preserving
1223 "blank" (consisting entirely of whitespace) lines which the \f(CW\*(C`^\es+\*(C'\fR
1224 would remove all by itself:
1225 .PP
1226 .Vb 4
1227 \& while( <> ) {
1228 \& s/^\es+|\es+$//g;
1229 \& print "$_\en";
1230 \& }
1231 .Ve
1232 .PP
1233 For a multi\-line string, you can apply the regular expression to each
1234 logical line in the string by adding the \f(CW\*(C`/m\*(C'\fR flag (for
1235 "multi\-line"). With the \f(CW\*(C`/m\*(C'\fR flag, the \f(CW\*(C`$\*(C'\fR matches \fIbefore\fR an
1236 embedded newline, so it doesn\*(Aqt remove it. This pattern still removes
1237 the newline at the end of the string:
1238 .PP
1239 .Vb 1
1240 \& $string =~ s/^\es+|\es+$//gm;
1241 .Ve
1242 .PP
1243 Remember that lines consisting entirely of whitespace will disappear,
1244 since the first part of the alternation can match the entire string
1245 and replace it with nothing. If you need to keep embedded blank lines,
1246 you have to do a little more work. Instead of matching any whitespace
1247 (since that includes a newline), just match the other whitespace:
1248 .PP
1249 .Vb 1
1250 \& $string =~ s/^[\et\ef ]+|[\et\ef ]+$//mg;
1251 .Ve
1252 .SS "How do I pad a string with blanks or pad a number with zeroes?"
1253 .IX Subsection "How do I pad a string with blanks or pad a number with zeroes?"
1254 In the following examples, \f(CW$pad_len\fR is the length to which you wish
1255 to pad the string, \f(CW$text\fR or \f(CW$num\fR contains the string to be padded,
1256 and \f(CW$pad_char\fR contains the padding character. You can use a single
1257 character string constant instead of the \f(CW$pad_char\fR variable if you
1258 know what it is in advance. And in the same way you can use an integer in
1259 place of \f(CW$pad_len\fR if you know the pad length in advance.
1260 .PP
1261 The simplest method uses the \f(CW\*(C`sprintf\*(C'\fR function. It can pad on the left
1262 or right with blanks and on the left with zeroes and it will not
1263 truncate the result. The \f(CW\*(C`pack\*(C'\fR function can only pad strings on the
1264 right with blanks and it will truncate the result to a maximum length of
1265 \&\f(CW$pad_len\fR.
1266 .PP
1267 .Vb 3
1268 \& # Left padding a string with blanks (no truncation):
1269 \& my $padded = sprintf("%${pad_len}s", $text);
1270 \& my $padded = sprintf("%*s", $pad_len, $text); # same thing
1271 \&
1272 \& # Right padding a string with blanks (no truncation):
1273 \& my $padded = sprintf("%\-${pad_len}s", $text);
1274 \& my $padded = sprintf("%\-*s", $pad_len, $text); # same thing
1275 \&
1276 \& # Left padding a number with 0 (no truncation):
1277 \& my $padded = sprintf("%0${pad_len}d", $num);
1278 \& my $padded = sprintf("%0*d", $pad_len, $num); # same thing
1279 \&
1280 \& # Right padding a string with blanks using pack (will truncate):
1281 \& my $padded = pack("A$pad_len",$text);
1282 .Ve
1283 .PP
1284 If you need to pad with a character other than blank or zero you can use
1285 one of the following methods. They all generate a pad string with the
1286 \&\f(CW\*(C`x\*(C'\fR operator and combine that with \f(CW$text\fR. These methods do
1287 not truncate \f(CW$text\fR.
1288 .PP
1289 Left and right padding with any character, creating a new string:
1290 .PP
1291 .Vb 2
1292 \& my $padded = $pad_char x ( $pad_len \- length( $text ) ) . $text;
1293 \& my $padded = $text . $pad_char x ( $pad_len \- length( $text ) );
1294 .Ve
1295 .PP
1296 Left and right padding with any character, modifying \f(CW$text\fR directly:
1297 .PP
1298 .Vb 2
1299 \& substr( $text, 0, 0 ) = $pad_char x ( $pad_len \- length( $text ) );
1300 \& $text .= $pad_char x ( $pad_len \- length( $text ) );
1301 .Ve
1302 .SS "How do I extract selected columns from a string?"
1303 .IX Subsection "How do I extract selected columns from a string?"
1304 (contributed by brian d foy)
1305 .PP
1306 If you know the columns that contain the data, you can
1307 use \f(CW\*(C`substr\*(C'\fR to extract a single column.
1308 .PP
1309 .Vb 1
1310 \& my $column = substr( $line, $start_column, $length );
1311 .Ve
1312 .PP
1313 You can use \f(CW\*(C`split\*(C'\fR if the columns are separated by whitespace or
1314 some other delimiter, as long as whitespace or the delimiter cannot
1315 appear as part of the data.
1316 .PP
1317 .Vb 3
1318 \& my $line = \*(Aq fred barney betty \*(Aq;
1319 \& my @columns = split /\es+/, $line;
1320 \& # ( \*(Aq\*(Aq, \*(Aqfred\*(Aq, \*(Aqbarney\*(Aq, \*(Aqbetty\*(Aq );
1321 \&
1322 \& my $line = \*(Aqfred||barney||betty\*(Aq;
1323 \& my @columns = split /\e|/, $line;
1324 \& # ( \*(Aqfred\*(Aq, \*(Aq\*(Aq, \*(Aqbarney\*(Aq, \*(Aq\*(Aq, \*(Aqbetty\*(Aq );
1325 .Ve
1326 .PP
1327 If you want to work with comma\-separated values, don\*(Aqt do this since
1328 that format is a bit more complicated. Use one of the modules that
1329 handle that format, such as Text::CSV, Text::CSV_XS, or
1330 Text::CSV_PP.
1331 .PP
1332 If you want to break apart an entire line of fixed columns, you can use
1333 \&\f(CW\*(C`unpack\*(C'\fR with the A (ASCII) format. By using a number after the format
1334 specifier, you can denote the column width. See the \f(CW\*(C`pack\*(C'\fR and \f(CW\*(C`unpack\*(C'\fR
1335 entries in perlfunc for more details.
1336 .PP
1337 .Vb 1
1338 \& my @fields = unpack( "A8 A8 A8 A16 A4", $line );
1339 .Ve
1340 .PP
1341 Note that spaces in the format argument to \f(CW\*(C`unpack\*(C'\fR do not denote literal
1342 spaces. If you have space separated data, you may want \f(CW\*(C`split\*(C'\fR instead.
1343 .SS "How do I find the soundex value of a string?"
1344 .IX Subsection "How do I find the soundex value of a string?"
1345 (contributed by brian d foy)
1346 .PP
1347 You can use the \f(CW\*(C`Text::Soundex\*(C'\fR module. If you want to do fuzzy or close
1348 matching, you might also try the String::Approx, and
1349 Text::Metaphone, and Text::DoubleMetaphone modules.
1350 .SS "How can I expand variables in text strings?"
1351 .IX Subsection "How can I expand variables in text strings?"
1352 (contributed by brian d foy)
1353 .PP
1354 If you can avoid it, don\*(Aqt, or if you can use a templating system,
1355 such as Text::Template or Template Toolkit, do that instead. You
1356 might even be able to get the job done with \f(CW\*(C`sprintf\*(C'\fR or \f(CW\*(C`printf\*(C'\fR:
1357 .PP
1358 .Vb 1
1359 \& my $string = sprintf \*(AqSay hello to %s and %s\*(Aq, $foo, $bar;
1360 .Ve
1361 .PP
1362 However, for the one\-off simple case where I don\*(Aqt want to pull out a
1363 full templating system, I\*(Aqll use a string that has two Perl scalar
1364 variables in it. In this example, I want to expand \f(CW$foo\fR and \f(CW$bar\fR
1365 to their variable\*(Aqs values:
1366 .PP
1367 .Vb 3
1368 \& my $foo = \*(AqFred\*(Aq;
1369 \& my $bar = \*(AqBarney\*(Aq;
1370 \& $string = \*(AqSay hello to $foo and $bar\*(Aq;
1371 .Ve
1372 .PP
1373 One way I can do this involves the substitution operator and a double
1374 \&\f(CW\*(C`/e\*(C'\fR flag. The first \f(CW\*(C`/e\*(C'\fR evaluates \f(CW$1\fR on the replacement side and
1375 turns it into \f(CW$foo\fR. The second /e starts with \f(CW$foo\fR and replaces
1376 it with its value. \f(CW$foo\fR, then, turns into \*(AqFred\*(Aq, and that\*(Aqs finally
1377 what\*(Aqs left in the string:
1378 .PP
1379 .Vb 1
1380 \& $string =~ s/(\e$\ew+)/$1/eeg; # \*(AqSay hello to Fred and Barney\*(Aq
1381 .Ve
1382 .PP
1383 The \f(CW\*(C`/e\*(C'\fR will also silently ignore violations of strict, replacing
1384 undefined variable names with the empty string. Since I\*(Aqm using the
1385 \&\f(CW\*(C`/e\*(C'\fR flag (twice even!), I have all of the same security problems I
1386 have with \f(CW\*(C`eval\*(C'\fR in its string form. If there\*(Aqs something odd in
1387 \&\f(CW$foo\fR, perhaps something like \f(CW\*(C`@{[ system "rm \-rf /" ]}\*(C'\fR, then
1388 I could get myself in trouble.
1389 .PP
1390 To get around the security problem, I could also pull the values from
1391 a hash instead of evaluating variable names. Using a single \f(CW\*(C`/e\*(C'\fR, I
1392 can check the hash to ensure the value exists, and if it doesn\*(Aqt, I
1393 can replace the missing value with a marker, in this case \f(CW\*(C`???\*(C'\fR to
1394 signal that I missed something:
1395 .PP
1396 .Vb 1
1397 \& my $string = \*(AqThis has $foo and $bar\*(Aq;
1398 \&
1399 \& my %Replacements = (
1400 \& foo => \*(AqFred\*(Aq,
1401 \& );
1402 \&
1403 \& # $string =~ s/\e$(\ew+)/$Replacements{$1}/g;
1404 \& $string =~ s/\e$(\ew+)/
1405 \& exists $Replacements{$1} ? $Replacements{$1} : \*(Aq???\*(Aq
1406 \& /eg;
1407 \&
1408 \& print $string;
1409 .Ve
1410 .SS "Does Perl have anything like Ruby\*(Aqs #{} or Python\*(Aqs f string?"
1411 .IX Subsection "Does Perl have anything like Ruby's #{} or Python's f string?"
1412 Unlike the others, Perl allows you to embed a variable naked in a double
1413 quoted string, e.g. \f(CW"variable $variable"\fR. When there isn\*(Aqt whitespace or
1414 other non\-word characters following the variable name, you can add braces
1415 (e.g. \f(CW"foo ${foo}bar"\fR) to ensure correct parsing.
1416 .PP
1417 An array can also be embedded directly in a string, and will be expanded
1418 by default with spaces between the elements. The default
1419 LIST_SEPARATOR can be changed by assigning a
1420 different string to the special variable \f(CW$"\fR, such as \f(CW\*(C`local $" = \*(Aq, \*(Aq;\*(C'\fR.
1421 .PP
1422 Perl also supports references within a string providing the equivalent of
1423 the features in the other two languages.
1424 .PP
1425 \&\f(CW\*(C`${\e ... }\*(C'\fR embedded within a string will work for most simple statements
1426 such as an object\->method call. More complex code can be wrapped in a do
1427 block \f(CW\*(C`${\e do{...} }\*(C'\fR.
1428 .PP
1429 When you want a list to be expanded per \f(CW$"\fR, use \f(CW\*(C`@{[ ... ]}\*(C'\fR.
1430 .PP
1431 .Vb 4
1432 \& use Time::Piece;
1433 \& use Time::Seconds;
1434 \& my $scalar = \*(AqSTRING\*(Aq;
1435 \& my @array = ( \*(Aqzorro\*(Aq, \*(Aqa\*(Aq, 1, \*(AqB\*(Aq, 3 );
1436 \&
1437 \& # Print the current date and time and then Tomorrow
1438 \& my $t = Time::Piece\->new;
1439 \& say "Now is: ${\e $t\->cdate() }";
1440 \& say "Tomorrow: ${\e do{ my $T=Time::Piece\->new + ONE_DAY ; $T\->fullday }}";
1441 \&
1442 \& # some variables in strings
1443 \& say "This is some scalar I have $scalar, this is an array @array.";
1444 \& say "You can also write it like this ${scalar} @{array}.";
1445 \&
1446 \& # Change the $LIST_SEPARATOR
1447 \& local $" = \*(Aq:\*(Aq;
1448 \& say "Set \e$\e" to delimit with \*(Aq:\*(Aq and sort the Array @{[ sort @array ]}";
1449 .Ve
1450 .PP
1451 You may also want to look at the module
1452 Quote::Code, and templating tools such as Template::Toolkit and
1453 Mojo::Template.
1454 .PP
1455 See also: "How can I expand variables in text strings?" and
1456 "How do I expand function calls in a string?" in this FAQ.
1457 .SS "What\*(Aqs wrong with always quoting ""$vars""?"
1458 .IX Subsection "What's wrong with always quoting ""$vars""?"
1459 The problem is that those double\-quotes force
1460 stringification\-\-coercing numbers and references into strings\-\-even
1461 when you don\*(Aqt want them to be strings. Think of it this way:
1462 double\-quote expansion is used to produce new strings. If you already
1463 have a string, why do you need more?
1464 .PP
1465 If you get used to writing odd things like these:
1466 .PP
1467 .Vb 3
1468 \& print "$var"; # BAD
1469 \& my $new = "$old"; # BAD
1470 \& somefunc("$var"); # BAD
1471 .Ve
1472 .PP
1473 You\*(Aqll be in trouble. Those should (in 99.8% of the cases) be
1474 the simpler and more direct:
1475 .PP
1476 .Vb 3
1477 \& print $var;
1478 \& my $new = $old;
1479 \& somefunc($var);
1480 .Ve
1481 .PP
1482 Otherwise, besides slowing you down, you\*(Aqre going to break code when
1483 the thing in the scalar is actually neither a string nor a number, but
1484 a reference:
1485 .PP
1486 .Vb 5
1487 \& func(\e@array);
1488 \& sub func {
1489 \& my $aref = shift;
1490 \& my $oref = "$aref"; # WRONG
1491 \& }
1492 .Ve
1493 .PP
1494 You can also get into subtle problems on those few operations in Perl
1495 that actually do care about the difference between a string and a
1496 number, such as the magical \f(CW\*(C`++\*(C'\fR autoincrement operator or the
1497 \&\fBsyscall()\fR function.
1498 .PP
1499 Stringification also destroys arrays.
1500 .PP
1501 .Vb 3
1502 \& my @lines = \`command\`;
1503 \& print "@lines"; # WRONG \- extra blanks
1504 \& print @lines; # right
1505 .Ve
1506 .SS "Why don\*(Aqt my <<HERE documents work?"
1507 .IX Subsection "Why don't my <<HERE documents work?"
1508 Here documents are found in perlop. Check for these three things:
1509 .IP "There must be no space after the << part." 4
1510 .IX Item "There must be no space after the << part."
1511 .PD 0
1512 .IP "There (probably) should be a semicolon at the end of the opening token" 4
1513 .IX Item "There (probably) should be a semicolon at the end of the opening token"
1514 .IP "You can\*(Aqt (easily) have any space in front of the tag." 4
1515 .IX Item "You can't (easily) have any space in front of the tag."
1516 .IP "There needs to be at least a line separator after the end token." 4
1517 .IX Item "There needs to be at least a line separator after the end token."
1518 .PD
1519 .PP
1520 If you want to indent the text in the here document, you
1521 can do this:
1522 .PP
1523 .Vb 5
1524 \& # all in one
1525 \& (my $VAR = <<HERE_TARGET) =~ s/^\es+//gm;
1526 \& your text
1527 \& goes here
1528 \& HERE_TARGET
1529 .Ve
1530 .PP
1531 But the HERE_TARGET must still be flush against the margin.
1532 If you want that indented also, you\*(Aqll have to quote
1533 in the indentation.
1534 .PP
1535 .Vb 7
1536 \& (my $quote = <<\*(Aq FINIS\*(Aq) =~ s/^\es+//gm;
1537 \& ...we will have peace, when you and all your works have
1538 \& perished\-\-and the works of your dark master to whom you
1539 \& would deliver us. You are a liar, Saruman, and a corrupter
1540 \& of men\*(Aqs hearts. \-\-Theoden in /usr/src/perl/taint.c
1541 \& FINIS
1542 \& $quote =~ s/\es+\-\-/\en\-\-/;
1543 .Ve
1544 .PP
1545 A nice general\-purpose fixer\-upper function for indented here documents
1546 follows. It expects to be called with a here document as its argument.
1547 It looks to see whether each line begins with a common substring, and
1548 if so, strips that substring off. Otherwise, it takes the amount of leading
1549 whitespace found on the first line and removes that much off each
1550 subsequent line.
1551 .PP
1552 .Vb 11
1553 \& sub fix {
1554 \& local $_ = shift;
1555 \& my ($white, $leader); # common whitespace and common leading string
1556 \& if (/^\es*(?:([^\ew\es]+)(\es*).*\en)(?:\es*\eg1\eg2?.*\en)+$/) {
1557 \& ($white, $leader) = ($2, quotemeta($1));
1558 \& } else {
1559 \& ($white, $leader) = (/^(\es+)/, \*(Aq\*(Aq);
1560 \& }
1561 \& s/^\es*?$leader(?:$white)?//gm;
1562 \& return $_;
1563 \& }
1564 .Ve
1565 .PP
1566 This works with leading special strings, dynamically determined:
1567 .PP
1568 .Vb 10
1569 \& my $remember_the_main = fix<<\*(Aq MAIN_INTERPRETER_LOOP\*(Aq;
1570 \& @@@ int
1571 \& @@@ runops() {
1572 \& @@@ SAVEI32(runlevel);
1573 \& @@@ runlevel++;
1574 \& @@@ while ( op = (*op\->op_ppaddr)() );
1575 \& @@@ TAINT_NOT;
1576 \& @@@ return 0;
1577 \& @@@ }
1578 \& MAIN_INTERPRETER_LOOP
1579 .Ve
1580 .PP
1581 Or with a fixed amount of leading whitespace, with remaining
1582 indentation correctly preserved:
1583 .PP
1584 .Vb 9
1585 \& my $poem = fix<<EVER_ON_AND_ON;
1586 \& Now far ahead the Road has gone,
1587 \& And I must follow, if I can,
1588 \& Pursuing it with eager feet,
1589 \& Until it joins some larger way
1590 \& Where many paths and errands meet.
1591 \& And whither then? I cannot say.
1592 \& \-\-Bilbo in /usr/src/perl/pp_ctl.c
1593 \& EVER_ON_AND_ON
1594 .Ve
1595 .PP
1596 Beginning with Perl version 5.26, a much simpler and cleaner way to
1597 write indented here documents has been added to the language: the
1598 tilde (~) modifier. See "Indented Here\-docs" in perlop for details.
1599 .SH "Data: Arrays"
1600 .IX Header "Data: Arrays"
1601 .SS "What is the difference between a list and an array?"
1602 .IX Subsection "What is the difference between a list and an array?"
1603 (contributed by brian d foy)
1604 .PP
1605 A list is a fixed collection of scalars. An array is a variable that
1606 holds a variable collection of scalars. An array can supply its collection
1607 for list operations, so list operations also work on arrays:
1608 .PP
1609 .Vb 3
1610 \& # slices
1611 \& ( \*(Aqdog\*(Aq, \*(Aqcat\*(Aq, \*(Aqbird\*(Aq )[2,3];
1612 \& @animals[2,3];
1613 \&
1614 \& # iteration
1615 \& foreach ( qw( dog cat bird ) ) { ... }
1616 \& foreach ( @animals ) { ... }
1617 \&
1618 \& my @three = grep { length == 3 } qw( dog cat bird );
1619 \& my @three = grep { length == 3 } @animals;
1620 \&
1621 \& # supply an argument list
1622 \& wash_animals( qw( dog cat bird ) );
1623 \& wash_animals( @animals );
1624 .Ve
1625 .PP
1626 Array operations, which change the scalars, rearrange them, or add
1627 or subtract some scalars, only work on arrays. These can\*(Aqt work on a
1628 list, which is fixed. Array operations include \f(CW\*(C`shift\*(C'\fR, \f(CW\*(C`unshift\*(C'\fR,
1629 \&\f(CW\*(C`push\*(C'\fR, \f(CW\*(C`pop\*(C'\fR, and \f(CW\*(C`splice\*(C'\fR.
1630 .PP
1631 An array can also change its length:
1632 .PP
1633 .Vb 2
1634 \& $#animals = 1; # truncate to two elements
1635 \& $#animals = 10000; # pre\-extend to 10,001 elements
1636 .Ve
1637 .PP
1638 You can change an array element, but you can\*(Aqt change a list element:
1639 .PP
1640 .Vb 2
1641 \& $animals[0] = \*(AqRottweiler\*(Aq;
1642 \& qw( dog cat bird )[0] = \*(AqRottweiler\*(Aq; # syntax error!
1643 \&
1644 \& foreach ( @animals ) {
1645 \& s/^d/fr/; # works fine
1646 \& }
1647 \&
1648 \& foreach ( qw( dog cat bird ) ) {
1649 \& s/^d/fr/; # Error! Modification of read only value!
1650 \& }
1651 .Ve
1652 .PP
1653 However, if the list element is itself a variable, it appears that you
1654 can change a list element. However, the list element is the variable, not
1655 the data. You\*(Aqre not changing the list element, but something the list
1656 element refers to. The list element itself doesn\*(Aqt change: it\*(Aqs still
1657 the same variable.
1658 .PP
1659 You also have to be careful about context. You can assign an array to
1660 a scalar to get the number of elements in the array. This only works
1661 for arrays, though:
1662 .PP
1663 .Vb 1
1664 \& my $count = @animals; # only works with arrays
1665 .Ve
1666 .PP
1667 If you try to do the same thing with what you think is a list, you
1668 get a quite different result. Although it looks like you have a list
1669 on the righthand side, Perl actually sees a bunch of scalars separated
1670 by a comma:
1671 .PP
1672 .Vb 1
1673 \& my $scalar = ( \*(Aqdog\*(Aq, \*(Aqcat\*(Aq, \*(Aqbird\*(Aq ); # $scalar gets bird
1674 .Ve
1675 .PP
1676 Since you\*(Aqre assigning to a scalar, the righthand side is in scalar
1677 context. The comma operator (yes, it\*(Aqs an operator!) in scalar
1678 context evaluates its lefthand side, throws away the result, and
1679 evaluates its righthand side and returns the result. In effect,
1680 that list\-lookalike assigns to \f(CW$scalar\fR its rightmost value. Many
1681 people mess this up because they choose a list\-lookalike whose
1682 last element is also the count they expect:
1683 .PP
1684 .Vb 1
1685 \& my $scalar = ( 1, 2, 3 ); # $scalar gets 3, accidentally
1686 .Ve
1687 .ie n .SS "What is the difference between $array[1] and @array[1]?"
1688 .el .SS "What is the difference between \f(CW$array\fP[1] and \f(CW@array\fP[1]?"
1689 .IX Subsection "What is the difference between $array[1] and @array[1]?"
1690 (contributed by brian d foy)
1691 .PP
1692 The difference is the sigil, that special character in front of the
1693 array name. The \f(CW\*(C`$\*(C'\fR sigil means "exactly one item", while the \f(CW\*(C`@\*(C'\fR
1694 sigil means "zero or more items". The \f(CW\*(C`$\*(C'\fR gets you a single scalar,
1695 while the \f(CW\*(C`@\*(C'\fR gets you a list.
1696 .PP
1697 The confusion arises because people incorrectly assume that the sigil
1698 denotes the variable type.
1699 .PP
1700 The \f(CW$array[1]\fR is a single\-element access to the array. It\*(Aqs going
1701 to return the item in index 1 (or undef if there is no item there).
1702 If you intend to get exactly one element from the array, this is the
1703 form you should use.
1704 .PP
1705 The \f(CW@array[1]\fR is an array slice, although it has only one index.
1706 You can pull out multiple elements simultaneously by specifying
1707 additional indices as a list, like \f(CW@array[1,4,3,0]\fR.
1708 .PP
1709 Using a slice on the lefthand side of the assignment supplies list
1710 context to the righthand side. This can lead to unexpected results.
1711 For instance, if you want to read a single line from a filehandle,
1712 assigning to a scalar value is fine:
1713 .PP
1714 .Vb 1
1715 \& $array[1] = <STDIN>;
1716 .Ve
1717 .PP
1718 However, in list context, the line input operator returns all of the
1719 lines as a list. The first line goes into \f(CW@array[1]\fR and the rest
1720 of the lines mysteriously disappear:
1721 .PP
1722 .Vb 1
1723 \& @array[1] = <STDIN>; # most likely not what you want
1724 .Ve
1725 .PP
1726 Either the \f(CW\*(C`use warnings\*(C'\fR pragma or the \fB\-w\fR flag will warn you when
1727 you use an array slice with a single index.
1728 .SS "How can I remove duplicate elements from a list or array?"
1729 .IX Subsection "How can I remove duplicate elements from a list or array?"
1730 (contributed by brian d foy)
1731 .PP
1732 Use a hash. When you think the words "unique" or "duplicated", think
1733 "hash keys".
1734 .PP
1735 If you don\*(Aqt care about the order of the elements, you could just
1736 create the hash then extract the keys. It\*(Aqs not important how you
1737 create that hash: just that you use \f(CW\*(C`keys\*(C'\fR to get the unique
1738 elements.
1739 .PP
1740 .Vb 3
1741 \& my %hash = map { $_, 1 } @array;
1742 \& # or a hash slice: @hash{ @array } = ();
1743 \& # or a foreach: $hash{$_} = 1 foreach ( @array );
1744 \&
1745 \& my @unique = keys %hash;
1746 .Ve
1747 .PP
1748 If you want to use a module, try the \f(CW\*(C`uniq\*(C'\fR function from
1749 List::Util. In list context it returns the unique elements,
1750 preserving their order in the list. In scalar context, it returns the
1751 number of unique elements.
1752 .PP
1753 .Vb 1
1754 \& use List::Util qw(uniq);
1755 \&
1756 \& my @unique = uniq( 1, 2, 3, 4, 4, 5, 6, 5, 8 ); # 1,2,3,4,5,6,8
1757 \& my $unique = uniq( 1, 2, 3, 4, 4, 5, 6, 5, 8 ); # 7
1758 .Ve
1759 .PP
1760 You can also go through each element and skip the ones you\*(Aqve seen
1761 before. Use a hash to keep track. The first time the loop sees an
1762 element, that element has no key in \f(CW%seen\fR. The \f(CW\*(C`next\*(C'\fR statement
1763 creates the key and immediately uses its value, which is \f(CW\*(C`undef\*(C'\fR, so
1764 the loop continues to the \f(CW\*(C`push\*(C'\fR and increments the value for that
1765 key. The next time the loop sees that same element, its key exists in
1766 the hash \fIand\fR the value for that key is true (since it\*(Aqs not 0 or
1767 \&\f(CW\*(C`undef\*(C'\fR), so the next skips that iteration and the loop goes to the
1768 next element.
1769 .PP
1770 .Vb 2
1771 \& my @unique = ();
1772 \& my %seen = ();
1773 \&
1774 \& foreach my $elem ( @array ) {
1775 \& next if $seen{ $elem }++;
1776 \& push @unique, $elem;
1777 \& }
1778 .Ve
1779 .PP
1780 You can write this more briefly using a grep, which does the
1781 same thing.
1782 .PP
1783 .Vb 2
1784 \& my %seen = ();
1785 \& my @unique = grep { ! $seen{ $_ }++ } @array;
1786 .Ve
1787 .SS "How can I tell whether a certain element is contained in a list or array?"
1788 .IX Subsection "How can I tell whether a certain element is contained in a list or array?"
1789 (portions of this answer contributed by Anno Siegel and brian d foy)
1790 .PP
1791 Hearing the word "in" is an \fIin\fRdication that you probably should have
1792 used a hash, not a list or array, to store your data. Hashes are
1793 designed to answer this question quickly and efficiently. Arrays aren\*(Aqt.
1794 .PP
1795 That being said, there are several ways to approach this. If you
1796 are going to make this query many times over arbitrary string values,
1797 the fastest way is probably to invert the original array and maintain a
1798 hash whose keys are the first array\*(Aqs values:
1799 .PP
1800 .Vb 3
1801 \& my @blues = qw/azure cerulean teal turquoise lapis\-lazuli/;
1802 \& my %is_blue = ();
1803 \& for (@blues) { $is_blue{$_} = 1 }
1804 .Ve
1805 .PP
1806 Now you can check whether \f(CW$is_blue{$some_color}\fR. It might have
1807 been a good idea to keep the blues all in a hash in the first place.
1808 .PP
1809 If the values are all small integers, you could use a simple indexed
1810 array. This kind of an array will take up less space:
1811 .PP
1812 .Vb 4
1813 \& my @primes = (2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31);
1814 \& my @is_tiny_prime = ();
1815 \& for (@primes) { $is_tiny_prime[$_] = 1 }
1816 \& # or simply @is_tiny_prime[@primes] = (1) x @primes;
1817 .Ve
1818 .PP
1819 Now you check whether \f(CW$is_tiny_prime\fR[$some_number].
1820 .PP
1821 If the values in question are integers instead of strings, you can save
1822 quite a lot of space by using bit strings instead:
1823 .PP
1824 .Vb 3
1825 \& my @articles = ( 1..10, 150..2000, 2017 );
1826 \& undef $read;
1827 \& for (@articles) { vec($read,$_,1) = 1 }
1828 .Ve
1829 .PP
1830 Now check whether \f(CW\*(C`vec($read,$n,1)\*(C'\fR is true for some \f(CW$n\fR.
1831 .PP
1832 These methods guarantee fast individual tests but require a re\-organization
1833 of the original list or array. They only pay off if you have to test
1834 multiple values against the same array.
1835 .PP
1836 If you are testing only once, the standard module List::Util exports
1837 the function \f(CW\*(C`any\*(C'\fR for this purpose. It works by stopping once it
1838 finds the element. It\*(Aqs written in C for speed, and its Perl equivalent
1839 looks like this subroutine:
1840 .PP
1841 .Vb 7
1842 \& sub any (&@) {
1843 \& my $code = shift;
1844 \& foreach (@_) {
1845 \& return 1 if $code\->();
1846 \& }
1847 \& return 0;
1848 \& }
1849 .Ve
1850 .PP
1851 If speed is of little concern, the common idiom uses grep in scalar context
1852 (which returns the number of items that passed its condition) to traverse the
1853 entire list. This does have the benefit of telling you how many matches it
1854 found, though.
1855 .PP
1856 .Vb 1
1857 \& my $is_there = grep $_ eq $whatever, @array;
1858 .Ve
1859 .PP
1860 If you want to actually extract the matching elements, simply use grep in
1861 list context.
1862 .PP
1863 .Vb 1
1864 \& my @matches = grep $_ eq $whatever, @array;
1865 .Ve
1866 .SS "How do I compute the difference of two arrays? How do I compute the intersection of two arrays?"
1867 .IX Subsection "How do I compute the difference of two arrays? How do I compute the intersection of two arrays?"
1868 Use a hash. Here\*(Aqs code to do both and more. It assumes that each
1869 element is unique in a given array:
1870 .PP
1871 .Vb 7
1872 \& my (@union, @intersection, @difference);
1873 \& my %count = ();
1874 \& foreach my $element (@array1, @array2) { $count{$element}++ }
1875 \& foreach my $element (keys %count) {
1876 \& push @union, $element;
1877 \& push @{ $count{$element} > 1 ? \e@intersection : \e@difference }, $element;
1878 \& }
1879 .Ve
1880 .PP
1881 Note that this is the \fIsymmetric difference\fR, that is, all elements
1882 in either A or in B but not in both. Think of it as an xor operation.
1883 .SS "How do I test whether two arrays or hashes are equal?"
1884 .IX Subsection "How do I test whether two arrays or hashes are equal?"
1885 The following code works for single\-level arrays. It uses a
1886 stringwise comparison, and does not distinguish defined versus
1887 undefined empty strings. Modify if you have other needs.
1888 .PP
1889 .Vb 1
1890 \& $are_equal = compare_arrays(\e@frogs, \e@toads);
1891 \&
1892 \& sub compare_arrays {
1893 \& my ($first, $second) = @_;
1894 \& no warnings; # silence spurious \-w undef complaints
1895 \& return 0 unless @$first == @$second;
1896 \& for (my $i = 0; $i < @$first; $i++) {
1897 \& return 0 if $first\->[$i] ne $second\->[$i];
1898 \& }
1899 \& return 1;
1900 \& }
1901 .Ve
1902 .PP
1903 For multilevel structures, you may wish to use an approach more
1904 like this one. It uses the CPAN module FreezeThaw:
1905 .PP
1906 .Vb 2
1907 \& use FreezeThaw qw(cmpStr);
1908 \& my @a = my @b = ( "this", "that", [ "more", "stuff" ] );
1909 \&
1910 \& printf "a and b contain %s arrays\en",
1911 \& cmpStr(\e@a, \e@b) == 0
1912 \& ? "the same"
1913 \& : "different";
1914 .Ve
1915 .PP
1916 This approach also works for comparing hashes. Here we\*(Aqll demonstrate
1917 two different answers:
1918 .PP
1919 .Vb 1
1920 \& use FreezeThaw qw(cmpStr cmpStrHard);
1921 \&
1922 \& my %a = my %b = ( "this" => "that", "extra" => [ "more", "stuff" ] );
1923 \& $a{EXTRA} = \e%b;
1924 \& $b{EXTRA} = \e%a;
1925 \&
1926 \& printf "a and b contain %s hashes\en",
1927 \& cmpStr(\e%a, \e%b) == 0 ? "the same" : "different";
1928 \&
1929 \& printf "a and b contain %s hashes\en",
1930 \& cmpStrHard(\e%a, \e%b) == 0 ? "the same" : "different";
1931 .Ve
1932 .PP
1933 The first reports that both hashes contain the same data,
1934 while the second reports that they do not. Which you prefer is left as
1935 an exercise to the reader.
1936 .SS "How do I find the first array element for which a condition is true?"
1937 .IX Subsection "How do I find the first array element for which a condition is true?"
1938 To find the first array element which satisfies a condition, you can
1939 use the \f(CWfirst()\fR function in the List::Util module, which comes
1940 with Perl 5.8. This example finds the first element that contains
1941 "Perl".
1942 .PP
1943 .Vb 1
1944 \& use List::Util qw(first);
1945 \&
1946 \& my $element = first { /Perl/ } @array;
1947 .Ve
1948 .PP
1949 If you cannot use List::Util, you can make your own loop to do the
1950 same thing. Once you find the element, you stop the loop with last.
1951 .PP
1952 .Vb 4
1953 \& my $found;
1954 \& foreach ( @array ) {
1955 \& if( /Perl/ ) { $found = $_; last }
1956 \& }
1957 .Ve
1958 .PP
1959 If you want the array index, use the \f(CWfirstidx()\fR function from
1960 \&\f(CW\*(C`List::MoreUtils\*(C'\fR:
1961 .PP
1962 .Vb 2
1963 \& use List::MoreUtils qw(firstidx);
1964 \& my $index = firstidx { /Perl/ } @array;
1965 .Ve
1966 .PP
1967 Or write it yourself, iterating through the indices
1968 and checking the array element at each index until you find one
1969 that satisfies the condition:
1970 .PP
1971 .Vb 8
1972 \& my( $found, $index ) = ( undef, \-1 );
1973 \& for( $i = 0; $i < @array; $i++ ) {
1974 \& if( $array[$i] =~ /Perl/ ) {
1975 \& $found = $array[$i];
1976 \& $index = $i;
1977 \& last;
1978 \& }
1979 \& }
1980 .Ve
1981 .SS "How do I handle linked lists?"
1982 .IX Subsection "How do I handle linked lists?"
1983 (contributed by brian d foy)
1984 .PP
1985 Perl\*(Aqs arrays do not have a fixed size, so you don\*(Aqt need linked lists
1986 if you just want to add or remove items. You can use array operations
1987 such as \f(CW\*(C`push\*(C'\fR, \f(CW\*(C`pop\*(C'\fR, \f(CW\*(C`shift\*(C'\fR, \f(CW\*(C`unshift\*(C'\fR, or \f(CW\*(C`splice\*(C'\fR to do
1988 that.
1989 .PP
1990 Sometimes, however, linked lists can be useful in situations where you
1991 want to "shard" an array so you have many small arrays instead of
1992 a single big array. You can keep arrays longer than Perl\*(Aqs largest
1993 array index, lock smaller arrays separately in threaded programs,
1994 reallocate less memory, or quickly insert elements in the middle of
1995 the chain.
1996 .PP
1997 Steve Lembark goes through the details in his YAPC::NA 2009 talk "Perly
1998 Linked Lists" ( <http://www.slideshare.net/lembark/perly\-linked\-lists> ),
1999 although you can just use his LinkedList::Single module.
2000 .SS "How do I handle circular lists?"
2001 .IX Xref "circular array Tie::Cycle Array::Iterator::Circular cycle modulus"
2002 .IX Subsection "How do I handle circular lists?"
2003 (contributed by brian d foy)
2004 .PP
2005 If you want to cycle through an array endlessly, you can increment the
2006 index modulo the number of elements in the array:
2007 .PP
2008 .Vb 2
2009 \& my @array = qw( a b c );
2010 \& my $i = 0;
2011 \&
2012 \& while( 1 ) {
2013 \& print $array[ $i++ % @array ], "\en";
2014 \& last if $i > 20;
2015 \& }
2016 .Ve
2017 .PP
2018 You can also use Tie::Cycle to use a scalar that always has the
2019 next element of the circular array:
2020 .PP
2021 .Vb 1
2022 \& use Tie::Cycle;
2023 \&
2024 \& tie my $cycle, \*(AqTie::Cycle\*(Aq, [ qw( FFFFFF 000000 FFFF00 ) ];
2025 \&
2026 \& print $cycle; # FFFFFF
2027 \& print $cycle; # 000000
2028 \& print $cycle; # FFFF00
2029 .Ve
2030 .PP
2031 The Array::Iterator::Circular creates an iterator object for
2032 circular arrays:
2033 .PP
2034 .Vb 1
2035 \& use Array::Iterator::Circular;
2036 \&
2037 \& my $color_iterator = Array::Iterator::Circular\->new(
2038 \& qw(red green blue orange)
2039 \& );
2040 \&
2041 \& foreach ( 1 .. 20 ) {
2042 \& print $color_iterator\->next, "\en";
2043 \& }
2044 .Ve
2045 .SS "How do I shuffle an array randomly?"
2046 .IX Subsection "How do I shuffle an array randomly?"
2047 If you either have Perl 5.8.0 or later installed, or if you have
2048 Scalar\-List\-Utils 1.03 or later installed, you can say:
2049 .PP
2050 .Vb 1
2051 \& use List::Util \*(Aqshuffle\*(Aq;
2052 \&
2053 \& @shuffled = shuffle(@list);
2054 .Ve
2055 .PP
2056 If not, you can use a Fisher\-Yates shuffle.
2057 .PP
2058 .Vb 3
2059 \& sub fisher_yates_shuffle {
2060 \& my $deck = shift; # $deck is a reference to an array
2061 \& return unless @$deck; # must not be empty!
2062 \&
2063 \& my $i = @$deck;
2064 \& while (\-\-$i) {
2065 \& my $j = int rand ($i+1);
2066 \& @$deck[$i,$j] = @$deck[$j,$i];
2067 \& }
2068 \& }
2069 \&
2070 \& # shuffle my mpeg collection
2071 \& #
2072 \& my @mpeg = <audio/*/*.mp3>;
2073 \& fisher_yates_shuffle( \e@mpeg ); # randomize @mpeg in place
2074 \& print @mpeg;
2075 .Ve
2076 .PP
2077 Note that the above implementation shuffles an array in place,
2078 unlike the \f(CWList::Util::shuffle()\fR which takes a list and returns
2079 a new shuffled list.
2080 .PP
2081 You\*(Aqve probably seen shuffling algorithms that work using splice,
2082 randomly picking another element to swap the current element with
2083 .PP
2084 .Vb 6
2085 \& srand;
2086 \& @new = ();
2087 \& @old = 1 .. 10; # just a demo
2088 \& while (@old) {
2089 \& push(@new, splice(@old, rand @old, 1));
2090 \& }
2091 .Ve
2092 .PP
2093 This is bad because splice is already O(N), and since you do it N
2094 times, you just invented a quadratic algorithm; that is, O(N**2).
2095 This does not scale, although Perl is so efficient that you probably
2096 won\*(Aqt notice this until you have rather largish arrays.
2097 .SS "How do I process/modify each element of an array?"
2098 .IX Subsection "How do I process/modify each element of an array?"
2099 Use \f(CW\*(C`for\*(C'\fR/\f(CW\*(C`foreach\*(C'\fR:
2100 .PP
2101 .Vb 4
2102 \& for (@lines) {
2103 \& s/foo/bar/; # change that word
2104 \& tr/XZ/ZX/; # swap those letters
2105 \& }
2106 .Ve
2107 .PP
2108 Here\*(Aqs another; let\*(Aqs compute spherical volumes:
2109 .PP
2110 .Vb 5
2111 \& my @volumes = @radii;
2112 \& for (@volumes) { # @volumes has changed parts
2113 \& $_ **= 3;
2114 \& $_ *= (4/3) * 3.14159; # this will be constant folded
2115 \& }
2116 .Ve
2117 .PP
2118 which can also be done with \f(CWmap()\fR which is made to transform
2119 one list into another:
2120 .PP
2121 .Vb 1
2122 \& my @volumes = map {$_ ** 3 * (4/3) * 3.14159} @radii;
2123 .Ve
2124 .PP
2125 If you want to do the same thing to modify the values of the
2126 hash, you can use the \f(CW\*(C`values\*(C'\fR function. As of Perl 5.6
2127 the values are not copied, so if you modify \f(CW$orbit\fR (in this
2128 case), you modify the value.
2129 .PP
2130 .Vb 3
2131 \& for my $orbit ( values %orbits ) {
2132 \& ($orbit **= 3) *= (4/3) * 3.14159;
2133 \& }
2134 .Ve
2135 .PP
2136 Prior to perl 5.6 \f(CW\*(C`values\*(C'\fR returned copies of the values,
2137 so older perl code often contains constructions such as
2138 \&\f(CW@orbits{keys %orbits}\fR instead of \f(CW\*(C`values %orbits\*(C'\fR where
2139 the hash is to be modified.
2140 .SS "How do I select a random element from an array?"
2141 .IX Subsection "How do I select a random element from an array?"
2142 Use the \f(CWrand()\fR function (see "rand" in perlfunc):
2143 .PP
2144 .Vb 2
2145 \& my $index = rand @array;
2146 \& my $element = $array[$index];
2147 .Ve
2148 .PP
2149 Or, simply:
2150 .PP
2151 .Vb 1
2152 \& my $element = $array[ rand @array ];
2153 .Ve
2154 .SS "How do I permute N elements of a list?"
2155 .IX Xref "List::Permutor permute Algorithm::Loops Knuth The Art of Computer Programming Fischer-Krause"
2156 .IX Subsection "How do I permute N elements of a list?"
2157 Use the List::Permutor module on CPAN. If the list is actually an
2158 array, try the Algorithm::Permute module (also on CPAN). It\*(Aqs
2159 written in XS code and is very efficient:
2160 .PP
2161 .Vb 1
2162 \& use Algorithm::Permute;
2163 \&
2164 \& my @array = \*(Aqa\*(Aq..\*(Aqd\*(Aq;
2165 \& my $p_iterator = Algorithm::Permute\->new ( \e@array );
2166 \&
2167 \& while (my @perm = $p_iterator\->next) {
2168 \& print "next permutation: (@perm)\en";
2169 \& }
2170 .Ve
2171 .PP
2172 For even faster execution, you could do:
2173 .PP
2174 .Vb 1
2175 \& use Algorithm::Permute;
2176 \&
2177 \& my @array = \*(Aqa\*(Aq..\*(Aqd\*(Aq;
2178 \&
2179 \& Algorithm::Permute::permute {
2180 \& print "next permutation: (@array)\en";
2181 \& } @array;
2182 .Ve
2183 .PP
2184 Here\*(Aqs a little program that generates all permutations of all the
2185 words on each line of input. The algorithm embodied in the
2186 \&\f(CWpermute()\fR function is discussed in Volume 4 (still unpublished) of
2187 Knuth\*(Aqs \fIThe Art of Computer Programming\fR and will work on any list:
2188 .PP
2189 .Vb 2
2190 \& #!/usr/bin/perl \-n
2191 \& # Fischer\-Krause ordered permutation generator
2192 \&
2193 \& sub permute (&@) {
2194 \& my $code = shift;
2195 \& my @idx = 0..$#_;
2196 \& while ( $code\->(@_[@idx]) ) {
2197 \& my $p = $#idx;
2198 \& \-\-$p while $idx[$p\-1] > $idx[$p];
2199 \& my $q = $p or return;
2200 \& push @idx, reverse splice @idx, $p;
2201 \& ++$q while $idx[$p\-1] > $idx[$q];
2202 \& @idx[$p\-1,$q]=@idx[$q,$p\-1];
2203 \& }
2204 \& }
2205 \&
2206 \& permute { print "@_\en" } split;
2207 .Ve
2208 .PP
2209 The Algorithm::Loops module also provides the \f(CW\*(C`NextPermute\*(C'\fR and
2210 \&\f(CW\*(C`NextPermuteNum\*(C'\fR functions which efficiently find all unique permutations
2211 of an array, even if it contains duplicate values, modifying it in\-place:
2212 if its elements are in reverse\-sorted order then the array is reversed,
2213 making it sorted, and it returns false; otherwise the next
2214 permutation is returned.
2215 .PP
2216 \&\f(CW\*(C`NextPermute\*(C'\fR uses string order and \f(CW\*(C`NextPermuteNum\*(C'\fR numeric order, so
2217 you can enumerate all the permutations of \f(CW0..9\fR like this:
2218 .PP
2219 .Vb 1
2220 \& use Algorithm::Loops qw(NextPermuteNum);
2221 \&
2222 \& my @list= 0..9;
2223 \& do { print "@list\en" } while NextPermuteNum @list;
2224 .Ve
2225 .SS "How do I sort an array by (anything)?"
2226 .IX Subsection "How do I sort an array by (anything)?"
2227 Supply a comparison function to \fBsort()\fR (described in "sort" in perlfunc):
2228 .PP
2229 .Vb 1
2230 \& @list = sort { $a <=> $b } @list;
2231 .Ve
2232 .PP
2233 The default sort function is cmp, string comparison, which would
2234 sort \f(CW\*(C`(1, 2, 10)\*(C'\fR into \f(CW\*(C`(1, 10, 2)\*(C'\fR. \f(CW\*(C`<=>\*(C'\fR, used above, is
2235 the numerical comparison operator.
2236 .PP
2237 If you have a complicated function needed to pull out the part you
2238 want to sort on, then don\*(Aqt do it inside the sort function. Pull it
2239 out first, because the sort BLOCK can be called many times for the
2240 same element. Here\*(Aqs an example of how to pull out the first word
2241 after the first number on each item, and then sort those words
2242 case\-insensitively.
2243 .PP
2244 .Vb 7
2245 \& my @idx;
2246 \& for (@data) {
2247 \& my $item;
2248 \& ($item) = /\ed+\es*(\eS+)/;
2249 \& push @idx, uc($item);
2250 \& }
2251 \& my @sorted = @data[ sort { $idx[$a] cmp $idx[$b] } 0 .. $#idx ];
2252 .Ve
2253 .PP
2254 which could also be written this way, using a trick
2255 that\*(Aqs come to be known as the Schwartzian Transform:
2256 .PP
2257 .Vb 3
2258 \& my @sorted = map { $_\->[0] }
2259 \& sort { $a\->[1] cmp $b\->[1] }
2260 \& map { [ $_, uc( (/\ed+\es*(\eS+)/)[0]) ] } @data;
2261 .Ve
2262 .PP
2263 If you need to sort on several fields, the following paradigm is useful.
2264 .PP
2265 .Vb 5
2266 \& my @sorted = sort {
2267 \& field1($a) <=> field1($b) ||
2268 \& field2($a) cmp field2($b) ||
2269 \& field3($a) cmp field3($b)
2270 \& } @data;
2271 .Ve
2272 .PP
2273 This can be conveniently combined with precalculation of keys as given
2274 above.
2275 .PP
2276 See the \fIsort\fR article in the "Far More Than You Ever Wanted
2277 To Know" collection in <http://www.cpan.org/misc/olddoc/FMTEYEWTK.tgz> for
2278 more about this approach.
2279 .PP
2280 See also the question later in perlfaq4 on sorting hashes.
2281 .SS "How do I manipulate arrays of bits?"
2282 .IX Subsection "How do I manipulate arrays of bits?"
2283 Use \f(CWpack()\fR and \f(CWunpack()\fR, or else \f(CWvec()\fR and the bitwise
2284 operations.
2285 .PP
2286 For example, you don\*(Aqt have to store individual bits in an array
2287 (which would mean that you\*(Aqre wasting a lot of space). To convert an
2288 array of bits to a string, use \f(CWvec()\fR to set the right bits. This
2289 sets \f(CW$vec\fR to have bit N set only if \f(CW$ints[N]\fR was set:
2290 .PP
2291 .Vb 5
2292 \& my @ints = (...); # array of bits, e.g. ( 1, 0, 0, 1, 1, 0 ... )
2293 \& my $vec = \*(Aq\*(Aq;
2294 \& foreach( 0 .. $#ints ) {
2295 \& vec($vec,$_,1) = 1 if $ints[$_];
2296 \& }
2297 .Ve
2298 .PP
2299 The string \f(CW$vec\fR only takes up as many bits as it needs. For
2300 instance, if you had 16 entries in \f(CW@ints\fR, \f(CW$vec\fR only needs two
2301 bytes to store them (not counting the scalar variable overhead).
2302 .PP
2303 Here\*(Aqs how, given a vector in \f(CW$vec\fR, you can get those bits into
2304 your \f(CW@ints\fR array:
2305 .PP
2306 .Vb 7
2307 \& sub bitvec_to_list {
2308 \& my $vec = shift;
2309 \& my @ints;
2310 \& # Find null\-byte density then select best algorithm
2311 \& if ($vec =~ tr/\e0// / length $vec > 0.95) {
2312 \& use integer;
2313 \& my $i;
2314 \&
2315 \& # This method is faster with mostly null\-bytes
2316 \& while($vec =~ /[^\e0]/g ) {
2317 \& $i = \-9 + 8 * pos $vec;
2318 \& push @ints, $i if vec($vec, ++$i, 1);
2319 \& push @ints, $i if vec($vec, ++$i, 1);
2320 \& push @ints, $i if vec($vec, ++$i, 1);
2321 \& push @ints, $i if vec($vec, ++$i, 1);
2322 \& push @ints, $i if vec($vec, ++$i, 1);
2323 \& push @ints, $i if vec($vec, ++$i, 1);
2324 \& push @ints, $i if vec($vec, ++$i, 1);
2325 \& push @ints, $i if vec($vec, ++$i, 1);
2326 \& }
2327 \& }
2328 \& else {
2329 \& # This method is a fast general algorithm
2330 \& use integer;
2331 \& my $bits = unpack "b*", $vec;
2332 \& push @ints, 0 if $bits =~ s/^(\ed)// && $1;
2333 \& push @ints, pos $bits while($bits =~ /1/g);
2334 \& }
2335 \&
2336 \& return \e@ints;
2337 \& }
2338 .Ve
2339 .PP
2340 This method gets faster the more sparse the bit vector is.
2341 (Courtesy of Tim Bunce and Winfried Koenig.)
2342 .PP
2343 You can make the while loop a lot shorter with this suggestion
2344 from Benjamin Goldberg:
2345 .PP
2346 .Vb 3
2347 \& while($vec =~ /[^\e0]+/g ) {
2348 \& push @ints, grep vec($vec, $_, 1), $\-[0] * 8 .. $+[0] * 8;
2349 \& }
2350 .Ve
2351 .PP
2352 Or use the CPAN module Bit::Vector:
2353 .PP
2354 .Vb 3
2355 \& my $vector = Bit::Vector\->new($num_of_bits);
2356 \& $vector\->Index_List_Store(@ints);
2357 \& my @ints = $vector\->Index_List_Read();
2358 .Ve
2359 .PP
2360 Bit::Vector provides efficient methods for bit vector, sets of
2361 small integers and "big int" math.
2362 .PP
2363 Here\*(Aqs a more extensive illustration using \fBvec()\fR:
2364 .PP
2365 .Vb 7
2366 \& # vec demo
2367 \& my $vector = "\exff\ex0f\exef\exfe";
2368 \& print "Ilya\*(Aqs string \e\exff\e\ex0f\e\exef\e\exfe represents the number ",
2369 \& unpack("N", $vector), "\en";
2370 \& my $is_set = vec($vector, 23, 1);
2371 \& print "Its 23rd bit is ", $is_set ? "set" : "clear", ".\en";
2372 \& pvec($vector);
2373 \&
2374 \& set_vec(1,1,1);
2375 \& set_vec(3,1,1);
2376 \& set_vec(23,1,1);
2377 \&
2378 \& set_vec(3,1,3);
2379 \& set_vec(3,2,3);
2380 \& set_vec(3,4,3);
2381 \& set_vec(3,4,7);
2382 \& set_vec(3,8,3);
2383 \& set_vec(3,8,7);
2384 \&
2385 \& set_vec(0,32,17);
2386 \& set_vec(1,32,17);
2387 \&
2388 \& sub set_vec {
2389 \& my ($offset, $width, $value) = @_;
2390 \& my $vector = \*(Aq\*(Aq;
2391 \& vec($vector, $offset, $width) = $value;
2392 \& print "offset=$offset width=$width value=$value\en";
2393 \& pvec($vector);
2394 \& }
2395 \&
2396 \& sub pvec {
2397 \& my $vector = shift;
2398 \& my $bits = unpack("b*", $vector);
2399 \& my $i = 0;
2400 \& my $BASE = 8;
2401 \&
2402 \& print "vector length in bytes: ", length($vector), "\en";
2403 \& @bytes = unpack("A8" x length($vector), $bits);
2404 \& print "bits are: @bytes\en\en";
2405 \& }
2406 .Ve
2407 .SS "Why does \fBdefined()\fP return true on empty arrays and hashes?"
2408 .IX Subsection "Why does defined() return true on empty arrays and hashes?"
2409 The short story is that you should probably only use defined on scalars or
2410 functions, not on aggregates (arrays and hashes). See "defined" in perlfunc
2411 in the 5.004 release or later of Perl for more detail.
2412 .SH "Data: Hashes (Associative Arrays)"
2413 .IX Header "Data: Hashes (Associative Arrays)"
2414 .SS "How do I process an entire hash?"
2415 .IX Subsection "How do I process an entire hash?"
2416 (contributed by brian d foy)
2417 .PP
2418 There are a couple of ways that you can process an entire hash. You
2419 can get a list of keys, then go through each key, or grab a one
2420 key\-value pair at a time.
2421 .PP
2422 To go through all of the keys, use the \f(CW\*(C`keys\*(C'\fR function. This extracts
2423 all of the keys of the hash and gives them back to you as a list. You
2424 can then get the value through the particular key you\*(Aqre processing:
2425 .PP
2426 .Vb 4
2427 \& foreach my $key ( keys %hash ) {
2428 \& my $value = $hash{$key};
2429 \& ...
2430 \& }
2431 .Ve
2432 .PP
2433 Once you have the list of keys, you can process that list before you
2434 process the hash elements. For instance, you can sort the keys so you
2435 can process them in lexical order:
2436 .PP
2437 .Vb 4
2438 \& foreach my $key ( sort keys %hash ) {
2439 \& my $value = $hash{$key};
2440 \& ...
2441 \& }
2442 .Ve
2443 .PP
2444 Or, you might want to only process some of the items. If you only want
2445 to deal with the keys that start with \f(CW\*(C`text:\*(C'\fR, you can select just
2446 those using \f(CW\*(C`grep\*(C'\fR:
2447 .PP
2448 .Vb 4
2449 \& foreach my $key ( grep /^text:/, keys %hash ) {
2450 \& my $value = $hash{$key};
2451 \& ...
2452 \& }
2453 .Ve
2454 .PP
2455 If the hash is very large, you might not want to create a long list of
2456 keys. To save some memory, you can grab one key\-value pair at a time using
2457 \&\f(CWeach()\fR, which returns a pair you haven\*(Aqt seen yet:
2458 .PP
2459 .Vb 3
2460 \& while( my( $key, $value ) = each( %hash ) ) {
2461 \& ...
2462 \& }
2463 .Ve
2464 .PP
2465 The \f(CW\*(C`each\*(C'\fR operator returns the pairs in apparently random order, so if
2466 ordering matters to you, you\*(Aqll have to stick with the \f(CW\*(C`keys\*(C'\fR method.
2467 .PP
2468 The \f(CWeach()\fR operator can be a bit tricky though. You can\*(Aqt add or
2469 delete keys of the hash while you\*(Aqre using it without possibly
2470 skipping or re\-processing some pairs after Perl internally rehashes
2471 all of the elements. Additionally, a hash has only one iterator, so if
2472 you mix \f(CW\*(C`keys\*(C'\fR, \f(CW\*(C`values\*(C'\fR, or \f(CW\*(C`each\*(C'\fR on the same hash, you risk resetting
2473 the iterator and messing up your processing. See the \f(CW\*(C`each\*(C'\fR entry in
2474 perlfunc for more details.
2475 .SS "How do I merge two hashes?"
2476 .IX Xref "hash merge slice, hash"
2477 .IX Subsection "How do I merge two hashes?"
2478 (contributed by brian d foy)
2479 .PP
2480 Before you decide to merge two hashes, you have to decide what to do
2481 if both hashes contain keys that are the same and if you want to leave
2482 the original hashes as they were.
2483 .PP
2484 If you want to preserve the original hashes, copy one hash (\f(CW%hash1\fR)
2485 to a new hash (\f(CW%new_hash\fR), then add the keys from the other hash
2486 (\f(CW%hash2\fR) to the new hash. Checking that the key already exists in
2487 \&\f(CW%new_hash\fR gives you a chance to decide what to do with the
2488 duplicates:
2489 .PP
2490 .Vb 1
2491 \& my %new_hash = %hash1; # make a copy; leave %hash1 alone
2492 \&
2493 \& foreach my $key2 ( keys %hash2 ) {
2494 \& if( exists $new_hash{$key2} ) {
2495 \& warn "Key [$key2] is in both hashes!";
2496 \& # handle the duplicate (perhaps only warning)
2497 \& ...
2498 \& next;
2499 \& }
2500 \& else {
2501 \& $new_hash{$key2} = $hash2{$key2};
2502 \& }
2503 \& }
2504 .Ve
2505 .PP
2506 If you don\*(Aqt want to create a new hash, you can still use this looping
2507 technique; just change the \f(CW%new_hash\fR to \f(CW%hash1\fR.
2508 .PP
2509 .Vb 11
2510 \& foreach my $key2 ( keys %hash2 ) {
2511 \& if( exists $hash1{$key2} ) {
2512 \& warn "Key [$key2] is in both hashes!";
2513 \& # handle the duplicate (perhaps only warning)
2514 \& ...
2515 \& next;
2516 \& }
2517 \& else {
2518 \& $hash1{$key2} = $hash2{$key2};
2519 \& }
2520 \& }
2521 .Ve
2522 .PP
2523 If you don\*(Aqt care that one hash overwrites keys and values from the other, you
2524 could just use a hash slice to add one hash to another. In this case, values
2525 from \f(CW%hash2\fR replace values from \f(CW%hash1\fR when they have keys in common:
2526 .PP
2527 .Vb 1
2528 \& @hash1{ keys %hash2 } = values %hash2;
2529 .Ve
2530 .SS "What happens if I add or remove keys from a hash while iterating over it?"
2531 .IX Subsection "What happens if I add or remove keys from a hash while iterating over it?"
2532 (contributed by brian d foy)
2533 .PP
2534 The easy answer is "Don\*(Aqt do that!"
2535 .PP
2536 If you iterate through the hash with \fBeach()\fR, you can delete the key
2537 most recently returned without worrying about it. If you delete or add
2538 other keys, the iterator may skip or double up on them since perl
2539 may rearrange the hash table. See the
2540 entry for \f(CWeach()\fR in perlfunc.
2541 .SS "How do I look up a hash element by value?"
2542 .IX Subsection "How do I look up a hash element by value?"
2543 Create a reverse hash:
2544 .PP
2545 .Vb 2
2546 \& my %by_value = reverse %by_key;
2547 \& my $key = $by_value{$value};
2548 .Ve
2549 .PP
2550 That\*(Aqs not particularly efficient. It would be more space\-efficient
2551 to use:
2552 .PP
2553 .Vb 3
2554 \& while (my ($key, $value) = each %by_key) {
2555 \& $by_value{$value} = $key;
2556 \& }
2557 .Ve
2558 .PP
2559 If your hash could have repeated values, the methods above will only find
2560 one of the associated keys. This may or may not worry you. If it does
2561 worry you, you can always reverse the hash into a hash of arrays instead:
2562 .PP
2563 .Vb 3
2564 \& while (my ($key, $value) = each %by_key) {
2565 \& push @{$key_list_by_value{$value}}, $key;
2566 \& }
2567 .Ve
2568 .SS "How can I know how many entries are in a hash?"
2569 .IX Subsection "How can I know how many entries are in a hash?"
2570 (contributed by brian d foy)
2571 .PP
2572 This is very similar to "How do I process an entire hash?", also in
2573 perlfaq4, but a bit simpler in the common cases.
2574 .PP
2575 You can use the \f(CWkeys()\fR built\-in function in scalar context to find out
2576 how many entries you have in a hash:
2577 .PP
2578 .Vb 1
2579 \& my $key_count = keys %hash; # must be scalar context!
2580 .Ve
2581 .PP
2582 If you want to find out how many entries have a defined value, that\*(Aqs
2583 a bit different. You have to check each value. A \f(CW\*(C`grep\*(C'\fR is handy:
2584 .PP
2585 .Vb 1
2586 \& my $defined_value_count = grep { defined } values %hash;
2587 .Ve
2588 .PP
2589 You can use that same structure to count the entries any way that
2590 you like. If you want the count of the keys with vowels in them,
2591 you just test for that instead:
2592 .PP
2593 .Vb 1
2594 \& my $vowel_count = grep { /[aeiou]/ } keys %hash;
2595 .Ve
2596 .PP
2597 The \f(CW\*(C`grep\*(C'\fR in scalar context returns the count. If you want the list
2598 of matching items, just use it in list context instead:
2599 .PP
2600 .Vb 1
2601 \& my @defined_values = grep { defined } values %hash;
2602 .Ve
2603 .PP
2604 The \f(CWkeys()\fR function also resets the iterator, which means that you may
2605 see strange results if you use this between uses of other hash operators
2606 such as \f(CWeach()\fR.
2607 .SS "How do I sort a hash (optionally by value instead of key)?"
2608 .IX Subsection "How do I sort a hash (optionally by value instead of key)?"
2609 (contributed by brian d foy)
2610 .PP
2611 To sort a hash, start with the keys. In this example, we give the list of
2612 keys to the sort function which then compares them as strings. The output list
2613 has the keys in string order. Once we have the keys, we can go through them to
2614 create a report which lists the keys in string order:
2615 .PP
2616 .Vb 1
2617 \& my @keys = sort { $a cmp $b } keys %hash;
2618 \&
2619 \& foreach my $key ( @keys ) {
2620 \& printf "%\-20s %6d\en", $key, $hash{$key};
2621 \& }
2622 .Ve
2623 .PP
2624 We could get more fancy in the \f(CWsort()\fR block though. Instead of
2625 comparing the keys, we can compute a value with them and use that
2626 value as the comparison.
2627 .PP
2628 For instance, to make our report order case\-insensitive, we use
2629 \&\f(CW\*(C`fc\*(C'\fR to safely lowercase the keys before comparing them:
2630 .PP
2631 .Vb 2
2632 \& use v5.16;
2633 \& my @keys = sort { fc($a) cmp fc($b) } keys %hash;
2634 .Ve
2635 .PP
2636 Earlier versions of this answer used \f(CW\*(C`lc\*(C'\fR, but that could give
2637 unexpected results with some Unicode strings. See "fc" in perlfunc
2638 for the details. The Unicode::UCD module does the same thing for
2639 earlier perls.
2640 .PP
2641 Note: if the computation is expensive or the hash has many elements,
2642 you may want to look at the Schwartzian Transform to cache the
2643 computation results.
2644 .PP
2645 If we want to sort by the hash value instead, we use the hash key
2646 to look it up. We still get out a list of keys, but this time they
2647 are ordered by their value:
2648 .PP
2649 .Vb 1
2650 \& my @keys = sort { $hash{$a} <=> $hash{$b} } keys %hash;
2651 .Ve
2652 .PP
2653 From there we can get more complex. If the hash values are the same,
2654 we can provide a secondary sort on the hash key:
2655 .PP
2656 .Vb 6
2657 \& use v5.16;
2658 \& my @keys = sort {
2659 \& $hash{$a} <=> $hash{$b}
2660 \& or
2661 \& fc($a) cmp fc($b)
2662 \& } keys %hash;
2663 .Ve
2664 .SS "How can I always keep my hash sorted?"
2665 .IX Xref "hash tie sort DB_File Tie::IxHash"
2666 .IX Subsection "How can I always keep my hash sorted?"
2667 You can look into using the \f(CW\*(C`DB_File\*(C'\fR module and \f(CWtie()\fR using the
2668 \&\f(CW$DB_BTREE\fR hash bindings as documented in "In Memory
2669 Databases" in DB_File. The Tie::IxHash module from CPAN might also be
2670 instructive. Although this does keep your hash sorted, you might not
2671 like the slowdown you suffer from the tie interface. Are you sure you
2672 need to do this? :)
2673 .SS "What\*(Aqs the difference between ""delete"" and ""undef"" with hashes?"
2674 .IX Subsection "What's the difference between ""delete"" and ""undef"" with hashes?"
2675 Hashes contain pairs of scalars: the first is the key, the
2676 second is the value. The key will be coerced to a string,
2677 although the value can be any kind of scalar: string,
2678 number, or reference. If a key \f(CW$key\fR is present in
2679 \&\f(CW%hash\fR, \f(CWexists($hash{$key})\fR will return true. The value
2680 for a given key can be \f(CW\*(C`undef\*(C'\fR, in which case
2681 \&\f(CW$hash{$key}\fR will be \f(CW\*(C`undef\*(C'\fR while \f(CW\*(C`exists $hash{$key}\*(C'\fR
2682 will return true. This corresponds to (\f(CW$key\fR, \f(CW\*(C`undef\*(C'\fR)
2683 being in the hash.
2684 .PP
2685 Pictures help... Here\*(Aqs the \f(CW%hash\fR table:
2686 .PP
2687 .Vb 7
2688 \& keys values
2689 \& +\-\-\-\-\-\-+\-\-\-\-\-\-+
2690 \& | a | 3 |
2691 \& | x | 7 |
2692 \& | d | 0 |
2693 \& | e | 2 |
2694 \& +\-\-\-\-\-\-+\-\-\-\-\-\-+
2695 .Ve
2696 .PP
2697 And these conditions hold
2698 .PP
2699 .Vb 6
2700 \& $hash{\*(Aqa\*(Aq} is true
2701 \& $hash{\*(Aqd\*(Aq} is false
2702 \& defined $hash{\*(Aqd\*(Aq} is true
2703 \& defined $hash{\*(Aqa\*(Aq} is true
2704 \& exists $hash{\*(Aqa\*(Aq} is true (Perl 5 only)
2705 \& grep ($_ eq \*(Aqa\*(Aq, keys %hash) is true
2706 .Ve
2707 .PP
2708 If you now say
2709 .PP
2710 .Vb 1
2711 \& undef $hash{\*(Aqa\*(Aq}
2712 .Ve
2713 .PP
2714 your table now reads:
2715 .PP
2716 .Vb 7
2717 \& keys values
2718 \& +\-\-\-\-\-\-+\-\-\-\-\-\-+
2719 \& | a | undef|
2720 \& | x | 7 |
2721 \& | d | 0 |
2722 \& | e | 2 |
2723 \& +\-\-\-\-\-\-+\-\-\-\-\-\-+
2724 .Ve
2725 .PP
2726 and these conditions now hold; changes in caps:
2727 .PP
2728 .Vb 6
2729 \& $hash{\*(Aqa\*(Aq} is FALSE
2730 \& $hash{\*(Aqd\*(Aq} is false
2731 \& defined $hash{\*(Aqd\*(Aq} is true
2732 \& defined $hash{\*(Aqa\*(Aq} is FALSE
2733 \& exists $hash{\*(Aqa\*(Aq} is true (Perl 5 only)
2734 \& grep ($_ eq \*(Aqa\*(Aq, keys %hash) is true
2735 .Ve
2736 .PP
2737 Notice the last two: you have an undef value, but a defined key!
2738 .PP
2739 Now, consider this:
2740 .PP
2741 .Vb 1
2742 \& delete $hash{\*(Aqa\*(Aq}
2743 .Ve
2744 .PP
2745 your table now reads:
2746 .PP
2747 .Vb 6
2748 \& keys values
2749 \& +\-\-\-\-\-\-+\-\-\-\-\-\-+
2750 \& | x | 7 |
2751 \& | d | 0 |
2752 \& | e | 2 |
2753 \& +\-\-\-\-\-\-+\-\-\-\-\-\-+
2754 .Ve
2755 .PP
2756 and these conditions now hold; changes in caps:
2757 .PP
2758 .Vb 6
2759 \& $hash{\*(Aqa\*(Aq} is false
2760 \& $hash{\*(Aqd\*(Aq} is false
2761 \& defined $hash{\*(Aqd\*(Aq} is true
2762 \& defined $hash{\*(Aqa\*(Aq} is false
2763 \& exists $hash{\*(Aqa\*(Aq} is FALSE (Perl 5 only)
2764 \& grep ($_ eq \*(Aqa\*(Aq, keys %hash) is FALSE
2765 .Ve
2766 .PP
2767 See, the whole entry is gone!
2768 .SS "Why don\*(Aqt my tied hashes make the defined/exists distinction?"
2769 .IX Subsection "Why don't my tied hashes make the defined/exists distinction?"
2770 This depends on the tied hash\*(Aqs implementation of \fBEXISTS()\fR.
2771 For example, there isn\*(Aqt the concept of undef with hashes
2772 that are tied to DBM* files. It also means that \fBexists()\fR and
2773 \&\fBdefined()\fR do the same thing with a DBM* file, and what they
2774 end up doing is not what they do with ordinary hashes.
2775 .SS "How do I reset an \fBeach()\fP operation part\-way through?"
2776 .IX Subsection "How do I reset an each() operation part-way through?"
2777 (contributed by brian d foy)
2778 .PP
2779 You can use the \f(CW\*(C`keys\*(C'\fR or \f(CW\*(C`values\*(C'\fR functions to reset \f(CW\*(C`each\*(C'\fR. To
2780 simply reset the iterator used by \f(CW\*(C`each\*(C'\fR without doing anything else,
2781 use one of them in void context:
2782 .PP
2783 .Vb 2
2784 \& keys %hash; # resets iterator, nothing else.
2785 \& values %hash; # resets iterator, nothing else.
2786 .Ve
2787 .PP
2788 See the documentation for \f(CW\*(C`each\*(C'\fR in perlfunc.
2789 .SS "How can I get the unique keys from two hashes?"
2790 .IX Subsection "How can I get the unique keys from two hashes?"
2791 First you extract the keys from the hashes into lists, then solve
2792 the "removing duplicates" problem described above. For example:
2793 .PP
2794 .Vb 5
2795 \& my %seen = ();
2796 \& for my $element (keys(%foo), keys(%bar)) {
2797 \& $seen{$element}++;
2798 \& }
2799 \& my @uniq = keys %seen;
2800 .Ve
2801 .PP
2802 Or more succinctly:
2803 .PP
2804 .Vb 1
2805 \& my @uniq = keys %{{%foo,%bar}};
2806 .Ve
2807 .PP
2808 Or if you really want to save space:
2809 .PP
2810 .Vb 8
2811 \& my %seen = ();
2812 \& while (defined ($key = each %foo)) {
2813 \& $seen{$key}++;
2814 \& }
2815 \& while (defined ($key = each %bar)) {
2816 \& $seen{$key}++;
2817 \& }
2818 \& my @uniq = keys %seen;
2819 .Ve
2820 .SS "How can I store a multidimensional array in a DBM file?"
2821 .IX Subsection "How can I store a multidimensional array in a DBM file?"
2822 Either stringify the structure yourself (no fun), or else
2823 get the MLDBM (which uses Data::Dumper) module from CPAN and layer
2824 it on top of either DB_File or GDBM_File. You might also try DBM::Deep, but
2825 it can be a bit slow.
2826 .SS "How can I make my hash remember the order I put elements into it?"
2827 .IX Subsection "How can I make my hash remember the order I put elements into it?"
2828 Use the Tie::IxHash from CPAN.
2829 .PP
2830 .Vb 1
2831 \& use Tie::IxHash;
2832 \&
2833 \& tie my %myhash, \*(AqTie::IxHash\*(Aq;
2834 \&
2835 \& for (my $i=0; $i<20; $i++) {
2836 \& $myhash{$i} = 2*$i;
2837 \& }
2838 \&
2839 \& my @keys = keys %myhash;
2840 \& # @keys = (0,1,2,3,...)
2841 .Ve
2842 .SS "Why does passing a subroutine an undefined element in a hash create it?"
2843 .IX Subsection "Why does passing a subroutine an undefined element in a hash create it?"
2844 (contributed by brian d foy)
2845 .PP
2846 Are you using a really old version of Perl?
2847 .PP
2848 Normally, accessing a hash key\*(Aqs value for a nonexistent key will
2849 \&\fInot\fR create the key.
2850 .PP
2851 .Vb 3
2852 \& my %hash = ();
2853 \& my $value = $hash{ \*(Aqfoo\*(Aq };
2854 \& print "This won\*(Aqt print\en" if exists $hash{ \*(Aqfoo\*(Aq };
2855 .Ve
2856 .PP
2857 Passing \f(CW$hash{ \*(Aqfoo\*(Aq }\fR to a subroutine used to be a special case, though.
2858 Since you could assign directly to \f(CW$_[0]\fR, Perl had to be ready to
2859 make that assignment so it created the hash key ahead of time:
2860 .PP
2861 .Vb 2
2862 \& my_sub( $hash{ \*(Aqfoo\*(Aq } );
2863 \& print "This will print before 5.004\en" if exists $hash{ \*(Aqfoo\*(Aq };
2864 \&
2865 \& sub my_sub {
2866 \& # $_[0] = \*(Aqbar\*(Aq; # create hash key in case you do this
2867 \& 1;
2868 \& }
2869 .Ve
2870 .PP
2871 Since Perl 5.004, however, this situation is a special case and Perl
2872 creates the hash key only when you make the assignment:
2873 .PP
2874 .Vb 2
2875 \& my_sub( $hash{ \*(Aqfoo\*(Aq } );
2876 \& print "This will print, even after 5.004\en" if exists $hash{ \*(Aqfoo\*(Aq };
2877 \&
2878 \& sub my_sub {
2879 \& $_[0] = \*(Aqbar\*(Aq;
2880 \& }
2881 .Ve
2882 .PP
2883 However, if you want the old behavior (and think carefully about that
2884 because it\*(Aqs a weird side effect), you can pass a hash slice instead.
2885 Perl 5.004 didn\*(Aqt make this a special case:
2886 .PP
2887 .Vb 1
2888 \& my_sub( @hash{ qw/foo/ } );
2889 .Ve
2890 .SS "How can I make the Perl equivalent of a C structure/C++ class/hash or array of hashes or arrays?"
2891 .IX Subsection "How can I make the Perl equivalent of a C structure/C++ class/hash or array of hashes or arrays?"
2892 Usually a hash ref, perhaps like this:
2893 .PP
2894 .Vb 8
2895 \& $record = {
2896 \& NAME => "Jason",
2897 \& EMPNO => 132,
2898 \& TITLE => "deputy peon",
2899 \& AGE => 23,
2900 \& SALARY => 37_000,
2901 \& PALS => [ "Norbert", "Rhys", "Phineas"],
2902 \& };
2903 .Ve
2904 .PP
2905 References are documented in perlref and perlreftut.
2906 Examples of complex data structures are given in perldsc and
2907 perllol. Examples of structures and object\-oriented classes are
2908 in perlootut.
2909 .SS "How can I use a reference as a hash key?"
2910 .IX Subsection "How can I use a reference as a hash key?"
2911 (contributed by brian d foy and Ben Morrow)
2912 .PP
2913 Hash keys are strings, so you can\*(Aqt really use a reference as the key.
2914 When you try to do that, perl turns the reference into its stringified
2915 form (for instance, \f(CWHASH(0xDEADBEEF)\fR). From there you can\*(Aqt get
2916 back the reference from the stringified form, at least without doing
2917 some extra work on your own.
2918 .PP
2919 Remember that the entry in the hash will still be there even if
2920 the referenced variable goes out of scope, and that it is entirely
2921 possible for Perl to subsequently allocate a different variable at
2922 the same address. This will mean a new variable might accidentally
2923 be associated with the value for an old.
2924 .PP
2925 If you have Perl 5.10 or later, and you just want to store a value
2926 against the reference for lookup later, you can use the core
2927 Hash::Util::Fieldhash module. This will also handle renaming the
2928 keys if you use multiple threads (which causes all variables to be
2929 reallocated at new addresses, changing their stringification), and
2930 garbage\-collecting the entries when the referenced variable goes out
2931 of scope.
2932 .PP
2933 If you actually need to be able to get a real reference back from
2934 each hash entry, you can use the Tie::RefHash module, which does the
2935 required work for you.
2936 .SS "How can I check if a key exists in a multilevel hash?"
2937 .IX Subsection "How can I check if a key exists in a multilevel hash?"
2938 (contributed by brian d foy)
2939 .PP
2940 The trick to this problem is avoiding accidental autovivification. If
2941 you want to check three keys deep, you might naïvely try this:
2942 .PP
2943 .Vb 4
2944 \& my %hash;
2945 \& if( exists $hash{key1}{key2}{key3} ) {
2946 \& ...;
2947 \& }
2948 .Ve
2949 .PP
2950 Even though you started with a completely empty hash, after that call to
2951 \&\f(CW\*(C`exists\*(C'\fR you\*(Aqve created the structure you needed to check for \f(CW\*(C`key3\*(C'\fR:
2952 .PP
2953 .Vb 5
2954 \& %hash = (
2955 \& \*(Aqkey1\*(Aq => {
2956 \& \*(Aqkey2\*(Aq => {}
2957 \& }
2958 \& );
2959 .Ve
2960 .PP
2961 That\*(Aqs autovivification. You can get around this in a few ways. The
2962 easiest way is to just turn it off. The lexical \f(CW\*(C`autovivification\*(C'\fR
2963 pragma is available on CPAN. Now you don\*(Aqt add to the hash:
2964 .PP
2965 .Vb 7
2966 \& {
2967 \& no autovivification;
2968 \& my %hash;
2969 \& if( exists $hash{key1}{key2}{key3} ) {
2970 \& ...;
2971 \& }
2972 \& }
2973 .Ve
2974 .PP
2975 The Data::Diver module on CPAN can do it for you too. Its \f(CW\*(C`Dive\*(C'\fR
2976 subroutine can tell you not only if the keys exist but also get the
2977 value:
2978 .PP
2979 .Vb 1
2980 \& use Data::Diver qw(Dive);
2981 \&
2982 \& my @exists = Dive( \e%hash, qw(key1 key2 key3) );
2983 \& if( ! @exists ) {
2984 \& ...; # keys do not exist
2985 \& }
2986 \& elsif( ! defined $exists[0] ) {
2987 \& ...; # keys exist but value is undef
2988 \& }
2989 .Ve
2990 .PP
2991 You can easily do this yourself too by checking each level of the hash
2992 before you move onto the next level. This is essentially what
2993 Data::Diver does for you:
2994 .PP
2995 .Vb 3
2996 \& if( check_hash( \e%hash, qw(key1 key2 key3) ) ) {
2997 \& ...;
2998 \& }
2999 \&
3000 \& sub check_hash {
3001 \& my( $hash, @keys ) = @_;
3002 \&
3003 \& return unless @keys;
3004 \&
3005 \& foreach my $key ( @keys ) {
3006 \& return unless eval { exists $hash\->{$key} };
3007 \& $hash = $hash\->{$key};
3008 \& }
3009 \&
3010 \& return 1;
3011 \& }
3012 .Ve
3013 .SS "How can I prevent addition of unwanted keys into a hash?"
3014 .IX Subsection "How can I prevent addition of unwanted keys into a hash?"
3015 Since version 5.8.0, hashes can be \fIrestricted\fR to a fixed number
3016 of given keys. Methods for creating and dealing with restricted hashes
3017 are exported by the Hash::Util module.
3018 .SH "Data: Misc"
3019 .IX Header "Data: Misc"
3020 .SS "How do I handle binary data correctly?"
3021 .IX Subsection "How do I handle binary data correctly?"
3022 Perl is binary\-clean, so it can handle binary data just fine.
3023 On Windows or DOS, however, you have to use \f(CW\*(C`binmode\*(C'\fR for binary
3024 files to avoid conversions for line endings. In general, you should
3025 use \f(CW\*(C`binmode\*(C'\fR any time you want to work with binary data.
3026 .PP
3027 Also see "binmode" in perlfunc or perlopentut.
3028 .PP
3029 If you\*(Aqre concerned about 8\-bit textual data then see perllocale.
3030 If you want to deal with multibyte characters, however, there are
3031 some gotchas. See the section on Regular Expressions.
3032 .SS "How do I determine whether a scalar is a number/whole/integer/float?"
3033 .IX Subsection "How do I determine whether a scalar is a number/whole/integer/float?"
3034 Assuming that you don\*(Aqt care about IEEE notations like "NaN" or
3035 "Infinity", you probably just want to use a regular expression (see also
3036 perlretut and perlre):
3037 .PP
3038 .Vb 1
3039 \& use 5.010;
3040 \&
3041 \& if ( /\eD/ )
3042 \& { say "\ethas nondigits"; }
3043 \& if ( /^\ed+\ez/ )
3044 \& { say "\etis a whole number"; }
3045 \& if ( /^\-?\ed+\ez/ )
3046 \& { say "\etis an integer"; }
3047 \& if ( /^[+\-]?\ed+\ez/ )
3048 \& { say "\etis a +/\- integer"; }
3049 \& if ( /^\-?(?:\ed+\e.?|\e.\ed)\ed*\ez/ )
3050 \& { say "\etis a real number"; }
3051 \& if ( /^[+\-]?(?=\e.?\ed)\ed*\e.?\ed*(?:e[+\-]?\ed+)?\ez/i )
3052 \& { say "\etis a C float" }
3053 .Ve
3054 .PP
3055 There are also some commonly used modules for the task.
3056 Scalar::Util (distributed with 5.8) provides access to perl\*(Aqs
3057 internal function \f(CW\*(C`looks_like_number\*(C'\fR for determining whether a
3058 variable looks like a number. Data::Types exports functions that
3059 validate data types using both the above and other regular
3060 expressions. Thirdly, there is Regexp::Common which has regular
3061 expressions to match various types of numbers. Those three modules are
3062 available from the CPAN.
3063 .PP
3064 If you\*(Aqre on a POSIX system, Perl supports the \f(CW\*(C`POSIX::strtod\*(C'\fR
3065 function for converting strings to doubles (and also \f(CW\*(C`POSIX::strtol\*(C'\fR
3066 for longs). Its semantics are somewhat cumbersome, so here\*(Aqs a
3067 \&\f(CW\*(C`getnum\*(C'\fR wrapper function for more convenient access. This function
3068 takes a string and returns the number it found, or \f(CW\*(C`undef\*(C'\fR for input
3069 that isn\*(Aqt a C float. The \f(CW\*(C`is_numeric\*(C'\fR function is a front end to
3070 \&\f(CW\*(C`getnum\*(C'\fR if you just want to say, "Is this a float?"
3071 .PP
3072 .Vb 10
3073 \& sub getnum {
3074 \& use POSIX qw(strtod);
3075 \& my $str = shift;
3076 \& $str =~ s/^\es+//;
3077 \& $str =~ s/\es+$//;
3078 \& $! = 0;
3079 \& my($num, $unparsed) = strtod($str);
3080 \& if (($str eq \*(Aq\*(Aq) || ($unparsed != 0) || $!) {
3081 \& return undef;
3082 \& }
3083 \& else {
3084 \& return $num;
3085 \& }
3086 \& }
3087 \&
3088 \& sub is_numeric { defined getnum($_[0]) }
3089 .Ve
3090 .PP
3091 Or you could check out the String::Scanf module on the CPAN
3092 instead.
3093 .SS "How do I keep persistent data across program calls?"
3094 .IX Subsection "How do I keep persistent data across program calls?"
3095 For some specific applications, you can use one of the DBM modules.
3096 See AnyDBM_File. More generically, you should consult the FreezeThaw
3097 or Storable modules from CPAN. Starting from Perl 5.8, Storable is part
3098 of the standard distribution. Here\*(Aqs one example using Storable\*(Aqs \f(CW\*(C`store\*(C'\fR
3099 and \f(CW\*(C`retrieve\*(C'\fR functions:
3100 .PP
3101 .Vb 2
3102 \& use Storable;
3103 \& store(\e%hash, "filename");
3104 \&
3105 \& # later on...
3106 \& $href = retrieve("filename"); # by ref
3107 \& %hash = %{ retrieve("filename") }; # direct to hash
3108 .Ve
3109 .SS "How do I print out or copy a recursive data structure?"
3110 .IX Subsection "How do I print out or copy a recursive data structure?"
3111 The Data::Dumper module on CPAN (or the 5.005 release of Perl) is great
3112 for printing out data structures. The Storable module on CPAN (or the
3113 5.8 release of Perl), provides a function called \f(CW\*(C`dclone\*(C'\fR that recursively
3114 copies its argument.
3115 .PP
3116 .Vb 2
3117 \& use Storable qw(dclone);
3118 \& $r2 = dclone($r1);
3119 .Ve
3120 .PP
3121 Where \f(CW$r1\fR can be a reference to any kind of data structure you\*(Aqd like.
3122 It will be deeply copied. Because \f(CW\*(C`dclone\*(C'\fR takes and returns references,
3123 you\*(Aqd have to add extra punctuation if you had a hash of arrays that
3124 you wanted to copy.
3125 .PP
3126 .Vb 1
3127 \& %newhash = %{ dclone(\e%oldhash) };
3128 .Ve
3129 .SS "How do I define methods for every class/object?"
3130 .IX Subsection "How do I define methods for every class/object?"
3131 (contributed by Ben Morrow)
3132 .PP
3133 You can use the \f(CW\*(C`UNIVERSAL\*(C'\fR class (see UNIVERSAL). However, please
3134 be very careful to consider the consequences of doing this: adding
3135 methods to every object is very likely to have unintended
3136 consequences. If possible, it would be better to have all your objects
3137 inherit from some common base class, or to use an object system like
3138 Moose that supports roles.
3139 .SS "How do I verify a credit card checksum?"
3140 .IX Subsection "How do I verify a credit card checksum?"
3141 Get the Business::CreditCard module from CPAN.
3142 .SS "How do I pack arrays of doubles or floats for XS code?"
3143 .IX Subsection "How do I pack arrays of doubles or floats for XS code?"
3144 The arrays.h/arrays.c code in the PGPLOT module on CPAN does just this.
3145 If you\*(Aqre doing a lot of float or double processing, consider using
3146 the PDL module from CPAN instead\-\-it makes number\-crunching easy.
3147 .PP
3148 See <https://metacpan.org/release/PGPLOT> for the code.
3149 .SH "AUTHOR AND COPYRIGHT"
3150 .IX Header "AUTHOR AND COPYRIGHT"
3151 Copyright (c) 1997\-2010 Tom Christiansen, Nathan Torkington, and
3152 other authors as noted. All rights reserved.
3153 .PP
3154 This documentation is free; you can redistribute it and/or modify it
3155 under the same terms as Perl itself.
3156 .PP
3157 Irrespective of its distribution, all code examples in this file
3158 are hereby placed into the public domain. You are permitted and
3159 encouraged to use this code in your own programs for fun
3160 or for profit as you see fit. A simple comment in the code giving
3161 credit would be courteous but is not required.