gov.usgs.earthquake.nshmp.geo

Class LocationList

java.lang.Object

gov.usgs.earthquake.nshmp.geo.LocationList

All Implemented Interfaces:

Iterable<Location>

public abstract class LocationList
extends Object
implements Iterable<Location>

An immutable, ordered collection of Locations.

A LocationList must contain at least 1 Location and does not permit null elements. LocationList instances are immutable and calls to remove() when iterating will throw an UnsupportedOperationException. A variety of methods exist to simplify the creation of new lists via modification (e.g. resample(double) , reverse(), and translate(LocationVector).

Consider using a LocationList.Builder (via builder()) if a list is being compiled from numerous Locations that are not known in advance.

Note: Although this class is not final, it cannot be subclassed outside its package as it has no public or protected constructors. Thus, instances of this type are guaranteed to be immutable.

Author:

Peter Powers

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	LocationList.Builder A reusable builder of LocationLists.

Method Summary

Modifier and Type	Method and Description
Bounds	bounds() Lazily compute the bounds of the Locations in this list.
static LocationList.Builder	builder() Return a new LocationList builder.
static LocationList	create(Iterable<Location> locs) Create a new LocationList containing all Locations in locs.
static LocationList	create(Location... locs) Create a new LocationList containing all Locations in locs.
double	depth() Lazily compute the average depth of the Locations in this list.
boolean	equals(Object obj)
Location	first() Return the first Location in this list.
static LocationList	fromString(String s) Create a new LocationList from the supplied String.
abstract Location	get(int index) Return the location at index.
int	hashCode()
Location	last() Return the last Location in this list.
double	length() Lazily compute the horizontal length of this LocationList in km.
List<LocationList>	partition(double length) Partition this LocationList into sub-lists of desired length.
LocationList	resample(double spacing) Return a new LocationList created by resampling this with the desired maximum spacing.
LocationList	reverse() Return a new LocationList with Locations in reverse order.
abstract int	size() Return the number of locations in this list.
String	toString()
LocationList	translate(LocationVector vector) Return a new LocationList with each Location translated according to the supplied vector.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Iterable

forEach, iterator, spliterator

Method Detail

create

public static LocationList create(Location... locs)

Create a new LocationList containing all Locations in locs.

Parameters:

locs - to populate list with

Throws:

IllegalArgumentException - if locs is empty

create

public static LocationList create(Iterable<Location> locs)

Create a new LocationList containing all Locations in locs. This method avoids copying the supplied iterable if it is safe to do so.

Parameters:

locs - to populate list with

Throws:

IllegalArgumentException - if locs is empty

fromString

public static LocationList fromString(String s)

Create a new LocationList from the supplied String. This method assumes that s is formatted as one or more space-delimited [lat,lon,depth] tuples (comma-delimited); see Location.fromString(String).

Parameters:

s - String to read

Returns:

a new LocationList

See Also:

Location.fromString(String)

size

public abstract int size()

Return the number of locations in this list.

get

public abstract Location get(int index)

Return the location at index.

Parameters:

index - of Location to return

Throws:

IndexOutOfBoundsException - if the index is out of range ( index < 0 || index >= size())

first

public Location first()

Return the first Location in this list.

last

public Location last()

Return the last Location in this list.

length

public double length()

Lazily compute the horizontal length of this LocationList in km. Method uses the Locations.horzDistanceFast(Location, Location) algorithm and ignores depth variation between locations. That is, it computes length as though all locations in the list have a depth of 0.0 km. Repeat calls to this method will recalculate the length each time.

Returns:

the length of the line connecting all Locations in this list, ignoring depth variations, or 0.0 if list only contains 1 location

depth

public double depth()

Lazily compute the average depth of the Locations in this list.

bounds

public Bounds bounds()

Lazily compute the bounds of the Locations in this list. Method delegates to Locations.bounds(Iterable).

toString

public String toString()

Overrides:

toString in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

resample

public LocationList resample(double spacing)

Return a new LocationList created by resampling this with the desired maximum spacing. The actual spacing of the returned list will likely differ, as spacing is adjusted down to maintain uniform divisions. The original vertices are also not preserved such that some corners might be adversely clipped if spacing is large. Buyer beware.

If the length of this list is less than the desired spacing, this list is returned.

Parameters:

spacing - resample interval

partition

public List<LocationList> partition(double length)

Partition this LocationList into sub-lists of desired length. The actual length of the returned lists will likely differ, as the lengths of the sub-lists are adjusted up or down to a value closest to the target length that yields sub-lists of equal length.

If this list is shorter than the sub-list target length, the method will return this.

Parameters:

length - target length of sub-lists

reverse

public LocationList reverse()

Return a new LocationList with Locations in reverse order.

translate

public LocationList translate(LocationVector vector)

Return a new LocationList with each Location translated according to the supplied vector.

Parameters:

vector - to translate list by

builder

public static LocationList.Builder builder()

Return a new LocationList builder.