Lists (teed)
Soplang lists: indexing, insertion, removal, copying, slicing, sorting, search, and callbacks.
A list (teed) is an ordered collection of values. Items may have different
types. Use teed for an explicitly typed declaration, or door for a dynamic
variable holding a list.
Creating and Reading Lists
teed tirooyin = [10, 20, 30] qor(tirooyin.dherer()) // 3 qor(tirooyin[0]) // 10 qor(tirooyin[-1]) // 30 qor(tirooyin.hore()) // 10 qor(tirooyin.dambe()) // 30 qor(tirooyin.hel(9, 0)) // 0
Indexes start at 0; negative indexes count from the end. An out-of-range
read returns maran. hel(index, default?) returns the supplied default
only when the position is absent. A stored maran value is returned unchanged.
hore() and dambe() return maran for an empty list.
Adding, Replacing, and Removing Items
| Method | Description |
|---|---|
geli(value) | Append one value, including when that value is another list |
geli(index, value) | Insert one value at the specified position |
dhig(index, value) | Replace an existing item without creating a new position |
saar() | Remove and return the last item |
saar(index) | Remove and return the item at that position |
nadiifi() | Remove all items |
door tirooyin = [10, 20] tirooyin.geli(30) tirooyin.dhig(0, 5) qor(tirooyin.saar(1)) // 20 qor(tirooyin) // [5, 30] tirooyin.geli([40, 50]) qor(tirooyin) // [5, 30, [40, 50]]
Calling saar() on an empty list or writing to an out-of-range position
produces a catchable error. Other mutating list methods return the original list.
Combining and Copying
midee(other) returns a new list. nuqul() and jar() also create new
lists. These copies are shallow: nested lists and objects remain shared with
the original.
door asal = [10, 20, 30] door natiijo = asal.midee([40]) qor(asal) // [10, 20, 30] qor(natiijo) // [10, 20, 30, 40] qor(asal.jar(1, 3)) // [20, 30] qor(asal.jar(-2)) // [20, 30]
The end bound of jar(start?, end?) is excluded. Bounds must be integers and
are clamped to the list's length. Reversed bounds produce an empty list.
jar() without arguments copies the entire list.
Search, Counting, and Sorting
| Method | Result |
|---|---|
leeyahay(value) | run when the value is present |
raadi(value) | The first matching index, or maran when absent |
tiri(value) | The number of matching items |
rog() | Reverse the original list in place |
habee() | Sort the original list in place |
door tirooyin = [10, 2, 3, 2] tirooyin.habee() qor(tirooyin) // [2, 2, 3, 10] qor(tirooyin.raadi(2)) // 0 qor(tirooyin.raadi(99)) // maran qor(tirooyin.tiri(2)) // 2
Numbers are sorted numerically. Lists containing mixed types use the runtime's
comparison rules; do not assume Somali collation or a uniform numeric ordering
across types. A successful search may return 0, so test explicitly for
maran when checking for a missing item. Collection equality distinguishes
abn from jajab.
Callback Methods
| Method | Description |
|---|---|
aaddin(callback) | Transform each item and return a new list |
shaandhee(callback) | Return the items that satisfy the condition |
ururi(callback, initial) | Fold left; the callback receives the accumulated result and next item |
dhammaan(callback) | Check whether all items satisfy the condition |
qaar(callback) | Check whether at least one item satisfies the condition |
door tirooyin = [1, 2, 3, 4] qor(tirooyin.aaddin(hawl(x) { celi x * 2 })) // [2, 4, 6, 8] qor(tirooyin.shaandhee(hawl(x) { celi x % 2 == 0 })) // [2, 4] qor(tirooyin.ururi(hawl(a, b) { celi a * b }, 1)) // 24 qor(tirooyin.dhammaan(hawl(x) { celi x > 0 })) // run qor(tirooyin.qaar(hawl(x) { celi x > 3 })) // run
Iteration uses a shallow snapshot taken at the start. A callback may change
the original list without changing the remaining iteration sequence. A callback
error stops the operation and propagates to qabo. dhammaan() and qaar()
stop as soon as the result is known; on an empty list they return run and
been, respectively.
Supported earlier names and the different overloads of kudar() are explained
in the reference.