API reference
GD.collection
Reshape Arrays and Dictionaries and create heaps, queues, and caches. Awaitable operations use CPU workers or the runtime ready queue; callable work cooperates with other tasks without requiring SceneTree frames.
Methods
group_by(items: Array, key: Callable) -> Dictionarymap_values(src: Dictionary, fn: Callable) -> Dictionaryfilter_keys(src: Dictionary, pred: Callable) -> Dictionarypartition(items: Array, pred: Callable) -> Arraychunk(items: Array, size: int) -> Arrayunique_by(items: Array, key: Callable) -> Arrayunique(items: Array) -> Arraysort_by(items: Array, pick: Callable) -> Arraysort_key(items: Array, key: String) -> Arrayzip(a: Array, b: Array) -> Arraysum_of(items: Array, pick: Callable) -> floatmax_by(items: Array, pick: Callable) -> Variantmin_by(items: Array, pick: Callable) -> Variantindex_by(items: Array, key: Callable) -> Dictionarydeep_merge(base: Dictionary, over: Dictionary) -> Dictionarybinary_heap(pick: Callable = null) -> GDBinaryHeappriority_queue() -> GDPriorityQueuelru_cache(limit: int = 128, ttl_ms: int = 0) -> GDLRUCachememo(fn: Callable, limit: int = 128) -> GDMemoizedCallablegroup_by_async(items: Array, key: Callable) -> await Dictionarymap_values_async(src: Dictionary, fn: Callable) -> await Dictionaryfilter_keys_async(src: Dictionary, pred: Callable) -> await Dictionarypartition_async(items: Array, pred: Callable) -> await Arrayunique_by_async(items: Array, key: Callable) -> await Arraysort_by_async(items: Array, pick: Callable) -> await Arraysum_of_async(items: Array, pick: Callable) -> await floatmax_by_async(items: Array, pick: Callable) -> await Variantmin_by_async(items: Array, pick: Callable) -> await Variantindex_by_async(items: Array, key: Callable) -> await Dictionarychunk_async(items: Array, size: int) -> await Arrayunique_async(items: Array) -> await Arraysort_key_async(items: Array, key: String) -> await Arrayzip_async(a: Array, b: Array) -> await Arraydeep_merge_async(base: Dictionary, over: Dictionary) -> await Dictionary
group_by
group_by(items: Array, key: Callable) -> DictionaryGroup values by selected keys.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
items | Array | Required | Input elements to transform or collect, in their supplied order. |
key | Callable | Required | Callable selecting the grouping, uniqueness or indexing key from an element. |
Return value
Dictionary
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
map_values
map_values(src: Dictionary, fn: Callable) -> DictionaryTransform each dictionary value.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
src | Dictionary | Required | Source input to read or transform; file operations interpret it as a source path. |
fn | Callable | Required | Callable to invoke; supplied arguments follow the API's callback contract. |
Return value
Dictionary
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
filter_keys
filter_keys(src: Dictionary, pred: Callable) -> DictionaryKeep dictionary keys matching a predicate.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
src | Dictionary | Required | Source input to read or transform; file operations interpret it as a source path. |
pred | Callable | Required | Callable whose boolean result determines how each item is selected. |
Return value
Dictionary
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
partition
partition(items: Array, pred: Callable) -> ArrayPartition an array by predicate result.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
items | Array | Required | Input elements to transform or collect, in their supplied order. |
pred | Callable | Required | Callable whose boolean result determines how each item is selected. |
Return value
Array
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
chunk
chunk(items: Array, size: int) -> ArraySplit an array into chunks of the specified size.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
items | Array | Required | Input elements to transform or collect, in their supplied order. |
size | int | Required | Maximum number of elements in each chunk. |
Return value
Array
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
unique_by
unique_by(items: Array, key: Callable) -> ArrayRemove values with duplicate selected keys.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
items | Array | Required | Input elements to transform or collect, in their supplied order. |
key | Callable | Required | Callable selecting the grouping, uniqueness or indexing key from an element. |
Return value
Array
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
unique
unique(items: Array) -> ArrayRemove duplicate values.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
items | Array | Required | Input elements to transform or collect, in their supplied order. |
Return value
Array
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
sort_by
sort_by(items: Array, pick: Callable) -> ArraySort by selected values while retaining source order for equal keys.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
items | Array | Required | Input elements to transform or collect, in their supplied order. |
pick | Callable | Required | Callable selecting a comparison or aggregation key from each value. |
Return value
Array
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
sort_key
sort_key(items: Array, key: String) -> ArraySort by specified dictionary keys while retaining source order for equal keys.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
items | Array | Required | Input elements to transform or collect, in their supplied order. |
key | String | Required | Name of the field whose values determine the ordering. |
Return value
Array
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
zip
zip(a: Array, b: Array) -> ArrayPair elements at corresponding positions in two arrays.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
a | Array | Required | First input or comparison operand. |
b | Array | Required | Second input or comparison operand. |
Return value
Array
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
sum_of
sum_of(items: Array, pick: Callable) -> floatSum selected numeric values.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
items | Array | Required | Input elements to transform or collect, in their supplied order. |
pick | Callable | Required | Callable selecting a comparison or aggregation key from each value. |
Return value
float
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
max_by
max_by(items: Array, pick: Callable) -> VariantReturn the element with the maximum selected value.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
items | Array | Required | Input elements to transform or collect, in their supplied order. |
pick | Callable | Required | Callable selecting a comparison or aggregation key from each value. |
Return value
Variant
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
min_by
min_by(items: Array, pick: Callable) -> VariantReturn the element with the minimum selected value.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
items | Array | Required | Input elements to transform or collect, in their supplied order. |
pick | Callable | Required | Callable selecting a comparison or aggregation key from each value. |
Return value
Variant
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
index_by
index_by(items: Array, key: Callable) -> DictionaryIndex elements in a dictionary by selected keys.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
items | Array | Required | Input elements to transform or collect, in their supplied order. |
key | Callable | Required | Callable selecting the grouping, uniqueness or indexing key from an element. |
Return value
Dictionary
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
deep_merge
deep_merge(base: Dictionary, over: Dictionary) -> DictionaryMerge nested dictionaries recursively.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
base | Dictionary | Required | Base value against which another value is merged or compared. |
over | Dictionary | Required | Values that override corresponding entries in the base dictionary. |
Return value
Dictionary
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
binary_heap
binary_heap(pick: Callable = null) -> GDBinaryHeapCreate a binary heap with selectable priorities.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
pick | Callable | null | Callable selecting a comparison or aggregation key from each value. |
Return value
GDBinaryHeap
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
priority_queue
priority_queue() -> GDPriorityQueueCreate a priority queue.
Parameters
No parameters.
Return value
GDPriorityQueue
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
lru_cache
lru_cache(limit: int = 128, ttl_ms: int = 0) -> GDLRUCacheCreate an LRU cache with entry-count and expiry settings.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
limit | int | 128 | Maximum number of entries retained in the cache. |
ttl_ms | int | 0 | Entry lifetime in milliseconds; zero disables expiration. |
Return value
GDLRUCache
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
memo
memo(fn: Callable, limit: int = 128) -> GDMemoizedCallableCreate an argument-keyed cache of callable results.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
fn | Callable | Required | Callable to invoke; supplied arguments follow the API's callback contract. |
limit | int | 128 | Maximum number of entries retained in the cache. |
Return value
GDMemoizedCallable
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
group_by_async
group_by_async(items: Array, key: Callable) -> await DictionaryDispatch large collection operations without callables to CPU workers.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
items | Array | Required | Input elements to transform or collect, in their supplied order. |
key | Callable | Required | Callable selecting the grouping, uniqueness or indexing key from an element. |
Return value
await Dictionary
Returns a Signal. Use await to receive the completion value shown in the signature.
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
map_values_async
map_values_async(src: Dictionary, fn: Callable) -> await DictionaryDistribute dictionary value mapping across scheduler turns.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
src | Dictionary | Required | Source input to read or transform; file operations interpret it as a source path. |
fn | Callable | Required | Callable to invoke; supplied arguments follow the API's callback contract. |
Return value
await Dictionary
Returns a Signal. Use await to receive the completion value shown in the signature.
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
filter_keys_async
filter_keys_async(src: Dictionary, pred: Callable) -> await DictionaryDistribute dictionary key filtering across scheduler turns.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
src | Dictionary | Required | Source input to read or transform; file operations interpret it as a source path. |
pred | Callable | Required | Callable whose boolean result determines how each item is selected. |
Return value
await Dictionary
Returns a Signal. Use await to receive the completion value shown in the signature.
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
partition_async
partition_async(items: Array, pred: Callable) -> await ArrayDistribute array partitioning across scheduler turns.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
items | Array | Required | Input elements to transform or collect, in their supplied order. |
pred | Callable | Required | Callable whose boolean result determines how each item is selected. |
Return value
await Array
Returns a Signal. Use await to receive the completion value shown in the signature.
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
unique_by_async
unique_by_async(items: Array, key: Callable) -> await ArrayDistribute key-based deduplication across scheduler turns.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
items | Array | Required | Input elements to transform or collect, in their supplied order. |
key | Callable | Required | Callable selecting the grouping, uniqueness or indexing key from an element. |
Return value
await Array
Returns a Signal. Use await to receive the completion value shown in the signature.
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
sort_by_async
sort_by_async(items: Array, pick: Callable) -> await ArrayDistribute key extraction across scheduler turns, then sort on a CPU worker.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
items | Array | Required | Input elements to transform or collect, in their supplied order. |
pick | Callable | Required | Callable selecting a comparison or aggregation key from each value. |
Return value
await Array
Returns a Signal. Use await to receive the completion value shown in the signature.
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
sum_of_async
sum_of_async(items: Array, pick: Callable) -> await floatDistribute numeric summation across scheduler turns.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
items | Array | Required | Input elements to transform or collect, in their supplied order. |
pick | Callable | Required | Callable selecting a comparison or aggregation key from each value. |
Return value
await float
Returns a Signal. Use await to receive the completion value shown in the signature.
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
max_by_async
max_by_async(items: Array, pick: Callable) -> await VariantDistribute maximum selection across scheduler turns.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
items | Array | Required | Input elements to transform or collect, in their supplied order. |
pick | Callable | Required | Callable selecting a comparison or aggregation key from each value. |
Return value
await Variant
Returns a Signal. Use await to receive the completion value shown in the signature.
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
min_by_async
min_by_async(items: Array, pick: Callable) -> await VariantDistribute minimum selection across scheduler turns.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
items | Array | Required | Input elements to transform or collect, in their supplied order. |
pick | Callable | Required | Callable selecting a comparison or aggregation key from each value. |
Return value
await Variant
Returns a Signal. Use await to receive the completion value shown in the signature.
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
index_by_async
index_by_async(items: Array, key: Callable) -> await DictionaryDistribute key-index construction across scheduler turns.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
items | Array | Required | Input elements to transform or collect, in their supplied order. |
key | Callable | Required | Callable selecting the grouping, uniqueness or indexing key from an element. |
Return value
await Dictionary
Returns a Signal. Use await to receive the completion value shown in the signature.
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
chunk_async
chunk_async(items: Array, size: int) -> await ArrayDispatch array chunking to a CPU worker.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
items | Array | Required | Input elements to transform or collect, in their supplied order. |
size | int | Required | Maximum number of elements in each chunk. |
Return value
await Array
Returns a Signal. Use await to receive the completion value shown in the signature.
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
unique_async
unique_async(items: Array) -> await ArrayDispatch deduplication to a CPU worker.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
items | Array | Required | Input elements to transform or collect, in their supplied order. |
Return value
await Array
Returns a Signal. Use await to receive the completion value shown in the signature.
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
sort_key_async
sort_key_async(items: Array, key: String) -> await ArrayDispatch dictionary-key sorting to a CPU worker.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
items | Array | Required | Input elements to transform or collect, in their supplied order. |
key | String | Required | Name of the field whose values determine the ordering. |
Return value
await Array
Returns a Signal. Use await to receive the completion value shown in the signature.
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
zip_async
zip_async(a: Array, b: Array) -> await ArrayDispatch array zipping to a CPU worker.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
a | Array | Required | First input or comparison operand. |
b | Array | Required | Second input or comparison operand. |
Return value
await Array
Returns a Signal. Use await to receive the completion value shown in the signature.
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.
deep_merge_async
deep_merge_async(base: Dictionary, over: Dictionary) -> await DictionaryDispatch nested dictionary merging to a CPU worker.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
base | Dictionary | Required | Base value against which another value is merged or compared. |
over | Dictionary | Required | Values that override corresponding entries in the base dictionary. |
Return value
await Dictionary
Returns a Signal. Use await to receive the completion value shown in the signature.
Errors
This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.