Collection¶
Usage
use Collection;
or
import Collection;
Summary¶
A ‘Collection’ is an interface for a data structure that is a ‘contract’ between the user and implementer that it fulfills the following:
- Is safe parallel-safe, hence is safe to use across multiple tasks across multiple locales.
- Supports the basic operations that any data structure needs to be truly useful, that is:
- Insertion of an arbitrary element. From this, we can insert bulk arbitrary elements.
- Removal of an arbitrary element. From this, we can remove bulk arbitrary elements.
- Iteration over all elements. From this, we can perform lookups over all elements.
From the standpoint of the user, who directly benefits, they obtain a very nice but minimal guarantee on the object they are using, and from the implementor’s view, they get to the benefit from both implementing a well-design interface, and from getting some utility methods ‘for-free’.
Note
This module is a work in progress and may change in future releases.
Bugs and Known Issues¶
- Parallel iteration is not apart of the core Collections module as currently the Chapel compiler
will produce an internal error. As such, the utility methods provided ‘for-free’ use serial iteration.
This issue has been documented under issue #6998 . Couple this
fact with the fact that
break
ing out of a serial iterator will result in resource leakage, where destructors are not called, hence Collections using some RAII-based resource cleanup will end up leaking and potentially leaving the Collection in an undefined state. This has been documented under issue #6912 .
Methods¶
-
class
CollectionImpl
¶ -
type
eltType
¶ The type of element that this Collection holds.
-
proc
init
(type eltType)¶
-
proc
add
(elt: eltType): bool¶ Adds an element to this data structure.
-
proc
addBulk
(elts): int¶ Add all elements in bulk to this data structure. If the data structure rejects an element, we cease to offer more. We return the number of elements successfully added to this data structure.
-
proc
remove
(): (bool, eltType)¶ Removes an arbitrary element from this data structure.
-
proc
removeBulk
(nElts: int)¶ Removes nElts elements from this data structure, returning them as an array. If the data structure fails to produce a new element, we cease and shrink the array to its appropriate size and return that.
-
proc
contains
(elt: eltType): bool¶ Determine whether an element exists in this collection.
-
proc
clear
()¶ Clears all elements in this collection.
-
proc
isEmpty
(): bool¶ Check if this data structure is empty.
-
proc
length
: int¶ Deprecated - please use
CollectionImpl.size
.
-
proc
size
: int¶ Syntactic sugar for getSize.
-
proc
getSize
(): int¶ Obtain the number of elements contained in this collection.
-
iter
these
(): eltType¶ Iterate over all elements in the data structure.
-
type
-
proc
+=
(ref c: CollectionImpl(?eltType), elt: eltType)¶ Syntactic sugar for
CollectionImpl.add
.