edu.colorado.collections
Class LinkedBag<E>

java.lang.Object
  edu.colorado.collections.LinkedBag<E>

All Implemented Interfaces:

java.lang.Cloneable

public class LinkedBag<E>
extends java.lang.Object
implements java.lang.Cloneable

An LinkedBag is a collection of references to E objects.

See Also:

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

Note:

(1) Beyond Int.MAX_VALUE elements, countOccurrences, size, and grab are wrong.

(2) Because of the slow linear algorithms of this class, large bags will have poor performance.

Constructor Summary

LinkedBag()
Initialize an empty bag.

Method Summary

void	add(E element) Put a reference to an object into this bag.
void	addAll(LinkedBag<E> addend) Add the contents of another bag to this bag.
LinkedBag<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.
E	grab() Accessor method to retrieve a random element from this bag.
Lister<E>	iterator() Create an Iterator containing the elements of 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.
static <E> LinkedBag<E>	union(LinkedBag<E> b1, LinkedBag<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

LinkedBag

public LinkedBag()

Initialize an empty bag.

Parameters:

- - none

Postcondition:

This bag is empty.

Method Detail

add

public void add(E element)

Put a reference to an object into this bag. The new element may be the null reference.

Parameters:

element - the new element to be added to this bag

Postcondition:

The element has been added to this bag.

Throws:

java.lang.OutOfMemoryError - Indicates insufficient memory a new Node.

addAll

public void addAll(LinkedBag<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.

clone

public LinkedBag<E> clone()

Generate a copy of this bag.

Overrides:

clone in class java.lang.Object

Parameters:

- - none

Returns:

The return value is a copy of this bag. Subsequent changes to the copy will not affect the original, nor vice versa. Note that the return value must be type cast to an LinkedBag before it can be used.

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 return value is the number of times that target occurs in this bag. If target is non-null, then the occurrences are found using the target.equals method.

grab

public E grab()

Accessor method to retrieve a random element from this bag.

Parameters:

- - none

Precondition:

This bag is not empty.

Returns:

a randomly selected element from this bag

Throws:

java.lang.IllegalStateException - Indicates that the bag is empty.

iterator

public Lister<E> iterator()

Create an Iterator containing the elements of this bag.

Parameters:

- - none

Returns:

an Iterator containing the elements of this bag.

Note If changes are made to this bag before the Iterator returns all of its elements, then the subsequent behavior of the Iterator is unspecified.

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

Postcondition:

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.

Parameters:

- - none

Returns:

the number of elements in this bag

union

public static <E> LinkedBag<E> union(LinkedBag<E> b1,
                                     LinkedBag<E> b2)

Create a new bag that contains all the elements from two other bags.

Parameters:

b1 - the first of two bags

b2 - the second of two bags

Precondition:

Neither b1 nor b2 is null.

Returns:

the union of b1 and b2

Throws:

java.lang.IllegalArgumentException - Indicates that one of the arguments is null.

java.lang.OutOfMemoryError - Indicates insufficient memory for the new bag.