gdDocumentation0.8.0

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

group_by(items: Array, key: Callable) -> Dictionary

Group values by selected keys.

Parameters

NameTypeDefaultDescription
itemsArrayRequiredInput elements to transform or collect, in their supplied order.
keyCallableRequiredCallable 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) -> Dictionary

Transform each dictionary value.

Parameters

NameTypeDefaultDescription
srcDictionaryRequiredSource input to read or transform; file operations interpret it as a source path.
fnCallableRequiredCallable 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) -> Dictionary

Keep dictionary keys matching a predicate.

Parameters

NameTypeDefaultDescription
srcDictionaryRequiredSource input to read or transform; file operations interpret it as a source path.
predCallableRequiredCallable 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) -> Array

Partition an array by predicate result.

Parameters

NameTypeDefaultDescription
itemsArrayRequiredInput elements to transform or collect, in their supplied order.
predCallableRequiredCallable 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) -> Array

Split an array into chunks of the specified size.

Parameters

NameTypeDefaultDescription
itemsArrayRequiredInput elements to transform or collect, in their supplied order.
sizeintRequiredMaximum 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) -> Array

Remove values with duplicate selected keys.

Parameters

NameTypeDefaultDescription
itemsArrayRequiredInput elements to transform or collect, in their supplied order.
keyCallableRequiredCallable 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) -> Array

Remove duplicate values.

Parameters

NameTypeDefaultDescription
itemsArrayRequiredInput 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) -> Array

Sort by selected values while retaining source order for equal keys.

Parameters

NameTypeDefaultDescription
itemsArrayRequiredInput elements to transform or collect, in their supplied order.
pickCallableRequiredCallable 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) -> Array

Sort by specified dictionary keys while retaining source order for equal keys.

Parameters

NameTypeDefaultDescription
itemsArrayRequiredInput elements to transform or collect, in their supplied order.
keyStringRequiredName 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) -> Array

Pair elements at corresponding positions in two arrays.

Parameters

NameTypeDefaultDescription
aArrayRequiredFirst input or comparison operand.
bArrayRequiredSecond 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) -> float

Sum selected numeric values.

Parameters

NameTypeDefaultDescription
itemsArrayRequiredInput elements to transform or collect, in their supplied order.
pickCallableRequiredCallable 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) -> Variant

Return the element with the maximum selected value.

Parameters

NameTypeDefaultDescription
itemsArrayRequiredInput elements to transform or collect, in their supplied order.
pickCallableRequiredCallable 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) -> Variant

Return the element with the minimum selected value.

Parameters

NameTypeDefaultDescription
itemsArrayRequiredInput elements to transform or collect, in their supplied order.
pickCallableRequiredCallable 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) -> Dictionary

Index elements in a dictionary by selected keys.

Parameters

NameTypeDefaultDescription
itemsArrayRequiredInput elements to transform or collect, in their supplied order.
keyCallableRequiredCallable 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) -> Dictionary

Merge nested dictionaries recursively.

Parameters

NameTypeDefaultDescription
baseDictionaryRequiredBase value against which another value is merged or compared.
overDictionaryRequiredValues 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) -> GDBinaryHeap

Create a binary heap with selectable priorities.

Parameters

NameTypeDefaultDescription
pickCallablenullCallable 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() -> GDPriorityQueue

Create 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) -> GDLRUCache

Create an LRU cache with entry-count and expiry settings.

Parameters

NameTypeDefaultDescription
limitint128Maximum number of entries retained in the cache.
ttl_msint0Entry 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) -> GDMemoizedCallable

Create an argument-keyed cache of callable results.

Parameters

NameTypeDefaultDescription
fnCallableRequiredCallable to invoke; supplied arguments follow the API's callback contract.
limitint128Maximum 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 Dictionary

Dispatch large collection operations without callables to CPU workers.

Parameters

NameTypeDefaultDescription
itemsArrayRequiredInput elements to transform or collect, in their supplied order.
keyCallableRequiredCallable 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 Dictionary

Distribute dictionary value mapping across scheduler turns.

Parameters

NameTypeDefaultDescription
srcDictionaryRequiredSource input to read or transform; file operations interpret it as a source path.
fnCallableRequiredCallable 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 Dictionary

Distribute dictionary key filtering across scheduler turns.

Parameters

NameTypeDefaultDescription
srcDictionaryRequiredSource input to read or transform; file operations interpret it as a source path.
predCallableRequiredCallable 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 Array

Distribute array partitioning across scheduler turns.

Parameters

NameTypeDefaultDescription
itemsArrayRequiredInput elements to transform or collect, in their supplied order.
predCallableRequiredCallable 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 Array

Distribute key-based deduplication across scheduler turns.

Parameters

NameTypeDefaultDescription
itemsArrayRequiredInput elements to transform or collect, in their supplied order.
keyCallableRequiredCallable 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 Array

Distribute key extraction across scheduler turns, then sort on a CPU worker.

Parameters

NameTypeDefaultDescription
itemsArrayRequiredInput elements to transform or collect, in their supplied order.
pickCallableRequiredCallable 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 float

Distribute numeric summation across scheduler turns.

Parameters

NameTypeDefaultDescription
itemsArrayRequiredInput elements to transform or collect, in their supplied order.
pickCallableRequiredCallable 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 Variant

Distribute maximum selection across scheduler turns.

Parameters

NameTypeDefaultDescription
itemsArrayRequiredInput elements to transform or collect, in their supplied order.
pickCallableRequiredCallable 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 Variant

Distribute minimum selection across scheduler turns.

Parameters

NameTypeDefaultDescription
itemsArrayRequiredInput elements to transform or collect, in their supplied order.
pickCallableRequiredCallable 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 Dictionary

Distribute key-index construction across scheduler turns.

Parameters

NameTypeDefaultDescription
itemsArrayRequiredInput elements to transform or collect, in their supplied order.
keyCallableRequiredCallable 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 Array

Dispatch array chunking to a CPU worker.

Parameters

NameTypeDefaultDescription
itemsArrayRequiredInput elements to transform or collect, in their supplied order.
sizeintRequiredMaximum 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 Array

Dispatch deduplication to a CPU worker.

Parameters

NameTypeDefaultDescription
itemsArrayRequiredInput 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 Array

Dispatch dictionary-key sorting to a CPU worker.

Parameters

NameTypeDefaultDescription
itemsArrayRequiredInput elements to transform or collect, in their supplied order.
keyStringRequiredName 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 Array

Dispatch array zipping to a CPU worker.

Parameters

NameTypeDefaultDescription
aArrayRequiredFirst input or comparison operand.
bArrayRequiredSecond 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 Dictionary

Dispatch nested dictionary merging to a CPU worker.

Parameters

NameTypeDefaultDescription
baseDictionaryRequiredBase value against which another value is merged or compared.
overDictionaryRequiredValues 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.