## org.ascape.model.space
Class SubListSpace

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

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

    public class SubListSpace

extends ListSpace
implements SubSpace

A space list that is part of another space list. Any agents added to this list will also be added to the super list, and any agents removed from this list will be removed from the super list. Note that agents removed directly from the super list will not be removed from this list.

Since:
  2.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
`SubListSpace()` Constructs a sub-list list.
`SubListSpace(CoordinateDiscrete extent)` Constructs a sub-list list.

Method Summary
`void` `add(int index, java.lang.Object o, boolean isParent)` Adds the supplied object (agent) to this list at the specified location and to end of the super list.
`boolean` `add(java.lang.Object o, boolean isParent)` Adds the supplied object (agent) to this list at the specified location and to end of the super list.
`boolean` `addAll(java.util.Collection c)` Inserts all of the agents in the specified collection at the location specified in this list, and at the end of the super list.
`boolean` `addAll(int index, java.util.Collection c)` Inserts all of the agents in the specified collection at the location specified in this list, and at the end of the super list.
`protected void` `addToSuper(int index, java.lang.Object o, boolean isParent)` Adds the to super.
`double` `calculateDistance(Coordinate origin, Coordinate target)` Returns the shortest distance between one agent and the other, in the context of the superscape.
`void` `clear()` Removes all agents from the space, and all members of this space from the super list.
`Space` `getSuperSpace()` Returns the super list for this sub list, that is, the list defined to contain a superset of this space's agents.
`void` `moveAway(Location origin, Coordinate target, double distance)` Moves an agent toward the specified agent in the context of the superscape.
`void` `moveToward(Location origin, Coordinate target, double distance)` Moves an agent toward the specified agent in the context of the superscape.
`void` `populate()` Populates the space and its super list with clones of the prototype agent.
`boolean` `remove(java.lang.Object o)` Removes the supplied object (agent) from this list and its superlist.
`boolean` `removeAll(java.util.Collection c)` Removes all of the agnets contained in the collection from this space list and its super space list.
`boolean` `retainAll(java.util.Collection c)` Retains only the elements in the space that are in the specified collection.
`void` `setSuperSpace(Space superSpace)` Sets the super list for this sub list, that is, the list defined to contain a superset of this space's agents.

Methods inherited from class org.ascape.model.space.ListBase
`add, add, coordinateSweep, findCellAway, findCellToward, findFirstMatchInRank, findNearestMatchRank, findNearestMatchRank, findRandomMatchInRank, findWithinImpl, get, get, indexOf, isCoordinateSweepNeeded, lastIndexOf, listIterator, listIterator, remove, remove, set, set, setGeometry, subList`

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, calculateDistance, 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, newLocation, newLocation, randomInRange, randomInRange, randomIs, randomizeOrder, randomToLimit, 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 org.ascape.model.space.CoordinateMutable
`coordinateSweep, isCoordinateSweepNeeded`

Methods inherited from interface org.ascape.model.space.Mutable
`deleteSweep, isDeleteSweepNeeded, newLocation, newLocation`

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

Constructor Detail

### SubListSpace

    public SubListSpace()

  Constructs a sub-list list.

### SubListSpace

    public SubListSpace(CoordinateDiscrete extent)

  Constructs a sub-list list.

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

Method Detail

### populate

    public void populate()

  Populates the space and its super list with clones of the prototype agent. First removes any currently existing members from the super list to prevent orphans. Prototype agent should be set before calling this method. (By default, the prototpye agent is a Node.)

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

### remove

    public boolean remove(java.lang.Object o)

  Removes the supplied object (agent) from this list and its superlist. If the agent is _not_ a member of this space, but is a member of the super space, it is not removed from the super space.

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

### addAll

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

  Inserts all of the agents in the specified collection at the location specified in this list, and at the end of the super list. Assumes (but does not check) that all of the elements are instances of agent.

  Specified by:
    `addAll` in interface `java.util.List`
  Overrides:
    `addAll` in class `ListBase`
  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

### addAll

    public boolean addAll(java.util.Collection c)

  Inserts all of the agents in the specified collection at the location specified in this list, and at the end of the super list. Assumes (but does not check) that all of the elements are instances of agent.

  Specified by:
    `addAll` in interface `java.util.Collection`
  Specified by:
    `addAll` in interface `java.util.List`
  Overrides:
    `addAll` in class `CollectionSpace`
  Parameters:
    `c` - collection whose agents are to be added to the space
  Returns:
    true if the space had new agents added

### removeAll

    public boolean removeAll(java.util.Collection c)

  Removes all of the agnets contained in the collection from this space list and its super space list. No attempt is made to cache the removal; the agents are all removed at once.

  Specified by:
    `removeAll` in interface `java.util.Collection`
  Specified by:
    `removeAll` in interface `java.util.List`
  Overrides:
    `removeAll` in class `CollectionSpace`
  Parameters:
    `c` - collection whose agents are to be added to the space
  Returns:
    true if the space had agents (but not neccessarily all?) removed

### retainAll

    public boolean retainAll(java.util.Collection c)

  Retains only the elements in the space that are in the specified collection. Removes from the super space list those agents that are in this list but not in the specified reatined collection.

  Specified by:
    `retainAll` in interface `java.util.Collection`
  Specified by:
    `retainAll` in interface `java.util.List`
  Overrides:
    `retainAll` in class `CollectionSpace`
  Parameters:
    `c` - collection whose agents are to be retained in the space
  Returns:
    true if this space had agents removed

### clear

    public void clear()

  Removes all agents from the space, and all members of this space from the super list.

  Specified by:
    `clear` in interface `java.util.Collection`
  Specified by:
    `clear` in interface `java.util.List`
  Specified by:
    `clear` in interface `Mutable`
  Overrides:
    `clear` in class `CollectionSpace`

### addToSuper

    protected void addToSuper(int index,
                              java.lang.Object o,
                              boolean isParent)

  Adds the to super.

  Parameters:
    `index` - the index
    `o` - the o
    `isParent` - the is parent

### add

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

  Adds the supplied object (agent) to this list at the specified location and to end of the super 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 `ListBase`
  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(int index,
                    java.lang.Object o,
                    boolean isParent)

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

  Overrides:
    `add` in class `ListBase`
  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

### getSuperSpace

    public Space getSuperSpace()

  Returns the super list for this sub list, that is, the list defined to contain a superset of this space's agents.

  Specified by:
    `getSuperSpace` in interface `SubSpace`
  Returns:
    superSpace the list used as super set

### setSuperSpace

    public void setSuperSpace(Space superSpace)

  Sets the super list for this sub list, that is, the list defined to contain a superset of this space's agents. If a superlist had allready been assigned to this list, this list's elements are _not_ removed from the previous super list. Any agents allready members of this list would be added to the new superlist, however.

  Specified by:
    `setSuperSpace` in interface `SubSpace`
  Parameters:
    `superSpace` - the list to assign as super set

### moveToward

    public void moveToward(Location origin,
                           Coordinate target,
                           double distance)

  Moves an agent toward the specified agent in the context of the superscape.

  Specified by:
    `moveToward` in interface `Space`
  Overrides:
    `moveToward` in class `CollectionSpace`
  Parameters:
    `origin` - the agent moving
    `target` - the agent's target
    `distance` - the distance to move

### moveAway

    public void moveAway(Location origin,
                         Coordinate target,
                         double distance)

  Moves an agent toward the specified agent in the context of the superscape.

  Specified by:
    `moveAway` in interface `Space`
  Overrides:
    `moveAway` in class `CollectionSpace`
  Parameters:
    `origin` - the agent moving
    `target` - the agent's target
    `distance` - the distance to move

### calculateDistance

    public double calculateDistance(Coordinate origin,
                                    Coordinate target)

  Returns the shortest distance between one agent and the other, in the context of the superscape.

  Specified by:
    `calculateDistance` in interface `Space`
  Overrides:
    `calculateDistance` in class `ListBase`
  Parameters:
    `origin` - the starting cell
    `target` - the ending cell
  Returns:
    the double