Regexp::Common::zip(3pm)

1Regexp::Common::zip(3)User Contributed Perl DocumentationRegexp::Common::zip(3)
2
3
4

NAME

6       Regexp::Common::zip -- provide regexes for postal codes.
7

SYNOPSIS

9           use Regexp::Common qw /zip/;
10
11           while (<>) {
12               /^$RE{zip}{Netherlands}$/   and  print "Dutch postal code\n";
13           }
14

DESCRIPTION

16       Please consult the manual of Regexp::Common for a general description
17       of the works of this interface.
18
19       Do not use this module directly, but load it via Regexp::Common.
20
21       This module offers patterns for zip or postal codes of many different
22       countries. They all have the form "$RE{zip}{Country}[{options}]".
23
24       The following common options are used:
25
26   "{-prefix=[yes|no|allow]}" and "{-country=PAT}".
27       Postal codes can be prefixed with a country abbreviation. That is, a
28       Dutch postal code of 1234 AB can also be written as NL-1234 AB.  By
29       default, all the patterns will allow the prefixes. But this can be
30       changed with the "-prefix" option. With "-prefix=yes", the returned
31       pattern requires a country prefix, while "-prefix=no" disallows a
32       prefix. Any argument that doesn't start with a "y" or a "n" allows a
33       country prefix, but doesn't require them.
34
35       The prefixes used are, unfortunately, not always the same. Officially,
36       ISO country codes need to be used, but the usage of CEPT codes (the
37       same ones as used on cars) is common too. By default, each postal code
38       will recognize a country prefix that's either the ISO standard or the
39       CEPT code. That is, German postal codes may prefixed with either "DE"
40       or "D". The recognized prefix can be changed with the "-country"
41       option, which takes a (sub)pattern as argument. The arguments "iso" and
42       "cept" are special, and indicate the language prefix should be the ISO
43       country code, or the CEPT code.
44
45       Examples:
46        /$RE{zip}{Netherlands}/;
47                  # Matches '1234 AB' and 'NL-1234 AB'.
48        /$RE{zip}{Netherlands}{-prefix => 'no'}/;
49                  # Matches '1234 AB' but not 'NL-1234 AB'.
50        /$RE{zip}{Netherlands}{-prefix => 'yes'}/;
51                  # Matches 'NL-1234 AB' but not '1234 AB'.
52
53        /$RE{zip}{Germany}/;
54                  # Matches 'DE-12345' and 'D-12345'.
55        /$RE{zip}{Germany}{-country => 'iso'}/;
56                  # Matches 'DE-12345' but not 'D-12345'.
57        /$RE{zip}{Germany}{-country => 'cept'}/;
58                  # Matches 'D-12345' but not 'DE-12345'.
59        /$RE{zip}{Germany}{-country => 'GER'}/;
60                  # Matches 'GER-12345'.
61
62   "{-sep=PAT}"
63       Some countries have postal codes that consist of two parts. Typically
64       there is an official way of separating those parts; but in practise
65       people tend to use different separators. For instance, if the official
66       way to separate parts is to use a space, it happens that the space is
67       left off. The "-sep" option can be given a pattern as argument which
68       indicates what to use as a separator between the parts.
69
70       Examples:
71        /$RE{zip}{Netherlands}/;
72                  # Matches '1234 AB' but not '1234AB'.
73        /$RE{zip}{Netherlands}{-sep => '\s*'}/;
74                  # Matches '1234 AB' and '1234AB'.
75
76   "$RE{zip}{Australia}{-lax}"
77       Returns a pattern that recognizes Australian postal codes. Australian
78       postal codes consist of four digits; the first two digits, which range
79       from '10' to '97', indicate the state, although there are exceptions.
80       Territories use '02' or '08' as starting digits. '0909' is the only
81       postal code starting with '09' - this is the postal code for the
82       Northern Territory University). The (optional) country prefixes are AU
83       (ISO country code) and AUS (CEPT code).
84
85       It the past, it was claimed that for postal codes starting with a 0,
86       the leading 0 may be omitted, and up to (and including) version
87       2016060201, the leading 0 was optional. But there doesn't seem be solid
88       evidence the leading 0 is optional. So, we now require there always to
89       be four digit -- unless the "{-lax}" option is given, then a possibly
90       leading 0 is optional.
91
92       Regexp::Common 2.107 and before used "$RE{zip}{Australian}". This is
93       still supported.
94
95       If "{-keep}" is used, the following variables will be set:
96
97       $1  The entire postal code.
98
99       $2  The country code prefix.
100
101       $3  The postal code without the country prefix.
102
103       As of version 2016060201, no $4 or $5 will be set.
104
105   "$RE {zip} {Austria}"
106       Returns a pattern which recognizes Austrian postal codes. Austrian
107       postal codes consists of 4 digits, but not all possibilities are used.
108       This pattern matches the postal codes in use. The (optional) country
109       prefixes are AT (ISO country code) and AUT (CEPT code).
110
111       If "{-keep}" is used, the following variables will be set:
112
113       $1  The entire postal code.
114
115       $2  The country code prefix.
116
117       $3  The postal code without the country code prefix.
118
119   "$RE{zip}{Belgium}"
120       Returns a pattern than recognizes Belgian postal codes. Belgian postal
121       codes consist of 4 digits, of which the first indicates the province.
122       The (optional) country prefixes are BE (ISO country code) and B (CEPT
123       code).
124
125       If "{-keep}" is used, the following variables will be set:
126
127       $1  The entire postal code.
128
129       $2  The country code prefix.
130
131       $3  The postal code without the country prefix.
132
133   "$RE{zip}{Denmark}"
134       Returns a pattern that recognizes Danish postal codes. Danish postal
135       codes consist of four numbers; the first digit indicates the
136       distribution region, the second the distribution district. The
137       (optional) country prefix is DK, which is both the ISO country code and
138       the CEPT code.
139
140       If "{-keep}" is used, the following variables will be set:
141
142       $1  The entire postal code.
143
144       $2  The country code prefix.
145
146       $3  The postal code without the country prefix.
147
148       Danish postal codes will not start with 39. Postal codes of the form
149       39XX are reserved from Greenland; the pattern for Danish postal codes
150       will not recognize them.
151
152   "$RE{zip}{France}"
153       Returns a pattern that recognizes French postal codes. French postal
154       codes consist of five numbers; the first two numbers, which range from
155       '01' to '98', indicate the department. The (optional) country prefixes
156       are FR (ISO country code) and F (CEPT code).  Regexp::Common 2.107 and
157       before used "$RE{zip}{French}". This is still supported.
158
159       Monaco uses postal codes which are part of the numbering system used by
160       the French postal code system; their numbers start with 980. These
161       numbers are "not" recognized by this pattern.
162
163       If "{-keep}" is used, the following variables will be set:
164
165       $1  The entire postal code.
166
167       $2  The country code prefix.
168
169       $3  The postal code without the country prefix.
170
171   "$RE{zip}{Germany}"
172       Returns a pattern that recognizes German postal codes. German postal
173       codes consist of five numbers; the first two numbers indicating a wider
174       postal area, the last three digits a postal district.  The (optional)
175       country prefixes are DE (ISO country code) and D (CEPT code).
176       Regexp::Common 2.107 and before used "$RE{zip}{German}". This is still
177       supported.
178
179       If "{-keep}" is used, the following variables will be set:
180
181       $1  The entire postal code.
182
183       $2  The country code prefix.
184
185       $3  The postal code without the country prefix.
186
187   "$RE{zip}{Greenland}"
188       Returns a pattern that recognizes postal codes from Greenland.
189       Greenland, uses the Danish postal codes system. Postal codes starting
190       with 39 are reserved for Greenland, and all Greenlandic postal codes
191       start with 39. Except the postal code for Santa. He uses 2412.
192
193       The (optional) country prefix is GL, which is use both as the ISO
194       country code and the CEPT code. Earlier versions used DK as the prefix.
195
196       If "{-keep}" is used, the following variables will be set:
197
198       $1  The entire postal code.
199
200       $2  The country code prefix.
201
202       $3  The postal code without the country prefix.
203
204   "$RE{zip}{Italy}"
205       Returns a pattern recognizing Italian postal codes. Italian postal
206       codes consist of 5 digits. The first digit indicates the region, the
207       second the province. The third digit is odd for province capitals, and
208       even for the province itself. The fourth digit indicates the route, and
209       the fifth a place on the route (0 for small places, alphabetically for
210       the rest).
211
212       Codes starting with 4789 are postal codes for San Marino; they are not
213       recognized by the pattern. Use "$RE {zip} {'San Marino'}" instead.
214
215       The country prefix is either IT (the ISO country code), or I (the CEPT
216       code).
217
218       If "{-keep}" is used, the following variables will be set:
219
220       $1  The entire postal code.
221
222       $2  The country code prefix.
223
224       $3  The postal code without the country prefix.
225
226   "$RE {zip} {Liechtenstein}"
227       Returns a pattern which recognizes postal codes used in Liechtenstein.
228       Liechtenstein uses postal codes from the Swiss postal code system.
229       This system uses four digits. Postal codes which start with 94, and use
230       8 or 9 as a third digit are postal codes for Liechtenstein.
231
232       If "{-keep}" is used, the following variables will be set:
233
234       $1  The entire postal code.
235
236       $2  The country code prefix.
237
238       $3  The postal code without the country prefix.
239
240       The ISO country prefix is LI, the CEPT country prefix is LIE.
241
242   "$RE {zip {Monaco}"
243       Returns a pattern for postal codes used in Monaco. Monaco uses a range
244       from the system used in France. They are 5 digits, starting with 980.
245       The number 98000 is used for physical addresses. Numbers ending in 01
246       to 99 are used for special deliveries.
247
248       The ISO country code is MC.
249
250       If "{-keep}" is used, the following variables will be set:
251
252       $1  The entire postal code.
253
254       $2  The country code prefix.
255
256       $3  The postal code without the country prefix.
257
258   "$RE{zip}{Netherlands}"
259       Returns a pattern that recognizes Dutch postal codes. Dutch postal
260       codes consist of 4 digits and 2 letters, separated by a space.  The
261       separator can be changed using the "{-sep}" option, as discussed above.
262       The (optional) country prefix is NL, which is both the ISO country code
263       and the CEPT code. Regexp::Common 2.107 and earlier used
264       "$RE{zip}{Dutch}". This is still supported.
265
266       If "{-keep}" is used, the following variables will be set:
267
268       $1  The entire postal code.
269
270       $2  The country code prefix.
271
272       $3  The postal code without the country prefix.
273
274       $4  The digits part of the postal code.
275
276       $5  The separator between the digits and the letters.
277
278       $6  The letters part of the postal code.
279
280   "$RE{zip}{Norway}"
281       Returns a pattern that recognizes Norwegian postal codes. Norwegian
282       postal codes consist of four digits.
283
284       The country prefix is either NO (the ISO country code), or N (the CEPT
285       code).
286
287       If "{-keep}" is used, the following variables will be set:
288
289       $1  The entire postal code.
290
291       $2  The country code prefix.
292
293       $3  The postal code without the country prefix.
294
295   "$RE {zip} {'San Marino'}"
296       Postal codes of San Marino use a slice from the Italian postal codes.
297       Any code starting 4789, followed by another digit belongs to San
298       Marino.
299
300       The country prefix for San Marino is SM.
301
302       If "{-keep}" is used, the following variables will be set:
303
304       $1  The entire postal code.
305
306       $2  The country code prefix.
307
308       $3  The postal code without the country prefix.
309
310   "$RE{zip}{Spain}"
311       Returns a pattern that recognizes Spanish postal codes. Spanish postal
312       codes consist of 5 digits. The first 2 indicate one of Spain's fifties
313       provinces (in alphabetical order), starting with 00. The third digit
314       indicates a main city or the main delivery rounds. The last two digits
315       are the delivery area, secondary delivery route or a link to rural
316       areas.
317
318       The country prefix is either ES (the ISO country code), or E (the CEPT
319       code).
320
321       If "{-keep}" is used, the following variables will be set:
322
323       $1  The entire postal code.
324
325       $2  The country code prefix.
326
327       $3  The postal code without the country prefix.
328
329       $4  The two digits indicating the province.
330
331       $5  The digit indicating the main city or main delivery route.
332
333       $6  The digits indicating the delivery area, secondary delivery route
334           or a link to rural areas.
335
336   "$RE {zip} {Switzerland}"
337       Returns a pattern that recognizes Swiss postal codes. Swiss postal
338       codes consist of 4 digits, but not all combinations are used. Postal
339       codes starting with 948 and 949 are for location in Liechtenstein, and
340       will not be recognized by the pattern for Swiss postal codes.  Use "$RE
341       {zip} {Liechtenstein}" for those.
342
343       If "{-keep}" is used, the following variables will be set:
344
345       $1  The entire postal code.
346
347       $2  The country code prefix.
348
349       $3  The postal code without the country prefix.
350
351       The country prefix is CH, for both the ISO and CEPT prefixes.
352
353   "$RE{zip}{US}{-extended => [yes|no|allow]}"
354       Returns a pattern that recognizes US zip codes. US zip codes consist of
355       5 digits, with an optional 4 digit extension. By default, extensions
356       are allowed, but not required. This can be influenced by the
357       "-extended" option. If its argument starts with a "y", extensions are
358       required; if the argument starts with a "n", extensions will not be
359       recognized. If an extension is used, a dash is used to separate the
360       main part from the extension, but this can be changed with the "-sep"
361       option.
362
363       The country prefix is either US (the ISO country code), or USA (the
364       CEPT code).
365
366       If "{-keep}" is being used, the following variables will be set:
367
368       $1  The entire postal code.
369
370       $2  The country code prefix.
371
372       $3  The postal code without the country prefix.
373
374       $4  The first 5 digits of the postal code.
375
376       $5  The first three digits of the postal code, indicating a sectional
377           center or a large city. New in Regexp::Common 2.119.
378
379       $6  The last 2 digits of the 5 digit part of the postal code,
380           indicating a post office facility or delivery area. New in
381           Regexp::Common 2.119.
382
383       $7  The separator between the 5 digit part and the 4 digit part. Up to
384           Regexp::Common 2.118, this used to be $5.
385
386       $8  The 4 digit part of the postal code (if any). Up to Regexp::Common
387           2.118, this used to be $6.
388
389       $9  The first two digits of the 4 digit part of the postal code,
390           indicating a sector, or several blocks. New in Regexp::Common
391           2.119.
392
393       $10 The last two digits of the 4 digit part of the postal code,
394           indicating a segment or one side of a street. New in Regexp::Common
395           2.119.
396
397       Questions
398
399       •   Can the 5 digit part of the zip code (in theory) start with 000?
400
401       •   Can the 5 digit part of the zip code (in theory) end with 00?
402
403       •   Can the 4 digit part of the zip code (in theory) start with 00?
404
405       •   Can the 4 digit part of the zip code (in theory) end with 00?
406
407   "$RE {zip} {'Vatican City'}"
408       Vatican City uses a single postal code; taken from the Italian system
409       of postal codes, and sharing the single code with a part of Rome.
410
411       If "{-keep}" is used, the following variables will be set:
412
413       $1  The entire postal code.
414
415       $2  The country code prefix.
416
417       $3  The postal code without the country prefix.
418
419       The country prefix for Vatican City is "VA".
420

AUTHORS

450       Damian Conway (damian@conway.org) and Abigail
451       (regexp-common@abigail.be).
452

MAINTENANCE

454       This package is maintained by Abigail (regexp-common@abigail.be).
455

BUGS AND IRRITATIONS

457       Zip codes for most countries are missing.  Send them in to
458       regexp-common@abigail.be.
459

LICENSE and COPYRIGHT

461       This software is Copyright (c) 2001 - 2017, Damian Conway and Abigail.
462
463       This module is free software, and maybe used under any of the following
464       licenses:
465
466        1) The Perl Artistic License.     See the file COPYRIGHT.AL.
467        2) The Perl Artistic License 2.0. See the file COPYRIGHT.AL2.
468        3) The BSD License.               See the file COPYRIGHT.BSD.
469        4) The MIT License.               See the file COPYRIGHT.MIT.
470
471
472
473perl v5.38.0                      2023-07-21            Regexp::Common::zip(3)