Class Bag
- All Implemented Interfaces:
Serializable
,Cloneable
,Iterable
,Collection
,Indexed
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 Summary
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionboolean
boolean
boolean
addAll
(int index, Collection other) boolean
boolean
boolean
addAll
(Collection other) boolean
void
clear()
Removes all objects in the Bag.clone()
Always returns null.boolean
boolean
void
copyIntoArray
(int fromStart, Object[] to, int toStart, int len) Copies 'len' elements from the Bag into the provided array.void
Replaces all elements in the bag with the provided object.get
(int index) getValue
(int index) identical to get(index)boolean
isEmpty()
iterator()
NOT fail-fast.pop()
Returns null if the Bag is empty, else removes and returns the topmost object.boolean
Synonym for add(obj) -- stylistically, you should add instead unless you want to think of the Bag as a stack.remove
(int index) Removes the object at the given index, moving the topmost object into its position.boolean
Removes the object, moving the topmost object into its position.boolean
boolean
Removes multiple instantiations of an objectremoveNondestructively
(int index) Removes the object at the given index, shifting the other objects down.boolean
Removes the object, shifting the other objects down.void
resize
(int toAtLeast) Resizes the internal array to at least the requested size.boolean
void
reverse()
Reverses order of the elements in the Bagidentical to set(index, element)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).void
shuffle
(MersenneTwisterFast random) Shuffles (randomizes the order of) the Bagvoid
Shuffles (randomizes the order of) the Bagint
size()
void
sort()
Sorts the bag under the assumption that all objects stored within are Comparable.void
sort
(Comparator c) Sorts the bag according to the provided comparatorObject[]
toArray()
Object[]
top()
Returns null if the Bag is empty, else returns the topmost object.Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface java.util.Collection
equals, hashCode, parallelStream, removeIf, spliterator, stream, toArray
-
Field Details
-
objs
-
numObjs
public int numObjs
-
-
Constructor Details
-
Bag
public Bag() -
Bag
public Bag(int capacity) Creates a Bag with a given initial capacity. -
Bag
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
Creates a Bag with the given elements. If the Other array is null, a new empty Bag is created. -
Bag
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 interfaceCollection
- Specified by:
size
in interfaceIndexed
-
isEmpty
public boolean isEmpty()- Specified by:
isEmpty
in interfaceCollection
-
addAll
- Specified by:
addAll
in interfaceCollection
-
addAll
-
addAll
-
addAll
-
addAll
-
addAll
-
clone
- Overrides:
clone
in classObject
- 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
Returns null if the Bag is empty, else returns the topmost object. -
pop
Returns null if the Bag is empty, else removes and returns the topmost object. -
push
Synonym for add(obj) -- stylistically, you should add instead unless you want to think of the Bag as a stack. -
add
- Specified by:
add
in interfaceCollection
-
contains
- Specified by:
contains
in interfaceCollection
-
containsAll
- Specified by:
containsAll
in interfaceCollection
-
get
-
getValue
identical to get(index) -
set
-
setValue
identical to set(index, element) -
removeAll
- Specified by:
removeAll
in interfaceCollection
-
retainAll
- Specified by:
retainAll
in interfaceCollection
-
removeNondestructively
Removes the object at the given index, shifting the other objects down. -
removeNondestructively
Removes the object, shifting the other objects down. -
remove
Removes the object, moving the topmost object into its position.- Specified by:
remove
in interfaceCollection
-
removeMultiply
Removes multiple instantiations of an object -
remove
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 interfaceCollection
-
toArray
- Specified by:
toArray
in interfaceCollection
-
toArray
- Specified by:
toArray
in interfaceCollection
-
copyIntoArray
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
NOT fail-fast. Use this method only if you're concerned about accessing numObjs and objs directly.- Specified by:
iterator
in interfaceCollection
- Specified by:
iterator
in interfaceIterable
-
componentType
Always returns null. This method is to adhere to Indexed.- Specified by:
componentType
in interfaceIndexed
-
sort
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
Replaces all elements in the bag with the provided object. -
shuffle
Shuffles (randomizes the order of) the Bag -
shuffle
Shuffles (randomizes the order of) the Bag -
reverse
public void reverse()Reverses order of the elements in the Bag
-