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

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

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

Concatenates arbitrary collections
Example:

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

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

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.

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 caselessBefore: b]
 => #('Emma' 'James' 'Paul' 'paula' 'Thomas')

aCollection sorted

aCollection sorted: compareBlock

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

---

Copyright © 2014-2024 eXept Software AG