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