Removal of a bunch of changes that don't merit perldelta integration
[perl.git] / pod / perlfaq4.pod
1 =head1 NAME
2
3 perlfaq4 - Data Manipulation
4
5 =head1 DESCRIPTION
6
7 This section of the FAQ answers questions related to manipulating
8 numbers, dates, strings, arrays, hashes, and miscellaneous data issues.
9
10 =head1 Data: Numbers
11
12 =head2 Why am I getting long decimals (eg, 19.9499999999999) instead of the numbers I should be getting (eg, 19.95)?
13
14 Internally, your computer represents floating-point numbers in binary.
15 Digital (as in powers of two) computers cannot store all numbers
16 exactly.  Some real numbers lose precision in the process.  This is a
17 problem with how computers store numbers and affects all computer
18 languages, not just Perl.
19
20 L<perlnumber> shows the gory details of number representations and
21 conversions.
22
23 To limit the number of decimal places in your numbers, you can use the
24 printf or sprintf function.  See the L<"Floating Point
25 Arithmetic"|perlop> for more details.
26
27         printf "%.2f", 10/3;
28
29         my $number = sprintf "%.2f", 10/3;
30
31 =head2 Why is int() broken?
32
33 Your C<int()> is most probably working just fine.  It's the numbers that
34 aren't quite what you think.
35
36 First, see the answer to "Why am I getting long decimals
37 (eg, 19.9499999999999) instead of the numbers I should be getting
38 (eg, 19.95)?".
39
40 For example, this
41
42         print int(0.6/0.2-2), "\n";
43
44 will in most computers print 0, not 1, because even such simple
45 numbers as 0.6 and 0.2 cannot be presented exactly by floating-point
46 numbers.  What you think in the above as 'three' is really more like
47 2.9999999999999995559.
48
49 =head2 Why isn't my octal data interpreted correctly?
50
51 (contributed by brian d foy)
52
53 You're probably trying to convert a string to a number, which Perl only
54 converts as a decimal number. When Perl converts a string to a number, it
55 ignores leading spaces and zeroes, then assumes the rest of the digits
56 are in base 10:
57
58         my $string = '0644';
59
60         print $string + 0;  # prints 644
61
62         print $string + 44; # prints 688, certainly not octal!
63
64 This problem usually involves one of the Perl built-ins that has the
65 same name a unix command that uses octal numbers as arguments on the
66 command line. In this example, C<chmod> on the command line knows that
67 its first argument is octal because that's what it does:
68
69         %prompt> chmod 644 file
70
71 If you want to use the same literal digits (644) in Perl, you have to tell
72 Perl to treat them as octal numbers either by prefixing the digits with
73 a C<0> or using C<oct>:
74
75         chmod(     0644, $file);   # right, has leading zero
76         chmod( oct(644), $file );  # also correct
77
78 The problem comes in when you take your numbers from something that Perl
79 thinks is a string, such as a command line argument in C<@ARGV>:
80
81         chmod( $ARGV[0],      $file);   # wrong, even if "0644"
82
83         chmod( oct($ARGV[0]), $file );  # correct, treat string as octal
84
85 You can always check the value you're using by printing it in octal
86 notation to ensure it matches what you think it should be. Print it
87 in octal  and decimal format:
88
89         printf "0%o %d", $number, $number;
90
91 =head2 Does Perl have a round() function?  What about ceil() and floor()?  Trig functions?
92
93 Remember that C<int()> merely truncates toward 0.  For rounding to a
94 certain number of digits, C<sprintf()> or C<printf()> is usually the
95 easiest route.
96
97         printf("%.3f", 3.1415926535);   # prints 3.142
98
99 The C<POSIX> module (part of the standard Perl distribution)
100 implements C<ceil()>, C<floor()>, and a number of other mathematical
101 and trigonometric functions.
102
103         use POSIX;
104         $ceil   = ceil(3.5);   # 4
105         $floor  = floor(3.5);  # 3
106
107 In 5.000 to 5.003 perls, trigonometry was done in the C<Math::Complex>
108 module.  With 5.004, the C<Math::Trig> module (part of the standard Perl
109 distribution) implements the trigonometric functions. Internally it
110 uses the C<Math::Complex> module and some functions can break out from
111 the real axis into the complex plane, for example the inverse sine of
112 2.
113
114 Rounding in financial applications can have serious implications, and
115 the rounding method used should be specified precisely.  In these
116 cases, it probably pays not to trust whichever system rounding is
117 being used by Perl, but to instead implement the rounding function you
118 need yourself.
119
120 To see why, notice how you'll still have an issue on half-way-point
121 alternation:
122
123         for ($i = 0; $i < 1.01; $i += 0.05) { printf "%.1f ",$i}
124
125         0.0 0.1 0.1 0.2 0.2 0.2 0.3 0.3 0.4 0.4 0.5 0.5 0.6 0.7 0.7
126         0.8 0.8 0.9 0.9 1.0 1.0
127
128 Don't blame Perl.  It's the same as in C.  IEEE says we have to do
129 this. Perl numbers whose absolute values are integers under 2**31 (on
130 32 bit machines) will work pretty much like mathematical integers.
131 Other numbers are not guaranteed.
132
133 =head2 How do I convert between numeric representations/bases/radixes?
134
135 As always with Perl there is more than one way to do it.  Below are a
136 few examples of approaches to making common conversions between number
137 representations.  This is intended to be representational rather than
138 exhaustive.
139
140 Some of the examples later in L<perlfaq4> use the C<Bit::Vector>
141 module from CPAN. The reason you might choose C<Bit::Vector> over the
142 perl built in functions is that it works with numbers of ANY size,
143 that it is optimized for speed on some operations, and for at least
144 some programmers the notation might be familiar.
145
146 =over 4
147
148 =item How do I convert hexadecimal into decimal
149
150 Using perl's built in conversion of C<0x> notation:
151
152         $dec = 0xDEADBEEF;
153
154 Using the C<hex> function:
155
156         $dec = hex("DEADBEEF");
157
158 Using C<pack>:
159
160         $dec = unpack("N", pack("H8", substr("0" x 8 . "DEADBEEF", -8)));
161
162 Using the CPAN module C<Bit::Vector>:
163
164         use Bit::Vector;
165         $vec = Bit::Vector->new_Hex(32, "DEADBEEF");
166         $dec = $vec->to_Dec();
167
168 =item How do I convert from decimal to hexadecimal
169
170 Using C<sprintf>:
171
172         $hex = sprintf("%X", 3735928559); # upper case A-F
173         $hex = sprintf("%x", 3735928559); # lower case a-f
174
175 Using C<unpack>:
176
177         $hex = unpack("H*", pack("N", 3735928559));
178
179 Using C<Bit::Vector>:
180
181         use Bit::Vector;
182         $vec = Bit::Vector->new_Dec(32, -559038737);
183         $hex = $vec->to_Hex();
184
185 And C<Bit::Vector> supports odd bit counts:
186
187         use Bit::Vector;
188         $vec = Bit::Vector->new_Dec(33, 3735928559);
189         $vec->Resize(32); # suppress leading 0 if unwanted
190         $hex = $vec->to_Hex();
191
192 =item How do I convert from octal to decimal
193
194 Using Perl's built in conversion of numbers with leading zeros:
195
196         $dec = 033653337357; # note the leading 0!
197
198 Using the C<oct> function:
199
200         $dec = oct("33653337357");
201
202 Using C<Bit::Vector>:
203
204         use Bit::Vector;
205         $vec = Bit::Vector->new(32);
206         $vec->Chunk_List_Store(3, split(//, reverse "33653337357"));
207         $dec = $vec->to_Dec();
208
209 =item How do I convert from decimal to octal
210
211 Using C<sprintf>:
212
213         $oct = sprintf("%o", 3735928559);
214
215 Using C<Bit::Vector>:
216
217         use Bit::Vector;
218         $vec = Bit::Vector->new_Dec(32, -559038737);
219         $oct = reverse join('', $vec->Chunk_List_Read(3));
220
221 =item How do I convert from binary to decimal
222
223 Perl 5.6 lets you write binary numbers directly with
224 the C<0b> notation:
225
226         $number = 0b10110110;
227
228 Using C<oct>:
229
230         my $input = "10110110";
231         $decimal = oct( "0b$input" );
232
233 Using C<pack> and C<ord>:
234
235         $decimal = ord(pack('B8', '10110110'));
236
237 Using C<pack> and C<unpack> for larger strings:
238
239         $int = unpack("N", pack("B32",
240         substr("0" x 32 . "11110101011011011111011101111", -32)));
241         $dec = sprintf("%d", $int);
242
243         # substr() is used to left pad a 32 character string with zeros.
244
245 Using C<Bit::Vector>:
246
247         $vec = Bit::Vector->new_Bin(32, "11011110101011011011111011101111");
248         $dec = $vec->to_Dec();
249
250 =item How do I convert from decimal to binary
251
252 Using C<sprintf> (perl 5.6+):
253
254         $bin = sprintf("%b", 3735928559);
255
256 Using C<unpack>:
257
258         $bin = unpack("B*", pack("N", 3735928559));
259
260 Using C<Bit::Vector>:
261
262         use Bit::Vector;
263         $vec = Bit::Vector->new_Dec(32, -559038737);
264         $bin = $vec->to_Bin();
265
266 The remaining transformations (e.g. hex -> oct, bin -> hex, etc.)
267 are left as an exercise to the inclined reader.
268
269 =back
270
271 =head2 Why doesn't & work the way I want it to?
272
273 The behavior of binary arithmetic operators depends on whether they're
274 used on numbers or strings.  The operators treat a string as a series
275 of bits and work with that (the string C<"3"> is the bit pattern
276 C<00110011>).  The operators work with the binary form of a number
277 (the number C<3> is treated as the bit pattern C<00000011>).
278
279 So, saying C<11 & 3> performs the "and" operation on numbers (yielding
280 C<3>).  Saying C<"11" & "3"> performs the "and" operation on strings
281 (yielding C<"1">).
282
283 Most problems with C<&> and C<|> arise because the programmer thinks
284 they have a number but really it's a string.  The rest arise because
285 the programmer says:
286
287         if ("\020\020" & "\101\101") {
288                 # ...
289                 }
290
291 but a string consisting of two null bytes (the result of C<"\020\020"
292 & "\101\101">) is not a false value in Perl.  You need:
293
294         if ( ("\020\020" & "\101\101") !~ /[^\000]/) {
295                 # ...
296                 }
297
298 =head2 How do I multiply matrices?
299
300 Use the Math::Matrix or Math::MatrixReal modules (available from CPAN)
301 or the PDL extension (also available from CPAN).
302
303 =head2 How do I perform an operation on a series of integers?
304
305 To call a function on each element in an array, and collect the
306 results, use:
307
308         @results = map { my_func($_) } @array;
309
310 For example:
311
312         @triple = map { 3 * $_ } @single;
313
314 To call a function on each element of an array, but ignore the
315 results:
316
317         foreach $iterator (@array) {
318                 some_func($iterator);
319                 }
320
321 To call a function on each integer in a (small) range, you B<can> use:
322
323         @results = map { some_func($_) } (5 .. 25);
324
325 but you should be aware that the C<..> operator creates an array of
326 all integers in the range.  This can take a lot of memory for large
327 ranges.  Instead use:
328
329         @results = ();
330         for ($i=5; $i < 500_005; $i++) {
331                 push(@results, some_func($i));
332                 }
333
334 This situation has been fixed in Perl5.005. Use of C<..> in a C<for>
335 loop will iterate over the range, without creating the entire range.
336
337         for my $i (5 .. 500_005) {
338                 push(@results, some_func($i));
339                 }
340
341 will not create a list of 500,000 integers.
342
343 =head2 How can I output Roman numerals?
344
345 Get the http://www.cpan.org/modules/by-module/Roman module.
346
347 =head2 Why aren't my random numbers random?
348
349 If you're using a version of Perl before 5.004, you must call C<srand>
350 once at the start of your program to seed the random number generator.
351
352          BEGIN { srand() if $] < 5.004 }
353
354 5.004 and later automatically call C<srand> at the beginning.  Don't
355 call C<srand> more than once--you make your numbers less random,
356 rather than more.
357
358 Computers are good at being predictable and bad at being random
359 (despite appearances caused by bugs in your programs :-).  see the
360 F<random> article in the "Far More Than You Ever Wanted To Know"
361 collection in http://www.cpan.org/misc/olddoc/FMTEYEWTK.tgz , courtesy
362 of Tom Phoenix, talks more about this.  John von Neumann said, "Anyone
363 who attempts to generate random numbers by deterministic means is, of
364 course, living in a state of sin."
365
366 If you want numbers that are more random than C<rand> with C<srand>
367 provides, you should also check out the C<Math::TrulyRandom> module from
368 CPAN.  It uses the imperfections in your system's timer to generate
369 random numbers, but this takes quite a while.  If you want a better
370 pseudorandom generator than comes with your operating system, look at
371 "Numerical Recipes in C" at http://www.nr.com/ .
372
373 =head2 How do I get a random number between X and Y?
374
375 To get a random number between two values, you can use the C<rand()>
376 built-in to get a random number between 0 and 1. From there, you shift
377 that into the range that you want.
378
379 C<rand($x)> returns a number such that C<< 0 <= rand($x) < $x >>. Thus
380 what you want to have perl figure out is a random number in the range
381 from 0 to the difference between your I<X> and I<Y>.
382
383 That is, to get a number between 10 and 15, inclusive, you want a
384 random number between 0 and 5 that you can then add to 10.
385
386         my $number = 10 + int rand( 15-10+1 ); # ( 10,11,12,13,14, or 15 )
387
388 Hence you derive the following simple function to abstract
389 that. It selects a random integer between the two given
390 integers (inclusive), For example: C<random_int_between(50,120)>.
391
392         sub random_int_between {
393                 my($min, $max) = @_;
394                 # Assumes that the two arguments are integers themselves!
395                 return $min if $min == $max;
396                 ($min, $max) = ($max, $min)  if  $min > $max;
397                 return $min + int rand(1 + $max - $min);
398                 }
399
400 =head1 Data: Dates
401
402 =head2 How do I find the day or week of the year?
403
404 The localtime function returns the day of the year.  Without an
405 argument localtime uses the current time.
406
407         $day_of_year = (localtime)[7];
408
409 The C<POSIX> module can also format a date as the day of the year or
410 week of the year.
411
412         use POSIX qw/strftime/;
413         my $day_of_year  = strftime "%j", localtime;
414         my $week_of_year = strftime "%W", localtime;
415
416 To get the day of year for any date, use C<POSIX>'s C<mktime> to get
417 a time in epoch seconds for the argument to localtime.
418
419         use POSIX qw/mktime strftime/;
420         my $week_of_year = strftime "%W",
421                 localtime( mktime( 0, 0, 0, 18, 11, 87 ) );
422
423 The C<Date::Calc> module provides two functions to calculate these.
424
425         use Date::Calc;
426         my $day_of_year  = Day_of_Year(  1987, 12, 18 );
427         my $week_of_year = Week_of_Year( 1987, 12, 18 );
428
429 =head2 How do I find the current century or millennium?
430
431 Use the following simple functions:
432
433         sub get_century    {
434                 return int((((localtime(shift || time))[5] + 1999))/100);
435                 }
436
437         sub get_millennium {
438                 return 1+int((((localtime(shift || time))[5] + 1899))/1000);
439                 }
440
441 On some systems, the C<POSIX> module's C<strftime()> function has been
442 extended in a non-standard way to use a C<%C> format, which they
443 sometimes claim is the "century". It isn't, because on most such
444 systems, this is only the first two digits of the four-digit year, and
445 thus cannot be used to reliably determine the current century or
446 millennium.
447
448 =head2 How can I compare two dates and find the difference?
449
450 (contributed by brian d foy)
451
452 You could just store all your dates as a number and then subtract.
453 Life isn't always that simple though. If you want to work with
454 formatted dates, the C<Date::Manip>, C<Date::Calc>, or C<DateTime>
455 modules can help you.
456
457 =head2 How can I take a string and turn it into epoch seconds?
458
459 If it's a regular enough string that it always has the same format,
460 you can split it up and pass the parts to C<timelocal> in the standard
461 C<Time::Local> module.  Otherwise, you should look into the C<Date::Calc>
462 and C<Date::Manip> modules from CPAN.
463
464 =head2 How can I find the Julian Day?
465
466 (contributed by brian d foy and Dave Cross)
467
468 You can use the C<Time::JulianDay> module available on CPAN.  Ensure
469 that you really want to find a Julian day, though, as many people have
470 different ideas about Julian days.  See
471 http://www.hermetic.ch/cal_stud/jdn.htm for instance.
472
473 You can also try the C<DateTime> module, which can convert a date/time
474 to a Julian Day.
475
476         $ perl -MDateTime -le'print DateTime->today->jd'
477         2453401.5
478
479 Or the modified Julian Day
480
481         $ perl -MDateTime -le'print DateTime->today->mjd'
482         53401
483
484 Or even the day of the year (which is what some people think of as a
485 Julian day)
486
487         $ perl -MDateTime -le'print DateTime->today->doy'
488         31
489
490 =head2 How do I find yesterday's date?
491 X<date> X<yesterday> X<DateTime> X<Date::Calc> X<Time::Local>
492 X<daylight saving time> X<day> X<Today_and_Now> X<localtime>
493 X<timelocal>
494
495 (contributed by brian d foy)
496
497 Use one of the Date modules. The C<DateTime> module makes it simple, and
498 give you the same time of day, only the day before.
499
500         use DateTime;
501
502         my $yesterday = DateTime->now->subtract( days => 1 );
503
504         print "Yesterday was $yesterday\n";
505
506 You can also use the C<Date::Calc> module using its C<Today_and_Now>
507 function.
508
509         use Date::Calc qw( Today_and_Now Add_Delta_DHMS );
510
511         my @date_time = Add_Delta_DHMS( Today_and_Now(), -1, 0, 0, 0 );
512
513         print "@date_time\n";
514
515 Most people try to use the time rather than the calendar to figure out
516 dates, but that assumes that days are twenty-four hours each.  For
517 most people, there are two days a year when they aren't: the switch to
518 and from summer time throws this off. Let the modules do the work.
519
520 If you absolutely must do it yourself (or can't use one of the
521 modules), here's a solution using C<Time::Local>, which comes with
522 Perl:
523
524         # contributed by Gunnar Hjalmarsson
525          use Time::Local;
526          my $today = timelocal 0, 0, 12, ( localtime )[3..5];
527          my ($d, $m, $y) = ( localtime $today-86400 )[3..5];
528          printf "Yesterday: %d-%02d-%02d\n", $y+1900, $m+1, $d;
529
530 In this case, you measure the day starting at noon, and subtract 24
531 hours. Even if the length of the calendar day is 23 or 25 hours,
532 you'll still end up on the previous calendar day, although not at
533 noon. Since you don't care about the time, the one hour difference
534 doesn't matter and you end up with the previous date.
535
536 =head2 Does Perl have a Year 2000 problem? Is Perl Y2K compliant?
537
538 Short answer: No, Perl does not have a Year 2000 problem.  Yes, Perl is
539 Y2K compliant (whatever that means). The programmers you've hired to
540 use it, however, probably are not.
541
542 Long answer: The question belies a true understanding of the issue.
543 Perl is just as Y2K compliant as your pencil--no more, and no less.
544 Can you use your pencil to write a non-Y2K-compliant memo?  Of course
545 you can.  Is that the pencil's fault?  Of course it isn't.
546
547 The date and time functions supplied with Perl (gmtime and localtime)
548 supply adequate information to determine the year well beyond 2000 and
549 2038.  The year returned by these functions when used in a list
550 context is the year minus 1900.  For years between 1910 and 1999 this
551 I<happens> to be a 2-digit decimal number. To avoid the year 2000
552 problem simply do not treat the year as a 2-digit number.  It isn't.
553
554 When gmtime() and localtime() are used in scalar context they return
555 a timestamp string that contains a fully-expanded year.  For example,
556 C<$timestamp = gmtime(1005613200)> sets $timestamp to "Tue Nov 13 01:00:00
557 2001".  There's no year 2000 problem here.
558
559 That doesn't mean that Perl can't be used to create non-Y2K compliant
560 programs.  It can.  But so can your pencil.  It's the fault of the user,
561 not the language.  At the risk of inflaming the NRA: "Perl doesn't
562 break Y2K, people do."  See http://www.perl.org/about/y2k.html for
563 a longer exposition.
564
565 =head1 Data: Strings
566
567 =head2 How do I validate input?
568
569 (contributed by brian d foy)
570
571 There are many ways to ensure that values are what you expect or
572 want to accept. Besides the specific examples that we cover in the
573 perlfaq, you can also look at the modules with "Assert" and "Validate"
574 in their names, along with other modules such as C<Regexp::Common>.
575
576 Some modules have validation for particular types of input, such
577 as C<Business::ISBN>, C<Business::CreditCard>, C<Email::Valid>,
578 and C<Data::Validate::IP>.
579
580 =head2 How do I unescape a string?
581
582 It depends just what you mean by "escape".  URL escapes are dealt
583 with in L<perlfaq9>.  Shell escapes with the backslash (C<\>)
584 character are removed with
585
586         s/\\(.)/$1/g;
587
588 This won't expand C<"\n"> or C<"\t"> or any other special escapes.
589
590 =head2 How do I remove consecutive pairs of characters?
591
592 (contributed by brian d foy)
593
594 You can use the substitution operator to find pairs of characters (or
595 runs of characters) and replace them with a single instance. In this
596 substitution, we find a character in C<(.)>. The memory parentheses
597 store the matched character in the back-reference C<\1> and we use
598 that to require that the same thing immediately follow it. We replace
599 that part of the string with the character in C<$1>.
600
601         s/(.)\1/$1/g;
602
603 We can also use the transliteration operator, C<tr///>. In this
604 example, the search list side of our C<tr///> contains nothing, but
605 the C<c> option complements that so it contains everything. The
606 replacement list also contains nothing, so the transliteration is
607 almost a no-op since it won't do any replacements (or more exactly,
608 replace the character with itself). However, the C<s> option squashes
609 duplicated and consecutive characters in the string so a character
610 does not show up next to itself
611
612         my $str = 'Haarlem';   # in the Netherlands
613         $str =~ tr///cs;       # Now Harlem, like in New York
614
615 =head2 How do I expand function calls in a string?
616
617 (contributed by brian d foy)
618
619 This is documented in L<perlref>, and although it's not the easiest
620 thing to read, it does work. In each of these examples, we call the
621 function inside the braces used to dereference a reference. If we
622 have more than one return value, we can construct and dereference an
623 anonymous array. In this case, we call the function in list context.
624
625         print "The time values are @{ [localtime] }.\n";
626
627 If we want to call the function in scalar context, we have to do a bit
628 more work. We can really have any code we like inside the braces, so
629 we simply have to end with the scalar reference, although how you do
630 that is up to you, and you can use code inside the braces. Note that
631 the use of parens creates a list context, so we need C<scalar> to
632 force the scalar context on the function:
633
634         print "The time is ${\(scalar localtime)}.\n"
635
636         print "The time is ${ my $x = localtime; \$x }.\n";
637
638 If your function already returns a reference, you don't need to create
639 the reference yourself.
640
641         sub timestamp { my $t = localtime; \$t }
642
643         print "The time is ${ timestamp() }.\n";
644
645 The C<Interpolation> module can also do a lot of magic for you. You can
646 specify a variable name, in this case C<E>, to set up a tied hash that
647 does the interpolation for you. It has several other methods to do this
648 as well.
649
650         use Interpolation E => 'eval';
651         print "The time values are $E{localtime()}.\n";
652
653 In most cases, it is probably easier to simply use string concatenation,
654 which also forces scalar context.
655
656         print "The time is " . localtime() . ".\n";
657
658 =head2 How do I find matching/nesting anything?
659
660 This isn't something that can be done in one regular expression, no
661 matter how complicated.  To find something between two single
662 characters, a pattern like C</x([^x]*)x/> will get the intervening
663 bits in $1. For multiple ones, then something more like
664 C</alpha(.*?)omega/> would be needed. But none of these deals with
665 nested patterns.  For balanced expressions using C<(>, C<{>, C<[> or
666 C<< < >> as delimiters, use the CPAN module Regexp::Common, or see
667 L<perlre/(??{ code })>.  For other cases, you'll have to write a
668 parser.
669
670 If you are serious about writing a parser, there are a number of
671 modules or oddities that will make your life a lot easier.  There are
672 the CPAN modules C<Parse::RecDescent>, C<Parse::Yapp>, and
673 C<Text::Balanced>; and the C<byacc> program. Starting from perl 5.8
674 the C<Text::Balanced> is part of the standard distribution.
675
676 One simple destructive, inside-out approach that you might try is to
677 pull out the smallest nesting parts one at a time:
678
679         while (s/BEGIN((?:(?!BEGIN)(?!END).)*)END//gs) {
680                 # do something with $1
681                 }
682
683 A more complicated and sneaky approach is to make Perl's regular
684 expression engine do it for you.  This is courtesy Dean Inada, and
685 rather has the nature of an Obfuscated Perl Contest entry, but it
686 really does work:
687
688         # $_ contains the string to parse
689         # BEGIN and END are the opening and closing markers for the
690         # nested text.
691
692         @( = ('(','');
693         @) = (')','');
694         ($re=$_)=~s/((BEGIN)|(END)|.)/$)[!$3]\Q$1\E$([!$2]/gs;
695         @$ = (eval{/$re/},$@!~/unmatched/i);
696         print join("\n",@$[0..$#$]) if( $$[-1] );
697
698 =head2 How do I reverse a string?
699
700 Use C<reverse()> in scalar context, as documented in
701 L<perlfunc/reverse>.
702
703         $reversed = reverse $string;
704
705 =head2 How do I expand tabs in a string?
706
707 You can do it yourself:
708
709         1 while $string =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e;
710
711 Or you can just use the C<Text::Tabs> module (part of the standard Perl
712 distribution).
713
714         use Text::Tabs;
715         @expanded_lines = expand(@lines_with_tabs);
716
717 =head2 How do I reformat a paragraph?
718
719 Use C<Text::Wrap> (part of the standard Perl distribution):
720
721         use Text::Wrap;
722         print wrap("\t", '  ', @paragraphs);
723
724 The paragraphs you give to C<Text::Wrap> should not contain embedded
725 newlines.  C<Text::Wrap> doesn't justify the lines (flush-right).
726
727 Or use the CPAN module C<Text::Autoformat>.  Formatting files can be
728 easily done by making a shell alias, like so:
729
730         alias fmt="perl -i -MText::Autoformat -n0777 \
731                 -e 'print autoformat $_, {all=>1}' $*"
732
733 See the documentation for C<Text::Autoformat> to appreciate its many
734 capabilities.
735
736 =head2 How can I access or change N characters of a string?
737
738 You can access the first characters of a string with substr().
739 To get the first character, for example, start at position 0
740 and grab the string of length 1.
741
742
743         $string = "Just another Perl Hacker";
744         $first_char = substr( $string, 0, 1 );  #  'J'
745
746 To change part of a string, you can use the optional fourth
747 argument which is the replacement string.
748
749         substr( $string, 13, 4, "Perl 5.8.0" );
750
751 You can also use substr() as an lvalue.
752
753         substr( $string, 13, 4 ) =  "Perl 5.8.0";
754
755 =head2 How do I change the Nth occurrence of something?
756
757 You have to keep track of N yourself.  For example, let's say you want
758 to change the fifth occurrence of C<"whoever"> or C<"whomever"> into
759 C<"whosoever"> or C<"whomsoever">, case insensitively.  These
760 all assume that $_ contains the string to be altered.
761
762         $count = 0;
763         s{((whom?)ever)}{
764         ++$count == 5       # is it the 5th?
765             ? "${2}soever"  # yes, swap
766             : $1            # renege and leave it there
767                 }ige;
768
769 In the more general case, you can use the C</g> modifier in a C<while>
770 loop, keeping count of matches.
771
772         $WANT = 3;
773         $count = 0;
774         $_ = "One fish two fish red fish blue fish";
775         while (/(\w+)\s+fish\b/gi) {
776                 if (++$count == $WANT) {
777                         print "The third fish is a $1 one.\n";
778                         }
779                 }
780
781 That prints out: C<"The third fish is a red one.">  You can also use a
782 repetition count and repeated pattern like this:
783
784         /(?:\w+\s+fish\s+){2}(\w+)\s+fish/i;
785
786 =head2 How can I count the number of occurrences of a substring within a string?
787
788 There are a number of ways, with varying efficiency.  If you want a
789 count of a certain single character (X) within a string, you can use the
790 C<tr///> function like so:
791
792         $string = "ThisXlineXhasXsomeXx'sXinXit";
793         $count = ($string =~ tr/X//);
794         print "There are $count X characters in the string";
795
796 This is fine if you are just looking for a single character.  However,
797 if you are trying to count multiple character substrings within a
798 larger string, C<tr///> won't work.  What you can do is wrap a while()
799 loop around a global pattern match.  For example, let's count negative
800 integers:
801
802         $string = "-9 55 48 -2 23 -76 4 14 -44";
803         while ($string =~ /-\d+/g) { $count++ }
804         print "There are $count negative numbers in the string";
805
806 Another version uses a global match in list context, then assigns the
807 result to a scalar, producing a count of the number of matches.
808
809         $count = () = $string =~ /-\d+/g;
810
811 =head2 Does Perl have a Year 2038 problem?
812
813 No, all of Perl's built in date and time functions and modules will
814 work to about 2 billion years before and after 1970.
815
816 Many systems cannot count time past the year 2038.  Older versions of
817 Perl were dependent on the system to do date calculation and thus
818 shared their 2038 bug.
819
820 =head2 How do I capitalize all the words on one line?
821 X<Text::Autoformat> X<capitalize> X<case, title> X<case, sentence>
822
823 (contributed by brian d foy)
824
825 Damian Conway's L<Text::Autoformat> handles all of the thinking
826 for you.
827
828         use Text::Autoformat;
829         my $x = "Dr. Strangelove or: How I Learned to Stop ".
830           "Worrying and Love the Bomb";
831
832         print $x, "\n";
833         for my $style (qw( sentence title highlight )) {
834                 print autoformat($x, { case => $style }), "\n";
835                 }
836
837 How do you want to capitalize those words?
838
839         FRED AND BARNEY'S LODGE        # all uppercase
840         Fred And Barney's Lodge        # title case
841         Fred and Barney's Lodge        # highlight case
842
843 It's not as easy a problem as it looks. How many words do you think
844 are in there? Wait for it... wait for it.... If you answered 5
845 you're right. Perl words are groups of C<\w+>, but that's not what
846 you want to capitalize. How is Perl supposed to know not to capitalize
847 that C<s> after the apostrophe? You could try a regular expression:
848
849         $string =~ s/ (
850                                  (^\w)    #at the beginning of the line
851                                    |      # or
852                                  (\s\w)   #preceded by whitespace
853                                    )
854                                 /\U$1/xg;
855
856         $string =~ s/([\w']+)/\u\L$1/g;
857
858 Now, what if you don't want to capitalize that "and"? Just use
859 L<Text::Autoformat> and get on with the next problem. :)
860
861 =head2 How can I split a [character] delimited string except when inside [character]?
862
863 Several modules can handle this sort of parsing--C<Text::Balanced>,
864 C<Text::CSV>, C<Text::CSV_XS>, and C<Text::ParseWords>, among others.
865
866 Take the example case of trying to split a string that is
867 comma-separated into its different fields. You can't use C<split(/,/)>
868 because you shouldn't split if the comma is inside quotes.  For
869 example, take a data line like this:
870
871         SAR001,"","Cimetrix, Inc","Bob Smith","CAM",N,8,1,0,7,"Error, Core Dumped"
872
873 Due to the restriction of the quotes, this is a fairly complex
874 problem.  Thankfully, we have Jeffrey Friedl, author of
875 I<Mastering Regular Expressions>, to handle these for us.  He
876 suggests (assuming your string is contained in C<$text>):
877
878          @new = ();
879          push(@new, $+) while $text =~ m{
880                  "([^\"\\]*(?:\\.[^\"\\]*)*)",?  # groups the phrase inside the quotes
881                 | ([^,]+),?
882                 | ,
883                 }gx;
884          push(@new, undef) if substr($text,-1,1) eq ',';
885
886 If you want to represent quotation marks inside a
887 quotation-mark-delimited field, escape them with backslashes (eg,
888 C<"like \"this\"">.
889
890 Alternatively, the C<Text::ParseWords> module (part of the standard
891 Perl distribution) lets you say:
892
893         use Text::ParseWords;
894         @new = quotewords(",", 0, $text);
895
896 =head2 How do I strip blank space from the beginning/end of a string?
897
898 (contributed by brian d foy)
899
900 A substitution can do this for you. For a single line, you want to
901 replace all the leading or trailing whitespace with nothing. You
902 can do that with a pair of substitutions.
903
904         s/^\s+//;
905         s/\s+$//;
906
907 You can also write that as a single substitution, although it turns
908 out the combined statement is slower than the separate ones. That
909 might not matter to you, though.
910
911         s/^\s+|\s+$//g;
912
913 In this regular expression, the alternation matches either at the
914 beginning or the end of the string since the anchors have a lower
915 precedence than the alternation. With the C</g> flag, the substitution
916 makes all possible matches, so it gets both. Remember, the trailing
917 newline matches the C<\s+>, and  the C<$> anchor can match to the
918 physical end of the string, so the newline disappears too. Just add
919 the newline to the output, which has the added benefit of preserving
920 "blank" (consisting entirely of whitespace) lines which the C<^\s+>
921 would remove all by itself.
922
923         while( <> )
924                 {
925                 s/^\s+|\s+$//g;
926                 print "$_\n";
927                 }
928
929 For a multi-line string, you can apply the regular expression
930 to each logical line in the string by adding the C</m> flag (for
931 "multi-line"). With the C</m> flag, the C<$> matches I<before> an
932 embedded newline, so it doesn't remove it. It still removes the
933 newline at the end of the string.
934
935         $string =~ s/^\s+|\s+$//gm;
936
937 Remember that lines consisting entirely of whitespace will disappear,
938 since the first part of the alternation can match the entire string
939 and replace it with nothing. If need to keep embedded blank lines,
940 you have to do a little more work. Instead of matching any whitespace
941 (since that includes a newline), just match the other whitespace.
942
943         $string =~ s/^[\t\f ]+|[\t\f ]+$//mg;
944
945 =head2 How do I pad a string with blanks or pad a number with zeroes?
946
947 In the following examples, C<$pad_len> is the length to which you wish
948 to pad the string, C<$text> or C<$num> contains the string to be padded,
949 and C<$pad_char> contains the padding character. You can use a single
950 character string constant instead of the C<$pad_char> variable if you
951 know what it is in advance. And in the same way you can use an integer in
952 place of C<$pad_len> if you know the pad length in advance.
953
954 The simplest method uses the C<sprintf> function. It can pad on the left
955 or right with blanks and on the left with zeroes and it will not
956 truncate the result. The C<pack> function can only pad strings on the
957 right with blanks and it will truncate the result to a maximum length of
958 C<$pad_len>.
959
960         # Left padding a string with blanks (no truncation):
961         $padded = sprintf("%${pad_len}s", $text);
962         $padded = sprintf("%*s", $pad_len, $text);  # same thing
963
964         # Right padding a string with blanks (no truncation):
965         $padded = sprintf("%-${pad_len}s", $text);
966         $padded = sprintf("%-*s", $pad_len, $text); # same thing
967
968         # Left padding a number with 0 (no truncation):
969         $padded = sprintf("%0${pad_len}d", $num);
970         $padded = sprintf("%0*d", $pad_len, $num); # same thing
971
972         # Right padding a string with blanks using pack (will truncate):
973         $padded = pack("A$pad_len",$text);
974
975 If you need to pad with a character other than blank or zero you can use
976 one of the following methods.  They all generate a pad string with the
977 C<x> operator and combine that with C<$text>. These methods do
978 not truncate C<$text>.
979
980 Left and right padding with any character, creating a new string:
981
982         $padded = $pad_char x ( $pad_len - length( $text ) ) . $text;
983         $padded = $text . $pad_char x ( $pad_len - length( $text ) );
984
985 Left and right padding with any character, modifying C<$text> directly:
986
987         substr( $text, 0, 0 ) = $pad_char x ( $pad_len - length( $text ) );
988         $text .= $pad_char x ( $pad_len - length( $text ) );
989
990 =head2 How do I extract selected columns from a string?
991
992 (contributed by brian d foy)
993
994 If you know where the columns that contain the data, you can
995 use C<substr> to extract a single column.
996
997         my $column = substr( $line, $start_column, $length );
998
999 You can use C<split> if the columns are separated by whitespace or
1000 some other delimiter, as long as whitespace or the delimiter cannot
1001 appear as part of the data.
1002
1003         my $line    = ' fred barney   betty   ';
1004         my @columns = split /\s+/, $line;
1005                 # ( '', 'fred', 'barney', 'betty' );
1006
1007         my $line    = 'fred||barney||betty';
1008         my @columns = split /\|/, $line;
1009                 # ( 'fred', '', 'barney', '', 'betty' );
1010
1011 If you want to work with comma-separated values, don't do this since
1012 that format is a bit more complicated. Use one of the modules that
1013 handle that format, such as C<Text::CSV>, C<Text::CSV_XS>, or
1014 C<Text::CSV_PP>.
1015
1016 If you want to break apart an entire line of fixed columns, you can use
1017 C<unpack> with the A (ASCII) format. by using a number after the format
1018 specifier, you can denote the column width. See the C<pack> and C<unpack>
1019 entries in L<perlfunc> for more details.
1020
1021         my @fields = unpack( $line, "A8 A8 A8 A16 A4" );
1022
1023 Note that spaces in the format argument to C<unpack> do not denote literal
1024 spaces. If you have space separated data, you may want C<split> instead.
1025
1026 =head2 How do I find the soundex value of a string?
1027
1028 (contributed by brian d foy)
1029
1030 You can use the Text::Soundex module. If you want to do fuzzy or close
1031 matching, you might also try the C<String::Approx>, and
1032 C<Text::Metaphone>, and C<Text::DoubleMetaphone> modules.
1033
1034 =head2 How can I expand variables in text strings?
1035
1036 (contributed by brian d foy)
1037
1038 If you can avoid it, don't, or if you can use a templating system,
1039 such as C<Text::Template> or C<Template> Toolkit, do that instead. You
1040 might even be able to get the job done with C<sprintf> or C<printf>:
1041
1042         my $string = sprintf 'Say hello to %s and %s', $foo, $bar;
1043
1044 However, for the one-off simple case where I don't want to pull out a
1045 full templating system, I'll use a string that has two Perl scalar
1046 variables in it. In this example, I want to expand C<$foo> and C<$bar>
1047 to their variable's values:
1048
1049         my $foo = 'Fred';
1050         my $bar = 'Barney';
1051         $string = 'Say hello to $foo and $bar';
1052
1053 One way I can do this involves the substitution operator and a double
1054 C</e> flag.  The first C</e> evaluates C<$1> on the replacement side and
1055 turns it into C<$foo>. The second /e starts with C<$foo> and replaces
1056 it with its value. C<$foo>, then, turns into 'Fred', and that's finally
1057 what's left in the string:
1058
1059         $string =~ s/(\$\w+)/$1/eeg; # 'Say hello to Fred and Barney'
1060
1061 The C</e> will also silently ignore violations of strict, replacing
1062 undefined variable names with the empty string. Since I'm using the
1063 C</e> flag (twice even!), I have all of the same security problems I
1064 have with C<eval> in its string form. If there's something odd in
1065 C<$foo>, perhaps something like C<@{[ system "rm -rf /" ]}>, then
1066 I could get myself in trouble.
1067
1068 To get around the security problem, I could also pull the values from
1069 a hash instead of evaluating variable names. Using a single C</e>, I
1070 can check the hash to ensure the value exists, and if it doesn't, I
1071 can replace the missing value with a marker, in this case C<???> to
1072 signal that I missed something:
1073
1074         my $string = 'This has $foo and $bar';
1075
1076         my %Replacements = (
1077                 foo  => 'Fred',
1078                 );
1079
1080         # $string =~ s/\$(\w+)/$Replacements{$1}/g;
1081         $string =~ s/\$(\w+)/
1082                 exists $Replacements{$1} ? $Replacements{$1} : '???'
1083                 /eg;
1084
1085         print $string;
1086
1087 =head2 What's wrong with always quoting "$vars"?
1088
1089 The problem is that those double-quotes force
1090 stringification--coercing numbers and references into strings--even
1091 when you don't want them to be strings.  Think of it this way:
1092 double-quote expansion is used to produce new strings.  If you already
1093 have a string, why do you need more?
1094
1095 If you get used to writing odd things like these:
1096
1097         print "$var";           # BAD
1098         $new = "$old";          # BAD
1099         somefunc("$var");       # BAD
1100
1101 You'll be in trouble.  Those should (in 99.8% of the cases) be
1102 the simpler and more direct:
1103
1104         print $var;
1105         $new = $old;
1106         somefunc($var);
1107
1108 Otherwise, besides slowing you down, you're going to break code when
1109 the thing in the scalar is actually neither a string nor a number, but
1110 a reference:
1111
1112         func(\@array);
1113         sub func {
1114                 my $aref = shift;
1115                 my $oref = "$aref";  # WRONG
1116                 }
1117
1118 You can also get into subtle problems on those few operations in Perl
1119 that actually do care about the difference between a string and a
1120 number, such as the magical C<++> autoincrement operator or the
1121 syscall() function.
1122
1123 Stringification also destroys arrays.
1124
1125         @lines = `command`;
1126         print "@lines";     # WRONG - extra blanks
1127         print @lines;       # right
1128
1129 =head2 Why don't my E<lt>E<lt>HERE documents work?
1130
1131 Check for these three things:
1132
1133 =over 4
1134
1135 =item There must be no space after the E<lt>E<lt> part.
1136
1137 =item There (probably) should be a semicolon at the end.
1138
1139 =item You can't (easily) have any space in front of the tag.
1140
1141 =back
1142
1143 If you want to indent the text in the here document, you
1144 can do this:
1145
1146     # all in one
1147     ($VAR = <<HERE_TARGET) =~ s/^\s+//gm;
1148         your text
1149         goes here
1150     HERE_TARGET
1151
1152 But the HERE_TARGET must still be flush against the margin.
1153 If you want that indented also, you'll have to quote
1154 in the indentation.
1155
1156     ($quote = <<'    FINIS') =~ s/^\s+//gm;
1157             ...we will have peace, when you and all your works have
1158             perished--and the works of your dark master to whom you
1159             would deliver us. You are a liar, Saruman, and a corrupter
1160             of men's hearts.  --Theoden in /usr/src/perl/taint.c
1161         FINIS
1162     $quote =~ s/\s+--/\n--/;
1163
1164 A nice general-purpose fixer-upper function for indented here documents
1165 follows.  It expects to be called with a here document as its argument.
1166 It looks to see whether each line begins with a common substring, and
1167 if so, strips that substring off.  Otherwise, it takes the amount of leading
1168 whitespace found on the first line and removes that much off each
1169 subsequent line.
1170
1171     sub fix {
1172         local $_ = shift;
1173         my ($white, $leader);  # common whitespace and common leading string
1174         if (/^\s*(?:([^\w\s]+)(\s*).*\n)(?:\s*\1\2?.*\n)+$/) {
1175             ($white, $leader) = ($2, quotemeta($1));
1176         } else {
1177             ($white, $leader) = (/^(\s+)/, '');
1178         }
1179         s/^\s*?$leader(?:$white)?//gm;
1180         return $_;
1181     }
1182
1183 This works with leading special strings, dynamically determined:
1184
1185         $remember_the_main = fix<<'    MAIN_INTERPRETER_LOOP';
1186         @@@ int
1187         @@@ runops() {
1188         @@@     SAVEI32(runlevel);
1189         @@@     runlevel++;
1190         @@@     while ( op = (*op->op_ppaddr)() );
1191         @@@     TAINT_NOT;
1192         @@@     return 0;
1193         @@@ }
1194         MAIN_INTERPRETER_LOOP
1195
1196 Or with a fixed amount of leading whitespace, with remaining
1197 indentation correctly preserved:
1198
1199         $poem = fix<<EVER_ON_AND_ON;
1200        Now far ahead the Road has gone,
1201           And I must follow, if I can,
1202        Pursuing it with eager feet,
1203           Until it joins some larger way
1204        Where many paths and errands meet.
1205           And whither then? I cannot say.
1206                 --Bilbo in /usr/src/perl/pp_ctl.c
1207         EVER_ON_AND_ON
1208
1209 =head1 Data: Arrays
1210
1211 =head2 What is the difference between a list and an array?
1212
1213 An array has a changeable length.  A list does not.  An array is
1214 something you can push or pop, while a list is a set of values.  Some
1215 people make the distinction that a list is a value while an array is a
1216 variable. Subroutines are passed and return lists, you put things into
1217 list context, you initialize arrays with lists, and you C<foreach()>
1218 across a list.  C<@> variables are arrays, anonymous arrays are
1219 arrays, arrays in scalar context behave like the number of elements in
1220 them, subroutines access their arguments through the array C<@_>, and
1221 C<push>/C<pop>/C<shift> only work on arrays.
1222
1223 As a side note, there's no such thing as a list in scalar context.
1224 When you say
1225
1226         $scalar = (2, 5, 7, 9);
1227
1228 you're using the comma operator in scalar context, so it uses the scalar
1229 comma operator.  There never was a list there at all! This causes the
1230 last value to be returned: 9.
1231
1232 =head2 What is the difference between $array[1] and @array[1]?
1233
1234 The former is a scalar value; the latter an array slice, making
1235 it a list with one (scalar) value.  You should use $ when you want a
1236 scalar value (most of the time) and @ when you want a list with one
1237 scalar value in it (very, very rarely; nearly never, in fact).
1238
1239 Sometimes it doesn't make a difference, but sometimes it does.
1240 For example, compare:
1241
1242         $good[0] = `some program that outputs several lines`;
1243
1244 with
1245
1246         @bad[0]  = `same program that outputs several lines`;
1247
1248 The C<use warnings> pragma and the B<-w> flag will warn you about these
1249 matters.
1250
1251 =head2 How can I remove duplicate elements from a list or array?
1252
1253 (contributed by brian d foy)
1254
1255 Use a hash. When you think the words "unique" or "duplicated", think
1256 "hash keys".
1257
1258 If you don't care about the order of the elements, you could just
1259 create the hash then extract the keys. It's not important how you
1260 create that hash: just that you use C<keys> to get the unique
1261 elements.
1262
1263         my %hash   = map { $_, 1 } @array;
1264         # or a hash slice: @hash{ @array } = ();
1265         # or a foreach: $hash{$_} = 1 foreach ( @array );
1266
1267         my @unique = keys %hash;
1268
1269 If you want to use a module, try the C<uniq> function from
1270 C<List::MoreUtils>. In list context it returns the unique elements,
1271 preserving their order in the list. In scalar context, it returns the
1272 number of unique elements.
1273
1274         use List::MoreUtils qw(uniq);
1275
1276         my @unique = uniq( 1, 2, 3, 4, 4, 5, 6, 5, 7 ); # 1,2,3,4,5,6,7
1277         my $unique = uniq( 1, 2, 3, 4, 4, 5, 6, 5, 7 ); # 7
1278
1279 You can also go through each element and skip the ones you've seen
1280 before. Use a hash to keep track. The first time the loop sees an
1281 element, that element has no key in C<%Seen>. The C<next> statement
1282 creates the key and immediately uses its value, which is C<undef>, so
1283 the loop continues to the C<push> and increments the value for that
1284 key. The next time the loop sees that same element, its key exists in
1285 the hash I<and> the value for that key is true (since it's not 0 or
1286 C<undef>), so the next skips that iteration and the loop goes to the
1287 next element.
1288
1289         my @unique = ();
1290         my %seen   = ();
1291
1292         foreach my $elem ( @array )
1293                 {
1294                 next if $seen{ $elem }++;
1295                 push @unique, $elem;
1296                 }
1297
1298 You can write this more briefly using a grep, which does the
1299 same thing.
1300
1301         my %seen = ();
1302         my @unique = grep { ! $seen{ $_ }++ } @array;
1303
1304 =head2 How can I tell whether a certain element is contained in a list or array?
1305
1306 (portions of this answer contributed by Anno Siegel and brian d foy)
1307
1308 Hearing the word "in" is an I<in>dication that you probably should have
1309 used a hash, not a list or array, to store your data.  Hashes are
1310 designed to answer this question quickly and efficiently.  Arrays aren't.
1311
1312 That being said, there are several ways to approach this.  In Perl 5.10
1313 and later, you can use the smart match operator to check that an item is
1314 contained in an array or a hash:
1315
1316         use 5.010;
1317
1318         if( $item ~~ @array )
1319                 {
1320                 say "The array contains $item"
1321                 }
1322
1323         if( $item ~~ %hash )
1324                 {
1325                 say "The hash contains $item"
1326                 }
1327
1328 With earlier versions of Perl, you have to do a bit more work. If you
1329 are going to make this query many times over arbitrary string values,
1330 the fastest way is probably to invert the original array and maintain a
1331 hash whose keys are the first array's values:
1332
1333         @blues = qw/azure cerulean teal turquoise lapis-lazuli/;
1334         %is_blue = ();
1335         for (@blues) { $is_blue{$_} = 1 }
1336
1337 Now you can check whether C<$is_blue{$some_color}>.  It might have
1338 been a good idea to keep the blues all in a hash in the first place.
1339
1340 If the values are all small integers, you could use a simple indexed
1341 array.  This kind of an array will take up less space:
1342
1343         @primes = (2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31);
1344         @is_tiny_prime = ();
1345         for (@primes) { $is_tiny_prime[$_] = 1 }
1346         # or simply  @istiny_prime[@primes] = (1) x @primes;
1347
1348 Now you check whether $is_tiny_prime[$some_number].
1349
1350 If the values in question are integers instead of strings, you can save
1351 quite a lot of space by using bit strings instead:
1352
1353         @articles = ( 1..10, 150..2000, 2017 );
1354         undef $read;
1355         for (@articles) { vec($read,$_,1) = 1 }
1356
1357 Now check whether C<vec($read,$n,1)> is true for some C<$n>.
1358
1359 These methods guarantee fast individual tests but require a re-organization
1360 of the original list or array.  They only pay off if you have to test
1361 multiple values against the same array.
1362
1363 If you are testing only once, the standard module C<List::Util> exports
1364 the function C<first> for this purpose.  It works by stopping once it
1365 finds the element. It's written in C for speed, and its Perl equivalent
1366 looks like this subroutine:
1367
1368         sub first (&@) {
1369                 my $code = shift;
1370                 foreach (@_) {
1371                         return $_ if &{$code}();
1372                 }
1373                 undef;
1374         }
1375
1376 If speed is of little concern, the common idiom uses grep in scalar context
1377 (which returns the number of items that passed its condition) to traverse the
1378 entire list. This does have the benefit of telling you how many matches it
1379 found, though.
1380
1381         my $is_there = grep $_ eq $whatever, @array;
1382
1383 If you want to actually extract the matching elements, simply use grep in
1384 list context.
1385
1386         my @matches = grep $_ eq $whatever, @array;
1387
1388 =head2 How do I compute the difference of two arrays?  How do I compute the intersection of two arrays?
1389
1390 Use a hash.  Here's code to do both and more.  It assumes that each
1391 element is unique in a given array:
1392
1393         @union = @intersection = @difference = ();
1394         %count = ();
1395         foreach $element (@array1, @array2) { $count{$element}++ }
1396         foreach $element (keys %count) {
1397                 push @union, $element;
1398                 push @{ $count{$element} > 1 ? \@intersection : \@difference }, $element;
1399                 }
1400
1401 Note that this is the I<symmetric difference>, that is, all elements
1402 in either A or in B but not in both.  Think of it as an xor operation.
1403
1404 =head2 How do I test whether two arrays or hashes are equal?
1405
1406 With Perl 5.10 and later, the smart match operator can give you the answer
1407 with the least amount of work:
1408
1409         use 5.010;
1410
1411         if( @array1 ~~ @array2 )
1412                 {
1413                 say "The arrays are the same";
1414                 }
1415
1416         if( %hash1 ~~ %hash2 ) # doesn't check values!
1417                 {
1418                 say "The hash keys are the same";
1419                 }
1420
1421 The following code works for single-level arrays.  It uses a
1422 stringwise comparison, and does not distinguish defined versus
1423 undefined empty strings.  Modify if you have other needs.
1424
1425         $are_equal = compare_arrays(\@frogs, \@toads);
1426
1427         sub compare_arrays {
1428                 my ($first, $second) = @_;
1429                 no warnings;  # silence spurious -w undef complaints
1430                 return 0 unless @$first == @$second;
1431                 for (my $i = 0; $i < @$first; $i++) {
1432                         return 0 if $first->[$i] ne $second->[$i];
1433                         }
1434                 return 1;
1435                 }
1436
1437 For multilevel structures, you may wish to use an approach more
1438 like this one.  It uses the CPAN module C<FreezeThaw>:
1439
1440         use FreezeThaw qw(cmpStr);
1441         @a = @b = ( "this", "that", [ "more", "stuff" ] );
1442
1443         printf "a and b contain %s arrays\n",
1444                 cmpStr(\@a, \@b) == 0
1445                 ? "the same"
1446                 : "different";
1447
1448 This approach also works for comparing hashes.  Here we'll demonstrate
1449 two different answers:
1450
1451         use FreezeThaw qw(cmpStr cmpStrHard);
1452
1453         %a = %b = ( "this" => "that", "extra" => [ "more", "stuff" ] );
1454         $a{EXTRA} = \%b;
1455         $b{EXTRA} = \%a;
1456
1457         printf "a and b contain %s hashes\n",
1458         cmpStr(\%a, \%b) == 0 ? "the same" : "different";
1459
1460         printf "a and b contain %s hashes\n",
1461         cmpStrHard(\%a, \%b) == 0 ? "the same" : "different";
1462
1463
1464 The first reports that both those the hashes contain the same data,
1465 while the second reports that they do not.  Which you prefer is left as
1466 an exercise to the reader.
1467
1468 =head2 How do I find the first array element for which a condition is true?
1469
1470 To find the first array element which satisfies a condition, you can
1471 use the C<first()> function in the C<List::Util> module, which comes
1472 with Perl 5.8. This example finds the first element that contains
1473 "Perl".
1474
1475         use List::Util qw(first);
1476
1477         my $element = first { /Perl/ } @array;
1478
1479 If you cannot use C<List::Util>, you can make your own loop to do the
1480 same thing.  Once you find the element, you stop the loop with last.
1481
1482         my $found;
1483         foreach ( @array ) {
1484                 if( /Perl/ ) { $found = $_; last }
1485                 }
1486
1487 If you want the array index, you can iterate through the indices
1488 and check the array element at each index until you find one
1489 that satisfies the condition.
1490
1491         my( $found, $index ) = ( undef, -1 );
1492         for( $i = 0; $i < @array; $i++ ) {
1493                 if( $array[$i] =~ /Perl/ ) {
1494                         $found = $array[$i];
1495                         $index = $i;
1496                         last;
1497                         }
1498                 }
1499
1500 =head2 How do I handle linked lists?
1501
1502 In general, you usually don't need a linked list in Perl, since with
1503 regular arrays, you can push and pop or shift and unshift at either
1504 end, or you can use splice to add and/or remove arbitrary number of
1505 elements at arbitrary points.  Both pop and shift are O(1)
1506 operations on Perl's dynamic arrays.  In the absence of shifts and
1507 pops, push in general needs to reallocate on the order every log(N)
1508 times, and unshift will need to copy pointers each time.
1509
1510 If you really, really wanted, you could use structures as described in
1511 L<perldsc> or L<perltoot> and do just what the algorithm book tells
1512 you to do.  For example, imagine a list node like this:
1513
1514         $node = {
1515                 VALUE => 42,
1516                 LINK  => undef,
1517                 };
1518
1519 You could walk the list this way:
1520
1521         print "List: ";
1522         for ($node = $head;  $node; $node = $node->{LINK}) {
1523                 print $node->{VALUE}, " ";
1524                 }
1525         print "\n";
1526
1527 You could add to the list this way:
1528
1529         my ($head, $tail);
1530         $tail = append($head, 1);       # grow a new head
1531         for $value ( 2 .. 10 ) {
1532                 $tail = append($tail, $value);
1533                 }
1534
1535         sub append {
1536                 my($list, $value) = @_;
1537                 my $node = { VALUE => $value };
1538                 if ($list) {
1539                         $node->{LINK} = $list->{LINK};
1540                         $list->{LINK} = $node;
1541                         }
1542                 else {
1543                         $_[0] = $node;      # replace caller's version
1544                         }
1545                 return $node;
1546                 }
1547
1548 But again, Perl's built-in are virtually always good enough.
1549
1550 =head2 How do I handle circular lists?
1551 X<circular> X<array> X<Tie::Cycle> X<Array::Iterator::Circular>
1552 X<cycle> X<modulus>
1553
1554 (contributed by brian d foy)
1555
1556 If you want to cycle through an array endlessy, you can increment the
1557 index modulo the number of elements in the array:
1558
1559         my @array = qw( a b c );
1560         my $i = 0;
1561
1562         while( 1 ) {
1563                 print $array[ $i++ % @array ], "\n";
1564                 last if $i > 20;
1565                 }
1566
1567 You can also use C<Tie::Cycle> to use a scalar that always has the
1568 next element of the circular array:
1569
1570         use Tie::Cycle;
1571
1572         tie my $cycle, 'Tie::Cycle', [ qw( FFFFFF 000000 FFFF00 ) ];
1573
1574         print $cycle; # FFFFFF
1575         print $cycle; # 000000
1576         print $cycle; # FFFF00
1577
1578 The C<Array::Iterator::Circular> creates an iterator object for
1579 circular arrays:
1580
1581         use Array::Iterator::Circular;
1582
1583         my $color_iterator = Array::Iterator::Circular->new(
1584                 qw(red green blue orange)
1585                 );
1586
1587         foreach ( 1 .. 20 ) {
1588                 print $color_iterator->next, "\n";
1589                 }
1590
1591 =head2 How do I shuffle an array randomly?
1592
1593 If you either have Perl 5.8.0 or later installed, or if you have
1594 Scalar-List-Utils 1.03 or later installed, you can say:
1595
1596         use List::Util 'shuffle';
1597
1598         @shuffled = shuffle(@list);
1599
1600 If not, you can use a Fisher-Yates shuffle.
1601
1602         sub fisher_yates_shuffle {
1603                 my $deck = shift;  # $deck is a reference to an array
1604                 return unless @$deck; # must not be empty!
1605
1606                 my $i = @$deck;
1607                 while (--$i) {
1608                         my $j = int rand ($i+1);
1609                         @$deck[$i,$j] = @$deck[$j,$i];
1610                         }
1611         }
1612
1613         # shuffle my mpeg collection
1614         #
1615         my @mpeg = <audio/*/*.mp3>;
1616         fisher_yates_shuffle( \@mpeg );    # randomize @mpeg in place
1617         print @mpeg;
1618
1619 Note that the above implementation shuffles an array in place,
1620 unlike the C<List::Util::shuffle()> which takes a list and returns
1621 a new shuffled list.
1622
1623 You've probably seen shuffling algorithms that work using splice,
1624 randomly picking another element to swap the current element with
1625
1626         srand;
1627         @new = ();
1628         @old = 1 .. 10;  # just a demo
1629         while (@old) {
1630                 push(@new, splice(@old, rand @old, 1));
1631                 }
1632
1633 This is bad because splice is already O(N), and since you do it N
1634 times, you just invented a quadratic algorithm; that is, O(N**2).
1635 This does not scale, although Perl is so efficient that you probably
1636 won't notice this until you have rather largish arrays.
1637
1638 =head2 How do I process/modify each element of an array?
1639
1640 Use C<for>/C<foreach>:
1641
1642         for (@lines) {
1643                 s/foo/bar/;     # change that word
1644                 tr/XZ/ZX/;      # swap those letters
1645                 }
1646
1647 Here's another; let's compute spherical volumes:
1648
1649         for (@volumes = @radii) {   # @volumes has changed parts
1650                 $_ **= 3;
1651                 $_ *= (4/3) * 3.14159;  # this will be constant folded
1652                 }
1653
1654 which can also be done with C<map()> which is made to transform
1655 one list into another:
1656
1657         @volumes = map {$_ ** 3 * (4/3) * 3.14159} @radii;
1658
1659 If you want to do the same thing to modify the values of the
1660 hash, you can use the C<values> function.  As of Perl 5.6
1661 the values are not copied, so if you modify $orbit (in this
1662 case), you modify the value.
1663
1664         for $orbit ( values %orbits ) {
1665                 ($orbit **= 3) *= (4/3) * 3.14159;
1666                 }
1667
1668 Prior to perl 5.6 C<values> returned copies of the values,
1669 so older perl code often contains constructions such as
1670 C<@orbits{keys %orbits}> instead of C<values %orbits> where
1671 the hash is to be modified.
1672
1673 =head2 How do I select a random element from an array?
1674
1675 Use the C<rand()> function (see L<perlfunc/rand>):
1676
1677         $index   = rand @array;
1678         $element = $array[$index];
1679
1680 Or, simply:
1681
1682         my $element = $array[ rand @array ];
1683
1684 =head2 How do I permute N elements of a list?
1685 X<List::Permuter> X<permute> X<Algorithm::Loops> X<Knuth>
1686 X<The Art of Computer Programming> X<Fischer-Krause>
1687
1688 Use the C<List::Permutor> module on CPAN. If the list is actually an
1689 array, try the C<Algorithm::Permute> module (also on CPAN). It's
1690 written in XS code and is very efficient:
1691
1692         use Algorithm::Permute;
1693
1694         my @array = 'a'..'d';
1695         my $p_iterator = Algorithm::Permute->new ( \@array );
1696
1697         while (my @perm = $p_iterator->next) {
1698            print "next permutation: (@perm)\n";
1699                 }
1700
1701 For even faster execution, you could do:
1702
1703         use Algorithm::Permute;
1704
1705         my @array = 'a'..'d';
1706
1707         Algorithm::Permute::permute {
1708                 print "next permutation: (@array)\n";
1709                 } @array;
1710
1711 Here's a little program that generates all permutations of all the
1712 words on each line of input. The algorithm embodied in the
1713 C<permute()> function is discussed in Volume 4 (still unpublished) of
1714 Knuth's I<The Art of Computer Programming> and will work on any list:
1715
1716         #!/usr/bin/perl -n
1717         # Fischer-Krause ordered permutation generator
1718
1719         sub permute (&@) {
1720                 my $code = shift;
1721                 my @idx = 0..$#_;
1722                 while ( $code->(@_[@idx]) ) {
1723                         my $p = $#idx;
1724                         --$p while $idx[$p-1] > $idx[$p];
1725                         my $q = $p or return;
1726                         push @idx, reverse splice @idx, $p;
1727                         ++$q while $idx[$p-1] > $idx[$q];
1728                         @idx[$p-1,$q]=@idx[$q,$p-1];
1729                 }
1730         }
1731
1732         permute { print "@_\n" } split;
1733
1734 The C<Algorithm::Loops> module also provides the C<NextPermute> and
1735 C<NextPermuteNum> functions which efficiently find all unique permutations
1736 of an array, even if it contains duplicate values, modifying it in-place:
1737 if its elements are in reverse-sorted order then the array is reversed,
1738 making it sorted, and it returns false; otherwise the next
1739 permutation is returned.
1740
1741 C<NextPermute> uses string order and C<NextPermuteNum> numeric order, so
1742 you can enumerate all the permutations of C<0..9> like this:
1743
1744         use Algorithm::Loops qw(NextPermuteNum);
1745
1746     my @list= 0..9;
1747     do { print "@list\n" } while NextPermuteNum @list;
1748
1749 =head2 How do I sort an array by (anything)?
1750
1751 Supply a comparison function to sort() (described in L<perlfunc/sort>):
1752
1753         @list = sort { $a <=> $b } @list;
1754
1755 The default sort function is cmp, string comparison, which would
1756 sort C<(1, 2, 10)> into C<(1, 10, 2)>.  C<< <=> >>, used above, is
1757 the numerical comparison operator.
1758
1759 If you have a complicated function needed to pull out the part you
1760 want to sort on, then don't do it inside the sort function.  Pull it
1761 out first, because the sort BLOCK can be called many times for the
1762 same element.  Here's an example of how to pull out the first word
1763 after the first number on each item, and then sort those words
1764 case-insensitively.
1765
1766         @idx = ();
1767         for (@data) {
1768                 ($item) = /\d+\s*(\S+)/;
1769                 push @idx, uc($item);
1770             }
1771         @sorted = @data[ sort { $idx[$a] cmp $idx[$b] } 0 .. $#idx ];
1772
1773 which could also be written this way, using a trick
1774 that's come to be known as the Schwartzian Transform:
1775
1776         @sorted = map  { $_->[0] }
1777                 sort { $a->[1] cmp $b->[1] }
1778                 map  { [ $_, uc( (/\d+\s*(\S+)/)[0]) ] } @data;
1779
1780 If you need to sort on several fields, the following paradigm is useful.
1781
1782         @sorted = sort {
1783                 field1($a) <=> field1($b) ||
1784                 field2($a) cmp field2($b) ||
1785                 field3($a) cmp field3($b)
1786                 } @data;
1787
1788 This can be conveniently combined with precalculation of keys as given
1789 above.
1790
1791 See the F<sort> article in the "Far More Than You Ever Wanted
1792 To Know" collection in http://www.cpan.org/misc/olddoc/FMTEYEWTK.tgz for
1793 more about this approach.
1794
1795 See also the question later in L<perlfaq4> on sorting hashes.
1796
1797 =head2 How do I manipulate arrays of bits?
1798
1799 Use C<pack()> and C<unpack()>, or else C<vec()> and the bitwise
1800 operations.
1801
1802 For example, you don't have to store individual bits in an array
1803 (which would mean that you're wasting a lot of space). To convert an
1804 array of bits to a string, use C<vec()> to set the right bits. This
1805 sets C<$vec> to have bit N set only if C<$ints[N]> was set:
1806
1807         @ints = (...); # array of bits, e.g. ( 1, 0, 0, 1, 1, 0 ... )
1808         $vec = '';
1809         foreach( 0 .. $#ints ) {
1810                 vec($vec,$_,1) = 1 if $ints[$_];
1811                 }
1812
1813 The string C<$vec> only takes up as many bits as it needs. For
1814 instance, if you had 16 entries in C<@ints>, C<$vec> only needs two
1815 bytes to store them (not counting the scalar variable overhead).
1816
1817 Here's how, given a vector in C<$vec>, you can get those bits into
1818 your C<@ints> array:
1819
1820         sub bitvec_to_list {
1821                 my $vec = shift;
1822                 my @ints;
1823                 # Find null-byte density then select best algorithm
1824                 if ($vec =~ tr/\0// / length $vec > 0.95) {
1825                         use integer;
1826                         my $i;
1827
1828                         # This method is faster with mostly null-bytes
1829                         while($vec =~ /[^\0]/g ) {
1830                                 $i = -9 + 8 * pos $vec;
1831                                 push @ints, $i if vec($vec, ++$i, 1);
1832                                 push @ints, $i if vec($vec, ++$i, 1);
1833                                 push @ints, $i if vec($vec, ++$i, 1);
1834                                 push @ints, $i if vec($vec, ++$i, 1);
1835                                 push @ints, $i if vec($vec, ++$i, 1);
1836                                 push @ints, $i if vec($vec, ++$i, 1);
1837                                 push @ints, $i if vec($vec, ++$i, 1);
1838                                 push @ints, $i if vec($vec, ++$i, 1);
1839                                 }
1840                         }
1841                 else {
1842                         # This method is a fast general algorithm
1843                         use integer;
1844                         my $bits = unpack "b*", $vec;
1845                         push @ints, 0 if $bits =~ s/^(\d)// && $1;
1846                         push @ints, pos $bits while($bits =~ /1/g);
1847                         }
1848
1849                 return \@ints;
1850                 }
1851
1852 This method gets faster the more sparse the bit vector is.
1853 (Courtesy of Tim Bunce and Winfried Koenig.)
1854
1855 You can make the while loop a lot shorter with this suggestion
1856 from Benjamin Goldberg:
1857
1858         while($vec =~ /[^\0]+/g ) {
1859                 push @ints, grep vec($vec, $_, 1), $-[0] * 8 .. $+[0] * 8;
1860                 }
1861
1862 Or use the CPAN module C<Bit::Vector>:
1863
1864         $vector = Bit::Vector->new($num_of_bits);
1865         $vector->Index_List_Store(@ints);
1866         @ints = $vector->Index_List_Read();
1867
1868 C<Bit::Vector> provides efficient methods for bit vector, sets of
1869 small integers and "big int" math.
1870
1871 Here's a more extensive illustration using vec():
1872
1873         # vec demo
1874         $vector = "\xff\x0f\xef\xfe";
1875         print "Ilya's string \\xff\\x0f\\xef\\xfe represents the number ",
1876         unpack("N", $vector), "\n";
1877         $is_set = vec($vector, 23, 1);
1878         print "Its 23rd bit is ", $is_set ? "set" : "clear", ".\n";
1879         pvec($vector);
1880
1881         set_vec(1,1,1);
1882         set_vec(3,1,1);
1883         set_vec(23,1,1);
1884
1885         set_vec(3,1,3);
1886         set_vec(3,2,3);
1887         set_vec(3,4,3);
1888         set_vec(3,4,7);
1889         set_vec(3,8,3);
1890         set_vec(3,8,7);
1891
1892         set_vec(0,32,17);
1893         set_vec(1,32,17);
1894
1895         sub set_vec {
1896                 my ($offset, $width, $value) = @_;
1897                 my $vector = '';
1898                 vec($vector, $offset, $width) = $value;
1899                 print "offset=$offset width=$width value=$value\n";
1900                 pvec($vector);
1901                 }
1902
1903         sub pvec {
1904                 my $vector = shift;
1905                 my $bits = unpack("b*", $vector);
1906                 my $i = 0;
1907                 my $BASE = 8;
1908
1909                 print "vector length in bytes: ", length($vector), "\n";
1910                 @bytes = unpack("A8" x length($vector), $bits);
1911                 print "bits are: @bytes\n\n";
1912                 }
1913
1914 =head2 Why does defined() return true on empty arrays and hashes?
1915
1916 The short story is that you should probably only use defined on scalars or
1917 functions, not on aggregates (arrays and hashes).  See L<perlfunc/defined>
1918 in the 5.004 release or later of Perl for more detail.
1919
1920 =head1 Data: Hashes (Associative Arrays)
1921
1922 =head2 How do I process an entire hash?
1923
1924 (contributed by brian d foy)
1925
1926 There are a couple of ways that you can process an entire hash. You
1927 can get a list of keys, then go through each key, or grab a one
1928 key-value pair at a time.
1929
1930 To go through all of the keys, use the C<keys> function. This extracts
1931 all of the keys of the hash and gives them back to you as a list. You
1932 can then get the value through the particular key you're processing:
1933
1934         foreach my $key ( keys %hash ) {
1935                 my $value = $hash{$key}
1936                 ...
1937                 }
1938
1939 Once you have the list of keys, you can process that list before you
1940 process the hash elements. For instance, you can sort the keys so you
1941 can process them in lexical order:
1942
1943         foreach my $key ( sort keys %hash ) {
1944                 my $value = $hash{$key}
1945                 ...
1946                 }
1947
1948 Or, you might want to only process some of the items. If you only want
1949 to deal with the keys that start with C<text:>, you can select just
1950 those using C<grep>:
1951
1952         foreach my $key ( grep /^text:/, keys %hash ) {
1953                 my $value = $hash{$key}
1954                 ...
1955                 }
1956
1957 If the hash is very large, you might not want to create a long list of
1958 keys. To save some memory, you can grab one key-value pair at a time using
1959 C<each()>, which returns a pair you haven't seen yet:
1960
1961         while( my( $key, $value ) = each( %hash ) ) {
1962                 ...
1963                 }
1964
1965 The C<each> operator returns the pairs in apparently random order, so if
1966 ordering matters to you, you'll have to stick with the C<keys> method.
1967
1968 The C<each()> operator can be a bit tricky though. You can't add or
1969 delete keys of the hash while you're using it without possibly
1970 skipping or re-processing some pairs after Perl internally rehashes
1971 all of the elements. Additionally, a hash has only one iterator, so if
1972 you use C<keys>, C<values>, or C<each> on the same hash, you can reset
1973 the iterator and mess up your processing. See the C<each> entry in
1974 L<perlfunc> for more details.
1975
1976 =head2 How do I merge two hashes?
1977 X<hash> X<merge> X<slice, hash>
1978
1979 (contributed by brian d foy)
1980
1981 Before you decide to merge two hashes, you have to decide what to do
1982 if both hashes contain keys that are the same and if you want to leave
1983 the original hashes as they were.
1984
1985 If you want to preserve the original hashes, copy one hash (C<%hash1>)
1986 to a new hash (C<%new_hash>), then add the keys from the other hash
1987 (C<%hash2> to the new hash. Checking that the key already exists in
1988 C<%new_hash> gives you a chance to decide what to do with the
1989 duplicates:
1990
1991         my %new_hash = %hash1; # make a copy; leave %hash1 alone
1992
1993         foreach my $key2 ( keys %hash2 )
1994                 {
1995                 if( exists $new_hash{$key2} )
1996                         {
1997                         warn "Key [$key2] is in both hashes!";
1998                         # handle the duplicate (perhaps only warning)
1999                         ...
2000                         next;
2001                         }
2002                 else
2003                         {
2004                         $new_hash{$key2} = $hash2{$key2};
2005                         }
2006                 }
2007
2008 If you don't want to create a new hash, you can still use this looping
2009 technique; just change the C<%new_hash> to C<%hash1>.
2010
2011         foreach my $key2 ( keys %hash2 )
2012                 {
2013                 if( exists $hash1{$key2} )
2014                         {
2015                         warn "Key [$key2] is in both hashes!";
2016                         # handle the duplicate (perhaps only warning)
2017                         ...
2018                         next;
2019                         }
2020                 else
2021                         {
2022                         $hash1{$key2} = $hash2{$key2};
2023                         }
2024                 }
2025
2026 If you don't care that one hash overwrites keys and values from the other, you
2027 could just use a hash slice to add one hash to another. In this case, values
2028 from C<%hash2> replace values from C<%hash1> when they have keys in common:
2029
2030         @hash1{ keys %hash2 } = values %hash2;
2031
2032 =head2 What happens if I add or remove keys from a hash while iterating over it?
2033
2034 (contributed by brian d foy)
2035
2036 The easy answer is "Don't do that!"
2037
2038 If you iterate through the hash with each(), you can delete the key
2039 most recently returned without worrying about it.  If you delete or add
2040 other keys, the iterator may skip or double up on them since perl
2041 may rearrange the hash table.  See the
2042 entry for C<each()> in L<perlfunc>.
2043
2044 =head2 How do I look up a hash element by value?
2045
2046 Create a reverse hash:
2047
2048         %by_value = reverse %by_key;
2049         $key = $by_value{$value};
2050
2051 That's not particularly efficient.  It would be more space-efficient
2052 to use:
2053
2054         while (($key, $value) = each %by_key) {
2055                 $by_value{$value} = $key;
2056             }
2057
2058 If your hash could have repeated values, the methods above will only find
2059 one of the associated keys.   This may or may not worry you.  If it does
2060 worry you, you can always reverse the hash into a hash of arrays instead:
2061
2062         while (($key, $value) = each %by_key) {
2063                  push @{$key_list_by_value{$value}}, $key;
2064                 }
2065
2066 =head2 How can I know how many entries are in a hash?
2067
2068 (contributed by brian d foy)
2069
2070 This is very similar to "How do I process an entire hash?", also in
2071 L<perlfaq4>, but a bit simpler in the common cases.
2072
2073 You can use the C<keys()> built-in function in scalar context to find out
2074 have many entries you have in a hash:
2075
2076         my $key_count = keys %hash; # must be scalar context!
2077         
2078 If you want to find out how many entries have a defined value, that's
2079 a bit different. You have to check each value. A C<grep> is handy: 
2080
2081         my $defined_value_count = grep { defined } values %hash;
2082
2083 You can use that same structure to count the entries any way that
2084 you like. If you want the count of the keys with vowels in them,
2085 you just test for that instead:
2086
2087         my $vowel_count = grep { /[aeiou]/ } keys %hash;
2088         
2089 The C<grep> in scalar context returns the count. If you want the list
2090 of matching items, just use it in list context instead:
2091
2092         my @defined_values = grep { defined } values %hash;
2093
2094 The C<keys()> function also resets the iterator, which means that you may
2095 see strange results if you use this between uses of other hash operators
2096 such as C<each()>.
2097
2098 =head2 How do I sort a hash (optionally by value instead of key)?
2099
2100 (contributed by brian d foy)
2101
2102 To sort a hash, start with the keys. In this example, we give the list of
2103 keys to the sort function which then compares them ASCIIbetically (which
2104 might be affected by your locale settings). The output list has the keys
2105 in ASCIIbetical order. Once we have the keys, we can go through them to
2106 create a report which lists the keys in ASCIIbetical order.
2107
2108         my @keys = sort { $a cmp $b } keys %hash;
2109
2110         foreach my $key ( @keys )
2111                 {
2112                 printf "%-20s %6d\n", $key, $hash{$key};
2113                 }
2114
2115 We could get more fancy in the C<sort()> block though. Instead of
2116 comparing the keys, we can compute a value with them and use that
2117 value as the comparison.
2118
2119 For instance, to make our report order case-insensitive, we use
2120 the C<\L> sequence in a double-quoted string to make everything
2121 lowercase. The C<sort()> block then compares the lowercased
2122 values to determine in which order to put the keys.
2123
2124         my @keys = sort { "\L$a" cmp "\L$b" } keys %hash;
2125
2126 Note: if the computation is expensive or the hash has many elements,
2127 you may want to look at the Schwartzian Transform to cache the
2128 computation results.
2129
2130 If we want to sort by the hash value instead, we use the hash key
2131 to look it up. We still get out a list of keys, but this time they
2132 are ordered by their value.
2133
2134         my @keys = sort { $hash{$a} <=> $hash{$b} } keys %hash;
2135
2136 From there we can get more complex. If the hash values are the same,
2137 we can provide a secondary sort on the hash key.
2138
2139         my @keys = sort {
2140                 $hash{$a} <=> $hash{$b}
2141                         or
2142                 "\L$a" cmp "\L$b"
2143                 } keys %hash;
2144
2145 =head2 How can I always keep my hash sorted?
2146 X<hash tie sort DB_File Tie::IxHash>
2147
2148 You can look into using the C<DB_File> module and C<tie()> using the
2149 C<$DB_BTREE> hash bindings as documented in L<DB_File/"In Memory
2150 Databases">. The C<Tie::IxHash> module from CPAN might also be
2151 instructive. Although this does keep your hash sorted, you might not
2152 like the slow down you suffer from the tie interface. Are you sure you
2153 need to do this? :)
2154
2155 =head2 What's the difference between "delete" and "undef" with hashes?
2156
2157 Hashes contain pairs of scalars: the first is the key, the
2158 second is the value.  The key will be coerced to a string,
2159 although the value can be any kind of scalar: string,
2160 number, or reference.  If a key C<$key> is present in
2161 %hash, C<exists($hash{$key})> will return true.  The value
2162 for a given key can be C<undef>, in which case
2163 C<$hash{$key}> will be C<undef> while C<exists $hash{$key}>
2164 will return true.  This corresponds to (C<$key>, C<undef>)
2165 being in the hash.
2166
2167 Pictures help...  here's the C<%hash> table:
2168
2169           keys  values
2170         +------+------+
2171         |  a   |  3   |
2172         |  x   |  7   |
2173         |  d   |  0   |
2174         |  e   |  2   |
2175         +------+------+
2176
2177 And these conditions hold
2178
2179         $hash{'a'}                       is true
2180         $hash{'d'}                       is false
2181         defined $hash{'d'}               is true
2182         defined $hash{'a'}               is true
2183         exists $hash{'a'}                is true (Perl 5 only)
2184         grep ($_ eq 'a', keys %hash)     is true
2185
2186 If you now say
2187
2188         undef $hash{'a'}
2189
2190 your table now reads:
2191
2192
2193           keys  values
2194         +------+------+
2195         |  a   | undef|
2196         |  x   |  7   |
2197         |  d   |  0   |
2198         |  e   |  2   |
2199         +------+------+
2200
2201 and these conditions now hold; changes in caps:
2202
2203         $hash{'a'}                       is FALSE
2204         $hash{'d'}                       is false
2205         defined $hash{'d'}               is true
2206         defined $hash{'a'}               is FALSE
2207         exists $hash{'a'}                is true (Perl 5 only)
2208         grep ($_ eq 'a', keys %hash)     is true
2209
2210 Notice the last two: you have an undef value, but a defined key!
2211
2212 Now, consider this:
2213
2214         delete $hash{'a'}
2215
2216 your table now reads:
2217
2218           keys  values
2219         +------+------+
2220         |  x   |  7   |
2221         |  d   |  0   |
2222         |  e   |  2   |
2223         +------+------+
2224
2225 and these conditions now hold; changes in caps:
2226
2227         $hash{'a'}                       is false
2228         $hash{'d'}                       is false
2229         defined $hash{'d'}               is true
2230         defined $hash{'a'}               is false
2231         exists $hash{'a'}                is FALSE (Perl 5 only)
2232         grep ($_ eq 'a', keys %hash)     is FALSE
2233
2234 See, the whole entry is gone!
2235
2236 =head2 Why don't my tied hashes make the defined/exists distinction?
2237
2238 This depends on the tied hash's implementation of EXISTS().
2239 For example, there isn't the concept of undef with hashes
2240 that are tied to DBM* files. It also means that exists() and
2241 defined() do the same thing with a DBM* file, and what they
2242 end up doing is not what they do with ordinary hashes.
2243
2244 =head2 How do I reset an each() operation part-way through?
2245
2246 (contributed by brian d foy)
2247
2248 You can use the C<keys> or C<values> functions to reset C<each>. To
2249 simply reset the iterator used by C<each> without doing anything else,
2250 use one of them in void context:
2251
2252         keys %hash; # resets iterator, nothing else.
2253         values %hash; # resets iterator, nothing else.
2254
2255 See the documentation for C<each> in L<perlfunc>.
2256
2257 =head2 How can I get the unique keys from two hashes?
2258
2259 First you extract the keys from the hashes into lists, then solve
2260 the "removing duplicates" problem described above.  For example:
2261
2262         %seen = ();
2263         for $element (keys(%foo), keys(%bar)) {
2264                 $seen{$element}++;
2265                 }
2266         @uniq = keys %seen;
2267
2268 Or more succinctly:
2269
2270         @uniq = keys %{{%foo,%bar}};
2271
2272 Or if you really want to save space:
2273
2274         %seen = ();
2275         while (defined ($key = each %foo)) {
2276                 $seen{$key}++;
2277         }
2278         while (defined ($key = each %bar)) {
2279                 $seen{$key}++;
2280         }
2281         @uniq = keys %seen;
2282
2283 =head2 How can I store a multidimensional array in a DBM file?
2284
2285 Either stringify the structure yourself (no fun), or else
2286 get the MLDBM (which uses Data::Dumper) module from CPAN and layer
2287 it on top of either DB_File or GDBM_File.
2288
2289 =head2 How can I make my hash remember the order I put elements into it?
2290
2291 Use the C<Tie::IxHash> from CPAN.
2292
2293         use Tie::IxHash;
2294
2295         tie my %myhash, 'Tie::IxHash';
2296
2297         for (my $i=0; $i<20; $i++) {
2298                 $myhash{$i} = 2*$i;
2299                 }
2300
2301         my @keys = keys %myhash;
2302         # @keys = (0,1,2,3,...)
2303
2304 =head2 Why does passing a subroutine an undefined element in a hash create it?
2305
2306 (contributed by brian d foy)
2307
2308 Are you using a really old version of Perl?
2309
2310 Normally, accessing a hash key's value for a nonexistent key will
2311 I<not> create the key.
2312
2313         my %hash  = ();
2314         my $value = $hash{ 'foo' };
2315         print "This won't print\n" if exists $hash{ 'foo' };
2316
2317 Passing C<$hash{ 'foo' }> to a subroutine used to be a special case, though.
2318 Since you could assign directly to C<$_[0]>, Perl had to be ready to
2319 make that assignment so it created the hash key ahead of time:
2320
2321     my_sub( $hash{ 'foo' } );
2322         print "This will print before 5.004\n" if exists $hash{ 'foo' };
2323
2324         sub my_sub {
2325                 # $_[0] = 'bar'; # create hash key in case you do this
2326                 1;
2327                 }
2328
2329 Since Perl 5.004, however, this situation is a special case and Perl
2330 creates the hash key only when you make the assignment:
2331
2332     my_sub( $hash{ 'foo' } );
2333         print "This will print, even after 5.004\n" if exists $hash{ 'foo' };
2334
2335         sub my_sub {
2336                 $_[0] = 'bar';
2337                 }
2338
2339 However, if you want the old behavior (and think carefully about that
2340 because it's a weird side effect), you can pass a hash slice instead.
2341 Perl 5.004 didn't make this a special case:
2342
2343         my_sub( @hash{ qw/foo/ } );
2344
2345 =head2 How can I make the Perl equivalent of a C structure/C++ class/hash or array of hashes or arrays?
2346
2347 Usually a hash ref, perhaps like this:
2348
2349         $record = {
2350                 NAME   => "Jason",
2351                 EMPNO  => 132,
2352                 TITLE  => "deputy peon",
2353                 AGE    => 23,
2354                 SALARY => 37_000,
2355                 PALS   => [ "Norbert", "Rhys", "Phineas"],
2356         };
2357
2358 References are documented in L<perlref> and the upcoming L<perlreftut>.
2359 Examples of complex data structures are given in L<perldsc> and
2360 L<perllol>.  Examples of structures and object-oriented classes are
2361 in L<perltoot>.
2362
2363 =head2 How can I use a reference as a hash key?
2364
2365 (contributed by brian d foy and Ben Morrow)
2366
2367 Hash keys are strings, so you can't really use a reference as the key.
2368 When you try to do that, perl turns the reference into its stringified
2369 form (for instance, C<HASH(0xDEADBEEF)>). From there you can't get
2370 back the reference from the stringified form, at least without doing
2371 some extra work on your own.
2372
2373 Remember that the entry in the hash will still be there even if
2374 the referenced variable  goes out of scope, and that it is entirely
2375 possible for Perl to subsequently allocate a different variable at
2376 the same address. This will mean a new variable might accidentally
2377 be associated with the value for an old.
2378
2379 If you have Perl 5.10 or later, and you just want to store a value
2380 against the reference for lookup later, you can use the core
2381 Hash::Util::Fieldhash module. This will also handle renaming the
2382 keys if you use multiple threads (which causes all variables to be
2383 reallocated at new addresses, changing their stringification), and
2384 garbage-collecting the entries when the referenced variable goes out
2385 of scope.
2386
2387 If you actually need to be able to get a real reference back from
2388 each hash entry, you can use the Tie::RefHash module, which does the
2389 required work for you.
2390
2391 =head1 Data: Misc
2392
2393 =head2 How do I handle binary data correctly?
2394
2395 Perl is binary clean, so it can handle binary data just fine.
2396 On Windows or DOS, however, you have to use C<binmode> for binary
2397 files to avoid conversions for line endings. In general, you should
2398 use C<binmode> any time you want to work with binary data.
2399
2400 Also see L<perlfunc/"binmode"> or L<perlopentut>.
2401
2402 If you're concerned about 8-bit textual data then see L<perllocale>.
2403 If you want to deal with multibyte characters, however, there are
2404 some gotchas.  See the section on Regular Expressions.
2405
2406 =head2 How do I determine whether a scalar is a number/whole/integer/float?
2407
2408 Assuming that you don't care about IEEE notations like "NaN" or
2409 "Infinity", you probably just want to use a regular expression.
2410
2411         if (/\D/)            { print "has nondigits\n" }
2412         if (/^\d+$/)         { print "is a whole number\n" }
2413         if (/^-?\d+$/)       { print "is an integer\n" }
2414         if (/^[+-]?\d+$/)    { print "is a +/- integer\n" }
2415         if (/^-?\d+\.?\d*$/) { print "is a real number\n" }
2416         if (/^-?(?:\d+(?:\.\d*)?|\.\d+)$/) { print "is a decimal number\n" }
2417         if (/^([+-]?)(?=\d|\.\d)\d*(\.\d*)?([Ee]([+-]?\d+))?$/)
2418                         { print "a C float\n" }
2419
2420 There are also some commonly used modules for the task.
2421 L<Scalar::Util> (distributed with 5.8) provides access to perl's
2422 internal function C<looks_like_number> for determining whether a
2423 variable looks like a number.  L<Data::Types> exports functions that
2424 validate data types using both the above and other regular
2425 expressions. Thirdly, there is C<Regexp::Common> which has regular
2426 expressions to match various types of numbers. Those three modules are
2427 available from the CPAN.
2428
2429 If you're on a POSIX system, Perl supports the C<POSIX::strtod>
2430 function.  Its semantics are somewhat cumbersome, so here's a
2431 C<getnum> wrapper function for more convenient access.  This function
2432 takes a string and returns the number it found, or C<undef> for input
2433 that isn't a C float.  The C<is_numeric> function is a front end to
2434 C<getnum> if you just want to say, "Is this a float?"
2435
2436         sub getnum {
2437                 use POSIX qw(strtod);
2438                 my $str = shift;
2439                 $str =~ s/^\s+//;
2440                 $str =~ s/\s+$//;
2441                 $! = 0;
2442                 my($num, $unparsed) = strtod($str);
2443                 if (($str eq '') || ($unparsed != 0) || $!) {
2444                                 return undef;
2445                         }
2446                 else {
2447                         return $num;
2448                         }
2449                 }
2450
2451         sub is_numeric { defined getnum($_[0]) }
2452
2453 Or you could check out the L<String::Scanf> module on the CPAN
2454 instead. The C<POSIX> module (part of the standard Perl distribution)
2455 provides the C<strtod> and C<strtol> for converting strings to double
2456 and longs, respectively.
2457
2458 =head2 How do I keep persistent data across program calls?
2459
2460 For some specific applications, you can use one of the DBM modules.
2461 See L<AnyDBM_File>.  More generically, you should consult the C<FreezeThaw>
2462 or C<Storable> modules from CPAN.  Starting from Perl 5.8 C<Storable> is part
2463 of the standard distribution.  Here's one example using C<Storable>'s C<store>
2464 and C<retrieve> functions:
2465
2466         use Storable;
2467         store(\%hash, "filename");
2468
2469         # later on...
2470         $href = retrieve("filename");        # by ref
2471         %hash = %{ retrieve("filename") };   # direct to hash
2472
2473 =head2 How do I print out or copy a recursive data structure?
2474
2475 The C<Data::Dumper> module on CPAN (or the 5.005 release of Perl) is great
2476 for printing out data structures.  The C<Storable> module on CPAN (or the
2477 5.8 release of Perl), provides a function called C<dclone> that recursively
2478 copies its argument.
2479
2480         use Storable qw(dclone);
2481         $r2 = dclone($r1);
2482
2483 Where C<$r1> can be a reference to any kind of data structure you'd like.
2484 It will be deeply copied.  Because C<dclone> takes and returns references,
2485 you'd have to add extra punctuation if you had a hash of arrays that
2486 you wanted to copy.
2487
2488         %newhash = %{ dclone(\%oldhash) };
2489
2490 =head2 How do I define methods for every class/object?
2491
2492 (contributed by Ben Morrow)
2493
2494 You can use the C<UNIVERSAL> class (see L<UNIVERSAL>). However, please
2495 be very careful to consider the consequences of doing this: adding
2496 methods to every object is very likely to have unintended
2497 consequences. If possible, it would be better to have all your object
2498 inherit from some common base class, or to use an object system like
2499 Moose that supports roles.
2500
2501 =head2 How do I verify a credit card checksum?
2502
2503 Get the C<Business::CreditCard> module from CPAN.
2504
2505 =head2 How do I pack arrays of doubles or floats for XS code?
2506
2507 The arrays.h/arrays.c code in the C<PGPLOT> module on CPAN does just this.
2508 If you're doing a lot of float or double processing, consider using
2509 the C<PDL> module from CPAN instead--it makes number-crunching easy.
2510
2511 See L<http://search.cpan.org/dist/PGPLOT> for the code.
2512
2513 =head1 REVISION
2514
2515 Revision: $Revision$
2516
2517 Date: $Date$
2518
2519 See L<perlfaq> for source control details and availability.
2520
2521 =head1 AUTHOR AND COPYRIGHT
2522
2523 Copyright (c) 1997-2009 Tom Christiansen, Nathan Torkington, and
2524 other authors as noted. All rights reserved.
2525
2526 This documentation is free; you can redistribute it and/or modify it
2527 under the same terms as Perl itself.
2528
2529 Irrespective of its distribution, all code examples in this file
2530 are hereby placed into the public domain.  You are permitted and
2531 encouraged to use this code in your own programs for fun
2532 or for profit as you see fit.  A simple comment in the code giving
2533 credit would be courteous but is not required.