legal

Utopian postcodes are four digit numbers, and the lowest number in use is '1003'. This procedure is programmed to return true for any four digit number where the first digit is non-zero.

 $boolean = Geo::Postcodes::U2::legal('ABBA'); # 0 -> Illegal
 $boolean = Geo::Postcodes::U2::legal('0900'); # 0 -> Illegal
 $boolean = Geo::Postcodes::U2::legal('1900'); # 1 -> Legal
 $boolean = Geo::Postcodes::U2::legal('1000'); # 1 -> Legal

valid

 $boolean = Geo::Postcodes::U2::valid('1000'); # 0 -> Not in use
 $boolean = Geo::Postcodes::U2::valid('ABBA'); # 0 -> Not in use

postcode - postcode_of

 $postcode = $P->postcode();
 $postcode = Geo::Postcodes::U2::location_of($postcode); # Silly

The actual postcode value is available with "postcode" method, as the object itself does not have this information. The corresponding postcode_of-procedure is used internally by selection-procedure/method, but should be avoided in applications.

location - location_of

 $location = $P->location();
 $location = Geo::Postcodes::U2::location_of($postcode);

The location (or postal location) of the postcode. This is the value shown after the postcode in addresses.

borough - borough_of

 $borough = $P->borough();
 $borough = $Geo::Postcodes::U2::borough_of($postcode);

The borough where the postcode is located.

This field is not used by danish postcodes.

county - county_of

 $county = $P->county();
 $county = $Geo::Postcodes::U2::county_of($postcode);

The county where the postcode is located.

This field is not used by danish postcodes.

owner - owner_of

 $owner = $P->owner();
 $owner = $Geo::Postcodes::U2::owner_of($postcode);

The owner of the postcode. This value is only used if the postcode is used by a single user.

This field is not used by norwegian postcodes.

address - address_of

 $address = $P->address();
 $address = $Geo::Postcodes::U2::address_of($postcode);

The street address of the postcode. This value is only used if the postcode is used by a single street, and the street does not use any other posrcode.

This field is not used by norwegian postcodes.

type - type_of

 $type = $P->type();
 $type = $Geo::Postcodes::U2::type_of($postcode);

The type of the postcode, as a short (2-4 characters) code. The types supported by the core module are:

BX

Post Office box

ST

Street address

SX

Service box (as a Post Office box, but the mail is delivered to the customer).

IO

Individual owner (a company with its own postcode).

STBX

Either a Street address (ST) or a Post Office box (BX)

MU

Multiple usage (a mix of the other types)

PP

Porto Paye receiver (mail where the reicever will pay the postage).

PN

Place name

The child classes can use as many of the codes as they want. Utopian postcodes support them all.

type_verbose - type_verbose_of

 $utopian_description = $P->type_verbose();
 $utopian_description = Geo::postcodes::U2::type_verbose_of($postcode);

This will give the description in utopian, if set up by the utopian module, and english otherwise.

The individual country classes are responsible for translating the descriptions of the codes they use to the native language, if appropriate.

 $english_description = Geo::postcodes::type_verbose_of($postcode);
 $english_description = $P->Geo::Postcodes::type_verbose();

Use the version in the base class for the english version.

The danish and norwegian modules have translations for the codes they use.

Example Using Procedures

  my $postcode = '1010';

  if (Geo::Postcodes::U2::valid($postcode))
  {
    printf "Postcode"        '%s'.\n", $postcode;
    printf "Postal location: '%s'.\n", location_of($postcode);
    printf "Borough:         '%s'.\n", borough_of($postcode);
    printf "County:          '%s'.\n", county_of($postcode);
    printf "Owner:           '%s'.\n", owner_of($postcode);
    printf "Address:         '%s'.\n", address_of($postcode);
    printf "Postcode type:   '%s'.\n", type_of($postcode); 
    printf "- in utopian:    '%s'.\n", type_of_verbose($postcode); 
    printf "- in english:    '%s'.\n", Geo::Postcodes::type_of_verbose($postcode); 
  }

The fields are described in the prevoius section; "UTOPIAN FIELDS".

Object Oriented Example

  if (Geo::Postcodes::U2::valid($postcode))
  {
    my $P = Geo::Postcodes::U2->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 norwegian:  '%s'.\n", $P->type_verbose(); 
    printf "- in english:    '%s'.\n", $P->Geo::Postcodes::type_verbose(); 
  }

If speed is a concern, use the procedure version.

new

 my $P = Geo::Postcodes::U2->new($postcode);

Create a new postcode object. Internally this will call the "xxx_of" procedures for the fields supported by utopian postcodes.

The constructor will return undef if given an invalid or illegal postcode. Do not try method calls on it, as it is not an object (and will result in a runtime error). See the description of the legal and valid procedures above.

get_fields

  my @fields = Geo::postcodes::U2::get_fields();
  my @fields = $P->get_fields();

is_field

  my $boolean = Geo::postcodes::U2::is_field($field);
  my $boolean = $P->is_field($field);

A sample program

Specify one or more postcodes on the command line; e.g. ""basic_u2 1001 1003"".

 01 #! /usr/bin/perl -w
 02 use strict;
 03 use Geo::Postcodes::U2 0.30;

The example will not work with older versions of the module.

 04 unless (@ARGV)
 05 {
 06   print "Usage: basic_u2 <one or more utopian postcodes>\n";
 07   exit;
 08 }

Exit with an error message if the program hasn't been given any arguments.

 09 foreach my $postcode (@ARGV)
 10 {

Loop through the arguments, and create a postcode object for each one.

 11   if (my $P = Geo::Postcodes::U2->new($postcode)))
 12   {

Skip the argument if it isn't a valid postcode. The "new"-call returns an object reference on success, and undef on failure (i.e. an illegal or unvalid postcode).

 13     foreach my $field (Geo::Postcodes::U2::get_fields())
 14     {
 15       printf("%-10s\t%s\n", ucfirst($field), $P->$field() || ""),
 16     }

For each field supported by the module, we print the field name (with an initial uppercase letter), followed by the value of the field. All tabulated nicely.

 17      printf("%-10s\t%s\n\n", "Type_english", 
 18        Geo::Postcodes::type2verbose($P->type()));
 19   }

We must ask for the english description of the type manually.

 20   else # Not valid.
 21   {
 22     if (Geo::Postcodes::U2::legal($postcode))
 23     {
 24       print "Postcode '$postcode' not in use.\n\n";
 25     }
 26     else
 27     {
 28       print "Illegal postcode '$postcode'.\n\n";
 29     }
 30   }
 31 }

This part will be called if the "new"-call fails, and we will get an error message telling us what is wrong; if the argument is illegal (not following the rules for utopian postcodes) or invalid (not in use).

get_postcodes

  @postcodes =      Geo::postcodes::U2::get_postcodes(); # Unsorted
  @postcodes = sort Geo::postcodes::U2::get_postcodes(); # Sorted

This procedure returns an unsorted list of all the postcodes.

It is possible to use this call to write your own selection code:

  my @list;
  foreach my $postcode (Geo::postcodes::U2::get_postcodes())
  {
    push(@list, $postcode) if check_the_postcode_for_something($postcode);
  }

Write the "check_the_postcode_for_something"-procedure to decide if the postcode should be included. Use the "xxx_of"-procedures, or whatever else is needed. Do not create postcode objects inside this loop, as this will increase the time of execution quite a lot.

selection

See the selection manual (perldoc Geo::Postcodes::Selection or man Geo::Postcodes::Selection) for further information.

selection_loop

  my @list = Geo::postcodes::U2::selection(....);
  foreach my $postcode (@list)
  {
    do_something($postcode)
  }

The following line of code will do the same thing:

  Geo::postcodes::U2::selection_loop(\&do_something, ....);

The loop can use postcode objects instead of plain postcodes, as with selection.

  Geo::postcodes::U2->selection_loop(\&do_something, ....);

The benefit of this is that the "selection"-method will generate all the postcode objects, before passing them on, while this method will generate one at a time, destroying the prevoius one before creating a new.

verify_selectionlist

  my ($status, @modified) = Geo::Postcodes::U2::verify_selectionlist(@args);

  if ($status)
  {
    my @result = Geo::Postcodes::U2::selection(@modified);
     # And do something with the list of postcodes.
  }
  else
  {
    print "Diagnostic messages:\n";
    map { print " - $_\n" } @modified;
  }

A second program

Specify a field and a value on the command line, e.g. ""selection_u2 postcode %12"".

 01 #! /usr/bin/perl -w
 02 use strict;
 03 use Geo::Postcodes::DK 0.30;
 
 04 unless (@ARGV == 2)
 05 {
 06  print "Usage: selection_u2 <field> <value>\n";
 07  print "Legal fields: ", join(" ", Geo::Postcodes::U2::get_fields()), ".\n";
 08  exit;
 09 }

This program requires exactly two arguments, a field and a value, and is terminated if the are missing.

 10 my $field = shift(@ARGV);
 11 my $value = shift(@ARGV);
 12 my @fields;

 13 if (Geo::Postcodes::U2::is_field($field))
 14 {

Do we have a legal field? (If not, the "else"-part below will give an error message.

 15   @fields = Geo::Postcodes::U2::get_fields();

Get the list of available fields for this class.

 16   foreach my $m (@fields)
 17   {
 18     printf("%-14s", ucfirst($m));
 19   }
 20   print "\n";

We are going to print one line for each matching postcode, and this will give us a header line.

 21   Geo::Postcodes::U2->selection_loop(\&print_it, $field, $value);

This piece of magic will use the "select" method to find any matching postcodes, and pass them on as a postcode pbject to the specified "print_it" procedure - one at a time.

 22   print "\n";
 23 }

 24 else # illegal field.
 25 {
 26   print "Not a legal field '$field'.\n";
 27 }

A simple error message.

 28 sub print_it
 29 {
 30   my $object = shift;
 31   foreach my $method (@fields)
 32   {
 33     printf("%-14s", $object->$method() || "");
 34   }
 35   print "\n";
 36 }

This procedure is called for each matching postcode, and receives a postcode object as argument. The "foreach" loop uses the list of fields set up in line 15. The second part of the argument in the "print" statement traps errors, as the call returns undef if the value is undefined for the given postcode, and printing an undefined value gives a warning.

A third program

Specify a field and a value on the command line, e.g. ""multiselection_u2 postcode %12"" (for postcodes ending with '12').

 01 #! /usr/bin/perl -w
 02 use strict;
 03 use Geo::Postcodes::U2 0.30;

This should be familiar by now.

 04 my ($status, @lines) = Geo::Postcodes::U2::verify_selectionlist(@ARGV);

Simply passing a list of arguments on to "selection" is not a good idea, as it will return an empty list both on failure (as in syntax errors, illegal modes or fields) and when the call itself didn't match anything.

Use "verify_selectionlist" to check the argument list for errors. The $status variable is true if the argument list is legal, and false otherwise.

 11 if ($status == 0)
 12 {
 13   print "Usage: \n",
 14         " * multiselection_u2 [all|none]\n",
 15         " * multiselection_u2 [" , 
 16         join("|", Geo::Postcodes::get_initial_selectionmodes()),
 17         "]? <field> <value> [[",
 18         join("|", Geo::Postcodes::get_selectionmodes()),
 19         "]? [<field> <value>]]*\n\n";
 20   print "Legal fields: ", join(", ", Geo::Postcodes::U2::get_fields()), "\n\n";

We use several procedures to show the legal modes and fields. This ensures that we do not have to update the program if we add new modes or fields in the modules later on (and that the code, as shown, will work for all country modules; after substituting 'U2' and 'u2' with another country code.) ).

 21   print "Diagnostic output:\n";
 22   foreach (@lines)
 23   {
 24     print " * $_\n";
 25   }

The @lines variable contains diagnostic output on failure, and they are printed as a service to the user - to help correct the error.

 26   exit;
 27 }

 28 my @fields = Geo::Postcodes::U2::get_fields();
 29 foreach my $m (@fields)
 30 {
 31   printf("%-14s", ucfirst($m)); # Print headers for each column
 32 }
 33 print "\n";
 
 34 foreach my $P (Geo::Postcodes::U2->selection(@lines))
 35 {

Note that we use the argument list as returned by the "verify_selectionlist" call, as it corrects some mistakes that the "selection" procedure/method does not cope with.

 36   foreach my $method (@fields)
 37   {
 38     printf("%-14s", $P->$method() || "");
 39   }
 40   print "\n";
 41 }
 42 print "\n";

Advanced selection

It is also possible to call external procedures, and have them decide if the postcode should be included. Specify 'procedure' and "\&procedure_to_do_the_job", instead of a field/value pair.

The procedure is passed the postcode, and must return true or false.

 sub procedure_to_do_the_job
 {
   my postcode = shift;
   return 1 if ...
   return 0;
 }

Passing a pointer to a non-existing procedure to selection will result in an empty list in return. verify_selectionlist can be used to check that any specified procedures actually exist.

A fourth program

 01 #! /usr/bin/perl -w
 02 use strict;
 03 use Geo::Postcodes::U2 0.30;

This should be familiar by now.

 04 use Digest::SHA1;

For the sake of this example, som computation had to be done that could not be done by a regular expression. This module was chosen.

 05 my @arg1 = ('postcode' => '(.)(.)\2\1');

We start with a regular expression, matching postcodes where the first and fourth digit are identical, as is the second and third.

 06 print "All norwegian postcodes where (...),\n";
 06 print "All norwegian postcodes where :\n";
 07 my @postcodes = Geo::Postcodes::NO::selection(@arg1);
 08 print join ",", @postcodes; print ".\n\n";

This prints the matching postcodes. Nothing fancy so far.

 09 print "As above, but with the addition of a procedure:\n";
 10 my @arg2 = (@arg1, 'procedure' => \&selector_procedure);

Now we have added a procedure to the argument list, and the selection call below does the job for us.

 11 @postcodes = Geo::Postcodes::NO::selection(@arg2);
 12 print join ",", @postcodes; print ".\n\n";

 13 sub selector_procedure
 14 {
 15   my $postcode = shift;
 16   my $location = Geo::Postcodes::NO::location_of($postcode);
 17   my $digest = Digest::SHA1::sha1($location);
 18   return 1 if substr($digest, 10, 5) =~ /[a-z]/;
 19   return 0;
 20 }

The procedure computes the SHA1-digest for the postal location, and returns true if the there is a lower case letter (a-z) among the 11th to 15th characters of the digest. This may not be very useful in practice...