3 perlfaq4 - Data Manipulation
7 This section of the FAQ answers questions related to manipulating
8 numbers, dates, strings, arrays, hashes, and miscellaneous data issues.
12 =head2 Why am I getting long decimals (eg, 19.9499999999999) instead of the numbers I should be getting (eg, 19.95)?
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>).
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.
24 L<perlnumber> shows the gory details of number representations and
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.
33 my $number = sprintf "%.2f", 10/3;
35 =head2 Why is int() broken?
37 Your C<int()> is most probably working just fine. It's the numbers that
38 aren't quite what you think.
40 First, see the answer to "Why am I getting long decimals
41 (eg, 19.9499999999999) instead of the numbers I should be getting
46 print int(0.6/0.2-2), "\n";
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.
53 =head2 Why isn't my octal data interpreted correctly?
55 (contributed by brian d foy)
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
64 print $string + 0; # prints 644
66 print $string + 44; # prints 688, certainly not octal!
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:
73 %prompt> chmod 644 file
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>:
79 chmod( 0644, $file); # right, has leading zero
80 chmod( oct(644), $file ); # also correct
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>:
85 chmod( $ARGV[0], $file); # wrong, even if "0644"
87 chmod( oct($ARGV[0]), $file ); # correct, treat string as octal
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:
93 printf "0%o %d", $number, $number;
95 =head2 Does Perl have a round() function? What about ceil() and floor()? Trig functions?
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
101 printf("%.3f", 3.1415926535); # prints 3.142
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.
108 $ceil = ceil(3.5); # 4
109 $floor = floor(3.5); # 3
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
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
124 To see why, notice how you'll still have an issue on half-way-point
127 for ($i = 0; $i < 1.01; $i += 0.05) { printf "%.1f ",$i}
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
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.
137 =head2 How do I convert between numeric representations/bases/radixes?
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
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.
152 =item How do I convert hexadecimal into decimal
154 Using perl's built in conversion of C<0x> notation:
158 Using the C<hex> function:
160 $dec = hex("DEADBEEF");
164 $dec = unpack("N", pack("H8", substr("0" x 8 . "DEADBEEF", -8)));
166 Using the CPAN module C<Bit::Vector>:
169 $vec = Bit::Vector->new_Hex(32, "DEADBEEF");
170 $dec = $vec->to_Dec();
172 =item How do I convert from decimal to hexadecimal
176 $hex = sprintf("%X", 3735928559); # upper case A-F
177 $hex = sprintf("%x", 3735928559); # lower case a-f
181 $hex = unpack("H*", pack("N", 3735928559));
183 Using C<Bit::Vector>:
186 $vec = Bit::Vector->new_Dec(32, -559038737);
187 $hex = $vec->to_Hex();
189 And C<Bit::Vector> supports odd bit counts:
192 $vec = Bit::Vector->new_Dec(33, 3735928559);
193 $vec->Resize(32); # suppress leading 0 if unwanted
194 $hex = $vec->to_Hex();
196 =item How do I convert from octal to decimal
198 Using Perl's built in conversion of numbers with leading zeros:
200 $dec = 033653337357; # note the leading 0!
202 Using the C<oct> function:
204 $dec = oct("33653337357");
206 Using C<Bit::Vector>:
209 $vec = Bit::Vector->new(32);
210 $vec->Chunk_List_Store(3, split(//, reverse "33653337357"));
211 $dec = $vec->to_Dec();
213 =item How do I convert from decimal to octal
217 $oct = sprintf("%o", 3735928559);
219 Using C<Bit::Vector>:
222 $vec = Bit::Vector->new_Dec(32, -559038737);
223 $oct = reverse join('', $vec->Chunk_List_Read(3));
225 =item How do I convert from binary to decimal
227 Perl 5.6 lets you write binary numbers directly with
230 $number = 0b10110110;
234 my $input = "10110110";
235 $decimal = oct( "0b$input" );
237 Using C<pack> and C<ord>:
239 $decimal = ord(pack('B8', '10110110'));
241 Using C<pack> and C<unpack> for larger strings:
243 $int = unpack("N", pack("B32",
244 substr("0" x 32 . "11110101011011011111011101111", -32)));
245 $dec = sprintf("%d", $int);
247 # substr() is used to left-pad a 32-character string with zeros.
249 Using C<Bit::Vector>:
251 $vec = Bit::Vector->new_Bin(32, "11011110101011011011111011101111");
252 $dec = $vec->to_Dec();
254 =item How do I convert from decimal to binary
256 Using C<sprintf> (perl 5.6+):
258 $bin = sprintf("%b", 3735928559);
262 $bin = unpack("B*", pack("N", 3735928559));
264 Using C<Bit::Vector>:
267 $vec = Bit::Vector->new_Dec(32, -559038737);
268 $bin = $vec->to_Bin();
270 The remaining transformations (e.g. hex -> oct, bin -> hex, etc.)
271 are left as an exercise to the inclined reader.
275 =head2 Why doesn't & work the way I want it to?
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>).
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
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
293 if ("\020\020" & "\101\101") {
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:
300 if ( ("\020\020" & "\101\101") !~ /[^\000]/) {
304 =head2 How do I multiply matrices?
306 Use the C<Math::Matrix> or C<Math::MatrixReal> modules (available from CPAN)
307 or the C<PDL> extension (also available from CPAN).
309 =head2 How do I perform an operation on a series of integers?
311 To call a function on each element in an array, and collect the
314 @results = map { my_func($_) } @array;
318 @triple = map { 3 * $_ } @single;
320 To call a function on each element of an array, but ignore the
323 foreach $iterator (@array) {
324 some_func($iterator);
327 To call a function on each integer in a (small) range, you B<can> use:
329 @results = map { some_func($_) } (5 .. 25);
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
336 for ($i=5; $i <= 500_005; $i++) {
337 push(@results, some_func($i));
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.
343 for my $i (5 .. 500_005) {
344 push(@results, some_func($i));
347 will not create a list of 500,000 integers.
349 =head2 How can I output Roman numerals?
351 Get the L<http://www.cpan.org/modules/by-module/Roman> module.
353 =head2 Why aren't my random numbers random?
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.
358 BEGIN { srand() if $] < 5.004 }
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,
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."
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/>.
379 =head2 How do I get a random number between X and Y?
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.
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>.
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.
392 my $number = 10 + int rand( 15-10+1 ); # ( 10,11,12,13,14, or 15 )
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)>.
398 sub random_int_between {
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);
408 =head2 How do I find the day or week of the year?
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.
414 my $day_of_year = (localtime)[7];
416 The C<POSIX> module can also format a date as the day of the year or
419 use POSIX qw/strftime/;
420 my $day_of_year = strftime "%j", localtime;
421 my $week_of_year = strftime "%W", localtime;
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>.
426 use POSIX qw/mktime strftime/;
427 my $week_of_year = strftime "%W",
428 localtime( mktime( 0, 0, 0, 18, 11, 87 ) );
430 You can also use C<Time::Piece>, which comes with Perl and provides a
431 C<localtime> that returns an object:
434 my $day_of_year = localtime->yday;
435 my $week_of_year = localtime->week;
437 The C<Date::Calc> module provides two functions to calculate these, too:
440 my $day_of_year = Day_of_Year( 1987, 12, 18 );
441 my $week_of_year = Week_of_Year( 1987, 12, 18 );
443 =head2 How do I find the current century or millennium?
445 Use the following simple functions:
448 return int((((localtime(shift || time))[5] + 1999))/100);
452 return 1+int((((localtime(shift || time))[5] + 1899))/1000);
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
462 =head2 How can I compare two dates and find the difference?
464 (contributed by brian d foy)
466 You could just store all your dates as a number and then subtract.
467 Life isn't always that simple though.
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:
474 my $date1 = localtime( $some_time );
475 my $date2 = localtime( $some_other_time );
477 if( $date1 < $date2 ) {
478 print "The date was in the past\n";
481 You can also get differences with a subtraction, which returns a
482 C<Time::Seconds> object:
484 my $diff = $date1 - $date2;
485 print "The difference is ", $date_diff->days, " days\n";
487 If you want to work with formatted dates, the C<Date::Manip>,
488 C<Date::Calc>, or C<DateTime> modules can help you.
490 =head2 How can I take a string and turn it into epoch seconds?
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.
497 =head2 How can I find the Julian Day?
499 (contributed by brian d foy and Dave Cross)
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:
504 $ perl -MTime::Piece -le 'print localtime->julian_day'
507 Or the modified Julian Day:
509 $ perl -MTime::Piece -le 'print localtime->mjd'
512 Or even the day of the year (which is what some people think of as a
515 $ perl -MTime::Piece -le 'print localtime->yday'
518 You can also do the same things with the C<DateTime> module:
520 $ perl -MDateTime -le'print DateTime->today->jd'
522 $ perl -MDateTime -le'print DateTime->today->mjd'
524 $ perl -MDateTime -le'print DateTime->today->doy'
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
532 $ perl -MTime::JulianDay -le 'print local_julian_day( time )'
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>
540 (contributed by brian d foy)
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:
549 my $yesterday = DateTime->now->subtract( days => 1 );
551 print "Yesterday was $yesterday\n";
553 You can also use the C<Date::Calc> module using its C<Today_and_Now>
556 use Date::Calc qw( Today_and_Now Add_Delta_DHMS );
558 my @date_time = Add_Delta_DHMS( Today_and_Now(), -1, 0, 0, 0 );
560 print "@date_time\n";
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:
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
575 my $yesterday = localtime() - ONE_DAY; # WRONG
576 print "Yesterday was $yesterday\n";
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
585 You have the same problem with C<Time::Local>, which will give the wrong
586 answer for those same special cases:
588 # contributed by Gunnar Hjalmarsson
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;
594 =head2 Does Perl have a Year 2000 or 2038 problem? Is Perl Y2K compliant?
596 (contributed by brian d foy)
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.
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>:
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
610 On a 64-bit C<perl>, you can get even larger dates for those really long
613 % perl5.12 -E 'say scalar gmtime( 0x9FFF_FFFFFFFF )'
614 Thu Nov 2 00:42:39 5576711
616 You're still out of luck if you need to keep track of decaying protons
621 =head2 How do I validate input?
623 (contributed by brian d foy)
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>.
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>.
634 =head2 How do I unescape a string?
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
642 This won't expand C<"\n"> or C<"\t"> or any other special escapes.
644 =head2 How do I remove consecutive pairs of characters?
646 (contributed by brian d foy)
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>.
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
666 my $str = 'Haarlem'; # in the Netherlands
667 $str =~ tr///cs; # Now Harlem, like in New York
669 =head2 How do I expand function calls in a string?
671 (contributed by brian d foy)
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.
679 print "The time values are @{ [localtime] }.\n";
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:
688 print "The time is ${\(scalar localtime)}.\n"
690 print "The time is ${ my $x = localtime; \$x }.\n";
692 If your function already returns a reference, you don't need to create
693 the reference yourself.
695 sub timestamp { my $t = localtime; \$t }
697 print "The time is ${ timestamp() }.\n";
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
704 use Interpolation E => 'eval';
705 print "The time values are $E{localtime()}.\n";
707 In most cases, it is probably easier to simply use string concatenation,
708 which also forces scalar context.
710 print "The time is " . localtime() . ".\n";
712 =head2 How do I find matching/nesting anything?
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
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.
730 One simple destructive, inside-out approach that you might try is to
731 pull out the smallest nesting parts one at a time:
733 while (s/BEGIN((?:(?!BEGIN)(?!END).)*)END//gs) {
734 # do something with $1
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
742 # $_ contains the string to parse
743 # BEGIN and END are the opening and closing markers for the
748 ($re=$_)=~s/((BEGIN)|(END)|.)/$)[!$3]\Q$1\E$([!$2]/gs;
749 @$ = (eval{/$re/},$@!~/unmatched/i);
750 print join("\n",@$[0..$#$]) if( $$[-1] );
752 =head2 How do I reverse a string?
754 Use C<reverse()> in scalar context, as documented in
757 $reversed = reverse $string;
759 =head2 How do I expand tabs in a string?
761 You can do it yourself:
763 1 while $string =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e;
765 Or you can just use the C<Text::Tabs> module (part of the standard Perl
769 @expanded_lines = expand(@lines_with_tabs);
771 =head2 How do I reformat a paragraph?
773 Use C<Text::Wrap> (part of the standard Perl distribution):
776 print wrap("\t", ' ', @paragraphs);
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).
781 Or use the CPAN module C<Text::Autoformat>. Formatting files can be
782 easily done by making a shell alias, like so:
784 alias fmt="perl -i -MText::Autoformat -n0777 \
785 -e 'print autoformat $_, {all=>1}' $*"
787 See the documentation for C<Text::Autoformat> to appreciate its many
790 =head2 How can I access or change N characters of a string?
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.
797 $string = "Just another Perl Hacker";
798 $first_char = substr( $string, 0, 1 ); # 'J'
800 To change part of a string, you can use the optional fourth
801 argument which is the replacement string.
803 substr( $string, 13, 4, "Perl 5.8.0" );
805 You can also use substr() as an lvalue.
807 substr( $string, 13, 4 ) = "Perl 5.8.0";
809 =head2 How do I change the Nth occurrence of something?
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.
818 ++$count == 5 # is it the 5th?
819 ? "${2}soever" # yes, swap
820 : $1 # renege and leave it there
823 In the more general case, you can use the C</g> modifier in a C<while>
824 loop, keeping count of matches.
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";
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:
838 /(?:\w+\s+fish\s+){2}(\w+)\s+fish/i;
840 =head2 How can I count the number of occurrences of a substring within a string?
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:
846 $string = "ThisXlineXhasXsomeXx'sXinXit";
847 $count = ($string =~ tr/X//);
848 print "There are $count X characters in the string";
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
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";
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.
863 $count = () = $string =~ /-\d+/g;
865 =head2 How do I capitalize all the words on one line?
866 X<Text::Autoformat> X<capitalize> X<case, title> X<case, sentence>
868 (contributed by brian d foy)
870 Damian Conway's L<Text::Autoformat> handles all of the thinking
873 use Text::Autoformat;
874 my $x = "Dr. Strangelove or: How I Learned to Stop ".
875 "Worrying and Love the Bomb";
878 for my $style (qw( sentence title highlight )) {
879 print autoformat($x, { case => $style }), "\n";
882 How do you want to capitalize those words?
884 FRED AND BARNEY'S LODGE # all uppercase
885 Fred And Barney's Lodge # title case
886 Fred and Barney's Lodge # highlight case
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:
895 (^\w) #at the beginning of the line
897 (\s\w) #preceded by whitespace
901 $string =~ s/([\w']+)/\u\L$1/g;
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. :)
906 =head2 How can I split a [character]-delimited string except when inside [character]?
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.
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:
916 SAR001,"","Cimetrix, Inc","Bob Smith","CAM",N,8,1,0,7,"Error, Core Dumped"
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>):
924 push(@new, $+) while $text =~ m{
925 "([^\"\\]*(?:\\.[^\"\\]*)*)",? # groups the phrase inside the quotes
929 push(@new, undef) if substr($text,-1,1) eq ',';
931 If you want to represent quotation marks inside a
932 quotation-mark-delimited field, escape them with backslashes (eg,
935 Alternatively, the C<Text::ParseWords> module (part of the standard
936 Perl distribution) lets you say:
938 use Text::ParseWords;
939 @new = quotewords(",", 0, $text);
941 =head2 How do I strip blank space from the beginning/end of a string?
943 (contributed by brian d foy)
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:
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:
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:
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:
979 $string =~ s/^\s+|\s+$//gm;
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:
987 $string =~ s/^[\t\f ]+|[\t\f ]+$//mg;
989 =head2 How do I pad a string with blanks or pad a number with zeroes?
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.
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
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
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
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
1016 # Right padding a string with blanks using pack (will truncate):
1017 $padded = pack("A$pad_len",$text);
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>.
1024 Left and right padding with any character, creating a new string:
1026 $padded = $pad_char x ( $pad_len - length( $text ) ) . $text;
1027 $padded = $text . $pad_char x ( $pad_len - length( $text ) );
1029 Left and right padding with any character, modifying C<$text> directly:
1031 substr( $text, 0, 0 ) = $pad_char x ( $pad_len - length( $text ) );
1032 $text .= $pad_char x ( $pad_len - length( $text ) );
1034 =head2 How do I extract selected columns from a string?
1036 (contributed by brian d foy)
1038 If you know the columns that contain the data, you can
1039 use C<substr> to extract a single column.
1041 my $column = substr( $line, $start_column, $length );
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.
1047 my $line = ' fred barney betty ';
1048 my @columns = split /\s+/, $line;
1049 # ( '', 'fred', 'barney', 'betty' );
1051 my $line = 'fred||barney||betty';
1052 my @columns = split /\|/, $line;
1053 # ( 'fred', '', 'barney', '', 'betty' );
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
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.
1065 my @fields = unpack( $line, "A8 A8 A8 A16 A4" );
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.
1070 =head2 How do I find the soundex value of a string?
1072 (contributed by brian d foy)
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.
1078 =head2 How can I expand variables in text strings?
1080 (contributed by brian d foy)
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>:
1086 my $string = sprintf 'Say hello to %s and %s', $foo, $bar;
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:
1095 $string = 'Say hello to $foo and $bar';
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:
1103 $string =~ s/(\$\w+)/$1/eeg; # 'Say hello to Fred and Barney'
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.
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:
1118 my $string = 'This has $foo and $bar';
1120 my %Replacements = (
1124 # $string =~ s/\$(\w+)/$Replacements{$1}/g;
1125 $string =~ s/\$(\w+)/
1126 exists $Replacements{$1} ? $Replacements{$1} : '???'
1131 =head2 What's wrong with always quoting "$vars"?
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?
1139 If you get used to writing odd things like these:
1142 $new = "$old"; # BAD
1143 somefunc("$var"); # BAD
1145 You'll be in trouble. Those should (in 99.8% of the cases) be
1146 the simpler and more direct:
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
1159 my $oref = "$aref"; # WRONG
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
1167 Stringification also destroys arrays.
1170 print "@lines"; # WRONG - extra blanks
1171 print @lines; # right
1173 =head2 Why don't my E<lt>E<lt>HERE documents work?
1175 Here documents are found in L<perlop>. Check for these three things:
1179 =item There must be no space after the E<lt>E<lt> part.
1181 =item There (probably) should be a semicolon at the end of the opening token
1183 =item You can't (easily) have any space in front of the tag.
1185 =item There needs to be at least a line separator after the end token.
1189 If you want to indent the text in the here document, you
1193 ($VAR = <<HERE_TARGET) =~ s/^\s+//gm;
1198 But the HERE_TARGET must still be flush against the margin.
1199 If you want that indented also, you'll have to quote
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
1208 $quote =~ s/\s+--/\n--/;
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
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));
1223 ($white, $leader) = (/^(\s+)/, '');
1225 s/^\s*?$leader(?:$white)?//gm;
1229 This works with leading special strings, dynamically determined:
1231 $remember_the_main = fix<<' MAIN_INTERPRETER_LOOP';
1234 @@@ SAVEI32(runlevel);
1236 @@@ while ( op = (*op->op_ppaddr)() );
1240 MAIN_INTERPRETER_LOOP
1242 Or with a fixed amount of leading whitespace, with remaining
1243 indentation correctly preserved:
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
1257 =head2 What is the difference between a list and an array?
1259 (contributed by brian d foy)
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:
1266 ( 'dog', 'cat', 'bird' )[2,3];
1270 foreach ( qw( dog cat bird ) ) { ... }
1271 foreach ( @animals ) { ... }
1273 my @three = grep { length == 3 } qw( dog cat bird );
1274 my @three = grep { length == 3 } @animals;
1276 # supply an argument list
1277 wash_animals( qw( dog cat bird ) );
1278 wash_animals( @animals );
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>.
1285 An array can also change its length:
1287 $#animals = 1; # truncate to two elements
1288 $#animals = 10000; # pre-extend to 10,001 elements
1290 You can change an array element, but you can't change a list element:
1292 $animals[0] = 'Rottweiler';
1293 qw( dog cat bird )[0] = 'Rottweiler'; # syntax error!
1295 foreach ( @animals ) {
1296 s/^d/fr/; # works fine
1299 foreach ( qw( dog cat bird ) ) {
1300 s/^d/fr/; # Error! Modification of read only value!
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
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
1313 my $count = @animals; # only works with arrays
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
1320 my $scalar = ( 'dog', 'cat', 'bird' ); # $scalar gets bird
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:
1330 my $scalar = ( 1, 2, 3 ); # $scalar gets 3, accidentally
1332 =head2 What is the difference between $array[1] and @array[1]?
1334 (contributed by brian d foy)
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.
1341 The confusion arises because people incorrectly assume that the sigil
1342 denotes the variable type.
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.
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]>.
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:
1358 $array[1] = <STDIN>;
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:
1364 @array[1] = <STDIN>; # most likely not what you want
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.
1369 =head2 How can I remove duplicate elements from a list or array?
1371 (contributed by brian d foy)
1373 Use a hash. When you think the words "unique" or "duplicated", think
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
1381 my %hash = map { $_, 1 } @array;
1382 # or a hash slice: @hash{ @array } = ();
1383 # or a foreach: $hash{$_} = 1 foreach ( @array );
1385 my @unique = keys %hash;
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.
1392 use List::MoreUtils qw(uniq);
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
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
1410 foreach my $elem ( @array )
1412 next if $seen{ $elem }++;
1413 push @unique, $elem;
1416 You can write this more briefly using a grep, which does the
1420 my @unique = grep { ! $seen{ $_ }++ } @array;
1422 =head2 How can I tell whether a certain element is contained in a list or array?
1424 (portions of this answer contributed by Anno Siegel and brian d foy)
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.
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:
1436 if( $item ~~ @array )
1438 say "The array contains $item"
1441 if( $item ~~ %hash )
1443 say "The hash contains $item"
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:
1451 @blues = qw/azure cerulean teal turquoise lapis-lazuli/;
1453 for (@blues) { $is_blue{$_} = 1 }
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.
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:
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;
1466 Now you check whether $is_tiny_prime[$some_number].
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:
1471 @articles = ( 1..10, 150..2000, 2017 );
1473 for (@articles) { vec($read,$_,1) = 1 }
1475 Now check whether C<vec($read,$n,1)> is true for some C<$n>.
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.
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:
1489 return $_ if &{$code}();
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
1499 my $is_there = grep $_ eq $whatever, @array;
1501 If you want to actually extract the matching elements, simply use grep in
1504 my @matches = grep $_ eq $whatever, @array;
1506 =head2 How do I compute the difference of two arrays? How do I compute the intersection of two arrays?
1508 Use a hash. Here's code to do both and more. It assumes that each
1509 element is unique in a given array:
1511 @union = @intersection = @difference = ();
1513 foreach $element (@array1, @array2) { $count{$element}++ }
1514 foreach $element (keys %count) {
1515 push @union, $element;
1516 push @{ $count{$element} > 1 ? \@intersection : \@difference }, $element;
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.
1522 =head2 How do I test whether two arrays or hashes are equal?
1524 With Perl 5.10 and later, the smart match operator can give you the answer
1525 with the least amount of work:
1529 if( @array1 ~~ @array2 )
1531 say "The arrays are the same";
1534 if( %hash1 ~~ %hash2 ) # doesn't check values!
1536 say "The hash keys are the same";
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.
1543 $are_equal = compare_arrays(\@frogs, \@toads);
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];
1555 For multilevel structures, you may wish to use an approach more
1556 like this one. It uses the CPAN module C<FreezeThaw>:
1558 use FreezeThaw qw(cmpStr);
1559 @a = @b = ( "this", "that", [ "more", "stuff" ] );
1561 printf "a and b contain %s arrays\n",
1562 cmpStr(\@a, \@b) == 0
1566 This approach also works for comparing hashes. Here we'll demonstrate
1567 two different answers:
1569 use FreezeThaw qw(cmpStr cmpStrHard);
1571 %a = %b = ( "this" => "that", "extra" => [ "more", "stuff" ] );
1575 printf "a and b contain %s hashes\n",
1576 cmpStr(\%a, \%b) == 0 ? "the same" : "different";
1578 printf "a and b contain %s hashes\n",
1579 cmpStrHard(\%a, \%b) == 0 ? "the same" : "different";
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.
1586 =head2 How do I find the first array element for which a condition is true?
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
1593 use List::Util qw(first);
1595 my $element = first { /Perl/ } @array;
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.
1601 foreach ( @array ) {
1602 if( /Perl/ ) { $found = $_; last }
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.
1609 my( $found, $index ) = ( undef, -1 );
1610 for( $i = 0; $i < @array; $i++ ) {
1611 if( $array[$i] =~ /Perl/ ) {
1612 $found = $array[$i];
1618 =head2 How do I handle linked lists?
1620 (contributed by brian d foy)
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
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
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.
1638 =head2 How do I handle circular lists?
1639 X<circular> X<array> X<Tie::Cycle> X<Array::Iterator::Circular>
1642 (contributed by brian d foy)
1644 If you want to cycle through an array endlessly, you can increment the
1645 index modulo the number of elements in the array:
1647 my @array = qw( a b c );
1651 print $array[ $i++ % @array ], "\n";
1655 You can also use C<Tie::Cycle> to use a scalar that always has the
1656 next element of the circular array:
1660 tie my $cycle, 'Tie::Cycle', [ qw( FFFFFF 000000 FFFF00 ) ];
1662 print $cycle; # FFFFFF
1663 print $cycle; # 000000
1664 print $cycle; # FFFF00
1666 The C<Array::Iterator::Circular> creates an iterator object for
1669 use Array::Iterator::Circular;
1671 my $color_iterator = Array::Iterator::Circular->new(
1672 qw(red green blue orange)
1675 foreach ( 1 .. 20 ) {
1676 print $color_iterator->next, "\n";
1679 =head2 How do I shuffle an array randomly?
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:
1684 use List::Util 'shuffle';
1686 @shuffled = shuffle(@list);
1688 If not, you can use a Fisher-Yates shuffle.
1690 sub fisher_yates_shuffle {
1691 my $deck = shift; # $deck is a reference to an array
1692 return unless @$deck; # must not be empty!
1696 my $j = int rand ($i+1);
1697 @$deck[$i,$j] = @$deck[$j,$i];
1701 # shuffle my mpeg collection
1703 my @mpeg = <audio/*/*.mp3>;
1704 fisher_yates_shuffle( \@mpeg ); # randomize @mpeg in place
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.
1711 You've probably seen shuffling algorithms that work using splice,
1712 randomly picking another element to swap the current element with
1716 @old = 1 .. 10; # just a demo
1718 push(@new, splice(@old, rand @old, 1));
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.
1726 =head2 How do I process/modify each element of an array?
1728 Use C<for>/C<foreach>:
1731 s/foo/bar/; # change that word
1732 tr/XZ/ZX/; # swap those letters
1735 Here's another; let's compute spherical volumes:
1737 for (@volumes = @radii) { # @volumes has changed parts
1739 $_ *= (4/3) * 3.14159; # this will be constant folded
1742 which can also be done with C<map()> which is made to transform
1743 one list into another:
1745 @volumes = map {$_ ** 3 * (4/3) * 3.14159} @radii;
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.
1752 for $orbit ( values %orbits ) {
1753 ($orbit **= 3) *= (4/3) * 3.14159;
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.
1761 =head2 How do I select a random element from an array?
1763 Use the C<rand()> function (see L<perlfunc/rand>):
1765 $index = rand @array;
1766 $element = $array[$index];
1770 my $element = $array[ rand @array ];
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>
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:
1780 use Algorithm::Permute;
1782 my @array = 'a'..'d';
1783 my $p_iterator = Algorithm::Permute->new ( \@array );
1785 while (my @perm = $p_iterator->next) {
1786 print "next permutation: (@perm)\n";
1789 For even faster execution, you could do:
1791 use Algorithm::Permute;
1793 my @array = 'a'..'d';
1795 Algorithm::Permute::permute {
1796 print "next permutation: (@array)\n";
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:
1805 # Fischer-Krause ordered permutation generator
1810 while ( $code->(@_[@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];
1820 permute { print "@_\n" } split;
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.
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:
1832 use Algorithm::Loops qw(NextPermuteNum);
1835 do { print "@list\n" } while NextPermuteNum @list;
1837 =head2 How do I sort an array by (anything)?
1839 Supply a comparison function to sort() (described in L<perlfunc/sort>):
1841 @list = sort { $a <=> $b } @list;
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.
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
1856 ($item) = /\d+\s*(\S+)/;
1857 push @idx, uc($item);
1859 @sorted = @data[ sort { $idx[$a] cmp $idx[$b] } 0 .. $#idx ];
1861 which could also be written this way, using a trick
1862 that's come to be known as the Schwartzian Transform:
1864 @sorted = map { $_->[0] }
1865 sort { $a->[1] cmp $b->[1] }
1866 map { [ $_, uc( (/\d+\s*(\S+)/)[0]) ] } @data;
1868 If you need to sort on several fields, the following paradigm is useful.
1871 field1($a) <=> field1($b) ||
1872 field2($a) cmp field2($b) ||
1873 field3($a) cmp field3($b)
1876 This can be conveniently combined with precalculation of keys as given
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.
1883 See also the question later in L<perlfaq4> on sorting hashes.
1885 =head2 How do I manipulate arrays of bits?
1887 Use C<pack()> and C<unpack()>, or else C<vec()> and the bitwise
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:
1895 @ints = (...); # array of bits, e.g. ( 1, 0, 0, 1, 1, 0 ... )
1897 foreach( 0 .. $#ints ) {
1898 vec($vec,$_,1) = 1 if $ints[$_];
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).
1905 Here's how, given a vector in C<$vec>, you can get those bits into
1906 your C<@ints> array:
1908 sub bitvec_to_list {
1911 # Find null-byte density then select best algorithm
1912 if ($vec =~ tr/\0// / length $vec > 0.95) {
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);
1930 # This method is a fast general algorithm
1932 my $bits = unpack "b*", $vec;
1933 push @ints, 0 if $bits =~ s/^(\d)// && $1;
1934 push @ints, pos $bits while($bits =~ /1/g);
1940 This method gets faster the more sparse the bit vector is.
1941 (Courtesy of Tim Bunce and Winfried Koenig.)
1943 You can make the while loop a lot shorter with this suggestion
1944 from Benjamin Goldberg:
1946 while($vec =~ /[^\0]+/g ) {
1947 push @ints, grep vec($vec, $_, 1), $-[0] * 8 .. $+[0] * 8;
1950 Or use the CPAN module C<Bit::Vector>:
1952 $vector = Bit::Vector->new($num_of_bits);
1953 $vector->Index_List_Store(@ints);
1954 @ints = $vector->Index_List_Read();
1956 C<Bit::Vector> provides efficient methods for bit vector, sets of
1957 small integers and "big int" math.
1959 Here's a more extensive illustration using vec():
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";
1984 my ($offset, $width, $value) = @_;
1986 vec($vector, $offset, $width) = $value;
1987 print "offset=$offset width=$width value=$value\n";
1993 my $bits = unpack("b*", $vector);
1997 print "vector length in bytes: ", length($vector), "\n";
1998 @bytes = unpack("A8" x length($vector), $bits);
1999 print "bits are: @bytes\n\n";
2002 =head2 Why does defined() return true on empty arrays and hashes?
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.
2008 =head1 Data: Hashes (Associative Arrays)
2010 =head2 How do I process an entire hash?
2012 (contributed by brian d foy)
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.
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:
2022 foreach my $key ( keys %hash ) {
2023 my $value = $hash{$key}
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:
2031 foreach my $key ( sort keys %hash ) {
2032 my $value = $hash{$key}
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>:
2040 foreach my $key ( grep /^text:/, keys %hash ) {
2041 my $value = $hash{$key}
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:
2049 while( my( $key, $value ) = each( %hash ) ) {
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.
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.
2064 =head2 How do I merge two hashes?
2065 X<hash> X<merge> X<slice, hash>
2067 (contributed by brian d foy)
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.
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
2079 my %new_hash = %hash1; # make a copy; leave %hash1 alone
2081 foreach my $key2 ( keys %hash2 )
2083 if( exists $new_hash{$key2} )
2085 warn "Key [$key2] is in both hashes!";
2086 # handle the duplicate (perhaps only warning)
2092 $new_hash{$key2} = $hash2{$key2};
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>.
2099 foreach my $key2 ( keys %hash2 )
2101 if( exists $hash1{$key2} )
2103 warn "Key [$key2] is in both hashes!";
2104 # handle the duplicate (perhaps only warning)
2110 $hash1{$key2} = $hash2{$key2};
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:
2118 @hash1{ keys %hash2 } = values %hash2;
2120 =head2 What happens if I add or remove keys from a hash while iterating over it?
2122 (contributed by brian d foy)
2124 The easy answer is "Don't do that!"
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>.
2132 =head2 How do I look up a hash element by value?
2134 Create a reverse hash:
2136 %by_value = reverse %by_key;
2137 $key = $by_value{$value};
2139 That's not particularly efficient. It would be more space-efficient
2142 while (($key, $value) = each %by_key) {
2143 $by_value{$value} = $key;
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:
2150 while (($key, $value) = each %by_key) {
2151 push @{$key_list_by_value{$value}}, $key;
2154 =head2 How can I know how many entries are in a hash?
2156 (contributed by brian d foy)
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.
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:
2164 my $key_count = keys %hash; # must be scalar context!
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:
2169 my $defined_value_count = grep { defined } values %hash;
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:
2175 my $vowel_count = grep { /[aeiou]/ } keys %hash;
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:
2180 my @defined_values = grep { defined } values %hash;
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
2186 =head2 How do I sort a hash (optionally by value instead of key)?
2188 (contributed by brian d foy)
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.
2196 my @keys = sort { $a cmp $b } keys %hash;
2198 foreach my $key ( @keys )
2200 printf "%-20s %6d\n", $key, $hash{$key};
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.
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.
2212 my @keys = sort { "\L$a" cmp "\L$b" } keys %hash;
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.
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.
2222 my @keys = sort { $hash{$a} <=> $hash{$b} } keys %hash;
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.
2228 $hash{$a} <=> $hash{$b}
2233 =head2 How can I always keep my hash sorted?
2234 X<hash tie sort DB_File Tie::IxHash>
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
2243 =head2 What's the difference between "delete" and "undef" with hashes?
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>)
2255 Pictures help... Here's the C<%hash> table:
2265 And these conditions hold
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
2278 your table now reads:
2289 and these conditions now hold; changes in caps:
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
2298 Notice the last two: you have an undef value, but a defined key!
2304 your table now reads:
2313 and these conditions now hold; changes in caps:
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
2322 See, the whole entry is gone!
2324 =head2 Why don't my tied hashes make the defined/exists distinction?
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.
2332 =head2 How do I reset an each() operation part-way through?
2334 (contributed by brian d foy)
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:
2340 keys %hash; # resets iterator, nothing else.
2341 values %hash; # resets iterator, nothing else.
2343 See the documentation for C<each> in L<perlfunc>.
2345 =head2 How can I get the unique keys from two hashes?
2347 First you extract the keys from the hashes into lists, then solve
2348 the "removing duplicates" problem described above. For example:
2351 for $element (keys(%foo), keys(%bar)) {
2358 @uniq = keys %{{%foo,%bar}};
2360 Or if you really want to save space:
2363 while (defined ($key = each %foo)) {
2366 while (defined ($key = each %bar)) {
2371 =head2 How can I store a multidimensional array in a DBM file?
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.
2378 =head2 How can I make my hash remember the order I put elements into it?
2380 Use the C<Tie::IxHash> from CPAN.
2384 tie my %myhash, 'Tie::IxHash';
2386 for (my $i=0; $i<20; $i++) {
2390 my @keys = keys %myhash;
2391 # @keys = (0,1,2,3,...)
2393 =head2 Why does passing a subroutine an undefined element in a hash create it?
2395 (contributed by brian d foy)
2397 Are you using a really old version of Perl?
2399 Normally, accessing a hash key's value for a nonexistent key will
2400 I<not> create the key.
2403 my $value = $hash{ 'foo' };
2404 print "This won't print\n" if exists $hash{ 'foo' };
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:
2410 my_sub( $hash{ 'foo' } );
2411 print "This will print before 5.004\n" if exists $hash{ 'foo' };
2414 # $_[0] = 'bar'; # create hash key in case you do this
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:
2421 my_sub( $hash{ 'foo' } );
2422 print "This will print, even after 5.004\n" if exists $hash{ 'foo' };
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:
2432 my_sub( @hash{ qw/foo/ } );
2434 =head2 How can I make the Perl equivalent of a C structure/C++ class/hash or array of hashes or arrays?
2436 Usually a hash ref, perhaps like this:
2441 TITLE => "deputy peon",
2444 PALS => [ "Norbert", "Rhys", "Phineas"],
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
2452 =head2 How can I use a reference as a hash key?
2454 (contributed by brian d foy and Ben Morrow)
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.
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.
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
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.
2480 =head2 How can I check if a key exists in a multilevel hash?
2482 (contributed by brian d foy)
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:
2488 if( exists $hash{key1}{key2}{key3} ) {
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>:
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:
2506 no autovivification;
2508 if( exists $hash{key1}{key2}{key3} ) {
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
2517 use Data::Diver qw(Dive);
2519 my @exists = Dive( \%hash, qw(key1 key2 key3) );
2521 ...; # keys do not exist
2523 elsif( ! defined $exists[0] ) {
2524 ...; # keys exist but value is undef
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:
2531 if( check_hash( \%hash, qw(key1 key2 key3) ) ) {
2536 my( $hash, @keys ) = @_;
2538 return unless @keys;
2540 foreach my $key ( @keys ) {
2541 return unless eval { exists $hash->{$key} };
2542 $hash = $hash->{$key};
2550 =head2 How do I handle binary data correctly?
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.
2557 Also see L<perlfunc/"binmode"> or L<perlopentut>.
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.
2563 =head2 How do I determine whether a scalar is a number/whole/integer/float?
2565 Assuming that you don't care about IEEE notations like "NaN" or
2566 "Infinity", you probably just want to use a regular expression:
2572 { say "\thas nondigits"; continue }
2574 { say "\tis a whole number"; continue }
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" }
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.
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?"
2603 use POSIX qw(strtod);
2608 my($num, $unparsed) = strtod($str);
2609 if (($str eq '') || ($unparsed != 0) || $!) {
2617 sub is_numeric { defined getnum($_[0]) }
2619 Or you could check out the L<String::Scanf> module on the CPAN
2622 =head2 How do I keep persistent data across program calls?
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:
2631 store(\%hash, "filename");
2634 $href = retrieve("filename"); # by ref
2635 %hash = %{ retrieve("filename") }; # direct to hash
2637 =head2 How do I print out or copy a recursive data structure?
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.
2644 use Storable qw(dclone);
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
2652 %newhash = %{ dclone(\%oldhash) };
2654 =head2 How do I define methods for every class/object?
2656 (contributed by Ben Morrow)
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.
2665 =head2 How do I verify a credit card checksum?
2667 Get the C<Business::CreditCard> module from CPAN.
2669 =head2 How do I pack arrays of doubles or floats for XS code?
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.
2675 See L<http://search.cpan.org/dist/PGPLOT> for the code.
2677 =head1 AUTHOR AND COPYRIGHT
2679 Copyright (c) 1997-2010 Tom Christiansen, Nathan Torkington, and
2680 other authors as noted. All rights reserved.
2682 This documentation is free; you can redistribute it and/or modify it
2683 under the same terms as Perl itself.
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.