sonolus.py 0.3.2__tar.gz → 0.3.3__tar.gz

{sonolus_py-0.3.2 → sonolus_py-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sonolus.py
-Version: 0.3.2
+Version: 0.3.3
 Summary: Sonolus engine development in Python
 License-File: LICENSE
 Requires-Python: >=3.12

{sonolus_py-0.3.2 → sonolus_py-0.3.3}/docs/concepts/builtins.md

@@ -2,7 +2,7 @@
 Sonolus.py comes with support for a number of built-in functions.
 
 - `abs(x)`
-- `bool(object)` (for a num argument)
+- `bool(object)`
 - `callable(object)`
 - `enumerate(iterable, start=0)`
 - `filter(function, iterable)`
@@ -38,6 +38,10 @@ Sonolus.py also comes with support for some standard library modules.
 - `ceil(x)`
 - `trunc(x)`
 - `log(x[, base])`
+- `pi`
+- `e`
+- `tau`
+- `inf`
 
 ### random
 - `randrange(stop)`, `random.randrange(start, stop[, step])`

{sonolus_py-0.3.2 → sonolus_py-0.3.3}/docs/concepts/types.md

@@ -14,7 +14,7 @@ Sonolus.py will treat any of these types as `Num`, but it's recommended to use w
 The Sonolus app uses 32-bit floating-point numbers for all numeric values, so precision may be lower compared to Python
 when running on Sonolus.
 
-Infinity, NaN, and values outside the range of 32-bit floating-point numbers are not supported.
+NaN and values outside the range of 32-bit floating-point numbers are not supported.
 
 You can import `Num` from `sonolus.script.num`:
 
@@ -42,8 +42,10 @@ Nums support most of the standard Python operations:
     Floating point precision may be lower when running on Sonolus compared to Python.
     Care should be taken when performing precision-sensitive operations.
 
-Nums are the only supported type for boolean operations and control flow conditions.
-As a condition, any nonzero value is considered true, and `0` is considered false.
+As in regular Python, `0` is considered `False`, while any non-zero value is considered `True`.
+
+Objects with an explicit `__bool__` method may also be used in `if`, `while`, `case ... if` expressions as well as with
+the `not` operator. However, the operands of the `and` and `or` operators must be of type `Num`.
 
 - Logical operators: `and`, `or`, `not`
 - Ternary expressions: `... if <condition> else ...`

{sonolus_py-0.3.2 → sonolus_py-0.3.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sonolus.py"
-version = "0.3.2"
+version = "0.3.3"
 description = "Sonolus engine development in Python"
 readme = "README.md"
 requires-python = ">=3.12"

{sonolus_py-0.3.2 → sonolus_py-0.3.3}/sonolus/backend/finalize.py

@@ -1,3 +1,5 @@
+from math import isfinite, isinf, isnan
+
 from sonolus.backend.ir import IRConst, IRGet, IRInstr, IRPureInstr, IRSet
 from sonolus.backend.node import ConstantNode, EngineNode, FunctionNode
 from sonolus.backend.ops import Op
@@ -54,10 +56,20 @@ def cfg_to_engine_node(entry: BasicBlock):
 
 def ir_to_engine_node(stmt) -> EngineNode:
     match stmt:
-        case int() | float():
-            return ConstantNode(value=float(stmt))
-        case IRConst(value=int(value) | float(value)):
-            return ConstantNode(value=value)
+        case int(value) | float(value) | IRConst(value=int(value) | float(value)):
+            value = float(value)
+            if value.is_integer():
+                return ConstantNode(value=int(value))
+            elif isfinite(value):
+                return ConstantNode(value=value)
+            elif isinf(value):
+                # Read values from ROM
+                return FunctionNode(Op.Get, args=[ConstantNode(value=3000), ConstantNode(value=1 if value > 0 else 2)])
+            elif isnan(value):
+                # Read value from ROM
+                return FunctionNode(Op.Get, args=[ConstantNode(value=3000), ConstantNode(value=0)])
+            else:
+                raise ValueError(f"Invalid constant value: {value}")
         case IRPureInstr(op=op, args=args) | IRInstr(op=op, args=args):
             return FunctionNode(func=op, args=[ir_to_engine_node(arg) for arg in args])
         case IRGet(place=place):

{sonolus_py-0.3.2 → sonolus_py-0.3.3}/sonolus/backend/visitor.py

@@ -359,7 +359,7 @@ class Visitor(ast.NodeVisitor):
         self.loop_head_ctxs.append(header_ctx)
         self.break_ctxs.append([])
         set_ctx(header_ctx)
-        has_next = self.ensure_boolean_num(self.handle_call(node, iterator.has_next))
+        has_next = self.convert_to_boolean_num(node, self.handle_call(node, iterator.has_next))
         if has_next._is_py_() and not has_next._as_py_():
             # The loop will never run, continue after evaluating the condition
             self.loop_head_ctxs.pop()
@@ -400,7 +400,7 @@ class Visitor(ast.NodeVisitor):
         self.loop_head_ctxs.append(header_ctx)
         self.break_ctxs.append([])
         set_ctx(header_ctx)
-        test = self.ensure_boolean_num(self.visit(node.test))
+        test = self.convert_to_boolean_num(node.test, self.visit(node.test))
         if test._is_py_():
             if test._as_py_():
                 # The loop will run until a break / return
@@ -454,7 +454,7 @@ class Visitor(ast.NodeVisitor):
         set_ctx(after_ctx)
 
     def visit_If(self, node):
-        test = self.ensure_boolean_num(self.visit(node.test))
+        test = self.convert_to_boolean_num(node.test, self.visit(node.test))
 
         if test._is_py_():
             if test._as_py_():
@@ -507,7 +507,9 @@ class Visitor(ast.NodeVisitor):
                 set_ctx(false_ctx)
                 continue
             set_ctx(true_ctx)
-            guard = self.ensure_boolean_num(self.visit(case.guard)) if case.guard else validate_value(True)
+            guard = (
+                self.convert_to_boolean_num(case.guard, self.visit(case.guard)) if case.guard else validate_value(True)
+            )
             if guard._is_py_():
                 if guard._as_py_():
                     for stmt in case.body:
@@ -544,7 +546,7 @@ class Visitor(ast.NodeVisitor):
         match pattern:
             case ast.MatchValue(value=value):
                 value = self.visit(value)
-                test = self.ensure_boolean_num(validate_value(subject == value))
+                test = self.convert_to_boolean_num(pattern, validate_value(subject == value))
                 if test._is_py_():
                     if test._as_py_():
                         return ctx(), ctx().into_dead()
@@ -574,7 +576,7 @@ class Visitor(ast.NodeVisitor):
                 target_len = len(patterns)
                 if not (isinstance(subject, Sequence | TupleImpl)):
                     return ctx().into_dead(), ctx()
-                length_test = self.ensure_boolean_num(validate_value(_len(subject) == target_len))
+                length_test = self.convert_to_boolean_num(pattern, validate_value(_len(subject) == target_len))
                 ctx_init = ctx()
                 if not length_test._is_py_():
                     ctx_init.test = length_test.ir()
@@ -739,7 +741,7 @@ class Visitor(ast.NodeVisitor):
     def visit_UnaryOp(self, node):
         operand = self.visit(node.operand)
         if isinstance(node.op, ast.Not):
-            return self.ensure_boolean_num(operand).not_()
+            return self.convert_to_boolean_num(node, operand).not_()
         op = unary_ops[type(node.op)]
         if operand._is_py_():
             operand_py = operand._as_py_()
@@ -768,7 +770,7 @@ class Visitor(ast.NodeVisitor):
         return validate_value(fn)
 
     def visit_IfExp(self, node):
-        test = self.ensure_boolean_num(self.visit(node.test))
+        test = self.convert_to_boolean_num(node.test, self.visit(node.test))
 
         if test._is_py_():
             if test._as_py_():
@@ -1076,7 +1078,7 @@ class Visitor(ast.NodeVisitor):
 
     def handle_call[**P, R](
         self, node: ast.stmt | ast.expr, fn: Callable[P, R], /, *args: P.args, **kwargs: P.kwargs
-    ) -> R:
+    ) -> R | Value:
         """Handles a call to the given callable."""
         self.active_ctx = ctx()
         if (
@@ -1127,6 +1129,20 @@ class Visitor(ast.NodeVisitor):
             raise TypeError(f"Invalid type where a bool (Num) was expected: {type(value).__name__}")
         return value
 
+    def convert_to_boolean_num(self, node, value: Value) -> Num:
+        if _is_num(value):
+            return value
+        if hasattr(type(value), "__bool__"):
+            return self.ensure_boolean_num(self.handle_call(node, type(value).__bool__, validate_value(value)))
+        if hasattr(type(value), "__len__"):
+            length = self.handle_call(node, type(value).__len__, validate_value(value))
+            if not _is_num(length):
+                raise TypeError(f"Invalid type for __len__: {type(length).__name__}")
+            if length._is_py_():
+                return Num._accept_(length._as_py_() > 0)
+            return length > Num._accept_(0)
+        raise TypeError(f"Converting {type(value).__name__} to bool is not supported")
+
     def arguments_to_signature(self, arguments: ast.arguments) -> inspect.Signature:
         parameters: list[inspect.Parameter] = []
         pos_only_count = len(arguments.posonlyargs)

{sonolus_py-0.3.2 → sonolus_py-0.3.3}/sonolus/script/archetype.py

@@ -549,11 +549,19 @@ class _BaseArchetype:
                     metadata = _annotation_defaults.get(metadata, metadata)
                 if isinstance(metadata, _ArchetypeFieldInfo):
                     if field_info is not None:
-                        raise TypeError(
-                            f"Unexpected multiple field annotations for '{name}', "
-                            f"expected exactly one of imported, exported, entity_memory, or shared_memory"
-                        )
-                    field_info = metadata
+                        if field_info.storage == metadata.storage and field_info.name is None:
+                            field_info = metadata
+                        elif field_info.storage == metadata.storage and (
+                            metadata.name is None or field_info.name == metadata.name
+                        ):
+                            pass
+                        else:
+                            raise TypeError(
+                                f"Unexpected multiple field annotations for '{name}', "
+                                f"expected exactly one of imported, exported, entity_memory, or shared_memory"
+                            )
+                    else:
+                        field_info = metadata
             if field_info is None:
                 raise TypeError(
                     f"Missing field annotation for '{name}', "
@@ -880,7 +888,7 @@ class WatchArchetype(_BaseArchetype):
             case _ArchetypeSelfData():
                 return _deref(ctx().blocks.EntityInfo, 0, WatchEntityInfo)
             case _ArchetypeReferenceData(index=index):
-                return _deref(ctx().blocks.EntityInfoArray, index * WatchEntityInfo._size_(), PlayEntityInfo)
+                return _deref(ctx().blocks.EntityInfoArray, index * WatchEntityInfo._size_(), WatchEntityInfo)
             case _:
                 raise RuntimeError("Info is only accessible from the entity itself")
 
@@ -1106,10 +1114,20 @@ class EntityRef[A: _BaseArchetype](Record):
         """Return a new reference with the given archetype type."""
         return EntityRef[archetype](index=self.index)
 
+    @meta_fn
     def get(self) -> A:
         """Get the entity."""
+        if ref := getattr(self, "_ref_", None):
+            return ref
         return self.archetype().at(self.index)
 
+    @meta_fn
+    def get_as(self, archetype: type[_BaseArchetype]) -> _BaseArchetype:
+        """Get the entity as the given archetype type."""
+        if getattr(archetype, "_ref_", None):
+            raise TypeError("Using get_as in level data is not supported.")
+        return self.with_archetype(archetype).get()
+
     def archetype_matches(self) -> bool:
         """Check if entity at the index is precisely of the archetype."""
         return self.index >= 0 and self.archetype().is_at(self.index)
@@ -1117,7 +1135,7 @@ class EntityRef[A: _BaseArchetype](Record):
     def _to_list_(self, level_refs: dict[Any, str] | None = None) -> list[DataValue | str]:
         ref = getattr(self, "_ref_", None)
         if ref is None:
-            return [self.index]
+            return Num._accept_(self.index)._to_list_()
         else:
             if ref not in level_refs:
                 raise KeyError("Reference to entity not in level data")

{sonolus_py-0.3.2 → sonolus_py-0.3.3}/sonolus/script/array.py

@@ -5,7 +5,7 @@ from typing import Any, Self, final
 
 from sonolus.backend.ir import IRConst, IRSet
 from sonolus.backend.place import BlockPlace
-from sonolus.script.array_like import ArrayLike
+from sonolus.script.array_like import ArrayLike, get_positive_index
 from sonolus.script.debug import assert_unreachable
 from sonolus.script.internal.context import ctx
 from sonolus.script.internal.error import InternalError
@@ -18,6 +18,7 @@ from sonolus.script.num import Num
 class ArrayMeta(type):
     @meta_fn
     def __pos__[T](cls: type[T]) -> T:
+        """Create a zero-initialized array instance."""
         return cls._zero_()
 
 
@@ -186,7 +187,7 @@ class Array[T, Size](GenericValue, ArrayLike[T], metaclass=ArrayMeta):
 
     @meta_fn
     def __getitem__(self, index: Num) -> T:
-        index: Num = Num._accept_(index)
+        index: Num = Num._accept_(get_positive_index(index, self.size()))
         if index._is_py_() and 0 <= index._as_py_() < self.size():
             const_index = index._as_py_()
             if isinstance(const_index, float) and not const_index.is_integer():
@@ -230,7 +231,7 @@ class Array[T, Size](GenericValue, ArrayLike[T], metaclass=ArrayMeta):
 
     @meta_fn
     def __setitem__(self, index: Num, value: T):
-        index: Num = Num._accept_(index)
+        index: Num = Num._accept_(get_positive_index(index, self.size()))
         value = self.element_type()._accept_(value)
         if ctx():
             if isinstance(self._value, list):
@@ -303,6 +304,7 @@ class Array[T, Size](GenericValue, ArrayLike[T], metaclass=ArrayMeta):
         else:
             return f"{type(self).__name__}({', '.join(repr(self[i]) for i in range(self.size()))})"
 
+    @meta_fn
     def __pos__(self) -> Self:
         """Return a copy of the array."""
         return self._copy_()

{sonolus_py-0.3.2 → sonolus_py-0.3.3}/sonolus/script/array_like.py

@@ -5,6 +5,8 @@ from abc import abstractmethod
 from collections.abc import Callable
 from typing import Any
 
+from sonolus.script.internal.context import ctx
+from sonolus.script.internal.impl import meta_fn
 from sonolus.script.iterator import SonolusIterator
 from sonolus.script.num import Num
 from sonolus.script.record import Record
@@ -302,3 +304,26 @@ class _ArrayEnumerator[V: ArrayLike](Record, SonolusIterator):
 
     def advance(self):
         self.i += 1
+
+
+@meta_fn
+def get_positive_index(index: Num, length: Num) -> Num:
+    """Get the positive index for the given index in the array of the given length.
+
+    This is used to convert negative indixes relative to the end of the array to positive indices.
+
+    Args:
+        index: The index to convert.
+        length: The length of the array.
+
+    Returns:
+        The positive index.
+    """
+    if not ctx():
+        return index if index >= 0 else index + length
+    index = Num._accept_(index)
+    length = Num._accept_(length)
+    if index._is_py_() and length._is_py_():
+        return Num._accept_(index._as_py_() + length._as_py_() if index._as_py_() < 0 else index._as_py_())
+    else:
+        return index + (index < 0) * length

{sonolus_py-0.3.2 → sonolus_py-0.3.3}/sonolus/script/containers.py

@@ -2,10 +2,11 @@ from __future__ import annotations
 
 from sonolus.backend.visitor import compile_and_call
 from sonolus.script.array import Array
-from sonolus.script.array_like import ArrayLike
+from sonolus.script.array_like import ArrayLike, get_positive_index
 from sonolus.script.debug import error
 from sonolus.script.internal.context import ctx
 from sonolus.script.internal.impl import meta_fn
+from sonolus.script.interval import clamp
 from sonolus.script.iterator import SonolusIterator
 from sonolus.script.num import Num
 from sonolus.script.pointer import _deref
@@ -140,11 +141,11 @@ class VarArray[T, Capacity](Record, ArrayLike[T]):
             assert p == Pair(5, 6)  # The value of p has changed
             ```
         """
-        return self._array[item]
+        return self._array[get_positive_index(item, len(self))]
 
     def __setitem__(self, key: int, value: T):
         """Update the element at the given index."""
-        self._array[key] = value
+        self._array[get_positive_index(key, len(self))] = value
 
     def __delitem__(self, key: int):
         """Remove the element at the given index."""
@@ -190,6 +191,7 @@ class VarArray[T, Capacity](Record, ArrayLike[T]):
         """
         if index is None:
             index = self._size - 1
+        index = get_positive_index(index, len(self))
         assert 0 <= index < self._size
         value = copy(self._array[index])
         self._size -= 1
@@ -207,7 +209,7 @@ class VarArray[T, Capacity](Record, ArrayLike[T]):
             index: The index at which to insert the value. Must be in the range [0, size].
             value: The value to insert.
         """
-        assert 0 <= index <= self._size
+        index = clamp(get_positive_index(index, len(self)), 0, self._size)
         assert self._size < len(self._array)
         self._size += 1
         for i in range(self._size - 1, index, -1):
@@ -329,6 +331,7 @@ class ArrayPointer[T](Record, ArrayLike[T]):
 
     @meta_fn
     def _get_item(self, item: int) -> T:
+        item = get_positive_index(item, self.size)
         if not ctx():
             raise TypeError("ArrayPointer values cannot be accessed outside of a context")
         return _deref(
@@ -536,6 +539,23 @@ class ArrayMap[K, V, Capacity](Record):
         self._array[self._size] = _ArrayMapEntry(key, value)
         self._size += 1
 
+    def __delitem__(self, key: K):
+        """Remove the key-value pair associated with the given key.
+
+        Must be called with a key that is present in the map.
+
+        Args:
+            key: The key to remove
+        """
+        for i in range(self._size):
+            entry = self._array[i]
+            if entry.key == key:
+                self._size -= 1
+                if i < self._size:
+                    self._array[i] = self._array[self._size]
+                return
+        error()
+
     def __contains__(self, key: K) -> bool:
         """Return whether the given key is present in the map.
 

{sonolus_py-0.3.2 → sonolus_py-0.3.3}/sonolus/script/internal/builtin_impls.py

@@ -1,6 +1,7 @@
 from collections.abc import Iterable
 from typing import overload
 
+from sonolus.script.array import Array
 from sonolus.script.array_like import ArrayLike
 from sonolus.script.internal.context import ctx
 from sonolus.script.internal.dict_impl import DictImpl
@@ -129,6 +130,8 @@ def _max(*args, key: callable = _identity):
         (iterable,) = args
         if isinstance(iterable, ArrayLike):
             return compile_and_call(iterable._max_, key=key)
+        elif isinstance(iterable, TupleImpl) and all(_is_num(v) for v in iterable.value):
+            return compile_and_call(Array(*iterable.value)._max_, key=key)
         else:
             raise TypeError(f"Unsupported type: {type(iterable)} for max")
     else:
@@ -169,6 +172,8 @@ def _min(*args, key: callable = _identity):
         (iterable,) = args
         if isinstance(iterable, ArrayLike):
             return compile_and_call(iterable._min_, key=key)
+        elif isinstance(iterable, TupleImpl) and all(_is_num(v) for v in iterable.value):
+            return compile_and_call(Array(*iterable.value)._min_, key=key)
         else:
             raise TypeError(f"Unsupported type: {type(iterable)} for min")
     else:
@@ -221,12 +226,12 @@ def _float(value=0.0):
     return value
 
 
-@meta_fn
 def _bool(value=False):
-    value = validate_value(value)
-    if not _is_num(value):
-        raise TypeError("Only numeric arguments to bool() are supported")
-    return value != 0
+    # Relies on the compiler to perform the conversion in a boolean context
+    if value:  # noqa: SIM103
+        return True
+    else:
+        return False
 
 
 _int._type_mapping_ = Num

{sonolus_py-0.3.2 → sonolus_py-0.3.3}/sonolus/script/internal/context.py

@@ -291,7 +291,11 @@ class ReadOnlyMemory:
     _lock: Lock
 
     def __init__(self):
-        self.values = []
+        self.values = [
+            float("nan"),
+            float("inf"),
+            float("-inf"),
+        ]
         self.indexes = {}
         self._lock = Lock()
 

{sonolus_py-0.3.2 → sonolus_py-0.3.3}/sonolus/script/internal/range.py

@@ -1,4 +1,6 @@
-from sonolus.script.array_like import ArrayLike
+from sonolus.script.array_like import ArrayLike, get_positive_index
+from sonolus.script.internal.context import ctx
+from sonolus.script.internal.impl import meta_fn, validate_value
 from sonolus.script.iterator import SonolusIterator
 from sonolus.script.num import Num
 from sonolus.script.record import Record
@@ -36,7 +38,7 @@ class Range(Record, ArrayLike[Num]):
             return (diff - self.step - 1) // -self.step
 
     def __getitem__(self, index: Num) -> Num:
-        return self.start + index * self.step
+        return self.start + get_positive_index(index, len(self)) * self.step
 
     def __setitem__(self, index: Num, value: Num):
         raise TypeError("Range does not support item assignment")
@@ -79,3 +81,24 @@ class RangeIterator(Record, SonolusIterator):
 
     def advance(self):
         self.value += self.step
+
+
+@meta_fn
+def range_or_tuple(start: Num, stop: Num | None = None, step: Num = 1) -> Range | tuple[Num, ...]:
+    if stop is None:
+        start, stop = 0, start
+    if not ctx():
+        return range(start, stop, step)  # type: ignore
+    start = Num._accept_(start)
+    stop = Num._accept_(stop) if stop is not None else None
+    step = Num._accept_(step)
+    if start._is_py_() and stop._is_py_() and step._is_py_():
+        start_int = start._as_py_()
+        stop_int = stop._as_py_() if stop is not None else None
+        if stop_int is None:
+            start_int, stop_int = 0, start_int
+        step_int = step._as_py_()
+        if start_int % 1 != 0 or stop_int % 1 != 0 or step_int % 1 != 0:
+            raise TypeError("Range arguments must be integers")
+        return validate_value(tuple(range(int(start_int), int(stop_int), int(step_int))))  # type: ignore
+    return Range(start, stop, step)

{sonolus_py-0.3.2 → sonolus_py-0.3.3}/sonolus/script/internal/tuple_impl.py

@@ -21,8 +21,10 @@ class TupleImpl(TransientValue):
             raise TypeError(f"Cannot index tuple with {item}")
         if int(item) != item:
             raise TypeError(f"Cannot index tuple with non-integer {item}")
-        if not (0 <= item < len(self.value)):
+        if not (-len(self.value) <= item < len(self.value)):
             raise IndexError(f"Tuple index out of range: {item}")
+        if item < 0:
+            item += len(self.value)
         return self.value[int(item)]
 
     @meta_fn

{sonolus_py-0.3.2 → sonolus_py-0.3.3}/sonolus/script/interval.py

@@ -1,8 +1,10 @@
 from typing import Self
 
 from sonolus.backend.ops import Op
+from sonolus.script.array_like import ArrayLike
 from sonolus.script.debug import static_error
 from sonolus.script.internal.native import native_function
+from sonolus.script.internal.range import range_or_tuple
 from sonolus.script.num import Num
 from sonolus.script.record import Record
 
@@ -296,7 +298,7 @@ def unlerp_clamped(a: float, b: float, x: float, /) -> float:
 
 @native_function(Op.Remap)
 def remap(a: float, b: float, c: float, d: float, x: float, /) -> float:
-    """Remap a value from one interval to another.
+    """Linearly remap a value from one interval to another.
 
     Args:
         a: The start of the input interval.
@@ -313,7 +315,7 @@ def remap(a: float, b: float, c: float, d: float, x: float, /) -> float:
 
 @native_function(Op.RemapClamped)
 def remap_clamped(a: float, b: float, c: float, d: float, x: float, /) -> float:
-    """Remap a value from one interval to another, clamped to the output interval.
+    """Linearly remap a value from one interval to another, clamped to the output interval.
 
     Args:
         a: The start of the input interval.
@@ -341,3 +343,59 @@ def clamp(x: float, a: float, b: float, /) -> float:
         The clamped value.
     """
     return max(a, min(b, x))
+
+
+def interp(
+    xp: ArrayLike[float] | tuple[float, ...],
+    fp: ArrayLike[float] | tuple[float, ...],
+    x: float,
+) -> float:
+    """Linearly interpolate a value within a sequence of points.
+
+    The sequence must have at least 2 elements and be sorted in increasing order of x-coordinates.
+    For values of x outside the range of xp, the slope of the first or last segment is used to extrapolate.
+
+    Args:
+        xp: The x-coordinates of the points in increasing order.
+        fp: The y-coordinates of the points.
+        x: The x-coordinate to interpolate.
+
+    Returns:
+        The interpolated value.
+    """
+    assert len(xp) == len(fp)
+    assert len(xp) >= 2
+    for i in range_or_tuple(1, len(xp) - 1):
+        # At i == 1, x may be less than x[0], but since we're extrapolating, we use the first segment regardless.
+        if x <= xp[i]:
+            return remap(xp[i - 1], xp[i], fp[i - 1], fp[i], x)
+    # x > xp[-2] so we can just use the last segment regardless of whether x is in it or to the right of it.
+    return remap(xp[-2], xp[-1], fp[-2], fp[-1], x)
+
+
+def interp_clamped(
+    xp: ArrayLike[float] | tuple[float, ...],
+    fp: ArrayLike[float] | tuple[float, ...],
+    x: float,
+):
+    """Linearly interpolate a value within a sequence of points.
+
+    The sequence must have at least 2 elements and be sorted in increasing order of x-coordinates.
+    For x-coordinates outside the range of the sequence, the respective endpoint of fp is returned.
+
+    Args:
+        xp: The x-coordinates of the points in increasing order.
+        fp: The y-coordinates of the points.
+        x: The x-coordinate to interpolate.
+
+    Returns:
+        The interpolated value.
+    """
+    assert len(xp) == len(fp)
+    assert len(xp) >= 2
+    if x <= xp[0]:
+        return fp[0]
+    for i in range_or_tuple(1, len(xp)):
+        if x <= xp[i]:
+            return remap(xp[i - 1], xp[i], fp[i - 1], fp[i], x)
+    return fp[-1]