The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Business-FO-Postalcode-0.02
River stage zero No dependents
++
/ Class::Business::FO::Postalcode

NAME

Class::Business::FO::Postalcode - OO interface to validation and listing of Faroe Islands postal codes

VERSION

This documentation describes version 0.02

SYNOPSIS

    # construction
    my $validator = Business::FO::Postalcode->new();

    # basic validation of string
    if ($validator->validate($postalcode)) {
        print "We have a valid Faroe Islands postal code\n";
    } else {
        warn "Not a valid Faroe Islands postal code\n";
    }


    # All postal codes for use outside this module
    my @postalcodes = @{$validator->get_all_postalcodes()};


    # All postal codes and data for use outside this module
    my $postalcodes = $validator->get_all_data();

    foreach (@{postalcodes}) {
        printf
            'postal code: %s city: %s street/desc: %s company: %s province: %d country: %d', split /;/, $_, 6;
    }

FEATURES

  • Providing list of Faroe Islands postal codes and related area names

  • Look up methods for Faroe Islands postal codes for web applications and the like

DESCRIPTION

Please note that this class inherits from: https://metacpan.org/pod/Business::GL::Postalcode, so most of the functionality is implmented in the parent class.

This distribution is not the original resource for the included data, but simply acts as a simple distribution for Perl use. The central source is monitored so this distribution can contain the newest data. The monitor script (postdanmark.pl) is included in the distribution: https://metacpan.org/pod/Business::DK::Postalcode.

The data are converted for inclusion in this module. You can use different extraction subroutines depending on your needs:

Data

Here follows a description of the included data, based on the description from the original source and the authors interpretation of the data, including details on the distribution of the data.

city name

A non-unique, case-sensitive representation of a city name in Faroese or Danish.

street/description

This field is unused for this dataset.

company name

This field is unused for this dataset.

province

This field is a bit special and it's use is expected to be related to distribution all entries are marked as 'False'. The data are included since they are a part of the original data.

country

Since the original source contains data on 3 different countries:

  • Denmark (1)

  • Greenland (2)

  • Faroe Islands (3)

Only the data representing Faroe Islands has been included in this distribution, so this field is always containing a '3'.

For access to the data on Denmark or Greenland please refer to: Business::DK::Postalcode and Business::GL::Postalcode respectfully.

Encoding

The data distributed are in Faroese and Danish for descriptions and names and these are encoded in UTF-8.

SUBROUTINES AND METHODS

new

Basic contructor, takes no arguments. Load the dataset and returns a Class::Business::FO::Postalcode object.

validate

A simple validator for Faroese postal codes.

Takes a string representing a possible Faroese postal code and returns either 1 or 0 indicating either validity or invalidity.

    my $validator = Business::FO::Postalcode->new();

    my $rv = $validator->validate(100);

    if ($rv == 1) {
        print "We have a valid Faroese postal code\n";
    } ($rv == 0) {
        print "Not a valid Faroese postal code\n";
    }

get_all_postalcodes

Takes no parameters.

Returns a reference to an array containing all valid Faroese postal codes.

    my $validator = Business::FO::Postalcode->new();

    my $postalcodes = $validator->get_all_postalcodes;

    foreach my $postalcode (@{$postalcodes}) { ... }

get_all_cities

Takes no parameters.

Returns a reference to an array containing all Faroese city names having a postal code.

    my $validator = Business::FO::Postalcode->new();

    my $cities = $validator->get_all_cities;

    foreach my $city (@{$cities}) { ... }

Please note that this data source used in this distribution by no means is authorative when it comes to cities located in Denmark, it might have all cities listed, but unfortunately also other post distribution data.

get_city_from_postalcode

Takes a string representing a Faroese postal code.

Returns a single string representing the related city name or an empty string indicating nothing was found.

    my $validator = Business::FO::Postalcode->new();

    my $zipcode = '3900';

    my $city = $validator->get_city_from_postalcode($zipcode);

    if ($city) {
        print "We found a city for $zipcode\n";
    } else {
        warn "No city found for $zipcode";
    }

get_postalcode_from_city

Takes a string representing a Faroese city name.

Returns a reference to an array containing zero or more postal codes related to that city name. Zero indicates nothing was found.

Please note that city names are not unique, hence the possibility of a list of postal codes.

    my $validator = Business::FO::Postalcode->new();

    my $city = 'Tórshavn';

    my $postalcodes = $validator->get_postalcode_from_city($city);

    if (scalar @{$postalcodes} == 1) {
        print "$city is unique\n";
    } elsif (scalar @{$postalcodes} > 1) {
        warn "$city is NOT unique\n";
    } else {
        die "$city not found\n";
    }

num_of_digits_in_postalcode

Mutator to get/set the number of digits used to compose a Greenlandic postal code

    my $validator = Business::FO::Postalcode->new();

    my $rv = $validator->num_of_digits_in_postalcode(3);

    my $digits = $validator->num_of_digits_in_postalcode();

postal_data

Mutator to get/set the reference to the array comprising the main data structure

    my $validator = Business::FO::Postalcode->new();

    my $rv = $validator->postal_data(\@postal_data);

    my $postal_data = $validator->postal_data();

DIAGNOSTICS

There are not special diagnostics apart from the ones related to the different subroutines.

CONFIGURATION AND ENVIRONMENT

This distribution requires no special configuration or environment.

DEPENDENCIES

TEST

Please note that the above list does not reflect requirements for:

  • Additional components in this distribution, see lib/. Additional components list own requirements

  • Test and build system, please see: Build.PL for details

BUGS AND LIMITATIONS

There are no known bugs at this time.

The data source used in this distribution by no means is authorative when it comes to cities located in Faroe Islands, it might have all cities listed, but unfortunately also other post distribution data.

BUG REPORTING

Please report issues via CPAN RT:

SEE ALSO

Business::DK::Postalcode
Business::GL::Postalcode

MOTIVATION

Postdanmark the largest danish postal and formerly stateowned postal service, maintain the postalcode mapping for Greenland and the Faroe Islands. Since I am using this resource to maintain the danish postalcodes I decided to release distributions of these two other countries.

AUTHOR

Jonas B. Nielsen, (jonasbn) - <jonasbn@cpan.org>

COPYRIGHT

Class-Business-FO-Postalcode is (C) by Jonas B. Nielsen, (jonasbn) 2014

Class-Business-FO-Postalcode is released under the artistic license 2.0