s, t, u. The sequence s is a sub-sequence of t, and t
being a sub-sequence of u; each one accessible in its function context only.
The module seq provides a generic sequence container Seq for Rust.
Seq is a lightweight container of data sequences, data being stacked on top of each other (LIFO).
Add the following dependency to your Cargo.toml file: ```toml
[dependencies] seq = "0.3.0" ```
Seq is defined as generic enum. Seq is a sequence of data of type T and lifetime 'a.
Either a sequence is Empty or a sequence is a construction of a new value
(head or first (ft)) on-top of another sequence (the tail or rest (rt)). The lifetime of the tail must be at least as
long as the one of the head. Two kind of constructions are possible, depending on location of tail in memory-heap or
on stack.
rust
pub enum Seq<'a, T: 'a> {
Empty,
ConsRef(T, &'a Seq<'a, T>),
ConsOwn(T, Box<Seq<'a, T>>),
}
Explaning the enum variants:
* Empty: The empty sequence <>
* ConsRef(head, tail): Constructs a new sequence with head being the first element and tail referencing another,
borrowed sequence. This variant permits construction of sequences using stack-allocated
data solely.
* ConsOwn(head, boxedtail): Constructs a new sequence with head being the first element and boxedtail referencing
another, owned, boxed sequence. Here the tail is residing in heap allocated memory. This variant
permits construction of sequences using heap-allocated dynamic data.
These variants may be combined with each other, representing a mixture of borrowed and owned elements. The memory safety feature of Rust allows automated and correct management of lifetime of each element of the sequence.
The lifetime of each element of the sequence depends on the function-context it has been added to the top of the sequence; Empty is the element with longest lifetime (see image).
The following image illustrates the sequences s, t, u. The sequence s is a sub-sequence of t, and t
being a sub-sequence of u; each one accessible in its function context only.
For use-cases where a sub-routine/expression shall return a temporary extended sequence, it is possible to construct new
sequences using elements in heap-memory. In this case these heap-elements are boxed/owned.
But, first and foremost, the container Seq is intended as lightweight, dynamic, stack-allocated, linked list for use cases such as managing state/context while traversing tree-like data structures - without any dynamic memory-allocation (heap) involved.
The sequence type Seq implements the trait IntoIterator, enabling the usage of Rust's iterator framework.
A stack allocated sequnece is based on the variants Seq::Empty and Seq::ConsRef only ```rust extern crate seq; use seq::Seq;
fn myfun() {
// constructing the sequence seq!(3,2,1)
let s0: Seq
A sequence can be a mixture of stack-allocated and heap-allocated data elements. The following sequence ```rust extern crate seq; use seq::Seq;
fn myfun() {
let s0: Seq
Pattern-matching is used to de-construct a sequence. ```rust extern crate seq; use seq::Seq;
fn head(sequence: &Seq
Sequences can be used to manage state in nested function calls. This code demonstrates how the iterator is used. ```rust extern crate seq; use seq::Seq; use std::ops;
// Recursive, nested invocation while val
fn main() { recurs(0, 10, seq::empty()); } ```
'Seq' permits mixture of stack allocated data and heap allocated data within a single linked list. The following code is a variation of previous sample, just adding two heap-allocated elements onto top of sequence finally. This code demonstrates how the iterator is used. ```rust extern crate seq; use seq::Seq; use std::ops;
fn prependTwoBoxedValues <'a> (v: u32, w: u32, seq: &'a Seq
// Recursive, nested invocation while val
fn main() { recurs(0, 10, seq::empty()); } ```
The seqdef! macro defines a stack-allocated sequence variable using the speficied data list,
the last data item in the list will be the top most in the sequence (head). The macro can be used to
create a new sequence on top of another one (tail).
s, the head will be 2.rust
seqdef!(s; seq::empty() => 0, 1, 2);
seq::empty(). Seq t is identical to s.rust
seqdef!(t; 0, 1, 2);
s of example 1 as tail, the head will be 5.rust
seqdef!(u; &s => 3, 4, 5);
The previous macros are useful, but limited as the exact number of elements must be known at compile time.
The following macro seqdef_try! helps. This macro reserves MAX elements on the stack
every time when entering the function context. The upper limit MAX is defined at compile time.
At runtime the sequence is constructed, reading the elements from the iterator and placing them
in the reserved stack-memory. When the function context is left, the stack-memory is released.
The macro seqdef_try! will declare the specified identifier as type Resultx must be checked after construction with seqdef_try!.
Note! No matter the number of elements returned by the iterator, the macro is always reserving stack-memory for MAX elements. If you choose too large, the stack might run out of memory. The iterator provided to the macro may consume the underlying container-elements or clone each element. ```rust use std::mem; use std::ptr;
fn largeseqrolloutonstack() {
const MAX: usize = 2000;
let largelist: &[i32] = &[42; MAX];
// define x of type Result