Smalltalk/X Webserver

Documentation of class 'SequenceableCollection':

Class: SequenceableCollection

Inheritance
Description
Related information
Class protocol
Instance protocol

Inheritance:

   Object
   |
   +--Collection
      |
      +--SequenceableCollection
         |
         +--ArrayedCollection
         |
         +--CollectingSharedQueueStream
         |
         +--Colormap
         |
         +--Cons
         |
         +--Heap
         |
         +--LinkedList
         |
         +--NumberSet
         |
         +--OrderedCollection
         |
         +--ReadOnlySequenceableCollection
         |
         +--ReindexedCollection
         |
         +--RunArray
         |
         +--SequenceWithSentinel

Package:: stx:libbasic

Category:: Collections-Abstract

Version:: rev: 1.295 date: 2010/04/23 13:39:19; user: mb; file: SequenceableCollection.st directory: libbasic; module: stx stc-classLibrary: libbasic

Author:: Claus Gittinger

Description:

SequenceableCollections have ordered elements which can be accessed via a numeric index.
SequenceableCollection is an abstract class - there are no direct instances of it in the system.

The methods found here assume that implementations of (at least)
#at:/#at:put: are implemented (which are always found in Object for indexable objects).

For performance, some subclasses redefine more methods, 
knowing the detail of how elements are stored.

Especially, bulk data manipulation (i.e. #replaceFrom:to:with:startingAt:)
and search methods (i.e. #indexOf:startingAt:) are good candidates for this kind of tuneup.

The most heavily used SequentialCollections in the system are probably Array, String, ByteArray
OrderedCollection and SortedCollection.

Related information:

    Array
    ByteArray
    OrderedCollection
    SortedCollection
    CharacterArray
    String

Class protocol:

Compatibility-Squeak

writeStream: create a write-stream on an instance of the receiver-class

Signal constants

missingClassInLiteralArrayErrorSignal

initialization

initialize

instance creation

decodeFromLiteralArray: anArray: create & return a new instance from information encoded in anArray.
Redefined for faster creation.
new: size withAll: element: return a new collection of size, where all elements are
initialized to element.
newWithConcatenationOfAll: aCollectionOfCollections: this creates and returns a new collection consisting
of the concatenation of all elements of the argument.
I.e. it has the same effect as concatenating all elements
of the argument using #, ,but is implemented more efficiently,
by avoiding repeated garbage allocations.
This is an O runtime algorithm, in contrast to the #, loop, which is O*O
withSize: size: return a new collection of size.
For variable size collections, this is different from #new:,
in that #new: creates an empty collection with preallocated size,
while #withSize: creates a non empty one.

instance creation-multiDimensional

_at: nIndices: this is a synthetic selector, generated by the compiler,
if a construct of the form expr[idx...] is parsed.
I.e.
Array[n]
generates
Array _at: n
_at: dim1 at: dim2: this is a synthetic selector, generated by the compiler,
if a construct of the form expr[idx...] is parsed.
I.e.
Array[n,m]
generates
Array _at:n at:m
_at: dim1 at: dim2 at: dim3: this is a synthetic selector, generated by the compiler,
if a construct of the form expr[idx...] is parsed.
I.e.
Array[n,m,o]
generates
Array _at:n at:m at:o

instance creation-streaming

streamContents: blockWithArg: create a write-stream on an instance of the receiver-class,
evaluate blockWithArg, passing that stream,
extract and return the streams contents.
streamContents: blockWithArg limitedTo: limit: create a limited write-stream on an instance of the receiver-class,
evaluate blockWithArg, passing that stream,
extract and return the streams contents (possibly truncated).
streamContentsEnumerating: aReceiver using: enumeratorSelector: create a write-stream on an instance of the receiver-class,
enumerate on aReceiver using enumeratorSelector as a do-block-selector,
and return the collected values. Especially useful, if you have a do-like
enumerator somewhere, and you want this as a collection.
streamContentsOf: aReceiver enumerator: enumeratorSelector: create a write-stream on an instance of the receiver-class,
enumerate on aReceiver using enumeratorSelector as a do-block-selector,
and return the collected values. Especially useful, if you have a do-like
enumerator somewhere, and you want this as a collection.

queries

isAbstract: Return if this class is an abstract class.
True is returned for SequenceableCollection here; false for subclasses.
Abstract subclasses must redefine again.

Instance protocol:

Compatibility-Squeak

allButFirst: Return a copy of the receiver containing all but the first element.
Raise an error if there are not enough elements.
allButFirst: n: Return a copy of the receiver containing all but the first n elements.
Raise an error if there are not enough elements.
allButLast: Return a copy of the receiver containing all but the last element.
Raise an error if there are not enough elements.
allButLast: n: Return a copy of the receiver containing all but the last n elements.
Raise an error if there are not enough elements.
atPin: index: Return the index'th element of me if possible.
Return the first or last element if index is out of bounds.
atRandom: Return any random element from the receiver
atRandom: aRandomGenerator: Return any random element from the receiver
atWrap: index: Return the index'th element of me if possible.
Wrap the index modulu the receivers size if it is out of bounds.
beginsWith: aCollection: Squeak & VW compatibility: same as #startsWith: - sigh
collect: aBlock from: startIndex to: stopIndex: squeak uses a different naming here - sigh.
Notice, that the squeak name is actually wrong and misleading, as it suggests
collecting first and then taking the subcollection; this is wrong, as conceptually,
this method first takes a slice (from:to:) and then collects over that.
I.e. it is equivalent to:
(self startIndex to:stopIndex) collect:aBlock
copyAfter: anElement: Answer a copy of the receiver from after the first occurrence
of anElement up to the end. If no such element exists, answer
an empty copy.
copyAfterLast: element: return a copy of the receiver from (but excluding) the last occurrence
of element to the end; uses = for comparison
copyUpToLast: element: return a copy of the receiver up to (but excluding) the last occurrence
of element; uses = for comparison
copyWithoutAll: elementsToSkip: return a new collection consisting of a copy of the receiver, with
ALL elements equal to any in elementsToSkip are left out.
No error is reported, if any in elementsToSkip is not in the collection.
copyWithoutFirst
shuffled: return a randomly shuffled copy of the receiver
shuffledBy: aRandom: return a randomly shuffled copy of the receiver, using the given random generator
sortBy: aBlock: Sort inplace - destructive

Compatibility-VW

replaceElementsFrom: start to: stop withArray: anArray startingAt: repStart

JavaScript support

concat: aCollection: returns a new collection consisting of the concatenation of the receiver and the argument
every: filterFunction: return true, if filterFunction returns true for all elements
filter: filterFunction: select elements for which filterFunction returns true
forEach: function: apply function for each element
indexOf0: anElement: returns the index of anElement, using a 0-based indexing scheme; 0 if not found (sigh)
indexOf1: anElement: returns the index of anElement, using a 1-based indexing scheme; 0 if not found (sigh)
join: separator: joins the strings of the receiver into a single string
js_add: aCollection: For JavaScript only:
Alternative string-concatenation.
Generated for +-operator in javascript.
js_map: function: return a new collection collecting the results of applying function to each
element in sequence
lastIndexOf0: anElement: returns the last index of anElement, using a 0-based indexing scheme; 0 if not found (sigh)
lastIndexOf1: anElement: returns the last index of anElement, using a 1-based indexing scheme; 0 if not found (sigh)
pop: removes and returns the last element of the collection
push: value: adds value at the end of the collection; returns the new size
reduce0: filterFunction: apply function against two values, reducing from left to right.
Function must be declared as: f(previousValue, currentValue, index, arr).
Pass 0-based indices to the filter.
reduce0: filterFunction _: initialValue: apply function against two values, reducing from left to right.
Function must be declared as: f(previousValue, currentValue, index, arr).
Pass 0-based indices to the filter.
reduce1: filterFunction: apply function against two values, reducing from left to right.
Function must be declared as: f(previousValue, currentValue, index, arr).
Pass 1-based indices to the filter.
reduce1: filterFunction _: initialValue: apply function against two values, reducing from left to right.
Function must be declared as: f(previousValue, currentValue, index, arr).
Pass 1-based indices to the filter.
shift: removes and returns the first element of the collection
slice0: index1 _: index2: extracts a subcollection, using a 0-based indexing scheme
slice1: index1 _: index2: extracts a subcollection, using a 1-based indexing scheme
some: filterFunction: return true, if filterfunction returns true for any element
unshift: arg: adds an element to the beginning of the collection

accessing

after: anObject: return the element, after anObject.
If anObject is not in the receiver, report an error;
if anObject is the last in the receiver, return nil.
This depends on #after:ifAbsent: being implemented in a concrete class.
after: anObject ifAbsent: exceptionBlock: return the element, after anObject.
If anObject is the last in the receiver, return nil.
If there is no such element (anObject is not found),
return the value from exceptionBlock.
anElement: return any element from the collection,
report an error if there is none
at: index ifAbsent: exceptionBlock: return the element at index if valid.
If the index is invalid, return the result of evaluating
the exceptionblock.
NOTICE:
in ST-80, this message is only defined for Dictionaries,
however, having a common protocol with indexed collections
often simplifies things.
before: anObject: return the element before the argument, anObject.
If anObject is not in the receiver, report an error;
if anObject is the first in the receiver, return nil.
This depends on #before:ifAbsent: being implemented in a concrete class.
before: anObject ifAbsent: exceptionBlock: return the element, before anObject.
If anObject is the first in the receiver, return nil.
If there is no such element (anObject is not found),
return the value from exceptionBlock.
first: return the first element;
report an error, if the collection is empty.
first: n: return the n first elements of the collection.
Raises an error if there are not enough elements in the receiver.
indexOfNth: n occurrenceOf: what: return the index of the nTh occurence of a value, or 0 if there are not that many
keyAtEqualValue: value: return the index of a value.
This is normally not used (use indexOf:), but makes the
protocol more compatible with dictionaries.
keyAtEqualValue: value ifAbsent: exceptionBlock: return the index of a value.
This is normally not used (use indexOf:), but makes the
protocol more compatible with dictionaries.
keyAtValue: value: return the index of a value.
This is normally not used (use indexOf:), but makes the
protocol more compatible with dictionaries.
keyAtValue: value ifAbsent: exceptionBlock: return the index of a value.
This is normally not used (use indexOf:), but makes the
protocol more compatible with dictionaries.
last: return the last element;
report an error, if the collection is empty.
last: n: return the n last elements of the collection.
Raises an error if there are not enough elements in the receiver.
nth: n: return the nth element;
report an error, if the collections size is smaller than n.
order: the order is the set of keys
second: return the second element;
report an error, if the collections size is smaller than 2.
swap: index1 with: index2: exchange two elements

adding & removing

add: anObject: append the argument, anObject to the collection.
Return the argument, anObject.

Notice, that this is modifies the receiver NOT a copy.
Also note, that it may be a slow operation for some collections,
due to the grow:-message, which is inefficient for fixed size
collections (i.e. for Strings and Arrays it is not recommened).
add: anElement beforeIndex: index: insert the first argument, anObject into the collection before slot index.
Return the receiver (sigh - ST-80 compatibility).

Notice, that this is modifies the receiver NOT a copy.
Also note, that it may be a slow operation for some collections,
due to the grow:-message, which is inefficient for fixed size
collections (i.e. for Strings and Arrays it is not recommened).
addFirst: anObject: prepend the argument, anObject to the collection.
Return the argument, anObject.

Notice, that this is modifies the receiver NOT a copy.
Also note, that it may be a slow operation for some collections,
due to the grow:-message, which is inefficient for fixed size
collections (i.e. for Strings and Arrays it is not recommened).
remove: anElement ifAbsent: aBlock: search for an object which is equal to anElement;
if found remove and return it; if not, return the value from evaluating aBlock.
Use equality compare (=) to search for an occurrence.

Notice, that this is modifies the receiver NOT a copy.
Also note, that it may be a slow operation for some collections,
due to the grow:-message, which is inefficient for fixed size
collections (i.e. for Strings and Arrays it is not recommened).
removeAllSuchThat: aBlock: remove all elements that meet a test criteria as specified in aBlock.
The argument, aBlock is evaluated for successive elements and all those,
for which it returns true, are removed.
Return a collection containing the removed elements.
removeAtIndex: anIndex: remove the element stored at anIndex. Return the removed object.

Notice, that this is modifies the receiver NOT a copy.
Also note, that it may be a slow operation for some collections,
due to the grow:-message, which is inefficient for fixed size
collections (i.e. for Strings and Arrays it is not recommened).
removeFirst: remove the first element of the receiver and return it.

Notice, that this is modifies the receiver NOT a copy.
Also note, that it may be a slow operation for some collections,
due to the grow:-message, which is inefficient for fixed size
collections (i.e. for Strings and Arrays it is not recommened).
removeFromIndex: startIndex: remove the elements stored at indexes from startIndex to the end.
Return the receiver.
Returning the receiver is a historic leftover - it may at one
time return a collection of the removed elements.

Notice, that this is modifies the receiver - NOT a copy;
therefore any other users of the receiver will also see this change.
Also note, that it may be a slow operation for some collections,
due to the grow:-message, which is inefficient for fixed size
collections (i.e. for Strings and Arrays it is not recommened).
removeFromIndex: startIndex toIndex: endIndex: remove the elements stored at indexes between startIndex and endIndex.
Return the receiver.
Returning the receiver is a historic leftover - it may at one
time return a collection of the removed elements.

Notice, that this is modifies the receiver - NOT a copy;
therefore any other users of the receiver will also see this change.
Also note, that it may be a slow operation for some collections,
due to the grow:-message, which is inefficient for fixed size
collections (i.e. for Strings and Arrays it is not recommened).
removeIdentical: anElement ifAbsent: aBlock: search for an object which is identical to anElement;
if found remove and return it; if not, return the value from evaluating aBlock.
Uses identity compare (==) to search for an occurrence.

Notice, that this is modifies the receiver NOT a copy.
Also note, that it may be a slow operation for some collections,
due to the grow:-message, which is inefficient for fixed size
collections (i.e. for Strings and Arrays it is not recommened).
removeIndex: index: remove the argument stored at index. Return the receiver.

Notice, that this is modifies the receiver NOT a copy.
Also note, that it may be a slow operation for some collections,
due to the grow:-message, which is inefficient for fixed size
collections (i.e. for Strings and Arrays it is not recommened).
removeLast: remove the last element of the receiver and return it.

Notice, that this is modifies the receiver NOT a copy.
Also note, that it may be a slow operation for some collections,
due to the grow:-message, which is inefficient for fixed size
collections (i.e. for Strings and Arrays it is not recommened).

combinatoric

combinationsDo: aBlock: Repeatly evaluate aBlock with all combinations of elements from the receivers elements.
The receivers elements must be collections of the individuals to be taken for the combinations
combinationsStartingAt: anInteger prefix: prefix do: aBlock: a helper for combinationsDo:
lexicographicPermutationsDo: aBlock: Repeatly evaluate aBlock with a single copy of the receiver.
Reorder the copy so that aBlock is presented all (self size factorial) possible
permutations in lexicographical order (i.e. sorted by size).

Notice, that the swapping occurs within a buffered copy, so the block will receive
the identical same collection (but with different contents) every time.
This non-functional kludge was done for performance, as we had to generate huge amounts
of permuted copies. The user of this function must be careful in the block,
to copy the argument, if it has to be stored somewhere.
lexicographicPermutationsStartingAt: anInteger do: aBlock: a helper for lexicographicPermutationsDo:
permutationsDo: aBlock: Repeatly evaluate aBlock with a single copy of the receiver.
Reorder the copy so that aBlock is presented all (self size factorial) possible permutations.

Notice, that the swapping occurs within a buffered copy, so the block will receive
the identical same collection (but with different contents) every time.
This non-functional kludge was done for performance, as we had to generate huge amounts
of permuted copies. The user of this function must be careful in the block,
to copy the argument, if it has to be stored somewhere.
permutationsStartingAt: anInteger do: aBlock: a helper for permutationsDo:
permutationsStartingAt: anInteger with: anotherCollection do: aBlock: a helper for permutationsDo:
permutationsWith: anotherCollection do: aBlock: Repeatly evaluate aBlock with a single copy of the receiver.
Reorder the copy so that aBlock is presented all (self size factorial) possible permutations.

Notice, that the swapping occurs within a buffered copy, so the block will receive
the identical same collection (but with different contents) every time.
This non-functional kludge was done for performance, as we had to generate huge amounts
of permuted copies. The user of this function must be careful in the block,
to copy the argument, if it has to be stored somewhere.

comparing

< aCollection: compare two sequenceable collections
<= aCollection: Compare the receiver with the argument and return true if the
receiver is less than or equal to the argument. Otherwise return false
= aCollection: return true if the receiver and aCollection represent collections
with equal contents, and if they are of the same species.
> aCollection: Compare the receiver with the argument and return true if the
receiver is greater than the argument.
Otherwise return false.
>= aCollection: Compare the receiver with the argument and return true if the
receiver is greater than or equal to the argument.
Otherwise return false.
commonPrefixWith: aCollection: return the common prefix of myself and the argument, aCollection.
If there is none, an empty collection is returned.
commonPrefixWith: aCollection ignoreCase: ignoreCase: return the common prefix of myself and the argument, aCollection.
If there is none, an empty collection is returned.
commonSuffixWith: aCollection: return the common suffix (tail) of myself and the argument, aCollection.
If there is none, an empty collection is returned.
commonSuffixWith: aCollection ignoreCase: ignoreCase: return the common suffix (tail) of myself and the argument, aCollection.
If there is none, an empty collection is returned.
deepSameContentsAs: aCollection: return true, if the receiver and the arg have the same contents
in both the named instance vars and any indexed instVars.
This method descends into referenced objects, where #sameContentsAs: does not descend.

Redefinded, so that SequenceableCollections are equivalent, especially OrderedCollections with
unused space
endsWith: aCollection: return true, if the receivers last elements match those
of aCollection
endsWithAnyOf: aCollectionOfCollections: return true, if the receiver endswith any in aCollection
hasEqualElements: otherCollection: Answer whether the receiver's size is the same as otherCollection's
size, and each of the receiver's elements equal the corresponding
element of otherCollection.
This should probably replace the current definition of #= .
hash: return a hash key for the receiver
identicalContentsAs: aCollection: return true if the receiver and aCollection represent collections
with identical contents. This is much like #=, but compares
elements using #== instead of #=.
isSameSequenceAs: otherCollection: Answer whether the receiver's size is the same as otherCollection's size,
and each of the receiver's elements equal the corresponding element of otherCollection.
This should probably replace the current definition of #= .
sameContentsAs: aCollection whenComparedWith: compareBlock: return true if the receiver and aCollection represent collections
with the same contents, using compareSelector to compare elements.
This is a generic version of #= or #identicalContentsAs:;
i.e. #= is the same as #sameContentsAs:whenComparedUsing:#=
and #identicalContentsAs: is the same as #sameContentsAs:whenComparedUsing:#==.
startsWith: aCollection: return true, if the receivers first elements match those
of aCollection
If the argument is empty, true is returned.
startsWithAnyOf: aCollectionOfCollections: return true, if the receiver starts with any in aCollection

converting

asCollectionOfSubCollectionsOfSize: pieceSize: return a collection containing pieces of size pieceSite from the receiver.
The last piece may be smaller, if the receivers size is not a multiple of pieceSize.
asCollectionOfSubCollectionsSeparatedBy: anElement: return a collection containing the subcollections (separated by anElement)
of the receiver. If anElement occurs multiple times in a row,
the result will contain empty collections.
This algorithm uses equality-compare to detect the element.
asCollectionOfSubCollectionsSeparatedBy: anElement do: aBlock: evaluate aBlock for each subcollection generated by separating elements
of the receiver by anElement.
If anElement occurs multiple times in a row,
the block will be invoked with empty collections as argument.
This algorithm uses equality-compare to detect the element.
asCollectionOfSubCollectionsSeparatedByAll: aSeparatorCollection: return a collection containing the subcollections (separated by aSeparatorCollection)
of the receiver. If aSeparatorCollection occurs multiple times in a row,
the result will contain empty strings.
Uses equality-compare when searching for aSeparatorCollection.
asCollectionOfSubCollectionsSeparatedByAny: aCollectionOfSeparators: return a collection containing the subCollection
(separated by any from aCollectionOfSeparators) of the receiver.
This allows breaking up strings using a number of elements as separator.
Uses equality-compare when searching for separators.
asCollectionOfSubCollectionsSeparatedByAnyForWhich: aBlock: return a collection containing the subCollection
(separated by elements for which aBlock evaluates to true) of the receiver.
This allows breaking up strings using an arbitrary condition.
asSequenceableCollection: return myself as a SequenceableCollection.
I am already a SequenceableCollection.
asStringCollection: return a new string collection containing the elements;
these ought to be strings. (i.e. String or Text instances)
asStringWith: sepChar: return a string generated by concatenating my elements
(which must be strings or nil) and embedding sepChar characters in between.
Nil entries and empty strings are counted as empty lines.
asStringWith: sepCharacter from: firstLine to: lastLine: return part of myself as a string with embedded sepCharacters.
My elements must be strings or nil; nil entries and empty strings are
taken as empty lines.
asStringWith: sepCharacter from: firstLine to: lastLine compressTabs: compressTabs final: endCharacter: return part of myself as a string or text with embedded sepCharacters.
My elements must be strings or nil; nil entries and empty strings are
taken as empty lines.
If the argument compressTabs is true, leading spaces are converted
to tab-characters (8col tabs). The last line is followed by a final
character (if non-nil).
asStringWith: sepCharacter from: firstLine to: lastLine compressTabs: compressTabs final: endCharacter withEmphasis: withEmphasis: return part of myself as a string or text with embedded sepCharacters
and followup endCharacter.
My elements must be strings or nil; nil entries and empty strings are
taken as empty lines.
sepCharacter and endCharacter may be nil, a character or a string.
If the argument compressTabs is true, leading spaces are converted
to tab-characters (8col tabs). The last line is followed by a final
character (if non-nil).
The withEmphais argument controls if the returned string should preserve
any emphasis. If false, a plain string is returned.
This method is tuned for big collections, in not creating many
intermediate strings (has linear runtime). For very small collections
and small strings, it may be faster to use the comma , operation.
asStringWithCRs: return a string generated by concatenating my elements
(which must be strings or nil) and embedding cr characters in between.
Nil entries and empty strings are counted as empty lines.
asStringWithCRsFrom: firstLine to: lastLine: return a string generated by concatenating some of my elements
(which must be strings or nil) and embedding cr characters in between.
Nil entries and empty strings are counted as empty lines.
asStringWithCRsFrom: firstLine to: lastLine compressTabs: compressTabs: return part of myself as a string with embedded cr's.
My elements must be strings or nil.
If the argument compressTabs is true, leading spaces are converted
to tab-characters (8col tabs).
Nil entries and empty strings are taken as empty lines.
asStringWithCRsFrom: firstLine to: lastLine compressTabs: compressTabs withCR: withCR: return part of myself as a string with embedded cr's.
My elements must be strings or nil; nil entries and empty strings are
taken as empty lines.
If the argument compressTabs is true, leading spaces are converted
to tab-characters (8col tabs). WithCR controls whether the last line
should be followed by a cr or not.
decodeAsLiteralArray: given a literalEncoding in the receiver,
create & return the corresponding object.
The inverse operation to #literalArrayEncoding.
decodeAsLiteralArrayCollection: given an array of literalEncodings in the receiver,
create & return the corresponding collection object.
from: firstLine to: lastLine asStringWith: sepCharacter: return part of myself as a string with embedded sepCharacters.
My elements must be strings or nil; nil entries and empty strings are
taken as empty lines.
from: firstLine to: lastLine asStringWith: sepCharacter compressTabs: compressTabs final: endCharacter: return part of myself as a string or text with embedded sepCharacters.
My elements must be strings or nil; nil entries and empty strings are
taken as empty lines.
If the argument compressTabs is true, leading spaces are converted
to tab-characters (8col tabs). The last line is followed by a final
character (if non-nil).
from: firstLine to: lastLine asStringWith: sepCharacter compressTabs: compressTabs final: endCharacter withEmphasis: withEmphasis: return part of myself as a string or text with embedded sepCharacters
and followup endCharacter.
My elements must be strings or nil; nil entries and empty strings are
taken as empty lines.
sepCharacter and endCharacter may be nil, a character or a string.
If the argument compressTabs is true, leading spaces are converted
to tab-characters (8col tabs). The last line is followed by a final
character (if non-nil).
The withEmphais argument controls if the returned string should preserve
any emphasis. If false, a plain string is returned.
This method is tuned for big collections, in not creating many
intermediate strings (has linear runtime). For very small collections
and small strings, it may be faster to use the comma , operation.
subCollections: aBlock: Answser an ordered collection of ordered collections
where each subcollection is delimited by an element of the receiver
for which the given block evaluates to true.

converting-reindexed

from: startIndex: Create a ReindexedCollection from the receiver.
The new collection represents the elements starting at startIndex to the end.
(i.e. logically it represents the receiver copyFrom:startIndex,
however, physically, no copy is made).
Warning:
The slice SHARES the memory for the element-data with the original,
this means that any modifications in the original are visible in the slice
and vice versa.
from: startIndex by: step: Create a ReindexedCollection from the receiver.
The new collection represents the elements starting at startIndex to the end.
(i.e. logically it represents the receiver copyFrom:startIndex,
however, physically, no copy is made).
Warning:
The slice SHARES the memory for the element-data with the original,
this means that any modifications in the original are visible in the slice
and vice versa.
from: startIndex count: numberOfElements: return a sub-collection consisting of numberOfElements elements
in the receiver starting at index start (i.e. reference to a slice).
Warning:
The slice SHARES the memory for the element-data with the original,
this means that any modifications in the original are visible in the slice
and vice versa.
from: startIndex to: endIndex: Create a ReindexedCollection from the receiver.
The new collection represents the elements starting at startIndex to endIndex.
(i.e. logically it represents the receiver copyFrom:startIndex,
however, physically, no copy is made).
Warning:
The slice SHARES the memory for the element-data with the original,
this means that any modifications in the original are visible in the slice
and vice versa.
from: startIndex to: endIndex by: step: Create a ReindexedCollection from the receiver.
The new collection represents the receivers elements up to endIndex.
(i.e. logically it represents the receiver copyTo:endIndex,
however, physically, no copy is made).
Warning:
The slice SHARES the memory for the element-data with the original,
this means that any modifications in the original are visible in the slice
and vice versa.
to: endIndex: Create a ReindexedCollection from the receiver.
The new collection represents the receivers elements up to endIndex.
(i.e. logically it represents the receiver copyTo:endIndex,
however, physically, no copy is made).
Warning:
The slice SHARES the memory for the element-data with the original,
this means that any modifications in the original are visible in the slice
and vice versa.
to: endIndex by: step: Create a ReindexedCollection from the receiver.
The new collection represents the receivers elements up to endIndex.
(i.e. logically it represents the receiver copyTo:endIndex,
however, physically, no copy is made).
Warning:
The slice SHARES the memory for the element-data with the original,
this means that any modifications in the original are visible in the slice
and vice versa.

copying

++ aCollection: return a new collection formed from concatenating the receiver with
the argument. The class of the new collection is determined by the
receivers class, so mixing classes is possible, if the second collections
elements can be stored into instances of the receivers class.
, aCollection: return a new collection formed from concatenating the receiver with
the argument. The class of the new collection is determined by the
receivers class, so mixing classes is possible, if the second collections
elements can be stored into instances of the receivers class.
copyButFirst: count: return a new collection consisting of the receivers elements
except for the first count elements - for convenience.
copyButLast: count: return a new collection consisting of the receivers elements
except for the last count elements - for convenience.
copyFirst: count: return a new collection consisting of the receivers first count
elements - this is just a rename of copyTo: - for compatibility.
copyFrom: startIndex: return a new collection consisting of receivers elements from startIndex to the end of the collection.
Return an empty collection, if startIndex is beyond the receivers size.
copyFrom: startIndex count: numberOfElements: return a new collection consisting of numberOfElements elements
extracted from the receiver starting at index start
(i.e. extract a slice).
Returns an empty collection if startIndex is beyond the receivers size.
Raise an error, if stopIndex is out of range.
copyFrom: startIndex to: stopIndex: return a new collection consisting of receivers elements
between start and stop.
Returns an empty collection if startIndex is beyond the receivers size.
Raise an error, if stopIndex is out of range.
copyLast: count: return a new collection consisting of the receivers last count
elements.
copyMapping: map: return a copy, where elements all replaced via the given mapping.
If the element is present as key in map, it is replaced by a corresponding value from the map.
Otherwise, it is left unchanged.
copyMappingFrom: inMap to: outMap: return a copy, where elements all replaced via the given mapping.
If the element is present in inmap, it is replaced by a corresponding value from outmap.
Otherwise, it is left unchanged.
copyReplaceAll: oldElement with: newElement: return a copy of the receiver, where all elements equal to oldElement
have been replaced by newElement.
copyReplaceAll: oldObject withAll: aCollection: return a copy, where all oldObjects are replaced by all
elements from aCollection (i.e. sliced in).
Non-destructive; returns a new collection.
The implementation here is a general-purpose one;
and should be redefined in String, if heavily used.
copyReplaceFrom: startIndex to: endIndex with: aCollection: return a copy of the receiver, where the elements from startIndex to
endIndex have been replaced by the elements of aCollection
copyReplaceFrom: startIndex with: aCollection: return a copy of the receiver, where the elements from startIndex to
the end have been replaced by the elements of aCollection
copyReplacing: oldElement withObject: newElement: return a copy of the receiver, where all elements equal to oldElement
have been replaced by newElement.
ANSI version of what used to be #copyReplaceAll:with:
copyThrough: element: return a new collection consisting of the receiver elements
up-to (AND including) the first occurrence of element.
copyTo: stopIndex: Return a new collection consisting of receivers elements from 1 up to (including) stopIndex.
Raise an error, if stopIndex is out of range.
copyToMax: stop: return a new collection consisting of receivers elements
from 1 up to (including) index stop, or up to the receivers end,
whichever is smaller (i.e. like copyTo:, but do not err if receiver is smaller
copyTransliterating: oldElements to: newElements: return a copy, where elements all transliterated via the given mapping.
The transiteraion works like perl's tr operator.

Transliterates all occurrences of the characters found in the search list with the
corresponding character in the replacement list.
A character range may be specified with a hyphen, so /A-J/0-9/ does the same replacement as
/ACEGIBDFHJ/0246813579/. The hyphen may be escaped with a backslash as in /0\-1).

Note that tr does not do other character escapes such as \n.
If you want to map strings between lower/upper cases, see asUpperCase and asLowerCase.

Note also that the whole range idea is rather unportable between character sets,
and even within character sets they may cause results you probably didn't expect.
A sound principle is to use only ranges that begin from and end at either alphabets of equal
case (a-e, A-E), or digits (0-4).
Anything else is unsafe. If in doubt, spell out the character sets in full.
copyTransliterating: oldElements to: newElements complement: complement squashDuplicates: squashDuplicates: return a copy, where elements all transliterated via the given mapping.
The transiteraion works like perl's tr operator.

Transliterates all occurrences of the characters found in the search list with the
corresponding character in the replacement list. It returns the number of characters replaced
or deleted.
A character range may be specified with a hyphen, so /A-J/0-9/ does the same replacement as
/ACEGIBDFHJ/0246813579/. The hyphen may be escaped with a backslash as in /0\-1).

Note that tr does not do other character escapes such as \n.
If you want to map strings between lower/upper cases, see asUpperCase and asLowerCase.

Note also that the whole range idea is rather unportable between character sets,
and even within character sets they may cause results you probably didn't expect.
A sound principle is to use only ranges that begin from and end at either alphabets of equal
case (a-e, A-E), or digits (0-4).
Anything else is unsafe. If in doubt, spell out the character sets in full.

If complement is true, non-matching chars are affected.
If squashDuplicates is true, translated duplicates are squashed (but not non-matches)
copyUpTo: element: return a new collection consisting of the receiver elements
up-to (but excluding) the first occurrence of element;
or to the end, if element is not included
copyWith: newElement: return a new collection containing the receivers elements
and the single new element, newElement.
This is different from concatentation, which expects another collection
as argument, but equivalent to copy-and-addLast.
copyWithFirst: newFirstElement: return a new collection containing the receivers elements
and the single new element, newElement up front.
This is different from concatentation, which expects two collections
as argument, but equivalent to copy-and-addFirst.
copyWithout: elementToSkip: return a new collection consisting of a copy of the receiver, with
ALL elements equal to elementToSkip are left out.
No error is reported, if elementToSkip is not in the collection.
copyWithoutFirst: elementToSkip: return a new collection consisting of a copy of the receivers elements
without the first elementToSkip, if it was present.
No error is reported, if elementToSkip is not in the collection.
Do not confuse this with copyButFirst:
copyWithoutIdentical: elementToSkip: return a new collection consisting of a copy of the receiver, with
ALL elements identical to elementToSkip are left out.
No error is reported, if elementToSkip is not in the collection.
copyWithoutIndex: omitIndex: return a new collection consisting of receivers elements
without the argument stored at omitIndex
copyWithoutLast: count: return a new collection consisting of the receivers elements
except the last count elements.
That is the same as copyButLast: and badly named (for compatibility),
because the name may confuse users with the copyWithoutFirst: functionality.
Please use copyButLast:.

** This is an obsolete interface - do not use it (it may vanish in future versions) **
repeatedConcatenation: nTimes: return a new collection consisting of nTimes the concatenation of the receiver
restAfter: anElement: return a new collection consisting of the receivers elements after
(but excluding) anElement.
If anElement is not in the receiver, the returned collection
will be empty.
See also #upTo:.
trimForWhich: aCheckBlock: return a copy of myself without leading and trailing elements for which aCheckBlock returns true.
Normally, this is mostly used with string receivers.
upTo: anElement: return a new collection consisting of the receivers elements upTo
(but excluding) anElement.
If anElement is not in the receiver, the returned collection
will consist of all elements of the receiver.
See also #restAfter: , #copyFrom:index.
upTo: anElement count: count: return a new collection consisting of the receivers elements upTo
(but excluding) count found anElements, i.e. the first found count-1
elements are included in the returned collection; if count < 0 the
procedure is done from the end of the collection backwards.
If anElement is not in the receiver, the returned collection
will consist of all elements of the receiver
upToAny: aCollectionOfObjects: return a new collection consisting of the receivers elements upTo
(but excluding) any in aCollectionOfObjects.
If none of aCollectionOfObjects is found in the receiver, the returned collection
will consist of all elements of the receiver.
See also #upTo:
withoutLeadingForWhich: aCheckBlock: return a copy of myself without leading eleents for which aCheckBlock returns true.
Returns an empty collection, if the receiver consist only of matching elements.
Normally, this is mostly used with string receivers.
withoutTrailingForWhich: aCheckBlock: return a copy of myself without trailing characters for which aCheckBlock returns true.
Returns an empty collection, if the receiver consist only of matching chars.

enumerating

collect: aBlock: evaluate the argument, aBlock for every element in the collection
and return a collection of the results
do: aBlock: evaluate the argument, aBlock for every element in the collection.
do: aBlock separatedBy: sepBlock: evaluate the argument, aBlock for every element in the collection.
Between each element (i.e. not before the first element and not after the
last element), evaluate sepBlock.
This supports printing of collections with elements separated by some
string.
doWithIndex: aBlock: Squeak compatibility; like keysAndValuesDo:, but passes
the index as second argument.
from: start collect: aBlock: evaluate the argument, aBlock for the elements starting at start
to the end and return a collection of the results
from: startIndex do: aBlock: evaluate the argument, aBlock for the elements starting with the
element at startIndex to the end.
from: startIndex keysAndValuesDo: aBlock: evaluate the argument, aBlock for the elements and indices starting with the
element at startIndex to the end.
from: index1 to: index2 by: stepArg do: aBlock: evaluate the argument, aBlock for the elements with index index1 to index2 stepping by step in the collection
from: start to: stop collect: aBlock: evaluate the argument, aBlock for the elements indexed by start
to stop in the collection and return a collection of the results
from: index1 to: index2 do: aBlock: evaluate the argument, aBlock for the elements with index index1 to
index2 in the collection
from: index1 to: index2 keysAndValuesDo: aBlock: evaluate the argument, aBlock for the elements with index index1 to
index2 in the collection; pass both index and value.
from: index1 to: index2 reverseDo: aBlock: evaluate the argument, aBlock for the elements with index index1 to
index2 in the collection. Step in reverse order
from: startIndex to: stopIndex select: aBlock: evaluate the argument, aBlock for the elements at startIndex..stopIndex
and return a collection of those elements for which the block return true.
inGroupsOf: n collect: anNArgBlock: evaluate the argument, anNArgBlock for every group of n elements in the collection,
and collect the results.
The block is called with n arguments for group of n consecutive elements in the receiver.
An error will be reported, if the number of elements in the receiver
is not a multiple of n.
inGroupsOf: n do: anNArgBlock: evaluate the argument, anNArgBlock for every group of n elements in the collection.
The block is called with n arguments for group of n consecutive elements in the receiver.
An error will be reported, if the number of elements in the receiver
is not a multiple of n.
keysAndValuesCollect: aTwoArgBlock: evaluate the argument, aBlock for every element in the collection,
passing both index and element as arguments.
Collect the returned values and return them.
keysAndValuesDo: aTwoArgBlock: evaluate the argument, aBlock for every element in the collection,
passing both index and element as arguments.
keysAndValuesReverseDo: aTwoArgBlock: evaluate the argument, aBlock in reverse order, for every element
in the collection, passing both index and element as arguments.
nonNilElementsDo: aBlock: evaluate the argument, aBlock for every non-nil element in the collection.
pairWiseCollect: aTwoArgBlock: evaluate the argument, aTwoArgBlock for every pair of elements in the collection.
The block is called with 2 arguments for each 2 elements in the receiver.
An error will be reported, if the number of elements in the receiver
is not a multiple of 2.
Collect the results and return a new collection containing those.
pairWiseDo: aTwoArgBlock: evaluate the argument, aTwoArgBlock for every group of 2 elements in the collection.
An error will be reported, if the number of elements in the receiver
is not a multiple of 2.
CONFUSION ATTACK:
this is different from pairWiseDo:.
but the Squeak-pairsDo: does the same as our pairWiseDo:
(sigh: but we were first, so they should have adapted...)
reverseDo: aBlock: evaluate the argument, aBlock for every element in the collection
in reverse order
select: aBlock: evaluate the argument, aBlock for every element in the collection
and return a collection of all elements for which the block return
true
with: aSequenceableCollection do: aTwoArgBlock: evaluate the argument, aBlock for successive elements from
each the receiver and the argument, aSequenceableCollection.
The second argument, aBlock must be a two-argument block.
The collection argument must implement access via a numeric key.
with: aSequenceableCollection doWithIndex: aThreeArgBlock: evaluate the argument, aBlock for successive elements from
each the receiver and the argument, aSequenceableCollection.
aBlock must be a three-argument block, which get elements from either collection and
the index as arguments.
The collection argument must implement access via a numeric key.

filling & replacing

atAllPut: anObject: replace all elements of the collection by the argument, anObject.
Notice: This operation modifies the receiver, NOT a copy;
therefore the change may affect all others referencing the receiver.
from: index1 to: index2 put: anObject: replace the elements from index1 to index2 of the collection
by the argument, anObject.
Notice: This operation modifies the receiver, NOT a copy;
therefore the change may affect all others referencing the receiver.
replaceAll: oldObject by: newObject: backward ST/X compatibility: an alias for #replaceAll:with:.
Pleace do no longer use this one;
instead use #replaceAll:with: for ST-80 compatibility.

** This is an obsolete interface - do not use it (it may vanish in future versions) **
replaceAll: oldObject by: newObject from: startIndex to: stopIndex: backward ST/X compatibility: an alias for #replaceAll:with:from:to:.
Please do no longer use this one;
instead use #replaceAll:with:from:to: for ST-80 compatibility.

** This is an obsolete interface - do not use it (it may vanish in future versions) **
replaceAll: oldObject with: newObject: replace all oldObjects by newObject in the receiver.

Notice: This operation modifies the receiver, NOT a copy;
therefore the change may affect all others referencing the receiver.
replaceAll: oldObject with: newObject from: startIndex to: stopIndex: replace all oldObjects found between startIndex and endIndex,
by newObject in the receiver.

Notice: This operation modifies the receiver, NOT a copy;
therefore the change may affect all others referencing the receiver.
replaceAllForWhich: aConditionBlock with: newObject: replace all elements for which aConditionBlock returns true
between startIndex and endIndex, by newObject in the receiver.

Notice: This operation modifies the receiver, NOT a copy;
therefore the change may affect all others referencing the receiver.
replaceAllForWhich: aConditionBlock with: newObject from: startIndex to: stopIndex: replace all elements for which aConditionBlock returns true
between startIndex and endIndex, by newObject in the receiver.

Notice: This operation modifies the receiver, NOT a copy;
therefore the change may affect all others referencing the receiver.
replaceAllIdentical: oldObject with: newObject: replace all oldObjects by newObject in the receiver.
This is like #replaceAll:with:from:to:, but uses an identity compare.

Notice: This operation modifies the receiver, NOT a copy;
therefore the change may affect all others referencing the receiver.
replaceAllIdentical: oldObject with: newObject from: startIndex to: stopIndex: replace all oldObjects found between startIndex and endIndex,
by newObject in the receiver.
This is like #replaceAll:with:from:to:, but uses an identity compare.

Notice: This operation modifies the receiver, NOT a copy;
therefore the change may affect all others referencing the receiver.
replaceAny: aCollection by: newObject: backward ST/X compatibility; alias for #replaceAny:with:.
Pleace do no longer use this one;
instead use #replaceAny:with: for naming consistence.

** This is an obsolete interface - do not use it (it may vanish in future versions) **
replaceAny: aCollection by: newObject from: startIndex to: stopIndex: backward ST/X compatibility; alias for #replaceAny:with:from:to:.
Pleace do no longer use this one;
instead use #replaceAny:with:from:to: for naming consistence.

** This is an obsolete interface - do not use it (it may vanish in future versions) **
replaceAny: aCollection with: newObject: replace all elements, which are in aCollection, by newObject.

Notice: This operation modifies the receiver, NOT a copy;
therefore the change may affect all others referencing the receiver.
replaceAny: aCollection with: newObject from: startIndex to: stopIndex: replace all elements within a range,
which are in contained in aCollection by newObject.

Notice: This operation modifies the receiver, NOT a copy;
therefore the change may affect all others referencing the receiver.
replaceFrom: startIndex count: numberOfElements with: replacementCollection: replace numberOfElements elements in the receiver from startIndex,
with elements taken from replacementCollection starting at 1.

Notice: This operation modifies the receiver, NOT a copy;
therefore the change may affect all others referencing the receiver.
replaceFrom: startIndex count: numberOfElementsToReplace with: replacementCollection startingAt: repStartIndex: replace numberOfElementsToReplace elements in the receiver from startIndex,
with elements taken from replacementCollection starting at repStartIndex.

Notice: This operation modifies the receiver, NOT a copy;
therefore the change may affect all others referencing the receiver.
replaceFrom: startIndex to: stopIndex with: replacementCollection: replace elements in the receiver between index startIndex and stopIndex,
with elements taken from replacementCollection starting at 1.

Notice: This operation modifies the receiver, NOT a copy;
therefore the change may affect all others referencing the receiver.
replaceFrom: startIndex to: stopIndex with: replacementCollection startingAt: repStartIndex: replace elements in the receiver between index startIndex and stopIndex,
with elements taken from replacementCollection starting at repStartIndex.
Return the receiver.

Notice: This operation modifies the receiver, NOT a copy;
therefore the change may affect all others referencing the receiver.
replaceFrom: startIndex with: replacementCollection: replace elements in the receiver starting at startIndex,
with elements taken from replacementCollection starting at 1
to the end of replacementCollection.

Notice: This operation modifies the receiver, NOT a copy;
therefore the change may affect all others referencing the receiver.
replaceFrom: startIndex with: replacementCollection startingAt: repStartIndex: replace elements in the receiver starting at startIndex,
with elements taken from replacementCollection starting at repStartIndex
to the end of replacementCollection.

Notice: This operation modifies the receiver, NOT a copy;
therefore the change may affect all others referencing the receiver.
startingAt: sourceStart replaceElementsIn: destColl from: destStartIndex to: destEndIndex: replace elements in destColl with elements from the receiver.

Notice: This operation modifies the destination collection, NOT a copy;
therefore the change may affect all others referencing this object.

padded copying

leftPaddedTo: size with: padElement: return a new collection of length size, which contains the receiver
right-adjusted (i.e. padded on the left).
Elements on the left are filled with padElement.
If the receivers size is equal or greater than the length argument,
the original receiver is returned unchanged.
paddedTo: newSize with: padElement: return a new collection consisting of the receivers elements,
plus pad elements up to length.
If the receivers size is equal or greater than the length argument,
the original receiver is returned unchanged.
paddedToMultipleOf: sizeModulu with: padElement

private-sorting helpers

mergeFirst: first middle: middle last: last into: dst by: aBlock: Private!
Merge the sorted ranges [first..middle] and [middle+1..last] of the receiver into the range [first..last] of dst.
mergeSortFrom: first to: last src: src dst: dst by: aBlock: Private! Split the range to be sorted in half, sort each half, and merge the two half-ranges into dst.
quickSortFrom: inBegin to: inEnd: actual quicksort worker for sort-message.
Simulates recursion in a stack, to avoid recursion overflow
with degenerated collections.

Use #< for element comparisons, since this is the (fastest) base
method in Magnitude, and the others may be defined by sending #<.
quickSortFrom: inBegin to: inEnd sortBlock: sortBlock: actual quicksort worker for sort:-message.
Simulates recursion in a stack, to avoid recursion overflow
with degenerated collections.
quickSortFrom: inBegin to: inEnd sortBlock: sortBlock policy: p: actual quicksort worker for sort:-message.
Simulates recursion in a stack, to avoid recursion overflow
with degenerated collections.
quickSortFrom: inBegin to: inEnd sortBlock: sortBlock with: aCollection: actual quicksort worker for sort:-message.
Simulates recursion in a stack, to avoid recursion overflow
with degenerated collections.
quickSortFrom: inBegin to: inEnd with: aCollection: actual quicksort worker for sortWith-message.
Simulates recursion in a stack, to avoid recursion overflow
with degenerated collections.

Use #< for element comparisons, since this is the (fastest) base
method in Magnitude, and the others may be defined by sending #<.
randomizedQuickSortFrom: inBegin to: inEnd sortBlock: sortBlock with: aCollection: actual randomizedQuicksort worker for sort:with:-message.
This exchanges a random element within the partition, to avoid
the worst case O-square situation of quickSort.

Notice, that this method has a much worse best- and average case
runTime, due to the random number generation.
The worst case of quickSort is encountered, if the choosen pivot
element lies at either end of the partition, so that a split
creates partitions of size 1 and (n-1).
Since the middle element is choosen, this worst case is very unlikely
to be encountered.

** This is an obsolete interface - do not use it (it may vanish in future versions) **
randomizedQuickSortFrom: inBegin to: inEnd with: aCollection: actual randomizedQuicksort worker for randomizedSort:-message.
This exchanges a random element within the partition, to avoid
the worst case O-square situation of quickSort.

Notice, that this method has a much worse best- and average case
runTime, due to the random number generation.
The worst case of quickSort is encountered, if the choosen pivot
element lies at either end of the partition, so that a split
creates partitions of size 1 and (n-1).
Since the middle element is choosen, this worst case is very unlikely
to be encountered.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

queries

firstIndex: return the first elements index
isSequenceable: return true, if the receiver is some kind of sequenceableCollection
isSequenceableCollection: OBSOLETE: use isSequenceable for ST-80 compatibility.
This method is a historic leftover and will be removed.

** This is an obsolete interface - do not use it (it may vanish in future versions) **
isSorted: return true. if my elements are sorted (already)
isSortedBy: aBlock: return true, if my elements are sorted (already) by the given criterion (sortBlock)
keys: return a collection with all keys in the Smalltalk dictionary
lastIndex: return the last elements index
size: return the number of elements in the collection.
concrete implementations must define this

** This method raises an error - it must be redefined in concrete classes **
zeroIndex: return the index value which is returned when nothing
is found in an indexOf* kind of search.
ST-compatibility

searching

detect: aBlock startingAt: startIndex: find the first element, for which evaluation of the argument, aBlock
return true, starting the search with startIndex.
If none does so, report an error
detect: aBlock startingAt: startIndex ifNone: exceptionBlock: find the first element, for which evaluation of the argument, aBlock
return true, starting the search with startIndex.
If none does so, return the evaluation of exceptionBlock
findFirst: aBlock ifNone: exceptionalValue: find the index of the first element, for which evaluation of the argument, aBlock
returns true; return its index or the value from exceptionalValue if none detected.
This is much like #detect, however, here an INDEX is returned,
while #detect returns the element.
findFirst: aBlock startingAt: startIndex: find the first element, for which evaluation of the argument, aBlock
returns true; return its index or 0 if none detected.
This is much like #detect:startingAt:, however, here an INDEX is returned,
while #detect returns the element.
findLast: aBlock: find the last element, for which evaluation of the argument, aBlock
returns true.
Return its index or 0 if none detected.
findLast: aBlock startingAt: startIndex: find the last element, for which evaluation of the argument, aBlock
returns true. Start the search at startIndex.
Return its index or 0 if none detected.
findLast: aBlock startingAt: startIndex endingAt: endIndex: find the last element, for which evaluation of the argument, aBlock
returns true. Start the search at startIndex.
End the search at endIndex or when an element is found.
Return its index or 0 if none detected.
indexOfAny: aCollection: search the collection for an element in aCollection.
if found, return the index otherwise return 0.
The comparison is done using =
(i.e. equality test - not identity test).

Notice, that for big collections, the runtime of this search
grows proportional to size(receiver) * size(aCollection).
You may think about using other mechanisms (Sets, Dictionaries etc).
indexOfAny: aCollection startingAt: start: search the collection for an element in aCollection,
starting the search at index start;
if found, return the index otherwise return 0.
The comparison is done using =
(i.e. equality test - not identity test).

Notice, that for big collections, the runtime of this search
grows proportional to size(receiver) * size(aCollection).
You may think about using other mechanisms (Sets, Dictionaries etc).
indexOfAny: aCollection startingAt: start ifAbsent: exceptionBlock: search the collection for an element in aCollection,
starting the search at index start;
if found, return the index. If not, return the value returned by exceptionBlock.
The comparison is done using =
(i.e. equality test - not identity test).

Notice, that for big collections, the runtime of this search
grows proportional to size(receiver) * size(aCollection).
You may think about using other mechanisms (Sets, Dictionaries etc).
indexOfAnyOf: aCollection: squeak compatibility: same as #indexOfAny:
indexOfAnyOf: aCollection startingAt: start: squeak compatibility: same as #indexOfAny:startingAt:
indexOfAnyOf: aCollection startingAt: start ifAbsent: exceptionBlock: squeak compatibility: same as #indexOfAny:startingAt:ifAbsent:
indexOfSubCollection: aCollection: find a subcollection. If found, return the index; if not found, return 0.
indexOfSubCollection: aCollection ifAbsent: exceptionBlock: find a subcollection. If found, return the index;
if not found, return the result of evaluating exceptionBlock.
indexOfSubCollection: aCollection startingAt: startIndex: find a subcollection starting at index.
If found, return the index; if not found, return 0.
indexOfSubCollection: aCollection startingAt: startIndex ifAbsent: exceptionBlock: find a subcollection, starting at index. If found, return the index;
if not found, return the result of evaluating exceptionBlock.
This is a q&d hack - not very efficient
lastIndexOfSubCollection: aCollection: find a subcollection from the end.
If found, return the index; if not found, return 0.
lastIndexOfSubCollection: aCollection ifAbsent: exceptionBlock: find a subcollection from the end. If found, return the index;
if not found, return the result of evaluating exceptionBlock.
lastIndexOfSubCollection: aCollection startingAt: startIndex: find a subcollection from the end starting at index.
If found, return the index; if not found, return 0.
lastIndexOfSubCollection: aCollection startingAt: startIndex ifAbsent: exceptionBlock: find a subcollection from the end, starting at index. If found, return the index;
if not found, return the result of evaluating exceptionBlock.
This is a q&d hack - not very efficient

searching-equality

includes: anElement: return true if the collection contains anElement; false otherwise.
Comparison is done using equality compare (i.e. =).
See #includesIdentical: if identity is asked for.
indexOf: anElement: search the collection for anElement;
if found, return the index otherwise return 0.
The comparison is done using =
(i.e. equality test - not identity test).
indexOf: anElement ifAbsent: exceptionBlock: search the collection for anElement;
if found, return the index; otherwise return the value of the exceptionBlock.
The comparison is done using =
(i.e. equality test - not identity test).
indexOf: elementToFind replaceWith: replacement startingAt: start stoppingAt: stop: search for the first occurrence of elementToFind starting at start,
stopping the search at stop. If found, replace the element by replacement
and return the index.
If not found, return 0.
indexOf: anElement startingAt: start: search the collection for anElement, starting the search at index start;
if found, return the index otherwise return 0.
The comparison is done using =
(i.e. equality test - not identity test).
indexOf: anElement startingAt: start endingAt: stop: search the collection for anElement, starting the search at index start;
ending at stop.
If found (within the range), return the index, otherwise return 0.
The comparison is done using =
(i.e. equality test - not identity test).
indexOf: anElement startingAt: start ifAbsent: exceptionBlock: search the collection for anElement starting the search at index start;
if found, return the index otherwise return the value of the
exceptionBlock.
The comparison is done using =
(i.e. equality test - not identity test).
lastIndexOf: anElement: search the collection backwards for anElement;
if found, return the index otherwise return 0.
The comparison is done using =
(i.e. equality test - not identity test).
lastIndexOf: anElement ifAbsent: exceptionBlock: search the collection backwards for anElement;
if found, return the index otherwise return the value of the
exceptionBlock.
The comparison is done using =
(i.e. equality test - not identity test).
lastIndexOf: anElement startingAt: start: search the collection backwards for anElement, starting the search at index start;
if found, return the index otherwise return 0.
The comparison is done using =
(i.e. equality test - not identity test).
lastIndexOf: anElement startingAt: start ifAbsent: exceptionBlock: search the collection backwards for anElement starting the search at
index start; if found, return the index
otherwise return the value of the exceptionBlock.
The comparison is done using =
(i.e. equality test - not identity test).
lastIndexOfAny: aCollection: search the collection backwards for any in aCollection;
if found, return the index, otherwise return 0.
The comparison is done using =
(i.e. equality test - not identity test).
lastIndexOfAny: aCollection startingAt: start: search the collection backwards for any in aCollection, starting the search at index start;
if found, return the index, otherwise return 0.
The comparison is done using =
(i.e. equality test - not identity test).
nextIndexOf: anElement from: start to: stop: search the collection for anElement, starting the search at index start,
stopping at:stop;
if found, return the index otherwise return nil.
The comparison is done using =
(i.e. equality test - not identity test).

NOTICE: nil is returned here if the element is not found,
although this is somewhat strange (the indexOf-search
methods return 0), this is done for VW compatibility.
nextIndexOf: anElement from: start to: stop ifAbsent: exceptionBlock: search the collection for anElement, starting the search at index start
and stopping at stop;
if found, return the index otherwise return the value of the
exceptionBlock.
The comparison is done using =
(i.e. equality test - not identity test).
prevIndexOf: anElement from: startSearchIndex to: endSearchIndex: search the collection for anElement, starting the search at index start;
ending at stop, going in reverse direction.
If found (within the range), return the index, otherwise return nil.
The comparison is done using =
(i.e. equality test - not identity test).

NOTICE: nil is returned here if the element is not found,
although this is somewhat strange (the indexOf-search
methods return 0), this is done for VW compatibility.
prevIndexOf: anElement from: start to: stop ifAbsent: exceptionBlock: search the collection for anElement, starting the search at index start
and stopping at stop, doing a reverse search;
if found, return the index otherwise return the value of the
exceptionBlock.
The comparison is done using =
(i.e. equality test - not identity test).

searching-identity

identityIndexOf: anElement: search the collection for anElement using identity compare (i.e. ==);
if found, return the index otherwise return 0.
identityIndexOf: anElement ifAbsent: exceptionBlock: search the collection for anElement using identity compare (i.e. ==);
if found, return the index otherwise return the value of the
exceptionBlock.
identityIndexOf: anElement or: anotherElement: search the collection for anElement and anotherElement using identity compare (i.e. ==);
if any is found, return the index otherwise return 0.
identityIndexOf: anElement or: anotherElement startingAt: start: search the collection for anElement and anotherElement, starting search at index start
using identity compare (i.e. ==);
if any is found, return the index otherwise return 0.
identityIndexOf: anElement startingAt: start: search the collection for anElement, starting search at index start
using identity compare (i.e. ==);
if found, return the index otherwise return 0.
identityIndexOf: anElement startingAt: start endingAt: stop: search the collection for anElement, starting the search at index start;
ending at stop.
If found (within the range), return the index, otherwise return 0.
The comparison is done using =
(i.e. equality test - not identity test).
identityIndexOf: anElement startingAt: start ifAbsent: exceptionBlock: search the collection for anElement, starting search at index start;
if found, return the index otherwise return the value of the
exceptionBlock.
This one searches for identical objects (i.e. ==).
includesIdentical: anElement: return true if the collection contains anElement; false otherwise.
Comparison is done using identity compare (i.e. ==).
See #includes: if equality is asked for.
lastIdentityIndexOf: anElement: search the collection backwards for anElement;
if found, return the index otherwise return 0.
The comparison is done using ==
(i.e. identity test - not equality test).
lastIdentityIndexOf: anElement ifAbsent: exceptionBlock: search the collection backwards for anElement;
if found, return the index otherwise return the value of the
exceptionBlock.
The comparison is done using ==
(i.e. identity test - not equality test).
lastIdentityIndexOf: anElement startingAt: start: search the collection backwards for anElement, starting the search at index start;
if found, return the index otherwise return 0.
The comparison is done using ==
(i.e. identity test - not equality test).
lastIdentityIndexOf: anElement startingAt: start ifAbsent: exceptionBlock: search the collection backwards for anElement starting the search at
index start; if found, return the index
otherwise return the value of the exceptionBlock.
The comparison is done using ==
(i.e. identity test - not equality test).

sorting & reordering

detectFirstInOrder: sortBlock: find the first element of the collection sorted with sortBlock
mergeSort: sort the collection using a mergeSort algorithm.
The elements are compared using'<'
i.e. they should offer a magnitude-like protocol.

The implementation uses the mergesort algorithm, which may not be
the best possible for all situations
See also #quickSort and #randomizedSort for other sort algorithms
with different worst- and average case behavior)
mergeSort: sortBlock: sort the collection using a mergeSort algorithm.
The elements are compared using'<'
i.e. they should offer a magnitude-like protocol.

The implementation uses the mergesort algorithm, which may not be
the best possible for all situations
See also #quickSort and #randomizedSort for other sort algorithms
with different worst- and average case behavior)
mergeSort: aBlock from: startIndex to: stopIndex: Sort the given range of indices using the mergesort algorithm.
Mergesort is a worst-case O(N log N) sorting algorithm that usually does only half
as many comparisons as heapsort or quicksort.
quickSort: sort the collection inplace. The elements are compared using
'<' i.e. they should offer a magnitude-like protocol.

The implementation uses the quicksort algorithm, which may not be
the best possible for all situations (quickSort has O-square worst
case behavior). See also #randomizedSort for a version with better
worstCase behavior (but worse average & bestCase behavior)
quickSort: sortBlock: sort the collection inplace using the 2-arg block sortBlock
for comparison. This allows any sort criteria to be implemented.

The implementation uses the quicksort algorithm, which may not be
the best possible for all situations (quickSort has O-square worst
case behavior). See also #randomizedSort: for a version with better
worstCase behavior (but worse average & bestCase behavior)
quickSort: sortBlock with: aCollection: sort the collection inplace using the 2-arg block sortBlock
for comparison. Also reorder the elements in aCollection.
Use this, when you have a key collection to sort some other collection with.

The implementation uses the quicksort algorithm, which may not be
the best possible for all situations (quickSort has O-square worst
case behavior). See also #randomizedSort: for a version with better
worstCase behavior (but worse average & bestCase behavior)
quickSortWith: aCollection: sort the receiver collection inplace, using '<' to compare elements.
Also, the elements of aCollection are reordered with it.
Use this, when you have a key collection to sort another collection with.

The implementation uses the quicksort algorithm, which may not be
the best possible for all situations (quickSort has O-square worst
case behavior). See also #randomizedSort: for a version with better
worstCase behavior (but worse average & bestCase behavior)
randomShuffle: random shuffle my elements in place.
This is a destructive algorithm.
Moses, Oakford, Durstenfeld, Knuth algorithm.
See 'The Art of Computer Programming'.
randomizedSort: sort the collection inplace. The elements are compared using
'<' i.e. they should offer a magnitude-like protocol.

This uses the randomized quicksort algorithm,
which has a better worstCase behavior than quickSort
(bit worse bestCase & averageCase behavior).
See: Knuth or Cormen,Leiserson,Rivest pg. 163
randomizedSort: sortBlock: sort the collection inplace using the 2-arg block sortBlock
for comparison. This allows any sort criteria to be implemented.

This uses the randomized quicksort algorithm,
which has a better worstCase behavior than quickSort
(bit worse bestCase & averageCase behavior).
See: Knuth or Cormen,Leiserson,Rivest pg. 163
randomizedSort: sortBlock with: aCollection: sort the collection inplace using the 2-arg block sortBlock
for comparison. Also reorder the elements in aCollection.
Use this, when you have a key collection to sort some other collection with.

This uses the randomized quicksort algorithm,
which has a better worstCase behavior than quickSort
(bit worse bestCase & averageCase behavior).
See: Knuth or Cormen,Leiserson,Rivest pg. 163
randomizedSortWith: aCollection: sort the receiver collection inplace, using '<' to compare elements.
Also, the elements of aCollection are reordered with it.
Use this, when you have a key collection to sort another collection with.

This uses the randomized quicksort algorithm,
which has a better worstCase behavior than quickSort
(bit worse bestCase & averageCase behavior).
See: Knuth or Cormen,Leiserson,Rivest pg. 163
reverse: destructively reverse the order of the elements inplace.
WARNING: this is a destructive operation, which modifies the receiver.
Please use reversed (with a d) for a functional version.
reversed: return a copy with elements in reverse order
sort: sort the collection inplace. The elements are compared using
'<' i.e. they should offer a magnitude-like protocol.

The implementation uses the quicksort algorithm, which may not be
the best possible for all situations (quickSort has O-square worst
case behavior). See also #randomizedSort for a version with better
worstCase behavior (but worse average & bestCase behavior)
sort: sortBlock: sort the collection inplace using the 2-arg block sortBlock
for comparison. This allows any sort criteria to be implemented.

The implementation uses the quicksort algorithm, which may not be
the best possible for all situations (quickSort has O-square worst
case behavior). See also #randomizedSort: for a version with better
worstCase behavior (but worse average & bestCase behavior)
sort: sortBlock with: aCollection: sort the collection inplace using the 2-arg block sortBlock
for comparison. Also reorder the elements in aCollection.
Use this, when you have a key collection to sort some other collection with.

The implementation uses the quicksort algorithm, which may not be
the best possible for all situations (quickSort has O-square worst
case behavior). See also #randomizedSort: for a version with better
worstCase behavior (but worse average & bestCase behavior)
sortByApplying: aBlock: Sort my contents inplace based on the value of what aBlock returns for each element.
Similar to, but even more flexible than sortBySelector.
sortBySelector: aSelector: Sort my contents inplace based on the value of what aSelector returns when sent to my
elements. Sorting by a selector is so common, that its worth a separate utility
sortWith: aCollection: sort the receiver collection inplace, using '<' to compare elements.
Also, the elements of aCollection are reordered with it.
Use this, when you have a key collection to sort another collection with.

The implementation uses the quicksort algorithm, which may not be
the best possible for all situations (quickSort has O-square worst
case behavior). See also #randomizedSort: for a version with better
worstCase behavior (but worse average & bestCase behavior)
sortedBy: aBlock: Create a copy that is sorted. Sort criteria is the block that accepts two arguments.
When the block is true, the first arg goes first ([:a :b | a > b] sorts in descending order).
topologicalSort: sortBlock: sort the collection inplace using a sloooow sort algorithm.
This algorithm has O-square runtime behavior and should be used only
in special situations.
It compares all elements, thus can be used when a>b, b>c does NOT imply
a>c (for example, to sort classes by inheritance)

In all other situations, use #sort; which implements the quicksort algorithm.

If there are cycles, this algorithm may loop endless!
Note: consider using Collection>>#topologicalSort, which is faster and does not do endless loop.

testing

includesKey: anIndex: return true, if anIndex is a valid key.
NOTICE: in ST-80, this message is only defined for Dictionaries,
however, having a common protocol with indexed collections
often simplifies things.

visiting

acceptVisitor: aVisitor with: aParameter

ST/X 6.1.1; WebServer 1.620 at exept:8081; Wed, 23 May 2012 21:01:17 GMT