struct
List
The List
type is a dynamically-allocated list.
It supports pushing and popping from the back resizing the underlying storage as needed. When it is deallocated, it frees its memory.
Parameters
- T (
CollectionElement
): The type of the elements.
Fields
- data (
UnsafePointer[T, 0]
): The underlying storage for the list. - size (
Int
): The number of elements in the list. - capacity (
Int
): The amount of elements that can fit in the list without resizing it.
Implemented traits
AnyType
,
Boolable
,
CollectionElement
,
Copyable
,
Movable
,
Sized
Methods
__init__
__init__(inout self: Self)
Constructs an empty list.
__init__(inout self: Self, existing: Self)
Creates a deep copy of the given list.
Args:
- existing (
Self
): The list to copy.
__init__(inout self: Self, *, capacity: Int)
Constructs a list with the given capacity.
Args:
- capacity (
Int
): The requested capacity of the list.
__init__(inout self: Self, *values: T)
Constructs a list from the given values.
Args:
- *values (
T
): The values to populate the list with.
__init__(inout self: Self, span: Span[T, is_mutable, lifetime])
Constructs a list from the a Span of values.
Args:
- span (
Span[T, is_mutable, lifetime]
): The span of values to populate the list with.
__init__(inout self: Self, *, unsafe_pointer: UnsafePointer[T, 0], size: Int, capacity: Int)
Constructs a list from a pointer, its size, and its capacity.
Args:
- unsafe_pointer (
UnsafePointer[T, 0]
): The pointer to the data. - size (
Int
): The number of elements in the list. - capacity (
Int
): The capacity of the list.
__copyinit__
__copyinit__(inout self: Self, existing: Self)
Creates a deepcopy of the given list.
Args:
- existing (
Self
): The list to copy.
__moveinit__
__moveinit__(inout self: Self, owned existing: Self)
Move data of an existing list into a new one.
Args:
- existing (
Self
): The existing list.
__del__
__del__(owned self: Self)
Destroy all elements in the list and free its memory.
__bool__
__bool__(self: Self) -> Bool
Checks whether the list has any elements or not.
Returns:
False
if the list is empty, True
if there is at least one element.
__getitem__
__getitem__(self: Self, span: Slice) -> Self
Gets the sequence of elements at the specified positions.
Args:
- span (
Slice
): A slice that specifies positions of the new list.
Returns:
A new list containing the list at the specified span.
__getitem__(self: Self, idx: Int) -> T
Gets a copy of the list element at the given index.
FIXME(lifetimes): This should return a reference, not a copy!
Args:
- idx (
Int
): The index of the element.
Returns:
A copy of the element at the given index.
__setitem__
__setitem__(inout self: Self, idx: Int, owned value: T)
Sets a list element at the given index.
Args:
- idx (
Int
): The index of the element. - value (
T
): The value to assign.
__contains__
__contains__[T2: ComparableCollectionElement](self: Self, value: T2) -> Bool
Verify if a given value is present in the list.
var x = List[Int](1,2,3)
if 3 in x: print("x contains 3")
Parameters:
- T2 (
ComparableCollectionElement
): The type of the elements in the list. Must implement the traitsEqualityComparable
andCollectionElement
.
Args:
- value (
T2
): The value to find.
Returns:
True if the value is contained in the list, False otherwise.
__add__
__add__(self: Self, owned other: Self) -> Self
Concatenates self with other and returns the result as a new list.
Args:
- other (
Self
): List whose elements will be combined with the elements of self.
Returns:
The newly created list.
__mul__
__mul__(self: Self, x: Int) -> Self
Multiplies the list by x and returns a new list.
Args:
- x (
Int
): The multiplier number.
Returns:
The new list.
__iadd__
__iadd__(inout self: Self, owned other: Self)
Appends the elements of other into self.
Args:
- other (
Self
): List whose elements will be appended to self.
__imul__
__imul__(inout self: Self, x: Int)
Multiplies the list by x in place.
Args:
- x (
Int
): The multiplier number.
append
append(inout self: Self, owned value: T)
Appends a value to this list.
Args:
- value (
T
): The value to append.
insert
insert(inout self: Self, i: Int, owned value: T)
Inserts a value to the list at the given index. a.insert(len(a), value)
is equivalent to a.append(value)
.
Args:
- i (
Int
): The index for the value. - value (
T
): The value to insert.
extend
extend(inout self: Self, owned other: Self)
Extends this list by consuming the elements of other
.
Args:
- other (
Self
): List whose elements will be added in order at the end of this list.
pop
pop(inout self: Self, i: Int = -1) -> T
Pops a value from the list at the given index.
Args:
- i (
Int
): The index of the value to pop.
Returns:
The popped value.
reserve
reserve(inout self: Self, new_capacity: Int)
Reserves the requested capacity.
If the current capacity is greater or equal, this is a no-op. Otherwise, the storage is reallocated and the date is moved.
Args:
- new_capacity (
Int
): The new capacity.
resize
resize(inout self: Self, new_size: Int, value: T)
Resizes the list to the given new size.
If the new size is smaller than the current one, elements at the end are discarded. If the new size is larger than the current one, the list is appended with new values elements up to the requested size.
Args:
- new_size (
Int
): The new size. - value (
T
): The value to use to populate new elements.
resize(inout self: Self, new_size: Int)
Resizes the list to the given new size.
With no new value provided, the new size must be smaller than or equal to the current one. Elements at the end are discarded.
Args:
- new_size (
Int
): The new size.
reverse
reverse(inout self: Self)
Reverses the elements of the list.
index
index[C: ComparableCollectionElement](self: Reference[List[C], is_mutable, lifetime, 0], value: C, start: Int = 0, stop: Optional[Int] = #kgen.none) -> Int
Returns the index of the first occurrence of a value in a list restricted by the range given the start and stop bounds.
var my_list = List[Int](1, 2, 3)
print(my_list.index(2)) # prints `1`
Parameters:
- C (
ComparableCollectionElement
): The type of the elements in the list. Must implement theComparableCollectionElement
trait.
Args:
- value (
C
): The value to search for. - start (
Int
): The starting index of the search, treated as a slice index (defaults to 0). - stop (
Optional[Int]
): The ending index of the search, treated as a slice index (defaults to None, which means the end of the list).
Returns:
The index of the first occurrence of the value in the list.
Raises:
ValueError: If the value is not found in the list.
clear
clear(inout self: Self)
Clears the elements in the list.
steal_data
steal_data(inout self: Self) -> UnsafePointer[T, 0]
Take ownership of the underlying pointer from the list.
Returns:
The underlying data.
unsafe_get
unsafe_get(self: Reference[List[T], is_mutable, lifetime, 0], idx: Int) -> Reference[T, $0, $1, 0]
Get a reference to an element of self without checking index bounds.
Users should consider using __getitem__
instead of this method as it
is unsafe. If an index is out of bounds, this method will not abort, it
will be considered undefined behavior.
Note that there is no wraparound for negative indices, caution is
advised. Using negative indices is considered undefined behavior. Never
use my_list.unsafe_get(-1)
to get the last element of the list.
Instead, do my_list.unsafe_get(len(my_list) - 1)
.
Args:
- idx (
Int
): The index of the element to get.
Returns:
A reference to the element at the given index.
count
count[T: ComparableCollectionElement](self: List[T], value: T) -> Int
Counts the number of occurrences of a value in the list. Note that since we can't condition methods on a trait yet, the way to call this method is a bit special. Here is an example below.
var my_list = List[Int](1, 2, 3)
print(my_list.count(1))
When the compiler supports conditional methods, then a simple my_list.count(1)
will
be enough.
Parameters:
- T (
ComparableCollectionElement
): The type of the elements in the list. Must implement the traitsEqualityComparable
andCollectionElement
.
Args:
- value (
T
): The value to count.
Returns:
The number of occurrences of the value in the list.
unsafe_ptr
unsafe_ptr(self: Self) -> UnsafePointer[T, 0]
Retrieves a pointer to the underlying memory.
Returns:
The UnsafePointer to the underlying memory.
Was this page helpful?
Thank you! We'll create more content like this.
Thank you for helping us improve!
If you'd like to share more information, please report an issue on GitHub
😔 What went wrong?