Regexp::Common::zip(3) User Contributed Perl Documentation Regexp::Common::zip(3)
NAME
Regexp::Common::zip -- provide regexes for postal codes.
SYNOPSIS
use Regexp::Common qw /zip/;
while (<>) {
/^$RE{zip}{Netherlands}$/ and print "Dutch postal code\n";
}
DESCRIPTION
Please consult the manual of Regexp::Common for a general description of the works of this interface.
Do not use this module directly, but load it via Regexp::Common.
This module offers patterns for zip or postal codes of many different countries. They all have the
form "$RE{zip}{Country}[{options}]".
The following common options are used:
"{-prefix=[yes|no|allow]}" and "{-country=PAT}".
Postal codes can be prefixed with a country abbreviation. That is, a dutch postal code of 1234 AB can
also be written as NL-1234 AB. By default, all the patterns will allow the prefixes. But this can be
changed with the "-prefix" option. With "-prefix=yes", the returned pattern requires a country
prefix, while "-prefix=no" disallows a prefix. Any argument that doesn't start with a "y" or a "n"
allows a country prefix, but doesn't require them.
The prefixes used are, unfortunally, not always the same. Officially, ISO country codes need to be
used, but the usage of CEPT codes (the same ones as used on cars) is common too. By default, each
postal code will recognize a country prefix that's either the ISO standard or the CEPT code. That is,
German postal codes may prefixed with either "DE" or "D". The recognized prefix can be changed with
the "-country" option, which takes a (sub)pattern as argument. The arguments "iso" and "cept" are
special, and indicate the language prefix should be the ISO country code, or the CEPT code.
Examples:
/$RE{zip}{Netherlands}/;
# Matches '1234 AB' and 'NL-1234 AB'.
/$RE{zip}{Netherlands}{-prefix => 'no'}/;
# Matches '1234 AB' but not 'NL-1234 AB'.
/$RE{zip}{Netherlands}{-prefix => 'yes'}/;
# Matches 'NL-1234 AB' but not '1234 AB'.
/$RE{zip}{Germany}/;
# Matches 'DE-12345' and 'D-12345'.
/$RE{zip}{Germany}{-country => 'iso'}/;
# Matches 'DE-12345' but not 'D-12345'.
/$RE{zip}{Germany}{-country => 'cept'}/;
# Matches 'D-12345' but not 'DE-12345'.
/$RE{zip}{Germany}{-country => 'GER'}/;
# Matches 'GER-12345'.
"{-sep=PAT}"
Some countries have postal codes that consist of two parts. Typically there is an official way of
separating those parts; but in practise people tend to use different separators. For instance, if the
official way to separate parts is to use a space, it happens that the space is left off. The "-sep"
option can be given a pattern as argument which indicates what to use as a separator between the
parts.
Examples:
/$RE{zip}{Netherlands}/;
# Matches '1234 AB' but not '1234AB'.
/$RE{zip}{Netherlands}{-sep => '\s*'}/;
# Matches '1234 AB' and '1234AB'.
$RE{zip}{Australia}
Returns a pattern that recognizes Australian postal codes. Australian postal codes consist of four
digits; the first two digits, which range from '10' to '97', indicate the state. Territories use '02'
or '08' as starting digits; the leading zero is optional. '0909' is the only postal code starting
with '09' (the leading zero is optional here as well) - this is the postal code for the Nothern
Territory University). The (optional) country prefixes are AU (ISO country code) and AUS (CEPT
code). Regexp::Common 2.107 and before used $RE{zip}{Australia}. This is still supported.
If "{-keep}" is used, the following variables will be set:
$1 The entire postal code.
$2 The country code prefix.
$3 The postal code without the country prefix.
$4 The state or territory.
$5 The last two digits.
$RE{zip}{Belgium}
Returns a pattern than recognizes Belgian postal codes. Belgian postal codes consist of 4 digits, of
which the first indicates the province. The (optional) country prefixes are BE (ISO country code)
and B (CEPT code).
If "{-keep}" is used, the following variables will be set:
$1 The entire postal code.
$2 The country code prefix.
$3 The postal code without the country prefix.
$4 The digit indicating the province.
$5 The last three digits of the postal code.
$RE{zip}{Denmark}
Returns a pattern that recognizes Danish postal codes. Danish postal codes consist of four numbers;
the first digit (which cannot be 0), indicates the distribution region, the second the distribution
district. The (optional) country prefix is DK, which is both the ISO country code and the CEPT code.
If "{-keep}" is used, the following variables will be set:
$1 The entire postal code.
$2 The country code prefix.
$3 The postal code without the country prefix.
$4 The digit indicating the distribution region.
$5 The digit indicating the distribution district.
$6 The last two digits of the postal code.
$RE{zip}{France}
Returns a pattern that recognizes French postal codes. French postal codes consist of five numbers;
the first two numbers, which range from '01' to '98', indicate the department. The (optional) country
prefixes are FR (ISO country code) and F (CEPT code). Regexp::Common 2.107 and before used
$RE{zip}{French}. This is still supported.
If "{-keep}" is used, the following variables will be set:
$1 The entire postal code.
$2 The country code prefix.
$3 The postal code without the country prefix.
$4 The department.
$5 The last three digits.
$RE{zip}{Germany}
Returns a pattern that recognizes German postal codes. German postal codes consist of five numbers;
the first number indicating the distribution zone, the second the distribution region, while the
latter three indicate the distribution district and the postal town. The (optional) country prefixes
are DE (ISO country code) and D (CEPT code). Regexp::Common 2.107 and before used $RE{zip}{German}.
This is still supported.
If "{-keep}" is used, the following variables will be set:
$1 The entire postal code.
$2 The country code prefix.
$3 The postal code without the country prefix.
$4 The distribution zone.
$5 The distribution region.
$6 The distribution district and postal town.
$RE{zip}{Greenland}
Returns a pattern that recognizes postal codes from Greenland. Greenland, being part of Denmark,
uses Danish postal codes. All postal codes of Greenland start with 39. The (optional) country
prefix is DK, which is both the ISO country code and the CEPT code.
If "{-keep}" is used, the following variables will be set:
$1 The entire postal code.
$2 The country code prefix.
$3 The postal code without the country prefix.
$4 39, being the distribution region and distribution district for Greenland.
$5 The last two digits of the postal code.
$RE{zip}{Italy}
Returns a pattern recognizing Italian postal codes. Italian postal codes consist of 5 digits. The
first digit indicates the region, the second the province. The third digit is odd for province
capitals, and even for the province itself. The fourth digit indicates the route, and the fifth a
place on the route (0 for small places, alphabetically for the rest).
The country prefix is either IT (the ISO country code), or I (the CEPT code).
If "{-keep}" is used, the following variables will be set:
$1 The entire postal code.
$2 The country code prefix.
$3 The postal code without the country prefix.
$4 The region.
$5 The province.
$6 Capital or province.
$7 The route.
$8 The place on the route.
$RE{zip}{Netherlands}
Returns a pattern that recognizes Dutch postal codes. Dutch postal codes consist of 4 digits and 2
letters, separated by a space. The separator can be changed using the "{-sep}" option, as discussed
above. The (optional) country prefix is NL, which is both the ISO country code and the CEPT code.
Regexp::Common 2.107 and earlier used $RE{zip}{Dutch}. This is still supported.
If "{-keep}" is used, the following variables will be set:
$1 The entire postal code.
$2 The country code prefix.
$3 The postal code without the country prefix.
$4 The digits part of the postal code.
$5 The separator between the digits and the letters.
$6 The letters part of the postal code.
$RE{zip}{Norway}
Returns a pattern that recognizes Norwegian postal codes. Norwegian postal codes consist of four
digits.
The country prefix is either NO (the ISO country code), or N (the CEPT code).
If "{-keep}" is used, the following variables will be set:
$1 The entire postal code.
$2 The country code prefix.
$3 The postal code without the country prefix.
$RE{zip}{Spain}
Returns a pattern that recognizes Spanish postal codes. Spanish postal codes consist of 5 digits. The
first 2 indicate one of Spains fifties provinces (in alphabetical order), starting with 00. The third
digit indicates a main city or the main delivery rounds. The last two digits are the delivery area,
secondary delivery route or a link to rural areas.
The country prefix is either ES (the ISO country code), or E (the CEPT code).
If "{-keep}" is used, the following variables will be set:
$1 The entire postal code.
$2 The country code prefix.
$3 The postal code without the country prefix.
$4 The two digits indicating the province.
$5 The digit indicating the main city or main delivery route.
$6 The digits indicating the delivery area, secondary delivery route or a link to rural areas.
$RE{zip}{US}{-extended => [yes|no|allow]}
Returns a pattern that recognizes US zip codes. US zip codes consist of 5 digits, with an optional 4
digit extension. By default, extensions are allowed, but not required. This can be influenced by the
"-extended" option. If its argument starts with a "y", extensions are required; if the argument
starts with a "n", extensions will not be recognized. If an extension is used, a dash is used to
separate the main part from the extension, but this can be changed with the "-sep" option.
The country prefix is either US (the ISO country code), or USA (the CEPT code).
If "{-keep}" is being used, the following variables will be set:
$1 The entire postal code.
$2 The country code prefix.
$3 The postal code without the country prefix.
$4 The first 5 digits of the postal code.
$5 The first three digits of the postal code, indicating a sectional center or a large city. New in
Regexp::Common 2.119.
$6 The last 2 digits of the 5 digit part of the postal code, indicating a post office facility or
delivery area. New in Regexp::Common 2.119.
$7 The separator between the 5 digit part and the 4 digit part. Up to Regexp::Common 2.118, this
used to be $5.
$8 The 4 digit part of the postal code (if any). Up to Regexp::Common 2.118, this used to be $6.
$9 The first two digits of the 4 digit part of the postal code, indicating a sector, or several
blocks. New in Regexp::Common 2.119.
$10 The last two digits of the 4 digit part of the postal code, indicating a segment or one side of a
street. New in Regexp::Common 2.119.
You need at least version 5.005_03 to be able to use US postal codes. Older versions contain a bug
that let the pattern match invalid US postal codes.
Questions
Can the 5 digit part of the zip code (in theory) start with 000?
Can the 5 digit part of the zip code (in theory) end with 00?
Can the 4 digit part of the zip code (in theory) start with 00?
Can the 4 digit part of the zip code (in theory) end with 00?
HISTORY
$Log: zip.pm,v $
Revision 2.112 2005/01/01 16:34:04 abigail
- Modified the -keep captures for US zip codes. Both the 5 and 4 digit parts
of the zip codes can be dissected into 2 parts.
- Updated the copyright notice.
Revision 2.111 2004/12/14 23:15:13 abigail
Disable '-prefix' for Danish postal codes for pre-5.00503 perls.
Revision 2.110 2004/06/09 21:44:13 abigail
- Norway, Italy, Spain.
- References.
- POD nits.
Revision 2.109 2003/07/04 13:34:05 abigail
Fixed assignment to
Revision 2.108 2003/06/24 23:23:14 abigail
Australia currently has a postal code '0909' (or '909') for the
Northern Territory University; this is the only postal code starting
with '09'. $RE{zip}{Australia} now accepts '0909', and rejects all
other postal codes starting with '09'. (Ron Savage).
Revision 2.107 2003/03/25 23:46:58 abigail
Added RCS Id: tag
Revision 2.106 2003/02/09 21:31:16 abigail
Postal codes for Denmark and Greenland
Revision 2.105 2003/02/09 12:41:31 abigail
Added Belgian postal codes
Revision 2.104 2003/02/01 22:55:31 abigail
Changed Copyright years
Revision 2.103 2003/02/01 22:49:25 abigail
Added Australian postal codes
Revision 2.102 2003/01/23 02:18:42 abigail
Added French postal codes
Revision 2.101 2003/01/22 17:23:26 abigail
German postal codes added.
Revision 2.100 2003/01/21 23:19:40 abigail
The whole world understands RCS/CVS version numbers, that 1.9 is an
older version than 1.10. Except CPAN. Curse the idiot(s) who think
that version numbers are floats (in which universe do floats have
more than one decimal dot?).
Everything is bumped to version 2.100 because CPAN couldn't deal
with the fact one file had version 1.10.
Revision 1.5 2003/01/16 11:06:27 abigail
Typo fix.
Revision 1.4 2003/01/16 11:02:17 abigail
For US zip codes, version needs to be at least 5.005_03; older 5.005
versions seem to have a bug in the regex machine, creating false
positives.
Revision 1.3 2003/01/13 21:45:01 abigail
Complete redoing of Dutch & US postal codes. Documented them.
Revision 1.2 2003/01/01 15:09:47 abigail
Added US zip codes.
Revision 1.1 2002/12/31 02:01:33 abigail
First version
SEE ALSO
Regexp::Common for a general description of how to use this interface.
<http://www.columbia.edu/kermit/postal.html
Frank's compulsive guide to postal addresses.
<http://www.upu.int/post_code/en/addressing_formats_guide.shtml
Postal addressing systems.
<http://www.uni-koeln.de/~arcd2/33e.htm
Postal code information.
<http://www.grcdi.nl/linkspc.htm
Links to Postcode Pages.
<http://www1.auspost.com.au/postcodes/
Information about Australian postal codes.
<http://hdusps.esecurecare.net/cgi-bin/hdusps.cfg/php/enduser/std_adp.php?p_faqid=1014
Information about US postal codes.
<http://en.wikipedia.org/wiki/Postal_code
AUTHORS
Damian Conway (damian@conway.org) and Abigail (regexp-common@abigail.nl).
MAINTAINANCE
This package is maintained by Abigail (regexp-common@abigail.nl).
BUGS AND IRRITATIONS
Zip codes for most countries are missing. Send them in to regexp-common@abigail.nl.
COPYRIGHT
Copyright (c) 2001 - 2005, Damian Conway and Abigail. All Rights
Reserved. This module is free software. It may be used, redistributed
and/or modified under the terms of the Perl Artistic License
(see http://www.perl.com/perl/misc/Artistic.html)
perl v5.8.8 2005-01-01 Regexp::Common::zip(3)
|