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

Concatenation

, (comma)

collection1 , collection2

Example:

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

Splitting

splitBy:

Splits a collection into pieces, given a splitting element.

aCollection splitBy: anElement
aCollection.splitBy( anElement ) [JS]

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

splitOn:

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.

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]

Comparing

startsWith:[caseSensitive:]

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

aCollection startsWith: prefixCollection
aCollection.startsWith( prefixCollection ) [JS]

Example:

endsWith:

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

aCollection endsWith: suffixCollection
aCollection.endsWith( suffixCollection ) [JS]

Searching

indexOf: / lastIndexOf:

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

aCollection indexOf: element
aCollection lastIndexOf: element
aCollection.indexOf( element ) [JS]
aCollection.lastIndexOf( element ) [JS]

Example:

 'HELLO' indexOf: $L
 => 3

 'HELLO' indexOf: $x
 => 0

 'HELLO' lastIndexOf: $L
 => 4

indexOf:startingAt: / lastIndexOf:startingAt:

Returns the next/previous index of an element given a search start index . Returns 0 if not found.

aCollection indexOf: element startingAt: startIndex
aCollection lastIndexOf: element startingAt: startIndex
aCollection.indexOf_startingAt( element, startIndex ) [JS]
aCollection.lastIndexOf_startingAt( element, startIndex ) [JS]

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

indexOfAny:[startingAt:] / lastIndexOfAny:[startingAt:]

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

Example:

Converting

asByteArray

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

aCollection asByteArray
aCollection.asByteArray() [JS]

Sorting

sorted

Returns a sorted copy of the collection.

hello world sorted
 => ' dehllloorw'

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

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

sort

Sorts the collection in place.

---

Copyright © 2014-2024 eXept Software AG