eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'SequenceableCollection':

Home

Documentation
www.exept.de
Everywhere
for:
[back]

Class: SequenceableCollection


Inheritance:

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

Package:
stx:libbasic
Category:
Collections-Abstract
Version:
rev: 1.478 date: 2018/05/15 11:04:16
user: cg
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:

Signal constants
o  missingClassInLiteralArrayErrorSignal
raised when decoding a literal array spec,
when a non-existing class is encountered
(i.e. a spec-element of the form (ClassNameSymbol args...),
where ClassNameSymbol refers to a non-existing class)

initialization
o  initialize
now a class based exception

instance creation
o  decodeFromLiteralArray: anArray
create & return a new instance from information encoded in anArray.
Redefined for faster creation.
usage example(s):
     Array decodeFromLiteralArray:#(Array 1 2 3)

o  new: size withAll: element
return a new collection of size, where all elements are
initialized to element.

o  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

o  newWithSize: 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 #newWithSize: creates a non empty one.
usage example(s):
     (OrderedCollection new:10) inspect.
     (OrderedCollection newWithSize:10) inspect.
     (Array new:10) inspect.
     (Array newWithSize:10) inspect.

instance creation-multiDimensional
o  _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

o  _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

o  _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
o  new: newSize streamContents: blockWithArg
create a write-stream on an instance of the receiver-class with initial size,
evaluate blockWithArg, passing that stream,
extract and return the streams contents.

o  new: initialSize withCollectedContents: blockWithArg
create an instance of the receiver-class,
evaluate blockWithArg, passing that instance,
return the instance.
Similar to streamContents, but passes the collection to the block,
instead of a stream.

o  streamContents: blockWithArg
create a write-stream on an instance of the receiver-class,
evaluate blockWithArg, passing that stream,
extract and return the streams contents.

o  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).

o  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.
usage example(s):
     String streamContentsEnumerating:'hello' using:#reverseDo:
     Array streamContentsEnumerating:Method using:#allInstancesDo:

o  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.
usage example(s):
     String streamContentsOf:'hello' enumerator:#reverseDo:
     Array streamContentsOf:Method enumerator:#allInstancesDo:

o  withCollectedContents: blockWithArg
create an instance of the receiver-class,
evaluate blockWithArg, passing that instance,
return the instance.
Similar to streamContents, but passes the collection to the block,
instead of a stream.

o  writeStream
create a write-stream on an instance of the receiver-class
usage example(s):
     OrderedCollection writeStream
     Text writeStream

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

o  writeStreamWithInitialSize: l
create a write-stream on an instance of the receiver-class

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


Instance protocol:

Compatibility-Squeak
o  allButFirst
Return a copy of the receiver containing all but the first element.
Returns an empty collection if there are not at least two elements.
Differs from #copyButFirst in its error behavior.
usage example(s):
     '1234567890' allButFirst
     'ab' allButFirst
     'a' allButFirst
     '' allButFirst

     '' copyButFirst

o  allButFirst: n
Return a copy of the receiver containing all but the first n elements.
Returns a short (or empty) collection if there are not enough elements.
Differs from #copyButFirst: in its error behavior.
usage example(s):
     '1234567890' allButFirst:5 
     '123456' allButFirst:5       
     '12345' allButFirst:5       
     '1234' allButFirst:5       

     '1234' copyButFirst:5       

o  allButLast
Return a copy of the receiver containing all but the last element.
Returns an empty collection if there are not at least two elements.
Differs from #copyButFirst: in its error behavior.
usage example(s):
     '1234567890' allButLast
     'ab' allButLast
     '0' allButLast
     '' allButLast

     '' copyButLast

o  allButLast: n
Return a copy of the receiver containing all but the last n elements.
Returns a short (or empty) collection if there are not enough elements.
Differs from #copyButFirst: in its error behavior.
usage example(s):
     '1234567890' allButLast:5
     '12345' allButLast:5
     '123' allButLast:5
     { 1 . 2 . 3 . 4 . 5 . 6 . 7} asOrderedCollection allButLast:5
     { 1 . 2 . 3 . 4 . 5} asOrderedCollection allButLast:5
     { 1 . 2 . 3 } asOrderedCollection allButLast:5
     '' allButLast:5

     '' copyButLast:5

o  asTraitComposition
( an extension from the stx:libcompat package )
For convenience the composition {T1. T2 ...} is the same as T1 + T2 + ...
usage example(s):
    ^self isEmpty
	ifFalse: [
	    self size = 1
		ifTrue: [self first asTraitComposition]
		ifFalse: [
		    self copyWithoutFirst
			inject: self first
			into: [:left :right | left + right]]]
	ifTrue: [
	    TraitComposition new]

o  atPin: index
Return the index'th element of me if possible.
Return the first or last element if index is out of bounds.
usage example(s):
     #(1 2 3) atPin:4
     #(1 2 3) atPin:0
     #(1 2 3) atPin:1
     #(1 2 3) atPin:3

o  atRandom
Return any random element from the receiver
usage example(s):
     #(1 2 3) atRandom

o  atRandom: aRandomGenerator
Return any random element from the receiver
usage example(s):
     #(1 2 3) atRandom:(Random new)

o  atWrap: index
Return the index'th element of me if possible.
Wrap the index modulu the receiver's size if it is out of bounds.
usage example(s):
     #(1 2 3) atWrap:1
     #(1 2 3) atWrap:2
     #(1 2 3) atWrap:3
     #(1 2 3) atWrap:4
     #(1 2 3) atWrap:5
     #(1 2 3) atWrap:6
     #(1 2 3) atWrap:7
     #(1 2 3) atWrap:0
     #(1 2 3) atWrap:-1

o  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

o  copyUpToLast: element
return a copy of the receiver up to (but excluding) the last occurrence
of element; uses = for comparison
usage example(s):
     'hello world' copyUpToLast:$l
     '123456123456' copyUpToLast:$2
     #(1 2 3 4 1 2 3 3 4 5 6) copyUpToLast:3
     #(1 2 3 4 2 3 3 4 5 6) copyUpToLast:1
     #(1 2 3 4 1 2 3 3 4 5 6) copyUpToLast:7

o  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.
usage example(s):
     #($a $b $c $d $e $f $g) copyWithoutAll:#($d $b $f)
     'abcdefghi' copyWithoutAll:'hai'
     #(90 80 70 80 60 45 80 50) copyWithoutAll:#(80 70 45)

o  copyWithoutFirst
An alias for copyButFirst: for squeak compatibility.
Raises an error, if the receiver is empty.
usage example(s):
     'foo' copyWithoutFirst
     'f' copyWithoutFirst
     '' copyWithoutFirst

o  destroy
used with cryptographic keys, to wipe their contents after use

o  forceTo: newSize paddingWith: padding
#[1 2 3 4] forceTo:10 paddingWith:255
#[1 2 3 4] forceTo:3 paddingWith:255

o  joinWith: separatingElement
return a collection generated by concatenating my elements
and embedding separatingElement in between.
Similar to asStringWith:, but not specifically targeted towards collections of strings.
usage example(s):
     #('hello' 'world' 'foo' 'bar' 'baz') joinWith:$;   
     #('hello' 'world' 'foo' 'bar' 'baz') joinWith:$|
     #('hello' 'world' 'foo' 'bar' 'baz') joinWithAll:'; '

o  pairsDistanceFrom: aSequenceableCollection
( an extension from the stx:libcompat package )

o  pairsSimilarityWith: aSequenceableCollection
( an extension from the stx:libcompat package )
Examples:
'1234' pairsSimilarityWith: '2234' ==> (2/3)
'1234' pairsSimilarityWith: '123' ==> (4/5)
'1234' pairsSimilarityWith: '5678' ==> 0

o  piecesCutWhere: testBlock do: enumerationBlock
( an extension from the stx:libcompat package )
Evaluate testBlock for successive pairs of the receiver elements,
breaking the receiver into pieces between elements where
the block evaluated to true, and evaluate enumerationBlock
with each of those pieces.
usage example(s):
'A sentence. Another sentence... Yet another sentence.'
		piecesCutWhere: [:each :next | each = $. and: [next = Character space]] 
		do: [:each | Transcript show: each printString; cr]

o  runsFailing: aBlock
( an extension from the stx:libcompat package )
Evaluate testBlock with the receiver elements, selecting from the
receiver runs, that is sequences of adjacent elements, for which
the block returned false. Return an OrderedCollection of those runs.
usage example(s):
'Hello to\all of the world,\isn''t Smalltalk cool?' 
		runsFailing: [:each | each = $\] 

o  runsSatisfying: testBlock
( an extension from the stx:libcompat package )
Evaluate testBlock with the receiver elements, selecting from the
receiver runs, that is sequences of adjacent elements, for which the block
returned true. Return an OrderedCollection of those subsequences.
usage example(s):
'Hello to\all of the world,\isn''t Smalltalk cool?' 
		runsSatisfying: [:each | each ~= $\] 

o  runsSatisfying: testBlock do: enumerationBlock
( an extension from the stx:libcompat package )
Evaluate testBlock with the receiver elements, selecting from the
receiver runs, that is sequences of adjacent elements, for which the block
returned true, and evaluate enumerationBlock with each of those
subsequences.
usage example(s):
'Hello to\all of the world,\isn''t Smalltalk cool?' 
		runsSatisfying: [:each | each ~= $\] 
		do: [:each | Transcript show: each; cr]

o  shuffle
( an extension from the stx:libcompat package )
Swaps the receiver's elements at random. Inplace, destructive

o  shuffle: times
( an extension from the stx:libcompat package )
Swaps random elements of the receiver. Inplace, destructive

o  shuffled
return a randomly shuffled copy of the receiver
usage example(s):
     #(1 2 3 4 5 6 7 8 9) shuffled.
     #(1 2 3 4 5 6 7 8 9) shuffled. 

o  shuffledBy: aRandom
return a randomly shuffled copy of the receiver, using the given random generator
usage example(s):
     #(1 2 3 4 5 6 7 8 9) shuffledBy:(Random new).
     #(1 2 3 4 5 6 7 8 9) shuffledBy:(Random new). 

o  sliceFrom: startIndex
( an extension from the stx:libcompat package )
Answers a copy of a subset of the receiver, starting from element at start index
up to the end of the collection.

Comfortable alternative to stupid copyFrom:to: method.
See also comment on sliceFrom:to:

o  sliceFrom: startIndex to: endIndex
( an extension from the stx:libcompat package )
Answers a copy of a subset of the receiver, starting from element at start index
until element at end index.

Comfortable alternative to stupid copyFrom:to: method.
If the start or end index is negative, the index will be counted from the end of the collection.

Note: this method does NEVER throw a SubscriptOutOfBoundsError. If the indexes are
too large or start is greater than end, then an empty collection will be returned.

o  sliceTo: endIndex
( an extension from the stx:libcompat package )
Answer a copy of a subset of the receiver, starting from first element
up to element at endIndex.

o  sortBy: aBlock
Sort inplace - destructive

Compatibility-V'Age
o  replaceFrom: start to: end withObject: anObject
Replace the elements from start to end with anObject.
Return the receiver.

Compatibility-VW
o  replaceElementsFrom: start to: stop withArray: anArray startingAt: repStart

JavaScript support
o  concat: aCollection
( an extension from the stx:libjavascript package )
obsolete: now xlated to js_concat:.
returns a new collection consisting of the concatenation of the receiver and the argument

o  doesNotUnderstand: aMessage
( an extension from the stx:libjavascript package )
consider this a hack: JavaScript concat(...) is a varArg method;

o  every: filterFunction
( an extension from the stx:libjavascript package )
return true, if filterFunction returns true for all elements

o  filter: filterFunction
( an extension from the stx:libjavascript package )
select elements for which filterFunction returns true

o  indexOf0: anElement
( an extension from the stx:libjavascript package )
returns the index of anElement, using a 0-based indexing scheme; -1 if not found (sigh)

o  indexOf1: anElement
( an extension from the stx:libjavascript package )
returns the index of anElement, using a 1-based indexing scheme; 0 if not found (sigh)

o  join: separator
( an extension from the stx:libjavascript package )
joins the strings of the receiver into a single string
usage example(s):
     #(1 2 3 4 5 6) join:' '

o  js_add: aCollection
( an extension from the stx:libjavascript package )
For JavaScript only:
Alternative string-concatenation.
Generated for +-operator in javascript.
usage example(s):
     'hello' + $1   - fails in ST
     'hello' + '1'  - fails in ST

     'hello' js_add: $1   - ok in JS
     'hello' js_add: '1'  - ok in JS

o  js_concat
( an extension from the stx:libjavascript package )
JS: coll.concat()
returns a copy of the receiver

o  js_concat: arg1
( an extension from the stx:libjavascript package )
JS: collection.concat(arg1)
returns a new collection consisting of the concatenation of the receiver and the argument

o  js_concat: arg1 _: arg2
( an extension from the stx:libjavascript package )
JS: collection.concat(arg1, arg2)
returns a new collection consisting of the concatenation of the receiver and the arguments

o  js_concat: arg1 _: arg2 _: arg3
( an extension from the stx:libjavascript package )
JS: collection.concat(arg1, arg2, arg3)
returns a new collection consisting of the concatenation of the receiver and the arguments

o  js_concat: arg1 _: arg2 _: arg3 _: arg4
( an extension from the stx:libjavascript package )
JS: collection.concat(arg1, arg2, arg3, arg4)
returns a new collection consisting of the concatenation of the receiver and the arguments

o  js_concat: arg1 _: arg2 _: arg3 _: arg4 _: arg5
( an extension from the stx:libjavascript package )
JS: collection.concat(arg1, arg2, arg3, arg4, arg5)
returns a new collection consisting of the concatenation of the receiver and the arguments

o  js_concat: arg1 _: arg2 _: arg3 _: arg4 _: arg5 _: arg6
( an extension from the stx:libjavascript package )
JS: collection.concat(arg1, arg2, arg3, arg4, arg5, arg6)
returns a new collection consisting of the concatenation of the receiver and the arguments

o  js_indexOf: anElement
( an extension from the stx:libjavascript package )
JS: collection.indexOf(element)
returns the index of anElement, using a 0-based indexing scheme; -1 if not found (sigh).
Selector-xlation to allow redefinition in CharacterArray, which supports substring searching.

o  js_indexOf: anElement _: startIndex
( an extension from the stx:libjavascript package )
JS: collection.indexOf(element, startIndex)
returns the index of anElement, using a 0-based indexing scheme; -1 if not found (sigh).
Selector-xlation to allow redefinition in CharacterArray, which supports substring searching.

o  js_lastIndexOf: anElement
( an extension from the stx:libjavascript package )
JS: collection.lastIndexOf(element)
returns the index of the last occurrence of anElement, using a 0-based indexing scheme; -1 if not found (sigh).
Selector-xlation to allow redefinition in CharacterArray, which supports substring searching.

o  js_lastIndexOf: anElement _: startIndex
( an extension from the stx:libjavascript package )
JS: collection.lastIndexOf(element)
returns the index of the last occurrence of anElement, using a 0-based indexing scheme; -1 if not found (sigh).
Selector-xlation to allow redefinition in CharacterArray, which supports substring searching.

o  js_map: function
( an extension from the stx:libjavascript package )
JS: collection.map(func)
return a new collection collecting the results of applying function to each element in sequence

o  lastIndexOf0: anElement
( an extension from the stx:libjavascript package )
returns the last index of anElement, using a 0-based indexing scheme; -1 if not found (sigh)

o  lastIndexOf1: anElement
( an extension from the stx:libjavascript package )
returns the last index of anElement, using a 1-based indexing scheme; 0 if not found (sigh)

o  pop
( an extension from the stx:libjavascript package )
removes and returns the last element of the collection

o  push: value
( an extension from the stx:libjavascript package )
adds value at the end of the collection; returns the new size

o  reduce0: filterFunction
( an extension from the stx:libjavascript package )
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.
usage example(s):
     #(1 2 3 4 5 6 7 8 9 10) reduce0:[:prev :this :idx :arr | prev + this]

     JavaScriptParser
	evaluate:'
[0,1,2,3,4].reduce(function(previousValue, currentValue, index, array){
  return previousValue + currentValue;
});
'

     JavaScriptParser
	evaluate:'[0,1,2,3,4].length;'

o  reduce0: filterFunction _: initialValue
( an extension from the stx:libjavascript package )
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.

o  reduce1: filterFunction
( an extension from the stx:libjavascript package )
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.
usage example(s):
     #(1 2 3 4 5 6 7 8 9 10) reduce1:[:prev :this :idx :arr | prev + this]

o  reduce1: filterFunction _: initialValue
( an extension from the stx:libjavascript package )
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.

o  shift
( an extension from the stx:libjavascript package )
removes and returns the first element of the collection

o  slice0: index1 _: index2
( an extension from the stx:libjavascript package )
extracts a subcollection, using a 0-based indexing scheme

o  slice1: index1 _: index2
( an extension from the stx:libjavascript package )
extracts a subcollection, using a 1-based indexing scheme

o  some: filterFunction
( an extension from the stx:libjavascript package )
return true, if filterfunction returns true for any element

o  unshift: arg
( an extension from the stx:libjavascript package )
adds an element to the beginning of the collection

accessing
o  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.
usage example(s):
     #(4 3 2 1) asOrderedCollection after:3.
     #(4 3 2 1) asOrderedCollection after:5
     #(4 3 2 1) asOrderedCollection after:1

o  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.
usage example(s):
     #(4 3 2 1) after:3 ifAbsent:nil.
     (2 to:10 by:2) after:4 ifAbsent:nil.
     #(4 3 2 1) asOrderedCollection after:5 ifAbsent:nil.
     (2 to:10 by:2) after:5 ifAbsent:nil.

o  anElement
return any element from the collection,
report an error if there is none.
Use this to fetch the some element from a collection which is non-indexed or which
has a non-numeric index. I.e. if someone gets an arbitrary collection which might be either indexable
or not, anElement is a save way to access some element without a need to check for a proper key.
usage example(s):
     #() anElement            -> Error
     #(1 2 3) anElement       -> 1
     #(1 2 3) asSet anElement -> any one (undefined which one)

o  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.
usage example(s):
     #(1 2 3) at:4 ifAbsent:['no such index']
     #(1 2 3) asOrderedCollection at:4 ifAbsent:['no such index']
     #(1 2 3) at:4 ifAbsent:['no such index']

     (Dictionary with:(#foo -> #bar)
		 with:(#frob -> #baz))
	 at:#foobar ifAbsent:['no such index']

o  atAllIndices: indexCollection
return the elements at each index from indexCollection.
usage example(s):
     'abcdefghijklmnopqrstuvwxyz' atAllIndices:#( 8 5 12 12 15) 
     'abcdefghijklmnopqrstuvwxyz' atAllIndices:( 5 to: 10) 

o  atIndex: index
return an element at a given index. This allows for sequentialCollections
and orderedDictionaries to be both accessed via a numeric index.

o  atIndex: index ifAbsent: absentBlock
return an element at a given index. This allows for sequenceableCollections
and orderedDictionaries to be both accessed via a numeric index.

o  atIndex: index put: newValue
return an element at a given index. This allows for sequentialCollections
and orderedDictionaries to be both accessed via a numeric index.

o  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.
usage example(s):
     #(4 3 2 1) asOrderedCollection before:3.
     #(4 3 2 1) asOrderedCollection before:4
     #(4 3 2 1) asOrderedCollection before:0

o  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.
usage example(s):
     #(4 3 2 1) asOrderedCollection before:3 ifAbsent:nil.
     #(4 3 2 1) asOrderedCollection before:5 ifAbsent:nil.
     #(4 3 2 1) asOrderedCollection before:5.
     #(4 3 2 1) asOrderedCollection before:4 ifAbsent:nil.
     #(4 3 2 1) asOrderedCollection before:4.
     (2 to:10 by:2) before:4 ifAbsent:nil.
     (2 to:10 by:2) before:5 ifAbsent:nil.

o  first
return the first element;
report an error, if the collection is empty.

o  first: n
return the n first elements of the collection.
No longer raises an error if there are not enough elements;
instead, returns what is there
usage example(s):
     #(1 2 3 4 5) first:3
     #(1 2 3 4 5) first:6
     #(1 2 3 4 5) asSet first:3
     'hello world' first:5

o  firstOrNil
return the first element or nil, if the collection is empty.

o  indexOfNth: n occurrenceOf: what
return the index of the nTh occurrence of a value, or 0 if there are not that many
usage example(s):
1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6
   #(1 2 3 4 1 2 3 1 9 8 7 1 7 8 9 0) indexOfNth:3 occurrenceOf:1
   #(1 2 3 4 1 2 3 1 9 8 7 1 7 8 9 0) indexOfNth:2 occurrenceOf:7
   #(1 2 3 4 1 2 3 1 9 8 7 1 7 8 9 0) indexOfNth:3 occurrenceOf:9

o  keyAtEqualValue: value
return the index of a value.
This is normally not used (use indexOf:),
but makes the protocol more compatible with dictionaries.
This is a slow access, since the receiver is searched sequentially.
NOTICE:
The value is searched using equality compare

o  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.
This is a slow access, since the receiver is searched sequentially.
NOTICE:
The value is searched using equality compare

o  keyAtIdenticalValue: value
return the identity index of a value.
This is normally not used (use indexOf:),
but makes the protocol more compatible with dictionaries.
This is a slow access, since the receiver is searched sequentially.

o  keyAtIdenticalValue: value ifAbsent: exceptionBlock
return the identity index of a value.
This is normally not used (use indexOf:),
but makes the protocol more compatible with dictionaries.
This is a slow access, since the receiver is searched sequentially.
NOTICE:
The value is searched using identity compare

o  keyAtValue: value
return the index of a value.
This is normally not used (use indexOf:),
but makes the protocol more compatible with dictionaries.
This is a slow access, since the receiver is searched sequentially.
NOTICE:
The value is searched using identity compare;
use #keyAtEqualValue: to compare for equality.

o  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.
This is a slow access, since the receiver is searched sequentially.
NOTICE:
The value is searched using identity compare;
use #keyAtEqualValue:ifAbsent: to compare for equality.

o  last
return the last element;
report an error, if the collection is empty.
usage example(s):
     #(1 2 3 4 5) last
     #() last

o  last: n
return the n last elements of the collection.
No longer raises an error if there are not enough elements;
instead, returns what is there.
usage example(s):
     #(1 2 3 4 5) last:3
     #(1 2 3 4 5) last:6
     #(1 2 3 4 5) asSet last:3
     'hello world' last:5
     'hello' last:10

o  nth: n
return the nth element;
report an error, if the collections size is smaller than n.
usage example(s):
     #(10 20 30 40 50) nth:4
     #(10 20 30 40 50) nth:6
     #() nth:1

o  order
the order is the set of keys

o  second
return the second element;
report an error, if the collections size is smaller than 2.

o  secondLast
return the second last element;
report an error, if the collection does not contain at least
2 elements.
usage example(s):
     #(1 2 3 4 5) secondLast
     #(1) secondLast
     #() secondLast

o  swap: index1 with: index2
exchange two elements

o  swapIndex: i1 and: i2
spap element at i1 and i2

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

adding & removing
o  add: anObject
append the argument, anObject to the collection.
Return the argument, anObject.

Notice that this 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 recommended).

o  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 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 recommended).
usage example(s):
     #(1 2 3 4 5 6 7 8) add:'hello' beforeIndex:5

o  addAll: aCollection beforeIndex: index
insert all elements of the argument, anObject to become located at index.
The collection may be unordered, but then order of the sliced-in elements
is undefined.
Return the receiver.

o  addFirst: anObject
prepend the argument, anObject to the collection.
Return the argument, anObject.

Notice that this 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 recommended).

o  remove: anElement ifAbsent: aBlock
search for the first occurrence of object
(i.e. 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 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 recommended).
usage example(s):
     #(1 2 3 4 5 6 7 8 9 0) remove:3 ifAbsent:[Transcript showCR:'no']
     #(1 2 3 4 5 6 7 8 9 0) remove:99 ifAbsent:[#oops]
     #(1.0 2.0 3.0 4.0 5.0) remove:5 ifAbsent:[#oops]
     #(1.0 2.0 3.0 4.0 5.0) removeIdentical:5 ifAbsent:[#oops]

     |a|
     a := #(1 2 3 1 2 3 1 2 3).
     a remove:3.
     a

     |a|
     a := #(1 2 3 1 2 3 1 2 3) asOrderedCollection.
     a remove:3.
     a

o  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.

o  removeAtIndex: anIndex
remove the element stored at anIndex. Return the removed object.

Notice that this 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 recommended).
usage example(s):
     #(1 2 3 4 5 6 7 8 9) asOrderedCollection removeAtIndex:3
     #(1 2 3 4 5) asOrderedCollection removeAtIndex:6
     #($a $b $c $d $e $f $g) removeAtIndex:3

o  removeFirst
remove the first element of the receiver and return it.

Notice that this 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 recommended).

o  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 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 recommended).
usage example(s):
     #(1 2 3 4 5 6 7 8 9 0) asOrderedCollection removeFromIndex:3
     #(1 2 3 4 5 6 7 8 9 0) removeFromIndex:3

o  removeFromIndex: startIndex toIndex: endIndex
remove the elements stored at indexes between startIndex and endIndex.
Return the receiver.

Notice that this 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 recommended).
usage example(s):
     #(1 2 3 4 5 6 7 8 9 0) asOrderedCollection removeFromIndex:3 toIndex:5
     #(1 2 3 4 5 6 7 8 9 0) removeFromIndex:3 toIndex:5
     #(1 2 3 4 5 6 7 8 9 0) asOrderedCollection removeFromIndex:1 toIndex:10
     #(1 2 3 4 5 6 7 8 9 0) removeFromIndex:1 toIndex:10

o  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 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 recommended).
usage example(s):
     #(1.0 2.0 3.0 4.0 5.0) remove:5 ifAbsent:[#oops]
     #(1.0 2.0 3.0 4.0 5.0) removeIdentical:5 ifAbsent:[#oops]

o  removeIndex: index
remove the argument stored at index. Return the receiver.

Notice that this 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 recommended).
usage example(s):
     #(1 2 3 4 5 6 7 8 9) asOrderedCollection removeIndex:3
     #(1 2 3 4 5) asOrderedCollection removeIndex:6
     #($a $b $c $d $e $f $g) removeIndex:3

o  removeLast
remove the last element of the receiver and return it.

Notice that this 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 recommended).

o  removeToIndex: index
remove the elements stored at indexes from 1 to index to the beginning.
Return the receiver.

Notice that this 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 recommended).

combinatoric
o  combinationsDo: aBlock
Repeatly evaluate aBlock with all combinations of elements from the receiver's elements.
The receiver's elements must be collections of the individuals to be taken for the combinations
usage example(s):
     (Array with:($a to:$d)) 
        combinationsDo:[:eachCombination | Transcript showCR: eachCombination]
usage example(s):
     (Array 
            with:($a to:$d)
            with:(1 to: 4)) 
        combinationsDo:[:eachCombination | Transcript showCR: eachCombination]
usage example(s):
all combinations of two letters are generated with:
     (Array 
            with:($a to:$z)
            with:($a to:$z)) 
        combinationsDo:[:eachCombination | Transcript showCR: eachCombination]
usage example(s):
     (Array 
            with:#(1 2 3 4 5 6 7 8 9)
            with:#(A)) 
        combinationsDo:[:eachCombination | Transcript showCR: eachCombination]

o  combinationsStartingAt: anInteger prefix: prefix do: aBlock
a helper for combinationsDo:

o  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.
usage example(s):
     (1 to: 4) asArray lexicographicPermutationsDo:[:each | Transcript showCR: each printString]

o  lexicographicPermutationsStartingAt: anInteger do: aBlock
a helper for lexicographicPermutationsDo:

o  permutationsDetect: 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.
Return the first permutation for which aBlock returns true, nil if there is none.

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.

o  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.
usage example(s):
     (1 to: 4) asArray permutationsDo:[:each | Transcript showCR: each printString]

o  permutationsStartingAt: anInteger do: aBlock
a helper for permutationsDo:

o  permutationsStartingAt: anInteger with: anotherCollection do: aBlock
a helper for permutationsDo:

o  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.
usage example(s):
     (1 to: 4) asArray permutationsWith:'abcd' 
        do:[:each1 :each2 | Transcript showCR: each2 copy]

comparing
o  < aCollection
compare two sequenceable collections
usage example(s):
      #(1 2 3) < #(1)
      #(1 2 3) < #(2)
      #(1 2 3) < #()
      #(1 2 3) < #(1 2 3)

      |a b|

      a := 'hello world'.
      b := a copy.
      Time millisecondsToRun:[
        1000000 timesRepeat:[
            a < b
        ]
      ]

      |a b|

      a := CharacterArray fromString:'hello world'.
      b := a copy.
      Time millisecondsToRun:[
        1000000 timesRepeat:[
            a < b
        ]
      ]

      |a b|

      a := #[1 2 3 4 5 6 7 8 9 10 11].
      b := a copy.
      Time millisecondsToRun:[
        1000000 timesRepeat:[
           a < b
        ]
      ]

o  <= aCollection
Compare the receiver with the argument and return true if the
receiver is less than or equal to the argument. Otherwise return false

o  = aCollection
return true if the receiver and aCollection represent collections
with equal contents, and if they are of the same species.
usage example(s):
     #(1 2 3 4 5) = #(1 2 3 4 5)
     #($1 $2 $3 $4 $5) = #(1 2 3 4 5)
     #($1 $2 $3 $4 $5) = '12345'
     #($1 $2 $3 $4 $5) = '54321' asSortedCollection

o  > aCollection
Compare the receiver with the argument and return true if the
receiver is greater than the argument.
Otherwise return false.

o  >= aCollection
Compare the receiver with the argument and return true if the
receiver is greater than or equal to the argument.
Otherwise return false.

o  beginsWith: aCollection
Squeak & VW compatibility: similar to #startsWith: but returns false for an empty argument - sigh

o  commonElementsWith: 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 #= .
usage example(s):
        #(1 2 3) commonElementsWith:#(4 2 3 4)

o  commonPrefixWith: aCollection
return the common prefix of myself and the argument, aCollection.
If there is none, an empty collection is returned.
usage example(s):
     'hello' commonPrefixWith:'hello'
     'hello' commonPrefixWith:'hElLo'
     'hello' commonPrefixWith:'hello world'
     'hello' commonPrefixWith:'hElLo WoRlD'

     'hello world' commonPrefixWith:'hello'
     'hello WoRlD' commonPrefixWith:'hElLo'

     'abcd' commonPrefixWith:'bcde'

     'abcd' commonPrefixWith:'abab'
     'abcd' commonPrefixWith:'ab'
     'abcd' commonPrefixWith:'ababab'
     'abcd' commonPrefixWith:'abcdef'

     'abab' commonPrefixWith:'abcd'
     'ab'   commonPrefixWith:'abcd'
     'ababab' commonPrefixWith:'abcd'
     'abcdef' commonPrefixWith:'abcd'

o  commonPrefixWith: aCollection caseSensitive: caseSensitive
return the common prefix of myself and the argument, aCollection.
If there is none, an empty collection is returned.
usage example(s):
     'hello' commonPrefixWith:'hello' caseSensitive:false
     'hello' commonPrefixWith:'hElLo' caseSensitive:false
     'hello' commonPrefixWith:'hello world' caseSensitive:false
     'hello' commonPrefixWith:'hElLo WoRlD' caseSensitive:false

     'hello world' commonPrefixWith:'hello' caseSensitive:false
     'hello WoRlD' commonPrefixWith:'hElLo' caseSensitive:false

     'abcd' commonPrefixWith:'bcde' caseSensitive:false

     'abcd' commonPrefixWith:'abab' caseSensitive:false
     'abcd' commonPrefixWith:'aBAb' caseSensitive:false
     'abcd' commonPrefixWith:'ab'   caseSensitive:false
     'abcd' commonPrefixWith:'ababab'   caseSensitive:false
     'abcd' commonPrefixWith:'abcdef'   caseSensitive:false

     'abab' commonPrefixWith:'abcd' caseSensitive:false
     'ab'   commonPrefixWith:'abcd'   caseSensitive:false
     'ababab' commonPrefixWith:'abcd'   caseSensitive:false
     'abcdef' commonPrefixWith:'abcd'   caseSensitive:false

o  commonPrefixWith: aCollection ignoreCase: ignoreCase
return the common prefix of myself and the argument, aCollection.
If there is none, an empty collection is returned.

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

o  commonSuffixWith: aCollection
return the common suffix (tail) of myself and the argument, aCollection.
If there is none, an empty collection is returned.
usage example(s):
     'hello' commonSuffixWith:'hello'
     'hello' commonSuffixWith:'hElLo'
     'hello' commonSuffixWith:'hello world'
     'hello' commonSuffixWith:'hElLo WoRlD'
     'hello2 world' commonSuffixWith:'hello world'
     'hello2 world' commonSuffixWith:'hElLo WoRlD'

     'hello world' commonSuffixWith:'world'
     'hello WoRlD' commonSuffixWith:'world'

     'dcba' commonSuffixWith:'edcb'

     'dcba' commonSuffixWith:'baba'
     'dcba' commonSuffixWith:'ba'
     'dcba' commonSuffixWith:'bababa'
     'dcba' commonSuffixWith:'fdcba'

     'baba' commonSuffixWith:'dcba'
     'ba'   commonSuffixWith:'dcba'
     'bababa' commonSuffixWith:'dcba'
     'fdcba' commonSuffixWith:'dcba'

o  commonSuffixWith: aCollection caseSensitive: caseSensitive
return the common suffix (tail) of myself and the argument, aCollection.
If there is none, an empty collection is returned.
usage example(s):
     'hello' commonSuffixWith:'hello' caseSensitive:false
     'hello' commonSuffixWith:'hElLo' caseSensitive:false
     'hello' commonSuffixWith:'hello world' caseSensitive:false
     'hello' commonSuffixWith:'hElLo WoRlD' caseSensitive:false
     'hello2 world' commonSuffixWith:'hello world' caseSensitive:false
     'hello2 world' commonSuffixWith:'hElLo WoRlD' caseSensitive:false

     'hello world' commonSuffixWith:'world' caseSensitive:false
     'hello WoRlD' commonSuffixWith:'world' caseSensitive:false

     'dcba' commonSuffixWith:'edcb' caseSensitive:false

     'dcba' commonSuffixWith:'baba' caseSensitive:false
     'dcba' commonSuffixWith:'ba'   caseSensitive:false
     'dcba' commonSuffixWith:'bababa'   caseSensitive:false
     'dcba' commonSuffixWith:'fdcba'   caseSensitive:false

     'baba' commonSuffixWith:'dcba' caseSensitive:false
     'ba'   commonSuffixWith:'dcba'   caseSensitive:false
     'bababa' commonSuffixWith:'dcba'   caseSensitive:false
     'fdcba' commonSuffixWith:'dcba'   caseSensitive:false

o  commonSuffixWith: aCollection ignoreCase: ignoreCase
return the common suffix (tail) of myself and the argument, aCollection.
If there is none, an empty collection is returned.

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

o  compareWith: aSequenceableCollection
Compare the receiver with the argument and return 1 if the receiver is
greater, 0 if equal and -1 if less than the argument.

o  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
usage example(s):
     #(1 2 3 4 5) deepSameContentsAs: #(1 2 3 4 5)
     #($1 $2 $3 $4 $5) deepSameContentsAs: #(1 2 3 4 5)
     #($1 $2 $3 $4 $5) deepSameContentsAs: '12345'
     #($1 $2 $3 $4 $5) deepSameContentsAs: '54321' asSortedCollection

o  endsWith: aCollection
return true, if the receiver's last elements match those of aCollection.
If aCollection is empty, true is returned (incompatible to some other dialect's endsWith.)
usage example(s):
     'abcde' endsWith:#($d $e)
     #[1 2 3 4] endsWith:#(3 4)
     #(1 2 3 4) asOrderedCollection endsWith:#(3 4)

o  endsWithAnyOf: aCollectionOfCollections
return true, if the receiver endswith any in aCollection
usage example(s):
     'abcde' endsWithAnyOf:#('DE' 'de')
     'abcde' endsWithAnyOf:#('DF' 'df')
     #[1 2 3 4] endsWithAnyOf:#( #(3 5) #(2 4))
     #[1 2 3 4] endsWithAnyOf:#( #(3 4) #(2 4))

o  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 #= .

o  hash
return a hash key for the receiver
usage example(s):
this hash is stupid - but for larger collections, the hashing
     time can become much bigger than the time lost in added probing.
     Time will show ...
usage example(s):
^ ((((self first hash bitShift:5) + self last hash) bitShift:5) + self size hash) bitAnd:16r3FFFFFFF.
usage example(s):
     #(1 2 3 4 5 6) hash
     (1 to:6) hash

     #(1 2 3 4 5 6.0) asOrderedCollection hash
     #[1 2 3 4 5 6] hash

o  indexOfFirstDifferenceWith: anotherCollection
return the index of the first element which is different to the corresponding
element in anotherCollection. 0 if they are all the same.
The comparison is by equality, i.e. using #=
usage example(s):
     'hello' indexOfFirstDifferenceWith:'helLo' 
     'hello' indexOfFirstDifferenceWith:'hello'   
     'hello' indexOfFirstDifferenceWith:'hello1'   
     'hello1' indexOfFirstDifferenceWith:'hello' 

o  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 #= .

o  sameContentsAs: aCollection
return true, if the receiver and the arg have the same contents.

Redefinded, so that SequenceableCollections are equivalent,
especially OrderedCollections with unused space
usage example(s):
     #(1 2 3 4 5) sameContentsAs: #(1 2 3 4 5) copy
     #(1 2 3 4 5) sameContentsAs: #(1 2 3 4) 
     #(1 2 3 4 5) sameContentsAs: #(1 2 3 4 5) asSet
     #(1 2 3 4 5) asSet sameContentsAs: #(1 2 3 4 5) copy
     #($1 $2 $3 $4 $5) sameContentsAs: #(1 2 3 4 5) 
     #($1 $2 $3 $4 $5) sameContentsAs: '12345'      
     #($1 $2 $3 $4 $5) sameContentsAs: '54321' asSortedCollection 
     #(1 2 3 4 5) sameContentsAs: nil 

o  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:#==.

usage example(s):
     #(1 2 3 4 5) sameContentsAs: #(1 2 3 4 5)     whenComparedWith:[:a :b | a = b]
     #(1 2 3 4 5) sameContentsAs: #(1 2 3 4 5) asSet whenComparedWith:[:a :b | a = b]
     #(1 2 3 4 5) sameContentsAs: #(1 2 3 4 5)     whenComparedWith:[:a :b | a == b]
     #(1 2 3 4 5) sameContentsAs: #(1.0 2 3 4.0 5) whenComparedWith:[:a :b | a = b]
     #(1 2 3 4 5) sameContentsAs: #(1.0 2 3 4.0 5) whenComparedWith:[:a :b | a == b]

     #('Hello' 'ABC' 'worlD') sameContentsAs: #('Hello' 'ABC' 'worlD') whenComparedWith:[:a :b | a sameAs:b]

o  sameContentsFrom: start1 to: stop1 as: aCollection startingAt: start2
return true, if the receiver's slice from start to stop
has the same contents as aCollection's slice starting at startIndex.
The argument, aCollection must be sequenceable.
usage example(s):
     #(1 2 3 4 5) sameContentsFrom:2 to:4 as:#(10 20 2 3 4 50) startingAt:3
     #(1 2 3 4 5) sameContentsFrom:2 to:4 as:#(10 20 2 30 4 50) startingAt:3
     #($1 $2 $3 $4 $5) sameContentsFrom:2 to:4 as:'54321234987' startingAt:6 

o  startsWith: aCollection
return true, if the receiver's first elements match those of aCollection
If the argument is empty, true is returned.
Notice, that this is similar to, but slightly different from VW's and Squeak's beginsWith:,
which are both inconsistent w.r.t. an empty argument.
usage example(s):
     'abcde' startsWith:#($a $b $c)
     'abcde' startsWith:'abc'
     'abcd' startsWith:'abcde'
     'abcde' startsWith:'abd'
     #[1 2 3 4] startsWith:#(1 2 3)
     #(1 2 3 4) asOrderedCollection startsWith:#(1 2 3)
     #(1 2 3 4) asOrderedCollection startsWith:#()

o  startsWithAnyOf: aCollectionOfCollections
return true, if the receiver starts with any in aCollection
usage example(s):
     'abcde' startsWithAnyOf:#('AB' 'ab')
     'abcde' startsWithAnyOf:#('AC' 'ac')
     #[1 2 3 4] startsWithAnyOf:#( #(1 3) #(1 4))
     #[1 2 3 4] startsWithAnyOf:#( #(1 3) #(1 2))

o  with: aCollection findFirst: aBlock
return the index of the first element for which aTwoArgBlock returns true
against corresponding elements of aCollection.
If any collection is smaller, the size of the smaller plus one is returned
usage example(s):
     'hello' with:'helLo' findFirst:[:a :b | a ~= b] 
     'hello' with:'hello' findFirst:[:a :b | a ~= b]   
     'hello' with:'hello1' findFirst:[:a :b | a ~= b]   
     'hello1' with:'hello' findFirst:[:a :b | a ~= b]   

converting
o  asSequenceableCollection
return myself as a SequenceableCollection.
I am already a SequenceableCollection.

o  asStringCollection
return a new string collection containing the elements;
these ought to be strings. (i.e. String or Text instances)

o  decodeAsLiteralArray
given a literalEncoding in the receiver,
create & return the corresponding object.
The inverse operation to #literalArrayEncoding.
usage example(s):
     #(10 20) literalArrayEncoding 
     #(Array 10 20) decodeAsLiteralArray 
     #() literalArrayEncoding   
     #(Array) decodeAsLiteralArray 

o  decodeAsLiteralArrayCollection
given an array of literalEncodings in the receiver,
create & return the corresponding collection object.
usage example(s):
     #(
        #(Point 10 20) 
        #(Point 20 30) 
        #(Point 30 40) 
        #(Point 40 50) 
     ) decodeAsLiteralArrayCollection 

converting-reindexed
o  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 (well, no; the slice is readOnly).
usage example(s):
     #(1 2 3 4 5 6 7) from:3
     ( #(1 2 3 4 5 6 7) from:3 ) first
     ( #(1 2 3 4 5 6 7) from:3 ) last
     ( #(1 2 3 4 5 6 7) from:3 ) size

o  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 (well, no; the slice is readOnly).
usage example(s):
     #(1 2 3 4 5 6 7) from:3 by:2
     ( #(1 2 3 4 5 6 7) from:3 by:2) first
     ( #(1 2 3 4 5 6 7) from:3 by:2) last
     ( #(1 2 3 4 5 6 7) from:3 by:2) size
     ( #(1 2 3 4 5 6 7) from:5 by:-2)

o  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.
usage example(s):
     #($a $b $c $d $e $f $g) from:2 count:3
     '1234567890' from:2 count:5

o  from: startIndex count: numberOfElements put: newElement
replace numberOfElements elements from startIndex of the collection
by the argument, newElement.
Notice: This operation modifies the receiver, NOT a copy;
therefore the change may affect all others referencing the receiver.
usage example(s):
     #($a $b $c $d $e $f $g) copy from:2 count:3 put:nil
     '1234567890' copy from:2 count:5 put:$*
     '1234567890' copy from:2 count:20 put:$* -> error

o  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 (well, no; the slice is readOnly).
usage example(s):
     #(1 2 3 4 5 6 7) from:3 to:6
     ( #(1 2 3 4 5 6 7) from:3 to:6) first
     ( #(1 2 3 4 5 6 7) from:3 to:6) last
     ( #(1 2 3 4 5 6 7) from:3 to:6) size
     
     #(1 2 3 4 5 6 7) from:3 to:1
     ( #(1 2 3 4 5 6 7) from:3 to:1 ) first
     ( #(1 2 3 4 5 6 7) from:3 to:1 ) last
     ( #(1 2 3 4 5 6 7) from:3 to:1 ) size

o  from: startIndex to: endIndex by: step
Create a ReindexedCollection from the receiver.
The new collection represents the receiver's 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.
usage example(s):
     #(1 2 3 4 5 6 7) from:3 to:7 by:2
     ( #(1 2 3 4 5 6 7) from:3 to:7 by:2) first
     ( #(1 2 3 4 5 6 7) from:3 to:7 by:2) last
     ( #(1 2 3 4 5 6 7) from:3 to:7 by:2) size

     ( #(1 2 3 4 5 6 7) from:7 to:3 by:-2) 

o  to: endIndex
Create a ReindexedCollection from the receiver.
The new collection represents the receiver's 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 (well, no; the slice is readOnly).
usage example(s):
     #(1 2 3 4 5 6 7) to:4
     ( #(1 2 3 4 5 6 7) to:4) first
     ( #(1 2 3 4 5 6 7) to:4) last
     ( #(1 2 3 4 5 6 7) to:4) size

o  to: endIndex by: step
Create a ReindexedCollection from the receiver.
The new collection represents the receiver's 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 (well, no; the slice is readOnly).
usage example(s):
     #(1 2 3 4 5 6 7) to:4 by:2
     ( #(1 2 3 4 5 6 7) to:4 by:2) first
     ( #(1 2 3 4 5 6 7) to:4 by:2) last
     ( #(1 2 3 4 5 6 7) to:4 by:2) size
     #(1 2 3 4 5 6 7) to:1 by:-1

copying
o  ++ aCollection
This is just syntactic sugar for javascript.
Return a new collection formed from concatenating the receiver with
the argument. The class of the new collection is determined by the
receiver's class, so mixing classes is possible, if the second collections
elements can be stored into instances of the receiver's class.
usage example(s):
     #($a $b $c) ++ #(1 2 3)
     #($a $b $c) ++ '123'
     'abc' ++ '123'
     'abc' ++ #($q $w $e $r $t $y) asSortedCollection
     'abc' ++ #(1 2 3 4 5)

o  , aCollection
return a new collection formed from concatenating the receiver with the argument.
The class of the new collection is determined by the
receiver's class, so mixing classes is possible, if the second collection's
elements can be stored into instances of the receiver's class.
usage example(s):
must grow, otherwise replace fails
usage example(s):
         yes, aCollection has indexed elements
usage example(s):
         no, enumerate aCollection
usage example(s):
     #($a $b $c) , #(1 2 3)
     #($a $b $c) , '123'
     'abc' , '123'
     'abc' , #($q $w $e $r $t $y) asSortedCollection
     'abc' , #(1 2 3 4 5)

o  ,* n
return a new collection formed from concatenating the receiver n times,
with 0 returning an empty collection, 1 returning the receiver, etc.
usage example(s):
     #($a $b $c) ,* 3
     'abc' ,* 5
     'abc' ,* 0
     'abc' ,* 1
     'a' ,* 50
     (1 to:4) ,* 5  

o  concatenate: string1 and: string2
return the concatenation of myself and the arguments, string1 and string2.
This is equivalent to self , string1 , string2
- generated by stc compiler when such a construct is detected and the receiver
is known to be a string.

o  concatenate: string1 and: string2 and: string3
return the concatenation of myself and the string arguments.
This is equivalent to self , string1 , string2 , string3
- generated by stc compiler when such a construct is detected and the receiver
is known to be a string.

o  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.
usage example(s):
     'hello world' copyAfter:$l
     '123456123456' copyAfter:$2
     #(1 2 3 4 1 2 3 3 4 5 6) copyAfter:3
     #(1 2 3 4 2 3 3 4 5 6) copyAfter:1
     #(1 2 3 4 1 2 3 3 4 5 6) copyAfter:7

o  copyAfterLast: element
return a copy of the receiver from (but excluding) the last occurrence
of element to the end; uses = for comparison
usage example(s):
     'hello world' copyAfterLast:$l
     '123456123456' copyAfterLast:$2
     #(1 2 3 4 1 2 3 3 4 5 6) copyAfterLast:3
     #(1 2 3 4 2 3 3 4 5 6) copyAfterLast:1
     #(1 2 3 4 1 2 3 3 4 5 6) copyAfterLast:7

o  copyButFirst
return a new collection consisting of the receiver's elements
except for the first element.
Raises an error if the receiver is empty.
Differs from #allButFirst in its error behavior.
usage example(s):
     #($a $b $c $d $e $f $g) copyButFirst
     '1234567890' copyButFirst
     '1' copyButFirst
     '' copyButFirst

     '' allButFirst

o  copyButFirst: count
return a new collection consisting of the receiver's elements
except for the first count elements
Raises an error if the receiver is empty.
Differs from #allButFirst: in its error behavior.
usage example(s):
     #($a $b $c $d $e $f $g) copyButFirst:2
     '1234567890' copyButFirst:2
     '12' copyButFirst:2
     '' copyButFirst:2

     '' allButFirst:2

o  copyButLast
return a new collection consisting of the receiver's elements
except for the last element.
Raises an error if the receiver is empty.
Differs from #allButLast in its error behavior.
usage example(s):
     #($a $b $c $d $e $f $g) copyButLast
     '1234567890' copyButLast
     '1' copyButLast
     '' copyButLast

     '' allButLast

o  copyButLast: count
return a new collection consisting of the receiver's elements
except for the last count elements.
Raises an error if there are not at least count elements.
Differs from #allButLast: in its error behavior.
usage example(s):
     #($a $b $c $d $e $f $g) copyButLast:2
     '1234567890' copyButLast:2
     '12' copyButLast:2
     '1' copyButLast:2

     '1' allButLast:2

o  copyFirst: count
return a new collection consisting of the receiver's first count elements.
Raises an error if there are not enough elements.
Differs from #first: in its error behavior.
usage example(s):
     #($a $b $c $d $e $f $g) copyFirst:5
     '1234567890' copyFirst:4
     '1234' copyFirst:4
     '12' copyFirst:4

     '1234567890' first:4
     '123' first:4
     '' first:4

o  copyFrom: startIndex
return a new collection consisting of receiver's elements from startIndex to the end of the collection.
Return an empty collection, if startIndex is beyond the receiver's size.
usage example(s):
     #($a $b $c $d $e $f $g) copyFrom:2
     '1234567890' copyFrom:2
     (10 to:19) copyFrom:5

o  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 receiver's size.
Raise an error, if stopIndex is out of range.
usage example(s):
     #($a $b $c $d $e $f $g) copyFrom:2 count:3
     '1234567890' copyFrom:2 count:5

o  copyFrom: startIndex to: stopIndex
return a new collection consisting of receiver's elements
between start and stop.
Returns an empty collection if startIndex is beyond the receiver's size.
Raise an error, if stopIndex is out of range.
usage example(s):
     #($a $b $c $d $e $f $g) copyFrom:2 to:5
     '1234567890' copyFrom:2 to:5
     (1 to:10) copyFrom:2 to:5

     '1234567890' copyFrom:2 to:15
     (1 to:10) copyFrom:12 to:1

o  copyLast: count
return a new collection consisting of the receiver's last count elements.
Raises an error if there are not enough elements.
Differs from #last: in its error behavior.
usage example(s):
     #($a $b $c $d $e $f $g) copyLast:5
     '1234567890' copyLast:4
     '12345' copyLast:4
     '1234' copyLast:4
     '123' copyLast:4
     '' copyLast:4

     '123' last:4
     '' last:4

o  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.

o  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.
usage example(s):
     #(1 2 3 4 1 2 3 4) copyMappingFrom:#(1 2) to:#('one' 'two')  
     'hello' copyMappingFrom:'eo' to:'**'    

o  copyReplaceAll: oldElement with: newElement
return a copy of the receiver, where all elements equal to oldElement
have been replaced by newElement.
usage example(s):
'Warning: #copyReplaceAll:with: will change semantics as defined in ANSI soon' errorPrintCR.
usage example(s):
     #(1 2 1 2 1 2 1 2 1 2) copyReplaceAll:1 with:99
     'hello world' copyReplaceAll:$l with:$*

o  copyReplaceAll: oldElement with: newElement ifNone: valueIfNoneFound
return a copy of the receiver, where all elements equal to oldElement
have been replaced by newElement.
If none is found, return valueIfNoneFound.
Usually this is used as:
foo copyReplaceAll:oldElement with:newElement ifNone:foo
usage example(s):
'Warning: #copyReplaceAll:with: will change semantics as defined in ANSI soon' errorPrintCR.
usage example(s):
     #(1 2 1 2 1 2 1 2 1 2) copyReplaceAll:1 with:99 ifNone:nil
     'hello world' copyReplaceAll:$l with:$* ifNone:'oops'
     'hello world' copyReplaceAll:$x with:$* ifNone:'oops' 

o  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.
usage example(s):
'Warning: #copyReplaceAll:withAll: will change semantics as defined in ANSI soon' errorPrintCR.
usage example(s):
     '123123abc123' copyReplaceAll:$1 withAll:'one' 
     #(1 2 3 4 1 2 3 4) copyReplaceAll:1 withAll:#(9 9 9) 
     #(1 2 3 4 1 2 3 4) copyReplaceAll:1 withAll:'one' 

o  copyReplaceAllSubcollections: subColl with: newColl
return a copy of the receiver, with all sequences of subColl replaced
by newColl (i.e. slice in the newColl in place of the subColl).
usage example(s):
     #[1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0] copyReplaceAllSubcollections:#[1 2 3] with:#[9 8 7]

     '12345678901234567890' copyReplaceAllSubcollections:'123' with:'OneTwoThree'
     '12345678901234567890' copyReplaceAllSubcollections:'123' with:'*'
     '12345678901234567890' copyReplaceAllSubcollections:'234' with:'foo'

o  copyReplaceAny: collectionOfOldElements with: newElement
return a copy of the receiver, where all elements equal to any in collectionOfOldElements
have been replaced by newElement.
usage example(s):
     #(1 2 3 1 2 3 1 2 3 4 1 2 3 1 2 3) copyReplaceAny:#(1 2) with:99
     'hello world' copyReplaceAny:'eo' with:$*

o  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.
Returns a plain copy, if startIndex is beyond the receiver's size
usage example(s):
     #(1 2 3 4 5 6 7 8 9 0) copyReplaceFrom:3 to:6 with:#(a b c d e f g h i j k)
     'hello world' copyReplaceFrom:6 to:6 with:' there, '
     'one two three' copyReplaceFrom:5 to:7 with:'zwei'

    the following is something we want, not an unexpected side feature:
     '12345' copyReplaceFrom:5 to:4 with:'xxx'

o  copyReplaceFrom: startIndex to: endIndex withObject: anObject
return a copy of the receiver, where the elements from startIndex to
endIndex have been replaced by anObject.
Returns a plain copy, if startIndex is beyond the receiver's size
usage example(s):
     #(1 2 3 4 5 6 7 8 9 0) copyReplaceFrom:3 to:6 withObject:#foo
     'hello world' copyReplaceFrom:1 to:5 withObject:$*
     'hello world' copyReplaceFrom:6 to:8 withObject:$*

o  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
usage example(s):
     #(1 2 3 4 5 6 7 8 9 0) copyReplaceFrom:3 with:#(a b c)
     'hello world' copyReplaceFrom:7 with:'smalltalk fan'

o  copyReplaceSubcollection: subColl with: newColl
return a copy of the receiver, with the first occurrence of
the subColl sequence replaced by newColl
(i.e. slice in the newColl in place of the first subColl).
usage example(s):
     #[1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0] copyReplaceSubcollection:#[1 2 3] with:#[9 8 7]
     #[0 0 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0] copyReplaceSubcollection:#[1 2 3] with:#[9 8 7]

     '12345678901234567890' copyReplaceSubcollection:'123' with:'OneTwoThree'
     '12345678901234567890' copyReplaceSubcollection:'123' with:'*'
     '12345678901234567890' copyReplaceSubcollection:'234' with:'foo'

o  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:
usage example(s):
     #(1 2 1 2 1 2 1 2 1 2) copyReplacing:1 withObject:99
     'hello world' copyReplacing:$l withObject:$*

o  copyThrough: element
return a new collection consisting of the receiver elements
up-to (AND including) the first occurrence of element.
usage example(s):
     #($a $b $c $d $e $f $g) copyThrough:$d
     '1234567890' copyThrough:$5
     '1234567890' copyThrough:$a
     '1234567890' copyThrough:$1

o  copyTo: stopIndex
Return a new collection consisting of receiver's elements from 1 up to (including) stopIndex.
Raise an error, if stopIndex is out of range.
usage example(s):
     #($a $b $c $d $e $f $g) copyTo:5
     '1234567890' copyTo:4

o  copyToMax: stop
return a new collection consisting of receiver's elements
from 1 up to (including) index stop, or up to the receiver's end,
whichever is smaller (i.e. like copyTo:, but do not err if receiver is smaller
usage example(s):
     #($a $b $c $d $e $f $g) copyTo:10  - raises an error
     #($a $b $c $d $e $f $g) copyToMax:10

o  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.

usage example(s):
     'abcdefghijkl1234567890' copyTransliterating:'b-g' to:'B-G'  
     'abcdefghijkl1234567890' copyTransliterating:'69' to:'96'      
     'abcdefghijkl1234567890' copyTransliterating:'a' to:'b'        
     'abcdefghijkl1234567890' copyTransliterating:'aeiou' to:'AEIOU' 
     'abcdefghijkl1234567890' copyTransliterating:'0-9' to:'QERTYUIOPX' 

     can also be used to remove character:
     'abcdefghijkl1234567890' copyTransliterating:'aeiou' to:''

     'abcdefg
hijkl1
234567890' copyTransliterating:(Array with:Character cr) to:''        

o  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)

usage example(s):
     'abcdefghijkl1234567890' copyTransliterating:'b-g' to:'B-G'    
     'abcdefghij-kl1234567890' copyTransliterating:'b\-g' to:'B+G'               
     'abcdefghijkl1234567890' copyTransliterating:'69' to:'96'      
     'abcdefghijkl1234567890' copyTransliterating:'a' to:'b'        
     'abcdefghijkl1234567890' copyTransliterating:'aeiou' to:'AEIOU'  
     'abcdefghijkl1234567890' copyTransliterating:'0-9' to:'QERTYUIOPX'  
     'abcdefghijkl1234567890' copyTransliterating:'a-z' to:'b-za'  
     'abcdefghijkl1234567890' copyTransliterating:'a-z' to:'c-zab'  
     'abcdefghijkl1234567890' copyTransliterating:'a-z' to:'z-a'  

     'abcdefghijkl1234567890' copyTransliterating:'0-9' to:'A'
                              complement:false squashDuplicates:false

     'abcdefghijkl1234567890' copyTransliterating:'0-9' to:'A'
                              complement:false squashDuplicates:true

     'abcdefghijkl1234567890' copyTransliterating:'0-9' to:'*'
                              complement:false squashDuplicates:false

     'abcdefghijkl1234567890' copyTransliterating:'0-9' to:'*'
                              complement:true squashDuplicates:false

     'abcdefghijkl1234567890' copyTransliterating:'a-zA-Z' to:' '
                              complement:true squashDuplicates:false

     'abcdefghijkl1234567890' copyTransliterating:'a-zA-Z' to:' '
                              complement:false squashDuplicates:false

     - delete all a-zA-Z
     'abcdefghijkl1234567890abcdefghijkl' copyTransliterating:'a-zA-Z' to:''
                              complement:false squashDuplicates:false            

     - delete all except a-zA-Z
     'abcdefghijkl1234567890abcdefghijkl' copyTransliterating:'a-zA-Z' to:''
                              complement:true squashDuplicates:false  

     - squash multiple spaces
     'abcd   efghij kl112234  5678999 0abbb cccc deeeef ghijkl' copyTransliterating:' ' to:' '
                              complement:false squashDuplicates:true         

     - squash multiple digits
     'abcd   efghij kl112234  5678999 0abbb cccc deeeef ghijkl' copyTransliterating:'0-9' to:'0-9'
                              complement:false squashDuplicates:true         

o  copyTransliterating: oldElements to: newElements rawMap: rawMap complement: complement squashDuplicates: squashDuplicates
return a copy, where elements all transliterated via the given mapping.

The transiteraion works like perl's tr operator, unless rawMap is true;
otherwise, elements from oldElements and newElements are treated without any processing,
which makes this easier to use, if special characters (such as '-', '[' etc. are to be transliterated).

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)

usage example(s):
     'abcdefghijkl1234567890' copyTransliterating:'b-g' to:'B-G'    
     'abcdefghij-kl1234567890' copyTransliterating:'b\-g' to:'B+G'               
     'abcdefghijkl1234567890' copyTransliterating:'69' to:'96'      
     'abcdefghijkl1234567890' copyTransliterating:'a' to:'b'        
     'abcdefghijkl1234567890' copyTransliterating:'aeiou' to:'AEIOU'  
     'abcdefghijkl1234567890' copyTransliterating:'aeiou' to:'*'  
     'abcdefghijkl1234567890' copyTransliterating:'0-9' to:'QERTYUIOPX'   
     'abcdefghijkl1234567890' copyTransliterating:'a-z' to:'b-za'  
     'abcdefghijkl1234567890' copyTransliterating:'a-z' to:'c-zab'  
     'abcdefghijkl1234567890' copyTransliterating:'a-z' to:'z-a'  

     'abcdefghijkl12345678--90' copyTransliterating:'-abcz' to:'z-' rawMap:true complement:false squashDuplicates:false  

     'abcdefghijkl1234567890' copyTransliterating:'0-9' to:'A'
                              complement:false squashDuplicates:false

     'abcdefghijkl1234567890' copyTransliterating:'0-9' to:'A'
                              complement:false squashDuplicates:true

     'abcdefghijkl1234567890' copyTransliterating:'0-9' to:'*'
                              complement:false squashDuplicates:false

     'abcdefghijkl1234567890' copyTransliterating:'0-9' to:'*'
                              complement:true squashDuplicates:false

     'abcdefghijkl1234567890' copyTransliterating:'a-zA-Z' to:' '
                              complement:true squashDuplicates:false

     'abcdefghijkl1234567890' copyTransliterating:'a-zA-Z' to:' '
                              complement:false squashDuplicates:false

     - delete all a-zA-Z
     'abcdefghijkl1234567890abcdefghijkl' copyTransliterating:'a-zA-Z' to:''
                              complement:false squashDuplicates:false            

     - delete all except a-zA-Z
     'abcdefghijkl1234567890abcdefghijkl' copyTransliterating:'a-zA-Z' to:''
                              complement:true squashDuplicates:false  

     - squash multiple spaces
     'abcd   efghij kl112234  5678999 0abbb cccc deeeef ghijkl' copyTransliterating:' ' to:' '
                              complement:false squashDuplicates:true         

     - squash multiple digits
     'abcd   efghij kl112234  5678999 0abbb cccc deeeef ghijkl' copyTransliterating:'0-9' to:'0-9'
                              complement:false squashDuplicates:true         

o  copyTransliteratingRaw: oldElements to: newElements
return a copy, where elements all transliterated via the given mapping
usage example(s):
     'abcdefghijkl1234567890' copyTransliteratingRaw:'abc' to:'*'  
     'abcdefghijkl---1234567890' copyTransliteratingRaw:'-' to:'*'      

o  copyUpThrough: element
return a new collection consisting of the receiver elements
up-to (and including) the first occurrence of element;
or to the end, if element is not included
usage example(s):
     #($a $b $c $d $e $f $g) copyUpThrough:$d
     '1234567890' copyUpThrough:$5
     '1234567890' copyUpThrough:$a
     '1234567890' copyUpThrough:$1
     '123456789' copyUpThrough:$0

o  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
usage example(s):
     #($a $b $c $d $e $f $g) copyUpTo:$d
     '1234567890' copyUpTo:$5
     '1234567890' copyUpTo:$a
     '1234567890' copyUpTo:$1
     '123456789' copyUpTo:$0

o  copyWith: newElement
return a new collection containing the receiver's elements
and the single new element, newElement.
This is different from concatentation, which expects another collection
as argument, but equivalent to copy-and-addLast.
usage example(s):
     #(1 2 3 4 5) copyWith:$a
     'abcdefg' copyWith:$h
     'abcdefg' copyWith:'123'   -- will fail: string cannot be stored into string
     'abcdefg' copyWith:1       -- will fail: integer cannot be stored into string

o  copyWith: newElement insertedAfterIndex: index
return a new collection with newElement inserted after index.
With a 0 index, newElement is prepended;
if index is my size, it is appended.
The receiver remains unchanged
usage example(s):
     #(1 2 3 4 5 6 7 8 9 0 1 2 3 4) copyWith:#a insertedAfterIndex:1  
     #(1 2 3 4 5 6 7 8 9 0 1 2 3 4) copyWith:#a insertedAfterIndex:0
     #(1 2 3 4 5 6 7 8 9 0 1 2 3 4) copyWith:#a insertedAfterIndex:14
     #(1 2 3 4 5 6 7 8 9 0 1 2 3 4) copyWith:#a insertedAfterIndex:15  --> error

o  copyWith: newElement insertedBeforeIndex: index
return a new collection with newElement inserted after index.
With a 1 index, newElement is prepended;
if index is my size, it is appended.
The receiver remains unchanged
usage example(s):
     #(1 2 3 4 5 6 7 8 9 0 1 2 3 4) copyWith:#a insertedBeforeIndex:1  
     #(1 2 3 4 5 6 7 8 9 0 1 2 3 4) copyWith:#a insertedBeforeIndex:0  --> error
     #(1 2 3 4 5 6 7 8 9 0 1 2 3 4) copyWith:#a insertedBeforeIndex:14
     #(1 2 3 4 5 6 7 8 9 0 1 2 3 4) copyWith:#a insertedBeforeIndex:15 
     #(1 2 3 4 5 6 7 8 9 0 1 2 3 4) copyWith:#a insertedBeforeIndex:16  --> error

o  copyWithAll: aCollection insertedAfterIndex: index
return a new collection with aCollection sliced in after index.
With a 0 index, aString is prepended;
if index is my size, it is appended.
The receiver remains unchanged
usage example(s):
     #(1 2 3 4 5 6 7 8 9 0 1 2 3 4) copyWithAll:#(a b c) insertedAfterIndex:1  
     #(1 2 3 4 5 6 7 8 9 0 1 2 3 4) copyWithAll:#(a b c) insertedAfterIndex:0
     #(1 2 3 4 5 6 7 8 9 0 1 2 3 4) copyWithAll:#(a b c) insertedAfterIndex:14
     #(1 2 3 4 5 6 7 8 9 0 1 2 3 4) copyWithAll:#(a b c) insertedAfterIndex:15  --> error

o  copyWithAll: aCollection insertedBeforeIndex: index
return a new collection with aCollection sliced in before index.
With a 1 index, aString is prepended;
if index is my size+1, it is appended.
The receiver remains unchanged
usage example(s):
     #(1 2 3 4 5 6 7 8 9 0 1 2 3 4) copyWithAll:#(a b c) insertedBeforeIndex:1  
     #(1 2 3 4 5 6 7 8 9 0 1 2 3 4) copyWithAll:#(a b c) insertedBeforeIndex:0  --> error
     #(1 2 3 4 5 6 7 8 9 0 1 2 3 4) copyWithAll:#(a b c) insertedBeforeIndex:14
     #(1 2 3 4 5 6 7 8 9 0 1 2 3 4) copyWithAll:#(a b c) insertedBeforeIndex:15 
     #(1 2 3 4 5 6 7 8 9 0 1 2 3 4) copyWithAll:#(a b c) insertedBeforeIndex:16  --> error

o  copyWithFirst: newFirstElement
return a new collection containing the receiver's 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.
usage example(s):
     #(1 2 3 4 5) copyWithFirst:$a  
     'abcdefg' copyWithFirst:$h
     'abcdefg' copyWithFirst:'123'   -- will fail: string cannot be stored into string
     'abcdefg' copyWithFirst:1       -- will fail: integer cannot be stored into string

o  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.
usage example(s):
     #($a $b $c $d $e $f $g) copyWithout:$d
     #($a $b $c $d $e $f $g) copyWithout:$a
     #($a $b $c $d $e $f $g) copyWithout:$g
     'abcdefghi' copyWithout:$h
     'abcdefg' copyWithout:$h
     'abcdefabcghi' copyWithout:$a
     'abcdefabcg' copyWithout:$h
     #($a $b $c $a $a $d $e $a $f $g) copyWithout:$a
     #($a $b $c $d $e $f $g) copyWithout:$x
     #(90 80 70 60 50) copyWithout:70
     #(90 80 70 80 60 45 80 50) copyWithout:80

o  copyWithoutFirst: elementToSkip
return a new collection consisting of a copy of the receiver's 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:
usage example(s):
     #($a $b $c $d $e $f $g) copyWithoutFirst:$d
     #($a $b $c $d $e $f $g) copyWithoutFirst:$x
     #(90 80 70 60 50) copyWithoutFirst:70
     #(90 80 70 80 60 45 80 50) copyWithoutFirst:80

o  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.
usage example(s):
     #(#a #b #c 'a' #e #f #g) copyWithoutIdentical:#a
     #(#a #b #c 'a' #e #f #g) copyWithout:#a

o  copyWithoutIndex: omitIndex
return a new collection consisting of receiver's elements
without the argument stored at omitIndex
usage example(s):
     #(1 2 3 4 5 6 7 8 9 0) copyWithoutIndex:3
     'abcdefghijkl' copyWithoutIndex:5

o  copyWithoutIndex: firstIndex toIndex: lastIndex
return a new collection consisting of receiver's elements
without the arguments elements stored from firstIndex to lastIndex
usage example(s):
     #(1 2 3 4 5 6 7 8 9 0) copyWithoutIndex:3 toIndex:5
     'abcdefghijkl' copyWithoutIndex:5 toIndex:5

o  copyWithoutLast: count
return a new collection consisting of the receiver's 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) **

o  repeatedConcatenation: nTimes
return a new collection consisting of nTimes the concatenation of the receiver
usage example(s):
     'hello' repeatedConcatenation:5 
     ' ' repeatedConcatenation:100   
     #[1 2 3] repeatedConcatenation:3
     #(1 2 3) repeatedConcatenation:1
     #(1 2 3) repeatedConcatenation:0

o  restAfter: anElement
return a new collection consisting of the receiver's elements after
(but excluding) anElement.
If anElement is not in the receiver, the returned collection
will be empty.
See also #upTo:.
usage example(s):
     #(1 2 3 4 5 6 7 8 9) upTo:5
     #(1 2 3 4 5 6 7 8 9) restAfter:5
     'hello world' upTo:Character space
     'hello world' restAfter:Character space
     '1234.5678' upTo:$.
     '1234.5678' restAfter:$.

o  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.
usage example(s):
     '    foo    ' trimForWhich:[:ch | ch isSeparator]  
     '           ' trimForWhich:[:ch | ch isSeparator]  
     #(0 0 0 1 2 3 0 0 0) trimForWhich:[:e | e = 0]

o  upTo: anElement
return a new collection consisting of the receiver's 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.
usage example(s):
     #(1 2 3 4 5 6 7 8 9) upTo:5
     'hello world' upTo:Character space
     #(9 8 7 6 5 4 3 2 1) asSortedCollection upTo:5
     '1234.5678' upTo:$.
     '1234'      upTo:$.
     '.'      upTo:$.


     raises an error:

     (Dictionary new
        at:#foo put:'foo';
        at:#bar put:'bar';
        at:#baz put:'baz';
        yourself) upTo:#bar

o  upTo: anElement count: count
return a new collection consisting of the receiver's 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
usage example(s):
     'hello1_hello2_hello3' upTo:$_ count:  2     returns first two 'hellos'
     'hello1_hello2_hello3' upTo:$_ count: -1     returns last 'hello'
     'hello1_hello2_hello3' upTo:$_ count: 0      returns first 'hello1'
     'hello1_hello2_hello3' upTo:$_ count: 1      returns first 'hello1'
     'hello1_hello2_hello3' upTo:$_               same; returns first 'hello1'

o  upToAll: aSubCollection
return a new collection consisting of the receiver's elements upTo
(but excluding) the first occurrence of a subcollection.
If none of aCollectionOfObjects is found in the receiver, the returned collection
will consist of all elements of the receiver.
See also #upTo:
usage example(s):
     'hello world' upToAll:'wo'
     'hello world' upToAll:'bla'
     #(1 2 3 4 5 6 7 8) upToAll:#(5)
     #(1 2 3 4 5 6 7 8) upToAll:#()
     #(1 3 4 2 3 4 5 6 7 8) upToAll:#(3 4 5 6)
     #(1 3 4 2 3 4 5 6 7 8) upToAll:#(3 5 6)

o  upToAny: aCollectionOfObjects
return a new collection consisting of the receiver's 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:
usage example(s):
     'hello world' upToAny:#($/ $:)
     'hello:world' upToAny:#($/ $:)
     'hello/world' upToAny:#($/ $:)

o  upToElementForWhich: aBlock
return a new collection consisting of the receiver's elements
upTo (but excluding) the first element for which aBlock returns true.
If none is found, a copy of whole collection is returned.
See also #upTo:
usage example(s):
     'hello world' upToElementForWhich:[:c | c isSeparator]
     'hello:world' upToElementForWhich:[:c | c isSeparator]

o  upToMatching: aBlock
Return the next elements up to but not including the next element
for which aBlock returns true.
If none is found, a copy of whole collection is returned.
usage example(s):
     #(1 2 3 4 5 6 7 8 9) upToMatching:[:el | el even and:[el >= 5]]
     'hello world' upToMatching:[:ch | ch isSeparator]

o  upToSeparator
Return the next elements up to but not including the next separator.
The next read will return the separator.
If no separator is encountered, the contents up to the end is returned.
The elements are supposed to understand #isSeparator
(i.e. the receiver is supposed to be a character-stream).
usage example(s):
     'hello world' upToSeparator

o  withoutLeadingForWhich: aCheckBlock
return a copy of myself without leading elements 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.
usage example(s):
     '****foo****' withoutLeadingForWhich:[:ch | ch isLetter not]     
     #( 0 0 0 1 2 3 4 0 0 0) withoutLeadingForWhich:[:e | e = 0]     

o  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.
usage example(s):
     '    foo....' withoutTrailingForWhich:[:ch | ch isLetter not]. 
     #( 0 0 0 1 2 3 4 0 0 0) withoutTrailingForWhich:[:e | e = 0]     

enumerating
o  collect: aBlock
evaluate the argument, aBlock for every element in the collection
and return a collection of the results
usage example(s):
     #(one two three four five six) collect:[:element | element asUppercase]
     #(1 2 3 4 5 6 7 8 9) collect:[:element | element factorial]
     (1 to:9) collect:[:element | element * element]

o  do: aBlock
evaluate the argument, aBlock for every element in the collection in
sequence order.
usage example(s):
     #(one two three four five six) do:[:element | Transcript showCR:element]

o  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.
usage example(s):
     #(one two three four five six)
        do:[:each | Transcript show:each]
        separatedBy:[Transcript show:' , ']

o  from: start collect: aBlock
evaluate the argument, aBlock for the elements starting at start
to the end and return a collection of the results
usage example(s):
     #(one two three four five six)
	from:2
	collect:[:element | element asUppercase]

o  from: start conform: aOneArgBlock
return true, if the elements starting at the start-index conform to some condition.
I.e. return false, if aBlock returns false for any of those elements;
true otherwise.

o  from: startIndex do: aBlock
evaluate the argument, aBlock for the elements starting with the
element at startIndex to the end.
usage example(s):
     #(one two three four five six)
	from:3
	do:[:element | Transcript showCR:element]

o  from: startIndex doWithExit: aBlock
evaluate the argument, aBlock for the elements starting with the
element at startIndex to the end. Passes an additional exitBlock as second
argument, which can be used to exit the loop early.
usage example(s):
     #(one two three four five six)
        from:3
        doWithExit:[:element :exit | 
            Transcript showCR:element.
            element = 'four' ifTrue:[ exit value:nil ]
        ]

o  from: startIndex keysAndValuesDo: aBlock
evaluate the argument, aBlock for the elements and indices starting with the
element at startIndex to the end.
usage example(s):
     #(one two three four five six)
	from:3
	keysAndValuesDo:[:element :idx | Transcript showCR:(idx -> element) ]

o  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
usage example(s):
     #(one two three four five six seven eight nine ten)
	from:2
	to:10
	by:2
	do:[:element | Transcript showCR:element]

o  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
usage example(s):
     #(one two three four five six)
	from:2
	to:4
	collect:[:element | element asUppercase]

o  from: start to: end conform: aOneArgBlock
return true, if the elements from start-index to end-index conform to some condition.
I.e. return false, if aBlock returns false for any of those elements;
true otherwise.
usage example(s):
     #(1 2 3 4 5) from:2 to:2 conform:[:el | el even]     
     #(1 2 2 4 5) from:2 to:4 conform:[:el | el even]               
     #(1 2 2 4 5) from:2 to:5 conform:[:el | el even]               
     #(2 4 6 8 10) conform:[:el | el even]    

o  from: index1 to: index2 do: aBlock
evaluate the argument, aBlock for the elements with index index1 to
index2 in the collection
usage example(s):
     #(one two three four five six)
        from:3 to:5 do:[:element | Transcript showCR:element]

o  from: index1 to: index2 doWithExit: aBlock
evaluate the argument, aBlock for the elements with index index1 to
index2 in the collection. Pass an additional exitBlock as second argument,
which can be used to exit the loop early.
usage example(s):
     #(one two three four five six)
        from:3 to:5 doWithExit:[:element :exit | 
            Transcript showCR:element.
            element = 'four' ifTrue:[ exit value:nil].
        ]

o  from: index1 to: index2 doWithIndex: aBlock
Squeak/V'Age compatibility;
like keysAndValuesDo:, but passes the index as second argument.

o  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.
usage example(s):
     #(one two three four five six)
	from:3
	to:5
	keysAndValuesDo:[:idx :element | Transcript show:idx; space; showCR:element]

o  from: index1 to: index2 orEndDo: aBlock
evaluate the argument, aBlock for the elements with index index1 to
index2 or the end (whichever comes first) in the collection
usage example(s):
     #(one two three four five six)
        from:3 to:10 orEndDo:[:element | Transcript showCR:element]

o  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
usage example(s):
     #(one two three four five six)
	from:3
	to:5
	reverseDo:[:element | Transcript showCR:element]

o  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.
usage example(s):
     #(faba one two three four five six)
        from:2 to:5 select:[:element | element startsWith:'f']

o  from: startArg to: stopArg 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.
usage example(s):
     #(one two three four five six) 
        from:2 to:5
        with:(1 to:10)
        doWithIndex:[:el1 :el2 :idx| Transcript show:idx; space; show:el1; space; showCR:el2]

o  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.
This is similar to slicesOf:collect:, but here, an N-arg block is expected.
usage example(s):
for groups of 2, this is the same as:
     #(1 one 2 two 3 three 4 four 5 five 6 six)
         pairWiseCollect:[:num :sym | num->sym]

     #(1 one 2 two 3 three 4 four 5 five 6 six)
         inGroupsOf:2 collect:[:num :sym | num->sym]

     #( 1 2 3 4 5    6 7 8 9 10   11 12 13 14 15   16 17 18 19 20 )
         inGroupsOf:5 collect:[:a :b :c :d :e | Array with:a with:b with:c with:d with:e]

o  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.
This is similar to slicesOf:do:, but here, an N-arg block is expected.
usage example(s):
for groups of 2, this is the same as:
     #(1 one 2 two 3 three 4 four 5 five 6 six)
         pairWiseDo:[:num :sym | Transcript show:num; show:' is: '; showCR:sym]

     #(1 one 2 two 3 three 4 four 5 five 6 six)
         inGroupsOf:2 do:[:num :sym | Transcript show:num; show:' is: '; showCR:sym]

     #( 1 2 3 4 5    6 7 8 9 10   11 12 13 14 15   16 17 18 19 20 )
         inGroupsOf:5 do:[:a :b :c :d :e | Transcript show:a;space;show:b;space;show:c;space;show:d;space;showCR:e]

o  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.
usage example(s):
     #(one two three four five six)
        keysAndValuesCollect:[:key :element |
                            key even ifTrue:element ifFalse:[element asUppercase]]


     |d|

     d := Dictionary new.
     d at:'a' put:'A'.
     d at:'b' put:'B'.
     d at:'c' put:'C'.
     d at:'d' put:'D'.
     d at:'e' put:'E'.
     d keysAndValuesCollect:[:key :element |
                            key first codePoint even
                                ifTrue:element
                                ifFalse:[element asLowercase]]

o  keysAndValuesDo: aTwoArgBlock
evaluate the argument, aBlock for every element in the collection,
passing both index and element as arguments.
usage example(s):
     #(one two three four five six)
        keysAndValuesDo:[:key :element |
                            Transcript show:key; space; showCR:element
                        ]

o  keysAndValuesReverseDo: aTwoArgBlock
evaluate the argument, aBlock in reverse order, for every element
in the collection, passing both index and element as arguments.
usage example(s):
     #(one two three four five six)
	keysAndValuesReverseDo:[:key :element |
				    Transcript show:key; space; showCR:element
			       ]

o  keysDo: aBlock
evaluate the argument, aBlock for every key in the collection.
That is: enumerate the indices.
Here mostly for protocol compatibility.
usage example(s):
     #(one two three four five six)
        keysDo:[:key | Transcript show:key; space; showCR:element
     ]

o  nonNilElementsDo: aBlock
evaluate the argument, aBlock for every non-nil element in the collection.
usage example(s):
     #(one nil three nil five nil seven) nonNilElementsDo:[:element | Transcript showCR:element]

o  overlappingPairsCollect: aTwoArgBlock
Answer the result of evaluating aBlock with all of the overlapping pairs of my elements.
Returns an array, because the block may return any object
(eg, if applied to a string, the returned collection could contain anything)
usage example(s):
     #(1 2 3 4) overlappingPairsCollect: [:a :b | a->b]

     'hello world how nice' overlappingPairsCollect: [:a :b | a,b]

     (('hello world aa bb' overlappingPairsCollect: [:a :b | a,b]) 
        asBag select:[:p | p asSet size = 1])
             valuesSortedByCounts first

o  overlappingPairsDo: aTwoArgBlock
Evaluate aBlock with all of the overlapping pairs of my elements.
usage example(s):
     #(1 2 3 4) overlappingPairsDo: [:a :b | Transcript show:a; show:' '; showCR:b]

o  overlappingPairsWithIndexDo: aThreeArgBlock
Evaluate aBlock with all of the overlapping pairs of my elements plus the index.
usage example(s):
     #(1 2 3 4) overlappingPairsWithIndexDo: [:a :b :idx | 
                    Transcript show:idx; show:': '; show:a; show:' '; showCR:b
                ]

o  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.
usage example(s):
     #(1 one 2 two 3 three 4 four 5 five 6 six)
         pairWiseCollect:[:num :sym | sym->num]


     #(1 1  1 2  1 3  1 4  1 5)
         pairWiseCollect:[:x :y | x@y]

o  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 pairsDo:.
but the Squeak-pairsDo: does the same as our pairWiseDo:
(sigh: but we were first, so they should have adapted...)
usage example(s):
     #(1 one 2 two 3 three 4 four 5 five 6 six)
         pairWiseDo:[:num :sym | Transcript show:num; show:' is: '; showCR:sym]


     #(1 1  1 2  1 3  1 4  1 5)
         pairWiseDo:[:x :y | Transcript showCR:x@y]

o  reverseDo: aBlock
evaluate the argument, aBlock for every element in the collection
in reverse order
usage example(s):
     #(one two three four five six) reverseDo:[:element | Transcript showCR:element]

o  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
usage example(s):
     #(one two three four five six) select:[:element | element startsWith:'f']
     #(1 2 3 4 5 6 7 8 9) select:[:element | element odd]
     #() select:[:element | element odd]
     (#(17 12 1 98 51) asSortedCollection:[:a :b | b < a]) select:[:element | element odd]
     (1 to:9) select:[:element | element odd]
     (Smalltalk allClasses) select:[:class | class name startsWith:'S']

o  slicesOf: n collect: aOneArgBlock
evaluate the argument, aOneArg for every slice of n elements of the collection,
and collect the results as instances of targetContainerClass.
The block is called with n element subcollections for groups of n consecutive elements in the receiver.
If the number of elements in the receiver is not a multiple of n, the last block evaluation will
get a short slice as argument.
This is similar to inGroupsOf:collect:, but here, a 1-arg block is expected.

o  slicesOf: n do: aOneArgBlock
evaluate the argument, aOneArg for every slice of n elements of the collection.
The block is called with n element subcollections for groups of n consecutive elements in the receiver.
If the number of elements in the receiver is not a multiple of n, the last block evaluation will
get a short slice as argument.
This is similar to inGroupsOf:do:, but here, a 1-arg block is expected.

o  with: aCollection andDefault: defaultElement do: aTwoArgBlock
evaluate the argument, aBlock for successive elements from
each the receiver and the argument, aCollection.
If the receiver has more elements than the argument, use defaultElement
for remaining evaluations.
The third argument, aTwoArgBlock must be a two-argument block.
This method fails if neither the receiver nor aCollection is
a sequenceable collection (i.e. implements numeric key access)
usage example(s):
     #(1 2 3) with:#(one two) andDefault:99 do:[:num :sym |
        Transcript showCR:(num->sym)
     ]

     #() with:#(one two) andDefault:99 do:[:num :sym |
        Transcript showCR:(num->sym)
     ]

     'this example does not really make sense'
     #(1 2 3) with:#(one two) asSet andDefault:99 do:[:num :sym |
        Transcript showCR:(num->sym)
     ]

o  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
and the sizes must be the same (this is a new check!).
usage example(s):
     #(one two three four five six)
        with:(1 to:6)
        do:[:el1 :el2 | Transcript show:el1; space; showCR:el2]

o  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.
and the sizes must be the same (this is a new check!).
usage example(s):
     #(one two three four five six)
        with:(1 to:10)
        doWithIndex:[:el1 :el2 :idx| Transcript show:idx; space; show:el1; space; showCR:el2]

o  with: collection2 with: collection3 do: aThreeArgBlock
evaluate the argument, aBlock for successive elements from
each the receiver and the collection arguments.
The last argument, aBlock must be a three-argument block.
The collection arguments must implement access via a numeric key
and the sizes must be the same.
usage example(s):
     #(one two three four five six)
        with:(1 to:6)
        with:(100 to:600 by:100)
        do:[:el1 :el2 :el3 | Transcript show:el1; space; show:el2; space; showCR:el3]

filling & replacing
o  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.
usage example(s):
     (Array new:10) atAllPut:1
     (String new:10) atAllPut:$a

o  clearContents
to be used with cryptographic keys, to wipe their contents after use

o  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.
usage example(s):
     #(1 2 3 4 5 6 7 8 9 0) from:3 to:6 put:$X
     'abcdefghijkl' from:3 to:6 put:$X

o  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) **

o  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) **

o  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.
usage example(s):
     '123123abc123' replaceAll:$1 with:$*
     #(1 2 3 4 1 2 3 4) copy replaceAll:1 with:'one'

o  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.
usage example(s):
     '123123abc123' replaceAll:$1 with:$*
     '123123abc123' replaceAll:$1 with:$* from:1 to:6
     #(1 2 3 4 1 2 3 4) replaceAll:1 with:'one' from:1 to:4

o  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.

o  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.

o  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.
usage example(s):
     #(1 2 3 4 1.0 2.0 3.0 4.0) copy replaceAll:1 with:'one'
     #(1 2 3 4 1.0 2.0 3.0 4.0) copy replaceAllIdentical:1 with:'one'

o  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.
usage example(s):
     #(1 2 3 4 1 2 3 4) replaceAll:1 with:'one' from:1 to:8
     #(1 2 3 4 1.0 2.0 3.0 4.0) replaceAll:1 with:'one' from:1 to:8
     #(1 2 3 4 1.0 2.0 3.0 4.0) replaceAllIdentical:1 with:'one' from:1 to:8

o  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) **

o  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) **

o  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.
usage example(s):
     #(1 2 3 4 5 6 7 1 2 3 4 5 6 7) copy replaceAny:#(1 3 5 9) with:99
     'abcdefgabcdefg' copy replaceAny:'abx' with:$_  

o  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.
usage example(s):
     '123123abc123' replaceAny:#($1 $2) with:$* from:1 to:6
     #('foo' 'bar' 'foo' 'baz' foo 1 2 3) replaceAny:#(foo 1) with:'*'

o  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.
usage example(s):
     '1234567890' replaceFrom:5 count:3 with:'abcdef'
     #($a $b $c $d $e) replaceFrom:2 count:2 with:'12345'

o  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.
usage example(s):
     '1234567890' replaceFrom:5 count:3 with:'abcdef' startingAt:3
     #($a $b $c $d $e) replaceFrom:2 count:3 with:'12345' startingAt:4
     #($a $b $c $d $e) asOrderedCollection replaceFrom:2 count:3 with:'12345' startingAt:4

o  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.
usage example(s):
     '1234567890' replaceFrom:5 to:7 with:'abcdef'
     #($a $b $c $d $e) replaceFrom:2 to:3 with:'12345'

o  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.
usage example(s):
     '1234567890' replaceFrom:5 to:7 with:'abcdef' startingAt:3
     #($a $b $c $d $e) replaceFrom:2 to:3 with:'12345' startingAt:4
     #($a $b $c $d $e) asOrderedCollection replaceFrom:2 to:3 with:'12345' startingAt:4

     |c|
     c := #($a $b $c $d $e) asOrderedCollection.
     c replaceFrom:2 to:3 with:c startingAt:4

     |c|
     c := #($a $b $c $d $e) asOrderedCollection.
     c replaceFrom:4 to:5 with:c startingAt:2

o  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.
usage example(s):
     '1234567890' replaceFrom:5 with:'abc'
     #($a $b $c $d $e) replaceFrom:2 with:'123'

o  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.
usage example(s):
     '1234567890' replaceFrom:5 with:'abcdef' startingAt:3
     #($a $b $c $d $e) replaceFrom:2 with:'12345' startingAt:4

o  replaceLast: count with: replacementCollection
replace the last count elements elements in the receiver
with elements taken from replacementCollection.
Return the receiver.

Notice: This operation modifies the receiver, NOT a copy;
therefore the change may affect all others referencing the receiver.
usage example(s):
     '1234567890' replaceLast:5 with:'abcdef'

o  replaceLast: count with: replacementCollection startingAt: repStartIndex
replace the last count elements elements in the receiver
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.
usage example(s):
     '1234567890' replaceLast:5 with:'abcdef' startingAt:1

o  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.

inspecting
o  inspector2TabGraph
( an extension from the stx:libtool package )
an extra tab showing the graph

o  inspector2Tabs
( an extension from the stx:libtool package )
add a graph-tab; but only if all my values are numerical

obsolete
o  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) **

o  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) **

o  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

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

o  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

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

o  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

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

o  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

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

padded copying
o  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 receiver's size is equal or greater than the length argument,
the original receiver is returned unchanged.
usage example(s):
     'foo' leftPaddedTo:10 with:$.
     'fooBar' leftPaddedTo:5 with:$.
     123 printString leftPaddedTo:10 with:$.
     (' ' , 123 printString) leftPaddedTo:10 with:$.
     (Float pi printString) leftPaddedTo:15 with:(Character space)
     (Float pi printString) leftPaddedTo:15 with:$-
     (' ' , Float pi class name) leftPaddedTo:15 with:$.
     #[1 2 3 4] leftPaddedTo:6 with:0
     #[1 2 3 4] leftPaddedTo:10 with:99
     #(1 2 3 4) leftPaddedTo:8 with:nil

o  paddedTo: newSize with: padElement
return a new collection consisting of the receiver's elements,
plus pad elements up to length.
If the receiver's size is equal or greater than the length argument,
the original receiver is returned unchanged.
usage example(s):
     'foo' paddedTo:10 with:$.
     123 printString paddedTo:10 with:$*
     (Float pi printString) paddedTo:15 with:(Character space)
     (Float pi printString) paddedTo:15 with:$-
     (Float pi class name , ' ') paddedTo:15 with:$.
     #[1 2 3 4] paddedTo:6 with:0
     #[1 2 3 4] paddedTo:10 with:99
     #(1 2 3 4) paddedTo:8 with:nil

o  paddedToMultipleOf: sizeModulu with: padElement
#[] paddedToMultipleOf:3 with:0
#[1] paddedToMultipleOf:3 with:0
#[1 2] paddedToMultipleOf:3 with:0
#[1 2 3] paddedToMultipleOf:3 with:0
#[1 2 3 4] paddedToMultipleOf:3 with:0

#() paddedToMultipleOf:3 with:nil
#(1) paddedToMultipleOf:3 with:nil
#(1 2) paddedToMultipleOf:3 with:nil
#(1 2 3) paddedToMultipleOf:3 with:nil
#(1 2 3 4) paddedToMultipleOf:3 with:nil

'' paddedToMultipleOf:3 with:Character space
'a' paddedToMultipleOf:3 with:Character space
'ab' paddedToMultipleOf:3 with:Character space
'abc' paddedToMultipleOf:3 with:Character space
'abcd' paddedToMultipleOf:3 with:Character space

printing & storing
o  printOn: aStream withSeparator: aSeparatorStringOrCharacter
#[1 2 3 4 10 17] printOn:Transcript withSeparator:$.

o  printStringWithSeparator: aSeparatorStringOrCharacter
#[1 2 3 4 10 17] printStringWithSeparator:$.

private-sorting helpers
o  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.

o  mergeSortFrom: first to: last by: aBlock
Private! Split the range to be sorted in half, sort each half, and merge the two half-ranges into dst.

o  quickSortFrom: inBegin to: inEnd
actual quicksort worker for sort-message.
Simulates recursion in a stack, to avoid recursion overflow
with degenerated collections.

The algorithm has been extended to introSort, which is quickSort with fallBack
when we find out, that we have a worst case quick sort with O(n*n).

Use #< for element comparisons, since this is the (fastest) base
method in Magnitude, and the others may be defined by sending #<.

o  quickSortFrom: inBegin to: inEnd sortBlock: sortBlock
actual quicksort worker for sort-message.
Simulates recursion in a stack, to avoid recursion overflow
with degenerated collections.

The algorithm has been extended to introSort, which is quickSort with fallBack
when we find out, that we have a worst case quick sort with O(n*n).

Use sortBlock for element comparisons.

o  quickSortFrom: inBegin to: inEnd sortBlock: sortBlock policy: policy
actual quicksort worker for sort-message.
Simulates recursion in a stack, to avoid recursion overflow
with degenerated collections.

Use sortBlock for element comparisons.

o  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.

Use sortBlock for element comparisons.

o  quickSortFrom: inBegin to: inEnd with: aCollection
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 #<.

queries
o  firstIndex
return the first elements index

o  isSequenceable
return true, if the receiver is some kind of sequenceableCollection

o  isSorted
return true. if my elements are sorted (already)
usage example(s):
     #(1 2 3 5 10 100) isSorted
     #(1 2 3 5 100 10) isSorted

o  isSortedBy: aBlock
return true, if my elements are sorted (already) by the given criterion (sortBlock)
usage example(s):
     #(1 2 3 5 10 100) isSortedBy:[:a :b | a <= b]
     #(1 2 3 5 100 10) isSortedBy:[:a :b | a <= b]
     #(100 10 5 3 2 1) isSortedBy:[:a :b | a <= b]
     #(100 10 5 3 2 1) isSortedBy:[:a :b | a > b]

o  keys
return a collection with all keys in the Smalltalk dictionary

o  lastIndex
return the last elements index

o  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 **

o  speciesForSubcollection
answer the class, when splitting instances into subcollections

o  zeroIndex
return the index value which is returned when nothing
is found in an indexOf* kind of search.
ST-compatibility

searching
o  detect: aBlock startingAt: startIndex
find the first element, for which evaluation of the argument, aBlock returns true.
Start the search at startIndex.
If none does so, report an error
usage example(s):
     #(11 12 13 14) detect:[:n | n odd] startingAt:3
     #(12 14 16 18) detect:[:n | n odd] startingAt:3

o  detect: aBlock startingAt: startIndex ifNone: exceptionBlock
find the first element, for which evaluation of the argument, aBlock returns true.
Start the search at startIndex.
If none does so, return the evaluation of exceptionBlock
usage example(s):
     #(11 12 13 14) detect:[:n | n odd] startingAt:3 ifNone:['sorry']
     #(12 14 16 18) detect:[:n | n odd] startingAt:3 ifNone:['sorry']

o  detectLast: aBlock
find the last element, for which evaluation of the argument, aBlock returns true.
If none does so, report an error
usage example(s):
     #(11 12 13 14) detectLast:[:n | n odd] 
     #(12 14 16 18) detectLast:[:n | n odd] ifNone:'sorry' 

o  detectLast: aBlock startingAt: startIndex
find the last element, for which evaluation of the argument, aBlock returns true.
Start the backward search at startIndex.
If none does so, report an error
usage example(s):
     #(11 12 13 14) detectLast:[:n | n odd] startingAt:3
     #(12 14 16 18) detectLast:[:n | n odd] startingAt:3

o  detectLast: aBlock startingAt: startIndex ifNone: exceptionBlock
find the last element, for which evaluation of the argument, aBlock returns true.
Start the backward search at startIndex.
If none does so, return the evaluation of exceptionBlock
usage example(s):
     #(11 12 13 14) detectLast:[:n | n odd] startingAt:3 ifNone:['sorry']
     #(12 14 16 18) detectLast:[:n | n odd] startingAt:3 ifNone:['sorry']

o  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.
usage example(s):
     #(1 2 3 4 5 6) findFirst:[:x | (x >= 3)] ifNone:0
     #(1 2 3 4 5 6) findFirst:[:x | (x >= 7)] ifNone:nil

o  findFirst: aBlock startingAt: startIndex
find the first element, for which evaluation of the argument, aBlock returns true.
Start the search at startIndex.
Return its index or 0 if none detected.
This is much like #detect:startingAt:, however, here an INDEX is returned,
whereas #detect: returns the element.
usage example(s):
     #(1 4 3 4 3 6) findFirst:[:x | (x > 3)] startingAt:4    
     'one.two.three' findFirst:[:c | (c == $.)] startingAt:5 
     'one.two.three' findFirst:[:c | (c == $.)] startingAt:9 

o  findFirst: aBlock startingAt: startIndex ifNone: exceptionalValue
find the first element, for which evaluation of the argument, aBlock returns true.
Start the search at startIndex.
Return its index or 0 if none detected.
This is much like #detect:startingAt:, however, here an INDEX is returned,
whereas #detect: returns the element.
usage example(s):
     #(1 4 3 4 3 6) findFirst:[:x | (x > 3)] startingAt:4
     'one.two.three' findFirst:[:c | (c == $.)] startingAt:5
     'one.two.three' findFirst:[:c | (c == $.)] startingAt:10
     'one.two.three' findFirst:[:c | (c == $.)] startingAt:10 ifNone:nil

o  findLast: aBlock ifNone: exceptionalValue
find the last element, for which evaluation of the argument, aBlock returns true.
Return its index or the value from exceptionValue if none detected.

o  findLast: aBlock startingAt: startIndex
find the last element, for which evaluation of the argument, aBlock returns true.
Start the backward search at startIndex.
Return its index or 0 if none detected.
usage example(s):
     #(1 99 3 99 5 6) findLast:[:x | (x == 99)] startingAt:3
     'one.two.three' findLast:[:c | (c == $.)] startingAt:7

o  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.
usage example(s):
     #(1 99 3 99 5 6) findLast:[:x | (x == 99)] startingAt:3
     #(1 99 3 99 3 5 6) findLast:[:x | (x == 3)] startingAt:7 endingAt:6
     #(1 99 3 99 3 5 6) findLast:[:x | (x == 3)] startingAt:7 endingAt:5
     'one.two.three' findLast:[:c | (c == $.)] startingAt:7

o  indexOfSubCollection: aCollection
find a subcollection. If found, return the index; if not found, return 0.
usage example(s):
     #(1 2 3 4 5 6 7) indexOfSubCollection:#()
     #(1 2 3 4 5 6 7) indexOfSubCollection:#(1)
     #(1 2 3 4 5 6 7) indexOfSubCollection:#(1 2 3 4)
     #(1 2 3 4 5 6 7) indexOfSubCollection:#(2 3 5)
     #(1 2 3 2 3 4 5) indexOfSubCollection:#(2 3 4)
     #(1 2 3 4 5 6 7) indexOfSubCollection:#(5 6 7)
     #(1 2 3 4 5 6 7) indexOfSubCollection:#(5 6 8)
     #(1 2 3 4 5 6 7) indexOfSubCollection:#(5 6 7 8)
     'foobarbaz' indexOfSubCollection:'bar'

o  indexOfSubCollection: aCollection ifAbsent: exceptionBlock
find a subcollection. If found, return the index;
if not found, return the result of evaluating exceptionBlock.

o  indexOfSubCollection: aCollection startingAt: startIndex
find a subcollection starting at index.
If found, return the index; if not found, return 0.

o  indexOfSubCollection: aCollection startingAt: startIndex endingAt: endIndex 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
usage example(s):
     #(1 2 3 4 5 6 7) indexOfSubCollection:#()  startingAt:2 endingAt:nil ifAbsent:0
     #(1 2 3 4 5 6 7) indexOfSubCollection:#(1) startingAt:2 endingAt:nil ifAbsent:0
     #(1 2 1 2 1 2 3) indexOfSubCollection:#(1 2 3) startingAt:2 endingAt:nil ifAbsent:0
     #(1 2 1 2 1 2 3) indexOfSubCollection:#(1 2 3) startingAt:2 endingAt:6 ifAbsent:0
     #(1 2 1 2 1 2 3) indexOfSubCollection:#(1 2)   startingAt:2 endingAt:nil ifAbsent:0
     #(1 2 1 2 1 2 3) indexOfSubCollection:#(1 2)   startingAt:3 endingAt:nil ifAbsent:0
     #(1 2 1 2 1 2 3) indexOfSubCollection:#(1 2)   startingAt:4 endingAt:nil ifAbsent:0

o  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
usage example(s):
     #(1 2 3 4 5 6 7) indexOfSubCollection:#()  startingAt:2
     #(1 2 3 4 5 6 7) indexOfSubCollection:#(1) startingAt:2
     #(1 2 1 2 1 2 3) indexOfSubCollection:#(1 2 3) startingAt:2
     #(1 2 1 2 1 2 3) indexOfSubCollection:#(1 2)   startingAt:2
     #(1 2 1 2 1 2 3) indexOfSubCollection:#(1 2)   startingAt:3
     #(1 2 1 2 1 2 3) indexOfSubCollection:#(1 2)   startingAt:4
     #(0 1 2 3 15921909 15921909 15921909 15921909 15921909 15921909 15921909 15921909 15921909 15921909 15921909 15921909) indexOfSubCollection:#(15921909 15921909 15921909 15921909 15921909 15921909)

o  lastIndexOfSubCollection: aCollection
find a subcollection from the end.
If found, return the index; if not found, return 0.

o  lastIndexOfSubCollection: aCollection ifAbsent: exceptionBlock
find a subcollection from the end. If found, return the index;
if not found, return the result of evaluating exceptionBlock.

o  lastIndexOfSubCollection: aCollection startingAt: startIndex
find a subcollection from the end starting at index.
If found, return the index; if not found, return 0.

o  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
usage example(s):
     #(1 2 3 4 5 6 7) lastIndexOfSubCollection:#()  startingAt:2
     #(1 2 3 4 5 6 7) lastIndexOfSubCollection:#(1)
     #(1 2 3 4 5 6 7) lastIndexOfSubCollection:#(1) startingAt:4
     #(1 3 1 2 1 3 3) lastIndexOfSubCollection:#(1 2 3)
     #(1 2 1 2 1 2 3) lastIndexOfSubCollection:#(1 2 3) startingAt:2
     #(1 2 1 2 1 2 3) lastIndexOfSubCollection:#(1 2 3)
     #(1 2 1 2 1 2 3) lastIndexOfSubCollection:#(1 2)
     #(1 2 1 2 1 2 3) lastIndexOfSubCollection:#(1 2)   startingAt:5
     #(1 2 1 2 1 2 3) lastIndexOfSubCollection:#(1 2)   startingAt:4

o  map: values at: key ifAbsent: exceptionValue
the receiver is interpreted as a collection of keys;
find key in the receiver and return the corresponding value
from the valuesCollection argument.
usage example(s):
     #(16 32 128 256 512 1024) 
        map: #('ipc4' 'ipc5' 'ic07' 'ic08' 'ic09' 'ic10')
        at:128 ifAbsent:nil 

     #(16 32 128 256 512 1024) 
        map: #('ipc4' 'ipc5' 'ic07' 'ic08' 'ic09' 'ic10')
        at:64 ifAbsent:nil 

searching-equality
o  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.
usage example(s):
     #(10 20 30 40 50 60 70) includes:99
     #(10 20 30 40 50 60 70) includes:40
     #(10 20 30 40 50 60 70) includes:40.0

o  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).
usage example(s):
     #(10 20 30 40 50 60 70) indexOf:40
     #(10 20 30 40 50 60 70) indexOf:40.0

o  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).
usage example(s):
     #(10 20 30 40 10 20 30 40) indexOf:40   ifAbsent:['none']
     #(10 20 30 40 10 20 30 40) indexOf:40.0 ifAbsent:['none']
     #(10 20 30 40 10 20 30 40) indexOf:35   ifAbsent:['none']

o  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.
The comparison is done using =
(i.e. equality test - not identity test).

o  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).
usage example(s):
     #(10 20 30 40 10 20 30 40) indexOf:40   startingAt:5
     #(10 20 30 40 10 20 30 40) indexOf:40.0 startingAt:5

o  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).
usage example(s):
     #(10 20 30 40 10 20 30 40) indexOf:40   startingAt:3 endingAt:99
     #(10 20 30 40 10 20 30 40) indexOf:40   startingAt:3 endingAt:5
     #(10 20 30 40 10 20 30 40) indexOf:40   startingAt:1 endingAt:3
     #(10 20 30 40 10 20 30 40) indexOf:40.0 startingAt:5

o  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).
usage example(s):
     #(10 20 30 40 10 20 30 40) indexOf:40   startingAt:5 ifAbsent:['none']
     #(10 20 30 40 10 20 30 40) indexOf:40.0 startingAt:5 ifAbsent:['none']
     #(10 20 30 40 10 20 30 40) indexOf:35   startingAt:5 ifAbsent:['none']

o  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).
usage example(s):
     #(10 20 30 40 50 60 70) indexOfAny:#(40 30 50)
     #(10 20 30 40 50 60 70) indexOfAny:#(40.0 30.0 50)

o  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).
usage example(s):
     #(10 20 30 40 10 20 30 40) indexOfAny:#(40 50 30) startingAt:5
     #(10 20 30 40 10 20 30 40) indexOfAny:#(40.0 50 30.0) startingAt:5

o  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).
usage example(s):
     #(10 20 30 40 10 20 30 40) indexOfAny:#(40 50 30) startingAt:5 ifAbsent:-1
     #(10 20 30 40 10 20 30 40) indexOfAny:#(40.0 50 30.0) startingAt:5 ifAbsent:-1
     #(10 20 30 40 10 20 30 40) indexOfAny:#(99 88 77) startingAt:5 ifAbsent:['oops']

o  indexOfAnyOf: aCollection
squeak compatibility: same as #indexOfAny:
usage example(s):
     #(10 20 30 40 50 60 70) indexOfAnyOf:#(40 30 50)
     #(10 20 30 40 50 60 70) indexOfAnyOf:#(40.0 30.0 50)
     'abcdefg' indexOfAnyOf:(CharacterSet newFrom:'cef')

o  indexOfAnyOf: aCollection startingAt: start
squeak compatibility: same as #indexOfAny:startingAt:
usage example(s):
     #(10 20 30 40 50 60 70) indexOfAnyOf:#(40 30 50)     startingAt:2
     #(10 20 30 40 50 60 70) indexOfAnyOf:#(40.0 30.0 50) startingAt:2

o  indexOfAnyOf: aCollection startingAt: start ifAbsent: exceptionBlock
squeak compatibility: same as #indexOfAny:startingAt:ifAbsent:

o  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).
usage example(s):
     #(10 20 30 40 50 60 70) lastIndexOf:40
     #(10 20 30 40 50 60 70) lastIndexOf:40.0
     #(10 20 30 40 50 60 70) lastIndexOf:35
     #(10 20 30 40 50 60 70) lastIndexOf:10

o  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).
usage example(s):
     #(10 20 30 40 10 20 30 40) lastIndexOf:40   ifAbsent:['none']
     #(10 20 30 40 10 20 30 40) lastIndexOf:40.0 ifAbsent:['none']
     #(10 20 30 40 10 20 30 40) lastIndexOf:35   ifAbsent:['none']
     #(10 20 30 40 10 20 30 40) lastIndexOf:10   ifAbsent:['none']

o  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).
usage example(s):
     #(10 20 30 40 10 20 30 40) lastIndexOf:40   startingAt:8
     #(10 20 30 40 10 20 30 40) lastIndexOf:40.0 startingAt:8
     #(10 20 30 40 10 20 30 40) lastIndexOf:35   startingAt:8
     #(10 20 30 40 10 20 30 40) lastIndexOf:10   startingAt:8
     #(10 20 30 40 10 20 30 40) lastIndexOf:10   startingAt:4

o  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).
usage example(s):
     #(10 20 30 40 10 20 30 40) lastIndexOf:40   startingAt:8 ifAbsent:['none']
     #(10 20 30 40 10 20 30 40) lastIndexOf:40.0 startingAt:8 ifAbsent:['none']
     #(10 20 30 40 10 20 30 40) lastIndexOf:35   startingAt:8 ifAbsent:['none']
     #(10 20 30 40 10 20 30 40) lastIndexOf:10   startingAt:8 ifAbsent:['none']

o  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).
usage example(s):
     #(10 20 30 40 50 60 70) lastIndexOfAny:#(40 60)
     #(10 20 30 40 50 60 70) lastIndexOfAny:#(40.0 60)
     #(10 20 30 40 50 60 70) lastIndexOfAny:#(35 40)
     #(10 20 30 40 50 60 70) lastIndexOfAny:#(15 35)

o  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).
usage example(s):
     #(10 20 30 40 10 20 30 40) lastIndexOfAny:#(40 60)   startingAt:8
     #(10 20 30 40 10 20 30 40) lastIndexOfAny:#(40 60)   startingAt:7

o  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 0.
The comparison is done using =
(i.e. equality test - not identity test).
usage example(s):
     #(10 20 30 40 10 20 30 40) nextIndexOf:40   from:2 to:6
     #(10 20 30 40 10 20 30 40) nextIndexOf:40.0 from:2 to:6
     #(10 20 30 40 10 20 30 40) nextIndexOf:35   from:2 to:6

o  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).
usage example(s):
     #(10 20 30 40 10 20 30 40) nextIndexOf:40   from:2 to:6 ifAbsent:['none']
     #(10 20 30 40 10 20 30 40) nextIndexOf:40.0 from:2 to:6 ifAbsent:['none']
     #(10 20 30 40 10 20 30 40) nextIndexOf:35   from:2 to:6 ifAbsent:['none']

o  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 0.
The comparison is done using =
(i.e. equality test - not identity test).
usage example(s):
     #(10 20 30 40 10 20 30 40) prevIndexOf:40   from:7 to:2
     #(10 20 30 40 10 20 30 40) prevIndexOf:40.0 from:7 to:2
     #(10 20 30 40 10 20 30 40) prevIndexOf:35   from:7 to:5

o  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).
usage example(s):
     #(10 20 30 40 10 20 30 40) prevIndexOf:40   from:7 to:2 ifAbsent:['none']
     #(10 20 30 40 10 20 30 40) prevIndexOf:40.0 from:7 to:2 ifAbsent:['none']
     #(10 20 30 40 10 20 30 40) prevIndexOf:35   from:7 to:5 ifAbsent:['none']

searching-identity
o  identityIndexOf: anElement
search the collection for anElement using identity compare (i.e. ==);
if found, return the index otherwise return 0.
usage example(s):
     #(10 20 30 40 50 60 70) identityIndexOf:40
     #(10 20 30 40 50 60 70) identityIndexOf:40.0
     #(10 20 30 40 50 60 70) indexOf:40.0

    be careful:

     #(10 20 30 40.0 50 60 70) indexOf:40.0
     #(10 20 30 40.0 50 60 70) identityIndexOf:40.0

o  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.
usage example(s):
     #(10 20 30 40 50 60 70) identityIndexOf:40  ifAbsent:['none']
     #(10 20 30 40 50 60 70) identityIndexOf:35  ifAbsent:['none']
     #(10 20 30 40 50 60 70) identityIndexOf:40.0 ifAbsent:['none']
     #(10 20 30 40 50 60 70) indexOf:40.0         ifAbsent:['none']

o  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.

o  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.
usage example(s):
     #(10 20 30 40 10 20 30 40) identityIndexOf:40 or:30  startingAt:2

o  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.
usage example(s):
     #(10 20 30 40 10 20 30 40) identityIndexOf:40   startingAt:5
     #(10 20 30 40 10 20 30 40) identityIndexOf:40.0 startingAt:5
     #(10 20 30 40 10 20 30 40) indexOf:40.0         startingAt:5

o  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. identity test - not equality test).

o  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. ==).
usage example(s):
     #(10 20 30 40 10) identityIndexOf:10 startingAt:3 ifAbsent:['none']
     #(10 20 30 40 10) identityIndexOf:35 startingAt:3 ifAbsent:['none']

o  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.
usage example(s):
     #(10 20 30 40 50 60 70) includesIdentical:40
     #(10 20 30 40 50 60 70) includesIdentical:40.0
     #(10 20 30 40 50 60 70) includes:40
     #(10 20 30 40 50 60 70) includes:40.0

     be careful:

     #(10 20 30 40.0 50 60 70) includes:40.0
     #(10 20 30 40.0 50 60 70) includesIdentical:40.0

o  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).
usage example(s):
     #(10 20 30 40 50 60 70) lastIdentityIndexOf:40
     #(10 20 30 40 50 60 70) lastIdentityIndexOf:40.0
     #(10 20 30 40 50 60 70) lastIdentityIndexOf:35
     #(10 20 30 40 50 60 70) lastIdentityIndexOf:10

o  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).
usage example(s):
     #(10 20 30 40 10 20 30 40) lastIdentityIndexOf:40   ifAbsent:['none']
     #(10 20 30 40 10 20 30 40) lastIdentityIndexOf:40.0 ifAbsent:['none']
     #(10 20 30 40 10 20 30 40) lastIdentityIndexOf:35   ifAbsent:['none']
     #(10 20 30 40 10 20 30 40) lastIdentityIndexOf:10   ifAbsent:['none']

o  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).
usage example(s):
     #(10 20 30 40 10 20 30 40) lastIdentityIndexOf:40   startingAt:8
     #(10 20 30 40 10 20 30 40) lastIdentityIndexOf:40.0 startingAt:8
     #(10 20 30 40 10 20 30 40) lastIdentityIndexOf:35   startingAt:8
     #(10 20 30 40 10 20 30 40) lastIdentityIndexOf:10   startingAt:8
     #(10 20 30 40 10 20 30 40) lastIdentityIndexOf:10   startingAt:4

o  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).
usage example(s):
     #(10 20 30 40 10 20 30 40) lastIdentityIndexOf:40   startingAt:8 ifAbsent:['none']
     #(10 20 30 40 10 20 30 40) lastIdentityIndexOf:40.0 startingAt:8 ifAbsent:['none']
     #(10 20 30 40 10 20 30 40) lastIdentityIndexOf:35   startingAt:8 ifAbsent:['none']
     #(10 20 30 40 10 20 30 40) lastIdentityIndexOf:10   startingAt:8 ifAbsent:['none']

sorting & reordering
o  detectFirstInOrder: sortBlock
find the first element of the collection sorted with sortBlock
usage example(s):
     #(1 16 7 98 3 19 4 0) detectFirstInOrder:[:a :b | a < b]
     #(1 16 7 98 3 19 4 0) detectFirstInOrder:[:a :b | a > b]
     #(1 -1 16 -16 7 -7 98 -98) detectFirstInOrder:[:a :b | a < b]
     #(1 -1 16 -16 7 -7 98 -98) detectFirstInOrder:[:a :b | a abs < b abs]

o  randomShuffle
random shuffle my elements in place.
This is a destructive algorithm.
Moses, Oakford, Durstenfeld, Knuth algorithm.
See 'The Art of Computer Programming'.
usage example(s):
     (1 to:10) asOrderedCollection randomShuffle

     |c| c := (1 to:100) asOrderedCollection . TimeDuration toRun:[ c randomShuffle ] 
     |c| c := (1 to:1000) asOrderedCollection . TimeDuration toRun:[ c randomShuffle ] 
     |c| c := (1 to:10000) asOrderedCollection . TimeDuration toRun:[ c randomShuffle ] 
     |c| c := (1 to:100000) asOrderedCollection . TimeDuration toRun:[ c randomShuffle ] 
     |c| c := (1 to:1000000) asOrderedCollection . TimeDuration toRun:[ c randomShuffle ] 
     |c| c := (1 to:10000000) asOrderedCollection . TimeDuration toRun:[ c randomShuffle ] 

o  removeAndAddFirst: anElement
if the anElement is in the receiver collection, remove it (compare by equality);
then add it to the beginning.
Effectively moving the element to the beginning if it is already present,
or adding it to the beginning if not already there

o  removeAndAddLast: anElement
if the anElement is in the receiver collection, remove it (compare by equality);
then add it to the end.
Effectively moving the element to the end if it is already present,
or adding it to the end if not already there

o  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.
usage example(s):
     #(4 5 6 7 7) copy reverse
     #(1 4 7 10 2 5) asOrderedCollection reverse

o  reverseFrom: startIndex to: endIndex
destructively reverse the order of some elements inplace.
WARNING: this is a destructive operation, which modifies the receiver.
usage example(s):
     #(1 2 3 4 5) copy reverseFrom:2 to:4

o  reversed
return a copy with elements in reverse order
usage example(s):
     #(4 5 6 7 7) reversed    
     #(1 4 7 10 2 5) asOrderedCollection reversed
     #foo reversed 

o  sort
sort the collection inplace. The elements are compared using
'<' i.e. they should offer a magnitude-like protocol.
WARNING: this is a destructive operation, which modifies the receiver.

The implementation uses the quicksort algorithm, which may not be
the best possible for all situations (quickSort has O-square worst
case behavior).
usage example(s):
     #(1 16 7 98 3 19 4 0) sort

     |data|
     data := Random new next:100000.
     Transcript show:'sort random  '; showCR:(Time millisecondsToRun:[data sort]).
     Transcript show:'sort sorted  '; showCR:(Time millisecondsToRun:[data sort]).
     data reverse.
     Transcript show:'sort reverse '; showCR:(Time millisecondsToRun:[data sort]).

o  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).
usage example(s):
     #(1 16 7 98 3 19 4 0) sort:[:a :b | a < b]
     #(1 16 7 98 3 19 4 0) sort:[:a :b | a > b]
     #(1 -1 16 -16 7 -7 98 -98) sort:[:a :b | a < b]
     #(1 -1 16 -16 7 -7 98 -98) sort:[:a :b | a abs < b abs]

o  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).

o  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.

o  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

o  sortByValue
Sort my contents inplace based on sending #value to my
elements.
Sorting by a #value selector is so common, that its worth a separate utility

o  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).

o  stableSort
sort the collection inplace. The elements are compared using
'<=' i.e. they should offer a magnitude-like protocol.

Use a stable sort algorithm - i.e. elements having an equal key will keep
their previous order.
usage example(s):
     #(1 16 7 98 3 19 4 0) stableSort

     |data|
     data := Random new next:100000.
     Transcript show:'sort random  '; showCR:(Time millisecondsToRun:[data stableSort]).
     Transcript show:'sort sorted  '; showCR:(Time millisecondsToRun:[data stableSort]).
     data reverse.
     Transcript show:'sort reverse '; showCR:(Time millisecondsToRun:[data stableSort]).

o  stableSort: sortBlock
sort the collection inplace using the 2-arg block sortBlock
for comparison. This allows any sort criteria to be implemented.

Use a stable sort algorithm - i.e. elements having an equal key will keep
their previous order.

NOTE: the sort algorithm will be stable, if the sortblock uses #< or #> for comparison!
Do not use #<= of #>= if you want stable behavior.
usage example(s):
     The 4@bla points keep their order:
         {(4@1). (8@2). (4@2). (3@3). (4@3). (-1@4). (17@17). (19@19).
          (12 @ 12). (13@13). (14@14). (15@15). (10@10). (8@8).} stableSort:[:a :b | a x < b x]
        
     But not with quickSort:
         {(4@1). (8@2). (4@2). (3@3). (4@3). (-1@4). (17@17). (19@19).
          (12 @ 12). (13@13). (14@14). (15@15). (10@10). (8@8).} sort:[:a :b | a x < b x]

o  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.

usage example(s):
     #(1 16 7 98 3 19 4 0) topologicalSort:[:a :b | a < b]
     #(1 16 7 98 3 19 4 0) sort:[:a :b | a < b]
     Smalltalk allClasses asArray topologicalSort:[:a :b | a == b superclass]
     Smalltalk allClasses asArray topologicalSort:[:a :b | b isSubclassOf:a]
     Smalltalk allClasses asArray sort:[:a :b | b isSubclassOf:a]

sorting algorithms
o  heapSort
sort the collection inplace. The elements are compared using
'<' i.e. they should offer a magnitude-like protocol.

Heap sort is an unstable sorting algorithm, i.e. elements with the same sort key
don't keep their order.

The implementation uses the heapsort algorithm, which has a complexity
of O(n*log(n)) for both average and worst case.
usage example(s):
     'franz jagt im komplett verwahrlosten taxi quer durch deutschland' copy heapSort
     #( 1 2 3 4 5 6 7 8 9) heapSort
     #( 1 2 3 4 5 6 7 8 9) reversed heapSort

     |data|
     data := Random new next:500000.
     Transcript show:'heap random  '; showCR:(Time millisecondsToRun:[data heapSort]).
     data inject:0 into:[:lastElement :each | lastElement > each ifTrue:[self halt]. each].
     Transcript show:'heap sorted  '; showCR:(Time millisecondsToRun:[data heapSort]).
     data inject:0 into:[:lastElement :each | lastElement > each ifTrue:[self halt]. each].
     data reverse.
     Transcript show:'heap reverse '; showCR:(Time millisecondsToRun:[data heapSort]).
     data inject:0 into:[:lastElement :each | lastElement > each ifTrue:[self halt]. each].

o  heapSort: sortBlock
sort the collection inplace. The elements are compared using
sortBlock.

Heap sort is an unstable sorting algorithm, i.e. elements with the same sort key
don't keep their order.

The implementation uses the heapsort algorithm, which has a complexity
of O(n*log(n)) for both average and worst case.

o  heapSort: sortBlock from: begin to: end
sort the collection inplace. The elements are compared using
the sortBlock.

Heap sort is an unstable sorting algorithm, i.e. elements with the same sort key
don't keep their order.

The implementation uses the heapsort algorithm, which has a complexity
of O(n*log(n)) for average and worst case.

o  heapSortFrom: begin to: end
sort the collection inplace. The elements are compared using
'<' i.e. they should offer a magnitude-like protocol.

Heap sort is an unstable sorting algorithm, i.e. elements with the same sort key
don't keep their order.

The implementation uses the heapsort algorithm, which has a complexity
of O(n*log(n)) for average and worst case.
usage example(s):
     'franz jagt im komplett verwahrlosten taxi quer durch deutschland' copy heapSort
     #( 1 2 3 4 5 6 7 8 9) copy heapSort
     #( 1 2 3 4 5 6 7 8 9) reversed heapSort

     |data|
     data := Random new next:500000.
     Transcript show:'heap random  '; showCR:(Time millisecondsToRun:[data heapSortFrom:1 to:data size]).
     Transcript show:'heap sorted  '; showCR:(Time millisecondsToRun:[data heapSortFrom:1 to:data size]).
     data reverse.
     Transcript show:'heap reverse '; showCR:(Time millisecondsToRun:[data heapSortFrom:1 to:data size]).

o  insertionSort
sort the collection using a insertionSort algorithm.
The elements are compared using'#<'
i.e. they should offer a magnitude-like protocol.

Insertion sort sort is a stable sorting algorithm, i.e. elements with the same sort key
keep their order (if you use e.g. #<) for comparison.

The implementation uses the insertionSort algorithm,
which is slow for large collections O(n*n), but good for small or
almost sorted collections O(N).

See also #quickSort for other sort algorithms
with different worst- and average case behavior)

o  insertionSort: sortBlock

o  insertionSort: sortBlock from: inBegin to: inEnd
binary insertion sort.
The implementation uses the insertionSort algorithm,
which is slow for large collections O(n*n), but good for small or
almost sorted collections O(N).

o  mergeSort
sort the collection using a mergeSort algorithm.
The elements are compared using '#<'
i.e. they should offer a magnitude-like protocol.

Merge sort is a stable sorting algorithm, i.e. elements with the same sort key
keep their order.

The implementation uses the mergesort algorithm, which may not be
the best possible for all situations
See also #quickSort for other sort algorithms
with different worst- and average case behavior)
usage example(s):
     #(1 16 7 98 3 19 4 0) mergeSort
     #(1 16 7 98 7 3 19 4 0) mergeSort 

     |random data|

     random := Random new next:500000.

     data := random copy.
     Transcript show:'merge random  '; showCR:(Time millisecondsToRun:[data mergeSort]).
     Transcript show:'merge sorted  '; showCR:(Time millisecondsToRun:[data mergeSort]).
     data := data reverse.
     Transcript show:'merge reverse '; showCR:(Time millisecondsToRun:[data mergeSort]).

     data := random copy.
     Transcript show:'quick block random  '; showCR:(Time millisecondsToRun:[data quickSort:[:a :b| a < b]]).
     Transcript show:'quick block sorted  '; showCR:(Time millisecondsToRun:[data quickSort:[:a :b| a < b]]).
     data := data reverse.
     Transcript show:'quick block reverse '; showCR:(Time millisecondsToRun:[data quickSort:[:a :b| a < b]]).

     data := random copy.
     Transcript show:'quick random  '; showCR:(Time millisecondsToRun:[data quickSort]).
     Transcript show:'quick sorted  '; showCR:(Time millisecondsToRun:[data quickSort]).
     data := data reverse.
     Transcript show:'quick reverse '; showCR:(Time millisecondsToRun:[data quickSort]).

o  mergeSort: sortBlock
sort the collection using a mergeSort algorithm.
The elements are compared using sortBlock
i.e. they should offer a magnitude-like protocol.

Merge sort is a stable sorting algorithm, i.e. elements with the same sort key
keep their order (if you use e.g. #< for comparison).

The implementation uses the mergesort algorithm, which may not be
the best possible for all situations
See also #quickSort for other sort algorithms
with different worst- and average case behavior)

o  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.

Merge sort is a stable sorting algorithm, i.e. elements with the same sort key
keep their order (if you use e.g. #< or #> for comparison).

o  quickSort
sort the collection inplace. The elements are compared using
'<' i.e. they should offer a magnitude-like protocol.

Quick sort is an unstable sorting algorithm, i.e. elements with the same sort key
don't keep their order.

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)
usage example(s):
     #(1 16 7 98 3 19 4 0) sort

     |data|
     data := Random new next:500001.
     Transcript show:'quick random  '; showCR:(Time millisecondsToRun:[data quickSort]).
     data inject:0 into:[:lastElement :each | lastElement > each ifTrue:[self halt]. each].
     Transcript show:'quick sorted  '; showCR:(Time millisecondsToRun:[data quickSort]).
     data reverse.
     Transcript show:'quick reverse '; showCR:(Time millisecondsToRun:[data quickSort]).

     |data rg|  
     rg := Random new.
     data := Array new:500001.
     1 to:data size do:[:i |
        data at:i put:(rg nextIntegerBetween:1 and:100).
     ].
     Transcript show:'quick random  '; showCR:(Time millisecondsToRun:[data quickSort]).
     data inject:0 into:[:lastElement :each | lastElement > each ifTrue:[self halt]. each].
     Transcript show:'quick sorted  '; showCR:(Time millisecondsToRun:[data quickSort]).
     data reverse.
     Transcript show:'quick reverse '; showCR:(Time millisecondsToRun:[data quickSort]).

o  quickSort: sortBlock
sort the collection inplace using the 2-arg block sortBlock
for comparison. This allows any sort criteria to be implemented.

Quick sort is an unstable sorting algorithm, i.e. elements with the same sort key
don't keep their order.

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)

o  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.

Quick sort is an unstable sorting algorithm, i.e. elements with the same sort key
don't keep their order.

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)

o  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.

Quick sort is an unstable sorting algorithm, i.e. elements with the same sort key
don't keep their order.

The implementation uses the quicksort algorithm, which may not be
the best possible for all situations (quickSort has O-square worst
case behavior).

o  sortSmallSized
for small sizes, specialized sorts with minimum number
of comparisons are used.
This is mostly useful if many small collections are to be sorted.
usage example(s):
     self assert: {1 . 2} sortSmallSized      = #(1 2)  
     self assert: {2 . 1} sortSmallSized      = #(1 2) 
     self assert: {1 . 1.0} sortSmallSized    = #(1 1.0) 
     self assert: {1.0 . 1} sortSmallSized    = #(1.0 1) 

     #( 1 2 3) permutationsDo:[:p |
        self assert: p copy sortSmallSized    = #(1 2 3) 
     ].
     #( 1 2 3 4) permutationsDo:[:p |
        self assert: p copy sortSmallSized    = #(1 2 3 4) 
     ].
usage example(s):
     Time millisecondsToRun:[
        1000000 timesRepeat:[
            { 1 . 2 } quickSort   
        ]
     ].   
     Time millisecondsToRun:[
        1000000 timesRepeat:[
            { 1 . 2 } sortSmallSized   
        ]
     ].   

     Time millisecondsToRun:[
        1000000 timesRepeat:[
            { 1 . 2 . 3} quickSort   
        ]
     ].   
     Time millisecondsToRun:[
        1000000 timesRepeat:[
            { 1 . 2 . 3} sortSmallSized   
        ]
     ].   

     Time millisecondsToRun:[
        1000000 timesRepeat:[
            { 1 . 2 . 3 . 4} quickSort   
        ]
     ].   
     Time millisecondsToRun:[
        1000000 timesRepeat:[
            { 1 . 2 . 3 . 4} sortSmallSized   
        ]
     ].   

splitting & joining
o  asCollectionOfSubCollectionsOfSize: pieceSize
slice into pieces; return a collection containing pieces of size pieceSize from the receiver.
The last piece may be smaller, if the receiver's size is not a multiple of pieceSize.
usage example(s):
     '123123123123123123' asCollectionOfSubCollectionsOfSize:3 
     '12312312312312312312' asCollectionOfSubCollectionsOfSize:3 

o  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.
usage example(s):
     '1 one:2 two:3 three:4 four:5 five' withCRs asCollectionOfSubCollectionsSeparatedBy:$:
     '1 one 2 two 3 three 4 four 5 five' withCRs asCollectionOfSubCollectionsSeparatedBy:Character space
     #(a b c d e f g h) asCollectionOfSubCollectionsSeparatedBy: #d. 
     #(a b c d e f d d g h) asCollectionOfSubCollectionsSeparatedBy: #d.
     'foo-bar-baz' asCollectionOfSubCollectionsSeparatedBy: $-.
     'foobarbaz' asCollectionOfSubCollectionsSeparatedBy: $-. 
     '' asCollectionOfSubCollectionsSeparatedBy: $-. 

o  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.
usage example(s):
     '' 
        asCollectionOfSubCollectionsSeparatedBy:$: do:[:each | Transcript showCR:each storeString]

     '1 one' 
        asCollectionOfSubCollectionsSeparatedBy:$: do:[:each | Transcript showCR:each storeString]

     '1 one:2 two:3 three:4 four:5 five' 
        asCollectionOfSubCollectionsSeparatedBy:$: do:[:each | Transcript showCR:each storeString]

     'a::b' 
        asCollectionOfSubCollectionsSeparatedBy:$: do:[:each | Transcript showCR:each storeString]

     ':' 
        asCollectionOfSubCollectionsSeparatedBy:$: do:[:each | Transcript showCR:each storeString]

     ':a' 
        asCollectionOfSubCollectionsSeparatedBy:$: do:[:each | Transcript showCR:each storeString]

     'a:' 
        asCollectionOfSubCollectionsSeparatedBy:$: do:[:each | Transcript showCR:each storeString]

o  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.
usage example(s):
     '1::2::3::4::5::' asCollectionOfSubCollectionsSeparatedByAll:'::'
     #(1 2 3 1 2 3 4 3 1 1 2 3 1 4 5) asCollectionOfSubCollectionsSeparatedByAll:#(3 1)
     'hello+#world+#here' asCollectionOfSubCollectionsSeparatedByAll:'+#'

o  asCollectionOfSubCollectionsSeparatedByAll: aSeparatorCollection do: aBlock
evaluate aBlock for each subcollection generated by separating elements
of the receiver by aSeparatorCollection.
If aSeparatorCollection occurs multiple times in a row,
the result will contain empty strings.
Uses equality-compare when searching for aSeparatorCollection.
usage example(s):
     '1::2::3::4::5::' asCollectionOfSubCollectionsSeparatedByAll:'::'
     #(1 2 3 1 2 3 4 3 1 1 2 3 1 4 5) asCollectionOfSubCollectionsSeparatedByAll:#(3 1)
     'hello+#world+#here' asCollectionOfSubCollectionsSeparatedByAll:'+#'

o  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.
usage example(s):
     'hello:world:isnt:this nice' asCollectionOfSubCollectionsSeparatedByAny:#($:)
     'hello:world:isnt:this nice' asCollectionOfSubCollectionsSeparatedByAny:':'
     'hello:world:isnt:this nice' asCollectionOfSubCollectionsSeparatedByAny:(Array with:$: with:Character space)
     'hello:world:isnt:this nice' asCollectionOfSubCollectionsSeparatedByAny:': '
     'h1e2l3l4o' asCollectionOfSubCollectionsSeparatedByAny:($1 to: $9)
     #(1 9 2 8 3 7 4 6 5 5) asCollectionOfSubCollectionsSeparatedByAny:#(1 2 3)

o  asCollectionOfSubCollectionsSeparatedByAnyChange: aTwoArgBlock
Answer 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.
The block is evaluated with a previous element of the collection
and the following element
usage example(s):
     #( 1 3 5 2 4 6 7 9 11 ) asCollectionOfSubCollectionsSeparatedByAnyChange:[:prev :curr | prev even ~= curr even].

o  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.
usage example(s):
     'hello:world:isnt:this nice' asCollectionOfSubCollectionsSeparatedByAnyForWhich:[:ch | ch = $:]
     'h1e2l3l4o' asCollectionOfSubCollectionsSeparatedByAnyForWhich:[:ch | ch isDigit]
     #(1 9 2 8 3 7 4 6 5 5) asCollectionOfSubCollectionsSeparatedByAnyForWhich:[:n | n odd]

o  asCollectionOfSubCollectionsSeparatedByAnyForWhich: aCheckBlock do: aBlock
evaluate aBlock for each subcollection generated by separating elements
by elements for which aCheckBlock evaluates to true of the receiver.
This allows breaking up strings using an arbitrary condition.
usage example(s):
     'hello:world:isnt:this nice' asCollectionOfSubCollectionsSeparatedByAnyForWhich:[:ch | ch = $:] do:[:component| Transcript showCR:component]
     'h1e2l3l4o' asCollectionOfSubCollectionsSeparatedByAnyForWhich:[:ch | ch isDigit]  do:[:component| Transcript showCR:component]
     #(1 9 2 8 3 7 4 6 5 5) asCollectionOfSubCollectionsSeparatedByAnyForWhich:[:n | n odd]  do:[:component| Transcript showCR:component]

o  asStringWith: sepCharOrString
return a string generated by concatenating my elements
(which must be strings or nil) and embedding sepCharOrString characters in between.
The argument sepCharOrString may be a character, a string or nil.
Nil entries and empty strings are counted as empty lines.
Similar to joinWith:, but specifically targeted towards collections of strings.
usage example(s):
     #('hello' 'world' 'foo' 'bar' 'baz') asStringWith:$;
     #('hello' 'world' 'foo' 'bar' 'baz') asStringWith:'|'
     'hello|world|foo|bar|baz' asCollectionOfSubstringsSeparatedBy:$|

o  asStringWith: sepCharacterOrString 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.
The argument sepCharOrString may be a character, a string or nil.
Similar to joinWith:, but specifically targeted towards collections of strings.
usage example(s):
     creating entries for searchpath:

     #('foo' 'bar' 'baz' '/foo/bar') asStringWith:$;

     #('foo' 'bar' 'baz' '/foo/bar') asStringWith:$: from:1 to:3

o  asStringWith: sepCharacterOrString from: firstLine to: lastLine compressTabs: compressTabs final: endCharacterOrString
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.
The arguments sepCharacterOrString and endCharacterOrString 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).
Similar to joinWith:, but specifically targeted towards collections of strings.

o  asStringWith: sepCharacterOrString from: firstLine to: lastLine compressTabs: compressTabs final: endCharacterOrString 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.
The arguments sepCharacterOrString and endCharacterOrString 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.
Similar to joinWith:, but specifically targeted towards collections of strings.

o  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.
usage example(s):
     #('hello' 'world' 'foo' 'bar' 'baz') asStringWithCRs

     (OrderedCollection new
	add:'hello';
	add:'world';
	add:'foo';
	add:('bar' asText allBold);
	yourself) asStringWithCRs

     Transcript showCR:
	 (OrderedCollection new
	    add:'hello';
	    add:'world';
	    add:'foo';
	    add:('bar' asText allBold);
	    yourself) asStringWithCRs

o  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.
usage example(s):
     #('hello' 'world' 'foo' 'bar' 'baz') asStringWithCRsFrom:2 to:4

o  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.

o  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.

o  from: firstLine to: lastLine asStringWith: sepCharacterOrString
return part of myself as a string with embedded sepCharacterOrStrings.
The argument sepCharacterOrString may be a character, a string or nil.
My elements must be strings or nil; nil entries and empty strings are
taken as empty lines.
usage example(s):
     creating entries for searchpath:

     #('foo' 'bar' 'baz' '/foo/bar') asStringWith:$;

     #('foo' 'bar' 'baz' '/foo/bar') from:1 to:3 asStringWith:$:

     (#('foo' 'bar' 'baz' '/foo/bar') copyFrom:1 to:3) asStringWith:$:

o  from: firstLine to: lastLine asStringWith: sepCharacterOrString compressTabs: compressTabs final: endCharacterOrString
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.
The arguments sepCharacterOrString and endCharacterOrString may be characters,
strings or nil.
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).

o  from: firstLine to: lastLine asStringWith: sepCharacterOrString compressTabs: compressTabs final: endCharacterOrString withEmphasis: withEmphasis
return part of myself as a string or text with embedded sepCharacterOrString
and followup endCharacterOrString.
My elements must be strings or nil; nil entries and empty strings are
taken as empty lines.
sepCharacterOrString and endCharacterOrString 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.
usage example(s):
     creating entries for searchpath:

       #('foo' 'bar' 'baz' '/foo/bar')
          asStringWith:$:
          from:1 to:4
          compressTabs:false
          final:nil

     with trailing colon:

       #('foo' 'bar' 'baz' '/foo/bar')
          asStringWith:$:
          from:1 to:4
          compressTabs:false
          final:$:

     concatenating elements (nil sepChars and nil endChars):

       #('foo' 'bar' 'baz')
          asStringWith:nil
          from:1 to:3
          compressTabs:false
          final:nil

     creating a string from a collection of lines:

       #('foo' 'bar' 'baz')
          asStringWith:(Character cr)
          from:1 to:3
          compressTabs:false
          final:(Character cr)

     creating a text from a collection of mixed texts and strings:

       (Array
            with:'foo'
            with:('bar' asText allBold)
            with:'baz'
            with:('baz2' asText emphasizeAllWith:#italic)
       )
          asStringWith:(Character cr)
          from:1 to:4
          compressTabs:false
          final:(Character cr)

     can also use strings as separating characters:

       #('foo' 'bar' 'baz')
          asStringWith:'__'
          from:1 to:3
          compressTabs:false
          final:nil

     and as final characters:

       #('foo' 'bar' 'baz')
          asStringWith:'__'
          from:1 to:3
          compressTabs:false
          final:'***'

o  joinWithAll: separatingCollection
return a collection generated by concatenating my elements
and slicing separatingCollection in between.
Similar to asStringWith:, but not specifically targeted towards collections of strings.
usage example(s):
     #('hello' 'world' 'foo' 'bar' 'baz') joinWithAll:' ; '   
     #('hello' 'world' 'foo' 'bar' 'baz') joinWithAll:' | '

o  joinWithAll: separatingCollection from: startIndex to: endIndex as: speciesOrNil
extract parts of myself as a new collection with optional embedded separator.
Separator may be nil, or a collection of elements to be sliced in between.
SpeciesOrNil specifies the species of the resultig object, allowing for Arrays to be converted
as OrderedCollection or vice versa on the fly. If nil is passed in, the species of the first non-nil
element is used.
This counts the overall size first, then allocates the new collection once and replaces elements
via bulk copies. For very small collections, it may be faster to use the comma , operation.
Similar to asStringWith:, but not specifically targeted towards string handling.

o  split: aSequenceableCollection
treating the receiver as a splitter,
split aSequenceableCollection accordingly and return a collection of
fragments.
usage example(s):
     ' ' split: 'hello world'

o  split: aCollection indicesDo: aTwoArgBlock
Split a collection by myself as a delimiter.
see Object >> split: for optimized version for single delimiters.
Example:
'||' split: 'foo||bar||2'
usage example(s):
     'xx' split:'helloxxworldxxthisxxisxxsplitted' indicesDo: [:start :stop | Transcript show:start; show:' to '; showCR:stop ]
     'xx' split:'helloxxworldxxthisxxisxxsplitted' do: [:frag | Transcript showCR:frag ]

     'hello world' 
        splitOn: ' ' 
        do: [:part | Transcript showCR:part ]

o  splitBy: 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.
Same as asCollectionOfSubCollectionsSeparatedBy: for Squeak compatibility
usage example(s):
     '1 one:2 two:3 three:4 four:5 five' withCRs splitBy:$:
     '1 one 2 two 3 three 4 four 5 five' withCRs splitBy:Character space
     #(a b c d e f g h) splitBy: #d.
     #(a b c d e f d d g h) splitBy: #d.

o  splitBy: 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.
usage example(s):
     '' 
        splitBy:$: do:[:each | Transcript showCR:each storeString]

     '1 one' 
        splitBy:$: do:[:each | Transcript showCR:each storeString]

     '1 one:2 two:3 three:4 four:5 five' 
        splitBy:$: do:[:each | Transcript showCR:each storeString]

     'a::b' 
        splitBy:$: do:[:each | Transcript showCR:each storeString]

     ':' 
        splitBy:$: do:[:each | Transcript showCR:each storeString]

     ':a' 
        splitBy:$: do:[:each | Transcript showCR:each storeString]

     'a:' 
        splitBy:$: do:[:each | Transcript showCR:each storeString]

o  splitByAll: 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.
usage example(s):
     '1::2::3::4::5::' splitByAll:'::'
     #(1 2 3 1 2 3 4 3 1 1 2 3 1 4 5) splitByAll:#(3 1)

o  splitByAny: 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.
usage example(s):
     'hello:world:isnt:this nice' splitByAny:#($:)
     'hello:world:isnt:this nice' splitByAny:':'
     'hello:world:isnt:this nice' splitByAny:(Array with:$: with:Character space)
     'hello:world:isnt:this nice' splitByAny:#( $: $ ) 
     'hello:world:isnt:this nice' splitByAny:{ $: . $ }
     'hello:world:isnt:this nice' splitByAny:': '
     'h1e2l3l4o' splitByAny:($1 to: $9)
     #(1 9 2 8 3 7 4 6 5 5) splitByAny:#(1 2 3)

o  splitByAnyForWhich: 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.
usage example(s):
     'hello:world:isnt:this nice' splitByAnyForWhich:[:ch | ch = $:]
     'h1e2l3l4o' splitByAnyForWhich:[:ch | ch isDigit]
     #(1 9 2 8 3 7 4 6 5 5) splitByAnyForWhich:[:n | n odd]

o  splitForSize: pieceSize
slice into pieces; return a collection containing pieces of size pieceSize from the receiver.
The last piece may be smaller, if the receiver's size is not a multiple of pieceSize.
usage example(s):
     '123123123123123123' splitForSize:3 
     '12312312312312312312' splitForSize:3 

o  splitOn: splitter
splitter can be any object which implements #split:;
in particular, Strings, Regexes and Blocks can be
used as spitter.
Any other object used as splitter is treated as an Array
containing that split object
usage example(s):
     'hello world' splitOn:' '

o  splitOn: splitter do: aBlock
split the receiver using splitter (can be a string or regex),
and evaluate aBlock on each fragment.
splitter can be any object which implements #split:;
in particular, Strings, Regexes and Blocks can be
used as spitter.
Any other object used as splitter is treated as an Array
containing that split object
usage example(s):
     'hello world' 
        splitOn:' ' 
        do:[:fragment | Transcript showCR:fragment].

o  splitOn: splitter indicesDo: aTwoArgBlock
split the receiver using splitter (can be a string or regex),
and evaluate aTwoArgBlock on each pair of start- and stop index.
Splitter can be any object which implements #split:;
in particular, Strings, Regexes and Blocks can be used.
Any other splitter object is treated as an Array
containing that split object
usage example(s):
     'hello world' 
        splitOn:' ' 
        indicesDo: [:start :stop | Transcript show:start; show:' to '; showCR:stop ]

o  subCollections: aBlock
Answer 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.
usage example(s):
     #( 1 2 3 nil 4 5 6 nil 7 8 9 nil ) subCollections:[:el | el isNil].

testing
o  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.
usage example(s):
     #(1 2 3) includesKey:4
     #(1 2 3) includesKey:3
     #(1 2 3) includesKey:0

vector arithmetic
o  dot: aFloatVector
Return the dot product of the receiver and the argument.
Raises an error, if the argument is not of the same size as the receiver.

o  hornerMultiplyAndAdd: x
horner's-method computation of polynomials.
(this is a fallback - there are highspeed versions in the floatArray subclasses.

The vector is interpreted as providing the factors for a polynomial,
an*x^n + (an-1)*x^(n-1) + ... + a2(x) + a1
where the ai are the elements of the Array.
The highest rank factor is at the first position, the 0-rank constant at last.

o  squaredVectorLength
Return the squared length of the receiver interpreted as vector.
Some algorithms get along without the square root, and run faster.
usage example(s):
     #(10.0 10.0 10.0) vectorLength
     #(10.0 10.0 10.0) squaredVectorLength

     #(10.0 10.0 10.0) asFloatArray vectorLength
     #(10.0 10.0 10.0) asFloatArray squaredVectorLength

o  vectorLength
Return the length of the receiver interpreted as vector
That is the length of the vector from 0.0 @ 0.0 @ ... @ 0.0
to the point in the n-dimensional space represented by the receiver.
In 2D, that is plain old pythagoras.
usage example(s):
     #(10.0 10.0) vectorLength
     #(10.0 10.0 10.0) vectorLength

     #(10.0 10.0) asFloatArray vectorLength
     #(10.0 10.0 10.0) asFloatArray vectorLength

visiting
o  acceptVisitor: aVisitor with: aParameter
dispatch for visitor pattern; send #visitSequenceableCollection:with: to aVisitor.



ST/X 7.1.0.0; WebServer 1.663 at exept.de:8081; Fri, 22 Feb 2019 22:28:01 GMT