Struct Array

pub struct Array(/* private fields */);

A sequence of values.

You can construct an array by enclosing a comma-separated sequence of values in parentheses. The values do not have to be of the same type.

You can access and update array items with the .at() method. Indices are zero-based and negative indices wrap around to the end of the array. You can iterate over an array using a for loop. Arrays can be added together with the + operator, joined together and multiplied with integers.

Note: An array of length one needs a trailing comma, as in {(1,)}. This is to disambiguate from a simple parenthesized expressions like {(1 + 2) * 3}. An empty array is written as {()}.

Example

#let values = (1, 7, 4, -3, 2)

#values.at(0) \
#(values.at(0) = 3)
#values.at(-1) \
#values.find(calc.even) \
#values.filter(calc.odd) \
#values.map(calc.abs) \
#values.rev() \
#(1, (2, 3)).flatten() \
#(("A", "B", "C")
    .join(", ", last: " and "))

Implementations

impl Array

pub fn new() -> Array

Create a new, empty array.

pub fn with_capacity(capacity: usize) -> Array

Creates a new vec, with a known capacity.

pub fn is_empty(&self) -> bool

Return true if the length is 0.

pub fn as_slice(&self) -> &[Value]

Extract a slice of the whole array.

pub fn iter(&self) -> Iter<'_, Value>

Iterate over references to the contained values.

pub fn first_mut(&mut self) -> Result<&mut Value, EcoString>

Mutably borrow the first value in the array.

pub fn last_mut(&mut self) -> Result<&mut Value, EcoString>

Mutably borrow the last value in the array.

pub fn at_mut(&mut self, index: i64) -> Result<&mut Value, EcoString>

Mutably borrow the value at the given index.

pub fn repeat(&self, n: usize) -> Result<Array, EcoString>

Repeat this array n times.

pub fn contains_impl( &self, value: &Value, sink: &mut dyn DeprecationSink, ) -> bool

The internal implementation of Array::contains.

impl Array

pub fn construct(value: ToArray) -> Array

Converts a value to an array.

Note that this function is only intended for conversion of a collection-like value to an array, not for creation of an array from individual items. Use the array syntax (1, 2, 3) (or (1,) for a single-element array) instead.

#let hi = "Hello 😃"
#array(bytes(hi))

pub fn len(&self) -> usize

The number of values in the array.

pub fn first(&self) -> Result<Value, EcoString>

Returns the first item in the array. May be used on the left-hand side of an assignment. Fails with an error if the array is empty.

pub fn last(&self) -> Result<Value, EcoString>

Returns the last item in the array. May be used on the left-hand side of an assignment. Fails with an error if the array is empty.

pub fn at(&self, index: i64, default: Option<Value>) -> Result<Value, EcoString>

Returns the item at the specified index in the array. May be used on the left-hand side of an assignment. Returns the default value if the index is out of bounds or fails with an error if no default value was specified.

pub fn push(&mut self, value: Value)

Adds a value to the end of the array.

pub fn pop(&mut self) -> Result<Value, EcoString>

Removes the last item from the array and returns it. Fails with an error if the array is empty.

pub fn insert(&mut self, index: i64, value: Value) -> Result<(), EcoString>

Inserts a value into the array at the specified index, shifting all subsequent elements to the right. Fails with an error if the index is out of bounds.

To replace an element of an array, use at.

pub fn remove( &mut self, index: i64, default: Option<Value>, ) -> Result<Value, EcoString>

Removes the value at the specified index from the array and return it.

pub fn slice( &self, start: i64, end: Option<i64>, count: Option<i64>, ) -> Result<Array, EcoString>

Extracts a subslice of the array. Fails with an error if the start or end index is out of bounds.

pub fn contains( &self, engine: &mut Engine<'_>, span: Span, value: Value, ) -> bool

Whether the array contains the specified value.

This method also has dedicated syntax: You can write {2 in (1, 2, 3)} instead of {(1, 2, 3).contains(2)}.

pub fn find( &self, engine: &mut Engine<'_>, context: Tracked<'_, Context<'_>>, searcher: Func, ) -> Result<Option<Value>, EcoVec<SourceDiagnostic>>

Searches for an item for which the given function returns {true} and returns the first match or {none} if there is no match.

pub fn position( &self, engine: &mut Engine<'_>, context: Tracked<'_, Context<'_>>, searcher: Func, ) -> Result<Option<i64>, EcoVec<SourceDiagnostic>>

Searches for an item for which the given function returns {true} and returns the index of the first match or {none} if there is no match.

pub fn range( args: &mut Args, step: NonZero<i64>, ) -> Result<Array, EcoVec<SourceDiagnostic>>

Create an array consisting of a sequence of numbers.

If you pass just one positional parameter, it is interpreted as the end of the range. If you pass two, they describe the start and end of the range.

This function is available both in the array function’s scope and globally.

#range(5) \
#range(2, 5) \
#range(20, step: 4) \
#range(21, step: 4) \
#range(5, 2, step: -1)

pub fn filter( &self, engine: &mut Engine<'_>, context: Tracked<'_, Context<'_>>, test: Func, ) -> Result<Array, EcoVec<SourceDiagnostic>>

Produces a new array with only the items from the original one for which the given function returns true.

pub fn map( self, engine: &mut Engine<'_>, context: Tracked<'_, Context<'_>>, mapper: Func, ) -> Result<Array, EcoVec<SourceDiagnostic>>

Produces a new array in which all items from the original one were transformed with the given function.

pub fn enumerate(self, start: i64) -> Result<Array, EcoString>

Returns a new array with the values alongside their indices.

The returned array consists of (index, value) pairs in the form of length-2 arrays. These can be destructured with a let binding or for loop.

pub fn zip( self, args: &mut Args, exact: bool, ) -> Result<Array, EcoVec<SourceDiagnostic>>

Zips the array with other arrays.

Returns an array of arrays, where the ith inner array contains all the ith elements from each original array.

If the arrays to be zipped have different lengths, they are zipped up to the last element of the shortest array and all remaining elements are ignored.

This function is variadic, meaning that you can zip multiple arrays together at once: {(1, 2).zip(("A", "B"), (10, 20))} yields {((1, "A", 10), (2, "B", 20))}.

pub fn fold( self, engine: &mut Engine<'_>, context: Tracked<'_, Context<'_>>, init: Value, folder: Func, ) -> Result<Value, EcoVec<SourceDiagnostic>>

Folds all items into a single value using an accumulator function.

pub fn sum( self, engine: &mut Engine<'_>, span: Span, default: Option<Value>, ) -> Result<Value, HintedString>

Sums all items (works for all types that can be added).

pub fn product(self, default: Option<Value>) -> Result<Value, HintedString>

Calculates the product all items (works for all types that can be multiplied).

pub fn any( self, engine: &mut Engine<'_>, context: Tracked<'_, Context<'_>>, test: Func, ) -> Result<bool, EcoVec<SourceDiagnostic>>

Whether the given function returns {true} for any item in the array.

pub fn all( self, engine: &mut Engine<'_>, context: Tracked<'_, Context<'_>>, test: Func, ) -> Result<bool, EcoVec<SourceDiagnostic>>

Whether the given function returns {true} for all items in the array.

pub fn flatten(self) -> Array

Combine all nested arrays into a single flat one.

pub fn rev(self) -> Array

Return a new array with the same items, but in reverse order.

pub fn split(&self, at: Value) -> Array

Split the array at occurrences of the specified value.

pub fn join( self, engine: &mut Engine<'_>, span: Span, separator: Option<Value>, last: Option<Value>, ) -> Result<Value, EcoString>

Combine all items in the array into one.

pub fn intersperse(self, separator: Value) -> Array

Returns an array with a copy of the separator value placed between adjacent elements.

pub fn chunks(self, chunk_size: NonZero<usize>, exact: bool) -> Array

Splits an array into non-overlapping chunks, starting at the beginning, ending with a single remainder chunk.

All chunks but the last have chunk-size elements. If exact is set to {true}, the remainder is dropped if it contains less than chunk-size elements.

#let array = (1, 2, 3, 4, 5, 6, 7, 8)
#array.chunks(3) \
#array.chunks(3, exact: true)

pub fn windows(self, window_size: NonZero<usize>) -> Array

Returns sliding windows of window-size elements over an array.

If the array length is less than window-size, this will return an empty array.

#let array = (1, 2, 3, 4, 5, 6, 7, 8)
#array.windows(5)

pub fn sorted( self, engine: &mut Engine<'_>, context: Tracked<'_, Context<'_>>, span: Span, key: Option<Func>, ) -> Result<Array, EcoVec<SourceDiagnostic>>

Return a sorted version of this array, optionally by a given key function. The sorting algorithm used is stable.

Returns an error if two values could not be compared or if the key function (if given) yields an error.

To sort according to multiple criteria at once, e.g. in case of equality between some criteria, the key function can return an array. The results are in lexicographic order.

#let array = (
  (a: 2, b: 4),
  (a: 1, b: 5),
  (a: 2, b: 3),
)
#array.sorted(key: it => (it.a, it.b))

pub fn dedup( self, engine: &mut Engine<'_>, context: Tracked<'_, Context<'_>>, span: Span, key: Option<Func>, ) -> Result<Array, EcoVec<SourceDiagnostic>>

Deduplicates all items in the array.

Returns a new array with all duplicate items removed. Only the first element of each duplicate is kept.

#(1, 1, 2, 3, 1).dedup()

pub fn to_dict(self) -> Result<Dict, EcoString>

Converts an array of pairs into a dictionary. The first value of each pair is the key, the second the value.

If the same key occurs multiple times, the last value is selected.

#(
  ("apples", 2),
  ("peaches", 3),
  ("apples", 5),
).to-dict()

pub fn reduce( self, engine: &mut Engine<'_>, context: Tracked<'_, Context<'_>>, reducer: Func, ) -> Result<Value, EcoVec<SourceDiagnostic>>

Reduces the elements to a single one, by repeatedly applying a reducing operation.

If the array is empty, returns {none}, otherwise, returns the result of the reduction.

The reducing function is a closure with two arguments: an “accumulator”, and an element.

For arrays with at least one element, this is the same as [array.fold] with the first element of the array as the initial accumulator value, folding every subsequent element into it.

Trait Implementations

impl Add for Array

type Output = Array

The resulting type after applying the + operator.

fn add(self, rhs: Array) -> <Array as Add>::Output

Performs the + operation.

impl AddAssign for Array

fn add_assign(&mut self, rhs: Array)

Performs the += operation.

impl Clone for Array

fn clone(&self) -> Array

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Array

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for Array

fn default() -> Array

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Array

fn deserialize<__D>( __deserializer: __D, ) -> Result<Array, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Extend<Value> for Array

fn extend<T>(&mut self, iter: T)

where T: IntoIterator<Item = Value>,

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl From<&[Value]> for Array

fn from(v: &[Value]) -> Array

Converts to this type from the input type.

impl From<EcoVec<Value>> for Array

fn from(v: EcoVec<Value>) -> Array

Converts to this type from the input type.

impl FromIterator<Value> for Array

fn from_iter<T>(iter: T) -> Array

where T: IntoIterator<Item = Value>,

Creates a value from an iterator.

impl FromValue for Array

fn from_value(value: Value) -> Result<Array, HintedString>

Try to cast the value into an instance of Self.

impl Hash for Array

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'a> IntoIterator for &'a Array

type Item = &'a Value

The type of the elements being iterated over.

type IntoIter = Iter<'a, Value>

Which kind of iterator are we turning this into?

fn into_iter(self) -> <&'a Array as IntoIterator>::IntoIter

Creates an iterator from a value.

impl IntoIterator for Array

type Item = Value

The type of the elements being iterated over.

type IntoIter = IntoIter<Value>

Which kind of iterator are we turning this into?

fn into_iter(self) -> <Array as IntoIterator>::IntoIter

Creates an iterator from a value.

impl IntoValue for Array

fn into_value(self) -> Value

Cast this type into a value.

impl NativeScope for Array

fn constructor() -> Option<&'static NativeFuncData>

The constructor function for the type, if any.

fn scope() -> Scope

Get the associated scope for the type.

impl NativeType for Array

const NAME: &'static str = "array"

The type’s name.

fn data() -> &'static NativeTypeData

fn ty() -> Type

Get the type for the native Rust type.

impl PartialEq for Array

fn eq(&self, other: &Array) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Reflect for Array

fn input() -> CastInfo

Describe what can be cast into this value.

fn output() -> CastInfo

Describe what this value can be cast into.

fn castable(value: &Value) -> bool

Whether the given value can be converted to T.

fn error(found: &Value) -> HintedString

Produce an error message for an unacceptable value type.

impl Repr for Array

fn repr(&self) -> EcoString

Return the debug representation of the value.

impl Serialize for Array

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Array