eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'Collection':

Home

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

Class: Collection


Inheritance:

   Object
   |
   +--Collection
      |
      +--Bag
      |
      +--BinaryTree
      |
      +--BloomFilter
      |
      +--CharacterSet
      |
      +--Dolphin::SharedSet
      |
      +--FileDirectory
      |
      +--Iterator
      |
      +--KeyedCollection
      |
      +--MappedCollection
      |
      +--PowerSet
      |
      +--PriorityQueue
      |
      +--Queue
      |
      +--SequenceableCollection
      |
      +--Set
      |
      +--SharedCollection
      |
      +--TreeSet
      |
      +--VirtualDictionary

Package:
stx:libbasic
Category:
Collections-Abstract
Version:
rev: 1.480 date: 2019/08/08 17:37:28
user: cg
file: Collection.st directory: libbasic
module: stx stc-classLibrary: libbasic
Author:
Claus Gittinger

Description:


Abstract superclass for all collections.
This abstract class provides functionality common to all collections,
without knowing how the concrete class implements things.
Thus, all methods found here depend on some basic mechanisms
to be defined in the concrete class.
These basic methods are usually defined as #subclassResponsibility here.
Some methods are also redefined for better performance.

Subclasses should at least implement:
    do:     - enumerate elements

they should implement one of the following set of access messages:
For keyed collections:
    at:ifAbsent:            - fetching an element
    at:                     - fetching an element
    at:put:                 - storing an element

For unkeyed collections:
    add:                    - add an element
    remove:ifAbsent:        - remove an element

Given that the above is implemented in a concrete subclass,
Collection provides protocol for enumeration, searching and others.
However, for performance reasons, many of them are also redefined in
concrete subclasses, as some can be implemented much faster if implementation
details are known (for example, searching can be done faster if it is known that
elements are sorted or accessible by a key).


Class protocol:

Compatibility-Squeak
o  ofSize: n
( an extension from the stx:libcompat package )
return a new collection which really provides space for n elements.
Kludges around the stupid definition of OrderedCollection>>new:

JS syntactic sugar
o  with: el1 _: el2
( an extension from the stx:libjavascript package )
for JS easy syntax - allows: Array.with(el1, el2,...)

o  with: el1 _: el2 _: el3
( an extension from the stx:libjavascript package )
for JS easy syntax - allows: Array.with(el1, el2,...)

o  with: el1 _: el2 _: el3 _: el4
( an extension from the stx:libjavascript package )
for JS easy syntax - allows: Array.with(el1, el2,...)

o  with: el1 _: el2 _: el3 _: el4 _: el5
( an extension from the stx:libjavascript package )
for JS easy syntax - allows: Array.with(el1, el2,...)

o  with: el1 _: el2 _: el3 _: el4 _: el5 _: el6
( an extension from the stx:libjavascript package )
for JS easy syntax - allows: Array.with(el1, el2,...)

o  with: el1 _: el2 _: el3 _: el4 _: el5 _: el6 _: el7
( an extension from the stx:libjavascript package )
for JS easy syntax - allows: Array.with(el1, el2,...)

o  with: el1 _: el2 _: el3 _: el4 _: el5 _: el6 _: el7 _: el8
( an extension from the stx:libjavascript package )
for JS easy syntax - allows: Array.with(el1, el2,...)

Signal constants
o  emptyCollectionSignal
return the signal used to report non-allowed operation on empty collections

o  invalidKeySignal
return the signal used to report bad key usage

o  notEnoughElementsSignal
return the signal used to report attempts for an operation, for which
there are not enough elements in the collection

o  valueNotFoundSignal
return the signal used to report a nonexisting element.

initialization
o  initialize
setup the signal

instance creation
o  collect: aCollection usingEnumerator: aBlockOrEnumeratorSelector
apply aBlock or enumeratorSelector to the receiver
and collect the enumerated elements.
If the enumerator is a symbol, it should be the name of an enumerator method (i.e. do:, reverseDo:, etc.).
If it is a block, it should be a two-arg block, expecting the collection first, and
a block to be applied to each element.
Can be used if the collection needs to be enumerated with a different enumerator
(eg. a tree, which implements aka. childrenDo:)

usage example(s):

     OrderedCollection collect:#(1 2 3 4 5) usingEnumerator:#do:
     OrderedCollection collect:#(1 2 3 4 5) usingEnumerator:#reverseDo:
     OrderedCollection collect:#(1 2 3 4 5) usingEnumerator:[:coll :block | coll do:block]
     OrderedCollection collect:#(1 2 3 4 5) usingEnumerator:[:coll :block | coll reverseDo:block]

o  combiningEach: collection1 withEach: collection2 using: aTwoArgBlock
evaluate aTwoArgBlock for each combination of elements from collection1
and collection2 and return an instance of the receiver containing all those elements

usage example(s):

     Set combiningEach:#(1 2 3 4 5) withEach:(10 to:100 by:10) using:[:a :b | a * b] 
     Set combiningEach:#(1 2 3 4 5) withEach:#(1 2 3 4 5) using:[:a :b | a * b] 
     Array combiningEach:#(1 2 3 4 5) withEach:#(1 2 3 4 5) using:[:a :b | a * b] 

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

o  newFrom: aCollection
Return an instance of me containing the same elements as aCollection.

usage example(s):

     Bag newFrom:#(1 2 3 4 4 5 6 7 7 7 )  
     Set newFrom:#(1 2 3 4 4 5 6 7 7 7 ) 

o  newWithCapacity: n
return a new empty Collection preferrably with capacity for n elements.
Redefined in StringCollection, where #new: returns a non-empty collection.
This does not work for ArrayedCollections, which will be not empty.

We return an empty collection here, because there are subclasses
which do not implement #new:.

o  newWithSize: n
return a new non-empty collection with n elements.
Kludges around the inconsistent definition of #new: in
returning an empty collection in OrderedCollection and Set
and
returning an non-empty collection in ArrayedCollectins and StringCollection.

o  with: anObject
return a new Collection with one element:anObject

o  with: firstObject with: secondObject
return a new Collection with two elements:firstObject and secondObject

o  with: firstObject with: secondObject with: thirdObject
return a new Collection with three elements

o  with: firstObject with: secondObject with: thirdObject with: fourthObject
return a new Collection with four elements

o  with: a1 with: a2 with: a3 with: a4 with: a5
return a new Collection with five elements

o  with: a1 with: a2 with: a3 with: a4 with: a5 with: a6
return a new Collection with size elements

o  with: a1 with: a2 with: a3 with: a4 with: a5 with: a6 with: a7
return a new Collection with seven elements

o  with: a1 with: a2 with: a3 with: a4 with: a5 with: a6 with: a7 with: a8
return a new Collection with eight elements

o  withAll: aCollection
return a new Collection with all elements taken from the argument,
aCollection

usage example(s):

        OrderedCollection withAll:#(1 2 3 4 5 6)
        Set withAll:#(1 2 3 4 5 6)
        StringCollection withAll:#('line1' 'line2' 'line3')
        String withAll:#($a $b $c)
        Set withAll:(Iterator on:[:whatToDo | 1 to:10 do:[:i | whatToDo value:i]]).

o  withSize: n
obsolete: please use newWithSize:, for its better name

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

instance creation-streaming
o  writeStreamClass
the type of stream used in writeStream

usage example(s):

     OrderedCollection writeStreamClass

misc ui support
o  iconInBrowserSymbol
( an extension from the stx:libtool package )
the browser will use this as index into the toolbariconlibrary

queries
o  growIsCheap
return true, if this collection can easily grow
(i.e. without a need for become:).
Returns true here; this method is redefined in fix-size
collections

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


Instance protocol:

Compatibility-ANSI
o  identityIncludes: anObject
return true, if the argument, anObject is in the collection.
Same as #includesIdentical for Dolphin/ANSI compatibility.

Compatibility-Dolphin
o  includesAllOf: aCollection
( an extension from the stx:libcompat package )
same as #includesAll for Squeak/Dolphin compatibility.

usage example(s):

     #(1 2 3 4 5 6 7) includesAllOf:#(1 2 3)
     #('hello' 'there' 'world') includesAllOf:#('hello' 'world')
     #(1 2 3 4 5 6 7) includesAllOf:#(7 8 9)
     #(1 2 3 4 5 6 7) includesAllOf:#(8 9 10)

o  includesAnyOf: aCollection
( an extension from the stx:libcompat package )
same as #includesAny for Squeak/Dolphin compatibility.

o  symmetricDifference: aCollection
( an extension from the stx:libcompat package )
return a new set containing all elements,
which are contained in either the receiver or aCollection, but not in both.
Same as xor: - for compatibility

Compatibility-Squeak
o  , aCollection
return a new collection formed from concatenating the receiver with the argument

o  addIfNotPresent: anObject
Include anObject as one of the receiver's elements, but only if there
is no such element already. Answer anObject.

o  anyOne
return any element from the collection.
Report an error if there is none.
Same as #anElement - for Squeak compatibility

o  associationsDo: aBlock
cg: I think this is bad, but - well...

o  collectAsSet: aBlock
( an extension from the stx:libcompat package )
Evaluates aBlock for each element of the receiver and collects
the resulting values into a Set.

o  contents
I am the contents of the collection

o  deepFlatten
( an extension from the stx:libcompat package )

o  deepFlattenInto: stream
( an extension from the stx:libcompat package )

o  detect: aBlock ifOne: presentBlock
( an extension from the stx:libcompat package )

o  detect: aBlock ifOne: presentBlock ifNone: noneBlock
( an extension from the stx:libcompat package )

o  difference: aCollection
Answer the set-theoretic difference of two collections.

usage example(s):

     #(0 2 4 6 8) difference:#(2 4)   

o  do: block displayingProgress: progressMessage
( an extension from the stx:libcompat package )
ProgressNotification handle:[:ex |
Transcript showCR:ex progressValue rounded.
ex proceed.
] do:[
#(0 1 2 3 4 5 6 6 7 8 9)
do:[:i| Delay waitForMilliseconds: 50]
displayingProgress: 'Progress'
].

o  equalsTo: aCollection
( an extension from the stx:libcompat package )
Answer true if the reciever contains the same elements as aCollection, and vice versa.

o  flatCollect: aBlock
( an extension from the stx:libcompat package )
Evaluate aBlock for each of the receiver's elements and answer the
list of all resulting values flatten one level. Assumes that aBlock returns some kind
of collection for each element. Equivalent to the lisp's mapcan

o  flatCollect: aBlock as: aCollectionClass
( an extension from the stx:libcompat package )
Evaluate aBlock for each of the receiver's elements and answer the
list of all resulting values flatten one level. Assumes that aBlock returns some kind
of collection for each element. Equivalent to the lisp's mapcan

o  flatCollectAsSet: aBlock
( an extension from the stx:libcompat package )
Evaluate aBlock for each of the receiver's elements and answer the
list of all resulting values flatten one level. Assumes that aBlock returns some kind
of collection for each element. Equivalent to the lisp's mapcan

usage example(s):

     #((1) (2) (3 -4) (5 (-6 7) 8) (9 10)) flatCollect:[:i | i abs] as:Set
     #((1) (2) (3 -4) (5 (-6 7) 8) (9 10)) flatCollectAsSet:[:i | i abs]

o  flatten
( an extension from the stx:libcompat package )
Recursively collect each non-collection element of the receiver and its descendant
collections. Please note, this implementation assumes that strings are to be treated
as objects rather than as collection.

o  gather: aBlock
return an Array,
containing all elements as returned from applying aBlock to each element of the receiver,
where the block returns a collection of to-be-added elements.
This could also be called: collectAllAsArray:

usage example(s):

     (Set withAll:#(10 20 30 10 20 40)) gather:[:el | Array with:el with:el * 2]

o  gather: aBlock as: aClass
return an instance of the collection-class aClass,
containing all elements as returned from applying aBlock to each element of the receiver.
where the block returns a collection of to-be-added elements.
This could also be called: collectAll:as:

usage example(s):

     (Set withAll:#(10 20 30 10 20 40)) gather:[:el | Array with:el with:el * 2] as:OrderedCollection
     (Set withAll:#(10 20 30 10 20 40)) collectAll:[:el | Array with:el with:el * 2]

o  groupBy: keyBlock having: selectBlock
Like in SQL operation - Split the receiver's contents into collections of
elements for which keyBlock returns the same results, and return those
collections allowed by selectBlock.

usage example(s):

     #(1 2 3 4 5 6 7 8 9) groupBy:[:e | e odd] having:[:a | true]  

o  groupedBy: aBlock
( an extension from the stx:libcompat package )
Return a dictionary whose keys are the result of evaluating aBlock for all elements in
the collection, and the value for each key is the collection of elements that evaluated
to that key. e.g.
#(1 2 3 4 5) groupedBy: [:each | each odd]
a Dictionary
true ---> #( 1 3 5)
false --> #(2 4)
originally developed by a. kuhn and released under MIT.

o  groupedBy: aBlock affect: anotherBlock
( an extension from the stx:libcompat package )
First, evaluate aBlock for each of the receiver's elements and group the
elements by the resulting values, and second, evaluate anotherBlock for
each of the resulting groups and return a dictionary with the first pass'
results as keys and the second pass' results as values.

usage example(s):

This is a shorthand for [ (self groupedBy: aBlock) collect: anotherBlock ].

o  ifEmpty: alternativeValue
return the receiver if not empty, alternativeValue otherwise

usage example(s):

     'foo' ifEmpty: 'bar'
     '' ifEmpty: 'bar'
     '' ifEmpty: [ Time now printString ]

o  ifEmpty: ifEmptyValue ifNotEmpty: ifNotEmptyValue
return ifNotEmptyValue if not empty, ifEmptyValue otherwise

o  ifEmpty: ifEmptyValue ifNotEmptyDo: ifNotEmptyValue
return ifNotEmptyValue if not empty, ifEmptyValue otherwise

o  ifEmptyDo: ifEmptyValue ifNotEmpty: ifNotEmptyValue
return ifNotEmptyValue if not empty, ifEmptyValue otherwise

o  ifNotEmpty: ifNotEmptyValue
return ifNotEmptyValue if not empty, nil otherwise

o  ifNotEmptyDo: ifNotEmptyValue
return ifNotEmptyValue if not empty, nil otherwise

o  ifNotEmptyDo: ifNotEmptyValue ifEmpty: ifEmptyValue
return ifNotEmptyValue if not empty, ifEmptyValue otherwise

o  intersection: aCollection
( an extension from the stx:libcompat package )
same as intersect: for Squeak compatibility

o  nilSafeGroupedBy: aBlock
( an extension from the stx:libcompat package )

o  selectAsSet: aBlock
( an extension from the stx:libcompat package )
Evaluate aBlock with each of the receiver's elements as the argument.
Collect into a new set, only those elements for which
aBlock evaluates to true. Answer the new collection.

o  sorted: aBlock
( an extension from the stx:libcompat package )
Create a copy that is sorted. Sort criteria is the block that accepts two arguments.
When the block is true, the first arg goes first ([:a :b | a > b] sorts in descending order).

JavaScript support
o  forEach: aBlock
( an extension from the stx:libjavascript package )
same as do: for javaScript

o  length
( an extension from the stx:libjavascript package )
returns the length of the collection

usage example(s):

     JavaScriptParser
        evaluate:'''hello''.length'

accessing
o  anElement
return any element from the collection,
report an error if there is none.
Use this to fetch the some element from a collection which is non-indexed or which
has a non-numeric index. I.e. if someone gets an arbitrary collection which might be either indexable
or not, anElement is a save way to access some element without a need to check for a proper key.

usage example(s):

     #() anElement             -> Error
     #(1 2 3) anElement        -> 1
     #(1 2 3) asSet anElement  -> one of them (undefined, which one)

o  at: index add: anObject
assuming that the receiver is an indexed collection of collections,
retrieve the collection at index, and add anObject to it.
Raise an error, of there is no collection at that index (or the index is invalid).
Typically used with dictionaries of sets.

usage example(s):

     (Dictionary new 
        at:'one' put:Set new;
        at:'two' put:Set new;
        yourself)
            at:'one' add:1;
            at:'two' add:2;
            at:'one' add:11;
            at:'two' add:22;
            yourself.

o  at: aKey ifAbsent: absentBlock
return the element at aKey if valid.
If the key is not present, return the result of evaluating
the exceptionblock.
NOTICE:
in ST-80, this message is only defined for Dictionaries,
however, having a common protocol with indexed collections
often simplifies things.

usage example(s):

     #(1 2 3 4) at:5 ifAbsent:['bla']

o  at: index ifAbsentPut: initializerValue add: anObject
assuming that the receiver is an indexed collection of collections,
retrieve the collection at index, and add anObject to it.
If there is no collection at that index put the value of initializerValue there
and add to that.
Typically used with dictionaries of sets.

usage example(s):

     (Dictionary new 
        at:'one' put:Set new;
        at:'two' put:Set new;
        yourself)
            at:'one' add:1;
            at:'two' add:2;
            at:'one' add:11;
            at:'two' add:22;
            yourself.

o  at: aKey ifNilOrAbsentPut: valueBlock
try to fetch the element at aKey. If either the key is invalid (as in a Dictionary)
or there is no element stored under that key (as in an Array), set the element
from the valueBlock and return it.
Useful for lazy initialization of collections.

o  atAll: indexCollection put: anObject
put anObject into all indexes from indexCollection in the receiver.
This abstract implementation requires that the receiver supports
access via a key (and indexCollection contains valid keys).

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) atAll:(1 to:5) put:0
     (Array new:10) atAll:#(1 5 6 9) put:0
     (Dictionary new) atAll:#(foo bar baz) put:'hello' 

    raises an error:
     (Set new) atAll:#(foo bar baz) put:'hello' 

o  atAny: aCollectionOfKeysTriedInSequence ifAbsent: absentBlock
try aCollectionOfKeysTriedInSequence and return the element at
the first found valid key.
If none of the keys is not present, return the result of evaluating
the exceptionblock.

o  decrementAt: aKey
remove 1 from the count stored under aKey.
If not yet present, assume 0 as initial counter value.

o  fifth
return the fifth element of the collection.
For unordered collections, this simply returns the fifth
element when enumerating them.
This should be redefined in subclasses.

usage example(s):

     #(1 2 3 4 5) fifth

o  first
return the first element of the collection.
For unordered collections, this simply returns the first
element when enumerating them.
This should be redefined in subclasses.

o  first: n
return the n first elements of the collection.
No longer raises an error if there are not enough elements;
instead, returns what is there.

For unordered collections, this simply returns the first
n elements when enumerating them.
(Warning: the contents of the returned collection is not deterministic in this case).
This should be redefined in subclasses.

usage example(s):

     #(1 2 3 4 5) first:3
     #(1 2 3 4 5) asSet first:3
     #(1 2 3) first:5
     #(1 2 3) asSet first:5

o  firstIfEmpty: exceptionValue
return the first element of the collection.
If it's empty, return the exceptionValue.
(i.e. don't trigger an error as done in #first)

o  firstOrNil
return the first element of the collection.
If it's empty, return nil.
(i.e. don't trigger an error as done in #first)

o  fourth
return the fourth element of the collection.
For unordered collections, this simply returns the fourth
element when enumerating them.
This should be redefined in subclasses.

usage example(s):

     #(1 2 3 4) fourth

o  incrementAt: aKey
add 1 to the count stored under aKey.
If not yet present, assume 0 as initial counter value.

o  incrementAt: aKey by: count
add count to the count stored under aKey.
If not yet present, assume 0 as initial counter value.

o  keys
return the keys of the collection.

** This method raises an error - it must be redefined in concrete classes **

o  keysSorted
return the keys as a sorted sequenceable collection.
Some collections (which keep their keys already sorted) may
redefine this method to return the keys as they are kept internally.
The fallback here sorts them into an OrderedCollection

o  keysSorted: aBlock
return the keys as a sorted sequenceable collection.
Some collections (which keep their keys already sorted) may
redefine this method to return the keys as they are kept internally.
The fallback here sorts them into an OrderedCollection

o  last
return the last element of the collection.
This is a slow fallback implementation,
and should be redefined in subclasses which can do indexed accesses.

o  last: n
return the n last elements of the collection.
No longer raises an error if there are not enough elements;
instead, returns what is there.
For unordered collections, this simply returns the last
n elements when enumerating them
(Warning: the contents of the returned collection is not deterministic in this case).
This should be redefined in subclasses since the implementation here is VERY inefficient.

usage example(s):

     #(1 2 3 4 5) last:3
     #(1 2 3 4 5 6 7 8 9 0) asSet last:3
     'hello world' last:5
     'hello' last:10
     'hello' asSet last:10

o  lastIfEmpty: exceptionValue
return the last element of the collection.
If it is empty, return the exceptionValue.
(i.e. don't trigger an error as done in #last)

o  nth: n
return the nth element of the collection.
For unordered collections, this simply returns the nth
element when enumerating them.
This should be redefined in subclasses which can accecss fast by numeric index (aka Array-like things).

usage example(s):

     #(1 2 3 4) nth:3
     #(1 2 3 4) nth:5

     #(1 2 3 4) asSet nth:3  
     #(1 2 3 4) asSet nth:5

o  order
report an error that only OrderedXXX's have an order

o  second
return the second element of the collection.
For unordered collections, this simply returns the second
element when enumerating them.
This should be redefined in subclasses.

usage example(s):

     #(1 2 3) second

o  secondLast
return the second last element of the collection.
This is a slow fallback implementation,
and should be redefined in subclasses which can do indexed accesses.

o  seventh
return the seventh element of the collection.
For unordered collections, this simply returns the sixth
element when enumerating them.
This should be redefined in subclasses.

usage example(s):

     #(1 2 3 4 5 6 7) seventh

o  sixth
return the sixth element of the collection.
For unordered collections, this simply returns the sixth
element when enumerating them.
This should be redefined in subclasses.

usage example(s):

     #(1 2 3 4 5 6 7) sixth

o  third
return the third element of the collection.
For unordered collections, this simply returns the third
element when enumerating them.
This should be redefined in subclasses.

usage example(s):

     #(1 2 3) third

o  values
return a collection containing all values of the receiver.
This is to make value access to an OrderedDictionary compatible with any-Collection

usage example(s):

        #(1 2 3 4 5) values
        #(1 2 3 4 5) asSet values
        #(1 2 3 4 5) asOrderedSet values

adding & removing
o  add: anObject
add the argument, anObject to the receiver.
If the receiver is ordered, the position of the new element is undefined
(i.e. don't depend on where it will be put).
An error is raised here - it is to be implemented by a concrete subclass.

** This method raises an error - it must be redefined in concrete classes **

o  add: newObject withOccurrences: anInteger
add the argument, anObject anInteger times to the receiver.
Returns the object.

o  addAll: aCollection
add all elements of the argument, aCollection to the receiver.
Returns the argument, aCollection (sigh).

usage example(s):

     #(1 2 3 4) copy addAll:#(5 6 7 8); yourself
     #(1 2 3 4) asOrderedCollection addAll:#(5 6 7 8); yourself

o  addAll: aCollectionOfObjects withOccurrences: anInteger
add each element from aCollection, anInteger times to the receiver.
Returns the argument, aCollection (sigh).

o  addAllFirst: aCollection
insert all elements of the argument, aCollection at the beginning
of the receiver. Returns the argument, aCollection.

o  addAllLast: aCollection
add all elements of the argument, aCollection to the receiver.
Returns the argument, aCollection.

o  addAllNonNilElements: aCollection
add all non-nil elements of the argument, aCollection to the receiver.
Use this, when operating on a Set, that should not hold nil.
Answer the argument, aCollection.

usage example(s):

     #(1 2 3 4) asSet addAllNonNilElements:#(5 nil 6 7 8); yourself

o  addAllReversed: aCollection
add all elements of the argument, aCollection in reverse order to the receiver.
Returns the argument, aCollection (sigh).

usage example(s):

     #(1 2 3 4) copy addAllReversed:#(5 6 7 8); yourself
     #(1 2 3 4) asOrderedCollection addAllReversed:#(5 6 7 8); yourself

o  addFirst: anObject
add the argument, anObject to the receiver.
If the receiver is ordered, the new element will be added at the beginning.
An error is raised here - it is to be implemented by a concrete subclass.

** This method raises an error - it must be redefined in concrete classes **

o  addLast: anObject
add the argument, anObject to the receiver.
If the receiver is ordered, the new element will be added at the end.
Return the argument, anObject.

This usually has the same semantics as #add:.
OrderedSet and OrderedDictionary redefine this, to move anObject to
the end, even if it is already present in the collection.

o  clearContents
remove all elements from the receiver. Returns the receiver.
Subclasses may redefine this to keep the container.

o  contents: aCollection
set my contents from aCollection
- this may be redefined in a concrete subclass for more performance

o  remove: anObject
search for the first element, which is equal to anObject;
if found, remove and return it.
If not found, report a 'value not found'-error.
Uses equality compare (=) to search for the occurrence.

o  remove: anObject ifAbsent: exceptionBlock
search for the first element, which is equal to anObject;
if found, remove and return it.
If not found, return the value of the exceptionBlock.
Uses equality compare (=) to search for the occurrence.
An error is raised here - it is to be implemented by a concrete subclass.

** This method raises an error - it must be redefined in concrete classes **

o  removeAll
remove all elements from the receiver. Returns the receiver.
This should be reimplemented in subclasses for better
performance.

o  removeAll: aCollection
remove all elements from the receiver which are equal to any in aCollection.
Return the argument, aCollection.
Raises an error, if some element-to-remove is not in the receiver.
(see also: #removeAllFoundIn:, which does not raise an error).

Notice: for some collections (those not tuned for
resizing themself) this may be very slow.
If the number of removed elements is big compared to
the receiver's size, it may be better to copy the
ones which are not to be removed into a new collection.

o  removeAllFoundIn: aCollection
remove all elements from the receiver which are equal to any in aCollection.
No error is raised, if some element-to-remove is not in the receiver.
(see also: #removeAll:, which does raise an error).

o  removeAllIdentical: aCollection
remove all elements from the receiver which are in aCollection.
Return the argument, aCollection.
Raises an error, if some element-to-remove is not in the receiver.
(see also: #removeAllFoundIn:, which does not raise an error).

Notice: for some collections (those not tuned for
resizing themself) this may be very slow.
If the number of removed elements is big compared to
the receiver's size, it may be better to copy the
ones which are not to be removed into a new collection.

o  removeAllIdenticalFoundIn: aCollection
remove all elements from the receiver which are in aCollection.
No error is raised, if some element-to-remove is not in the receiver.
(see also: #removeAll:, which does raise an error).

o  removeAllSuchThat: aBlock
Apply the condition to each element and remove it if the condition is true.
Return a collection of removed elements.
First elements-to-remove are collected, then removed in one operation.

o  removeFirst
remove the first element from the receiver.
Return the removed element.

usage example(s):

     (Set with:3 with:2 with:1) removeFirst 

o  removeFirst: n
remove the first n elements from the receiver.
Return a collection of removed elements.
Notice: for some collections (those not tuned for
resizing themself) this may be very slow.

o  removeIdentical: anObject
search for the first element, which is identical to anObject;
if found, remove and return it.
If not found, report a 'value not found'-error.
Uses identity compare (==) to search for the occurrence.

o  removeIdentical: anObject ifAbsent: exceptionBlock
search for the first element, which is identical to anObject;
if found, remove and return it.
If not found, return the value of the exceptionBlock.
Uses identity compare (==) to search for the occurrence.
An error is raised here - it is to be implemented by a concrete subclass.

** This method raises an error - it must be redefined in concrete classes **

o  removeLast
remove the last element from the receiver.
Return the removed element.
An error is raised here - it is to be implemented by a concrete subclass.

** This method raises an error - it must be redefined in concrete classes **

o  removeLast: n
remove the last n elements from the receiver collection.
Return a collection of removed elements.
Notice: for some collections this may be very slow
(those not tuned for resizing themself).

o  testAndAdd: anElement
Test, if the element is present in the receiver.
Answer true, if the element did already exist in the collection,
false otherwise.
If the element does not exist, add it to the collection.

WARNING: do not add elements while iterating over the receiver.
Iterate over a copy to do this.

o  unless: aCheckBlock add: anObject
if aCheckBlock evaluates to false,
add the argument, anObject to the receiver.
Otherwise do nothing.

o  when: aCheckBlock add: anObject
if aCheckBlock evaluates to true,
add the argument, anObject to the receiver.
Otherwise do nothing.

bulk operations
o  abs
absolute value of all elements in the collection.
Elements are supposed to be numeric

usage example(s):

     TestCase assert:( #(1 -2 -3 4) abs = #(1 2 3 4)).

o  negated
negated value of all elements in the collection.
Elements are supposed to be numeric

usage example(s):

     TestCase assert:( #(1 -2 -3 4) negated = #(-1 2 3 -4)).

o  product
return the product of all elements which are supposed to be numeric.
Returns 1 for an empty receiver.

usage example(s):

     TestCase should:[ Array new product ] raise:Error.

     TestCase assert:( #(1) product == 1).
     TestCase assert:( #(6) product == 6).
     TestCase assert:( #(1 2 3 4 5) product = 5 factorial )

o  sum
return the sum of all elements which are supposed to be numeric.
Returns 0 for an empty receiver.

usage example(s):

     TestCase assert: ( #() sum = 0 ).
     TestCase assert: ( #(1) sum = 1 ).
     TestCase assert: ( #(1 2 3 4) sum = 10 ).
     TestCase assert: ( (1 to:10) sum = 55 ).
     TestCase assert: ( 'abc' asByteArray sum = 294 ).
     TestCase assert: ( { 10 +/- 2.
                          20 +/- 4.
                         100 +/- 10 } sum = (130 +/- 16) ).

     TestCase assert: ( { (1 / 9).
                          (1 / 7).
                        } sum = (16 / 63) ).

o  sum: aBlock
for each element in the receiver, evaluate the argument, aBlock and sum up the results.
Return the total sum or 0 for an empty collection.
Similar to (self collect...) sum, but avoids creation of an intermediate collection.

usage example(s):

     TestCase assert:(
        ((1 to:10) collect:[:n | n squared]) sum = ((1 to:10) sum:[:n | n squared])
     )

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

usage example(s):

     #(1 2 3 4 5) = #(1 2 3 4 5)
     #(1 2 3 4 5) = #(1.0 2 3 4.0 5)
     #($1 $2 $3 $4 $5) = '12345'

     #(1 2 3 4 5) identicalContentsAs:#(1 2 3 4 5)
     #(1 2 3 4 5) identicalContentsAs: #(1.0 2 3 4.0 5)
     #($1 $2 $3 $4 $5) identicalContentsAs: '12345'

o  sameContentsAs: aCollection
answer true, if all the elements in self and aCollection
are common. This is not defined as #=, since we cannot redefine #hash
for aCollection.

usage example(s):

      #(1 2 3) asSet sameContentsAs: #(1 2 3)
      #(1 2 3 4) asSet sameContentsAs: #(1 2 3)
      #(1 2 3) asSet sameContentsAs: #(1 2 3 3)
      #(1 2 3 'aa') asSet sameContentsAs: #(1 2 3 'aa')
      #(1 2 3 'aa') asIdentitySet sameContentsAs: #(1 2 3 'aa')
      #(1 2 3 #aa) asIdentitySet sameContentsAs: #(1 2 3 #aa)

o  sameContentsAs: aCollection whenComparedWith: compareBlock
answer true, if all the elements in self and aCollection
are common. This is not defined as #=, since we cannot redefine #hash
for aCollection.

usage example(s):

     #(1 2 3 4 5) asSet 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) asSet sameContentsAs: #(1 2 3 4 5)     whenComparedWith:[:a :b | a == b]
     #(1 2 3 4 5) asSet sameContentsAs: #(1.0 2 3 4.0 5) whenComparedWith:[:a :b | a = b]
     #(1 2 3 4 5) asSet sameContentsAs: #(1.0 2 3 4.0 5) whenComparedWith:[:a :b | a == b]

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

converting
o  asArray
return an Array with the collection's elements.
Notice: this is redefined in Array, where it returns the receiver.
Use asNewArray, if you intent to modify the returned collection.

o  asArrayOfType: arrayClass
return a new instance of arrayClass with the collection's elements

o  asBag
return a new Bag with the receiver collection's elements

o  asByteArray
return a new ByteArray with the collection's elements
(which must convert to 8bit integers in the range 0..255).

o  asCollection
return myself as a Collection.
I am already a Collection.

o  asCollectionDo: aBlock
enumerate myself

o  asCollectionOrEmptyIfNil
return myself as a Collection.
I am already a Collection.

o  asDictionary
return a Dictionary with the receiver collection's elements,
using the original keys of the receiver as dictionary key.
Notice: this is redefined in Dictionary, where it returns the receiver.
Use asNewDictionary, if you intend to modify the returned collection.
See associationsAsDictionary if you already have a collection of associations

usage example(s):

     #(10 20 30 40 50 60 70 80 90) asDictionary 

o  asDoubleArray
return a new DoubleArray with the collection's elements
(which must convert to 64bit floats).

o  asFlatOrderedCollection
return a new ordered collection containing all elements of the receiver
and recursively of all collectionelements from the receiver

usage example(s):

     #(
        (1 2 3)
        4 5
        (6)
        7
        (8 (9 10) 11 12 (13 (14 (15) 16)))
     ) asFlatOrderedCollection

o  asFloatArray
return a new FloatArray with the collection's elements
(which must convert to 32bit floats).

o  asHalfFloatArray
( an extension from the stx:libbasic2 package )
return a new HalfFloatArray with the collection's elements
(which must convert to 16bit half-floats).

o  asIdentitySet
return a new IdentitySet with the receiver collection's elements

o  asIdentitySkipList
( an extension from the stx:libbasic2 package )
Answer a IdentitySkipList whose elements are the elements of the
receiver. The sort order is the default less than or equal.

o  asIntegerArray
return a new IntegerArray with the collection's elements
(which must convert to 32bit integers in the range 0..16rFFFFFFFF).

o  asIntegerArray: arrayClass
return a new Array with the collection's elements

o  asKeysAndValues
return a Dictionary with the receiver's associations as key->value pairs
using each element's key as dictionary key and value as dictionary value.

usage example(s):

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

o  asList
( an extension from the stx:libbasic2 package )
return a new List with the receiver collection's elements

o  asLongIntegerArray
return a new LongIntegerArray with the collection's elements
(which must convert to 64bit integers in the range 0..16rFFFFFFFFFFFFFFFF).

o  asMutableCollection
return myself

o  asNewArray
return a new Array with the receiver collection's elements.
This method ensures that the returned collection is a new one, not
the same or shared with the original receiver

o  asNewDictionary
return a new Dictionary with the receiver collection's elements.
This method ensures that the returned collection is a new one, not
the same or shared with the original receiver

o  asNewIdentitySet
return a new IdentitySet with the receiver collection's elements.
This method ensures that the returned collection is a new one, not
the same or shared with the original receiver

o  asNewOrderedCollection
return a new OrderedCollection with the receiver collection's elements.
This method ensures that the returned collection is a new one, not
the same or shared with the original receiver

o  asNewOrderedSet
return a new OrderedSet with the receiver collection's elements.
This method ensures that the returned collection is a new one, not
the same or shared with the original receiver

o  asNewSet
return a new Set with the receiver collection's elements.
This method ensures that the returned collection is a new one, not
the same or shared with the original receiver

o  asNilIfEmpty
return mySelf, or nil if I am empty

o  asOrderedCollection
return an OrderedCollection with the receiver collection's elements.
Notice: this is redefined in OrderedCollection, where it returns the receiver.
Use asNewOrderedCollection, if you intent to modify the returned collection.

o  asOrderedSet
return a new OrderedSet with the receiver collection's elements.
Notice: this is redefined in OrderedSet, where it returns the receiver.
Use asNewOrderedSet, if you intent to modify the returned collection.

o  asRunArray
( an extension from the stx:libbasic2 package )
return a new RunArray with the collection's elements

usage example(s):

     #(1 2 3 3 3 4 4 4 4 5 6 7) asRunArray 

o  asSequenceableCollection
return myself as a SequenceableCollection.
I am already a Collection, but not sequenceable.

o  asSet
return a Set with the receiver collection's elements.
Notice: this is redefined in Set, where it returns the receiver.
Use asNewSet, if you intent to modify the returned collection.

o  asSharedCollection
( an extension from the stx:libbasic2 package )
return a shared collection on the receiver.
This implements synchronized (i.e. mutually excluded) access to me.
Use this for safe access when multiple processes access me concurrently.
Notice that this is a general (possibly suboptimal) mechanism, which should
work with all collections. Look for specialized collections (SharedQueue), which are
tuned for this kind of operation.

o  asSignedByteArray
return a new ByteArray with the collection's elements
(which must convert to 8bit integers in the range -128..127).

usage example(s):

        #( 1 2 3 4 -128 -5 -6) asSignedByteArray

o  asSignedIntegerArray
return a new SignedIntegerArray with the collection's elements
(which must convert to 32bit signed integers in the range 16r-80000000..16r7FFFFFFF).

o  asSignedLongIntegerArray
return a new LongIntegerArray with the collection's elements
(which must convert to 64bit integers in the range 16r-8000000000000000..16r7FFFFFFFFFFFFFFF).

o  asSignedWordArray
return a new WordArray with the collection's elements
(which must convert to 16bit integers in the range -0x8000..16r7FFF).

o  asSkipList
( an extension from the stx:libbasic2 package )
Answer a SkipList whose elements are the elements of the
receiver. The sort order is the default less than or equal.

o  asSkipList: aSortBlock
( an extension from the stx:libbasic2 package )
Answer a SkipList whose elements are the elements of the
receiver. The sort order is defined by the argument, aSortBlock.

o  asSortedCollection
return a new SortedCollection with the receiver collection's elements

o  asSortedCollection: sortBlock
return a new SortedCollection with the receiver collection's elements,
using sortBlock for comparing

o  asSortedStrings
Create & return a SortedCollection that sorts the receiver's
elements according to the locales collating policy.
This is currently not really supported - strings are sorted
without caring for the locale.

o  asSortedStrings: sortBlock
Create & return a SortedCollection that sorts the receiver's
elements using sortBlock and according to the locales collating policy,
which is passed as first arg to sortBlock.
This is currently not really supported - strings are sorted
without caring for the locale.

o  asSortedStrings: sortBlock with: aCollationPolicy
Create & return a SortedCollection that sorts the receiver's
elements using sortBlock and according to the specified locales collating policy.
This is currently not really supported - strings are sorted
without caring for the locale.

o  asSortedStringsWith: aCollationPolicy
Create & return a SortedCollection that sorts the receiver's
elements according to the specified locales collating policy.
This is currently not really supported - strings are sorted
without caring for the locale.

o  asString
return a String with the collection's elements
(which must convert to characters)

usage example(s):

     #(80 81 82) asString
     #(16r8000 16r8001 16r8002) asString
     #(16r800000 16r800001 16r800002) asString

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

o  asUnicodeString
return a String with the collection's elements
(which must convert to characters)

usage example(s):

      #(16r440 16r443 16r441 16r441 16r43A 16r438 16r439 16r20 16r44F 16r437 16r44B 16r43A) asUnicodeString

o  asUnsignedByteArray
return a new ByteArray with the collection's elements
(which must convert to 8bit integers in the range 0..255).

o  asWordArray
return a new WordArray with the collection's elements
(which must convert to integers in the range 0..16rFFFF).

o  associationsAsDictionary
Modified (comment): / 14-09-2018 / 18:13:21 / Stefan Vogel

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

o  copyAs: collectionClass
return a new instance of collectionClass with the receiver collection's elements.
This is similar to copy as:collectionClass, to ensure that we get a new
(unshared) collection, but avoids the copy if the receiver is not already an
instance of collectionClass.

o  copyAsOrderedCollection
return a new OrderedCollection with the receiver collection's elements.
This is similar to copy asOrderedCollection, to ensure that we get a new
(unshared) collection, but avoids the copy if the receiver is not already an
OrderedCollection.

o  keysAndValues
return an OrderedCollection with the receiver's associations as key->value pairs
using each element's key as dictionary key and value as dictionary value.

usage example(s):

     #(10 20 30 40 50 60) keysAndValues

o  literalArrayEncoding
encode myself as an array literal, from which a copy of the receiver
can be reconstructed with #decodeAsLiteralArray.

usage example(s):

     (Array with:(Color red:50 green:50 blue:50)
            with:(1 @ 2)
     ) literalArrayEncoding decodeAsLiteralArray

o  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 

o  readStream
return a stream for reading from the receiver

o  readStreamOrNil
return a stream for reading from the receiver.
This has been defined for protocol compatibility with FileName,
but nil is never returned here

o  readWriteStream
return a stream for reading and writing from/to the receiver

usage example(s):

     'hello world' readWriteStream
        nextPutAll:'+Foo';
        contents

     'hello world' readWriteStream
        setToEnd;
        nextPutAll:'+Foo';
        contents

o  readingStreamDo: aBlock
simular to FileStream readingFileDo:,
this evaluates aBlock passing a readStream on the receiver

usage example(s):

     'hello world' readingStreamDo:[:s |
        Transcript showCR:(s next:5).
     ]                

o  writeStream
return a stream for writing onto the receiver

o  writeStreamOrNil
return a stream for writing onto the receiver.
This has been defined for protocol compatibility with FileName,
but nil is never returned here

copying
o  copy
return a copy of the receiver.
Redefined to pass the original as argument to the postCopyFrom method.

o  copyEmpty
return a copy of the receiver with no elements.
This is used by copying and enumeration methods
to get a new instance which is similar to the receiver.

o  copyEmpty: size
return a copy of the receiver with no elements, but space for
size elements. This is used by copying and enumeration methods
to get a new instance which is similar to the receiver.
This method should be redefined in subclasses with instance
variables, which should be put into the copy too.
For example, SortedCollection has to copy its sortBlock into the
new collection.

o  copyEmptyAndGrow: size
return a copy of the receiver with size nil elements.
This is used by copying and enumeration methods
to get a new instance which is similar to the receiver.

o  copyWith: additionalElement
Return a copy of the dictionary that is 1 bigger than the receiver and
includes the argument, additionalElement, at the end.

o  copyWithout: elementToSkip
return a new collection consisting of a copy of the receiver,
with ALL elements equal to elementToSkip left out.
No error is reported, if elementToSkip is not in the collection.
This is a slow generic fallback. Many collections redefine this for performance.

usage example(s):

     #($a $b $c $d $e $f $g $a $b $a $d $a $f $a) asBag copyWithout:$a
     #($a $b $c $d $e $f $g $a $b $a $d $a $f $a) asSet copyWithout:$a

o  copyWithoutAll: elementsToSkip
return a new collection consisting of a copy of the receiver, with
ALL elements equal to any in elementsToSkip are left out.
No error is reported, if any in elementsToSkip is not in the collection.

usage example(s):

     #($a $b $c $d $e $f $g $a $b $a $d $a $f $a) asBag copyWithoutAll:'abc'

o  postCopyFrom: original
sent to a freshly copied object to give it a chance to adjust things.
Notice, that for Sets/Dicts etc. a rehash is not needed, since the copy
will have the same hash key as the receiver (as long as ST/X provides the
setHash: functionality).

enumerating
o  addAllNonNilElementsTo: aCollection
add all nonNil elements of the receiver to aCollection.
Return aCollection.

usage example(s):

     #(1 2 3 4 5 1 2 3 4 5 nil) asOrderedCollection addAllNonNilElementsTo:Set new

o  addAllTo: aCollection
add all elements of the receiver, to aCollection.
Return aCollection.

usage example(s):

     #(1 2 3 4 5 1 2 3 4 5) addAllTo:Set new

o  and: aSecondCollection and: aThirdCollection do: aBlock
evaluate the argument, aBlock for each element in the receiver,
then for each element in aSecondCollection, then for each in aThirdCollection.

usage example(s):

     #(1 2 3) and: #(a b c) and: #(x y z) do:[:each | Transcript showCR:each]

o  and: aSecondCollection do: aBlock
evaluate the argument, aBlock for each element in the receiver,
then for each element in aSecondCollection.

usage example(s):

     #(1 2 3) and: #(a b c) do:[:each | Transcript showCR:each]

o  and: finalValue inject: thisValue into: binaryBlock
starting with thisValue for value, pass this value and each element
to binaryBlock, replacing value with the result returned from the block
in the next iteration.
As a last step, inject finalValue.
This last injection is useful to signal end-of-input to the block;
typically, a nil or other marker is injected as finalValue.

See also: #fold: #reduce:

usage example(s):

     #(1 2 3 4) and:5 inject:0 into:[:accu :element | accu + element]   
     (1 to:10) and:1000 inject:0 into:[:accu :element | accu + element]     
     (1 to:10) and:1000 inject:0 into:#+     

o  collect: aBlockOrSymbol
for each element in the receiver, evaluate the argument, aBlock
and return a new collection with the results

usage example(s):

     #(1 2 3 4) asSet collect:[:n | n * 2]
     #(1 2 3 4) asSet collect:#mul2

o  collect: aBlockOrSymbol as: aClass
like collect, but use an instance of aClass to collect the results.
Also avoids the need for an extra intermediate collection which is created with
the standard coding: 'self asXXXX collect:[...]

usage example(s):

     #(one two three four five six) collect:[:element | element asUppercase] as:OrderedCollection
     'abcdef' collect:[:char | char digitValue] as:ByteArray

     'abcdef' collect:#digitValue as:ByteArray

o  collect: collectBlock thenDetect: detectBlock ifNone: exceptionalValue
first apply collectBlock to each element, then pass the result to
detectBlock.
Return the first element from collectBlock for which detectBlock evaluates to true.
If none does, return the value of exceptionalValue, which is usually a block.
Returns the same as if two separate collect:+detect:ifNone: messages were sent,
but avoids the creation of intermediate collections, so this is nicer for
big collections.

usage example(s):

     ( #(1 2 3 4) collect:[:e | e squared] ) detect:[:e| e odd] ifNone:0
     #(1 2 3 4) collect:[:e | e squared] thenDetect:[:e| e odd] ifNone:0
     #(1 2 3 4) collect:#squared thenDetect:#odd ifNone:0

o  collect: collectBlock thenDo: aBlock
combination of collect followed by do.
Avoids the creation of intermediate garbage

usage example(s):

     #(1 2 3 4 5 6 7) collect:[:i | i * 2] thenDo:[:i | Transcript showCR:i ]

o  collect: collectBlock thenReject: rejectBlock
combination of collect followed by reject.
May be redefined by some subclasses for optimal performance
(avoiding the creation of intermediate garbage)

usage example(s):

     #(1 2 3 4 5 6 7) collect:[:i | i * 2] thenReject:[:i | i > 10]

o  collect: collectBlockOrSymbol thenSelect: selectBlockOrSymbol
combination of collect followed by select.
May be redefined by some subclasses for optimal performance
(avoiding the creation of intermediate garbage)

usage example(s):

     #(1 2 3 4 5 6 7) collect:[:i | i * 2] thenSelect:[:i | i < 10]
     #(1 2 3 4 5 6 7) collect:#mul2 thenSelect:#isPerfectSquare

o  collect: collectBlock thenSelect: selectBlock as: aCollectionClass
first apply collectBlock to each element, then pass the result to
selectBlock.
Return a new collection with all elements from the receiver,
for which the selectBlock evaluates to true.
Returns the same as if three separate collect+select+as messages were sent,
but avoids the creation of intermediate collections, so this is nicer for
big collections.

o  collectAll: aBlock
for each element in the receiver, evaluate the argument, aBlock.
The block is supposed to return a collection, whose elements are collected.
The species of the returned collection is that of the first returned
partial result.

usage example(s):

     #(1 2 3 4) collectAll:[:n | Array new:n withAll:n ]  
     #(1 2 3 4) collectAll:[:n | Array with:n with:n squared ]   
     #(1 2 3 4) collectAll:[:n | 1 to:n ]      
     (Array with:Point with:Rectangle) collectAll:[:c | c instVarNames ]      

o  collectAll: aBlock as: collectionClass
for each element in the receiver, evaluate the argument, aBlock.
The block is supposed to return a collection, whose elements are collected.
The returned collection will be an instance of collectionClass

usage example(s):

     #(1 2 3 4) collectAll:[:n | Array new:n withAll:n ] as:OrderedCollection  
     #(1 2 3 4) collectAll:[:n | Array new:n withAll:n ] as:Bag  
     #(1 2 3 4) collectAll:[:n | Array with:n with:n squared ] as: OrderedCollection  
     #(1 2 3 4) collectAll:[:n | 1 to:n ] as: Set     
     (Array with:Point with:Rectangle) collectAll:[:c | c instVarNames ] as:StringCollection     

o  collectColumn: columnNumberOrKey
for each row-element in the receiver (which ought to be indexable by columnNumberOrKey),
retrieve the indexed element at columnNumberOrKey,
and return a new collection with those column values

usage example(s):

     #((1 one) (2 two) (3 three) (4 four)) collectColumn:1
     #((1 one) (2 two) (3 three) (4 four)) collectColumn:2
    similar (but more general) to:
     #((1 one) (2 two) (3 three) (4 four)) collect:#first
     #((1 one) (2 two) (3 three) (4 four)) collect:#second

o  collectColumn: columnNumberOrKey ifAbsent: replacementValue
for each row-element in the receiver (which ought to be indexable by columnNumberOrKey),
retrieve the indexed element at columnNumberOrKey,
and return a new collection with those column values

usage example(s):

     #((1 one) (2 two) (3) (4 four)) collectColumn:2 ifAbsent:'foo'
     #((1 one) (2 two) (3) (4 four)) collectColumn:2 ifAbsent:[:e | e at:1]

o  collectWithIndex: aTwoArgBlock
for each element in the receiver and a running index,
evaluate the argument, aTwoArgBlock.
Return a new collection with the results

usage example(s):

     #(1 2 3 4) collectWithIndex:[:n :i | n * 2 + i]  
     #(1 2 3 4) collectWithIndex:[:n :i | i -> (n * 2)]  

o  count: aBlock
count elements, for which aBlock returns true.
Return the sum.

usage example(s):

     #(1 2 3 4 6 8 10) count:[:a | a even]     
     #(1 nil nil nil 2 3 nil 4 5) count:[:a | a isNil]   
     #(1 nil nil nil 2 3 nil 4 5) count:#isNil   

o  detect: aBlockOrSmbol
evaluate the argument, aBlock for each element in the receiver until
the block returns true; in this case return the element which caused
the true evaluation.
If none of the evaluations returns true, report an error

usage example(s):

     #(1 2 3 4) detect:[:n | n odd]   
     #(2 4 6 8) detect:[:n | n odd]  

     #(1 2 3 4) detect: #odd     
     #(2 4 6 8) detect: #odd  

o  detect: generatorBlock forWhich: testBlock ifNone: exceptionValue
evaluate generatorBlock for each element in the receiver until
testBlock returns true for it;
in this case return the value from generatorBlock, which caused the true evaluation.
If none of the test evaluations returns true, return the value from exceptionValue

usage example(s):

     #(2 3 4) detect:[:n | n squared] forWhich:[:nsq | nsq odd] ifNone:['sorry']    
     #( 2 4 ) detect:[:n | n squared] forWhich:[:nsq | nsq odd] ifNone:['sorry']    

     #( 'st' 'c' 'java' ) 
        detect:[:ext | 'Foo' asFilename withSuffix:ext]
        forWhich:[:fn | fn exists]
        ifNone:nil    

o  detect: aOneArgBlockOrSymbol ifNone: exceptionValue
evaluate the argument aOneArgBlock for each element in the receiver until
the block returns true; in this case return the element that caused the
true evaluation.
If none of the evaluations returns true, return the value from exceptionValue

usage example(s):

     #(1 2 3 4) detect:[:n | n odd] ifNone:['sorry']
     #(2 4 6 8) detect:[:n | n odd] ifNone:['sorry']
     #(1 2 3 4) detect:#odd ifNone:['sorry']
     #(2 4 6 8) detect:#odd ifNone:['sorry']

o  detect: checkBlock thenCompute: evalBlock
evaluate the argument, aBlock for each element in the receiver until
checkBck returns true; in this case return the value from evalBlock
applied to the element which caused the true evaluation.
If none of the evaluations returns true, report an error

usage example(s):

     #((1 'one') (2 'two') (3 'three') (4 'four')) 
        detect:[:pair | pair first odd] thenCompute:[:pair | pair second]

     #((1 'one') (2 'two') (3 'three') (4 'four')) 
        detect:[:pair | pair first odd] thenCompute:#second 

     #( (2 'two') (4 'four')) 
        detect:[:pair | pair first odd] thenCompute:[:pair | pair second] 

o  detect: checkBlock thenCompute: evalBlock ifNone: exceptionValue
evaluate the argument checkBlock for each element in the receiver until
it returns true; in this case return the value from evalBlock applied to
the element that caused the true evaluation.
If none of the evaluations returns true, return the value from exceptionValue.

usage example(s):

     #((1 'one') (2 'two') (3 'three') (4 'four'))
        detect:[:pair | pair first odd] thenCompute:[:pair | pair second]
        ifNone:[ nil ].

usage example(s):

     #( (2 'two')  (4 'four'))
        detect:[:pair | pair first odd] thenCompute:[:pair | pair second]
        ifNone:[ nil ].

o  detectLast: aBlock
evaluate the argument, aBlock for each element in the receiver until
the block returns true; in this case return the element which caused
the true evaluation. The elements are processed in reverse order.
If none of the evaluations returns true, report an error

usage example(s):

     #(1 2 3 4) detectLast:[:n | n odd]   
     #(1 2 3 4) detectLast:#odd   
     #(2 4 6 8) detectLast:[:n | n odd]  

o  detectLast: aBlock ifNone: exceptionValue
evaluate the argument, aBlock for each element in the receiver until
the block returns true; in this case return the element which caused
the true evaluation. The elements are processed in reverse order.
If none of the evaluations returns true, return the value from exceptionValue

usage example(s):

     #(1 2 3 4) detectLast:[:n | n odd] ifNone:['sorry']    
     #(2 4 6 8) detectLast:[:n | n odd] ifNone:['sorry']     

o  detectMax: aBlockOrSymbol
Evaluate aBlock with each of the receiver's elements as argument.
Answer the element for which aBlock evaluates to the highest magnitude.
If the receiver collection is empty, return nil.
This method might also be called elect:.

usage example(s):

     #(1 -1 5 -17 10 -8 5) detectMax: #abs

o  detectMin: aBlockOrSymbol
Evaluate aBlock with each of the receiver's elements as argument.
Answer the element for which aBlock evaluates to the lowest number.
If the receiver collection is empty, return nil.

usage example(s):

     #(1 -1 5 -17 10 -8 5) detectMin: #abs   

o  do: aBlock
evaluate the argument, aBlock for each element

** This method raises an error - it must be redefined in concrete classes **

o  do: aBlock inBetweenDo: betweenBlock
evaluate the argument, aBlock for each element.
Between elements (i.e. after each except for the last),
evaluate betweenBlock.
This is a utility helper for collection printers
(for example, to print a space between elements).

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

o  do: aBlock separatedBy: betweenBlock
evaluate the argument, aBlock for each element.
Between elements (i.e. after each except for the last),
evaluate betweenBlock.
This is a utility helper for collection printers
(for example, to print a space between elements).

usage example(s):

     #(1 2 3 4) do:[:el | Transcript show:el]
                separatedBy:[ Transcript show:'-']

     (Dictionary with:(1->'one') with:(2->'two'))
         do:[:el | Transcript showCR:el printString]
         separatedBy:[ Transcript showCR:'----']

     (Dictionary with:(1->'one') with:(2->'two'))
        associations
         do:[:el | Transcript showCR:el printString]
         separatedBy:[ Transcript showCR:'----']

o  do: aBlock separatedBy: betweenBlock afterEachCount: afterEachCount do: afterEachBlock
evaluate the argument, aBlock for each element.
Evaluate betweenBlock except after each count iteration and after the last,
Instead, after each count, but not at the end, the afterEachBlock is evaluated.
This is a utility helper for collection printers
(for example, to print a space between elements and a newline after each group).

usage example(s):

     #(1 2 3 4 5 6 7 8) 
        do:[:el | Transcript show:el]
        separatedBy:[ Transcript show:'-']
        afterEachCount:3
        do:[Transcript cr]

     #(1 2 3 4 5 6 7 8) 
        do:[:el | Transcript show:el]
        separatedBy:[ Transcript show:'-']
        afterEachCount:2
        do:[Transcript cr]

     #(1 2 3 4) 
        do:[:el | Transcript show:el]
        separatedBy:[ Transcript show:'-']
        afterEachCount:5
        do:[Transcript cr]

     #() 
        do:[:el | Transcript show:el]
        separatedBy:[ Transcript show:'-']
        afterEachCount:5
        do:[Transcript cr]

     #(1) 
        do:[:el | Transcript show:el]
        separatedBy:[ Transcript show:'-']
        afterEachCount:5
        do:[Transcript cr]

o  do: aBlock whileTrue: whileBlock
evaluate the argument, aBlock for each element until whileBlock
evaluates to false.
Answer the last result from evaluating aBlock.

o  do: aBlock without: anItem
enumerate all elements except those equal to anItem into aBlock.

usage example(s):

     #(1 2 3 4 999 5 6 7 8 9) 
        do:[:el | Transcript showCR:el ]
        without:5

o  doIfNotNil: aBlock
if I am a collection, then enumerate myself into aBlock.
if I am nil, then do nothing.
Otherwise, evaluate aBlock with myself as argument.

o  doWhileFalse: aBlock
evaluate the argument, aBlock for each element,
until it evaluates to true.
Answer false, if all the elements have been processed,
true otherwise.
Notice: to get the element, use #detect:ifNone:
to get its index, use #findFirst:ifNone:

o  doWhileTrue: aBlock
evaluate the argument, aBlock for each element,
until it evaluates to false.
Answer true, if all the elements have been processed,
false otherwise.
Notice: to get the element, use #detect:ifNone:
to get its index, use #findFirst:ifNone:

o  doWithBreak: aBlock
evaluate the argument, aBlock for each element.
Passes an additional exit object, which can be used to leave
the loop early, by sending it a #value message.

Notice, that this is different to a return statement in the block,
which returns from the enclosed method, NOT only from the block.

o  doWithExit: aBlock
evaluate the argument, aBlock for each element.
Passes an additional exit object, which can be used to leave
the loop early, by sending it a #value: message.
Returns nil or the value passed to the exit>>value: message.

Notice, that this is different to a return statement in the block,
which returns from the enclosed method, NOT only from the block.

o  doWithIndex: aBlock
Squeak/V'Age compatibility;
like keysAndValuesDo:, but passes the index as second argument.
Same as withIndexDo:, due to parallel evolution of different Smalltalk dialects

o  flatDetect: aBlock
for each element of the collection, if it's a scalar, evaluate aBlock for it;
otherwise, recursively invoke flatDetect: on the collection.
Return the first element for which aBlock evaluates to true.
Thus implementing a depth-first search.
Raises an error, if no element is found

usage example(s):

     #(
        (1 2 3)
        4 5
        (6)
        7
        (8 (9 10) 11 12 (13 (14 (15) 16)))) flatDetect:[:el | el>5]

o  flatDetect: aBlock ifNone: exceptionValue
for each element of the collection, if it's a scalar, evaluate aBlock for it;
otherwise, recursively invoke flatDetect: on the collection.
Return the first element for which aBlock evaluates to true.
Thus implementing a depth-first search.
Return the value from exceptionValue if none found

usage example(s):

     #(
        (1 2 3)
        4 5
        (6)
        7
        (  8 
          (9 10) 
          11 
          12 
          ( 13
           ( 14 
            (15) 
            16)
           )
          )
      ) flatDetect:[:el | el<0] ifNone:#none       

usage example(s):

     #(
        (1 2 3)
        4 5
        (6)
        7
        (  8 
          (9 10) 
          11 
          12 
          ( 13
           ( 14 
            (15) 
            16)
           )
          )
      ) flatDetect:[:el | el>15] ifNone:#none       

o  flatDo: aBlock
for each element of the collection, if it's a scalar, evaluate aBlock for it;
otherwise, recursively invoke flatDo: on the collection.
Thus implementing a depth-first enumeration

usage example(s):

     #(
        (1 2 3)
        4 5
        (6)
        7
        (8 (9 10) 11 12 (13 (14 (15) 16)))
     ) flatDo:[:el | Transcript showCR:el]

o  flatDoWithParent: aBlock
for each element of the collection, if it's a scalar, evaluate aBlock for it;
otherwise, recursively invoke flatWithParentDo: on the collection.
The block is called with two arguments, the element itself and its parent (owner),
thus implementing a depth-first enumeration

usage example(s):

     #(
        (1 2 3)
        4 5
        (6)
        7
        (8 (9 10) 11 12 (13 (14 (15) 16)))
     ) flatDoWithParent:[:el :parent | Transcript showCR:(parent -> el)]

o  fold: binaryBlock
Evaluate the block with the first two elements of the receiver,
then with the result of the first evaluation and the next element,
and so on. Answer the result of the final evaluation. If the receiver
is empty, raise an error. If the receiver has a single element, answer
that element.

Here the reduction is done from left to right.

See also: #inject:into: #reduce:

usage example(s):

     (1 to:10) fold:[:sum :el| sum + el]
     (1 to:10) fold:#+
     (1 to:15) fold:[:x :y| '(', x printString, '+', y printString, ')']
     (1 to:15) reduce:[:x :y| '(', x printString, '+', y printString, ')']
     #('if' 'it' 'is' 'to' 'be' 'it' 'is' 'up' 'to' 'me') fold: [:a :b | a, ' ', b]
     #('if' 'it' 'is' 'to' 'be' 'it' 'is' 'up' 'to' 'me') reduce: [:a :b | a, ' ', b]
     #() fold: [:a :b | a, ' ', b] -- raises an error

o  inject: thisValue into: binaryBlock
starting with thisValue for value, pass this value and each element
to binaryBlock, replacing value with the result returned from the block
in the next iteration.

See also: #fold: #reduce:

usage example(s):

sum up the elements of a collection:

     #(1 2 3 4) inject:0 into:[:accu :element | accu + element]   
     (1 to:10) inject:0 into:[:accu :element | accu + element]     
     (1 to:10) inject:0 into:#+     

     find the minimum:

     |coll|
     coll := #(1 99 -15 20 100).
     coll inject:(coll first) into:[:minSoFar :element | minSoFar min:element]

     |coll|
     coll := #(1 99 -15 20 100).
     coll inject:(coll first) into:#min:

o  injectAndCollect: thisValue into: binaryBlock
starting with thisValue for value, pass this value and each element
to binaryBlock, replacing value with the result returned from the block
in the next iteration.
Collect all results and return them all.

See also: #fold: #reduce:

usage example(s):

sum up the elements of a collection:

     #(1 2 3 4) inject:0 into:[:accu :element | accu + element]     
     (1 to:10) inject:0 into:[:accu :element | accu + element]      

     same, getting all partial sums:
     (1 to:10)  injectAndCollect:0 into:[:accu :element | accu + element] 

o  keysAndValuesCollect: aBlock
for each key-value pair in the receiver, evaluate the argument, aBlock
and return a collection with the results.

See also:
#associationsCollect: (which passes keys->value pairs)
#collect: (which only passes values)

This is much like #associationsCollect:, but aBlock gets the
key and value as two separate arguments.
#associationsCollect: is a bit slower.

WARNING: do not add/remove elements while iterating over the receiver.
Iterate over a copy to do this.

o  keysAndValuesConform: aTwoArgBlock
evaluate the argument, aBlock for every element in the collection,
passing both index and element as arguments.
Return false if any such evaluation returns false, true otherwise.

usage example(s):

     #(10 20 30 40) keysAndValuesConform:[:key :element | element = (key * 10) ]. 
     #(10 20 30 33 40) keysAndValuesConform:[:key :element | element = (key * 10) ]. 

o  keysAndValuesDetect: aBlock ifNone: exceptionalValue
for each key-value pair in the receiver, evaluate the argument, aBlock
and return the value for which aBlock returns true the very first time.
If none of the evaluations returns true, return the result of the
evaluation of the exceptionBlock

o  keysAndValuesDetectKey: aBlock ifNone: exceptionalValue
for each key-value pair in the receiver, evaluate the argument, aBlock
and return the key/index for which aBlock returns true the very first time.
If none of the evaluations returns true, return the result of the
evaluation of the exceptionBlock

o  keysAndValuesDo: aTwoArgBlock
evaluate the argument, aBlock for every element in the collection,
passing both index and element as arguments.
Blocked here - must be redefined in subclasses which have keyed elements

o  keysAndValuesDo: aTwoArgBlock separatedBy: sepBlock
evaluate the argument, aBlock for every element in the collection,
passing both index/key and element as arguments.
Between elements, evaluate aBlock (but not before the first).

o  keysAndValuesReverseDo: aTwoArgBlock
evaluate the argument, aBlock in reverse order for every element in the collection,
passing both index and element as arguments.
Blocked here - must be redefined in subclasses which have keyed elements

o  keysAndValuesSelect: selectBlockWith2Args
first call the selectBlockWith2Args, passsing it each key and element,
collect the elements for which the block returns true in an OrderedCollection.

usage example(s):

     #(10 20 30 40) 
        keysAndValuesSelect:[:idx :val | idx odd] 

o  keysAndValuesSelect: selectBlockWith2Args thenCollect: collectBlockWith2Args
first call the selectBlockWith2Args, passsing it each key and element,
if that returns true, call the collectBlockWith2Args, also with key and element,
and collect the resulting values in an OrderedCollection.

usage example(s):

     #(10 20 30 40) 
        keysAndValuesSelect:[:idx :val | idx > 2] 
        thenCollect:[:idx :val | idx->val]

o  keysDo: aBlock
evaluate the argument, aBlock for every key in the collection.

o  map: selectorOrBlock
for lisp fans (and also for Javascript) - similar to collect:

usage example(s):

     #(1 2 3 4) map:#negated 

     Time millisecondsToRun:[
       (1 to:10000000) map:#negated 
    ]

     Time millisecondsToRun:[
       (1 to:10000000) collect:#negated 
    ]

o  map: selectorOrBlock with: arg
for lisp fans - similar to collect:

usage example(s):

     #(1 2 3 4) map:#+ with:1  
     #(1 2 3 4) map:[:a :b | a + b] with:1  

o  nonNilElementsDo: aBlock
evaluate the argument, aBlock for every non-nil element in the collection.

usage example(s):

     #(1 nil 3 nil nil 6 7 nil)
        nonNilElementsDo:[:el | Transcript showCR:el]

o  pairsDo: aTwoArgBlock
evaluate the argument, aTwoArgBlock for every element in the collection,
which is supposed to consist of 2-element collections.
The block is called with 2 arguments for each collection in the receiver.
CONFUSION ATTACK:
this is different from pairWiseDo:.
but the Squeak-pairsDo: does the same as our pairWiseDo:
(sigh: but we were first, so they should have adapted...)

usage example(s):

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

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

o  partition: check as: species into: aTwoArgBlock
enumerate the receiver's elements and partition them into two collections,
depending on the outcome of a check block.
The type of result collection is passed in via the species argument.
Evaluate aTwoArgBlock on the two selected and rejected value collections.
Also return the selected values as return value

usage example(s):

     #(1 2 3 4 5 6 7 8)
        partition:[:el | el even]
        as:Set    
        into:[:evenElements :oddElements |
            Transcript show:'even: '; showCR:evenElements.
            Transcript show:' odd: '; showCR:oddElements.
        ].

o  partition: check into: aTwoArgBlock
enumerate the receiver's elements and partition them into two collections,
depending on the outcome of a check block.
Evaluate aTwoArgBlock on the two selected and rejected value collections.
Also return the selected values as return value

usage example(s):

     #(1 2 3 4 5 6 7 8)
        partition:[:el | el even]
        into:[:evenElements :oddElements |
            Transcript show:'even: '; showCR:evenElements.
            Transcript show:' odd: '; showCR:oddElements.
        ].

o  reduce: binaryBlock
Evaluate the block with the first two elements of the receiver,
then with the result of the first evaluation and the next element,
and so on. Answer the result of the final evaluation. If the receiver
is empty, raise an error. If the receiver has a single element, answer
that element.

Here the reduction is done from right to left.

See also: #inject:into: #fold:

usage example(s):

     (1 to:15) reduce:[:x :y| '(', x printString, '+', y printString, ')']
     (1 to:15) fold:[:x :y| '(', x printString, '+', y printString, ')']
     #('if' 'it' 'is' 'to' 'be' 'it' 'is' 'up' 'to' 'me') reduce: [:a :b | a, ' ', b]
     #('if' 'it' 'is' 'to' 'be' 'it' 'is' 'up' 'to' 'me') fold: [:a :b | a, ' ', b]
     #(10 1 2 3) reduce:[:el :diff | diff - el] 
     #(10 1 2 3) reduce:[:el :diff | diff + el] 
     #(10 1 2 3) reduce:#+ 
     #(10 1 2 3) reduce:#max: 

o  reduceLeft: aTwoArgBlock
#(1 2 3 4 5) reduceLeft:[:sum :el | sum + el]
#(1 2 3 4 5) reduceLeft:#+

o  reject: aBlock
return a new collection with all elements from the receiver, for which
the argument aBlock evaluates to false

usage example(s):

     #(1 2 3 4) reject:[:e | e odd]   
     (1 to:10) reject:[:e | e even]     

o  reject: rejectBlock thenCollect: collectBlock
combination of reject followed by collect.
May be redefined by some subclasses for optimal performance
(avoiding the creation of intermediate garbage)

usage example(s):

     #(1 2 3 4 5 6 7) reject:[:i | i even] thenCollect:[:i | i * 2]

o  reject: selectBlock thenDo: doBlock
combination of reject followed by do
Avoids the creation of intermediate garbage

usage example(s):

     #(1 2 3 4 5 6 7) reject:[:i | i even] thenDo:[:i | Transcript showCR:i]

o  reverseDo: aBlock
evaluate the argument, aBlock for each element in reverse order.

** This method raises an error - it must be redefined in concrete classes **

o  select: aBlock
return a new collection with all elements from the receiver, for which
the argument aBlock evaluates to true.
See also: #removeAllFoundIn: and #removeAllSuchThat:

usage example(s):

     #(1 2 3 4) select:[:e | e odd]
     (1 to:10) select:[:e | e even]
     (1 to:10) select:#even

o  select: aBlock as: aCollectionClass
return a new collection with all elements from the receiver, for which
the argument aBlock evaluates to true.
See also: #removeAllFoundIn: and #removeAllSuchThat:

usage example(s):

     #(1 2 3 4) select:[:e | e odd] as:OrderedCollection.
     (1 to:10) select:[:e | e even] as:OrderedCollection.

     #(1 2 3 4) select:[:e | e odd] as:Set.
     (1 to:10) select:[:e | e even] as:Set.

     #(1 2 3 4) select:[:e | e odd] as:ByteArray.
     (1 to:10) select:[:e | e even] as:ByteArray.

o  select: aBlock ifNone: exceptionValue
try a new collection with all elements from the receiver, for which
the argument aBlock evaluates to true. If none of the elements passes
the check of aBlock, return the value from exceptionValue.
See also: #removeAllFoundIn: and #removeAllSuchThat:

usage example(s):

     #(1 2 3 4) select:[:e | e > 10] ifNone:['sorry']  
     #(1 2 3 4) select:[:e | e > 10] 

o  select: selectBlock thenCollect: collectBlock
combination of select followed by collect.
May be redefined by some subclasses for optimal performance
(avoiding the creation of intermediate garbage)

usage example(s):

^ self select:selectBlock thenCollect:collectBlock as:self species

usage example(s):

     #(1 2 3 4 5 6 7) select:[:i | i even] thenCollect:[:i | i * 2]

o  select: selectBlock thenCollect: collectBlock as: aCollectionClass
return a new collection with all elements from the receiver,
for which the argument selectBlock evaluates to true.
Process the elements through collectBlock before adding.
Returns the same as if three separate collect+select+as: messages were sent,
but avoids the creation of intermediate collections,
so this is nicer for big collections.

usage example(s):

     #(1 2 3 4) select:[:e | e odd] thenCollect:[:e| e*e] as:OrderedCollection  
     (1 to:10) select:[:e | e even] thenCollect:[:e| e*e] as:IdentitySet       

o  select: selectBlock thenDo: doBlock
combination of select followed by do.
The same as if two separate select:+do: messages were sent,
but avoids the creation of intermediate collections,
so this is nicer for big collections.

usage example(s):

     #(1 2 3 4 5 6 7) select:[:i | i even] thenDo:[:i | Transcript showCR:i]

o  selectWithIndex: aTwoArgBlock
return a new collection with all elements from the receiver,
for which the argument aBlock evaluates to true.
aTwoArgBlock is called with value and index as arguments.

usage example(s):

     #(10 20 30 40) selectWithIndex:[:e :i | i odd]
     #(10 20 30 40) selectWithIndex:[:e :i | i even]

o  triplesDo: aThreeArgBlock
evaluate the argument, aThreeArgBlock for every element in the collection,
which is supposed to consist of 3-element collections.
The block is called with 3 arguments for each collection in the receiver.

usage example(s):

     #(
        (1 one eins)
        (2 two zwei)
        (3 three drei)
        (4 four vier)
        (5 five #'fuenf')
        (6 six sechs)
     )
     triplesDo:[:num :sym1 :sym2 |
                    Transcript show:num; space; show:sym1; space; showCR:sym2
               ]

o  tuplesDo: anNArgBlock
evaluate the argument, anNArgBlock for every element in the collection,
which is supposed to consist of N-element collections.
The block is called with N arguments for each collection in the receiver.

usage example(s):

     #(
        (1 one eins uno)
        (2 two zwei due)
        (3 three drei tre)
        (4 four vier quattro)
        (5 five #'fuenf' cinque)
     )
     tuplesDo:[:num :sym1 :sym2 :sym3 |
                    Transcript show:num; space; show:sym1; space; show:sym2; space; showCR:sym3
               ]

o  with: aCollection andDefault: defaultElement collect: aTwoArgBlock
like with:collect:, but use defaultElement for missing elements in aCollection
(i.e. if the receiver is longer)
The third argument, aBlock must be a two-argument block, which is
evaluated for each element-pair.
Collect the results and return a collection containing them.
This method fails if neither the receiver nor aCollection is
a sequenceable collection (i.e. implements numeric key access).
Can be used like zip/zipAll in other languages.

usage example(s):

     (1 to:3) with:#(one two) andDefault:'xxx' collect:[:num :sym | (num->sym)]
     #(1 2 3) with:#(10 20) andDefault:99 collect:[:x :y | (x@y)]

o  with: aSequenceableCollection andDefault: defaultElement do: aTwoArgBlock
evaluate the argument, aBlock for successive elements from
each the receiver and the argument, aSequenceableCollection.
If the receiver has more elements than the argument, use defaultElement
for remaining evaluations.
The third argument, aBlock 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 to:3) with:#(one two) andDefault:99 do:[:num :sym |
        Transcript showCR:(num->sym)
     ]

o  with: aCollection collect: aTwoArgBlockOrSymbol
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, which is
evaluated for each element-pair.
Collect the results and return a collection containing them.
This method fails if neither the receiver nor aCollection is
a sequenceable collection (i.e. implements numeric key access).
Can be used like zip/zipAll in other languages.

usage example(s):

     (1 to:3) with:#(one two three) collect:[:num :sym | (num->sym)]
     #(1 2 3) with:#(10 20 30) collect:[:x :y | (x@y)]
     #(1 2 3) with:#(10 20 30) collect:#@

o  with: aCollection conform: aTwoArgBlock
evaluate the argument, aBlock for successive elements from
each the receiver and the argument, aCollection.
Return true, if the block returns true for all of these pairs.
This method fails if neither the receiver nor aCollection is
a sequenceable collection (i.e. implements numeric key access).

usage example(s):

     (1 to:3) with:#(1 2 3 4) conform:[:a :b | a = b]   --- raises an error
     (1 to:3) with:#(1 22 3) conform:[:a :b | a = b]
     (1 to:3) with:#(1 2 3) conform:[:a :b | a = b]
     (1 to:3) with:#(1 2 3) conform:#=
     (1 to:3) with:#(1.0 2.0 3.0) conform:#=
     (1 to:3) with:#(1.0 2.0 3.0) conform:#==
     (1 to:3) with:#('1' '2' '3') conform:[:a :b | a asString = b asString]

o  with: aCollection contains: aTwoArgBlock
evaluate the argument, aBlock for successive elements from
each the receiver and the argument, aCollection.
Return true, if the block returns true for any of these pairs.
This method fails if neither the receiver nor aCollection is
a sequenceable collection (i.e. implements numeric key access).

usage example(s):

     (1 to:3) with:#(1 2 3 4) contains:[:a :b | a ~= b]   --- raises an error
     (1 to:3) with:#(1 22 3) contains:[:a :b | a ~= b]  
     (1 to:3) with:#(1 2 3) contains:[:a :b | a ~= b]  
     (1 to:3) with:#(1 2 4) contains:#~=  

o  with: aCollection count: aTwoArgBlock
evaluate the argument, aBlock for successive elements from
each the receiver and the argument, aSequenceableCollection.
Count, how often the second argument, aTwoArgBlock returns true.
This method fails if neither the receiver nor aCollection is
a sequenceable collection (i.e. implements numeric key access).

usage example(s):

     (1 to:3) with:#(1 3 3) count:[:n1 :n2 | n1 = n2]
     (1 to:3) with:#(1 3 3) count:#=

o  with: aCollection 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.
This method fails if neither the receiver nor aCollection is
a sequenceable collection (i.e. implements numeric key access)
or (new!) if the sizes are different.

usage example(s):

     (1 to:3) with:#(one two three) do:[:num :sym |
        Transcript showCR:(num->sym)
     ]

     the following fail because sets do not have ordered elements

     (1 to:3) with:#(one two three) asSet do:[:num :sym |
        Transcript showCR:(num->sym)
     ].
     (1 to:3) asSet with:#(one two three) do:[:num :sym |
        Transcript showCR:(num->sym)
     ]

o  with: aCollection reverseDo: aTwoArgBlock
evaluate the argument, aBlock in reverse order for successive elements from
each the receiver and the argument, aSequenceableCollection.
The second argument, aBlock 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)
or (new!) if the sizes are different.

usage example(s):

     (1 to:3) with:#(one two three) reverseDo:[:num :sym |
        Transcript showCR:(num->sym)
     ]

     the following fail because sets do not have ordered elements

     (1 to:3) with:#(one two three) asSet reverseDo:[:num :sym |
        Transcript showCR:(num->sym)
     ].
     (1 to:3) asSet with:#(one two three) reverseDo:[:num :sym |
        Transcript showCR:(num->sym)
     ]

o  withIndexCollect: aTwoArgBlock
same as keysAndValuesCollect:, but with argument order reversed

usage example(s):

     #(one two three) withIndexCollect:[:sym :num | (num->sym)] 
     #(10 20 30) withIndexCollect:[:n :i | n*i ]  

o  withIndexDo: aTwoArgBlock
evaluate the argument, aBlock for every element in the collection,
passing both element and index as arguments.
Same as doWithIndex:, due to parallel evolution of different Smalltalk dialects

enumerating-tests
o  allSatisfy: aBlock
evaluate aBlock for each of the receiver's elements.
Return true, if aBlock returns true for all elements, false otherwise
(i.e. false if any element fails to satisfy the block-condition).
This is an ANSI renomer of #conform:

usage example(s):

     #(1 2 3 4 5) allSatisfy:[:el | el odd]   
     #(2 4 6 8 10) allSatisfy:[:el | el odd]  
     #(2 4 6 8 10) allSatisfy:[:el | el even]  

o  anySatisfy: aBlock
evaluate aBlock for each of the receiver's elements.
Return true, if aBlock ever returns true, false otherwise
(i.e. if any element satisfies the block-condition).
This is an ANSI renomer of #contains:
(which is a better name, because #contains: is often misread as #includes by beginners)

usage example(s):

     #(1 2 3 4 5) anySatisfy:[:el | el odd]   
     #(2 4 6 8 10) anySatisfy:[:el | el odd]  

o  conform: aOneArgBlock
return true, if every element conforms to some condition.
I.e. return false, if aBlock returns false for any element;
true otherwise. Returns true for empty receivers.

usage example(s):

     #(1 2 3 4 5) conform:[:el | el even]     
     #(2 4 6 8 10) conform:[:el | el even]    
     #() conform:[:el | el even]    

o  contains: aOneArgBlock
evaluate aOneArgBlock for each of the receiver's elements
Return true and skip remaining elements, if aBlock ever returns true,
otherwise return false.
(#anySatisfy: is a better name, because #contains: is often misread as #includes by beginners)

usage example(s):

     #(1 2 3 4 5) contains:[:el | el odd]  
     #(2 4 6 8 10) contains:[:el | el odd]  

o  noneSatisfy: aBlock
evaluate aBlock for each of the receiver's elements.
Return true, if aBlock returns false for all elements, false otherwise
(i.e. false if any element satisfies the block-condition).

usage example(s):

     #(1 2 3 4 5) noneSatisfy:[:el | el odd]
     #(2 4 6 8 10) noneSatisfy:[:el | el odd]
     #(2 4 6 8 10) noneSatisfy:[:el | el even]

error handling
o  emptyCheck
check if the receiver is empty; report an error if so

o  emptyCollectionError
report an error that the operation is not allowed for empty collections

o  errorInvalidKey: aKey
report an error that the given key was invalid

o  errorNotKeyed
report an error that keyed access methods are not allowed

o  errorValueNotFound: anObject
report an error that an object was not found in the collection

o  noModificationError
a store is attempted into an immutable collection (typically: a literal).
For our convenience, find the method that contains me, for a nicer error message

o  notEnoughElementsError
report an error that the operation is not allowed,
since not enough elements are in the collection

growing
o  changeCapacityTo: newSize

o  grow
make the receiver larger

o  grow: howBig
change the receiver's size

** This method raises an error - it must be redefined in concrete classes **

o  growSize
return a suitable size increment for growing.
The default returned here may be (and is) redefined in subclasses.

inspecting
o  inspectorValueListIconFor: anInspector
( an extension from the stx:libtool package )
returns the icon to be shown alongside the value list of an inspector

o  inspectorValueStringInListFor: anInspector
( an extension from the stx:libtool package )
returns a string to be shown in the inspector's list

printing & storing
o  displayElement: element on: aStream
print a representation of element on aStream.
Subclasses may redefine this.

o  displayOn: aGCOrStream
print a representation of the receiver on aGCOrStream for display in inspectors etc.

o  displayStringName
redefinable helper for displayString

o  maxPrint
the print-limit; printOn: will try to not produce more output
than the limit defined here.

o  printElementsDo: aBlock
perform aBlock (1 arg) for all elements.
Used in #printOn:.
Subclasses (e.g. Dictionary) may redefine this.

o  printElementsOn: aStream
append a user readable representation of the receiver to aStream.
The text appended is not meant to be read back for reconstruction of
the receiver. Also, this method limits the size of generated string.

o  printOn: aStream
append a user readable representation of the receiver to aStream.
The text appended is not meant to be read back for reconstruction of
the receiver. Also, this method limits the size of generated string.

usage example(s):

     #(1 2 3 'hello' $a) printOn:Transcript
     (Array new:100000) printOn:Transcript
     (Array new:100000) printOn:Stdout
     (Array new:100000) printString size
     (Dictionary new at:#hello put:'world';
                     at:#foo put:'bar'; yourself) printOn:Transcript

o  storeOn: aStream
output a printed representation onto the argument, aStream.
The text can be re-read to reconstruct (a copy of) the receiver.
Recursive (i.e. cyclic) collections cannot be stored correctly
(use storeBinaryOn: to handle those).

usage example(s):

     OrderedCollection new storeOn:Transcript
     (1 to:10) storeOn:Transcript
     (Set new add:1; add:'hello'; yourself) storeOn:Transcript

queries
o  allElementsHaveTheIdenticalValue
true if all elements of the receiver have the same value

usage example(s):

     #(1 2 3 5 6 7 8 9) allElementsHaveTheIdenticalValue
     #(1 1 1 1 1 1) allElementsHaveTheIdenticalValue
     #(1 1 1.0 1.0 1) allElementsHaveTheIdenticalValue
     #(1 1 1.0 1.0 1) allElementsHaveTheSameValue

o  allElementsHaveTheSameValue
true if all elements of the receiver have the same value

usage example(s):

     #(1 2 3 5 6 7 8 9) allElementsHaveTheSameValue
     #(1 1 1 1 1 1) allElementsHaveTheSameValue
     #(1 1 1.0 1.0 1) allElementsHaveTheSameValue

o  defaultElement

o  identicalValuesComputedBy: aBlock
true if aBlock answers identical values for all elements of the receiver

o  includes: searchedElement
return true, if an element equal to the argument, searchedElement is in the collection.
This compares using #= (i.e. it does not look for the object itself,
instead, one that compares equal).
See #includesIdentical: when identity is asked for.
This is a *very* slow fallback - many subclasses redefine this for performance.

o  includesAll: aCollection
return true if the receiver includes all elements of
the argument, aCollection; false if any is missing.
Notice: depending on the concrete collection,
this method may have O² runtime behavior,
and may be slow for big receivers/args.
Think about using a Set, or Dictionary.

usage example(s):

     #(1 2 3 4 5 6 7) includesAll:#(1 2 3)
     #('hello' 'there' 'world') includesAll:#('hello' 'world')
     #(1 2 3 4 5 6 7) includesAll:#(7 8 9)

o  includesAllKeys: aCollectionOfKeys
return true if the receiver includes all keys in aCollectionOfKeys,
false if any is missing.

o  includesAny: searchedElementsCollection
return true if the receiver includes any from the argument, aCollection.
Return false if it includes none.
Uses #= (value compare)
Notice:
depending on the concrete collection,
this method may have O² runtime behavior,
and may be slow for big receivers/args.
Think about using a Set, or Dictionary.

Some speedup is also possible, by arranging highly
probable elements towards the beginning of aCollection,
to avoid useless searches.

Also: I am not sure, if (and if so, at which breakeven),
it is better to reverse the loops, and walk over the receiver's
elements once, walking over the searched elements in the inner loop.
If the receiver is large, caching effects will definitely favour this,
as the smaller collection might fit into the cache.

usage example(s):

     #(1 2 3 4 5 6 7) includesAny:#(1 2 3)
     #('hello' 'there' 'world') includesAny:#('hello' 'world')
     #(1 2 3 4 5 6 7) includesAny:#(7 8 9)
     #(1 2 3 4 5 6 7) includesAny:#(8 9 10)

     |coll|
     coll := (1 to:10000) asOrderedCollection.
     Time millisecondsToRun:[
        1000000 timesRepeat:[ coll includesAny:#(500 600) ]
     ].

     |coll|
     coll := (1 to:10000).
     Time millisecondsToRun:[
        1000000 timesRepeat:[ coll includesAny:#(500 600) ]
     ].

     |coll|
     coll := (1 to:10000) asOrderedCollection.
     Time millisecondsToRun:[
        100000 timesRepeat:[ coll includesAny:#(-1 -10) ]
     ].

     Notice: it is redefined for string search in a subclass:

     |coll|
     coll := String new:10000 withAll:$a.
     coll at:500 put:$b.
     Time millisecondsToRun:[
        100000 timesRepeat:[ coll includesAny:'bc' ]
     ].

     |coll|
     coll := String new:10000 withAll:$a.
     Time millisecondsToRun:[
        100000 timesRepeat:[ coll includesAny:'bc' ]
     ].

o  includesAnyIdentical: searchedElementsCollection
return true, if the receiver includes any from the argument, aCollection.
Return false if it includes none.
Use identity compare for comparing.
Notice:
depending on the concrete collection,
this method may have O² runtime behavior for some subclasses
and may be slow for big receivers/args.
Think about using a Set or Dictionary.
Some speedup is also possible, by arranging highly
probable elements towards the beginning of aCollection, to avoid useless searches.

usage example(s):

     #(1 2 3 4 5 6 7) includesAnyIdentical:#(1 2 3)
     #('hello' 'there' 'world') includesAnyIdentical:#('hello' 'world')
     #(1 2 3 4 5 6 7) includesAnyIdentical:#(7 8 9)
     #(1 2 3 4 5 6 7) includesAnyIdentical:#(8 9 10)

o  includesAnyKey: aCollectionOfKeys
return true if the receiver includes any key from aCollectionOfKeys,
false if none is present.

o  includesIdentical: searchedElement
return true, if the argument, searchedElement is in the collection.
This compares using #== (i.e. object identity).
See #includes: when equality is asked for.
This is a *very* slow fallback - many subclasses redefine this for performance.

o  includesKey: aKey

** This method raises an error - it must be redefined in concrete classes **

o  isEmpty
return true, if the receiver is empty

o  isEmptyOrNil
return true if I am nil or an empty collection - true here, if the receiver's size is 0,
(from Squeak)

o  isReadOnly
true if this is a readOnly (immutable) collection.
Q1: should this be called isImmutable?
Q2: who uses this?

o  isValidElement: anObject
return true, if I can hold this kind of object

o  isWritable
true if this is not a readOnly (immutable) collection.
Q1: should this be called isMutable?
Q2: who uses this?

o  notEmpty
return true, if the receiver is not empty

o  notEmptyOrNil
Squeak compatibility:
return true if I am neither nil nor an empty collection.

o  occurrencesOf: anElement
return the number of occurrences of the argument, anElement in
the receiver. Uses #= (i.e. equality) compare.

o  occurrencesOfAny: aCollectionOfElements
return the number of occurrences of any in aCollectionOfElements in the receiver.
Uses #= (i.e. equality) compare.
Should be redefined in subclass(es) if ever used heavily.

usage example(s):

     #(1 4 6 8 4 1) occurrencesOfAny:#(1 4)
     #(1 4 6 8 4 1) occurrencesOfAny:#(2 5)
     'hello world' occurrencesOfAny:'hel'

o  sameValuesComputedBy: aBlock
true if aBlock answers equal values for all elements of the receiver

usage example(s):

     #(1 2 3 5 6 7 8 9) sameValuesComputedBy:[:el | el even]
     #(1 1 1 1 1 1) sameValuesComputedBy:[:el | el even]
     #(1 1 1.0 1.0 1) sameValuesComputedBy:[:el | el even]
     #(1 3 3 15 1) sameValuesComputedBy:[:el | el even]

o  size
return the number of elements in the receiver.
This is usually redefined in subclasses for more performance.

o  speciesForAdding
like species, but redefined for collections which cannot grow easily.
Used by functions which create a growing collection (see collect:with:, for example)

o  speciesForCollecting
like species, but used when doing collect operations.
Redefined for collections which return a different classes object when doing collect.

searching
o  findFirst: aBlock
find the index of the first element, for which evaluation of the argument, aBlock
returns true; return its index or 0 if none detected.
This is much like #detect, however, here an INDEX is returned,
while #detect returns the element.

usage example(s):

     #(1 2 3 4 5 6) findFirst:[:x | (x >= 3)]
     #(1 2 3 4 5 6) findFirst:[:x | (x >= 3) and:[x even]]
     #(1 2 3 4 5 6) findFirst:[:x | (x >= 8)]
     'one.two.three' findFirst:[:c | (c == $.)]
     '__one.two.three' findFirst:[:c | (c ~= $_)]
     'one.two.three' findFirst:[:c | (c ~= $_)]

o  findFirst: aBlock ifNone: exceptionValue
find the index of the first element, for which evaluation of the argument, aBlock returns true;
return its index or the value from exceptionValue if none detected.
This is much like #detect:ifNone:, however, here an INDEX is returned,
while #detect:ifNone: returns the element.

** This method raises an error - it must be redefined in concrete classes **

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

usage example(s):

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

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

** This method raises an error - it must be redefined in concrete classes **

o  keysOfLargest: n
return the keys (aka indices) of the n largest elements, key of largest last.
Raises an exception, if the receiver does not contain at least n elements

usage example(s):

     #(10 35 20 45 30 5) keysOfLargest:1    
     #(10 35 20 45 30 5) keysOfLargest:2    
     #(10 35 20 45 30 5) largest:2          
     #(10 35 20 45 30 5) keysOfLargest:3   
     #(10 35 20 45 30 5) keysOfLargest:5   
     #(10 35 20 45 30 5) keysOfLargest:6   
     #(10 35 20 45 30 5) keysOfLargest:8
      (1 to: 1000) asArray shuffled keysOfLargest:51

o  keysOfSmallest: n
return the keys (aka indices) of the n smallest elements, key of largest last.
Raises an exception, if the receiver does not contain at least n elements

usage example(s):

     #(10 35 20 45 30 5) keysOfSmallest:1    
     #(10 35 20 45 30 5) keysOfSmallest:2    
     #(10 35 20 45 30 5) smallest:2          
     #(10 35 20 45 30 5) keysOfSmallest:3   
     #(10 35 20 45 30 5) keysOfSmallest:5   
     #(10 35 20 45 30 5) keysOfSmallest:6   
     #(10 35 20 45 30 5) keysOfSmallest:8
      (1 to: 1000) asArray shuffled keysOfSmallest:51 

o  largest: n
return a collection containing the n largest elements, largest last.
Raises an exception, if the receiver does not contain at least n elements

usage example(s):

     #(10 35 20 45 30 5) largest:1   
     #(10 35 20 45 30 5) largest:2   
     #(10 35 20 45 30 5) largest:3   
     #(10 35 20 45 30 5) largest:5    
     #(10 35 20 45 30 5) largest:6    
     #(10 35 20 45 30 5) largest:8

o  longestCommonPrefix
return the longest common prefix of my elements.
Typically used with string collections.

usage example(s):

     #('Array' 'ArrayedCollection' 'ArrayOfFoo') longestCommonPrefix 
     #('Arra' 'ArrayedCollection' 'ArrayOfFoo') longestCommonPrefix 
     #('Arra' 'b' 'c') longestCommonPrefix 
     #( (1 2 3 4) (1 2 3) (1 2 3 7) (1 2 3 9 10 11)) longestCommonPrefix

o  longestCommonPrefixCaseSensitive: caseSensitive
return the longest common prefix of all of my elements (which must be sequenceable collections).
Typically used with string collections,
especially with completion of selectors or filenames.

usage example(s):

     #('Array' 'arrayedCollection' 'ARRAYOfFoo') longestCommonPrefixCaseSensitive:false 
     #('Array' 'arrayedCollection' 'ARRAYOfFoo') longestCommonPrefixCaseSensitive:true 
     #('Array' 'ArayedCollection' 'ARRAYOfFoo') longestCommonPrefixCaseSensitive:true   
     #('AAA' 'A11' 'AA2') longestCommonPrefixCaseSensitive:true   
     #('AAA' 'BBB' 'CCC') longestCommonPrefixCaseSensitive:true   

o  longestCommonPrefixIgnoreCase: ignoreCase
return the longest common prefix of my elements (which must be sequenceableCollections).
Typically used with string collections,
especially with completion of selectors or filenames.

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

o  longestCommonSuffix
return the longest common suffix (tail) of my elements.
Typically used with string collections.

usage example(s):

     #('abcdefg' '1234cdefg' 'aaaaaadefg') longestCommonSuffix    

o  longestCommonSuffixCaseSensitive: caseSensitive
return the longest common suffix (tail) of my elements
(which must be sequenceableCollections).

usage example(s):

     #('Array' 'ByteArray' 'BigArray') longestCommonSuffixCaseSensitive:false
     #('AAA' 'BBBAA' 'CCCAAAA') longestCommonSuffixCaseSensitive:true
     #('AAA' 'BBB' 'CCC') longestCommonSuffixCaseSensitive:true

o  longestCommonSuffixIgnoreCase: ignoreCase
return the longest common suffix (tail) of my elements
(which must be sequenceableCollections).

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

o  max
return the maximum value in the receiver collection,
using #< to compare elements.
Raises an error, if the receiver is empty.

usage example(s):

     #(15 1 -9 10 5) max  
     (1 to:15) max  
     (-1 to:-15 by:-1) max  
     (-1 to:-15 by:-4) max  
     (0 to:15 by:4) max     

o  max: comparator
return the maximum value in the receiver collection,
using comparator to compare elements.
The argument comparator is a 2-arg block returning true if the first arg is less than the second.
Raises an error if the receiver is empty.

usage example(s):

     find the largest element (same as max without comparator):
         #(15 1 -20 -9 10 5) max:[:a :b | a < b]

     find the element which has the largest abs value:
         #(15 1 -20 -9 10 5) max:[:a :b | a abs < b abs]

o  maxApplying: aBlock
return the maximum value from applying aBlock to each element in the receiver collection,
using aBlock to compare elements.
Raises an error, if the receiver is empty.

usage example(s):

     #() max                                        -> Error
     #(15 1 -9 -20 10 5) max                        -> 15
     #(15 1 -9 -20 10 5) maxApplying:[:el | el abs] -> 20

o  min
return the minimum value in the receiver collection,
using < to compare elements.
Raises an error if the receiver is empty.

usage example(s):

     #(15 1 -9 10 5) min
     (1 to:15) min
     (-1 to:-15 by:-1) min
     (-1 to:-15 by:-4) min

o  min: comparator
return the minimum value in the receiver collection,
using comparator to compare elements.
The argument comparator is a 2-arg block returning true if the first arg is less than the second.
Raises an error if the receiver is empty.

usage example(s):

     find the smallest element (same as min without comparator):
         #(15 1 -9 10 5) min:[:a :b | a < b]
     
     find the element which has the smallest abs value:
         #(15 1 -9 10 5) min:[:a :b | a abs < b abs]

o  minApplying: aBlock
return the minimum value from applying aBlock to each element in the receiver collection,
using aBlock to compare elements.
Raises an error, if the receiver is empty.

usage example(s):

     #(15 -1 -9 10 5) min                        -> -9
     #(15 -1 -9 10 5) minApplying:[:el | el abs] -> 1

o  minMax
return the minimum and maximum values in the receiver collection
as a two element array, using #< to compare elements.
Raises an error, if the receiver is empty.

usage example(s):

     #(15 1 -9 10 5) minMax  
     (1 to:15) minMax  
     (-1 to:-15 by:-1) minMax  
     (-1 to:-15 by:-4) minMax  
     (0 to:15 by:4) minMax     

o  nthLargest: n
return the n-largest element

usage example(s):

     #(10 35 20 45 30 5) nthLargest:1
     #(10 35 20 45 30 5) nthLargest:2
     #(10 35 20 45 30 5) nthLargest:3
     #(10 35 20 45 30 5) nthLargest:5
     #(10 35 20 45 30 5) nthLargest:6 
     #(10 35 20 45 30 5) nthLargest:8

o  smallest: n
return the n smallest elements

usage example(s):

     #(10 35 20 45 30 5) smallest:1
     #(10 35 20 45 30 5) smallest:2
     #(10 35 20 45 30 5) smallest:3
     #(10 35 20 45 30 5) smallest:5
     #(10 35 20 45 30 5) smallest:6
      (1 to:10000) asArray shuffled smallest:10
      (1 to:10000) asArray shuffled largest:10
     #(10 35 20 45 30 5) smallest:8

set operations
o  \ aCollection
return a new set containing all elements of the receiver,
which are NOT also contained in the aCollection
For large collections you better use a Set for aCollection

usage example(s):

     #(0 1 2 3 4 5 6 7 8 9) \ #(1 2 3) asSet
     #(0 1 2 3 4 5 6 7 8 9) \ #(1 2 3)
     ('hello' \ 'l')

     (Dictionary withKeysAndValues:#(1 'uno' 2 'due' 3 'tre' 4 'quatro'))
        \ (Dictionary withKeysAndValues:#(1 'uno'  4 'quatro'))

o  intersect: aCollection
return a new set containing all elements of the receiver,
which are also contained in the argument collection.
For large collections you better use a Set for aCollection

usage example(s):

     #(0 1 2 3 4 5 6 7 8 9) asSet intersect:#(1 2 3 11)
     #(0 1 2 3 4 5 6 7 8 9) intersect:#(1 2 3 11)

     (Dictionary withKeysAndValues:#(1 'uno' 2 'due' 3 'tre' 4 'quatro'))
        intersect:(Dictionary withKeysAndValues:#(1 'uno'  4 'quatro' 5 'cinque'))

o  union: aCollection
return a new set containing all elements of the receiver
plus those of the aCollection

usage example(s):

     #(0 2 4 6 8) union:#(1 3 5 7)
     #(0 2 4 6 8) union:#(0 1 3 5 7)

     (Dictionary withKeysAndValues:#(1 'uno' 2 'due' 3 'tre' 4 'quatro'))
        union:(Dictionary withKeysAndValues:#(1 'uno'  4 'quatro' 5 'cinque'))

o  xor: aCollection
return a new set containing all elements,
which are contained in either the receiver or aCollection, but not in both.

For large collections you better use Sets for both self and aCollection

usage example(s):

     #(0 1 2 3 4 5 6 7 8 9) xor:#(1 2 3 11)
     (Dictionary withKeysAndValues:#(1 'uno' 2 'due' 3 'tre' 4 'quatro'))
        xor:(Dictionary withKeysAndValues:#(1 'uno'  4 'quatro' 5 'cinque'))

sorting & reordering
o  sortedBy: aTwoArgBlock
Create a copy that is sorted. Sort criteria is the block that accepts two arguments.
When the block returns true, the first arg goes first ([:a :b | a > b] sorts in descending order).

o  sortedBySelector: aSelector
return a new collection containing my elements sorted based on the value of what aSelector returns when sent to my
elements. Sorting by a selector is so common, that it's worth a separate utility

o  topologicalSort
Sort a partial ordered collection.
The receiver consists of tupels defining a partial order.
Use the algorithm by R. E. Tarjan from 1972.
Answer an OrderedCollection containing the sorted items

o  topologicalSortStable: sortStable
Sort a partial ordered collection.
The receiver consists of tupels defining a partial order.
Use the algorithm by R. E. Tarjan from 1972.
Answer an OrderedCollection containing the sorted items.

If sortStable is true, try to make order stable among
multiple invocations. If false, stability is not guaranteed.

statistical functions
o  arithmeticMean
arithmetic mean value of all elements in the collection

usage example(s):

     TestCase assert:( { 1. 2. 3. 4 } arithmeticMean = 2.5).
     TestCase assert:( { 13. 23. 12. 44. 55 } arithmeticMean closeTo: 29.4).
     TestCase assert:( { 13. 23. 12. 44. 55 } standardDeviation closeTo: 19.2431).

o  average
average value of all elements in the collection

usage example(s):

     TestCase assert:( { 1. 2. 3. 4 } average = 2.5).

o  geometricMean
geometric mean value of all elements in the collection

usage example(s):

     TestCase assert:( { 1. 2. 3. 4. } geometricMean closeTo: 2.21336).
     TestCase assert:( { 1. 2. 3. 4. 5 } geometricMean closeTo: 2.60517).
     TestCase assert:( { 13. 23. 12. 44. 55 } geometricMean closeTo: 24.41932).

o  median
Return the middle element, or as close as we can get.

usage example(s):

     #(10 35 20 45 30 5) median

o  standardDeviation
standard deviation value of all elements in the collection,
which is the complete set and not a sample.

usage example(s):

     TestCase assert:( #( 1 2 3 4) arithmeticMean = 2.5).
     TestCase assert:( #(13 23 12 44 55) arithmeticMean closeTo: 29.4).
     TestCase assert:( #(13 23 12 44 55) standardDeviation closeTo: 17.2116).
     TestCase assert:( (1 to: 100) arithmeticMean = ((100 + 1)/2)).
     TestCase assert:( (1 to: 100) standardDeviation = ((100 squared - 1)/12) sqrt).
     TestCase assert:( (1 to: 6) standardDeviation = ((6 squared - 1)/12) sqrt).

o  variance
compute the variance over a complete data set (and not of a sample)

usage example(s):

        #(1 1 1 1 1 1 1 1 1 1) variance
        #(1 1 1 1 1 1 1 1 1 1) standardDeviation
        
        #(1 1 1 1 1 2 2 2 2 2) variance
        #(1 1 1 1 1 2 2 2 2 2) standardDeviation

        #(1 2 3 4 5 6 7 8 9 0) variance
        #(1 2 3 4 5 6 7 8 9 0) standardDeviation

testing
o  capacity
return the number of elements, that the receiver is prepared to take.
For most collections, this is the actual size.
However, some have more space preallocated to allow
for faster adding of elements (i.e. there are logical vs. physical sizes).

o  isCollection
return true, if the receiver is some kind of collection;
true is returned here - the method is redefined from Object.

o  isNilOrEmptyCollection
return true if I am nil or an empty collection - false here.
Obsolete, use isEmptyOrNil.

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

o  isNonByteCollection
return true, if the receiver is some kind of collection, but not a String, ByteArray etc.;
true is returned here - the method is redefined from Object.

o  isOrdered
return true, if the receiver's elements are ordered.
This defaults to true here, and is to be redefined by collections which use
hashing, and the order of keys and values is therefore not guaranteed to remain
the same, as objects are added.
Notice, that this query might be useless/false for some collections;
for example, a file directory may change its order even though smalltalk does not touch it;
or a collection which is based on computed block values may return completely differently
ordered elements (also random value collections, etc.).
Therefore, use this only as a hint
(e.g. when showing values, to avoid sorting and destroying
any previous order in the visual representation)

o  isSorted
return true, if the receiver is sorted.
Collections which hold their elements in sorted order
should return true. Some algorithms (quicksort) degenerate when
operating on sorted collections and can be avoided if this information
is given. The default returned here (false) should not hurt.
I.e. you should NEVER depend on that in your application.

o  isSortedBy: aBlock
return true, if my elements are sorted (already) by the given criterion (sortBlock).
Collections which hold their elements in sorted order
should return true. Some algorithms (quicksort) degenerate when
operating on sorted collections and can be avoided if this information
is given. The default returned here (false) should not hurt.
I.e. you should NEVER depend on that in your application.

o  isSortedCollection
return true, if the receiver is a sortedCollection.

tracing
o  traceInto: aRequestor level: level from: referrer
double dispatch into tracer, passing my type implicitely in the selector

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

xml conversion
o  asXMLElementNamed: aName
( an extension from the stx:goodies/xml/stx package )



ST/X 7.2.0.0; WebServer 1.670 at bd0aa1f87cdd.unknown:8081; Tue, 19 Mar 2024 07:21:25 GMT