Struct Chain

pub struct Chain<T, M: Map<T> = BTree> { /* private fields */ }

A Markov chain.

This type implements Serialize and Deserialize when the serde feature is enabled (which it is by default).

Implementations

impl<T, M: Map<T>> Chain<T, M>

pub fn new(depth: usize) -> Self

Creates a new chain.

See Self::depth for an explanation of the depth.

Examples found in repository

examples/example.rs (line 23)

fn main() -> io::Result<()> {
    const DEPTH: usize = 6;
    // Maps each sequence of 6 items to a list of possible next items.
    // `HashChain` uses hash maps internally; b-trees can also be used.
    let mut chain = HashChain::new(DEPTH);

    // In this case, corpus.txt contains one paragraph per line.
    let file = File::open("examples/corpus.txt")?;
    let mut reader = BufReader::new(file);
    let mut line = String::new();
    // The previous `DEPTH` characters before `line`.
    let mut prev = Vec::<char>::new();

    while let Ok(1..) = reader.read_line(&mut line) {
        // `Both` means that the generated random output could start with the
        // beginning of `line` or end after the end of `line`.
        chain.add_all(line.chars(), AddEdges::Both);

        // This makes sure there's a chance that the end of the previous line
        // could be followed by the start of the current line when generating
        // random output.
        chain.add_all(
            prev.iter().copied().chain(line.chars().take(DEPTH)),
            AddEdges::Neither,
        );

        if let Some((n, (i, _c))) =
            line.char_indices().rev().enumerate().take(DEPTH).last()
        {
            // Keep only the most recent `DEPTH` characters.
            prev.drain(0..prev.len().saturating_sub(DEPTH - n - 1));
            prev.extend(line[i..].chars());
        }
        line.clear();
    }

    // Generate and print random Markov data.
    let mut stdout = BufWriter::new(io::stdout().lock());
    let mut prev_newline = false;
    for &c in chain.generate() {
        if prev_newline {
            writeln!(stdout)?;
        }
        prev_newline = c == '\n';
        write!(stdout, "{c}")?;
    }
    stdout.flush()
}

pub fn depth(&self) -> usize

Gets the chain’s depth.

A depth of n means the chain maps sequences of n items of type T to a list of possible next items.

pub fn add_all<I>(&mut self, items: I, edges: AddEdges)

where I: IntoIterator<Item = T>, T: Clone,

Adds all items in an iterator to the chain.

This essentially calls Self::add on every overlapping window of self.depth() elements plus the item following each window. (Smaller windows at the start of the sequence may also be added depending on the value of edges.)

edges controls whether the start or end of items may be used as the start or end of a generated sequence from the chain. See the documentation for AddEdges for more information.

Examples found in repository

examples/example.rs (line 35)

fn main() -> io::Result<()> {
    const DEPTH: usize = 6;
    // Maps each sequence of 6 items to a list of possible next items.
    // `HashChain` uses hash maps internally; b-trees can also be used.
    let mut chain = HashChain::new(DEPTH);

    // In this case, corpus.txt contains one paragraph per line.
    let file = File::open("examples/corpus.txt")?;
    let mut reader = BufReader::new(file);
    let mut line = String::new();
    // The previous `DEPTH` characters before `line`.
    let mut prev = Vec::<char>::new();

    while let Ok(1..) = reader.read_line(&mut line) {
        // `Both` means that the generated random output could start with the
        // beginning of `line` or end after the end of `line`.
        chain.add_all(line.chars(), AddEdges::Both);

        // This makes sure there's a chance that the end of the previous line
        // could be followed by the start of the current line when generating
        // random output.
        chain.add_all(
            prev.iter().copied().chain(line.chars().take(DEPTH)),
            AddEdges::Neither,
        );

        if let Some((n, (i, _c))) =
            line.char_indices().rev().enumerate().take(DEPTH).last()
        {
            // Keep only the most recent `DEPTH` characters.
            prev.drain(0..prev.len().saturating_sub(DEPTH - n - 1));
            prev.extend(line[i..].chars());
        }
        line.clear();
    }

    // Generate and print random Markov data.
    let mut stdout = BufWriter::new(io::stdout().lock());
    let mut prev_newline = false;
    for &c in chain.generate() {
        if prev_newline {
            writeln!(stdout)?;
        }
        prev_newline = c == '\n';
        write!(stdout, "{c}")?;
    }
    stdout.flush()
}

pub fn add<I>(&mut self, items: I, next: Option<T>)

where I: IntoIterator<Item = T>,

Adds items to the chain.

If items yields at least self.depth() items, this increases the chance that the first self.depth() items will be followed by next in a generated sequence (additional items in items are ignored).

If items yields fewer than self.depth() items, this method increases the chance that those items, when they are the only items that have been generated so far in a sequence (i.e., the start of a sequence), will be followed by next. In the case where items yields no elements, this increases the chance that item will be produced as the first element of a generated sequence.

If next is None, this method increases the chance that items will be considered the end of a sequence.

pub fn generate(&self) -> Generator<'_, T, ThreadRng, M>

Available on crate feature std only.

Generates random Markov chain data.

Returns an iterator that yields the elements by reference. If you want them by value, simply use Iterator::cloned (as long as T is Clone).

Examples found in repository

examples/example.rs (line 58)

fn main() -> io::Result<()> {
    const DEPTH: usize = 6;
    // Maps each sequence of 6 items to a list of possible next items.
    // `HashChain` uses hash maps internally; b-trees can also be used.
    let mut chain = HashChain::new(DEPTH);

    // In this case, corpus.txt contains one paragraph per line.
    let file = File::open("examples/corpus.txt")?;
    let mut reader = BufReader::new(file);
    let mut line = String::new();
    // The previous `DEPTH` characters before `line`.
    let mut prev = Vec::<char>::new();

    while let Ok(1..) = reader.read_line(&mut line) {
        // `Both` means that the generated random output could start with the
        // beginning of `line` or end after the end of `line`.
        chain.add_all(line.chars(), AddEdges::Both);

        // This makes sure there's a chance that the end of the previous line
        // could be followed by the start of the current line when generating
        // random output.
        chain.add_all(
            prev.iter().copied().chain(line.chars().take(DEPTH)),
            AddEdges::Neither,
        );

        if let Some((n, (i, _c))) =
            line.char_indices().rev().enumerate().take(DEPTH).last()
        {
            // Keep only the most recent `DEPTH` characters.
            prev.drain(0..prev.len().saturating_sub(DEPTH - n - 1));
            prev.extend(line[i..].chars());
        }
        line.clear();
    }

    // Generate and print random Markov data.
    let mut stdout = BufWriter::new(io::stdout().lock());
    let mut prev_newline = false;
    for &c in chain.generate() {
        if prev_newline {
            writeln!(stdout)?;
        }
        prev_newline = c == '\n';
        write!(stdout, "{c}")?;
    }
    stdout.flush()
}

pub fn generate_with_rng<R: Rng>(&self, rng: R) -> Generator<'_, T, R, M>

Like Self::generate, but takes a custom random number generator.

pub fn get<'a, B>(&'a self, items: &[B]) -> Option<&'a T>

where B: Borrow<T>,

Available on crate feature std only.

Gets a random item that has followed items in the added data.

If items yields more than self.depth() items, only the first self.depth() items are considered. If items yields fewer than self.depth() items (potentially zero), those items are interpreted as the beginning of a generated sequence.

pub fn get_with_rng<'a, B, R>(&'a self, items: &[B], rng: R) -> Option<&'a T>

where B: Borrow<T>, R: Rng,

Like Self::get, but takes a custom random number generator.

Trait Implementations

impl<T: Clone, M: Map<T>> Clone for Chain<T, M>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Debug, M: Map<T>> Debug for Chain<T, M>

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

Formats the value using the given formatter.

impl<'de, T, M> Deserialize<'de> for Chain<T, M>

where T: Deserialize<'de>, M: Map<T>,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<T, M> Serialize for Chain<T, M>

where T: Serialize, M: Map<T>,

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

where __S: Serializer,

Serialize this value into the given Serde serializer.