The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Geo::Walkabout::Line - A "line feature"

SYNOPSIS

  require Geo::Walkabout::Line;

  my $line = Geo::Walkabout::Line->retrieve($tlid);
  my $line = Geo::Walkabout::Line->new(\%data);

  $line->delete;

  my $id   = $line->id;
  my $name = $line->name;

  my($zip_left, $zip_right) = $line->zip;

  my @address_ranges = $line->addresses_left;
  my @address_ranges = $line->addresses_right;
  $line->add_addresses($side, @address_ranges);

  my $chain = $line->chain;

  $line->TLID;

  $line->FeDirP;
  $line->FeName;
  $line->FeType;
  $line->FeDirS;

  $line->ZipL;
  $line->Zip4L;
  $line->ZipR;
  $line->Zip4R;

  $line->commit;
  $line->rollback;

DESCRIPTION

This represents a complete "line feature". Roads, waterways, fences, power lines, railroads, boundries... See chapter 3 of the TIGER/Line documentation for details.

Public Methods

Constructors and Destructors

Geo::Walkabout::Line is a subclass of Class::DBI and expects to be stored in a database.

retrieve
  my $line = Geo::Walkabout::Line->retrieve($id);

Retrieve an existing line feature from the database by its ID.

new
  my $line = Geo::Walkabout::Line->new(\%data);

Create a new line feature. %data must contain the following fields...

    TLID        Unique TIGER/Line ID
    Chain       A Geo::Walkabout::Chain object representing the line

And optionally contain these...

    FeDirP      See accessor descriptions below
    FeName      for what these are
    FeType
    FeDirS

    ZipL
    Zip4L
    ZipR
    Zip4R
delete
  $line->delete;

Deletes this line feature from the database permanently.

Accessors

id
  my $id = $line->id

Returns a unique ID for this object, not necessarily the same as TLID.

NOTE Do NOT, I repeat, do NOT use attempt to use the TLID as a unique identifer for a Geo::Walkabout::Line object. While the TLID is unique, it is not guaranteed that all Geo::Walkabout::Line objects will have one. Geo::Walkabout::Line objects will come from many sources.

TLID
  my $tlid = $line->TLID;

Returns the TIGER/Line ID for this object.

name
  my $name = $line->name;

The complete name of this feature. Its roughly equivalent to:

  my $name = join ' ', $line->FeDirP, $line->FeName, $line->FeType, 
                       $line->FeDirS;

For example: "Elford PL"

zip
  my($zip_left, $zip_right) = $line->zip;

The zip code for the left and right side of this line. Zip may be the 5 digit zip code or the 9 digit zip +4.

addresses_left
addresses_right
  my @address_ranges = $line->addresses_left;
  my @address_ranges = $line->addresses_right;

The possible addresses on the left side of this line. @address_ranges is a list of range pairs (two element array refs). A range with the same start and end number (such as [146,146]) represents a single anomalous address.

The order is meaningless.

For example:

    # Represents that the addresses descend from 290 to 200 from the
    # start of the line to the end.  There is also a single outstanding
    # address #146 and an additional range of addresses from 20 to 10.
    # So 10-20, 146 and 200-290.
    ([290,200],[146,146],[20,10])
add_addresses
  $line->add_addresses($side, @address_ranges);

Addes a new address range to this line on the given $side. $side is either 'R' or 'L'. @address_range is a list of two element array references representing possible addresses on that side of the street. The ordering is from the start of the chain to the end.

chain
  my $chain = $line->chain;
  $line->chain($chain);

The Geo::Walkabout::Chain object representing the shape of this line feature. This is the important bit, the line's actual location in the world. Geo::Walkabout::Chain for details.

FeDirP
  my $fedirp = $line->FeDirP;
  $line->FeDirP($fedirp);

Feature Direction Prefix. For example, if you had "North Southington Road", "N" would be the FeDirP.

Possible values are "N", "NE", "NW", "S", "SE", "SW", "E", "W", "EX". "EX" means "Extended" or "Extension".

FeName
  my $fename = $line->FeName;
  $line->FeName($fename);

Feature Name. Continuing the example, "Southington" is the FeName.

FeType
  my $fetype = $line->FeType;
  $line->FeType($fetype);

Feature Type. "Rd" would be the feature type from above. Standard abbreviations can be found in Appendix D of the TIGER/Line documentation.

FeDirS
  my $fedirs = $line->FeDirS;
  $line->FeDirS($fedirs);

Feature Type Suffix. Same as FeDirP, except it follows the feature name. So for "Red Rock West", the FeDirS would be "W".

ZipL
ZipR
  my $zipl = $line->ZipL;
  $line->ZipL($zipl);
  my $zipr = $line->ZipR;
  $line->ZipR($zipr);

5 digit zip codes for the left and right side of this line.

Zip4L
Zip4R
  my $zip4l = $line->Zip4L;
  $line->Zip4L($zip4l);
  my $zip4r = $line->Zip4R;
  $line->Zip4R($zip4r);

4 digit +4 zip code extension for the left and right side of this line.

Other Methods

commit
  $line->commit;

Commit changes made to this line to the database.

rollback
  $line->rollback;

Throw away changes made to this line and refresh it from the database. If an object is changed and destroyed without committing or rolling back a warning will be thrown.

AUTHOR

Michael G Schwern <schwern@pobox.com>

SEE ALSO

Geo::Walkabout, Geo::TigerLine, Geo::Walkabout::Chain