Smalltalk/X Webserver

Documentation of class 'SequenceableCollection':

Class: SequenceableCollection

Inheritance
Description
Class protocol
Instance protocol

Inheritance:

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

Package:: stx:libbasic

Category:: Collections-Abstract

Version:: rev: 1.694 date: 2024/04/18 10:43:56; user: cg; file: SequenceableCollection.st directory: libbasic; module: stx stc-classLibrary: libbasic

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 (at least)
#at:/#at:put: are implemented (which are always found in Object for indexable objects),
and there is an enumerator named #do:.

For performance, many 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 sequenceable collections in the system are probably 
Array, String, ByteArray, OrderedCollection, List and SortedCollection.

copyrightCOPYRIGHT (c) 1989 by Claus Gittinger
             All Rights Reserved

This software is furnished under a license and may be used
only in accordance with the terms of that license and with the
inclusion of the above copyright notice.   This software may not
be provided or otherwise made available to, or used by, any
other person.  No title to or ownership of the software is
hereby transferred.

Class protocol:

Signal constants

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)

instance creation

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)

new: size withAll: element

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

newWithConcatenationOfAll: aCollectionOfCollections

this creates and returns a new collection consisting
of the concatenation of all elements of the argument.
I.e. it has the same effect as concatenating all elements
of the argument using #,
but is implemented more efficiently, by avoiding repeated garbage allocations.
This is an O runtime algorithm, in contrast to the , loop, which is O^2

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

_at: nIndices: this is a synthetic selector, generated by the compiler,
if a construct of the form expr[idx...] is parsed.
I.e.
Array[n]
generates
Array _at: n
_at: dim1 at: dim2: this is a synthetic selector, generated by the compiler,
if a construct of the form expr[idx] is parsed.
I.e.
Array[n][m]
generates
Array _at:n at:m
_at: dim1 at: dim2 at: dim3: this is a synthetic selector, generated by the compiler,
if a construct of the form expr[idx...] is parsed.
I.e.
Array[n][m][o]
generates
Array _at:n at:m at:o
_at: dim1 at: dim2 at: dim3 at: dim4: 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][p]
generates
Array _at:n at:m at:o at:p
which returns a 4-dimensional matrix acccessor

instance creation - streaming

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 stream's contents.

Usage example(s):

     Transcript showCR:(
        Array new:10 streamContents:[:s |
            s nextPut:99; nextPutAll:#(88 77 66); nextPut:55.
        ]
     )

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.

Usage example(s):

     |rslt|

     rslt := OrderedCollection new:10 withCollectedContents:[:c | c add:'hello'; add:'world']

streamContents: blockWithArg

create a write-stream on an instance of the receiver-class,
evaluate blockWithArg, passing that stream,
extract and return the stream's contents.

Usage example(s):

     |rslt|

     rslt := String streamContents:[:s | s nextPutAll:'hello'; space; nextPutAll:'world'].
     rslt := Text streamContents:[:s | s nextPutAll:'hello' allBold; space; nextPutAll:'world'].

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 stream's contents (possibly truncated).

Usage example(s):

     Transcript showCR:(
        Array streamContents:[:s |
            s nextPut:99; nextPutAll:#(88 77 66); nextPut:55.
        ]
        limitedTo:4
     )

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:

streamContentsOf: aReceiver enumerator: enumeratorSelector

Usage example(s):

     String streamContentsOf:'hello' enumerator:#reverseDo:
     Array streamContentsOf:Method enumerator:#allInstancesDo:

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.

Usage example(s):

     |rslt|

     rslt := OrderedCollection withCollectedContents:[:c | c add:'hello'; add:'world']

writeStream

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

Usage example(s):

     OrderedCollection writeStream
     Text writeStream

writeStream: count

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

writeStreamWithInitialSize: l

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

queries

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

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

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   => '67890'
     '123456' allButFirst:5       => '6'
     '12345' allButFirst:5        => ''
     '1234' allButFirst:5         => ''

     '1234567890' copyButFirst:5  => '67890'
     '123456' copyButFirst:5      => '6'
     '12345' copyButFirst:5       => ''
     '1234' copyButFirst:5        => error

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 #copyButLast: in its error behavior.

Usage example(s):

     '1234567890' allButLast
     'ab' allButLast
     '0' allButLast
     '' allButLast

     '' copyButLast

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'
     '12345' allButLast:5               => ''
     '123' allButLast:5                 => ''
     { 1 . 2 . 3 . 4 . 5 . 6 . 7} asOrderedCollection allButLast:5 => OrderedCollection(1 2)
     { 1 . 2 . 3 . 4 . 5} asOrderedCollection allButLast:5         => OrderedCollection()
     { 1 . 2 . 3 } asOrderedCollection allButLast:5                => OrderedCollection()

     '' allButLast:5    => ''
     '' copyButLast:5   => error

asDateAndTime
( an extension from the stx:libcompat package )

I must be a 2-element collection, where the first element is
a date instance and the 2nd element is a time instance.
Return a corresponing timestamp for that

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]

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

atRandom
( an extension from the stx:libbasic2 package )

Return any random element from the receiver

Usage example(s):

     #(1 2 3) atRandom 
     #('a' 'b' 'c') atRandom

atRandom: aRandomGenerator
( an extension from the stx:libbasic2 package )

Return any random element from the receiver

Usage example(s):

     #(1 2 3) atRandom:(Random new)

beginsWith: aCollection

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

collect: aBlock from: startIndex to: stopIndex
( an extension from the stx:libbasic2 package )

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

copyWithoutFirst
( an extension from the stx:libbasic2 package )

An alias for copyButFirst: for squeak compatibility.
Raises an error, if the receiver is empty.

Usage example(s):

     'foo' copyWithoutFirst
     'f' copyWithoutFirst
     '' copyWithoutFirst

destroy

used with cryptographic keys, to wipe their contents after use

forceTo: newSize paddingWith: padding

sigh: a bad name; should be named forceToSize:...

Usage example(s):

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

indexOfAnyOf: aCollection
( an extension from the stx:libbasic2 package )

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

indexOfAnyOf: aCollection startingAt: start
( an extension from the stx:libbasic2 package )

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

indexOfAnyOf: aCollection startingAt: start ifAbsent: exceptionBlock
( an extension from the stx:libbasic2 package )

squeak compatibility: same as #indexOfAny:startingAt:ifAbsent:

join

return a collection generated by concatenating my elements
Similar to flatten (but returns an instance if the furst element)
and asString (but not specifically targeted towards collections of strings).

Usage example(s):

     #('hello' 'world' 'foo' 'bar' 'baz') join   
     #('hello' 'world' 'foo' 'bar' 'baz') flatten   
     #('hello' 'world' 'foo' 'bar' 'baz') join 
     #('hello' 'world' 'foo' 'bar' 'baz') join '
     #((1) (2) (3)) join     
     #((1) (2) (3)) flatten

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:'; '

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

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

Examples:
'1234' pairsSimilarityWith: '2234' ==> (2/3)
'1234' pairsSimilarityWith: '123' ==> (4/5)
'1234' pairsSimilarityWith: '5678' ==> 0

piecesCutWhere: aBlock
( 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 return an OrderedCollection of
those pieces.

Usage example(s):

     'A sentence. Another sentence... Yet another sentence.'
            piecesCutWhere: [:each :next | each = $. and: [next = Character space]]

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]

removeAt: index
( an extension from the stx:libcompat package )

removePrefix: prefix
( an extension from the stx:libcompat package )

Return a copy of myself with the given prefix removed, if present.
If prefix is not present, return myself

Usage example(s):

     'helloworld' removePrefix:'hello'
     'helloworld' withoutPrefix:'hello'

removeSuffix: suffix
( an extension from the stx:libcompat package )

Return a copy of myself with the given suffix removed, if present.
If suffix is not present, return myself

Usage example(s):

     'helloworld' removeSuffix:'world'          
     'helloworld.txt' removeSuffix:'.txt'          
     'helloworld.bla' removeSuffix:'.txt'          
     'helloworld' removeSuffix:'.txt'          
     'helloworld' withoutSuffix:'world'

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 = $\]

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 ~= $\]

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]

shuffle
( an extension from the stx:libcompat package )

Swaps the receiver's elements at random. Inplace, destructive

shuffle: times
( an extension from the stx:libcompat package )

Swaps random elements of the receiver. Inplace, destructive

shuffled
( an extension from the stx:libcompat package )

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.

shuffledBy: aRandom
( an extension from the stx:libcompat package )

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

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:

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.

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.

sortBy: aBlock
( an extension from the stx:libcompat package )

Sort inplace - destructive

Compatibility-V'Age

replaceFrom: start to: end withObject: anObject

Replace the elements from start to end with anObject.
Return the receiver.

Usage example(s):

     |a|

     a := Array new: 10.
     a replaceFrom:3 to:7 withObject:999.
     a

Compatibility-VW

replaceElementsFrom: start to: stop withArray: anArray startingAt: repStart
( an extension from the stx:libcompat package )

JavaScript support

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

doesNotUnderstand: aMessage
( an extension from the stx:libjavascript package )

consider this a hack: JavaScript concat(...) is a varArg method;

every: filterFunction
( an extension from the stx:libjavascript package )

return true, if filterFunction returns true for all elements

fill: anElement
( 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) copy fill:99   
     (OrderedCollection new:100) fill:99

filter: filterFunction
( an extension from the stx:libjavascript package )

select elements for which filterFunction returns true

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)

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)

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:' '
     #(1 2 3 4 5 6) join:'-' 
     #(1 2 3 4 5 6) join:'->'

js_add: aCollection
( an extension from the stx:libjavascript package )

For JavaScript only:
Alternative collection-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

js_concat
( an extension from the stx:libjavascript package )

JS: coll.concat()
returns a copy of the receiver

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

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

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

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

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

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

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.

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.

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.

js_lastIndexOf: anElement _: startIndex
( an extension from the stx:libjavascript package )

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

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)

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)

pop
( an extension from the stx:libjavascript package )

removes and returns the last element of the collection

push: value
( an extension from the stx:libjavascript package )

adds value at the end of the collection; returns the new size

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;'

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.

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]

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.

shift
( an extension from the stx:libjavascript package )

removes and returns the first element of the collection

slice0: index1 _: index2
( an extension from the stx:libjavascript package )

extracts a subcollection, using a 0-based indexing scheme

slice1: index1 _: index2
( an extension from the stx:libjavascript package )

extracts a subcollection, using a 1-based indexing scheme

some: filterFunction
( an extension from the stx:libjavascript package )

return true, if filterfunction returns true for any element

unshift: arg
( an extension from the stx:libjavascript package )

adds an element to the beginning of the collection

accessing

_at: index

this is a synthetic selector, generated by the compiler,
if a construct of the form expr[idx] is parsed.
idx can be:
an integer
an interval
a sequenceable collection
I.e.
foo[n]
generates
foo _at: n
And therefore:
foo[a to: b]
computes
foo copyPath:a to:b

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

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.

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)

at: index ifAbsent: exceptionValue

return the element at index if valid.
If the index is invalid, return the result from exceptionValue.
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']

at: index ifAbsentPut: anObject

(comment from inherited method)
return the element indexed by aKey if present,
if not present, store the result of evaluating valueBlock
under aKey and return it.

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)

atIndex: index

return an element at a given index.
This can be used for collections which support both numeric indexing
and keyed access (eg. PrderedDictionary) to ensure that a numeric index is used.
For all other collections, this is the same as #at:

atIndex: index ifAbsent: absentBlock

return an element at a given index.
If the index is invalid, return the value from absentBlock

atIndex: index put: newValue

return an element at a given index. This allows for sequential collections
and ordered dictionaries to be both accessed via a numeric index.

atLastIndex: index

return an element at a given index, counting index from the end,
with index=1 referring to the last element

Usage example(s):

     #(10 20 30 40) atLastIndex:1   
     #(10 20 30 40) atLastIndex:4
     #(10 20 30 40) atLastIndex:5

atLastIndex: index ifAbsent: exceptionValue

return an element at a given index, counting index from the end,
with index=1 referring to the last element.
If the index is invalid, return the value from absentBlock

Usage example(s):

     #(10 20 30 40) atLastIndex:1 ifAbsent:nil
     #(10 20 30 40) atLastIndex:4 ifAbsent:nil
     #(10 20 30 40) atLastIndex:5 ifAbsent:nil

atLastIndex: index put: newElement

change an element at a given index, counting index from the end,
with index=1 referring to the last element

Usage example(s):

     |coll| 
     coll := #(10 20 30 40) copy.
     coll atLastIndex:1 put:42.
     coll

atWrap: index

Return the index'th element of me if possible.
Wrap the index modulo the receiver's size if it is out of bounds.

Usage example(s):

     #(10 20 30) atWrap:1     => 10
     #(10 20 30) atWrap:2     => 20
     #(10 20 30) atWrap:3     => 30
     #(10 20 30) atWrap:4     => 10
     #(10 20 30) atWrap:5     => 20
     #(10 20 30) atWrap:6     => 30
     #(10 20 30) atWrap:7     => 10
     #(10 20 30) atWrap:0     => 30
     #(10 20 30) atWrap:-1    => 20

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

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.

contents: aCollection

set my contents from aCollection

Usage example(s):

        OrderedCollection new contents:nil
        OrderedCollection new contents:#(1 2 3) asSet

first

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

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

firstOrNil

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

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

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

keyAtEqualValue: value ifAbsent: exceptionBlock

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.

keyAtIdenticalValue: value ifAbsent: exceptionBlock

keyAtValue: value

Usage example(s):

     #(10 20 30 40 50) keyAtValue:40    => 4
     #(10 20 30 40 50) keyAtValue:60    => 0
     #(10 20 30 40 50) keyAtValue:40.0  => 0
     #(10 20 30 40 50) keyAtEqualValue:40.0  => 4

keyAtValue: value ifAbsent: exceptionBlock

last

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

Usage example(s):

     #(1 2 3 4 5) last
     #() last

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        => #(3 4 5)
     #(1 2 3 4 5) last:6        => #(1 2 3 4 5)
     #(1 2 3 4 5) asSet last:3  => OrderedCollection(1 4 2)
     'hello world' last:5       => 'world'
     'hello' last:10            => 'hello'

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

order

the order is the set of keys

second

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

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

swap: index1 with: index2

exchange two elements

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

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

Usage example(s):

     |a|
     a := #(1 2 3 4 5 6 7 8).
     a add:'hello'.
     a

Usage example(s):

     |c|
     c := #(1 2 3 4 5 6 7 8) asOrderedCollection.
     c add:'hello'.
     c

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

addAll: aCollection beforeIndex: index

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

Usage example(s):

     |c|
     c := #(1 2 3 4) asOrderedCollection.
     c addAll:'here' beforeIndex:3

Usage example(s):

     |c|
     c := #(1 2 3 4) asOrderedCollection.
     c removeFirst.
     c addAll:'here' beforeIndex:3

Usage example(s):

     |c|
     c := #(1 2 3 4) asOrderedCollection.
     c addAll:'here' beforeIndex:1

Usage example(s):

     |c|
     c := #(1 2 3 4) asOrderedCollection.
     c addAll:'here' beforeIndex:5

Usage example(s):

     |c|
     c := #(1 2 3 4) asOrderedCollection.
     c addAll:('hello' asSet) beforeIndex:3

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

Usage example(s):

     |a|
     a:= #(1 2 3 4 5 6 7 8).
     a addFirst:'hello'.
     a

Usage example(s):

     |c|
     c := #(1 2 3 4 5 6 7 8) asOrderedCollection.
     c addFirst:'hello'.
     c

dropAllSuchThat: 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.
Differs from #removeAllSuchThat: returns self
instead of a collection containing the removed elements.

Usage example(s):

     |coll|

     coll := OrderedCollection withAll:(1 to:10).
     Transcript showCR:coll.
     coll dropAllSuchThat:[:el | el even].
     Transcript showCR:coll.

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

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.

Usage example(s):

     |coll|

     coll := OrderedCollection withAll:(1 to:10).
     Transcript showCR:(coll removeAllSuchThat:[:el | el even]).
     Transcript showCR:coll

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

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

Usage example(s):

     |a|
     a := #(1 2 3 4 5 6).
     a removeFirst.
     a

removeFirstIfAbsent: exceptionBlock

remove the first element from the collection; return the removed element.
If there is no element in the receiver collection, return the value from
exceptionBlock.

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 removeFirstIfAbsent:nil; yourself
     #() removeFirstIfAbsent:'nothing'

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
     #(1 2 3 4 5 6 7 8 9 0) removeFromIndex:11
     #(1 2 3 4 5 6 7 8 9 0) removeFromIndex:10

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

do not grow when doing #removeFromIndex:(size + x)

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
     #(1 2 3 4 5 6 7 8 9 0) removeFromIndex:33 toIndex:10
     #(1 2 3 4 5 6 7 8 9 0) removeFromIndex:11 toIndex:20 
     #(1 2 3 4 5 6 7 8 9 0) removeFromIndex:10 toIndex:20

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]

removeIndex: index

remove the argument stored at index.
Returns 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

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

Usage example(s):

     |a|
     a := #(1 2 3 4 5 6).
     a removeLast.
     a

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

Usage example(s):

     |t|
     t := #(1 2 3 4 5 6 7 8 9 0) asOrderedCollection.
     t removeToIndex:3.
     t

combinatoric

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)
            with:(1 to: 4)) 
        combinationsDo:[:eachCombination | Transcript showCR: eachCombination]

     (Array 
            with:'abc'
            with:'abc' 
            with:'abc') 
        combinationsDo:[:eachCombination | Transcript showCR: eachCombination]

     (Array with:($a to:$d)) 
        combinationsDo:[:eachCombination | Transcript showCR: eachCombination]

     (Array with:($a to:$d)) combinationsDo:#transcribeCR

Usage example(s):

     (Array 
            with:($a to:$d)
            with:(1 to: 4)) 
        combinationsDo:#transcribeCR

Usage example(s):

     (Array 
            with:#( true false )
            with:#( true false ) 
            with:#( true false ))
        combinationsDo:#transcribeCR

Usage example(s):

all combinations of two letters are generated with:
     (Array 
            with:($a to:$z)
            with:($a to:$z)) 
        combinationsDo:#transcribeCR

Usage example(s):

     (Array 
            with:#(1 2 3 4 5 6 7 8 9)
            with:#(A)) 
        combinationsDo:#transcribeCR

combinationsStartingAt: anInteger prefix: prefix do: aBlock

a helper for combinationsDo:

lexicographicPermutationsDo: aBlock

Repeatly evaluate aBlock with a single copy of the receiver.
Reorder the copy so that aBlock is presented all (self size factorial) possible
permutations in lexicographical order (i.e. sorted by size).

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

Usage example(s):

     (1 to: 4) lexicographicPermutationsDo:[:each | Transcript showCR: each printString]

lexicographicPermutationsStartingAt: anInteger do: aBlock

a helper for lexicographicPermutationsDo:

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.

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) permutationsDo:[:each | Transcript showCR: each printString]
     (0 to: 3) permutationsDo:#transcribeCR

     OrderedCollection streamContents:[:s | (1 to: 4) permutationsDo:[:p | s nextPut:p copy]]

permutationsStartingAt: anInteger do: aBlock

a helper for permutationsDo:

permutationsStartingAt: anInteger with: anotherCollection do: aBlock

a helper for permutationsDo:

permutationsWith: anotherCollection do: aBlock

Usage example(s):

     (1 to: 4) permutationsWith:'abcd' 
        do:[:each1 :each2 | Transcript showCR: each2 copy]

comparing

< 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
        ]
      ]

<= aCollection

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

= aCollection

return true if the receiver and aCollection represent collections
with equal contents, and if they are of the same species.

Usage example(s):

     #(1 2 3 4 5) = #(1 2 3 4 5)                     => true
     #(1 2 3 4 5) asOrderedCollection = #(1 2 3 4 5) asOrderedCollection => true

     #($1 $2 $3 $4 $5) = #(1 2 3 4 5)                => false
     #($1 $2 $3 $4 $5) sameContentsAs: #(1 2 3 4 5)  => false

     #($1 $2 $3 $4 $5) = '12345'                     => false
     #($1 $2 $3 $4 $5) sameContentsAs: '12345'       => true

     #($1 $2 $3 $4 $5) = '54321' asSortedCollection  => false
     #($1 $2 $3 $4 $5) sameContentsAs: '54321' asSortedCollection => true

> aCollection

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

>= aCollection

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

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)

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'

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

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

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'

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

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

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.

compareWith: aSequenceableCollection using: compareBlock

Compare the receiver with the argument and return 1 if the receiver is
greater, 0 if equal and -1 if less than the argument.
Uses compareBlock on each element, which ought to return -1,0 or 1 when
comparing individual elements

Usage example(s):

     #(1 2 1.1 2.9 4) compareWith:#(1 2 1 3 4) using:[:a :b | a rounded compareWith:b rounded].

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

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)

endsWith: aCollection using: compareBlock

return true, if the receiver's last elements match those of aCollection,
using compareBlock to compare individual elements.
compareBlock should return true if elements are considered the same.
If aCollection is empty, true is returned (incompatible to some other dialect's endsWith.)

Usage example(s):

     'abcde' endsWith:#($d $e) using:[:a :b | a asLowercase = b asLowercase]

endsWithAnyOf: aCollectionOfCollectionsOrElement

return true, if the receiver endswith any in aCollection.

Usage example(s):

     'abcde' endsWithAnyOf:#('E' 'e')             => true
     'abcde' endsWithAnyOf:#($E $e)               => true
     'abcde' endsWithAnyOf:#('DE' 'de')           => true
     'abcde' endsWithAnyOf:#('DF' 'df')           => false
     #[1 2 3 4] endsWithAnyOf:#( #(3 5) #(2 4))   => false
     #[1 2 3 4] endsWithAnyOf:#( #(3 4) #(2 4))   => true

     'abc' endsWithAnyOf:'ABC'   => false
     'Abc' endsWithAnyOf:'abc'   => true

hasEqualElements: otherCollection

Answer whether the receiver's size is the same as otherCollection's
size, and each of the receiver's elements equal the corresponding
element of otherCollection.
This should probably replace the current definition of #= .

hash

return a hash key for the receiver

Usage example(s):

this hash is stupid 
     it takes the size, the first and last element's hashes and combines them.
     But for larger collections, the hashing
     time can become much bigger than the time lost in added probing.
     Time will show...
     Concrete clases should redefine this.

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

identicalContentsAs: aCollection

return true if the receiver and aCollection represent collections
with identical contents. This is much like #sameContentsAs:, but compares
elements using #== instead of #=.

Redefinded, so that SequenceableCollections are equivalent,
especially OrderedCollections with unused space.

Usage example(s):

     #(1 2 3 4 5) identicalContentsAs: #(1 2 3 4 5) copy
     #(1 2 3 4 5) identicalContentsAs: #(1 2 3 4) 
     #(1 2 3 4 5) identicalContentsAs: #(1 2 3 4 5) asSet
     #(1 2 3 4 5) asSet identicalContentsAs: #(1 2 3 4 5) copy
     #($1 $2 $3 $4 $5) identicalContentsAs: #(1 2 3 4 5) 
     #($1 $2 $3 $4 $5) identicalContentsAs: '12345'      
     #($1 $2 $3 $4 $5) identicalContentsAs: '54321' asSortedCollection 
     #(1 2 3 4 5) identicalContentsAs: nil

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'

isSameSequenceAs: otherCollection

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

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]

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

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:#()

startsWith: aCollection using: compareBlock

return true, if the receiver's first elements match those of aCollection,
using compareBlock to compare individual elements.
compareBlock should return true if elements are considered the same.
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:'abc' using:[:a :b | a asLowercase = b asLowercase]
     'abCde' startsWith:'abc' using:[:a :b | a asLowercase = b asLowercase]
     'axCde' startsWith:'abc' using:[:a :b | a asLowercase = b asLowercase]

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

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

asDictionary

return a Dictionary with the receiver collection's elements;
if the elements are associations, use the element keys;
otherwise, use the numeric key.

Usage example(s):

     { 1->'one' . 2 -> 'two' } asDictionary

asKeysAndValues

return a new OrderedDictionary with the receiver collection's elements,
which must be associations

Usage example(s):

     { 'ten' -> 10 . 'twenty' -> 20 . 'thirty' -> 30 } asKeysAndValues

asPlainString

return myself as a plain string with embedded cr's, but drop any emphasis

asSequenceableCollection

return myself as a SequenceableCollection.
I am already a SequenceableCollection.

asStringCollection

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

asStringWithoutEmphasis

return myself as a string with embedded cr's, but drop any emphasis.
This is a historic method name. Please use the new method #asPlainString.

asVersionNumberCollection

Convert a collection of strings or numbers to a version number.
Remove zeroes from the end.

Usage example(s):

     #(1) asVersionNumberCollection.
     #(1 '1') asVersionNumberCollection.
     #(1 '1a') asVersionNumberCollection.
     #(1 1 0) asVersionNumberCollection.
     #('expecco' 18 10) asVersionNumberCollection.

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

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

pairsAsDictionary

return a new Dictionary with the receiver collection's elements,
each of which must be a SequenceableCollection with two elements

Usage example(s):

     #( ('ten' 10) ('twenty' 20) ('thirty' 30)) asSet pairsAsDictionary 
     #( ('ten' 10) ('twenty' 20) ('thirty' 30)) pairsAsDictionary

converting-reindexed

butLast: nLastSkipped

Create a ReindexedCollection (slice) from the receiver.
The new collection represents the elements from 1 to the end-nLastSkipped.
(i.e. logically it represents the receiver copyFrom:1 to:size-nLastSkipped,
however, physically, no copy is made).
Warning:
The slice SHARES the memory for the element-data with the original,
it is like a readOnly pointer INTO the receiver.
This means that any modifications in the original are visible in the slice
and vice versa (well, no: because the slice is readOnly).

Usage example(s):

     #(1 2 3 4 5 6 7) butLast:2           
     ( #(1 2 3 4 5 6 7) butLast:2) first   
     ( #(1 2 3 4 5 6 7) butLast:3) last   
     ( #(1 2 3 4 5 6 7) butLast:1) size

from: startIndex

Create a ReindexedCollection (slice) 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,
it is like a readOnly pointer INTO the receiver.
This means that any modifications in the original are visible in the slice
and vice versa (well, no: because 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

from: startIndex butLast: nLastSkipped

Create a ReindexedCollection (slice) from the receiver.
The new collection represents the elements starting at startIndex to the end-nLastSkipped.
(i.e. logically it represents the receiver copyFrom:startIndex to:size-nLastSkipped,
however, physically, no copy is made).
Warning:
The slice SHARES the memory for the element-data with the original,
it is like a readOnly pointer INTO the receiver.
This means that any modifications in the original are visible in the slice
and vice versa (well, no: because the slice is readOnly).

Usage example(s):

     #(1 2 3 4 5 6 7) from:3 butLast:2     
     ( #(1 2 3 4 5 6 7) from:3 butLast:2) first   
     ( #(1 2 3 4 5 6 7) from:3 butLast:3) last  
     ( #(1 2 3 4 5 6 7) from:3 butLast:1) size

from: startIndex by: step

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)

from: startIndex count: numberOfElements

return a ReindexedCollection (slice) 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,
it is like a readOnly pointer INTO the receiver.
This means that any modifications in the original are visible in the slice
and vice versa (well, no: because the slice is readOnly).

Usage example(s):

     #($a $b $c $d $e $f $g) from:2 count:3
     '1234567890' from:2 count:5

Usage example(s):

     |coll slice|

     coll := #(1 2 3 4 5 6 7 8 9 10) copy.
     slice := coll from:3 to:7.
     slice.
     coll at:4 put:40.
     slice.

Usage example(s):

     |coll slice|

     coll := #(1 2 3 4 5 6 7 8 9 10) copy.
     slice := coll from:3 to:7.
     slice.
     slice at:1 put:40.
     slice.

from: startIndex to: endIndex

Create a ReindexedCollection (slice) 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,
it is like a readOnly pointer INTO the receiver.
This means that any modifications in the original are visible in the slice
and vice versa (well, no: because 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

from: startIndex to: endIndex by: step

Create a ReindexedCollection (slice) 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,
it is like a readOnly pointer INTO the receiver.
This means that any modifications in the original are visible in the slice
and vice versa (well, no: because the slice is readOnly).

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) 
     #(1 2 3 4 5 6 7) from:4 to:1 by:-1

to: endIndex

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

to: endIndex by: step

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
     #(1 2 3 4 5 6 7) to:4 by:-1
     #(1 2 3 4 5 6 7) from:4 to:1 by:-1

copying

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

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

,* 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   -> #($a $b $c $a $b $c $a $b $c)
     'abc' ,* 5         -> 'abcabcabcabcabc'
     'abc' ,* 0         -> ''  
     'abc' ,* 1         -> 'abc'
     'a' ,* 50          -> 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'
     (1 to:4) ,* 5      -> OrderedCollection(1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4)

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.

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.

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.
Obsoleted: there was cinconsistency among different smalltalk dialects,
in that some return copyAfterFirst, others copyAfterLast.
(which did not make much difference, as obviously the element was usually only
found once in the receiver...)

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

copyAfterAll: aCollectionOfElements

Answer a copy of the receiver from after the first occurrence
of the subsequence aCollectionOfElements up to the end.
If no such subsequence exists, answer an empty copy.
Same as copyAfterAllFirst:

Usage example(s):

     'hello world' copyAfterAll:'bla'               -> ''
     'hello world' copyAfterAll:'hello'             -> ' world'
     '123456123456' copyAfterAll:#($1 $2 $3)        -> '456123456'
     #(1 2 3 4 1 2 3 3 4 5 6) copyAfterAll:#(2 3 4) -> #(1 2 3 3 4 5 6)
     #(1 2 3 4 1 2 3 3 4 5 6) copyAfterAll:#()
     #(1 2 3 4 1 2 3 3 4 5 6) copyAfterAll:#(6)
     #(1 2 3 4 1 2 3 3 4 5 6) copyAfterAll:#(7)

copyAfterAllFirst: aCollectionOfElements

Answer a copy of the receiver from after the first occurrence
of the subsequence aCollectionOfElements up to the end.
If no such subsequence exists, answer an empty copy.
Same as copyAfterAll:

copyAfterFirst: 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' copyAfterFirst:$l            => 'lo world'
     '123456123456' copyAfterFirst:$2           => '3456123456'
     #(1 2 3 4 1 2 3 3 4 5 6) copyAfterFirst:3  => #(4 1 2 3 3 4 5 6)
     #(1 2 3 4 2 3 3 4 5 6) copyAfterFirst:1    => #(2 3 4 2 3 3 4 5 6)
     #(1 2 3 4 1 2 3 3 4 5 6) copyAfterFirst:7  => #()

copyAfterLast: element

return a copy of the receiver from (but excluding) the last occurrence
of element to the end.
Return an empty collection if element is not found.
Uses equality (=) for comparison

Usage example(s):

     'hello world' copyAfterLast:$l             => 'd'
     '123456123456' copyAfterLast:$2            => '3456'
     #(1 2 3 4 1 2 3 3 4 5 6) copyAfterLast:3   => #(4 5 6)
     #(1 2 3 4 2 3 3 4 5 6) copyAfterLast:1     => #(2 3 4 2 3 3 4 5 6)
     #(1 2 3 4 1 2 3 3 4 5 6) copyAfterLast:7   => #()

copyAfterLastAll: aCollectionOfElements

Answer a copy of the receiver from after the last occurrence
of the subsequence aCollectionOfElements up to the end.
If no such subsequence exists, answer an empty copy.

Usage example(s):

     'hello world' copyAfterLastAll:'bla'                 => ''
     'hello world' copyAfterLastAll:'hello'               => ' world'
     '123456123456' copyAfterLastAll:#($1 $2 $3)          => '456'
     #(1 2 3 4 1 2 3 3 4 5 6) copyAfterLastAll:#(2 3 4)   => #(1 2 3 3 4 5 6)
     #(1 2 3 4 1 2 3 3 4 5 6) copyAfterLastAll:#()        => #()
     #(1 2 3 4 1 2 3 3 4 5 6) copyAfterLastAll:#(6)       => #()
     #(1 2 3 4 1 2 3 3 4 5 6) copyAfterLastAll:#(7)       => #()
     #(1 2 3 4 1 2 3 3 4 5 6) copyAfterLastAll:#()        => #()

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

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  => #($c $d $e $f $g)
     '1234567890' copyButFirst:2             => '34567890'
     '12' copyButFirst:2                     => ''
     '' copyButFirst:2                       => error

     '' allButFirst:2                        => ''

copyButFirstAndLast

return a new collection consisting of the receiver's elements
except for the first and last elements.
Raises an error if the receiver's size is less than 2.

Usage example(s):

     #($a $b $c $d $e $f $g) copyButFirstAndLast
     '1234567890' copyButFirstAndLast
     '1' copyButFirstAndLast
     '' copyButFirstAndLast
     'ab' copyButFirstAndLast

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

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 => #($a $b $c $d $e)
     '1234567890' copyButLast:2            => '12345678'
     '12' copyButLast:2                    => ''

     '1' copyButLast:2                     => error
     '1' allButLast:2                      => ''

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

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

copyFrom: startIndex butLast: skippedAtEnd

return a new collection consisting of receiver's elements from startIndex
to skippedAtEnd elements befoew the end of the collection.
Return an empty collection, if startIndex is beyond the receiver's size or
the end minus skippedAtEnd is before startIndex.

Usage example(s):

     #($a $b $c $d $e $f $g) copyFrom:2       
     #($a $b $c $d $e $f $g) copyFrom:2 butLast:3
     '1234567890' copyFrom:2
     '1234567890' copyFrom:2 butLast:3  
     (10 to:19) copyFrom:5
     (10 to:19) copyFrom:5 butLast:3 

     '1234567890' copyFrom:5 butLast:5 
     '1234567890' copyFrom:5 butLast:6

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    => #($b $c $d)
     'hello' copyFrom:2 count:2                    => 'el'
     'hello' copyFrom:2 count:1                    => 'e'
     'hello' copyFrom:2 count:0                    => ''
     '1234567890' copyFrom:2 count:5               => '23456'
     '1234567890' copyFrom:6 count:5               => '67890'
     '1234567890' copyFrom:7 count:5               -> error 
     #f(1 2 3 4 5 6 7 8 9 0) copyFrom:6 count:5    => FloatArray(6.0 7.0 8.0 9.0 0.0)
     #f(1 2 3 4 5 6 7 8 9 0) copyFrom:7 count:5    -> error

copyFrom: startIndex through: anElement

return a new collection consisting of receiver's elements from startIndex
up to (and including) the next occurence of anElement.
Return the remaining elements (up to the end), if anElement is not found.
Return an empty collection, if startIndex is beyond the receiver's size.

Usage example(s):

     #($a $b $c $d $e $f $g) copyFrom:2 through:$f
     '1234567890' copyFrom:2 through:$8
     (10 to:19) copyFrom:5 through:18

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

copyFrom: startIndex upTo: anElement

return a new collection consisting of receiver's elements from startIndex
up to (but excluding) the next occurence of anElement.
Return the remaining elements (up to the end), if anElement is not found.
Return an empty collection, if startIndex is beyond the receiver's size.

Usage example(s):

     #($a $b $c $d $e $f $g) copyFrom:2 upTo:$f
     '1234567890' copyFrom:2 upTo:$8
     (10 to:19) copyFrom:5 upTo:18

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    => #($c $d $e $f $g)
     '1234567890' copyLast:4               => '7890'
     '12345' copyLast:4                    => '2345'
     '1234' copyLast:4                     => '1234'
     '123' copyLast:4                      => error
     '' copyLast:4                         => error

     '123' last:4                          => '123'
     '' last:4                             => ''

copyLastUpToElementForWhich: aBlock

return a new collection consisting of the receiver's last elements
up-to (but excluding) the first element for which aBlock returns true,
searching from the end.

Usage example(s):

     '0123456789' copyLastUpToElementForWhich:[:el | el < $5]   
     '1234567890' copyLastUpToElementForWhich:[:el | el == $a]  
     '1234567890' copyLastUpToElementForWhich:[:el | el == $0]  
     '1234567890' copyLastUpToElementForWhich:[:el | el == $5]  
     'abcdef1234567890' copyLastUpToElementForWhich:[:el | el isLetter]  
     'abcdef1234567890' copyLastUpToElementForWhich:#isLetter    
     '1234567890abcdef' copyLastUpToElementForWhich:#isDigit

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.

Usage example(s):

     |map|

     map := Dictionary new
                at:1 put:'one';
                at:2 put:'two';
                yourself.

     #(1 2 3 4 1 2 3 4) copyMapping:map

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:'**'

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:$*

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'

copyReplaceAll: oldObject withAll: slicedInCollection

return a copy, where all elements equal to oldObject
are replaced by all elements from slicedInCollection (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' errorPrintCR.

Usage example(s):

     '123123abc123' copyReplaceAll:$1 withAll:'one'      => 'one23one23abcone23'
     '123123abc123' copyReplaceAll:$1 withAll:'äöü'      => 'äöü23äöü23abcäöü23'
     '123123abc123' copyReplaceAll:$1 withAll:'ΓΔΘ'      => 'ΓΔΘ23ΓΔΘ23abcΓΔΘ23'
     #(1 2 3 4 1 2 3 4) copyReplaceAll:1 withAll:#(9 9 9)  => #(9 9 9 2 3 4 9 9 9 2 3 4)
     #(1 2 3 4 1 2 3 4) copyReplaceAll:1 withAll:'one'     => #($o $n $e 2 3 4 $o $n $e 2 3 4)

copyReplaceAllForWhich: checkBlock with: newElement

return a copy of the receiver, where all elements for which checkBlock
returns true will are replaced by newElement.

Usage example(s):

     #(1 2 1 3 4 5 1 2 1 2) copyReplaceAllForWhich:[:e | e > 2] with:99
     'hello 1234 world' copyReplaceAllForWhich:#isDigit with:$*

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'

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:$*

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'

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:$*

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'

copyReplacePrefix: oldPrefix with: newPrefix

if the receiver startsWith oldPrefix, return a copy with that suffix replaced by newPrefix.
Otherwise return the receiver

Usage example(s):

     'helloworld' copyReplacePrefix:'hello' with:'Hello'  
     'foo class' copyReplacePrefix:'foo' with:'bar'      
     'ffoo class' copyReplacePrefix:'foo' with:'bar'

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'

copyReplaceSuffix: oldSuffix with: newSuffix

if the receiver endsWith oldSuffix, return a copy with that suffix replaced by newSuffix.
Otherwise return the receiver

Usage example(s):

     'helloworld' copyReplaceSuffix:'world' with:'welt'  
     'foo class' copyReplaceSuffix:' class' with:'Class'     
     'foo xlass' copyReplaceSuffix:' class' with:'Class'

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:$*

copyThrough: element

return a new collection consisting of the receiver elements
up-to (AND including) the first occurrence of element.
Returns nil if element is not found

Usage example(s):

     #($a $b $c $d $e $f $g) copyThrough:$d
     '1234567890' copyThrough:$5             => '12345'
     '1234567890' copyThrough:$a             => nil
     '1234567890' copyThrough:$1             => '1'

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

copyToMax: stop

return a new collection consisting of receiver's elements
from 1 up to (including) the index stop, or up to the receiver's end,
whichever is smaller
(i.e. like copyTo:, but do not report an error 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

copyToMax: stop ifLargerCopyWith: whatToAppendIfLarger

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).
If the copy is smaller, append the element whatToAppendIfLarger.
This is useful to cut off long texts and mark it with '...' at the end
as seen in the example below.

Usage example(s):

     (#('one' 'two' 'three' 'four') copyToMax:2 ifLargerCopyWith:'...') => #('one' 'two' '...')
     (#('one' 'two' 'three' 'four') copyToMax:4 ifLargerCopyWith:'...') => #('one' 'two' 'three' 'four')

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:''

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

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

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:'*'

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   => #($a $b $c $d)
     '1234567890' copyUpThrough:$5              => '12345'
     '1234567890' copyUpThrough:$a              => '1234567890'
     '1234567890' copyUpThrough:$1              => '1'
     '123456789' copyUpThrough:$0               => '123456789'

copyUpTo: 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.
I.e. #upTo:/upToAll: return the part to the left of an element/slice,
whereas restAfter:/restAfterAll: return the part to the right of it.
See also #copyFrom:index.

Usage example(s):

     #(1 2 3 4 5 6 7 8 9) copyUpTo:5                    => #(1 2 3 4)
     'hello world' copyUpTo:Character space             => 'hello'
     #(9 8 7 6 5 4 3 2 1) asSortedCollection copyUpTo:5 => SortedCollection(1 2 3 4)
     '1234.5678' copyUpTo:$.                            => '1234'
     '1234'      copyUpTo:$.                            => '1234'
     '.'      copyUpTo:$.                               => ''
     (1 to:10 by:2) copyUpTo:7                          => OrderedCollection(1 3 5)

     raises an error:

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

copyUpToElementForWhich: aBlock

return a new collection consisting of the receiver elements
up-to (but excluding) the first element for which aBlock returns true.

Usage example(s):

     '1234567890' copyUpToElementForWhich:[:el | el > $5]  
     '1234567890' copyUpToElementForWhich:[:el | el == $a]  
     '1234567890' copyUpToElementForWhich:[:el | el == $0]  
     'abcdef1234567890' copyUpToElementForWhich:[:el | el isLetter not]  
     'abcdef1234567890' copyUpToElementForWhich:#isDigit    
     '1234567890abcdef' copyUpToElementForWhich:#isLetter

copyUpToLast: element

return a copy of the receiver up to (but excluding) the last occurrence
of element; uses = for comparison.
Return a copy of the receiver if element is not found.

Usage example(s):

     'hello world' copyUpToLast:$l              => 'hello wor'
     '123456123456' copyUpToLast:$2             => '1234561'
     #(1 2 3 4 1 2 3 3 4 5 6) copyUpToLast:3    => #(1 2 3 4 1 2 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    => #(1 2 3 4 1 2 3 3 4 5 6)

copyValuesFrom: startIndex

Return a copy of the receiver that contains values from
position startIndex to the end.
For compatibility with OrderedDictionary protocol.

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

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 a 2 3 4 5 6 7 8 9 0 1 2 3 4)
     #(1 2 3 4 5 6 7 8 9 0 1 2 3 4) copyWith:#a insertedAfterIndex:0    => #(a 1 2 3 4 5 6 7 8 9 0 1 2 3 4)
     #(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 a)
     #(1 2 3 4 5 6 7 8 9 0 1 2 3 4) copyWith:#a insertedAfterIndex:15  --> error

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

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

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

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) asOrderedCollection copyWithFirst:$a   => OrderedCollection($a 1 2 3 4 5)
     'abcdefg' copyWithFirst:$h                          => 'habcdefg'
     'abcdefg' copyWithFirst:'123'   -- will fail: string cannot be stored into string
     'abcdefg' copyWithFirst:1       -- will fail: integer cannot be stored into string

copyWithout: elementToSkip

return a new collection consisting of a copy of the receiver, with
ALL elements equal to elementToSkip left out (i.e. removed).
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 $e $f $g)
     #($a $b $c $d $e $f $g) copyWithout:$a   => #($b $c $d $e $f $g)
     #($a $b $c $d $e $f $g) copyWithout:$g   => #($a $b $c $d $e $f)
     #($a $b $c $a $e $f $a) copyWithout:$a   => #($b $c $e $f)
     #($a $b $c $a $e $a $a) copyWithout:$a   => #($b $c $e)
     #($a $a $a) copyWithout:$a               => #()
     'abcdefghi' copyWithout:$h               => 'abcdefgi'
     'abcdefg' copyWithout:$h                 => 'abcdefg'
     'abcdefabcghi' copyWithout:$a            => 'bcdefbcghi'
     'abcdefabcg' copyWithout:$h              => 'abcdefabcg'
     #($a $b $c $a $a $d $e $a $f $g) copyWithout:$a                => #($b $c $d $e $f $g)
     #($a $b $c $d $e $f $g) copyWithout:$x                         => #($a $b $c $d $e $f $g)
     #(90 80 70 60 50) copyWithout:70                               => #(90 80 60 50)
     #(90 80 70 80 60 45 80 50) copyWithout:80                      => #(90 70 60 45 50)
     #(90 80 70 80 60 45 80 50) asSortedCollection copyWithout:80   => SortedCollection(45 50 60 70 90)

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)

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

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

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

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

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

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
     #(1 2 3) ,* 100
     'abc' ,* 100

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.
I.e. restAfter:/restAfterAll: return the part to the right of an element/slice,
whereas #upTo:/upToAll: return the part to the left of it.

Usage example(s):

     #(1 2 3 4 5 6 7 8 9) upTo:5             -> #(1 2 3 4)
     #(1 2 3 4 5 6 7 8 9) restAfter:5        -> #(6 7 8 9)
     'hello world' upTo:Character space      -> 'hello'          
     'hello world' restAfter:Character space -> 'world'

     '1234.5678' upTo:$.                     -> '1234'        
     '1234.5678' restAfter:$.                -> '5678'        
     '1234.5678' splitBy:$.                  -> StringCollection('1234' '5678')

restAfterAll: anElementCollection

return a new collection consisting of the receiver's elements after
(but excluding) anElementCollection.
If anElementCollection is not in the receiver, the returned collection will be empty.
I.e. restAfter:/restAfterAll: return the part to the right of an element/slice,
whereas #upTo:/upToAll: return the part to the left of it.

Usage example(s):

     #(1 2 3 5 4 5 6 7 8 9) upToAll:#(5 6)       -> #(1 2 3 5 4)
     #(1 2 3 5 4 5 6 7 8 9) restAfterAll:#(5 6)  -> #(7 8 9)
     'hello world' restAfterAll:'hello'          -> ' world'
     'hello world' upToAll:'world'               -> 'hello '

restAfterAny: anElementCollection

return a new collection consisting of the receiver's elements after
(but excluding) any from anElementCollection.
If none from anElementCollection is found in the receiver, the returned collection will be empty.
I.e. restAfter:/restAfterAll:/restAfterAny: return the part to the right of an element/slice,
whereas #upTo:/upToAll:/upToAny: return the part to the left of it.

Usage example(s):

     #(1 2 3 4 5 6 7 8 9) upToAny:#(4 5 6)       -> #(1 2 3)
     #(1 2 3 4 5 6 7 8 9) restAfterAny:#(4 5 6)  -> #(5 6 7 8 9)
     'hello world' restAfterAny:'eo'             -> 'llo world'
     'hello world' upToAny:'eo'                  -> 'h '

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

upTo: anElement

Usage example(s):

     #(1 2 3 4 5 6 7 8 9) upTo:5                    -> #(1 2 3 4)
     'hello world' upTo:Character space             -> 'hello'
     #(9 8 7 6 5 4 3 2 1) asSortedCollection upTo:5 -> SortedCollection(1 2 3 4)
     '1234.5678' upTo:$.                            -> '1234'
     '1234'      upTo:$.                            -> '1234'
     '.'      upTo:$.                               -> ''
     (1 to:10 by:2) upTo:7                          -> OrderedCollection(1 3 5)

     raises an error:

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

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   => 'hello1_hello2'  returns first two 'hellos'
     'hello1_hello2_hello3' upTo:$_ count: -1   => 'hello3'         returns last 'hello3'
     'hello1_hello2_hello3' upTo:$_ count: 0    => 'hello1'         returns first 'hello1'
     'hello1_hello2_hello3' upTo:$_ count: 1    => 'hello1'         returns first 'hello1'
     'hello1_hello2_hello3' upTo:$_             => 'hello1'         same; returns first 'hello1'

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.
I.e. #upTo:/upToAll: return the part to the left of an element/slice,
whereas restAfter:/restAfterAll: return the part to the right of it.
See also #copyFrom:index.

Usage example(s):

     'hello world' upToAll:'wo'                   => 'hello '
     'hello world' upToAll:'bla'                  => 'hello world'
     #(1 2 3 4 5 6 7 8) upToAll:#(5)              => #(1 2 3 4)
     #(1 2 3 4 5 6 7 8) upToAll:#()               => #(1 2 3 4 5 6 7 8)
     #(1 3 4 2 3 4 5 6 7 8) upToAll:#(3 4 5 6)    => #(1 3 4 2)
     #(1 3 4 2 3 4 5 6 7 8) upToAll:#(3 5 6)      => #(1 3 4 2 3 4 5 6 7 8)

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'
     'hello:world' upToAny:#($/ $:)   => 'hello'
     'hello/world' upToAny:#($/ $:)   => 'hello'
     'hello/world' upToAny:'/:'       => 'hello'
     #(1 2 3 4 5 6) upToAny:#(99 3)   => #(1 2)

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] 
     'hello world' upToSeparator
     'hello:world' upToSeparator
     'hello:world' upTo:$:

upToMatching: aBlock

marked as obsolete by exept MBP at 21-Jul-2021

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

upToOrSelf: anElement

return a new collection consisting of the receiver's elements upTo
(but excluding) anElement.
If anElement is not in the receiver, return myself (not a copy!).
See also #restAfter: , #copyFrom:index.

This is similar to #upTo: but avoids garbage if anElement is not
present in the collection and a copy of the collection is not needed.

Usage example(s):

     #(1 2 3 4 5 6 7 8 9) upToOrSelf:5                     => #(1 2 3 4)
     'hello world' upToOrSelf:Character space              => 'hello'
     #(9 8 7 6 5 4 3 2 1) asSortedCollection upToOrSelf:5  => SortedCollection(1 2 3 4)
     '1234.5678' upToOrSelf:$.                             => '1234'
     '1234'      upToOrSelf:$.                             => '1234'
     '.'      upToOrSelf:$.                                => ''


     raises an error:

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

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 => 'hello'

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]     

     'hello1234' withoutLeadingForWhich:#isDigit  -> ''hello1234''
     '1234' withoutLeadingForWhich:#isDigit       -> ''
     '1234aaa' withoutLeadingForWhich:#isDigit    -> 'aaa'
     '1234aaa123' withoutLeadingForWhich:#isDigit -> 'aaa123'

withoutPrefix: aStringOrCharacter

if the receiver startsWith aString, return a copy without it.
Otherwise return the receiver

Usage example(s):

     'helloworld' withoutPrefix:'hello'   -> 'world'
     'helloworld' withoutPrefix:'foo'     -> 'helloworld'
     'helloworld' withoutPrefix:$h        -> 'elloworld'
     'helloworld' withoutPrefix:#( $h )   -> 'elloworld'

withoutPrefix: prefixStringOrCharacter withoutSuffix: suffixStringOrCharacter

return a copy with prefix and suffix stripped off, if present;
otherwise return the receiver.

Usage example(s):

     'hello brave world' withoutPrefix:'hello' withoutSuffix:'world'  -> ' brave '
     'helloworld' withoutPrefix:'foo' withoutSuffix:'world'           -> 'hello'
     'helloworld' withoutPrefix:$h withoutSuffix:$d                   -> 'elloworl'
     'helloworld' withoutPrefix:#( $h ) withoutSuffix:'d'             -> 'elloworl'
     'helloworld' withoutPrefix:#( $x ) withoutSuffix:'x'             -> 'helloworld'

withoutSuffix: aStringOrCharacter

if the receiver endsWith aString, return a copy without it.
Otherwise return the receiver

Usage example(s):

     'helloworld' withoutSuffix:'world' => 'hello'
     'helloworld' withoutSuffix:'foo'   => 'helloworld'
     'helloworldx' withoutSuffix:$x     => 'helloworld'
     #(1 2 3 4) withoutSuffix:#(3 4)    => #(1 2)

withoutTrailingForWhich: aCheckBlock

return a copy of myself without trailing 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....' withoutTrailingForWhich:[:ch | ch isLetter not]. 
     #( 0 0 0 1 2 3 4 0 0 0) withoutTrailingForWhich:[:e | e = 0]     

     'hello1234' withoutTrailingForWhich:#isDigit  -> 'hello'
     '1234' withoutTrailingForWhich:#isDigit       -> ''
     '1234aaa' withoutTrailingForWhich:#isDigit    -> '1234aaa'

enumerating

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]

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]

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:' , ']

from: startIndex butLast: nSkippedAtEnd do: aBlock

evaluate the argument, aBlock for the elements starting with the
startIndex to the end, but skipping nSkippedAtEnd elements at the end .

Usage example(s):

     #(one two three four five six)
        from:3 butLast:2
        do:[:element | Transcript showCR:element]

from: startIndex collect: aBlock

evaluate the argument, aBlock for the elements starting at startIndex
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]

from: startIndex conform: aOneArgBlock

return true, if the elements starting at the startIndex conform to some condition.
I.e. return false, if aBlock returns false for any of those elements;
true otherwise.

from: startIndex do: aBlock

evaluate the argument, aBlock for the elements starting with the
startIndex to the end.

Usage example(s):

     #(one two three four five six)
        from:3
        do:[:element | Transcript showCR:element]

from: startIndex doWithExit: aBlock

evaluate the argument, aBlock for the elements starting with the
startIndex to the end. Passes an additional exitBlock as second
argument, which can be used to exit the loop early.
For convenience, return the exit argument if there was an early exit,
and nil, if there was not.

Usage example(s):

     #(one two three four five six)
        from:3
        doWithExit:[:element :exit | 
            Transcript showCR:element.
            element = 'four' ifTrue:[ exit value:999 ]
        ]

from: startIndex doWithIndex: aTwoArgBlock

evaluate the argument, aTwoArgBlock for the elements starting with the
startIndex to the end,
passing both the element and its index as argument.

Usage example(s):

     #(one two three four five six)
        from:3
        doWithIndex:[:element :idx | Transcript showCR:idx->element]

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

from: startIndex select: aBlock

evaluate the argument, aBlock for the elements starting at startIndex
and return a collection of those elements for which the block return true.

Usage example(s):

     #(faba one two three four five six)
        from:3 select:[:element | element startsWith:'f']

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]

from: startArg to: stopArg 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]

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]

from: index1 to: index2 do: aBlock

evaluate the argument, aBlock for the elements with index index1 to
index2 in the collection.
If index2 < index1, nothing is done

Usage example(s):

     #(one two three four five six)
        from:3 to:1 do:[:element | Transcript showCR:element]
     #(one two three four five six)
        from:3 to:5 do:[:element | Transcript showCR:element]

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.
For convenience, return the exit argument if there was an early exit,
and nil, if there was not.

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

from: index1 to: index2 doWithIndex: aBlock

Squeak/V'Age compatibility;
like keysAndValuesDo:, but passes the index as second argument.

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]

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]

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]

from: start to: stop 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']

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]

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]

inGroupsOf: n detect: anNArgBlock thenDo: anotherNArgBlock ifNone: exceptionValue

evaluate the argument, anNArgBlock for every group of n elements in the collection,
until the block returns true. Then deliver the to anotherNArgBlock and return
that block's result. If none matches, return the valeu from exceptionValue.
An error will be reported, if the number of elements in the receiver
is not a multiple of n.
This is similar to slicesOf:detect:, but here, an N-arg block is expected.

Usage example(s):

     #(1 one 2 two 3 three 4 four 5 five 6 six)
         inGroupsOf:2 detect:[:num :sym | num > 3]
         thenDo:[:num :sym | sym] ifNone:'ouch'   

     #(1 one 2 two 3 three 4 four 5 five 6 six)
         inGroupsOf:2 detect:[:num :sym | num > 99]
         thenDo:[:num :sym | sym] ifNone:'ouch'

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]

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]]

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
                        ]

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
			       ]

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
     ]

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]

nonNilElementsDoWithIndex: aTwoArgBlock

evaluate the argument, aTwoArgBlock for every non-nil element in the collection.

Usage example(s):

     #(one nil three nil five nil seven) 
        nonNilElementsDoWithIndex:[:element :index| 
            Transcript showCR:(index -> element)
        ]

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]  => #(1->2 2->3 3->4)

     'hello world how nice' overlappingPairsCollect: [:a :b | a,b] 
     #('hello' 'world' 'how' 'nice') overlappingPairsCollect: [:a :b | a,b] => #('helloworld' 'worldhow' 'hownice')

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

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]
    outputs:
        1 2
        2 3
        3 4

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
                ]

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]

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.
See also inGroupsOf:do:
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):

We could use 'self inGroupsOf:2 do:aTwoArgBlock'
     but for performance we do it here directly. #pairWiseDo: is used so often.

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]

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]

reverseDoWithIndex: aBlock

evaluate the argument, aBlock for every element in the collection
in reverse order, passing both the element and the index

Usage example(s):

     #(one two three four five six) reverseDo:[:element | Transcript showCR:element]
     #(one two three four five six) reverseDoWithIndex:[:element :idx | Transcript show:idx; show:' '; showCR:element]

select: aBlock

evaluate the argument, aBlock for every element in the collection
and return a collection of all elements for which the blocks 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']

selectIndices: aBlock

evaluate the argument, aBlock for every INDEX in the collection
and return a collection of all elements for which the block returns true

Usage example(s):

     #(one two three four five six) selectIndices:[:idx | idx odd]   
     #(1 2 3 4 5 6 7 8 9) selectIndices:#even

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.

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.

to: endIndex collect: aBlock

evaluate the argument, aBlock for the elements up
endIndex and return a collection of the results

Usage example(s):

     #(one two three four five six)
        to:3
        collect:[:element | element asUppercase]

to: end conform: aOneArgBlock

return true, if the elements up to endIndex conform to some condition.
I.e. return false, if aBlock returns false for any of those elements;
true otherwise.

to: endIndex do: aBlock

evaluate the argument, aBlock for the elements starting with the
first to the endIndex.

Usage example(s):

     #(one two three four five six)
        to:3
        do:[:element | Transcript showCR:element]

to: endIndex doWithIndex: aTwoArgBlock

evaluate the argument, aTwoArgBlock for the elements starting
with the first to endIndex,
passing both the element and its index as argument.

Usage example(s):

     #(one two three four five six)
        to:3
        doWithIndex:[:element :idx | Transcript showCR:idx->element]

to: endIndex keysAndValuesDo: aBlock

evaluate the argument, aBlock for the elements and indices
starting with the first element to the endIndex.

Usage example(s):

     #(one two three four five six)
        to:3
        keysAndValuesDo:[:element :idx | Transcript showCR:(idx -> element) ]

to: endIndex select: aBlock

evaluate the argument, aBlock for the elements up to endIndex
and return a collection of those elements for which the block return true.

Usage example(s):

     #(faba one two three four five six)
        to:3 select:[:element | element startsWith:'f']

validElementsDo: aBlock

evaluate the argument, aBlock for every non-nil element in the collection.
For compatibility with WeakCollections.

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

with: collection2 collect: aTwoArgBlock

evaluate the argument, aBlock for successive elements from
each the receiver and the collection argument,
and collect the results.
The last argument, aBlock must be a two-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:(100 to:600 by:100)
        collect:[:el1 :el2 | 
            el1 printString , el2 printString
        ]

     #(one two three four five six) with:(1 to:6)
        collect:[:el1 :el2 | 
            el1 printString , '-' , el2 printString
        ]

with: collection2 collect: aTwoArgBlock as: classOfResult

Usage example(s):

     #(one two three four five six)
        with:(100 to:600 by:100)
        collect:[:el1 :el2 | 
            el1 printString , el2 printString
        ]
        as:OrderedCollection

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]

with: aSequenceableCollection doWithIndex: aThreeArgBlock

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]

with: collection2 select: aTwoArgBlock

evaluate the argument, aBlock for successive elements from
each the receiver and the collection argument,
and select values from the receiver, where aTwoArgBlock returns true.
The collection arguments must implement access via a numeric key
and the sizes must be the same.

Usage example(s):

to fetch all elements at even indices:
    
     #(one two three four five six seven eight) with:(1 to:8) select:[:el :idx | idx even]

with: collection2 with: collection3 collect: aThreeArgBlock

evaluate the argument, aBlock for successive elements from
each the receiver and the collection arguments
and collect the results.
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)
        collect:[:el1 :el2 :el3 | 
            el1 printString , el2 printString , el3 printString
        ]

with: collection2 with: collection3 collect: aThreeArgBlock as: classOfResult

Usage example(s):

     #(one two three four five six)
        with:(1 to:6)
        with:(100 to:600 by:100)
        collect:[:el1 :el2 :el3 | 
            el1 printString , el2 printString , el3 printString
        ]

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

atAllPut: anObject

replace all elements of the collection by the argument, anObject.
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):

     (Array new:10) atAllPut:1
     (String new:10) atAllPut:$a

clearContents

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

equalFrom: startIndex to: stopIndex with: aCollection startingAt: repStartIndex

compare elements in the receiver between index start and stop,
with elements taken from aCollection starting at repStart.
Return true if the values are equal, false if not.

Usage example(s):

     '1234567890' equalFrom:5 to:7 with:'abcdef' startingAt:3  => false
     '1234567890' equalFrom:5 to:7 with:'xx567' startingAt:3   => true
     '1234567890' equalFrom:5 to:7 with:'567' startingAt:1     => true
     '1234567890' equalFrom:5 to:7 with:'568' startingAt:1     => false
     '1234567890' equalFrom:5 to:7 with:'578' startingAt:1     => false
     '1234567890' equalFrom:5 to:7 with:'678' startingAt:1     => false

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

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

replaceAll: oldObject by: newObject

backward ST/X compatibility: an alias for #replaceAll:with:.
Pleace do no longer use this one;
instead use #replaceAll:with: for ST-80 compatibility.

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

replaceAll: oldObject by: newObject from: startIndex to: stopIndex

backward ST/X compatibility: an alias for #replaceAll:with:from:to:.
Please do no longer use this one;
instead use #replaceAll:with:from:to: for ST-80 compatibility.

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

replaceAll: oldObject with: newObject

replace all oldObjects by newObject in the receiver.

Notice: This operation modifies the receiver, NOT a copy;
therefore the change may affect all others referencing the receiver.

Usage example(s):

     '123123abc123' replaceAll:$1 with:$*
     #(1 2 3 4 1 2 3 4) copy replaceAll:1 with:'one'

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

replaceAllForWhich: aConditionBlock with: newObject

replace all elements for which aConditionBlock returns true
between startIndex and endIndex, by newObject in the receiver.

Notice: This operation modifies the receiver, NOT a copy;
therefore the change may affect all others referencing the receiver.

replaceAllForWhich: aConditionBlock with: newObject from: startIndex to: stopIndex

replace all elements for which aConditionBlock returns true
between startIndex and endIndex, by newObject in the receiver.

Notice: This operation modifies the receiver, NOT a copy;
therefore the change may affect all others referencing the receiver.

replaceAllIdentical: oldObject with: newObject

replace all oldObjects by newObject in the receiver.
This is like #replaceAll:with:from:to:, but uses an identity compare.

Notice: This operation modifies the receiver, NOT a copy;
therefore the change may affect all others referencing the receiver.

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'

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

replaceAny: aCollection by: newObject

backward ST/X compatibility; alias for #replaceAny:with:.
Pleace do no longer use this one;
instead use #replaceAny:with: for naming consistence.

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

replaceAny: aCollection by: newObject from: startIndex to: stopIndex

backward ST/X compatibility; alias for #replaceAny:with:from:to:.
Pleace do no longer use this one;
instead use #replaceAny:with:from:to: for naming consistence.

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

replaceAny: aCollection with: newObject

replace all elements, which are in aCollection, by newObject.

Notice: This operation modifies the receiver, NOT a copy;
therefore the change may affect all others referencing the receiver.

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:$_

replaceAny: aCollection with: newObject from: startIndex to: stopIndex

within a range, replace all elements,
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  
     '123123abc123' replaceAny:'12' with:$* from:1 to:6  
     #('foo' 'bar' 'foo' 'baz' foo 1 2 3) replaceAny:#(foo 1) with:'*'

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'

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

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'

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

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'

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

     |v1 v2|
     v1 := #u32(1 2 3 4 5 6 7 8 9).
     v2 := #u32(10 20 30 40 50 60 70 80 90).
     v1 replaceFrom:5 with:v2 startingAt:7.
     v1

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'

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

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.

Usage example(s):

     |s|
     s := 'abcdefghijklmnop'.
     '1234567890' startingAt:1 replaceElementsIn:s from:1 to:3.
     s'123defghijklmnop'

inspecting

inspector2GraphTabUseful
( an extension from the stx:libtool package ): is a graph tab useful (in general for this type of collection)?
inspector2HasElementsForGraphTab
( an extension from the stx:libtool package ): should a graph tab be shown (are my elements ok)?
inspector2TabGraph
( an extension from the stx:libtool package ): an extra tab showing the graph
inspectorExtraAttributes
( an extension from the stx:libtool package ): extra (pseudo instvar) entries to be shown in an inspector.
inspectorValueListIconFor: anInspector
( an extension from the stx:libtool package ): returns the icon to be shown alongside the value list of an inspector

misc

entropy: unitString

compute the antropy of the receiver
This measures the disorder of the elements.
Higher values indicate more 'disorder'.
Can be used to determine if data is compressed or encrypted (eg. a binary file).
Code adapted from the article:
https://reverseengineering.stackexchange.com/questions/21555/what-is-an-entropy-graph.
The unitString argument defines which value the measurement should be based upon.
The names and values are:
'shannon' . 2.0 .
'natural' . Float e .
'hartley' . 10.0 .
'somrand' . 256.0 .

Definition:
Entropy is a measurement of the appearance of 'randomness' of bytes.
For example, if you were to take the entropy of the text content of a post,
and then take the entropy of a SHA-512 hash or RSA ciphertext,
you will see a dramatic increase in the hash and RSA ciphertext
over the plaintext content of the post.
There are known entropy levels for plaintext English, for instance.
(i.e. it can also be used to get a hint on the language

Usage example(s):

     c'abcde\x80\x90\xff\xfe\xde' entropy:'shannon'  -> 3.32192809488736
     c'abcde\x80\x90\xff\xfe\xde' entropy:'natural'  -> 2.30258509299405
     c'abcde\x80\x90\xff\xfe\xde' entropy:'hartley'  -> 1.0
     c'abcde\x80\x90\xff\xfe\xde' entropy:'somrand'  -> 0.41524101186092

     c'aaaaa\x61\x61\x61\x61\x61' entropy:'shannon'  -> 0.0
     c'aaaaa\x61\x61\x61\x61\x61' entropy:'natural'  -> 0.0
     c'aaaaa\x61\x61\x61\x61\x61' entropy:'hartley'  -> 0.0
     c'aaaaa\x61\x61\x61\x61\x61' entropy:'somrand'  -> 0.0

     Examples: 
        word based entropies of an english text vs. entropy of a german text.
        (notice, french and german have a higher entropy value than english)

     'compute the entropy of the receiver
     This measures the disorder of the elements.
     Higher values indicate more disorder.
     Can be used to determine if data is compressed or encrypted (eg. a binary file).
     Code adapted from the article:
     https://reverseengineering.stackexchange.com/questions/21555/what-is-an-entropy-graph.
     Definition:
        Entropy is a measurement of the appearance of randomness of bytes. 
        For example, if you were to take the entropy of the text content of a post, 
        and then take the entropy of a SHA-512 hash or RSA ciphertext, 
        you will see a dramatic increase in the hash and RSA ciphertext 
        over the plaintext content of the post. 
        There are known entropy levels for plaintext English, for instance.
     ' asCollectionOfWords entropy:'natural'    
            -> 3.94304048329486
            character based entropy: 2.96301083747822 (ie. without asCollectionOfWords)

     'Berechnen Sie die Entropie des Empfängers
      Diese misst die Randomness der Elemente.
      Höhere Werte zeigen mehr Unordnung an.
      Kann verwendet werden, um festzustellen, ob Daten komprimiert oder verschlüsselt sind (z. B. eine Binärdatei).
      Code aus dem Artikel angepasst:
      https://reverseengineering.stackexchange.com/questions/21555/what-is-an-entropy-graph.
      Definition:
         Die Entropie ist ein Maß für das Auftreten der Zufälligkeit von Bytes.
         Wenn Sie beispielsweise die Entropie des Textinhalts eines Beitrags übernehmen möchten,
         und dann die Entropie eines SHA-512-Hash oder RSA-Chiffretextes nehmen,
         Sie werden einen dramatischen Anstieg des Hash- und RSA-Chiffretextes feststellen
         über den Klartextinhalt des Beitrags.
         Es sind beispielsweise Entropieebenen für Klartext-Englisch bekannt
     ' asCollectionOfWords entropy:'natural'    
            -> 4.21327644090403
            character based: 3.08925293292496

     'calculer l''entropie du receveur
     Cela mesure le désordre des éléments.
     Des valeurs plus élevées indiquent plus de désordre.
     Peut être utilisé pour déterminer si les données sont compressées ou cryptées (par exemple, un fichier binaire).
     Code adapté de l''article :
     https://reverseengineering.stackexchange.com/questions/21555/what-is-an-entropy-graph.
     Définition:
        L''entropie est une mesure de l''apparition du caractère aléatoire des octets.
        Par exemple, si vous deviez prendre l''entropie du contenu textuel d''un message,
        puis prenez l''entropie d''un hachage SHA-512 ou d''un texte chiffré RSA,
        vous verrez une augmentation spectaculaire du texte chiffré par hachage et RSA
        sur le contenu en clair du message.
        Il existe des niveaux d''entropie connus pour l''anglais en clair, par exemple.
     ' asCollectionOfWords entropy:'natural'  
            -> 4.28007226957418
            character based: 3.04643089638433

     Examples: 
        character based entropies of a zipped english text vs. its plain text.

     (ZipStream compress:'compute the entropy of the receiver
     This measures the disorder of the elements.
     Higher values indicate more disorder.
     Can be used to determine if data is compressed or encrypted (eg. a binary file).
     Code adapted from the article:
     https://reverseengineering.stackexchange.com/questions/21555/what-is-an-entropy-graph.
     Definition:
        Entropy is a measurement of the appearance of randomness of bytes. 
        For example, if you were to take the entropy of the text content of a post, 
        and then take the entropy of a SHA-512 hash or RSA ciphertext, 
        you will see a dramatic increase in the hash and RSA ciphertext 
        over the plaintext content of the post. 
        There are known entropy levels for plaintext English, for instance.
     ' ) entropy:'natural'       
            -> 5.17826283884597

     ('compute the entropy of the receiver
     This measures the disorder of the elements.
     Higher values indicate more disorder.
     Can be used to determine if data is compressed or encrypted (eg. a binary file).
     Code adapted from the article:
     https://reverseengineering.stackexchange.com/questions/21555/what-is-an-entropy-graph.
     Definition:
        Entropy is a measurement of the appearance of randomness of bytes. 
        For example, if you were to take the entropy of the text content of a post, 
        and then take the entropy of a SHA-512 hash or RSA ciphertext, 
        you will see a dramatic increase in the hash and RSA ciphertext 
        over the plaintext content of the post. 
        There are known entropy levels for plaintext English, for instance.
     ' ) entropy:'natural'       
            -> 2.96301083747822

obsolete

detectFirstInOrder: sortBlock: marked as obsolete by exept MBP at 17-Jun-2021

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

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

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

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

** This is an obsolete interface - do not use it (it may vanish in future versions) **
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) **
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) **
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) **
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

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

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

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

printOn: aStream withSeparator: aSeparatorStringOrCharacter: #[1 2 3 4 10 17] printOn:Transcript withSeparator:$.
printStringWithSeparator: aSeparatorStringOrCharacter: #[1 2 3 4 10 17] printStringWithSeparator:$.

private-sorting helpers

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

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

firstIndex

return the first elements index

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

isSequenceable

return true, if the receiver is sequenceable,
i.e. if its elements are accessible via the #at: and #at:put: messages
using an integer index, and support the do:-protocol.

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

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]

keys

return a collection with all keys of the receiver

lastIndex

return the last elements index

size

return the number of elements in the collection.
concrete implementations must define this

** This method must be redefined in concrete classes (subclassResponsibility) **

speciesForSubcollection

answer the class, when splitting instances into subcollections

zeroIndex

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

searching

asMapAt: key

the receiver is interpreted as a collection of alternating keys and values;
find key in the receiver and return the corresponding value.
If not found, raise an exception.
Notice, that this does a sequential search (i.e. has O(n) time complexity).
On the other hand, it uses a dense data structure (typically, arrays).
So this is useful for seldom encountered map operations, for which a more
efficient Dictionary is not wanted.

Usage example(s):

     #(
        16   'ipc4' 
        32   'ipc5' 
        128  'ic07'
        256  'ic08'
        512  'ic09'
        1024 'ic10'
      ) asMapAt:128.    -> 'ic07' 

     #(
        16   'ipc4' 
        32   'ipc5' 
        128  'ic07'
        256  'ic08'
        512  'ic09'
        1024 'ic10'
      ) asMapAt:64      -> error

asMapAt: key ifAbsent: exceptionValue

the receiver is interpreted as a collection of alternating keys and values;
find key in the receiver and return the corresponding value.
If not found, return the value from exceptionValue.
Notice, that this does a sequential search (i.e. has O(n) time complexity).
On the other hand, it uses a dense data structure (typically, arrays).
So this is useful for seldom encountered map operations, for which a more
efficient Dictionary is not wanted.

Usage example(s):

     #(
        16   'ipc4' 
        32   'ipc5' 
        128  'ic07'
        256  'ic08'
        512  'ic09'
        1024 'ic10'
      ) asMapAt:128 ifAbsent:nil.   -> 'ic07'  

     #(
        16   'ipc4' 
        32   'ipc5' 
        128  'ic07'
        256  'ic08'
        512  'ic09'
        1024 'ic10'
      ) asMapAt:64 ifAbsent:#xxx.   -> #xxx

asMapKeyAtValue: value ifAbsent: exceptionValue

the receiver is interpreted as a collection of alternating keys and values;
find value in the receiver and return the corresponding key.
If not found, return the value from exceptionValue.
Notice, that this does a sequential search (i.e. has O(n) time complexity).
On the other hand, it uses a dense data structure (typically, arrays).
So this is useful for seldom encountered map operations, for which a more
efficient Dictionary is not wanted.

Usage example(s):

     #(
        16   'ipc4' 
        32   'ipc5' 
        128  'ic07'
        256  'ic08'
        512  'ic09'
        1024 'ic10'
      ) asMapKeyAtValue:'ic09' ifAbsent:nil.  

     #(
        16   'ipc4' 
        32   'ipc5' 
        128  'ic07'
        256  'ic08'
        512  'ic09'
        1024 'ic10'
      ) asMapKeyAtValue:#xxx ifAbsent:-1.

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

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']

detectFirstAndLastWhenSortedBy: sortBlock

find the first and last elements of the collection
when sorted with sortBlock.
I.e. returns the smallest and largest elements,
as defined by sortBlock.
This does the same as:
Array with:(self sort:sortBlock) first
with:(self sort:sortBlock) last
but faster (without actually sorting)
If multiple elements compare the same, the first such are returned

Usage example(s):

the shortest and longest string:
     #('a' 'abc' 'abcdef') detectFirstAndLastWhenSortedBy:[:a :b | a size < b size]

     the min and max values (could also be done by #minMaz)
     #(1 16 7 98 3 19 4 0) detectFirstAndLastWhenSortedBy:[:a :b | a < b]

     the max and min values 
     #(1 16 7 98 3 19 4 0) detectFirstAndLastWhenSortedBy:[:a :b | a > b]

     the min and max values (again)
     #(1 -1 16 -16 7 -7 98 -98) detectFirstAndLastWhenSortedBy:[:a :b | a < b]

     the elements with the smallest and largest abs value
     #(1 -1 16 -16 7 -7 98 -98) detectFirstAndLastWhenSortedBy:[:a :b | a abs < b abs]

detectFirstWhenSortedBy: sortBlock

find the first element of the collection sorted with sortBlock.
I.e. returns the smallest element, as defined by sortBlock.
This does the same as:
(self sort:sortBlock) first
but faster (without actually sorting).
Returns nil, if the receiver is empty.
If multiple elements compare the same, the first such is returned

Usage example(s):

the shortest string:
     #('a' 'abc' 'abcdef') detectFirstWhenSortedBy:[:a :b | a size < b size]

     the smallest value (could also be done with #min)
     #(1 16 7 98 3 19 4 0) detectFirstWhenSortedBy:[:a :b | a < b]

     the largest value (could also be done with #max)
     #(1 16 7 98 3 19 4 0) detectFirstWhenSortedBy:[:a :b | a > b]
     
     the smallest value again
     #(1 -1 16 -16 7 -7 98 -98) detectFirstWhenSortedBy:[:a :b | a < b]

     the value with the smallest absolute value 
     #(1 -1 16 -16 7 -7 98 -98) detectFirstWhenSortedBy:[:a :b | a abs < b abs]

detectFirstWhenSortedBySelector: selector

find the first element of the collection sorted with sortBlock.
I.e. returns the smallest element, as defined by sortBlock.
This does the same as:
(self sort:sortBlock) first
but faster (without actually sorting).
Returns nil, if the receiver is empty.
If multiple elements compare the same, the first such is returned

Usage example(s):

the shortest string:
     #('a' 'abc' 'abcdef') detectFirstWhenSortedBySelector:#size

     the value with the smallest absolute value 
     #(1 -1 16 -16 7 -7 98 -98) detectFirstWhenSortedBySelector:#abs

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'

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

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.
If multiple elements compare the same, the first such is returned

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']

detectLastWhenSortedBy: sortBlock

find the last element of the collection sorted with sortBlock.
I.e. returns the largest element, as defined by sortBlock.
This does the same as:
(self sort:sortBlock) last
but faster (without actually sorting).
Returns nil, if the receiver is empty.
If multiple elements compare the same, the first such is returned

Usage example(s):

the longest string:
     #('a' 'abc' 'abcdef') detectLastWhenSortedBy:[:a :b | a size < b size]

     the largest value (could also be done with #max)
     #(1 16 7 98 3 19 4 0) detectLastWhenSortedBy:[:a :b | a < b]

     the smallest value (could also be done with #min)
     #(1 16 7 98 3 19 4 0) detectLastWhenSortedBy:[:a :b | a > b]

     the largest value (again)
     #(1 -1 16 -16 7 -7 98 -98) detectLastWhenSortedBy:[:a :b | a < b]

     the value with the largest absolute value 
     #(1 -1 16 -16 7 -7 98 -98) detectLastWhenSortedBy:[:a :b | a abs < b abs]

detectLastWhenSortedBySelector: selector

find the last element of the collection sorted with sortBlock.
I.e. returns the largest element, as defined by sortBlock.
This does the same as:
(self sort:sortBlock) last
but faster (without actually sorting).
Returns nil, if the receiver is empty.
If multiple elements compare the same, the first such is returned

Usage example(s):

the longest string:
     #('a' 'abc' 'abcdef') detectLastWhenSortedBySelector:#size

     the value with the largest absolute value 
     #(1 -1 16 -16 7 -7 98 -98) detectLastWhenSortedBySelector:#abs

elementAfter: someValue

find the index of someValue, then return the element after it.
If someValue is not found, raise an exception.
Can be used to use a literal array for a poor-man's mapping collection

Usage example(s):

     #( 'one'  1  
        'two'  2
        'three' 3
     ) elementAfter:'two'    -> 2

     #( 'one'  1  
        'two'  2
        'three' 3
     ) elementAfter:'four'   -> error

elementAfter: someValue ifNone: exceptionValue

find the index of someValue, then return the element after it.
If someValue is not found, return the value from exceptionValue.
Can be used to use a literal array for a poor-man's mapping collection

Usage example(s):

     #( 'one'  1  
        'two'  2
        'three' 3
     ) elementAfter:'two' ifNone:0   -> 2

     #( 'one'  1  
        'two'  2
        'three' 3
     ) elementAfter:'four' ifNone:0  -> 0

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,
whereas #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

findFirst: aBlock startingAt: startIndex

find the index of 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

findFirst: aBlock startingAt: startIndex ifNone: exceptionalValue

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

findFirstWithIndex: aBlock ifNone: exceptionalValue

find the index of the first element, for which evaluation of the argument,
aBlock returns true.
The block gets both the element and the corresponding index as args.
Return the index or the value from exceptionalValue if none detected.

Usage example(s):

     #(0 1 2 3 4 5 6 1 2 3 4) findFirstWithIndex:[:el :idx | (el == 3) and:[idx > 4]] ifNone:0
     #(0 1 2 3 4 5 6 1 2  4) findFirstWithIndex:[:el :idx | (el == 3) and:[idx > 4]] ifNone:0

findLast: aBlock ifNone: exceptionalValue

Find the last element, for which evaluation of the argument, aBlock returns true.
Start the backward search at the end of the collection.
Return its index or the value from exceptionValue if none detected.
This is much like #detectLast:, however, here an INDEX is returned,
whereas #detectLast: returns the element.

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.
This is much like #detectLast:, however, here an INDEX is returned,
whereas #detectLast: returns the element.

Usage example(s):

     #(1 99 3 99 5 6) findLast:[:x | (x == 99)] startingAt:3
     'one.two.three' findLast:[:c | (c == $.)] startingAt:7

findLast: aBlock startingAt: startIndex endingAt: endIndex

find the last element, for which evaluation of the argument, aBlock returns true.
Start the backward search at startIndex.
End the search at endIndex or when an element is found.
Return its index or 0 if none detected.
This is much like #detectLast:, however, here an INDEX is returned,
whereas #detectLast: returns the element.

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

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'

indexOfSubCollection: aCollection ifAbsent: exceptionBlock

find a subcollection. If found, return the index;
if not found, return the result of evaluating exceptionBlock.

indexOfSubCollection: aCollection startingAt: startIndex

find a subcollection starting at index.
If found, return the index; if not found, return 0.

indexOfSubCollection: aCollection startingAt: startIndex 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

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,
and we might need a specialized version in Array

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)

     #(1 2 3 4 5 6 7) indexOfSubCollection:#(6 7 8)  startingAt:2 ifAbsent:-1  
     #(1 2 3 4 5 6 7) indexOfSubCollection:#(6 7)  startingAt:2 ifAbsent:-1  
     #(1 2 3 4 5 6 7) indexOfSubCollection:#(6 8)  startingAt:2 ifAbsent:-1

lastIndexOfSubCollection: aCollection

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

lastIndexOfSubCollection: aCollection ifAbsent: exceptionBlock

find a subcollection from the end. If found, return the index;
if not found, return the result of evaluating exceptionBlock.

lastIndexOfSubCollection: aCollection startingAt: startIndex

find a subcollection from the end starting at index.
If found, return the index; if not found, return 0.

lastIndexOfSubCollection: aCollection startingAt: startIndex ifAbsent: exceptionBlock

find a subcollection from the end, starting at index. If found, return the index;
if not found, return the result of evaluating exceptionBlock.
This is a q&d hack - not very efficient

Usage example(s):

     #(1 2 3 4 5 6 7) lastIndexOfSubCollection:#()  startingAt:2         => 0
     #(1 2 3 4 5 6 7) lastIndexOfSubCollection:#(1)                      => 1
     #(1 2 3 4 5 6 7) lastIndexOfSubCollection:#(1) startingAt:4         => 1
     #(1 3 1 2 1 3 3) lastIndexOfSubCollection:#(1 2 3)                  => 0
     #(1 2 1 2 1 2 3) lastIndexOfSubCollection:#(1 2 3) startingAt:2     => 0
     #(1 2 1 2 1 2 3) lastIndexOfSubCollection:#(1 2 3)                  => 5
     #(1 2 1 2 1 2 3) lastIndexOfSubCollection:#(1 2)                    => 5
     #(1 2 1 2 1 2 3) lastIndexOfSubCollection:#(1 2)   startingAt:5     => 5
     #(1 2 1 2 1 2 3) lastIndexOfSubCollection:#(1 2)   startingAt:4     => 3

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 values argument.
If not found, return the value from exceptionValue.
Notice, that this does a sequential search (i.e. has O(n) time complexity).
On the other hand, it uses dense data structures (typically, arrays).
So this is useful for seldom encountered map operations, for which a more
efficient Dictionary is not wanted.

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

identityIndexOf: anElement startingAt: start step: step

search the collection for anElement, starting the search at index start;
if found, return the index otherwise return 0.
Only look at every step element.
The comparison is done using =
(i.e. equality test - not identity test).

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

includesViaBinarySearch: anObject

This method applies only to collections, that are sorted in ascending order!
Return true, if the argument, anObject is in the collection.
In contrast to #includes:, since due to being sorted, the inclusion check can
be done with log-n compares i.e. much faster.

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

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']

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

Usage example(s):

     |a|

     a := #(10 20 30 40 50 60 70).
     (a indexOf:30 replaceWith:nil startingAt:1 stoppingAt:7) printNL.
     a printNL.

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

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

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']

indexOf: anElement startingAt: start step: step

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

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)

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       => 7
     #(10 20 30 40 10 20 30 40) indexOfAny:#(40.0 50 30.0) startingAt:5   => 7
     #(10 20 30 40 10 20 30 40) indexOfAny:#(40.0 50) startingAt:1        => 4
     #(10 20 30 40 10 20 30 40) indexOfAny:#(40.0 30.0) startingAt:1      => 3

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']

indexViaBinarySearchOf: anObject startingAt: firstIndex

This method applies only to collections, that are sorted in ascending order!
Search the collection for an anObject,
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).
In contrast to #indexOf:startingAt, since due to being sorted, the inclusion check can
be done with log-n compares i.e. much faster.

Usage example(s):

      TimeDuration toRun:[ 
        1000 timesRepeat:[
            (1 to: 10000000) indexViaBinarySearchOf:8000000 startingAt:1.
            (1 to: 10000000) indexViaBinarySearchOf:10000001 startingAt:1.
        ].    
      ]. 

      TimeDuration toRun:[        
        1000 timesRepeat:[
            (1 to: 10000000) indexOf:8000000 startingAt:1.
            (1 to: 10000000) indexOf:10000001 startingAt:1.
        ].    
      ].

indicesOf: anElement

search the collection for all occurrences of anElement;
return a collection of indices, or an empty collection if not found.
The comparison is done using =
(i.e. equality test - not identity test).

lastIndexOf: anElement

search the collection backwards for anElement;
if found, return the index otherwise return 0.
The comparison is done using =
(i.e. equality test - not identity test).

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

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']

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

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']

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)

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

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

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']

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

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

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

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']

identityIndexOf: anElement or: anotherElement

search the collection for anElement and anotherElement using identity compare (i.e. ==);
if any is found, return the index otherwise return 0.

identityIndexOf: anElement or: anotherElement startingAt: start

search the collection for anElement and anotherElement, starting search at index start
using identity compare (i.e. ==);
if any is found, return the index otherwise return 0.

Usage example(s):

     #(10 20 30 40 10 20 30 40) identityIndexOf:40 or:30  startingAt:2

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

identityIndexOf: anElement startingAt: start endingAt: stop

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']

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

indexOfNonNilElement

#(10 20 30 40 50 60 70) indexOfNonNilElement => 1
#(nil nil nil 10 20 30 40 50 60 70) indexOfNonNilElement => 4
#(nil nil nil nil nil) indexOfNonNilElement => 0

indexOfNonNilElementStartingAt: startIndex

search the collection for the first non-nil element;
return index if found, 0 otherwise

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

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']

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

lastIdentityIndexOf: anElement startingAt: start ifAbsent: exceptionBlock

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

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 ]

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.
If already present, make sure, to move the original element already in the collection
instead of exchanging it by anElement.

removeAndAddFirst: anElement limitSizeTo: maxSize

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.
If the receiver's size grows over maxSize, then the last element is removed,
to implement a history behavior (keep the last maxSize used elements)

removeAndAddLast: anElement

if the anElement is in the receiver collection (compare by equality), remove it;
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.
If already present, make sure, to move the original element already in the collection
instead of exchanging it by anElement.

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

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

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

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

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).
WARNING: this is a destructive operation, which modifies the receiver.

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]

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).
WARNING: this is a destructive operation, which modifies the receiver and aCollection.

Usage example(s):

     |c1 c2|
     c1 := #(1 16 7 9).
     c2 := #('one' 'sixteen' 'seven' 'nine').
     c1 sort:[:a :b | a > b] with:c2.
     c1 printNL.
     c2 printNL

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.
WARNING: this is a destructive operation, which modifies the receiver.

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.
WARNING: this is a destructive operation, which modifies the receiver.

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.
WARNING: this is a destructive operation, which modifies the receiver.

sortIgnoringCase

Sort my contents inplace based on a case-ignoring string compare.
If an elements is no string, it should know how to convert to one.
WARNING: this is a destructive operation, which modifies the receiver.

Usage example(s):

     #('aaa' 'BBB' 'AA' 'zz' 'ZZ') copy sort              => #('AA' 'BBB' 'ZZ' 'aaa' 'zz')
     #('aaa' 'BBB' 'AA' 'zz' 'ZZ') copy sortIgnoringCase  => #('AA' 'aaa' 'BBB' 'zz' 'ZZ')

sortIgnoringCaseBySelector: aSelector

Sort my contents inplace based on the value of what aSelector returns
when sent to my elements. The sort is ignoring case differences.
Sorting by a selector is so common, that its worth a separate utility.
WARNING: this is a destructive operation, which modifies the receiver.

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).
WARNING: this is a destructive operation, which modifies the receiver and aCollection.

Usage example(s):

     |indices names|

     names := #('nine' 'five' 'eight' 'one' 'four' 'two') copy.
     indices := #(9 5 8 1 4 2) copy.
     indices sortWith:names.
     names.
     indices

sorted

return a copy of the receiver with sorted elements.
The elements are compared using '<'
i.e. they should offer a magnitude-like protocol.

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

Usage example(s):

     #(1 16 7 98 3 19 4 0) sorted

sortedBy: compareBlock

return a copy of the receiver with sorted elements.
For two given aruments a and b, the compareBlock should return true if a '<' b.

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) sortedBy:[:a :b | a > b]             => #(98 19 16 7 4 3 1 0) 
     #(1 16 7 -98 3 -19 4 0) sortedBy:[:a :b | a abs < b abs]   => #(0 1 3 4 7 16 -19 -98)

stableSort

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

Uses a stable sort algorithm - i.e. elements having an equal key will keep
their previous order.
WARNING: this is a destructive operation, which modifies the receiver.

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

stableSort: sortBlock

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

Uses 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.
WARNING: this is a destructive operation, which modifies the receiver.

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]

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.

WARNING: this is a destructive operation, which modifies the receiver.

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

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

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.

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.

heapSortFrom: begin to: end

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

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)

insertionSort: sortBlock

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

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

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)

Usage example(s):

     |random data|

     random := Random new next:500000.

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

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

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

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

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)

Usage example(s):

     #(1 16 7 98 3 19 4 0) quickSort:[:a :b | a < b]
     #(1 16 7 98 3 19 4 98 0) quickSort:[:a :b | a <= b]
     #(1 16 7 98 3 19 4 0) quickSort:[:a :b | a > b]
     #(1 -1 16 -16 7 -7 98 -98) quickSort:[:a :b | a < b]
     #(1 -1 16 -16 7 -7 98 -98) quickSort:[:a :b | a <= b]
     #(1 -1 16 -16 7 -7 98 -98) quickSort:[:a :b | a abs < b abs]
     TimeDuration toRun:[
        Symbol allSymbols quickSort:[:a :b | a <= b].
     ]    
     TimeDuration toRun:[
        Symbol allSymbols quickSort:[:a :b | a < b].
     ]

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)

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

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

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

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.
If the receiver starts with anElement, an initial empty collection is added.
If the receiver ends with anElement, NO final empty collection is added.
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: $-.
     '-foo-bar-baz' asCollectionOfSubCollectionsSeparatedBy: $-.
     'foo-bar-baz-' asCollectionOfSubCollectionsSeparatedBy: $-.
     '-foo-bar-baz-' asCollectionOfSubCollectionsSeparatedBy: $-.
     'foobarbaz' asCollectionOfSubCollectionsSeparatedBy: $-. 
     '' asCollectionOfSubCollectionsSeparatedBy: $-.

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]

asCollectionOfSubCollectionsSeparatedByAll: aSeparatorCollection

return a collection containing the subcollections (separated by aSeparatorCollection)
of the receiver. If aSeparatorCollection occurs multiple times in a row,
the result may contain empty strings.
Uses equality-compare when searching for aSeparatorCollection.

Usage example(s):

     '1::2::3::4::5::' asCollectionOfSubCollectionsSeparatedByAll:'::'
     '::2' asCollectionOfSubCollectionsSeparatedByAll:'::'
     #(1 2 3 1 2 3 4 3 1 1 2 3 1 4 5) asCollectionOfSubCollectionsSeparatedByAll:#(3 1)
     'hello+#world+#here' asCollectionOfSubCollectionsSeparatedByAll:'+#'

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:'+#'

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)

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

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 = $:]
     '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]

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]

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:$|

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

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.

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.

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

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

asStringWithCRsFrom: firstLine to: lastLine compressTabs: compressTabs

return part of myself as a string with embedded cr's.
My elements must be strings or nil.
If the argument compressTabs is true, leading spaces are converted
to tab-characters (8col tabs).
Nil entries and empty strings are taken as empty lines.

asStringWithCRsFrom: firstLine to: lastLine compressTabs: compressTabs withCR: withCR

return part of myself as a string with embedded cr's.
My elements must be strings or nil; nil entries and empty strings are
taken as empty lines.
If the argument compressTabs is true, leading spaces are converted
to tab-characters (8col tabs). WithCR controls whether the last line
should be followed by a cr or not.

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:$:

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

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:'***'

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:' | '

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.

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 ]

splitAt: index

return a collection containing two subcollections of the receiver,
the first containing elements upTo index, the second containing remaining elements.
Raises an error, if index is greater than the receiver's size

Usage example(s):

     'helloworld' splitAt:5.    
     #(a b c d e f g h) splitAt:4. 
     #(a b c d e f g h) splitAt:0.   
     #(a b c d e f g h) splitAt:20.

splitAtEach: indexCollection

return a collection containing subcollections of the receiver,
the first containing elements upTo the first index in indexCollection,
the second containing elements from there to the next index etc.
Raises an error, if any index is greater than the receiver's size

Usage example(s):

     'helloworld' splitAtEach:#(5).    
     '1234567890123456789012' splitAtEach:#(5 10 15).

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.
If the receiver starts with anElement, an initial empty collection is added.
If the receiver ends with anElement, NO final empty collection is added.
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.
     'a;b;c;d' splitBy: $;.

splitBy: anElement do: aBlock

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]

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.
More or less the same as spitOn: (but has been around earlier)

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)

splitByAny: aCollectionOfSeparators

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)

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]

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

splitOn: splitter

Split at any encounter of splitter in the receiver.
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 element
used as split object (i.e. I wil split at that element).
If the splitter is not encountered, a single element collection containing
the receiver is returned

Usage example(s):

     'hello world' splitOn:' '
     'abacadae' splitOn:$a
     'abacadae' splitOn:'a'
     'abaacaadaae' splitOn:'aa'
     'abaacaadaae' splitOn:[:ch | ch == $a]
     'abaacaadaae' splitOn:('a+' asRegex)
     'helloworld' splitOn:' '        
     'helloworld ' splitOn:' '       
     ' helloworld ' splitOn:' '      
     ('a::b;a::b::c;d' splitOn:$;) collect:[:each | each splitOn:'::']      

     #(0 1 2 3 1 4 5 6 1 7 1 9 10) splitOn:1

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

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 ]

splitOnFirst: splitter

Split at the first encounter of splitter in the receiver;
return the two parts or nil, if the splitter was not encountered.
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 element
used as split object (i.e. I wil split at that element).
Returns a two-element collection containing the left and right parts.
If the splitter is not encountered, the returned right part is nil.
If the splitter is encountered at the end, the returned right part is empty

Usage example(s):

     'hello world more there' splitOnFirst:' ' 
     'bacadae' splitOnFirst:$a               
     'abaacaadaae' splitOnFirst:'aa'         
     'baacAadaae' splitOnFirst:[:ch | ch isUppercase]  
     'abaacaadaae' splitOnFirst:('a+' asRegex)
     'helloworld' splitOnFirst:' '  
     'helloworld ' splitOnFirst:' '       

     #(1 2 true 3 4 5) splitOnFirst:true

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

vector arithmetic

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.

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.

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) vectorLength                 => 14.142135623731
     #(10.0 10.0) squaredVectorLength          => 200.0

     #(10.0 10.0 10.0) vectorLength            => 17.3205080756888
     #(10.0 10.0 10.0) squaredVectorLength     => 300.0

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

vectorLength

Return the length of the receiver interpreted as a vector.
That is the length of the vector in N-dimensional space
from the origin (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       => 14.142135623731
     #(10.0 10.0 10.0) vectorLength  => 17.3205080756888

     #(10.0 10.0) asFloatArray vectorLength       => 14.142135623731
     #(10.0 10.0 10.0) asFloatArray vectorLength  => 17.3205080756888

visiting

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

ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Mon, 18 Nov 2024 04:39:07 GMT