std.array.Array
class pub Array[T]
An ordered, integer-indexed generic collection of values.
Accessing values in an Array
is a constant-time operation.
Arrays are created using the array literal syntax, instead of using a method. Here's how you'd create an empty Array:
[]
And here's how you'd create an Array with values:
[10, 20, 30]
All values in an array must be of the same type, and the array's value type is based on the type of the first value.
Static methods
filled
Show source codeHide source code
fn pub static filled[V: Clone[V]](with: V, times: Int) -> Array[V] {
if times == 0 { return [] }
let array = with_capacity(times)
let temp = ref with
(times - 1).times(fn (_) { array.push(temp.clone) })
array.push(with)
array
}
fn pub static filled[V: Clone[V]](with: V, times: Int) -> Array[V]
Returns an array filled with a certain amount of values.
The times
argument specifies how many times the with
argument must
exist in the array.
Examples
Array.filled(with: 0, times: 4) # => [0, 0, 0, 0]
with_capacity
Show source codeHide source code
fn pub static with_capacity(size: Int) -> Array[T] {
if size < 0 { panic('The capacity must be greater than or equal to zero') }
let vsize = _INKO.size_of_type_parameter(T)
let buffer = alloc_imp.resize(0x0 as Pointer[T], size: size * vsize)
Array(size: 0, capacity: size, buffer: buffer)
}
fn pub static with_capacity(size: Int) -> Array[T]
Returns a new Array
with enough space for at least amount
values.
The actual capacity may be greater than the given value.
Panics
This method panics of size
if less than zero.
Instance methods
!=
Show source codeHide source code
fn pub !=(other: T) -> Bool {
(self == other).false?
}
fn pub !=(other: T) -> Bool
Returns true
if self
and the given object are not equal to each other.
==
Show source codeHide source code
fn pub ==(other: ref Array[T]) -> Bool {
if @size != other.size { return false }
let mut index = 0
let max = @size
while index < max {
let ours = get(index)
let theirs = other.get(index)
if ours != theirs { return false }
index += 1
}
true
}
fn pub ==(other: ref Array[T]) -> Bool
if
T: Equal[ref T]
Returns true
if self
and the given Array
are identical.
Examples
Comparing two identical arrays:
[10, 20, 30] == [10, 20, 30] # => true
Comparing two arrays with a different size:
[10] == [10, 20] # => false
Comparing two arrays with the same size but with different values:
[10, 20] == [20, 10] # => false
append
Show source codeHide source code
fn pub mut append(other: Array[T]) {
other.into_iter.each(fn (v) { push(v) })
}
fn pub mut append(other: Array[T])
Appends the values of the given Array
to self
.
Examples
Appending one Array
to another:
let numbers = [10, 20, 30]
numbers.append([40, 50])
numbers.size # => 5
capacity
Show source codeHide source code
fn pub capacity -> Int {
@capacity
}
fn pub capacity -> Int
Returns the number of values that can be stored in self
before self
needs to be resized.
Examples
Array.with_capacity(2).capacity # => 4
clear
Show source codeHide source code
fn pub mut clear {
let mut index = 0
let max = @size
while index < max { read_from(index := index + 1) }
@size = 0
}
fn pub mut clear
Removes all values in the Array.
Examples
let array = [10, 20, 30]
array.clear
array.empty? # => true
clone
Show source codeHide source code
fn pub clone -> Array[T] {
let len = @size
let copy = Array.with_capacity(len)
let mut index = 0
while index < len { copy.push(get(index := index + 1).clone) }
copy
}
fn pub clone -> Array[T]
if
T: Clone[T]
Creates a clone of self
.
contains?
Show source codeHide source code
fn pub contains?(value: ref T) -> Bool {
iter.any?(fn (ours) { ours == value })
}
fn pub contains?(value: ref T) -> Bool
if
T: Equal[ref T]
Returns true
if self
contains the given value.
Examples
Checking if an Array
contains a value:
[10, 20, 30].contains?(10) # => true
empty?
Show source codeHide source code
fn pub empty? -> Bool {
@size == 0
}
fn pub empty? -> Bool
Returns true
if self
is empty.
Examples
[10].empty? # => false
[].empty? # => true
fmt
Show source codeHide source code
fn pub fmt(formatter: mut Formatter) {
let fmt = formatter.array
iter.each(fn (value) { fmt.value(value) })
fmt.finish
}
fn pub fmt(formatter: mut Formatter)
if
T: Format
Formats self
in a human-readable format for debugging purposes.
get
Show source codeHide source code
fn pub get(index: Int) -> ref T {
bounds_check(index, @size)
get_unchecked(index)
}
fn pub get(index: Int) -> ref T
Returns an immutable reference to the value at the given index.
Panics
This method panics if the index is out of bounds.
Examples
let numbers = [10, 20]
numbers.get(0) # => 10
get_mut
Show source codeHide source code
fn pub mut get_mut(index: Int) -> mut T {
bounds_check(index, @size)
get_unchecked_mut(index)
}
fn pub mut get_mut(index: Int) -> mut T: mut
if
T: mut
Returns a mutable reference to the value at the given index.
Panics
This method panics if the index is out of bounds.
Examples
let numbers = [10, 20]
numbers.get_mut(0) # => 10
hash
Show source codeHide source code
fn pub hash[H: mut + Hasher](hasher: mut H) {
let mut index = 0
let max = @size
while index < max { get(index := index + 1).hash(hasher) }
}
fn pub hash[H: mut + Hasher](hasher: mut H: mut)
if
T: Hash
Writes the hash for self
into the given Hasher
.
index_of
Show source codeHide source code
fn pub index_of(value: ref T) -> Option[Int] {
let mut idx = 0
while idx < @size {
if get_unchecked(idx) == value { return Option.Some(idx) }
idx += 1
}
Option.None
}
fn pub index_of(value: ref T) -> Option[Int]
if
T: Equal[ref T]
Returns the index of value
as a Some
if present, otherwise it returns a
None
.
Examples
[10, 20, 30].index_of(20) # => Option.Some(1)
[10, 20, 30].index_of(50) # => Option.None
insert
Show source codeHide source code
fn pub mut insert(index: Int, value: T) {
if index < 0 or index > @size {
panic('The index ${index} is out of bounds (size: ${@size})')
}
reserve(1)
# Shift to the right if the insertion isn't at the end of the array. If we
# have values like this:
#
# [A, B, C, D]
#
# And we want to insert at the index of B (index 1), this results in the
# following values:
#
# [A, B, B, C, D]
#
# We can then overwrite index 1 with the value to insert.
if index < @size {
let from = address_of(index)
let to = address_of(index + 1)
let vsize = _INKO.size_of_type_parameter(T)
alloc_imp.copy(from, to, size: @size - index * vsize)
}
write_to(index, value)
@size += 1
}
fn pub mut insert(index: Int, value: T)
Inserts the value at the given index, shifting all values after it to the right.
Panics
This method panics if the index is less than zero, or greater than the
number of values in self
.
Examples
Inserting a value at the start:
let nums = [10, 20]
nums.insert(0, 30)
nums # => [30, 10, 20]
Inserting a value at the end:
let nums = [10, 20]
nums.insert(2, 30)
nums # => [10, 20, 30]
into_iter
Show source codeHide source code
fn pub move into_iter -> IntoIter[T] {
IntoIter(array: self, index: 0)
}
fn pub move into_iter -> IntoIter[T]
Returns an Iter
that iterates over all values in self
, returning them
by value.
Examples
let numbers = [10, 20, 30]
let iter = numbers.into_iter
iter.next # => Option.Some(10)
iter.next # => Option.Some(20)
iter.next # => Option.Some(30)
iter.next # => Option.None
iter
Show source codeHide source code
fn pub iter -> Stream[ref T] {
let mut idx = 0
let max = @size
Stream.new(fn move {
if idx < max {
Option.Some(get_unchecked(idx := idx + 1))
} else {
Option.None
}
})
}
fn pub iter -> Stream[ref T]
Returns an iterator that yields immutable references to the values in
self
.
iter_mut
Show source codeHide source code
fn pub mut iter_mut -> Stream[mut T] {
let mut idx = 0
let max = @size
Stream.new(fn move {
if idx < max {
Option.Some(get_unchecked_mut(idx := idx + 1))
} else {
Option.None
}
})
}
fn pub mut iter_mut -> Stream[mut T: mut]
if
T: mut
Returns an iterator that yields mutable references to the values in self
.
last
Show source codeHide source code
fn pub last -> Option[ref T] {
opt(size - 1)
}
fn pub last -> Option[ref T]
Returns an immutable reference to the last value in self
.
Examples
[].last # => Option.None
[10, 20].last # => Option.Some(20)
last_mut
Show source codeHide source code
fn pub mut last_mut -> Option[mut T] {
opt_mut(size - 1)
}
fn pub mut last_mut -> Option[mut T: mut]
if
T: mut
Returns a mutable reference to the last value in self
.
Examples
[].last_mut # => Option.None
[10, 20].last_mut # => Option.Some(20)
opt
Show source codeHide source code
fn pub opt(index: Int) -> Option[ref T] {
if index < 0 or index >= @size { return Option.None }
Option.Some(get_unchecked(index))
}
fn pub opt(index: Int) -> Option[ref T]
Returns an optional immutable reference to the value at the given index.
Examples
Retrieving an existing value:
let numbers = [10, 20]
numbers.opt(0) # => Option.Some(ref 10)
Retrieving a value from a non-existing index:
let numbers = [10, 20]
numbers.opt(5) # => Option.None
opt_mut
Show source codeHide source code
fn pub mut opt_mut(index: Int) -> Option[mut T] {
if index < 0 or index >= @size { return Option.None }
Option.Some(get_unchecked_mut(index))
}
fn pub mut opt_mut(index: Int) -> Option[mut T: mut]
if
T: mut
Returns an optional mutable reference to the value at the given index.
Examples
Retrieving an existing value:
let numbers = [10, 20]
numbers.opt_mut(0) # => Option.Some(mut 10)
Retrieving a value from a non-existing index:
let numbers = [10, 20]
numbers.opt_mut(5) # => Option.None
pop
Show source codeHide source code
fn pub mut pop -> Option[T] {
if @size == 0 { return Option.None }
@size -= 1
Option.Some(read_from(@size))
}
fn pub mut pop -> Option[T]
Removes a value from the back of the Array, returning the removed value.
If no value was found, a None is returned instead.
Examples
Popping an existing value:
let array = [10]
array.pop # => Option.Some(10)
array.empty? # => true
Popping a value when the Array is empty:
let array = []
array.pop # => Option.None
push
Show source codeHide source code
fn pub mut push(value: T) {
reserve(1)
write_to(@size, value)
@size += 1
}
fn pub mut push(value: T)
Pushes a value to the back of the Array.
Examples
Pushing a value into an Array:
let array = []
array.push(10) # => Nil
array.get(0) # => 10
remove_at
Show source codeHide source code
fn pub mut remove_at(index: Int) -> T {
let len = size
bounds_check(index, len)
let addr = address_of(index)
let val = addr.0
let vsize = _INKO.size_of_type_parameter(T)
alloc_imp.copy(
from: addr as Int + vsize as Pointer[T],
to: addr,
size: len - index - 1 * vsize,
)
@size = len - 1
val
}
fn pub mut remove_at(index: Int) -> T
Removes the value at the given index, returning the removed value.
Values to the right of the index are shifted to the left.
Examples
Removing an existing value will result in the value being removed from the Array and returned:
let array = [10]
array.remove_at(0) # => 10
array.empty? # => true
Panics
This method panics if the index is out of bounds.
reserve
Show source codeHide source code
fn pub mut reserve(size: Int) {
if @capacity - @size >= size { return }
let vsize = _INKO.size_of_type_parameter(T)
@capacity = max(@capacity * 2, @capacity + size)
@buffer = alloc_imp.resize(@buffer, @capacity * vsize)
}
fn pub mut reserve(size: Int)
Reserves space for size
additional values.
The actual space reserved may be greater to prevent frequent reallocations.
After calling this method, the capacity will be greater than or equal to
self.size + size
.
If the capacity is great enough or the given size is less than zero, this method does nothing.
reverse
Show source codeHide source code
fn pub mut reverse {
let mut a = 0
let mut b = @size - 1
while a < b {
let a_val = read_from(a)
let b_val = read_from(b)
write_to(b, a_val)
write_to(a, b_val)
a += 1
b -= 1
}
}
fn pub mut reverse
Reverses self
in-place
Examples
let a = [10, 20, 30]
a.reverse
a # => [30, 20, 10]
reverse_iter
Show source codeHide source code
fn pub reverse_iter -> Stream[ref T] {
let mut index = size - 1
Stream.new(fn move {
if index > -1 {
Option.Some(get(index := index - 1))
} else {
Option.None
}
})
}
fn pub reverse_iter -> Stream[ref T]
Returns an Iter
that iterates over all values in self
in reverse
order.
Examples
Iterating over an Array
in reverse order:
let numbers = [10, 20, 30]
let iter = numbers.reverse_iter
iter.next # => Option.Some(30)
iter.next # => Option.Some(20)
iter.next # => Option.Some(10)
iter.next # => Option.None
set
Show source codeHide source code
fn pub mut set(index: Int, value: T) {
bounds_check(index, @size)
# This drops the old value, then writes the new value.
read_from(index)
write_to(index, value)
}
fn pub mut set(index: Int, value: T)
Stores a value at the given index.
If a value is already present at the given index, it's dropped before the new value overwrites it.
Panics
This method panics if the index is out of bounds.
Examples
Setting an index to a value:
let array = []
array.set(0, 10)
array # => [10]
shuffle
Show source codeHide source code
fn pub mut shuffle {
Shuffle.new.sort(self)
}
fn pub mut shuffle
Sorts the values in self
such that they are in a random order.
Examples
let a = [10, 20]
a.shuffle
a # => [20, 10]
size
Show source codeHide source code
fn pub size -> Int {
@size
}
fn pub size -> Int
Returns the number of values in this Array.
Examples
Getting the size of an empty Array:
[].size # => 0
Getting the size of an Array with values:
[10].size # => 1
sort
Show source codeHide source code
fn pub mut sort {
stable_sort(self, fn (a, b) { a <= b })
}
fn pub mut sort
if
T: Compare[T]
Sorts the values in self
in ascending order.
This method performs a stable sort, meaning it maintains the relative order of duplicate values.
Examples
let nums = [0, 3, 3, 5, 9, 1]
nums.sort
nums # => [0, 1, 3, 3, 5, 9]
sort_by
Show source codeHide source code
fn pub mut sort_by(block: fn (ref T, ref T) -> Ordering) {
stable_sort(self, fn (a, b) {
match block.call(a, b) {
case Less or Equal -> true
case _ -> false
}
})
}
fn pub mut sort_by(block: fn (ref T, ref T) -> Ordering)
Sorts the values in self
using a custom comparison closure.
Like Array.sort
, this method performs a stable sort.
Examples
let nums = [0, 3, 3, 5, 9, 1]
nums.sort_by fn (a, b) { b.cmp(a) }
nums # => [9, 5, 3, 3, 1, 0]
swap
Show source codeHide source code
fn pub mut swap(index: Int, with: T) -> T {
bounds_check(index, @size)
let old = read_from(index)
write_to(index, with)
old
}
fn pub mut swap(index: Int, with: T) -> T
Inserts the value at the given index, returning the old value.
Panics
This method panics if the index is out of bounds.
Examples
let numbers = [10, 20, 30]
numbers.swap(index: 1, with: 40) # => 20
numbers # => [10, 40, 30]
swap_indexes
Show source codeHide source code
fn pub mut swap_indexes(index: Int, with: Int) {
bounds_check(index, @size)
bounds_check(with, @size)
let a = read_from(index)
let b = read_from(with)
write_to(index, b)
write_to(with, a)
}
fn pub mut swap_indexes(index: Int, with: Int)
Swaps the values at the given indexes.
Examples
let numbers = [10, 20, 30]
numbers.swap_indexes(index: 0, with: 2)
numbers # => [30, 20, 10]
Implemented traits
Clone
impl Clone[Array[T]] for Array
if
T: Clone[T]
Contains
impl Contains[T] for Array
if
T: Equal[ref T]
Equal
impl Equal[ref Array[T]] for Array
if
T: Equal[ref T]
Drop
impl Drop for Array
Format
impl Format for Array
if
T: Format
Hash
impl Hash for Array
if
T: Hash