Struct lexpr::Cons

pub struct Cons { /* fields omitted */ }

A Lisp "cons cell".

A cons cell is similiar to a two-element tuple in Rust. Its fields are traditionally called car and cdr, for obscure historical reasons. Both the car and the cdr field can hold any Value, including other cons cells.

This data type is used to represent singly-linked lists, by forming a chain of cons cells where the list element is kept in the car field, and the cdr field either points to the next cons cell, or terminates the list with any other value. Usually, that terminator value is Value::Null, also referred to as the empty list. If any other terminating value is used, the resulting linked list is referred to as "dotted", or "improper" list.

The Cons data type provides some utility function for the singly-linked list use case, such as iterating through the list or converting the list to a vector. To account for the possibility of dotted lists, the iterators and vector conversion functions have slightly unusual types.

Methods

impl Cons

pub fn new<T, U>(car: T, cdr: U) -> Self where
    T: Into<Value>,
    U: Into<Value>, 

Constructs a new cons cell from two values.

pub fn car(&self) -> &Value

Returns a reference to the value in the car field.

pub fn car_mut(&mut self) -> &mut Value

Returns a mutable reference to the value in the car field.

pub fn set_car(&mut self, car: impl Into<Value>)

Sets the car field.

pub fn cdr(&self) -> &Value

Returns a reference to the value in the cdr field.

pub fn cdr_mut(&mut self) -> &mut Value

Returns a mutable reference to the value in the cdr field.

pub fn set_cdr(&mut self, cdr: impl Into<Value>)

Sets the cdr field.

pub fn as_pair(&self) -> (&Value, &Value)

Returns references to the values in the car and cdr fields.

let cell = Cons::new(1, 2);
assert_eq!(cell.as_pair(), (&Value::from(1), &Value::from(2)));

pub fn into_pair(self) -> (Value, Value)

Converts self into a pair of values without cloning.

let cell = Cons::new("a", 42);
assert_eq!(cell.car(), "a");
assert_eq!(cell.cdr(), 42);
let (car, cdr) = cell.into_pair();
assert_eq!(car, "a");
assert_eq!(cdr, 42);

Important traits for Iter<'a>

impl<'a> Iterator for Iter<'a> type Item = &'a Cons;

pub fn iter(&self) -> Iter

Obtains an iterator yielding references to all the cons cells in this linked list.

for cell in Cons::new(1, Cons::new(2, Value::Null)).iter() {
   println!("list element: {}", cell.car());
}

pub fn into_vec(self) -> (Vec<Value>, Value)

Converts self into a vector without cloning the elements.

Returns the accumulated items of the list and the cdr of the last list element. For proper lists, this will always be Value::Null.

let list = Cons::new(1, Cons::new(2, Cons::new(3, Value::Null)));
assert_eq!(list.into_vec(), (vec![Value::from(1), Value::from(2), Value::from(3)], Value::Null));

pub fn to_vec(&self) -> (Vec<Value>, Value)

Retrieves a vector, cloning the values.

Returns the accumulated items of the list and the cdr of the last list element. For proper lists, this will always be Value::Null.

let list = Cons::new(1, Cons::new(2, Cons::new(3, Value::Null)));
assert_eq!(list.to_vec(), (vec![Value::from(1), Value::from(2), Value::from(3)], Value::Null));

pub fn to_ref_vec(&self) -> (Vec<&Value>, &Value)

Retrieves a vector, taking references to the values.

Returns the accumulated items of the list and the cdr of the last list element. For proper lists, this will always be Value::Null.

let list = Cons::new(1, Cons::new(2, Cons::new(3, Value::Null)));
assert_eq!(list.to_ref_vec(), (vec![&Value::from(1), &Value::from(2), &Value::from(3)], &Value::Null));

Trait Implementations

impl From<Cons> for Value

fn from(pair: Cons) -> Self

Performs the conversion.

impl PartialEq<Cons> for Cons

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl Clone for Cons

fn clone(&self) -> Cons

Returns a copy of the value.

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

Performs copy-assignment from source.

impl IntoIterator for Cons

type Item = (Value, Option<Value>)

The type of the elements being iterated over.

type IntoIter = IntoIter

Which kind of iterator are we turning this into?

Important traits for IntoIter

impl Iterator for IntoIter type Item = (Value, Option<Value>);

fn into_iter(self) -> IntoIter

Obtains an iterator yielding the contents of the elements of this linked list.

The returned iterator transfers ownership of the values contained in the list to the consumer of the iterator. For each cons cell but the last, the iterator yields a pair containing the value in the cell's car field and None. For the last cell, the yielded pair will contain the value of car and Some(cdr).

let vec: Vec<_> = Cons::new(1, Cons::new(2, 3)).into_iter().collect();
assert_eq!(vec, vec![(Value::from(1), None), (Value::from(2), Some(Value::from(3)))]);

impl<'a> IntoIterator for &'a Cons

type Item = &'a Cons

The type of the elements being iterated over.

type IntoIter = Iter<'a>

Which kind of iterator are we turning this into?

Important traits for Iter<'a>

impl<'a> Iterator for Iter<'a> type Item = &'a Cons;

fn into_iter(self) -> Iter<'a>

Creates an iterator from a value.

impl Debug for Cons

fn fmt(&self, fmt: &mut Formatter) -> Result

Formats the value using the given formatter.