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