Collection API Functions

This document lists most useful (and most often needed) functions. Be aware, that there are many more to be found in either the class references or via the builtin class browser.

Reference: Collection

Back to Useful API Functions

Notice: except when written otherwise, all indices are 1-based. Valid indices range from 1 to the collection's size.
Also notice: String is a subclass of Collection, which means that most of the functions listed below can also be applied to strings.

Accessing

aCollection size

aCollection.size() [JS]

Returns the number of elements in the collection (i.e. its length).

Example:

 'hello world' size
 => 11

 #(1 2 3) size
 => 3

aCollection at: index

aCollection [ índex ]   [JS or ST]

Returns the element at an index (1 based).

Depending on the type of collection, this will be a numeric index (Array, OrderedCollection) or a general access key (Dictionary, OrderedDictionary).
Example:

 'hello world' at:2
 => $e  (Notice: the dollar-char notation represents a character constant in Smalltalk)

 'hello world'[5]
 => $o

 #(90 4 50 20 99) asSortedCollection at:2
 => 20

aCollection at: index put: newValue => void

aCollection [ índex ] := newValue  [ST]

aCollection [ índex ] = newValue  [JS]

Changes the element at an index (1 based).

Depending on the type of collection, this will be a numeric index (Array, OrderedCollection) or a general access key (Dictionary, OrderedDictionary).
Example:

 s := 'hello world' copy.
 s at:2 put:$*.
 s
 => 'h*llo world'

 c := #(90 4 50 20 99) asOrderedCollection.
 c at:2 put:-1.
 c
 => OrderedCollection(90 -1 50 20 99)

 s := 'hello world' copy. (Notice: use a copy here, because constants are immutable)
 s[5] := $O.
 s
 => 'hellO world'

Copying by Numeric Index

These functions are applicable to collections with a numeric index (i.e. Array, OrderedCollection, ByteArray, String, SortedCollection, FloatArray, DoubleArray, etc.).

aCollection copyFrom: startIndex to: endIndex

aCollection.copyFrom_to( startIndex, endIndex )   [JS]

Copies elements from a start index to an end index (both being 1-based indices).
Example:

 'hello world' copyFrom:1 to:5. 
 => 'hello'

 #(10 20 30 40 50 60 70) copyFrom:1 to:5. 
 => #(10 20 30 40 50)

 (10 to: 100 by: 10) copyFrom:1 to:3. 
 => #(10 20 30)

aCollection copyFrom: startIndex count: numChars

aCollection.copyFrom_count( startIndex, numChars )   [JS]

Copies a number of elements starting at the given index.

Example: see example in String

aCollection copyFrom:' startIndex

aCollection.copyFrom( startIndex )   [JS]

Copies from the given index to the end.

Example: see example in String

aCollection copyTo: endIndex

aCollection.copyTo( endIndex )   [JS]

Copies from the start to the given index.

Example: see example in String

aCollection copyLast: count

aCollection.copyLast( count )   [JS]

Copies the last count characters.

Example: see example in String

aCollection copyButFirst: count

aCollection.copyButFirst( count )   [JS]

Copies except for the first count characters.

Example: see example in String

aCollection copyButLast: count

aCollection.copyButLast( count )   [JS]

Copies except for the last count characters.

Example: see example in String

collection1 , collection2 (The comma operator in Smalltalk)

Concatenates arbitrary collections
Example:

 #[10 20 30 40] , #[50 60 70 80]
 => #[10 20 30 40 50 60 70 80]

 'Hello' , 'World'
 => 'Hello World'

 (1 to:5) , (20 to:25) , #(88 99)
 => OrderedCollection(1 2 3 4 5 20 21 22 23 24 25 88 99)

 (2 to:10 by:2) , (20 to:10 by:-2)
 => OrderedCollection(2 4 6 8 10 20 18 16 14 12 10)

Splitting

aCollection splitBy: anElement => collection

aCollection.splitBy( anElement )   [JS]

Splits a collection into pieces, given a splitting element.
Example:

 #(10 11 12 0 20 22 24 0 1 2 3 0 50) splitBy: 0
 => #( #(10 11 12)  #(20 22 24) #(1 2 3) #(50) ).  <- this is an array of arrays

aCollection splitForSize: pieceSize => collection

Splits a collection into pieces of a given size (the last returned piece might be smaller).
Example:

 #(10 11 12 0 20 22 24 0 1 99) splitForSize: 3
 => #( #(10 11 12)  #(0 20 22) #(24 0 1) #(99) ).  <- this is an array of arrays

aCollection splitOn: element

aCollection splitOn: splitCollection

aCollection splitOn: [ :el | <condition-expression on el> ]

aCollection.splitOn( element )   [JS]

aCollection.splitOn( splitCollection )   [JS]

aCollection.splitOn( (el) => <condition-expression on el> )   [JS]

Splits a collection into pieces, given a splitter.

The splitter may be a single element, a collection of elements or a block, which returns true to split.

This is a more general version of the above "splitBy:", for complex splits.

Comparing

aCollection startsWith: prefixCollection [ caseSensitive: bool ] => bool

aCollection.startsWith( prefixCollection )   [JS]

aCollection.startsWith_caseSensitive( prefixCollection, bool ) [JS]

Checks if a collection starts with the same elements as another collection.

aCollection endsWith: suffixCollection [ caseSensitive: bool ] => bool

aCollection.endsWith( suffixCollection )   [JS]

Checks if a collection ends with the same elements as another collection.

Searching

aCollection indexOf: element

aCollection lastIndexOf: element

aCollection.indexOf( element )   [JS]

aCollection.lastIndexOf( element )   [JS]

Returns the first/last index of an element. Returns 0 if not found.
Example:

 'HELLO' indexOf: $L
 => 3

 'HELLO' indexOf: $x
 => 0

 'HELLO' lastIndexOf: $L
 => 4

 #(1 2 3 1 2 3 1 2 3) lastIndexOf:2
 => 8

aCollection indexOf: element startingAt: startIndex

aCollection lastIndexOf: element startingAt: startIndex

aCollection.indexOf_startingAt( element, startIndex )   [JS]

aCollection.lastIndexOf_startingAt( element, startIndex )   [JS]

Returns the next/previous index of an element given a search start index .

Returns 0 if not found.
Example:

 'HELLO WORLD' indexOf: $O startingAt: 6
 => 8

 'HELLO WORLD' indexOf: $x startingAt: 6
 => 0

 'HELLO WORLD' indexOf: $L startingAt: 6
 => 0

 'HELLO WORLD' lastIndexOf: $O startingAt: 7
 => 5

aCollection indexOfAny: aCollectionOfElements [ startingAt: startIndex ]

aCollection lastIndexOfAny: aCollectionOfElements [ startingAt: startIndex ]

aCollection.indexOfAny( aCollectionOfElements ) [JS]

aCollection.indexOfAny_startingAt( aCollectionOfElements, startIndex ) [JS]

aCollection.lastIndexOfAny( aCollectionOfElements ) [JS]

aCollection.lastIndexOfAny_startingAt( aCollectionOfElements, startIndex ) [JS]

Similar to the above, but searches for any element in the given argument collection.

This may be a string (of characters) or an array or any other collection of characters. Returns 0 if not found.

aCollection indexOfString: aSubString [ caseSensitive: boolean ] [ startingAt: startIndex ]

aCollection lastIndexOfString: aSubString [ startingAt: startIndex ]

Searches for a substring.
Example:

 'HELLO WORLD Hello' indexOfString: 'LL'
 => 3

 'HELLO WORLD Hello' indexOfString: 'll'
 => 0

 'HELLO WORLD Hello' indexOfString: 'll' caseSensitive: false
 => 3
 
 'HELLO WORLD hello' indexOfString: 'll' caseSensitive: false startingAt: 4 
 => 15
 
 'Hello World Hello' lastIndexOfString: 'll'
 => 15

Search & Extract

aCollection withoutPrefix: prefixCollection

aCollection withoutPrefix: prefixCollection caseSensitive: aBoolean (Strings only)

If aCollection starts with prefixCollection, a copy of the remaining (right) elements is returned. Otherwise, the original collection is returned.
Example:

 'SomeLongerString' withoutPrefix: 'Some'
 => 'LongerString'

 'SomeLongerString' withoutPrefix: 'some'
 => 'SomeLongerString'

 'SomeLongerString' withoutPrefix: 'some' caseSensitive: false
 => 'LongerString'

 'anotherString' withoutPrefix: 'Some'
 => 'anotherString'
 
 #(0 7 1 4 2 0 0 7 42) withoutPrefix: #(0 7 1 4 2)
 => #(0 0 7 42)

aCollection withoutSuffix: suffixCollection

aCollection withoutSuffix: suffixCollection caseSensitive: aBoolean (Strings only)

If aCollection ends with suffixCollection, a copy of the left part is returned. Otherwise, the original collection is returned.
Example:

 'foo.bar.baz' withoutSuffix: '.baz'
 => 'foo.bar'

 'foo.bar.x' withoutSuffix: '.baz'
 => 'foo.bar.x'
 Notice, for filenames, use withoutSuffix.

aCollection upTo: elementToSearch

aCollection restAfter: elementToSearch

Searches elementToSearch in aCollection and returns a copy of the left/right part.
Example:

 'foo.bar.baz' upTo: $.
 => 'foo'

 'foo.bar.x' restAfter: $.
 => 'bar.x'

aCollection upToAny: elementsToSearch

aCollection restAfterAny: elementsToSearch

Searches aCollection for any element in elementsToSearch and returns a copy of the left/right part.
Example:

 'foo;bar.baz' upToAny: '.,;'
 => 'foo'

 'foo bar.x' restAfterAny: '.,;'
 => 'x'

aCollection upToAll: sliceToSearch

aCollection restAfterAll: sliceToSearch

Searches for the sliceToSearch sequence in aCollection and returns a copy of the left/right part.
Example:

 'name: foo age: 124' upToAll: 'age:'
 => 'name: foo '

 'name: foo age: 124' restAfterAll: 'age:'
 => ' 124'

Converting

aCollection asByteArray

aCollection.asByteArray() [JS]

Returns a byte array containing the elements which must be integers in the ISO8859 range 0x00 .. 0xFF.

aCollection asSet

Returns a set containing each element at most once.

aCollection asOrderedCollection

Returns an ordered collection (that is a resizable dynamic array) containing the elements in the same order.

aCollection asSortedCollection

Returns a sorted collection (that is a resizable dynamic collection which automatically sorts in additional elements).

Sorting

aCollection sorted

aCollection sortedBy: compareBlock

Returns a sorted copy of the collection (no side effect on the collection).

If a condition argument (a block) is given, that should return true if the first argument is to come before the second. I.e. without a condition, the behavior is the same as "sortedBy:[:elA :elB | elA < elB]".

Examples

hello world sorted
 => ' dehllloorw'

#(10 2 99 17 -5 100) sorted
 => #(-5 2 10 17 99 100)

#(10 2 99 17 -5 100) sortedBy:[:a :b | a > b]
 => #(100 99 17 10 2 -5)

#('Paul' 'paula'  'Thomas' 'James'  'Emma') sorted
 => #('Emma' 'James' 'Paul' 'Thomas' 'paula')

#('Paul' 'paula'  'Thomas' 'James'  'Emma') sorted:[:a :b | a > b]
 => #('paula' 'Thomas' 'Paul' 'James' 'Emma')

#('Paul' 'paula'  'Thomas' 'James'  'Emma') sorted:[:a :b | a < b]
 => OrderedCollection('Emma' 'James' 'Paul' 'Thomas' 'paula')

#('Paul' 'paula'  'Thomas' 'James'  'Emma') sorted:[:a :b | a caselessBefore: b]
 => #('Emma' 'James' 'Paul' 'paula' 'Thomas')

#('Paul' 'paula'  'Thomas' 'James'  'Emma') sorted:[:a :b | b caselessBefore: a]
 => #('Thomas' 'paula' 'Paul' 'James' 'Emma')

aCollection sort

aCollection sort: compareBlock

Sorts the collection in place (i.e. has a side effect on the collection).

aCollection reversed

Returns a copy with elements in reverse oerder

aCollection reverse

Inplace reverts the elements (i.e. modifies the collection)

Enumerating

In Smalltalk there is almost never a need to program a loop which fetches and processes elements. You should use the provided enumeration functions for that, both for readability and because some of them are highly optimized.

aCollection do: [ :el | ... ]

aCollection.do: ( function(el) { ... } ) [JS] (Function notation)

aCollection.do: ( (el) -> ...) [JS] (Lambda notation)

evaluates the argument block for each element in the collection. The "do:" method is supported by all collections and even some non-collections (for example some widgets which present lists or text lines may also support the do: message to enumerate their contents).

Examples

 #(10 5 4 20 99) do:[:eachElement |
    Transcript showCR: eachElement.
    myFile nextPutLine:(eachElement hexPrintString).
 ]

 #(10 5 4 20 99) sorted do:[:eachElement |
    Transcript showCR: eachElement.
 ]

 "/ info: "(nr1 to: nr2)" generates a range collection 
 "/ (called Interval in Smalltalk)
 (1 to:10) do:[:each |
    Transcript printf:'%3d: %4d\n' with:each with:(each * each).
 ]

 "/ a kind of "ls" implementation: lists files of the current folder 
 '.' asFilename files do:[:eachFile |
    Transcript showCR: eachFile.
 ]

 "/ this prints the contents of each file
 '.'asFilename files do:[:eachFile |
    Transcript showCR: eachFile.
    eachFile contents do:[:eachLine |
        Transcript showCR: eachLine.
    ]
 ]

 "/ the same but shorter and even faster...
 '.'asFilename files do:[:eachFile |
    Transcript showCR: eachFile.
    Transcript showCR: eachFile contents.
 ]

aCollection keysAndValuesDo: [ :k :el | ... ]

aCollection doWithIndex: [ :el :k | ... ]

evaluates the 2-argument block for each key and element in the collection. This is supported by all indexable collections. For arrays and other collections with a numeric index, that is provided as key. For dictionaries, the lookup key is provided.

The doWithIndex: variant performs the same function, but provides the argument in reverse order into the block (syntactic sugar for readability).

Examples

 #(10 5 4 20 99) keysAndValuesDo:[:eachIndex :eachElement |
    Transcript show: eachIndex.
    Transcript show:' -> '.
    Transcript showCR: eachElement.
 ] 

 d := Dictionary new.
 d at:'foo' put:123.
 d at:'bar' put:999.
 d keysAndValuesDo:[:eachKey :eachElement |
    Transcript show: eachKey .
    Transcript show:' -> '.
    Transcript showCR: eachElement.
 ] 

aCollection collect: [ :el | ... ]

evaluates the argument block for each element in the collection and collects the results, returning a new collection with all results (this is called "map" in other languages).

Examples

 '.' asFilename files collect:[:eachFile | eachFile fileSize].

 Transcript showCR:
    (1 to:10) collect:[:nr | nr * nr]

aCollection select: [ :el | ... ]

evaluates the boolean argument block for each element in the collection and collects those elements for which the block returns true. I.e. this is filtering elements by a boolean condition.

Examples

 "/ lists files larger than 10000 bytes 
 '.' asFilename files select:[:eachFile | eachFile fileSize > 10000].

 Transcript
    showCR: 'even numbers:'; 
    showCR: (1 to:100) select:[:nr | nr even]

aCollection reject: [ :el | ... ]

similar to select, but this returns the complement: a new collection without elements for which the boolean argument block returns true.

aCollection count: [ :el | ... ]

counts for how many elements the boolean argument block returns true.

Examples

 "/ how many files are larger than 10000 bytes 
 '.' asFilename files count:[:eachFile | eachFile fileSize > 10000].

aCollection detect: [ :el | ... ]

find and return the first element for which the boolean argument block returns true. If none is found, an error is reported.

aCollection detect: [ :el | ... ] ifNone: replacementBlock

find and return the first element for which the boolean argument block returns true. If none is found, replacementBlock is evaluated and its value returned.

Examples

 #(1 2 3 4 5) detect:[:el | el > 10]
   => reports an error: no such element

 #(1 2 3 4 5) detect:[:el | el > 10] ifNone:[99]
   => 99

 #(1 2 3 4 5) detect:[:el | el > 10] ifNone:[ Dialog warn:'No such element'. nil]
   => nil. (after the warning is shown)

aCollection findFirst: [ :el | ... ]

aCollection findLast: [ :el | ... ]

find the index of the first/last element for which the boolean condition block returns true. Returns 0 if no element matches the condition.

Examples

 #(15 2 -3 44 5.3) findFirst:[:el | el > 20]
   => 4 (the index of the found element)

 'Hello World' findFirst:[:ch | ch isSeparator]
   => 6

There are many more (hundreds) of additional useful enumeration messages to be found in the collection hierarchy. For example to enumerate in groups, stepping over elements, enumerating multiple collections together, enumerating in reverse order etc.

For details, open a System Browser (via the Extras - Tools menu) and take look at the collection class and its subclasses.

Also notice that Strings, NumberVectors, ByteArrays etc. also inherit from Collection; thus, all of those functions can also be applied to them.

---

Copyright © 2014-2024 eXept Software AG