## org.ascape.model.space
Class ListBase

    java.lang.Object
      org.ascape.model.space.CollectionSpace
          org.ascape.model.space.Discrete
              org.ascape.model.space.Array
                  org.ascape.model.space.ListBase

All Implemented Interfaces:
  java.io.Serializable, java.lang.Cloneable, java.lang.Iterable, java.util.Collection, java.util.List, Space, RandomFunctions

Direct Known Subclasses:
  Array1D, ListSpace

    public abstract class ListBase

extends Array
implements java.util.List

A one-dimensional, fixed-size, collection of agents providing services described for space.

Since:
  1.0
Version:
  3.0
Author:
  Miles Parker
See Also:
  Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class org.ascape.model.space.CollectionSpace
`CollectionSpace.ClosestDataPoint, CollectionSpace.ConditionalIterator, CollectionSpace.CSIterator, CollectionSpace.CSMutableIterator, CollectionSpace.ListMutableRandomIterator, CollectionSpace.ListRandomIterator, CollectionSpace.MutableSubIterator, CollectionSpace.SubIterator`

Field Summary

Fields inherited from class org.ascape.model.space.Array
`CACHE_RESULTS`

Fields inherited from class org.ascape.model.space.Discrete
`performanceWarning`

Fields inherited from class org.ascape.model.space.CollectionSpace
`collection, ESTIMATED_MAXIMUM_SIZE, extent, geometry`

Constructor Summary
`ListBase()` Constructs a space array.
`ListBase(CoordinateDiscrete extent)` Constructs a space array of provided extent, populated with clones of provided agent.

Method Summary
`void` `add(CoordinateDiscrete coordinate, java.lang.Object o)` Adds the supplied object (assumed to be an agent) to this list.
`void` `add(int index, java.lang.Object o)` Adds the supplied object (assumed to be an agent) to this list.
`void` `add(int index, java.lang.Object o, boolean isParent)` Adds the supplied object (agent) to this list.
`boolean` `add(java.lang.Object o, boolean isParent)` Adds the supplied object (agent) to this list.
`boolean` `addAll(int index, java.util.Collection c)` Inserts all of the agents in the specified collection at the location specified.
`double` `calculateDistance(Coordinate origin, Coordinate target)` Returns the shortest distance between one Location and another.
`void` `coordinateSweep()` Walks through each agent, setting the agent's coordinates.
`Node` `findCellAway(Node origin, Node target)` Returns the cell within immediate neighborhood furthest away from the requested cell.
`Node` `findCellToward(Node origin, Node target)` Returns the next cell within immediate neighborhood toward the requested cell.
`Node` `findFirstMatchInRank(Coordinate origin, Conditional condition, int rank)` Returns a random element in the supplied rank that matches the supplied condition, null if no matches.
`int` `findNearestMatchRank(Coordinate origin, Conditional condition, boolean includeOrigin)` Returns the nearest rank that includes a cell which matches the supplied condition, -1 if no matches.
`int` `findNearestMatchRank(Coordinate origin, Conditional condition, boolean includeOrigin, double maximumDistance)` Returns the nearest rank that includes a cell which matches the supplied condition, -1 if no matches.
`Location` `findRandomMatchInRank(Coordinate origin, Conditional condition, int rank)` Returns a random element in the supplied rank that matches the supplied condition, null if no matches.
`java.util.List` `findWithinImpl(Coordinate origin, boolean includeSelf, double distance)` Returns cells that are near the provided cell.
`Node` `get(CoordinateDiscrete coordinate)` Returns the agents at the specified index.
`java.lang.Object` `get(int index)` Returns the agents at the specified index.
`int` `indexOf(java.lang.Object o)` Returns the index in this list of the first occurrence of the agent.
`boolean` `isCoordinateSweepNeeded()` Is a coordinate location sweep needed for this space? Intended for internal purposes.
`int` `lastIndexOf(java.lang.Object o)` Returns the index in this list of the last occurrence of the agent.
`java.util.ListIterator` `listIterator()` Returns a list iterator across all agents in this space.
`java.util.ListIterator` `listIterator(int index)` Returns a list iterator across all agents in this space, beginning at the specified index.
`void` `populate()` Populates the space with clones of the prototype agent.
`java.lang.Object` `remove(CoordinateDiscrete coordinate)` Removes the agent at the specified coordinate from this list.
`java.lang.Object` `remove(int index)` Removes the agent at the specified position from this list.
`boolean` `remove(java.lang.Object o)` Removes the supplied object (agent) from this list.
`Node` `set(int index, Location o, boolean isParent)` Sets the agent at the specified coordinate to the supplied agent.
`java.lang.Object` `set(int index, java.lang.Object o)` Sets the agent at the specified coordinate to the supplied agent.
`void` `setGeometry(Geometry geometry)` Sets the geometry of this space.
`java.util.List` `subList(int fromIndex, int toIndex)` Returns a view of a sublist of this list between the specified indices.

Methods inherited from class org.ascape.model.space.Array
`findNearest, findWithin, replace, swap`

Methods inherited from class org.ascape.model.space.Discrete

`bfsWithinIterator, calculateDistance, calculateNeighbors, findAvailable, findAvailable, findCellAwayBFS, findCellTowardBFS, findNearestAvailable, findNearestBFS, findNeighbors, findOccupants, findOccupants, findRandomAvailable, findRandomAvailable, findRandomAvailable, findRandomAvailableNeighbor, findRandomNeighbor, findRandomNeighbor, findRandomUnoccupiedCell, findRandomUnoccupiedCell, findWithinDefault, getCells, getCellsNearDefault, getDistance, getMaximumRank, getSize`

Methods inherited from class org.ascape.model.space.CollectionSpace

`add, addAll, calculateDistance, clear, clone, conditionalIterator, conditionalIterator, construct, contains, containsAll, countWithin, createOrder, createSpatialConditional, deleteSweep, filter, find, findMaximum, findMaximum, findMaximumWithin, findMinimum, findMinimum, findMinimumWithin, findNearest, findRandom, findRandom, findRandom, findRandom, findRandomCoordinate, findRandomWithin, get, getContext, getExtent, getGeometry, getRandom, hasWithin, initialize, isDeleteSweepNeeded, isEmpty, isMutable, isPeriodic, iterator, iteratorCount, iteratorToList, moveAway, moveToward, newLocation, newLocation, randomInRange, randomInRange, randomIs, randomizeOrder, randomToLimit, removeAll, retainAll, safeIterator, safeIterator, safeIterators, safeRandomIterator, set, setContext, setExtent, setExtent, setPeriodic, setRandom, setSize, size, toArray, toArray, toList, withinIterator`

Methods inherited from class java.lang.Object
`equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Methods inherited from interface java.util.List
`add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, removeAll, retainAll, size, toArray, toArray`

Constructor Detail

### ListBase

    public ListBase()

  Constructs a space array.

### ListBase

    public ListBase(CoordinateDiscrete extent)

  Constructs a space array of provided extent, populated with clones of provided agent.

  Parameters:
    `extent` - a coordinate describing the size of this space

Method Detail

### populate

    public void populate()

  Populates the space with clones of the prototype agent. Prototype agent should be set before calling this method.

  Specified by:
    `populate` in interface `Space`
  Overrides:
    `populate` in class `CollectionSpace`

### add

    public void add(int index,
                    java.lang.Object o)

  Adds the supplied object (assumed to be an agent) to this list.

  Specified by:
    `add` in interface `java.util.List`
  Parameters:
    `index` - location to insert the new agent
    `o` - the agent to add

### add

    public void add(int index,
                    java.lang.Object o,
                    boolean isParent)

  Adds the supplied object (agent) to this list. The object is assumed to be an agent, though that behavior may be loosened at some point.

  Parameters:
    `index` - location to insert the new agent
    `o` - the agent to add
    `isParent` - should this space be made the parent space of the agent?
  Throws:
    `java.lang.ClassCastException` - if the object is not an instance of agent

### add

    public boolean add(java.lang.Object o,
                       boolean isParent)

  Adds the supplied object (agent) to this list. The object is assumed to be an agent, though that behavior may be loosened at some point.

  Specified by:
    `add` in interface `Space`
  Overrides:
    `add` in class `CollectionSpace`
  Parameters:
    `o` - the agent to add
    `isParent` - should this space be made the parent space of the agent?
  Returns:
    true, if add
  Throws:
    `java.lang.ClassCastException` - if the object is not an instance of agent

### add

    public void add(CoordinateDiscrete coordinate,
                    java.lang.Object o)

  Adds the supplied object (assumed to be an agent) to this list.

  Parameters:
    `coordinate` - the coordinate to insert the new agent at
    `o` - the agent to add

### addAll

    public boolean addAll(int index,
                          java.util.Collection c)

  Inserts all of the agents in the specified collection at the location specified. Assumes (but does not check) that all of the elements are instances of agent.

  Specified by:
    `addAll` in interface `java.util.List`
  Parameters:
    `index` - the location at which to place the agents
    `c` - collection whose agents are to be added to the space
  Returns:
    true if the space had new agents added

### remove

    public java.lang.Object remove(CoordinateDiscrete coordinate)

  Removes the agent at the specified coordinate from this list.

  Parameters:
    `coordinate` - coordinate of the agent to delete
  Returns:
    the agent removed

### remove

    public java.lang.Object remove(int index)

  Removes the agent at the specified position from this list.

  Specified by:
    `remove` in interface `java.util.List`
  Parameters:
    `index` - location of the agent to delete
  Returns:
    the agent removed

### remove

    public boolean remove(java.lang.Object o)

  Removes the supplied object (agent) from this list.

  Specified by:
    `remove` in interface `java.util.Collection`
  Specified by:
    `remove` in interface `java.util.List`
  Overrides:
    `remove` in class `CollectionSpace`
  Parameters:
    `o` - the agent to be removed
  Returns:
    true if the agent was deleted, false otherwise

### set

    public java.lang.Object set(int index,
                                java.lang.Object o)

  Sets the agent at the specified coordinate to the supplied agent. The object is expected to be an agent, though this requirement may be loosened at some point.

  Specified by:
    `set` in interface `java.util.List`
  Parameters:
    `index` - the lcoation to add the agent at
    `o` - the agent to add
  Returns:
    the agent (if any) replaced at the location

### set

    public Node set(int index,
                    Location o,
                    boolean isParent)

  Sets the agent at the specified coordinate to the supplied agent. The object is expected to be an agent, though this requirement may be loosened at some point.

  Parameters:
    `index` - the location to add the agent at
    `o` - the agent to add
    `isParent` - should this space be made the parent space of the agent?
  Returns:
    the node

### setGeometry

    public void setGeometry(Geometry geometry)

  Sets the geometry of this space. Must of course be one-dimensional.

  Overrides:
    `setGeometry` in class `CollectionSpace`
  Parameters:
    `geometry` - the basic geometry of this space

### indexOf

    public int indexOf(java.lang.Object o)

  Returns the index in this list of the first occurrence of the agent.

  Specified by:
    `indexOf` in interface `java.util.List`
  Parameters:
    `o` - the agent to search for.
  Returns:
    the index in this list of the first matching agent

### lastIndexOf

    public int lastIndexOf(java.lang.Object o)

  Returns the index in this list of the last occurrence of the agent. (Obviously, this will typically be the same as indexOf, as agents do not typically appear in the same space twice.)

  Specified by:
    `lastIndexOf` in interface `java.util.List`
  Parameters:
    `o` - the agent to search for.
  Returns:
    the index in this list of the first matching agent

### calculateDistance

    public double calculateDistance(Coordinate origin,
                                    Coordinate target)

  Description copied from class: `CollectionSpace`
  Returns the shortest distance between one Location and another. Warning: this default method only returns a coordinate specific distance. It uses no information about the context context; for example wether it is a periodic (wrapping) space or not. Therefore, if you implement your own versions of CollectionSpace, ensure that you have properly implemented a version of this method. (All Ascape spaces properly overide this method.)

  Specified by:
    `calculateDistance` in interface `Space`
  Overrides:
    `calculateDistance` in class `Discrete`
  Parameters:
    `origin` - one Location
    `target` - another Location
  Returns:
    the double

### findWithinImpl

    public java.util.List findWithinImpl(Coordinate origin,
                                         boolean includeSelf,
                                         double distance)

  Returns cells that are near the provided cell. Need to fix for non-periodic space!

  Specified by:
    `findWithinImpl` in class `Array`
  Parameters:
    `origin` - the coordinate to find cells near
    `distance` - the distance to form centralCells to return cells
    `includeSelf` - should supplied agent be included in the return set
  Returns:
    the list

### findCellToward

    public Node findCellToward(Node origin,
                               Node target)

  Returns the next cell within immediate neighborhood toward the requested cell.

  Specified by:
    `findCellToward` in class `Discrete`
  Parameters:
    `origin` - the current cell
    `target` - the cell that we are moving toward
  Returns:
    the node

### findCellAway

    public Node findCellAway(Node origin,
                             Node target)

  Returns the cell within immediate neighborhood furthest away from the requested cell.

  Specified by:
    `findCellAway` in class `Discrete`
  Parameters:
    `origin` - the current cell
    `target` - the cell that we are moving toward
  Returns:
    the node

### findNearestMatchRank

    public int findNearestMatchRank(Coordinate origin,
                                    Conditional condition,
                                    boolean includeOrigin)

  Returns the nearest rank that includes a cell which matches the supplied condition, -1 if no matches.

  Parameters:
    `origin` - the agent to find cells near
    `condition` - the condition that found cell must meet
    `includeOrigin` - should supplied agent (rank 0) be included in the search
  Returns:
    the int

### findNearestMatchRank

    public int findNearestMatchRank(Coordinate origin,
                                    Conditional condition,
                                    boolean includeOrigin,
                                    double maximumDistance)

  Returns the nearest rank that includes a cell which matches the supplied condition, -1 if no matches. Special Note: uses euclidian, _not_ geometry specific distance; this will be fixed soon.

  Specified by:
    `findNearestMatchRank` in class `Array`
  Parameters:
    `origin` - the agent to find cells near
    `condition` - the condition that found cell must meet
    `includeOrigin` - should supplied agent (rank 0) be included in the search
    `maximumDistance` - the maximum distance to search within
  Returns:
    the int

### findFirstMatchInRank

    public Node findFirstMatchInRank(Coordinate origin,
                                     Conditional condition,
                                     int rank)

  Returns a random element in the supplied rank that matches the supplied condition, null if no matches. Special Note: uses euclidian, _not_ geometry specific distance; this will be fixed soon.

  Parameters:
    `origin` - the agent to find cells near
    `condition` - the condition that found cell must meet
    `rank` - the rank to return match in
  Returns:
    the node

### findRandomMatchInRank

    public Location findRandomMatchInRank(Coordinate origin,
                                          Conditional condition,
                                          int rank)

  Returns a random element in the supplied rank that matches the supplied condition, null if no matches. Special Note: uses euclidian, _not_ geometry specific distance; this will be fixed soon.

  Specified by:
    `findRandomMatchInRank` in class `Array`
  Parameters:
    `origin` - the agent to find cells near
    `condition` - the condition that found cell must meet
    `rank` - the rank to return match in
  Returns:
    the location

### listIterator

    public java.util.ListIterator listIterator()

  Returns a list iterator across all agents in this space. The notes for iterator apply equally to the list iterators.

  Specified by:
    `listIterator` in interface `java.util.List`
  Returns:
    an iterator over the agents in space order

### listIterator

    public java.util.ListIterator listIterator(int index)

  Returns a list iterator across all agents in this space, beginning at the specified index. The notes for iterator apply equally to the list iterators.

  Specified by:
    `listIterator` in interface `java.util.List`
  Parameters:
    `index` - index of first agent to be returned
  Returns:
    an iterator over the agents in space order

### subList

    public java.util.List subList(int fromIndex,
                                  int toIndex)

  Returns a view of a sublist of this list between the specified indices. See important Java List comments.

  Specified by:
    `subList` in interface `java.util.List`
  Parameters:
    `fromIndex` - the low index (inclusive)
    `toIndex` - the high index (exclusive)
  Returns:
    a view of the specified range within this list.
  Throws:
    `java.lang.IndexOutOfBoundsException` - for an illegal endpoint index value @ see java.util.List

### coordinateSweep

    public void coordinateSweep()

  Walks through each agent, setting the agent's coordinates. Warning -- should only be called on space's of which all agents have the space as a primary space.

### isCoordinateSweepNeeded

    public boolean isCoordinateSweepNeeded()

  Is a coordinate location sweep needed for this space? Intended for internal purposes.

  Returns:
    true, if is coordinate sweep needed

### get

    public java.lang.Object get(int index)

  Returns the agents at the specified index.

  Specified by:
    `get` in interface `java.util.List`
  Parameters:
    `index` - index of the agent to return.
  Returns:
    the agent at the specified place in the space
  Throws:
    `java.lang.IndexOutOfBoundsException` - if the index is out of range

### get

    public Node get(CoordinateDiscrete coordinate)

  Returns the agents at the specified index.

  Parameters:
    `coordinate` - location of the agent to return.
  Returns:
    the agent at the specified place in the space
  Throws:
    `java.lang.IndexOutOfBoundsException` - if the index is out of range