Struct Array

pub struct Array { /* private fields */ }

Type representing a TOML array, payload of the Value::Array variant’s value

Implementations

impl Array

Constructors

See also FromIterator

pub fn new() -> Self

Create an empty Array

Examples

let mut arr = toml_edit::Array::new();

impl Array

Formatting

pub fn fmt(&mut self)

Auto formats the array.

pub fn set_trailing_comma(&mut self, yes: bool)

Set whether the array will use a trailing comma

pub fn trailing_comma(&self) -> bool

Whether the array will use a trailing comma

pub fn set_trailing(&mut self, trailing: impl Into<RawString>)

Set whitespace after last element

pub fn trailing(&self) -> &RawString

Whitespace after last element

pub fn decor_mut(&mut self) -> &mut Decor

Returns the surrounding whitespace

pub fn decor(&self) -> &Decor

Returns the surrounding whitespace

pub fn span(&self) -> Option<Range<usize>>

The location within the original document

This generally requires an ImDocument.

impl Array

pub fn iter(&self) -> ArrayIter<'_>

Returns an iterator over all values.

pub fn iter_mut(&mut self) -> ArrayIterMut<'_>

Returns an iterator over all values.

pub fn len(&self) -> usize

Returns the length of the underlying Vec.

In some rare cases, placeholder elements will exist. For a more accurate count, call a.iter().count()

Examples

let mut arr = toml_edit::Array::new();
arr.push(1);
arr.push("foo");
assert_eq!(arr.len(), 2);

pub fn is_empty(&self) -> bool

Return true if self.len() == 0.

Examples

let mut arr = toml_edit::Array::new();
assert!(arr.is_empty());

arr.push(1);
arr.push("foo");
assert!(! arr.is_empty());

pub fn clear(&mut self)

Clears the array, removing all values. Keeps the allocated memory for reuse.

pub fn get(&self, index: usize) -> Option<&Value>

Returns a reference to the value at the given index, or None if the index is out of bounds.

pub fn get_mut(&mut self, index: usize) -> Option<&mut Value>

Returns a reference to the value at the given index, or None if the index is out of bounds.

pub fn push<V: Into<Value>>(&mut self, v: V)

Appends a new value to the end of the array, applying default formatting to it.

Examples

let mut arr = toml_edit::Array::new();
arr.push(1);
arr.push("foo");

pub fn push_formatted(&mut self, v: Value)

Appends a new, already formatted value to the end of the array.

Examples

let formatted_value = "'literal'".parse::<toml_edit::Value>().unwrap();
let mut arr = toml_edit::Array::new();
arr.push_formatted(formatted_value);

pub fn insert<V: Into<Value>>(&mut self, index: usize, v: V)

Inserts an element at the given position within the array, applying default formatting to it and shifting all values after it to the right.

Panics

Panics if index > len.

Examples

let mut arr = toml_edit::Array::new();
arr.push(1);
arr.push("foo");

arr.insert(0, "start");

pub fn insert_formatted(&mut self, index: usize, v: Value)

Inserts an already formatted value at the given position within the array, shifting all values after it to the right.

Panics

Panics if index > len.

Examples

let mut arr = toml_edit::Array::new();
arr.push(1);
arr.push("foo");

let formatted_value = "'start'".parse::<toml_edit::Value>().unwrap();
arr.insert_formatted(0, formatted_value);

pub fn replace<V: Into<Value>>(&mut self, index: usize, v: V) -> Value

Replaces the element at the given position within the array, preserving existing formatting.

Panics

Panics if index >= len.

Examples

let mut arr = toml_edit::Array::new();
arr.push(1);
arr.push("foo");

arr.replace(0, "start");

pub fn replace_formatted(&mut self, index: usize, v: Value) -> Value

Replaces the element at the given position within the array with an already formatted value.

Panics

Panics if index >= len.

Examples

let mut arr = toml_edit::Array::new();
arr.push(1);
arr.push("foo");

let formatted_value = "'start'".parse::<toml_edit::Value>().unwrap();
arr.replace_formatted(0, formatted_value);

pub fn remove(&mut self, index: usize) -> Value

Removes the value at the given index.

Examples

let mut arr = toml_edit::Array::new();
arr.push(1);
arr.push("foo");

arr.remove(0);
assert_eq!(arr.len(), 1);

pub fn retain<F>(&mut self, keep: F)

where F: FnMut(&Value) -> bool,

Retains only the values specified by the keep predicate.

In other words, remove all values for which keep(&value) returns false.

This method operates in place, visiting each element exactly once in the original order, and preserves the order of the retained elements.

pub fn sort_by<F>(&mut self, compare: F)

where F: FnMut(&Value, &Value) -> Ordering,

Sorts the slice with a comparator function.

This sort is stable (i.e., does not reorder equal elements) and O(n * log(n)) worst-case.

The comparator function must define a total ordering for the elements in the slice. If the ordering is not total, the order of the elements is unspecified. An order is a total order if it is (for all a, b and c):

• total and antisymmetric: exactly one of a < b, a == b or a > b is true, and
• transitive, a < b and b < c implies a < c. The same must hold for both == and >.

For example, while f64 doesn’t implement Ord because NaN != NaN, we can use partial_cmp as our sort function when we know the slice doesn’t contain a NaN.

pub fn sort_by_key<K, F>(&mut self, f: F)

where F: FnMut(&Value) -> K, K: Ord,

Sorts the array with a key extraction function.

This sort is stable (i.e., does not reorder equal elements) and O(m * n * log(n)) worst-case, where the key function is O(m).

Trait Implementations

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

Formats the value using the given formatter.

impl Default for Array

fn default() -> Array

Returns the “default value” for a type.

impl Display for Array

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

Formats the value using the given formatter.

impl<V: Into<Value>> Extend<V> for Array

fn extend<T: IntoIterator<Item = V>>(&mut self, iter: T)

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<Array> for Value

fn from(array: Array) -> Self

Converts to this type from the input type.

impl<V: Into<Value>> FromIterator<V> for Array

fn from_iter<I>(iter: I) -> Self

where I: IntoIterator<Item = V>,

Creates a value from an iterator.

impl<'s> IntoIterator for &'s Array

type Item = &'s Value

The type of the elements being iterated over.

type IntoIter = Box<dyn Iterator<Item = &'s Value> + 's>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl IntoIterator for Array

type Item = Value

The type of the elements being iterated over.

type IntoIter = Box<dyn Iterator<Item = Value>>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.