ArrayBag

java.lang.Object
- edu.colorado.collections.ArrayBag<E>

All Implemented Interfaces:

java.lang.Cloneable
```
public class ArrayBag<E>
extends java.lang.Object
implements java.lang.Cloneable
```
An ArrayBag is a generic collection of references to objects. The same object may appear multiple times in a bag.

See Also:

Java Source Code for this class (www.cs.colorado.edu/~main/edu/colorado/collections/ArrayBag.java) , IntArrayBag, LinkedBag

Note:

(1) The capacity of one of these bags can change after it's created, but the maximum capacity is limited by the amount of free memory on the machine. The constructor, addItem, clone, and union will result in an OutOfMemoryError when free memory is exhausted.
(2) A bag's capacity cannot exceed the maximum integer 2,147,483,647 (Integer.MAX_VALUE). Any attempt to create a larger capacity results in a failure due to an arithmetic overflow.
(3) Because of the slow linear algorithms of this class, large bags will have poor performance.

Constructor Summary

Constructors
Constructor and Description
`ArrayBag()` Initialize an empty bag with an initial capacity of 10.
`ArrayBag(int initialCapacity)` Initialize an empty bag with a specified initial capacity.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`add(E element)` Add a new element to this bag.
`void`	`addAll(ArrayBag<E> addend)` Add the contents of another bag to this bag.
`void`	`addMany(E... elements)` Add new elements to this bag.
`ArrayBag<E>`	`clone()` Generate a copy of this bag.
`int`	`countOccurrences(E target)` Accessor method to count the number of occurrences of a particular element in this bag.
`void`	`ensureCapacity(int minimumCapacity)` Change the current capacity of this bag.
`int`	`getCapacity()` Accessor method to get the current capacity of this bag.
`E`	`grab()` Accessor method to retrieve a random element from this bag.
`boolean`	`remove(E target)` Remove one copy of a specified element from this bag.
`int`	`size()` Determine the number of elements in this bag.
`void`	`trimToSize()` Reduce the current capacity of this bag to its actual size (i.e., the number of elements it contains).
`static <E> ArrayBag<E>`	`union(ArrayBag<E> b1, ArrayBag<E> b2)` Create a new bag that contains all the elements from two other bags.

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

- Constructor Detail
  - ArrayBag
```
public ArrayBag()
```
    Initialize an empty bag with an initial capacity of 10. Note that the addItem method works efficiently (without needing more memory) until this capacity is reached.
    
    Postcondition:
    
    This bag is empty and has an initial capacity of 10.
    
    Throws:
    
    java.lang.OutOfMemoryError - Indicates insufficient memory for: new Object[10].
  - ArrayBag
```
public ArrayBag(int initialCapacity)
```
    Initialize an empty bag with a specified initial capacity. Note that the addItem method works efficiently (without needing more memory) until this capacity is reached.
    
    Parameters:
    
    initialCapacity - the initial capacity of this bag
    
    Precondition:
    
    initialCapacity is non-negative.
    
    Postcondition:
    
    This bag is empty and has the given initial capacity.
    
    Throws:
    
    java.lang.IllegalArgumentException - Indicates that initialCapacity is negative.
    
    java.lang.OutOfMemoryError - Indicates insufficient memory for: new Object[initialCapacity].
- Method Detail
  - add
```
public void add(E element)
```
    Add a new element to this bag. If the new element would take this bag beyond its current capacity, then the capacity is increased before adding the new element.
    
    Parameters:
    
    element - the new element that is being inserted
    
    Postcondition:
    
    A new copy of the element has been added to this bag.
    
    Throws:
    
    java.lang.OutOfMemoryError - Indicates insufficient memory for increasing the bag's capacity.
    
    Note:
    
    An attempt to increase the capacity beyond Integer.MAX_VALUE will cause the bag to fail with an arithmetic overflow.
  - addAll
```
public void addAll(ArrayBag<E> addend)
```
    Add the contents of another bag to this bag.
    
    Parameters:
    
    addend - a bag whose contents will be added to this bag
    
    Precondition:
    
    The parameter, addend, is not null.
    
    Postcondition:
    
    The elements from addend have been added to this bag.
    
    Throws:
    
    java.lang.NullPointerException - Indicates that addend is null.
    
    java.lang.OutOfMemoryError - Indicates insufficient memory to increase the size of the bag.
    
    Note:
    
    An attempt to increase the capacity beyond Integer.MAX_VALUE will cause an arithmetic overflow that will cause the bag to fail. Such large collections should use a different bag implementation.
  - addMany
```
public void addMany(E... elements)
```
    Add new elements to this bag. If the new elements would take this bag beyond its current capacity, then the capacity is increased before adding the new elements.
    
    Parameters:
    
    elements - (a variable-arity argument) one or more new elements that are being inserted
    
    Postcondition:
    
    A new copy of the element has been added to this bag.
    
    Throws:
    
    java.lang.OutOfMemoryError - Indicates insufficient memory for increasing the bag's capacity.
    
    Note:
    
    An attempt to increase the capacity beyond Integer.MAX_VALUE will cause the bag to fail with an arithmetic overflow.
  - clone
```
public ArrayBag<E> clone()
```
    Generate a copy of this bag.
    
    Overrides:
    
    clone in class java.lang.Object
    
    Returns:
    
    The return value is a copy of this bag. Subsequent changes to the copy will not affect the original, nor vice versa.
    
    Throws:
    
    java.lang.OutOfMemoryError - Indicates insufficient memory for creating the clone.
  - countOccurrences
```
public int countOccurrences(E target)
```
    Accessor method to count the number of occurrences of a particular element in this bag.
    
    Parameters:
    
    target - the element that needs to be counted
    
    Returns:
    
    the number of times that target occurs in this bag
  - ensureCapacity
```
public void ensureCapacity(int minimumCapacity)
```
    Change the current capacity of this bag.
    
    Parameters:
    
    minimumCapacity - the new capacity for this bag
    
    Postcondition:
    
    This bag's capacity has been changed to at least minimumCapacity. If the capacity was already at or greater than minimumCapacity, then the capacity is left unchanged.
    
    Throws:
    
    java.lang.OutOfMemoryError - Indicates insufficient memory for: new Object[minimumCapacity].
  - getCapacity
```
public int getCapacity()
```
    Accessor method to get the current capacity of this bag. The add method works efficiently (without needing more memory) until this capacity is reached.
    
    Returns:
    
    the current capacity of this bag
  - grab
```
public E grab()
```
    Accessor method to retrieve a random element from this bag.
    
    Precondition:
    
    This bag is not empty.
    
    Returns:
    
    a randomly selected element from this bag
    
    Throws:
    
    java.lang.IllegalStateException - Indicates that the bag is empty.
  - remove
```
public boolean remove(E target)
```
    Remove one copy of a specified element from this bag.
    
    Parameters:
    
    target - the element to remove from the bag
    
    Returns:
    
    If target was found in the bag, then one copy of target has been removed and the method returns true. Otherwise the bag remains unchanged and the method returns false.
  - size
```
public int size()
```
    Determine the number of elements in this bag.
    
    Returns:
    
    the number of elements in this bag
  - trimToSize
```
public void trimToSize()
```
    Reduce the current capacity of this bag to its actual size (i.e., the number of elements it contains).
    
    Postcondition:
    
    This bag's capacity has been changed to its current size.
    
    Throws:
    
    java.lang.OutOfMemoryError - Indicates insufficient memory for altering the capacity.
  - union
```
public static <E> ArrayBag<E> union(ArrayBag<E> b1,
                                    ArrayBag<E> b2)
```
    Create a new bag that contains all the elements from two other bags.
    
    Type Parameters:
    
    E - the type of the elements in the bag
    
    Parameters:
    
    b1 - the first of two bags
    
    b2 - the second of two bags
    
    Precondition:
    
    Neither b1 nor b2 is null, and b1.getCapacity( ) + b2.getCapacity( ) <= Integer.MAX_VALUE.
    
    Returns:
    
    the union of b1 and b2
    
    Throws:
    
    java.lang.NullPointerException - Indicates that one of the arguments is null.
    
    java.lang.OutOfMemoryError - Indicates insufficient memory for the new bag.
    
    Note:
    
    An attempt to create a bag with a capacity beyond Integer.MAX_VALUE will cause an arithmetic overflow that will cause the bag to fail. Such large collections should use a different bag implementation.

Class ArrayBag<E>

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

ArrayBag

ArrayBag

Method Detail

add

addAll

addMany

clone

countOccurrences

ensureCapacity

getCapacity

grab

remove

size

trimToSize

union