Mojo struct

IntTuple

struct IntTuple[origin: ImmutableOrigin = {}]

A hierarchical, nested tuple of integers with efficient memory management.

IntTuple provides a flexible data structure for representing multi-dimensional shapes, indices, and other nested integer collections. It supports both flat and hierarchical representations with efficient memory sharing.

This structure is fundamental for tensor operations, layout specifications, and dimension handling in high-performance computing contexts.

Parameters

origin (ImmutableOrigin): Origin tracking for memory safety. Defaults to the current origin.

Aliases

MinimumValue = -65534: Minimum allowed value for integers in an IntTuple. This constant defines the lower bound for integer values that can be stored directly in an IntTuple. Values below this threshold are reserved for internal use to represent structural information like sub-tuple offsets.

Implemented traits

AnyType, CollectionElement, Copyable, EqualityComparable, Intable, Movable, Sized, Stringable, UnknownDestructibility, Writable

Methods

`init`

__init__(out self)

Initialize an empty IntTuple.

Creates an IntTuple with zero elements, which can be used as a starting point for building tuples incrementally with append or extend.

Performance: - Minimal allocation (just a single element for length). - Structure validation only performed when INT_TUPLE_VALIDATION is enabled.

__init__(out self, *, num_elems: Int)

Initialize an IntTuple with a specified number of uninitialized elements.

Creates an IntTuple with space for the specified number of elements, but does not initialize the elements themselves.

Note: Structure validation only performed when INT_TUPLE_VALIDATION is enabled.

Args:

num_elems (Int): The number of elements to allocate space for.

@implicit __init__(out self, *elements: Int)

Initialize an IntTuple with a variadic list of integers.

Creates an IntTuple containing the provided integer values. This constructor is implicit, allowing direct conversion from integer lists.

Args:

*elements (Int): Variable number of integer values to store in the tuple.

__init__(out self, elements: VariadicList[Int])

Initialize an IntTuple with a list of integers.

Creates an IntTuple containing the provided integer values. This constructor is implicit, allowing direct conversion from integer lists.

Notes:

- Pre-allocates exact memory needed for efficiency.
- Validates that all values are above `MinimumValue`. If any value is
  less than `MinimumValue`, aborts with an error message.
- Structure validation only performed when `INT_TUPLE_VALIDATION` is
  enabled.
- Pre-allocates exact memory needed for efficiency.
- Validates that all values are above `MinimumValue`. If any value is
  less than `MinimumValue`, aborts with an error message.
- Structure validation only performed when `INT_TUPLE_VALIDATION` is
  enabled.

Args:

elements (VariadicList[Int]): List of integer values to store in the tuple.

@implicit __init__(out self, value: Int)

Initialize an IntTuple with a single integer value.

Creates an IntTuple containing a single integer element.

Args:

value (Int): The integer value to store in the tuple.

__init__(out self, *elements: IntTuple[origin])

Initialize an IntTuple with nested IntTuples.

Creates a hierarchical IntTuple containing the provided IntTuple elements, preserving their nested structure.

Args:

*elements (IntTuple[origin]): Variable number of IntTuple values to store in the tuple.

__init__(out self, *, non_owned: IntArray)

Initialize an IntTuple with a non-owned IntArray.

Creates an IntTuple that uses the provided IntArray as its storage without taking ownership. This allows creating views into existing IntTuple data without copying.

Args:

non_owned (IntArray): The IntArray to use as storage without taking ownership.

__init__(out self, existing: Self, rng: _StridedRange)

Initialize an IntTuple as a slice of an existing IntTuple.

Creates a new IntTuple containing only the elements from the existing IntTuple that are specified by the range.

Notes:

- Preserves nested structure of elements in the slice.
- Structure validation only performed when `INT_TUPLE_VALIDATION` is enabled.
- Preserves nested structure of elements in the slice.
- Structure validation only performed when `INT_TUPLE_VALIDATION` is enabled.

Args:

existing (Self): The source IntTuple to slice from.
rng (_StridedRange): The range of indices to include in the new IntTuple.

__init__(out self, dimlist: DimList)

Initialize an IntTuple from a DimList.

Creates an IntTuple containing the dimensions from a DimList, handling both defined and undefined dimensions appropriately.

Notes:

- Converts undefined dimensions to `UNKNOWN_VALUE`.
- Validates that all values are above `MinimumValue`. If any value is
  less than `MinimumValue`, aborts with an error message.
- Converts undefined dimensions to `UNKNOWN_VALUE`.
- Validates that all values are above `MinimumValue`. If any value is
  less than `MinimumValue`, aborts with an error message.

Args:

dimlist (DimList): The DimList containing dimension information.

@implicit __init__(out self, zipper: _zip[origin, 2])

Initialize an IntTuple from a zip iterator.

Creates an IntTuple by appending each element from the zip iterator. This constructor is implicit, allowing direct conversion from zip iterators.

Note: This implementation is not optimized and may be improved in future versions.

Args:

zipper (_zip[origin, 2]): A zip iterator containing pairs of elements to append.

`copyinit`

__copyinit__(out self, existing: Self)

Initialize by copying an existing IntTuple.

Creates a deep copy of the provided IntTuple, copying all its data into newly allocated memory.

Note: There is a Mojo bug where this method unnecessarily propagates the origin of self to the new copy.

Args:

existing (Self): The IntTuple to copy from.

`moveinit`

__moveinit__(out self, owned existing: Self)

Initialize by moving an existing IntTuple.

Takes ownership of the provided IntTuple's storage without copying. This is more efficient than copying when the source IntTuple is no longer needed.

Args:

existing (Self): The IntTuple to move from (will be consumed).

`getitem`

__getitem__(self, _idx: Int) -> IntTuple[self]

Retrieves an element at the specified index from the IntTuple.

Supports negative indexing (e.g., -1 for the last element).

Notes: If index validation is enabled and the index is out of bounds, aborts with an error message.

Args:

_idx (Int): The index of the element to retrieve.

Returns:

An IntTuple containing either a single value or a sub-tuple.

__getitem__(self, span: Slice) -> Self

Retrieves a slice of elements from the IntTuple.

Creates a new IntTuple containing the elements specified by the slice.

Args:

span (Slice): A slice object specifying the range of elements to retrieve.

Returns:

A new IntTuple containing the specified elements.

`lt`

__lt__(self, rhs: IntTuple[origin]) -> Bool

Compare two IntTuples lexicographically.

This function performs element-wise comparison of two IntTuples and determines if the first is lexicographically less than the second. It compares corresponding elements until it finds a pair where the elements differ.

Example:

```mojo
from layout.int_tuple import IntTuple

var tuple1 = IntTuple(1, 2, 3)
var tuple2 = IntTuple(1, 2, 4)

var result = tuple1 < tuple2  # Returns True because 3 < 4
```
```mojo
from layout.int_tuple import IntTuple

var tuple1 = IntTuple(1, 2, 3)
var tuple2 = IntTuple(1, 2, 4)

var result = tuple1 < tuple2  # Returns True because 3 < 4
```

Args:

rhs (IntTuple[origin]): The other IntTuple to compare.

Returns:

True if self is lexicographically less than rhs, False otherwise.

`eq`

__eq__(self, other: Self) -> Bool

Equality operator for IntTuple.

Args:

other (Self): The IntTuple to compare with.

Returns:

True if the IntTuples are equal, False otherwise.

`ne`

__ne__(self, other: Self) -> Bool

Inequality operator for IntTuple.

Args:

other (Self): The IntTuple to compare with.

Returns:

True if the IntTuples are not equal, False otherwise.

`elements_size`

static elements_size[origin: ImmutableOrigin](elements: VariadicListMem[IntTuple[origin], origin]) -> Int

Calculate the total storage size needed for a list of IntTuples.

Computes the sum of sizes for all elements, accounting for both direct integer values and nested sub-tuples.

Parameters:

origin (ImmutableOrigin): Origin of the elements in the IntTuple.

Args:

elements (VariadicListMem[IntTuple[origin], origin]): List of IntTuple elements to measure.

Returns:

The total storage size required for all elements.

static elements_size[origin: ImmutableOrigin, n: Int](elements: InlineArray[Pointer[IntTuple, origin], n], idx: Int) -> Int

Calculate the total storage size needed for IntTuples at a specific index.

Computes the sum of sizes for all elements at the given index in an array of IntTuple pointers.

Parameters:

origin (ImmutableOrigin): Origin tracking for memory safety.
n (Int): Size of the inline array.

Args:

elements (InlineArray[Pointer[IntTuple, origin], n]): Array of pointers to IntTuples.
idx (Int): Index to access in each IntTuple.

Returns:

The total storage size required for all elements at the specified index.

`owned_copy`

owned_copy(self) -> IntTuple

Create a deep copy of this IntTuple with its own memory ownership.

This method creates a completely independent copy of the IntTuple with newly allocated memory. Unlike __copyinit__, this method can be called on an existing instance to create a separate copy.

Example:

```mojo
from layout import IntTuple

var original = IntTuple(1, 2, 3)
var copy = original.owned_copy()
# Modifying copy will not affect original
```
.
```mojo
from layout import IntTuple

var original = IntTuple(1, 2, 3)
var copy = original.owned_copy()
# Modifying copy will not affect original
```
.

Returns:

A new IntTuple containing the same data as this one but with independent memory ownership.

`replace_entry`

replace_entry(self, idx: Int, value: IntTuple[origin]) -> IntTuple

Replace an entry in the tuple with another IntTuple.

Creates a new IntTuple with the element at the specified index replaced by the provided IntTuple.

Note: If the index is out of bounds and INT_TUPLE_VALIDATION is enabled, aborts with an error message.

Args:

idx (Int): The index of the element to replace.
value (IntTuple[origin]): The IntTuple to insert at the specified index.

Returns:

A new IntTuple with the replacement applied.

replace_entry(mut self, idx: Int, *, int_value: Int)

Replace an integer value at the specified index in-place.

Directly modifies the tuple by replacing the integer value at the given index. This is more efficient than creating a new tuple when only a single value needs to be changed.

Note: If the index is out of bounds and INT_TUPLE_VALIDATION is enabled, aborts with an error message.

Args:

idx (Int): The index of the element to replace.
int_value (Int): The integer value to insert at the specified index.

`count_values`

count_values(self) -> Int

Count the total number of integer values in this tuple hierarchy.

Recursively traverses the nested tuple structure and counts all integer values. This is useful for determining the size needed for flattened representations.

Note: For a flat tuple, this will return the same value as len(self). For nested tuples, it counts all leaf integer values.

Returns:

The total count of integer values in this tuple and all nested tuples.

`flatten`

flatten(self) -> IntTuple

Flatten a nested IntTuple into a single-level IntTuple.

This function converts a hierarchical IntTuple structure into a flat sequence of integer values, preserving the order of elements.

Returns:

A new IntTuple containing all integer values in a flat structure.

`all_known`

all_known(self) -> Bool

Check if all values in this tuple hierarchy are known (not UNKNOWN_VALUE).

Recursively traverses the nested tuple structure and checks if any value is equal to UNKNOWN_VALUE.

Returns:

True if all values in this tuple and nested tuples are known, False if any value is UNKNOWN_VALUE.

`append`

append(mut self, *elements: IntTuple[origin])

Append one or more IntTuple elements to this tuple.

This method modifies the tuple in-place by adding the provided elements to the end of the tuple. It handles both value tuples and nested tuples.

Notes:

- This operation requires reallocating the underlying `IntArray` storage to accommodate
the new elements, which may impact performance for large tuples.
- Aborts if called on a non-owning (sub-tuple) instance.
- This operation requires reallocating the underlying `IntArray` storage to accommodate
the new elements, which may impact performance for large tuples.
- Aborts if called on a non-owning (sub-tuple) instance.

Args:

*elements (IntTuple[origin]): Variable number of IntTuple objects to append to this tuple.

`extend`

extend(mut self, tuple: IntTuple[origin])

Extends this tuple by appending all elements from another tuple.

This method modifies the tuple in-place by adding all elements from the provided tuple to the end of this tuple. It efficiently handles both value elements and nested tuples.

Notes:

- This operation requires reallocating the underlying `IntArray` storage
  to accommodate the new elements, which may impact performance for large tuples.
- Aborts if called on a non-owning (sub-tuple) instance.
- If the input tuple is empty, this method returns without making any changes.
- This operation requires reallocating the underlying `IntArray` storage
  to accommodate the new elements, which may impact performance for large tuples.
- Aborts if called on a non-owning (sub-tuple) instance.
- If the input tuple is empty, this method returns without making any changes.

Args:

tuple (IntTuple[origin]): The IntTuple whose elements will be appended to this tuple.

`size`

size(self) -> Int

Returns the total size of the IntTuple in memory.

For owning tuples, returns the size of the underlying IntArray. For non-owning tuples, calculates the size recursively.

Returns:

The total size in memory units.

`tuple_size`

static tuple_size(data: IntArray) -> Int

Recursively calculates the size of a tuple represented by an IntArray.

This method traverses the tuple structure, accounting for both direct values and nested sub-tuples to compute the total memory footprint.

Args:

data (IntArray): IntArray containing the tuple data.

Returns:

The total size of the tuple in memory units.

`validate_structure`

validate_structure(self)

Validates the internal structure of the IntTuple.

Ensures that the actual size of the underlying data matches the computed size based on the tuple's structure. This helps detect memory corruption or implementation errors.

Aborts execution with an error message if validation fails.

`len`

__len__(self) -> Int

Returns the number of elements in the IntTuple.

This is the logical length of the tuple, not its memory size.

Returns:

The number of elements in the tuple.

`iter`

__iter__(self) -> _IntTupleIter[self, origin]

Returns an iterator over the elements of the IntTuple.

This enables iteration through the tuple using for-loops.

Returns:

An iterator object for this IntTuple.

`is_value`

is_value(self) -> Bool

Determines if this IntTuple represents a single value rather than a tuple.

Returns:

True if this IntTuple contains exactly one element that is a value, False otherwise.

is_value(self, i: Int) -> Bool

Determines if the element at the specified index is a value rather than a tuple.

Notes: If index validation is enabled and the index is out of bounds, aborts with an error message.

Args:

i (Int): The index of the element to check.

Returns:

True if the element at index i is a value, False if it's a tuple.

`is_tuple`

is_tuple(self) -> Bool

Determines if this IntTuple represents a tuple rather than a single value.

Returns:

True if this IntTuple is a tuple (not a single value), False otherwise.

is_tuple(self, i: Int) -> Bool

Determines if the element at the specified index is a tuple rather than a value.

Notes: This is the complement of is_value(i).

Args:

i (Int): The index of the element to check.

Returns:

True if the element at index i is a tuple, False if it's a value.

`value`

value(self) -> Int

Retrieves the value of this IntTuple if it represents a single value.

This method should only be called if is_value() returns True.

Returns:

The integer value stored in this IntTuple.

value(self, i: Int) -> Int

Retrieves the value of the element at the specified index.

This method should only be called if is_value(i) returns True.

Notes: If the element is not a value, the behavior is undefined.

Args:

i (Int): The index of the element to retrieve.

Returns:

The integer value stored at the specified index.

`tuple`

tuple(ref self) -> ref [self] Self

Returns a reference to this IntTuple as a tuple.

Notes: This method is used to access the current IntTuple as a tuple without creating a copy of the data.

Returns:

A reference to this IntTuple to avoid unnecessary copying.

`write_to`

write_to[W: Writer](self, mut writer: W)

Writes a string representation of this IntTuple to the provided writer.

Notes: For single values, writes just the value. For tuples, writes a comma-separated list of elements enclosed in parentheses.

Parameters:

W (Writer): A type that conforms to the Writer trait.

Args:

writer (W): The writer to output the string representation to.

`str`

__str__(self) -> String

Returns a string representation of this IntTuple.

Returns:

A string representation of the IntTuple, using the write_to method.

`is_equal`

static is_equal(a: IntTuple[origin], b: IntTuple[origin]) -> Bool

Compares two IntTuples for equality.

Notes: Handles nested tuples and special cases where a single-element tuple is equivalent to its contained value.

Args:

a (IntTuple[origin]): The first IntTuple to compare.
b (IntTuple[origin]): The second IntTuple to compare.

Returns:

True if the IntTuples are equal in structure and values, False otherwise.

`repr`

__repr__(self) -> String

Returns a string representation of this IntTuple for debugging.

Returns:

A string representation of the IntTuple, same as __str__.

`int`

__int__(self) -> Int

Converts this IntTuple to an integer.

This method should only be called if is_value() returns True.

Notes: If the IntTuple is not a single value, the behavior is undefined.

Returns:

The integer value stored in this IntTuple.

Parameters​

Aliases​

Implemented traits​

Methods​

__init__​

__copyinit__​

__moveinit__​

__getitem__​

__lt__​

__eq__​

__ne__​

elements_size​

owned_copy​

replace_entry​

count_values​

flatten​

all_known​

append​

extend​

size​

tuple_size​

validate_structure​

__len__​

__iter__​

is_value​

is_tuple​

value​

tuple​

write_to​

__str__​

is_equal​

__repr__​

__int__​

Parameters

Aliases

Implemented traits

Methods

`init`

`copyinit`

`moveinit`

`getitem`

`lt`

`eq`

`ne`

`elements_size`

`owned_copy`

`replace_entry`

`count_values`

`flatten`

`all_known`

`append`

`extend`

`size`

`tuple_size`

`validate_structure`

`len`

`iter`

`is_value`

`is_tuple`

`value`

`tuple`

`write_to`

`str`

`is_equal`

`repr`

`int`