/ 
Geo-Walkabout-0.01
River stage zero No dependents
/ Geo::Walkabout::Line

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