sonolus.script.containers¶
ArrayMap
¶
Bases: Record
A map implemented as an array of key-value pairs with a fixed maximum capacity.
Usage
ArrayMap[K, V, Capacity].new() # Create a new empty map
Examples:
map = ArrayMap[int, int, 10].new()
map[1] = 2
map[3] = 4
assert 1 in map
assert 2 not in map
assert map[3] == 4
__contains__(key)
¶
Return whether the given key is present in the map.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
K
|
The key to check for |
required |
Returns:
| Type | Description |
|---|---|
bool
|
True if the key is present, False otherwise. |
__getitem__(key)
¶
Return the value associated with the given key.
Must be called with a key that is present in the map.
The returned value continues to be part of the map. Future modifications to the map will affect the returned value.
Notes
Future modifications to the map may cause unexpected changes to the returned value. If the map may be modified in the future, it's recommended to make a copy of the value.
For example:
map = ArrayMap[int, Pair[int, int], 10].new()
map[1] = Pair(2, 3)
map[3] = Pair(4, 5)
map[5] = Pair(6, 7)
p = map[3]
map.pop(1)
# The value of `p` may now be different
__iter__()
¶
Return an iterator over the keys in the map.
__len__()
¶
Return the number of key-value pairs in the map.
__setitem__(key, value)
¶
Associate the given key with the given value.
If the key is already present in the map, the value is updated. Must not be called if the map is full.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
K
|
The key to associate with the value. |
required |
value
|
V
|
The value to associate with the key |
required |
capacity()
classmethod
¶
Return the maximum number of key-value pairs the map can hold.
clear()
¶
Clear the map, removing all key-value pairs.
is_full()
¶
Return whether the map is full.
items()
¶
Return an iterator over the key-value pairs in the map.
keys()
¶
Return an iterator over the keys in the map.
new()
classmethod
¶
Create a new empty map.
pop(key)
¶
Remove and return a copy of the value associated with the given key.
Must be called with a key that is present in the map.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
K
|
The key to remove |
required |
Returns:
| Type | Description |
|---|---|
V
|
The value associated with the key |
values()
¶
Return an iterator over the values in the map.
ArrayPointer
¶
An array defined by a size and pointer to the first element.
This is intended to be created internally and improper use may result in hard to debug issues.
Usage
ArrayPointer[T](size: int, block: int, offset: int)
ArraySet
¶
Bases: Record
A set implemented as an array with a fixed maximum capacity.
Usage
ArraySet[T, Capacity].new() # Create a new empty set
Examples:
s = ArraySet[int, 10].new()
s.add(1)
s.add(2)
assert 1 in s
assert 3 not in s
s.remove(1)
assert 1 not in s
__contains__(value)
¶
Return whether the given value is present in the set.
__iter__()
¶
Return an iterator over the values in the set.
__len__()
¶
Return the number of elements in the set.
add(value)
¶
Add a copy of the given value to the set.
This has no effect and returns False if the value is already present or if the set is full.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
T
|
The value to add. |
required |
Returns:
| Type | Description |
|---|---|
bool
|
True if the value was added, False otherwise. |
clear()
¶
Clear the set, removing all elements.
new()
classmethod
¶
Create a new empty set.
remove(value)
¶
Remove the given value from the set.
This has no effect and returns False if the value is not present.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
T
|
The value to remove. |
required |
Returns:
| Type | Description |
|---|---|
bool
|
True if the value was removed, False otherwise. |
Box
¶
Bases: Record
A box that contains a value.
This can be helpful for generic code that can handle both Num and non-Num types.
Usage
Box[T](value: T)
Examples:
box = Box(1)
box = Box[int](2)
x: T = ...
y: T = ...
box = Box(x)
box.value = y # Works regardless of whether x is a Num or not
value
instance-attribute
¶
The value contained in the box.
Pair
¶
VarArray
¶
An array with a variable size and fixed maximum capacity.
Usage
VarArray[T, Capacity].new() # Create a new empty array
Examples:
array = VarArray[int, 10].new()
array.append(1)
__delitem__(key)
¶
Remove the element at the given index.
__getitem__(item)
¶
Return the element at the given index.
The returned value continues to be part of the array. Future modifications to the array will affect the returned value.
Note
Future modifications to the array may cause unexpected changes to the returned value. If the array may be modified in the future, it's recommended to make a copy of the value.
For example:
a = VarArray[Pair, 10].new()
a.append(Pair(1, 2))
a.append(Pair(3, 4))
a.append(Pair(5, 6))
p = a[1]
a.pop(0) # Elements are shifted back
assert p == Pair(5, 6) # The value of p has changed
__iadd__(other)
¶
Appends copies of the values in the given array to the end of the array.
__len__()
¶
Return the number of elements in the array.
__setitem__(key, value)
¶
Update the element at the given index.
append(value)
¶
Append a copy of the given value to the end of the array.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
T
|
The value to append. |
required |
append_unchecked(value)
¶
Append the given value to the end of the array without checking the capacity.
Use with caution as this may cause hard to debug issues if the array is full.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
T
|
The value to append. |
required |
capacity()
classmethod
¶
Return the maximum number of elements the array can hold.
clear()
¶
Clear the array, removing all elements.
References to elements are not immediately changed, but future insertions may overwrite them.
extend(values)
¶
Appends copies of the values in the given array to the end of the array.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
values
|
ArrayLike[T]
|
The values to append. |
required |
insert(index, value)
¶
Insert a copy of the given value at the given index.
Preserves the relative order of the elements.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
index
|
int
|
The index at which to insert the value. Must be in the range [0, size]. |
required |
value
|
T
|
The value to insert. |
required |
is_full()
¶
Return whether the array is full.
new()
classmethod
¶
Create a new empty array.
pop(index=None)
¶
Remove and return a copy of the value at the given index.
Preserves the relative order of the elements.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
index
|
int | None
|
The index of the value to remove. If None, the last element is removed. |
None
|
remove(value)
¶
Remove the first occurrence of the given value, returning whether the value was removed.
Preserves the relative order of the elements.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
T
|
The value to remove |
required |
Returns:
| Type | Description |
|---|---|
bool
|
True if the value was removed, False otherwise. |
set_add(value)
¶
Adds a copy of the given value if it is not already present, returning whether the value was added.
If the value is already present, the array is not modified. If the array is full, the value is not added.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
T
|
The value to add |
required |
Returns:
| Type | Description |
|---|---|
bool
|
True if the value was added, False otherwise. |
set_remove(value)
¶
Removes the first occurrence of the given value, returning whether the value was removed.
Does not preserve the relative order of the elements.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
T
|
The value to remove |
required |
Returns:
| Type | Description |
|---|---|
bool
|
True if the value was removed, False otherwise. |