collections reference

Reads and updates arrays, rolling buffers, and maps; float collections support null and missing map reads return null.

collection.len

collection.len: int

Returns the number of items in the collection.

Arrays and rolling buffers count stored elements, including null float values. Maps count keys, including keys whose values are null.

Example

script "Collection Length"
data chart = subscribe(data.ohlcv)

state closes: rolling<float> = rolling<float>(20)

on chart.update {
  closes.push(chart.close)
  let sampleCount = closes.len
}

collection.isEmpty

collection.isEmpty: bool

Reports whether the collection is empty.

Returns true when len == 0. A map with a key whose value is null is still non-empty.

Example

script "Collection Empty"
data chart = subscribe(data.ohlcv)

state prices = map<string, float>(4)

on chart.update {
  let needsSeed = prices.isEmpty
  prices.set("last", chart.close ?? 0.0)
}

collection.capacity

collection.capacity: int

Returns the maximum number of items the collection can hold.

Arrays, rolling buffers, and mutable maps use the capacity set when they were created. A frozen map's capacity equals its length.

Example

script "Collection Capacity"
data chart = subscribe(data.ohlcv)

state closes: rolling<float> = rolling<float>(20)

on chart.update {
  closes.push(chart.close)
  let room = closes.capacity - closes.len
}

collection.isFull

collection.isFull: bool

Reports whether a rolling buffer currently holds its full capacity.

isFull is true once a rolling buffer's len equals its capacity. Plain arrays do not support isFull; compare len with capacity when an array needs the same test.

Example

script "Rolling Full"
data chart = subscribe(data.ohlcv)

state closes: rolling<float> = rolling<float>(20)

on chart.update {
  closes.push(chart.close)
  let full = closes.isFull
}

collection.get

collection.get(index: int) -> Item?

Reads the element at an index.

index counts from 0, starting with the oldest element. Returns null for a negative index or an index at or beyond len, including rolling-buffer slots that have not filled yet.

A stored float can also be null. Other element types cannot store null.

Contracts

• index: Accepted range: 0 up to but not including len. Invalid values return null.

Example

script "Collection Get"
data chart = subscribe(data.ohlcv)

state closes: rolling<float> = rolling<float>(20)

on chart.update {
  closes.push(chart.close)
  let oldest = closes.get(0) ?? chart.close
}

collection.set

collection.set(index: int, value: Item) -> void

Replaces the element at an index.

index counts from 0, starting with the oldest element. value replaces that element; a[i] = v does the same thing.

A negative index or an index at or beyond len stops the script with an error. Float collections can store null. Null values for other element types are rejected before the script runs.

Contracts

• index: Accepted range: 0 up to but not including len. Invalid values are rejected.

Example

script "Collection Set"
data chart = subscribe(data.ohlcv)

state closes: rolling<float> = rolling<float>(20)

on chart.update {
  closes.push(chart.open)
  closes.set(0, chart.close)
}

collection.push

collection.push(value: Item) -> per-receiver

Adds an element to the end of the collection.

value becomes the newest element.

• Arrays stop the script with an error if they are already full.
• Rolling buffers remove and return the oldest element when full. If there was room, they return null.

Float collections can store null. Null values for other element types are rejected before the script runs.

Example

script "Collection Push"
data chart = subscribe(data.ohlcv)

state closes: rolling<float> = rolling<float>(3)

on chart.update {
  let evicted = closes.push(chart.close)
}

collection.pop

collection.pop() -> Item?

Removes and returns the newest element.

Returns null if the collection is empty. A removed float element can also be null. Rolling buffers support pop for every element type.

Example

script "Collection Pop"
data chart = subscribe(data.ohlcv)

state closes: rolling<float> = rolling<float>(20)

on chart.update {
  closes.push(chart.close)
  let newest = closes.pop() ?? chart.close
}

collection.shift

collection.shift() -> Item?

Removes and returns the oldest element.

Returns null if the collection is empty. A removed float element can also be null. Rolling buffers support shift for every element type.

Example

script "Collection Shift"
data chart = subscribe(data.ohlcv)

state closes: rolling<float> = rolling<float>(20)

on chart.update {
  closes.push(chart.close)
  let oldest = closes.shift() ?? chart.close
}

collection.first

collection.first() -> Item?

Reads the oldest element.

Returns null if the collection is empty or the stored float value is null. Use last to read the newest element.

Example

script "Collection First"
data chart = subscribe(data.ohlcv)

state closes: rolling<float> = rolling<float>(20)

on chart.update {
  closes.push(chart.close)
  let oldest = closes.first() ?? chart.close
}

collection.last

collection.last() -> Item?

Reads the newest element.

Returns null if the collection is empty or the stored float value is null. Use first to read the oldest element.

Example

script "Collection Last"
data chart = subscribe(data.ohlcv)

state closes: rolling<float> = rolling<float>(20)

on chart.update {
  closes.push(chart.close)
  let newest = closes.last() ?? chart.close
}

collection.clear

collection.clear() -> void

Removes every item from the collection.

After clearing, len is zero. Arrays and rolling buffers have no elements, and maps have no keys. Stored null values are removed too.

Frozen maps cannot be cleared; attempting this is rejected before the script runs.

Example

script "Collection Clear"
data chart = subscribe(data.ohlcv)

state closes: rolling<float> = rolling<float>(20)

on chart.update {
  closes.push(chart.close)
  closes.clear()
}

collection.map

collection.map(f: |x| U) -> U[]

Creates a new array by transforming each element.

f receives each stored element from oldest to newest, including null floats. Its return value becomes the corresponding element in the new array.

The new array has the same length and capacity as the source. A rolling buffer also returns an ordinary array and visits only the elements it currently holds.

Example

script "Collection Map"
data chart = subscribe(data.ohlcv)

state closes: rolling<float> = rolling<float>(20)

on chart.update {
  closes.push(chart.close)
  let doubled = closes.map(|x| x * 2.0)
}

collection.filter

collection.filter(p: |x| bool) -> Item[]

Creates a new array containing the elements that pass a test.

p receives each stored element from oldest to newest, including null floats. Return true to keep an element or false to skip it; the result cannot be null.

The new array keeps the element type, order, and capacity of the source. A rolling buffer also returns an ordinary array and visits only its current elements.

Example

script "Collection Filter"
data chart = subscribe(data.ohlcv)

state closes: rolling<float> = rolling<float>(20)

on chart.update {
  closes.push(chart.close)
  let positive = closes.filter(|x| x > 0.0)
}

collection.reduce

collection.reduce(init: R, f: |acc, x| R) -> R

Combines the elements into one value.

init is the starting total. f receives the current total and the next element, then returns the new total. Elements are visited from oldest to newest, including null floats. An empty collection returns init unchanged.

A rolling buffer visits only the elements it currently holds.

Example

script "Collection Reduce"
data chart = subscribe(data.ohlcv)

state closes: rolling<float> = rolling<float>(20)

on chart.update {
  closes.push(chart.close)
  let total = closes.reduce(0.0, |acc, x| acc + (x ?? 0.0))
}

collection.sum

collection.sum() -> same_item_numeric

Adds all non-null numbers.

Available for numeric collections. Null float elements are skipped. The result keeps the element type.

Returns 0 if the collection is empty or every element is null.

Example

script "Collection Sum"
data chart = subscribe(data.ohlcv)

state closes: rolling<float> = rolling<float>(20)

on chart.update {
  closes.push(chart.close)
  let total = closes.sum()
}

collection.avg

collection.avg() -> float?

Returns the average of the non-null numbers.

Available for numeric collections. Null float elements are skipped. Divides by the number of non-null elements. The result is always a float.

Returns null if the collection is empty or every element is null.

Example

script "Collection Avg"
data chart = subscribe(data.ohlcv)

state closes: rolling<float> = rolling<float>(20)

on chart.update {
  closes.push(chart.close)
  let mean = closes.avg() ?? chart.close
}

collection.min

collection.min() -> same_item_numeric?

Returns the smallest non-null number.

Available for numeric collections. Null float elements are skipped. Infinities compare normally. A non-null result keeps the element type.

Returns null if the collection is empty or every element is null.

Example

script "Collection Min"
data chart = subscribe(data.ohlcv)

state lows: rolling<float> = rolling<float>(20)

on chart.update {
  lows.push(chart.low)
  let low = lows.min() ?? chart.low
}

collection.max

collection.max() -> same_item_numeric?

Returns the largest non-null number.

Available for numeric collections. Null float elements are skipped. Infinities compare normally. A non-null result keeps the element type.

Returns null if the collection is empty or every element is null.

Example

script "Collection Max"
data chart = subscribe(data.ohlcv)

state highs: rolling<float> = rolling<float>(20)

on chart.update {
  highs.push(chart.high)
  let high = highs.max() ?? chart.high
}

collection.variance

collection.variance() -> float?

Returns the population variance of the non-null numbers.

Available for numeric collections. Null float elements are skipped. Divides by the number of non-null elements.

Returns null if the collection is empty or every element is null.

Example

script "Collection Variance"
data chart = subscribe(data.ohlcv)

state closes: rolling<float> = rolling<float>(20)

on chart.update {
  closes.push(chart.close)
  let varianceValue = closes.variance() ?? 0.0
}

collection.stdev

collection.stdev() -> float?

Returns the population standard deviation of the non-null numbers.

Available for numeric collections. Null float elements are skipped. This is the square root of the population variance.

Returns null if the collection is empty or every element is null.

Example

script "Collection Stdev"
data chart = subscribe(data.ohlcv)

state closes: rolling<float> = rolling<float>(20)

on chart.update {
  closes.push(chart.close)
  let sigma = closes.stdev() ?? 0.0
}

collection.range

collection.range() -> same_item_numeric?

Returns the difference between the largest and smallest non-null numbers.

Available for numeric collections. Null float elements are skipped. A non-null result keeps the element type.

Returns null if the collection is empty or every element is null.

Example

script "Collection Range"
data chart = subscribe(data.ohlcv)

state ranges: rolling<float> = rolling<float>(20)

on chart.update {
  ranges.push(chart.high - chart.low)
  let span = ranges.range() ?? 0.0
}

collection.absSum

collection.absSum() -> same_item_numeric

Adds the absolute values of the non-null numbers.

Available for numeric collections. Null float elements are skipped. The result keeps the element type.

Returns 0 if the collection is empty or every element is null.

Example

script "Collection Abs Sum"
data chart = subscribe(data.ohlcv)

state moves: rolling<float> = rolling<float>(20)

on chart.update {
  moves.push(chart.close - chart.open)
  let grossMove = moves.absSum()
}

collection.sumLast

collection.sumLast(n: int) -> same_item_numeric

Adds the numbers in the last n elements.

n chooses how many elements to inspect from the newest end. Use a value from 0 to len, inclusive; other values stop the script with an error.

Available for numeric collections. Null float elements are skipped. An empty selection, including n = 0, returns 0.

Contracts

• n: Accepted range: 0 to len. Invalid values are rejected.

Example

script "Collection Sum Last"
data chart = subscribe(data.ohlcv)

state closes: rolling<float> = rolling<float>(20)

on chart.update {
  closes.push(chart.close)
  let recentTotal = closes.sumLast(math.min(5, closes.len))
}

collection.avgLast

collection.avgLast(n: int) -> float?

Averages the numbers in the last n elements.

n chooses how many elements to inspect from the newest end. Use a value from 0 to len, inclusive; other values stop the script with an error.

Available for numeric collections. Null float elements are skipped. Divides by the number of non-null elements in the selection and returns a float. An empty or all-null selection, including n = 0, returns null.

Contracts

• n: Accepted range: 0 to len. Invalid values are rejected.

Example

script "Collection Avg Last"
data chart = subscribe(data.ohlcv)

state closes: rolling<float> = rolling<float>(20)

on chart.update {
  closes.push(chart.close)
  let recentMean = closes.avgLast(math.min(5, closes.len)) ?? chart.close
}

collection.includes

collection.includes(value: Item) -> bool

Reports whether the collection contains a value.

Returns true if an element equals value, otherwise false. +0.0 and -0.0 compare equal; infinities compare normally.

Null elements never match a search value, even null. For struct elements, all fields are compared. Two null fields count as equal.

Example

script "Collection Includes"
data chart = subscribe(data.ohlcv)

state marks: rolling<float> = rolling<float>(20)

on chart.update {
  marks.push(chart.close)
  let seen = marks.includes(chart.close)
}

collection.indexOf

collection.indexOf(value: Item) -> int?

Finds the first element equal to a value.

Returns the first matching index or null if there is no match. Index 0 is the oldest element.

Null elements never match a search value, even null. For struct elements, all fields are compared. Two null fields count as equal.

Example

script "Collection Index"
data chart = subscribe(data.ohlcv)

state marks: rolling<float> = rolling<float>(20)

on chart.update {
  marks.push(chart.close)
  let i = marks.indexOf(chart.close) ?? -1
}

collection.lastIndexOf

collection.lastIndexOf(value: Item) -> int?

Finds the last element equal to a value.

Returns the last matching index or null if there is no match. Index 0 is still the oldest element; the search starts from the newest end.

Null elements never match a search value, even null. For struct elements, all fields are compared. Two null fields count as equal.

Example

script "Collection Last Index"
data chart = subscribe(data.ohlcv)

state marks: rolling<float> = rolling<float>(20)

on chart.update {
  marks.push(chart.close)
  let i = marks.lastIndexOf(chart.close) ?? -1
}

collection.countEq

collection.countEq(value: Item) -> int

Counts the elements equal to a value.

Returns the number of elements equal to value. +0.0 and -0.0 compare equal. The count is never null.

Null elements never match a search value, even null. For struct elements, all fields are compared. Two null fields count as equal.

Example

script "Collection Count Eq"
data chart = subscribe(data.ohlcv)

state marks: rolling<float> = rolling<float>(20)

on chart.update {
  marks.push(chart.close)
  let hits = marks.countEq(chart.close)
}

collection.countGt

collection.countGt(value: Item) -> int

Counts the numbers greater than a value.

Compares each numeric element with value. Null elements are skipped, and a null value matches nothing. Infinities compare normally. +0.0 and -0.0 compare equal.

Example

script "Collection Count Gt"
data chart = subscribe(data.ohlcv)

state marks: rolling<float> = rolling<float>(20)

on chart.update {
  marks.push(chart.close)
  let above = marks.countGt(chart.close)
}

collection.countGte

collection.countGte(value: Item) -> int

Counts the numbers greater than or equal to a value.

Compares each numeric element with value. Null elements are skipped, and a null value matches nothing. Infinities compare normally. +0.0 and -0.0 compare equal.

Example

script "Collection Count Gte"
data chart = subscribe(data.ohlcv)

state marks: rolling<float> = rolling<float>(20)

on chart.update {
  marks.push(chart.close)
  let atOrAbove = marks.countGte(chart.close)
}

collection.countLt

collection.countLt(value: Item) -> int

Counts the numbers less than a value.

Compares each numeric element with value. Null elements are skipped, and a null value matches nothing. Infinities compare normally. +0.0 and -0.0 compare equal.

Example

script "Collection Count Lt"
data chart = subscribe(data.ohlcv)

state marks: rolling<float> = rolling<float>(20)

on chart.update {
  marks.push(chart.close)
  let below = marks.countLt(chart.close)
}

collection.countLte

collection.countLte(value: Item) -> int

Counts the numbers less than or equal to a value.

Compares each numeric element with value. Null elements are skipped, and a null value matches nothing. Infinities compare normally. +0.0 and -0.0 compare equal.

Example

script "Collection Count Lte"
data chart = subscribe(data.ohlcv)

state marks: rolling<float> = rolling<float>(20)

on chart.update {
  marks.push(chart.close)
  let atOrBelow = marks.countLte(chart.close)
}

collection.map.get

collection.map.get(key: Key) -> Item?

Reads the value stored for a key.

key selects the entry. A missing key returns null; use ?? for a fallback. Stored null values also return null. On a frozen map, a constant key known to exist can return a non-null type.

A null key is rejected before the script runs when it is known then; otherwise it stops the script with an error.

Example

script "Map Get"
data chart = subscribe(data.ohlcv)

state prices = map<string, float>(4)

on chart.update {
  prices.set("last", chart.close ?? 0.0)
  let px = prices.get("last") ?? chart.close
}

collection.map.set

collection.map.set(key: Key, value: Item) -> void

Adds a key and value or replaces an existing value.

Stores value at key. Replacing a value keeps the key's position in insertion order. Values may be null.

Adding a new key when full stops the script with an error. Replacing an existing value when full is allowed. Frozen maps cannot be changed.

A null key is rejected before the script runs when it is known then; otherwise it stops the script with an error.

Example

script "Map Set"
data chart = subscribe(data.ohlcv)

state prices = map<string, float>(4)

on chart.update {
  prices.set("last", chart.close ?? 0.0)
}

collection.map.has

collection.map.has(key: Key) -> bool

Reports whether a key exists in the map.

key selects the entry to check. Returns true even if its stored value is null.

A null key is rejected before the script runs when it is known then; otherwise it stops the script with an error.

Example

script "Map Has"
data chart = subscribe(data.ohlcv)

state prices = map<string, float>(4)

on chart.update {
  prices.set("last", chart.close ?? 0.0)
  let known = prices.has("last")
}

collection.map.delete

collection.map.delete(key: Key) -> bool

Removes a key and its value.

key selects the entry to remove. Returns true if the key existed or false if it was missing, including when the stored value was null. Frozen maps cannot be changed.

A null key is rejected before the script runs when it is known then; otherwise it stops the script with an error.

Example

script "Map Delete"
data chart = subscribe(data.ohlcv)

state prices = map<string, float>(4)

on chart.update {
  prices.set("last", chart.close ?? 0.0)
  let removed = prices.delete("last")
}