Index
- NAME
- SYNOPSIS
- ABSTRACT
- DESCRIPTION
- DEPENDENCIES
- PROCEDURES and METHODS
- PROCEDURES
- METHODS
- TYPE
- CAVEAT
- SEE ALSO
- COPYRIGHT AND LICENCE
Code Index:
NAME
Geo::Postcodes::DK - Danish postcodes with associated information
SYNOPSIS
This module can be used object oriented, or as procedures. Take your pick.
AS OBJECTS
use Geo::Postcodes::DK;
my $postcode = '1171';
if (Geo::Postcodes::DK::valid($postcode)) # A valid postcode?
{
my $P = Geo::Postcodes::DK->new($postcode);
printf "Postcode '%s'.\n", $P->postcode();
printf "Postal location: '%s'.\n", $P->location();
printf "Borough: '%s'.\n", $P->borough();
printf "County: '%s'.\n", $P->county();
printf "Owner: '%s'.\n", $P->owner();
printf "Address: '%s'.\n", $P->address();
printf "Postcode type: '%s'.\n", $P->type();
printf "- in danish: '%s'.\n", $P->type_verbose();
printf "- in english: '%s'.\n", $P->Geo::Postcodes::type_verbose();
}
The test for a valid postcode can also be done on the object itself, as it will be undef when passed an illegal postcode (and thus no object at all.)
my $P = Geo::postcodes::DK->new($postcode);
if ($P) { ... }
A more compact solution:
if ($P = Geo::Postcodes::DK->new($postcode))
{
foreach my $field (Geo::Postcodes::DK::get_fields())
{
printf("%-20s %s\n", ucfirst($field), $P->$field())
}
}
AS PROCEDURES
use Geo::postcodes::DK;
my $postcode = "1171";
if (Geo::Postcodes::DK::valid($postcode))
{
printf "Postcode" '%s'.\n", $postcode;
printf "Postal location: '%s'.\n", location_of($postcode);
printf "Postcode type: '%s'.\n", type_of($postcode);
printf "Owner: '%s'.\n", owner_of($postcode);
printf "Address: '%s'.\n", address_of($postcode);
}
ABSTRACT
Geo::postcodes::DK - Perl extension for the mapping between danish (including Grønland and Færøerne) postcodes, postal location, address and address owner.
DESCRIPTION
Tired og entering the postal name all the time? This is not necessary, as it is uniquely defined from the postcode. Request the postcode only, and use this library to get the postal name.
EXPORT
None.
The module supports the following fields: 'postcode', 'location', 'address',
'owner', 'type', and -type_verbose'. This list can also be obtained with the
call Geo::Postcodes::DK::get_fields().
DEPENDENCIES
This module is a subclass of Geo::Postcodes, which must be installed first.
PROCEDURES and METHODS
These functions can be used as methods or procedures.
is_field
my $boolean = Geo::postcodes::DK::is_field($field); my $boolean = $postcode_object->is_field($field);
Does the specified field exist.
get_fields
my @fields = Geo::postcodes::DK::get_fields(); my @fields = $postcode_object->get_fields();
A list of fields supported by this class.
selection
This procedure/method makes it possible to select more than one postcode at a time, based on arbitrary complex rules.
See the selection documentation (perldoc Geo::Postcodes::Selection or man Geo::Postcodes::Selection) for a full description, and the tutorial (perldoc Geo::Postcodes::Tutorial or man Geo::Postcodes::Tutorial) for sample code.
selection_loop
As above.
PROCEDURES
Note that the xxx_of procedures return undef when passed an illegal argument. They are used internally by the object constructor (new).
legal
my $boolean = Geo::postcodes::DK::legal($postcode);
Do we have a legal postcode; a code that follows the syntax rules?
valid
my $boolean = Geo::postcodes::DK::valid($postcode);
Do we have a valid postcode; a code in actual use?
get_postcodes
This will return an unsorted list of all the norwegian postcodes.
verify_selectionlist
This will check the list of arguments for correctness, and should be used before calling 'selection'. The procedure returns a modified version of the arguments on success, and diagnostic messages on failure.
my($status, @modified) = Geo::Postcodes::DK::verify_selectionlist(@args);
if ($status)
{
my @result = Geo::Postcodes::DK::selection(@modified);
}
else
{
print "Diagnostic messages:\n";
map { print " - $_\n" } @modified;
}
postcode_of
$postcode = Geo::Postcodes::NO::postcode_of($postcode);
Used internally by 'selection', but otherwise not very useful.
location_of
my $location = Geo::postcodes::DK::location_of($postcode);
The postal place associated with the specified postcode.
owner_of
my $owner = Geo::postcodes::DK::owner_of($postcode);
The owner (company) of the postcode, if any.
address_of
my $address = Geo::postcodes::DK::address_of($postcode);
The address (street) associated with the specified postcode.
type_of
my $type = Geo::postcodes::DK::type_of($postcode);
What kind of postcode is this, as a code.
type_verbose_of
my $danish_description = Geo::postcodes::DK::type_verbose_of($postcode); my $english_description = Geo::postcodes::type_verbose_of($postcode);
A danish text describing the type. Use the base class for the english description.
See the TYPE section for a description of the types.
type2verbose
Get the description of the specified type.
my $danish_description = Geo::Postcodes::DK::type2verbose($type); my $english_description = Geo::Postcodes::type2verbose($type);
METHODS
new
my $P = Geo::postcodes::DK-E<gt>new($postcode);
Create a new postcode object. Internally this will call the xxx_of procedures
for the fields supported by this class.
The constructor will return undef when passed an invalid or illegal postcode. Do not try method calls on it, as it is not an object. See the description of the legal and valid procedures above.
postcode
my $postcode = $P->postcode();
The postcode, as given to the constructor (new).
location
my $location = $P->location();
The postal location associated with the specified postcode.
type
my $type = $P->type();
See the description of the procedure type_of above.
type_verbose
See the description of the procedure type_verbose_of above.
my $type_danish = $P->type_verbose(); my $type_english = $P->Geo::Postcodes::type_verbose();
Use this to get the description.
See the TYPE section for a description of the types.
TYPE
This class supports the following types for the postal locatuons:
- BX
-
Postboks (Post Office box)
- ST
-
Gadeadresse (Street address)
- IO
-
Personlig eier (Individual owner)
- PP
-
Ufrankerede svarforsendelser (Porto Paye receiver)
Se Geo::Postcodes for furter descriptions.
CAVEAT
POSTCODES
Danish postcodes (including Grønland) are four digit numbers ("0000" to "9999"), while Færøerne uses three digits numbers ("000" to "999"). This means that "0010" and "010" are legal, while "10" is not.
Use legal to check for legal postcodes, and valid to check if
the postcode is actually in use. Geo::postcodes::DK-new($postcode)>
will return undef if passed an illegal or invalid postcode.
An attempt to access the methods of a non-existent postcode object will
result in a runtime error. This can be avoided by checking if the postal
code is legal, before creating the object; valid($postcode)
returns true or false.
CHARACTER SET
The library was written using the ISO-8859-1 (iso-latin1) character set, and the special danish letters 'Æ', 'Ø' and 'Å' occur regularly in the postal places, kommune name and fylke name. Usage of other character sets may cause havoc. Unicode is not tested.
Note that the case insensitive search (in the 'selection' method/procedure)
doesn't recognize an 'Æ' as an 'æ' (and so on). use locale in the
application program should fix this, if the current locale supports these
characters.
SEE ALSO
See also the sample programs in the eg/-directory of the distribution, the
tutorial (perldoc Geo::Postcodes::Tutorial or man Geo::Postcodes::Tutorial)
and the selection manual (perldoc Geo::Postcodes::Selection or
man Geo::Postcodes::Selection) for usage details.
The latest version of this library should always be available on CPAN, but see also the library home page; http://bbop.org/perl/GeoPostcodes for additional information and sample usage.
COPYRIGHT AND LICENCE
Copyright (C) 2006 by Arne Sommer - perl@bbop.org
This library is free software; you can redistribute them and/or modify it under the same terms as Perl itself.