Package sim.util

Class Bag

java.lang.Object
sim.util.Bag
All Implemented Interfaces:
Serializable, Cloneable, Iterable, Collection, Indexed
public class Bag extends Object implements Collection, Serializable, Cloneable, Indexed
Maintains a simple array (objs) of Objects and the number of objects (numObjs) in the array (the array can be bigger than this number). Unlike Vector or ArrayList, Bag is designed to encourage direct access of the array. If you access the objects directly, they are stored in positions [0 ... numObjs-1]. If you wish to extend the array, you should call the resize method.

By providing direct access to the array, Bags are about three and a half times faster than ArrayLists (whose get/set methods unfortunately at present contain un-inlinable range bounds checks) and four times faster than Vectors (whose methods additionally are synchronized). Even Bag's built-in get() and set() methods, complete with range bounds checks, are twice the speed of ArrayLists. To get faster than a Bag, you'd have to go to a raw fixed-length array of the specific class type of your objects. Accessing a Bag's Object array and casting its Objects into the appropriate class is about 50% slower than accessing a fixed-length array of that class in the first place.

Bag is not synchronized, and so should not be accessed from different threads without locking on it or some appropriate lock object first. Bag also has an unusual, fast method for removing objects called remove(...), which removes the object simply by swapping the topmost object into its place. This means that after remove(...) is called, the Bag may no longer have the same order (hence the reason it's called a "Bag" rather than some variant on "Vector" or "Array" or "List"). You can guarantee order by calling removeNondestructively(...) instead if you wish, but this is O(n) in the worst case.

Bags provide iterators but you are strongly encouraged to just access the array instead. Iterators are slow. Bag's iterator performs its remove operation by calling removeNondestructively(). Like array access, iterator usage is undefined if objects are placed into the Bag or removed from the Bag in the middle of the iterator usage (except by using the iterator's remove operation of course).

See Also:

  • Field Details

    • objs

      public Object[] objs

    • numObjs

      public int numObjs

  • Constructor Details

    • Bag

      public Bag()

    • Bag

      public Bag(int capacity)
      Creates a Bag with a given initial capacity.

    • Bag

      public Bag(Bag other)
      Adds the objects from the other Bag without copying them. The size of the new Bag is the minimum necessary size to hold the objects. If the Other Bag is null, a new empty Bag is created.

    • Bag

      public Bag(Object[] other)
      Creates a Bag with the given elements. If the Other array is null, a new empty Bag is created.

    • Bag

      public Bag(Collection other)
      Creates a Bag with the given elements. If the Other Collection is null, a new empty Bag is created.

  • Method Details

    • size

      public int size()
      Specified by:
      size in interface Collection
      Specified by:
      size in interface Indexed

    • isEmpty

      public boolean isEmpty()
      Specified by:
      isEmpty in interface Collection

    • addAll

      public boolean addAll(Collection other)
      Specified by:
      addAll in interface Collection

    • addAll

      public boolean addAll(int index, Collection other)

    • addAll

      public boolean addAll(Object[] other)

    • addAll

      public boolean addAll(int index, Object[] other)

    • addAll

      public boolean addAll(Bag other)

    • addAll

      public boolean addAll(int index, Bag other)

    • clone

      public Object clone() throws CloneNotSupportedException
      Overrides:
      clone in class Object
      Throws:
      CloneNotSupportedException

    • resize

      public void resize(int toAtLeast)
      Resizes the internal array to at least the requested size.

    • shrink

      public void shrink(int desiredLength)
      Resizes the objs array to max(numObjs, desiredLength), unless that value is greater than or equal to objs.length, in which case no resizing is done (this operation only shrinks -- use resize() instead). This is an O(n) operation, so use it sparingly.

    • top

      public Object top()
      Returns null if the Bag is empty, else returns the topmost object.

    • pop

      public Object pop()
      Returns null if the Bag is empty, else removes and returns the topmost object.

    • push

      public boolean push(Object obj)
      Synonym for add(obj) -- stylistically, you should add instead unless you want to think of the Bag as a stack.

    • add

      public boolean add(Object obj)
      Specified by:
      add in interface Collection

    • contains

      public boolean contains(Object o)
      Specified by:
      contains in interface Collection

    • containsAll

      public boolean containsAll(Collection c)
      Specified by:
      containsAll in interface Collection

    • get

      public Object get(int index)

    • getValue

      public Object getValue(int index)
      identical to get(index)
      Specified by:
      getValue in interface Indexed

    • set

      public Object set(int index, Object element)

    • setValue

      public Object setValue(int index, Object element)
      identical to set(index, element)
      Specified by:
      setValue in interface Indexed

    • removeAll

      public boolean removeAll(Collection c)
      Specified by:
      removeAll in interface Collection

    • retainAll

      public boolean retainAll(Collection c)
      Specified by:
      retainAll in interface Collection

    • removeNondestructively

      public Object removeNondestructively(int index)
      Removes the object at the given index, shifting the other objects down.

    • removeNondestructively

      public boolean removeNondestructively(Object o)
      Removes the object, shifting the other objects down.

    • remove

      public boolean remove(Object o)
      Removes the object, moving the topmost object into its position.
      Specified by:
      remove in interface Collection

    • removeMultiply

      public boolean removeMultiply(Object o)
      Removes multiple instantiations of an object

    • remove

      public Object remove(int index)
      Removes the object at the given index, moving the topmost object into its position.

    • clear

      public void clear()
      Removes all objects in the Bag. This is done by clearing the internal array but not replacing it with a new, smaller one.
      Specified by:
      clear in interface Collection

    • toArray

      public Object[] toArray()
      Specified by:
      toArray in interface Collection

    • toArray

      public Object[] toArray(Object[] o)
      Specified by:
      toArray in interface Collection

    • copyIntoArray

      public void copyIntoArray(int fromStart, Object[] to, int toStart, int len)
      Copies 'len' elements from the Bag into the provided array. The 'len' elements start at index 'fromStart' in the Bag, and are copied into the provided array starting at 'toStat'.

    • iterator

      public Iterator iterator()
      NOT fail-fast. Use this method only if you're concerned about accessing numObjs and objs directly.
      Specified by:
      iterator in interface Collection
      Specified by:
      iterator in interface Iterable

    • componentType

      public Class componentType()
      Always returns null. This method is to adhere to Indexed.
      Specified by:
      componentType in interface Indexed

    • sort

      public void sort(Comparator c)
      Sorts the bag according to the provided comparator

    • sort

      public void sort()
      Sorts the bag under the assumption that all objects stored within are Comparable.

    • fill

      public void fill(Object o)
      Replaces all elements in the bag with the provided object.

    • shuffle

      public void shuffle(Random random)
      Shuffles (randomizes the order of) the Bag

    • shuffle

      public void shuffle(MersenneTwisterFast random)
      Shuffles (randomizes the order of) the Bag

    • reverse

      public void reverse()
      Reverses order of the elements in the Bag