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