tango.util.collection.impl.Collection

File:

Originally written by Doug Lea and released into the public domain. Thanks for the assistance and support of Sun Microsystems Labs, Agorics Inc, Loral, and everyone contributing, testing, and using this code.

History:

class Collection(T) : Dispenser!(T) ¶#

Collection serves as a convenient base class for most implementations of mutable containers. It maintains a version number and element count. It also provides default implementations of many collection operations.

Authors:

Doug Lea

uint vershion [protected] ¶#

version represents the current version number

Predicate screener [protected] ¶#

screener hold the supplied element screener

uint count [protected] ¶#

count holds the number of elements.

this(Predicate screener = null) [protected] ¶#

Initialize at version 0, an empty count, and supplied screener

bool isValidArg(T element) [protected, static, final] ¶#

T[] toArray() [public] ¶#

expose collection content as an array

bool drained() [public, final] ¶#

Time complexity: O(1).

See Also:

tango.util.collection.impl.Collection.Collection.drained

uint size() [public, final] ¶#

Time complexity: O(1).

Returns:

the count of elements currently in the collection

See Also:

tango.util.collection.impl.Collection.Collection.size

bool allows(T element) [public, final] ¶#

Checks if element is an allowed element for this collection. This will not throw an exception, but any other attemp to add an invalid element will do.

Time complexity: O(1) + time of screener, if present

See Also:

tango.util.collection.impl.Collection.Collection.allows

bool matches(ViewT other) [public] ¶#

Time complexity: O(n). Default implementation. Fairly sleazy approach. (Defensible only when you remember that it is just a default impl.) It tries to cast to one of the known collection interface types and then applies the corresponding comparison rules. This suffices for all currently supported collection types, but must be overridden if you define new Collection subinterfaces and/or implementations.

See Also:

tango.util.collection.impl.Collection.Collection.matches

uint mutation() [public, final] ¶#

Time complexity: O(1).

See Also:

tango.util.collection.impl.Collection.Collection.version

char[] toString() [public, override] ¶#

Default implementation of toString for Collections. Not very pretty, but parenthesizing each element means that for most kinds of elements, it's conceivable that the strings could be parsed and used to build other tango.util.collection.

Not a very pretty implementation either. Casts are used to get at elements/keys

char[] itoa(char[] buf, uint i) [protected, final] ¶#

void incVersion() [protected, final] ¶#

change the version number

void incCount() [protected, final] ¶#

Increment the element count and update version

void decCount() [protected, final] ¶#

Decrement the element count and update version

void addToCount(uint c) [protected, final] ¶#

add to the element count and update version if changed

void setCount(uint c) [protected, final] ¶#

set the element count and update version if changed

bool sameInclusions(ViewT s, ViewT t) [public, static, final] ¶#

Helper method left public since it might be useful

bool sameOccurrences(ViewT s, ViewT t) [public, static, final] ¶#

Helper method left public since it might be useful

bool sameOrderedElements(ViewT s, ViewT t) [public, static, final] ¶#

Helper method left public since it might be useful

void checkIndex(int index) [protected, final] ¶#

Principal method to throw a NoSuchElementException. Besides index checks in Seqs, you can use it to check for operations on empty collections via checkIndex(0)

void checkElement(T element) [protected, final] ¶#

Principal method to throw a IllegalElementException

void checkImplementation() [public] ¶#

See Also:

tango.util.collection.model.View.View.checkImplementation

void clear() [abstract] ¶#

Cause the collection to become empty.

void removeAll(T element) [abstract] ¶#

Exclude all occurrences of the indicated element from the collection. No effect if element not present.

Params:

element

the element to exclude. 1 2 3 4 !has(element) && size() == PREV(this).size() - PREV(this).instances(element) && no other element changes && Version change iff PREV(this).has(element)

void remove(T element) [abstract] ¶#

Remove an instance of the indicated element from the collection. No effect if !has(element)

Params:

element

the element to remove 1 2 3 4 5 let occ = max(1, instances(element)) in size() == PREV(this).size() - occ && instances(element) == PREV(this).instances(element) - occ && no other element changes && version change iff occ == 1

void replace(T oldElement, T newElement) [abstract] ¶#

Replace an occurrence of oldElement with newElement. No effect if does not hold oldElement or if oldElement.equals(newElement). The operation has a consistent, but slightly special interpretation when applied to Sets. For Sets, because elements occur at most once, if newElement is already included, replacing oldElement with with newElement has the same effect as just removing oldElement.

1 2 3 4 5 6 7 8

let int delta = oldElement.equals(newElement)? 0 : max(1, PREV(this).instances(oldElement) in instances(oldElement) == PREV(this).instances(oldElement) - delta && instances(newElement) == (this instanceof Set) ? max(1, PREV(this).instances(oldElement) + delta): PREV(this).instances(oldElement) + delta) && no other element changes && Version change iff delta != 0

Throws:

IllegalElementException if has(oldElement) and !allows(newElement)

void replaceAll(T oldElement, T newElement) [abstract] ¶#

Replace all occurrences of oldElement with newElement. No effect if does not hold oldElement or if oldElement.equals(newElement). The operation has a consistent, but slightly special interpretation when applied to Sets. For Sets, because elements occur at most once, if newElement is already included, replacing oldElement with with newElement has the same effect as just removing oldElement.

1 2 3 4 5 6 7 8

let int delta = oldElement.equals(newElement)? 0 : PREV(this).instances(oldElement) in instances(oldElement) == PREV(this).instances(oldElement) - delta && instances(newElement) == (this instanceof Set) ? max(1, PREV(this).instances(oldElement) + delta): PREV(this).instances(oldElement) + delta) && no other element changes && Version change iff delta != 0

Throws:

IllegalElementException if has(oldElement) and !allows(newElement)

void removeAll(Iterator!(T) e) [abstract] ¶#

Exclude all occurrences of each element of the Iterator. Behaviorally equivalent to

1 2	while (e.more()) removeAll(e.get());

Param : e = the enumeration of elements to exclude.

Throws:

CorruptedIteratorException is propagated if thrown

See Also:

tango.util.collection.impl.Collection.Collection.removeAll

void remove(Iterator!(T) e) [abstract] ¶#

Remove an occurrence of each element of the Iterator. Behaviorally equivalent to

1 2	while (e.more()) remove (e.get());

Param:

e = the enumeration of elements to remove.

Throws:

CorruptedIteratorException is propagated if thrown

T take() [abstract] ¶#

Remove and return an element. Implementations may strengthen the guarantee about the nature of this element. but in general it is the most convenient or efficient element to remove.

Examples:

One way to transfer all elements from MutableCollection a to MutableBag b is:

1 2	while (!a.empty()) b.add(a.take());

Returns:

an element v such that PREV(this).has(v) and the postconditions of removeOneOf(v) hold.

Throws:

NoSuchElementException iff drained.