Struct fst::Set

pub struct Set(_);

Set is a lexicographically ordered set of byte strings.

A Set is constructed with the SetBuilder type. Alternatively, a Set can be constructed in memory from a lexicographically ordered iterator of byte strings (Set::from_iter).

A key feature of Set is that it can be serialized to disk compactly. Its underlying representation is built such that the Set can be memory mapped (Set::from_path) and searched without necessarily loading the entire set into memory.

It supports most common operations associated with sets, such as membership, union, intersection, subset/superset, etc. It also supports range queries and automata based searches (e.g. a regular expression).

Sets are represented by a finite state transducer where output values are always zero. As such, sets have the following invariants:

1. Once constructed, a Set can never be modified.
2. Sets must be constructed with lexicographically ordered byte sequences.

Methods

impl Set

pub unsafe fn from_path<P: AsRef<Path>>(path: P) -> Result<Self>

Opens a set stored at the given file path via a memory map.

The set must have been written with a compatible finite state transducer builder (SetBuilder qualifies). If the format is invalid or if there is a mismatch between the API version of this library and the set, then an error is returned.

This is unsafe because Rust programs cannot guarantee that memory backed by a memory mapped file won't be mutably aliased. It is up to the caller to enforce that the memory map is not modified while it is opened.

pub fn from_bytes(bytes: Vec<u8>) -> Result<Self>

Creates a set from its representation as a raw byte sequence.

Note that this operation is very cheap (no allocations and no copies).

The set must have been written with a compatible finite state transducer builder (SetBuilder qualifies). If the format is invalid or if there is a mismatch between the API version of this library and the set, then an error is returned.

pub fn from_static_slice(bytes: &'static [u8]) -> Result<Self>

Creates a set from its representation as a raw byte sequence.

This accepts a static byte slice, which may be useful if the FST data is embedded into the program.

Example

use fst::Set;

// File written from a build script using SetBuilder.
static FST: &[u8] = include_bytes!(concat!(env!("OUT_DIR"), "/set.fst"));

let set = Set::from_static_slice(FST).unwrap();

pub fn from_iter<T, I>(iter: I) -> Result<Self> where
    T: AsRef<[u8]>,
    I: IntoIterator<Item = T>, 

Create a Set from an iterator of lexicographically ordered byte strings.

If the iterator does not yield values in lexicographic order, then an error is returned.

Note that this is a convenience function to build a set in memory. To build a set that streams to an arbitrary io::Write, use SetBuilder.

pub fn contains<K: AsRef<[u8]>>(&self, key: K) -> bool

Tests the membership of a single key.

Example

use fst::Set;

let set = Set::from_iter(&["a", "b", "c"]).unwrap();

assert_eq!(set.contains("b"), true);
assert_eq!(set.contains("z"), false);

pub fn stream(&self) -> Stream

Return a lexicographically ordered stream of all keys in this set.

While this is a stream, it does require heap space proportional to the longest key in the set.

If the set is memory mapped, then no further heap space is needed. Note though that your operating system may fill your page cache (which will cause the resident memory usage of the process to go up correspondingly).

Example

Since streams are not iterators, the traditional for loop cannot be used. while let is useful instead:

use fst::{IntoStreamer, Streamer, Set};

let set = Set::from_iter(&["a", "b", "c"]).unwrap();
let mut stream = set.stream();

let mut keys = vec![];
while let Some(key) = stream.next() {
    keys.push(key.to_vec());
}
assert_eq!(keys, vec![b"a", b"b", b"c"]);

pub fn range(&self) -> StreamBuilder

Return a builder for range queries.

A range query returns a subset of keys in this set in a range given in lexicographic order.

Memory requirements are the same as described on Set::stream. Notably, only the keys in the range are read; keys outside the range are not.

Example

Returns only the keys in the range given.

use fst::{IntoStreamer, Streamer, Set};

let set = Set::from_iter(&["a", "b", "c", "d", "e"]).unwrap();
let mut stream = set.range().ge("b").lt("e").into_stream();

let mut keys = vec![];
while let Some(key) = stream.next() {
    keys.push(key.to_vec());
}
assert_eq!(keys, vec![b"b", b"c", b"d"]);

pub fn search<A: Automaton>(&self, aut: A) -> StreamBuilder<A>

Executes an automaton on the keys of this set.

Note that this returns a StreamBuilder, which can be used to add a range query to the search (see the range method).

Memory requirements are the same as described on Set::stream.

Example

An implementation of regular expressions for Automaton is available in the fst-regex crate, which can be used to search sets.

extern crate fst;
extern crate fst_regex;

use std::error::Error;

use fst::{IntoStreamer, Streamer, Set};
use fst_regex::Regex;

fn example() -> Result<(), Box<Error>> {
    let set = Set::from_iter(&[
        "foo", "foo1", "foo2", "foo3", "foobar",
    ]).unwrap();

    let re = Regex::new("f[a-z]+3?").unwrap();
    let mut stream = set.search(&re).into_stream();

    let mut keys = vec![];
    while let Some(key) = stream.next() {
        keys.push(key.to_vec());
    }
    assert_eq!(keys, vec![
        "foo".as_bytes(), "foo3".as_bytes(), "foobar".as_bytes(),
    ]);

    Ok(())
}

pub fn len(&self) -> usize

Returns the number of elements in this set.

pub fn is_empty(&self) -> bool

Returns true if and only if this set is empty.

pub fn op(&self) -> OpBuilder

Creates a new set operation with this set added to it.

The OpBuilder type can be used to add additional set streams and perform set operations like union, intersection, difference and symmetric difference.

Example

use fst::{IntoStreamer, Streamer, Set};

let set1 = Set::from_iter(&["a", "b", "c"]).unwrap();
let set2 = Set::from_iter(&["a", "y", "z"]).unwrap();

let mut union = set1.op().add(&set2).union();

let mut keys = vec![];
while let Some(key) = union.next() {
    keys.push(key.to_vec());
}
assert_eq!(keys, vec![b"a", b"b", b"c", b"y", b"z"]);

pub fn is_disjoint<'f, I, S>(&self, stream: I) -> bool where
    I: for<'a> IntoStreamer<'a, Into = S, Item = &'a [u8]>,
    S: 'f + for<'a> Streamer<'a, Item = &'a [u8]>, 

Returns true if and only if the self set is disjoint with the set stream.

stream must be a lexicographically ordered sequence of byte strings.

Example

use fst::{IntoStreamer, Streamer, Set};

let set1 = Set::from_iter(&["a", "b", "c"]).unwrap();
let set2 = Set::from_iter(&["x", "y", "z"]).unwrap();

assert_eq!(set1.is_disjoint(&set2), true);

let set3 = Set::from_iter(&["a", "c"]).unwrap();

assert_eq!(set1.is_disjoint(&set3), false);

pub fn is_subset<'f, I, S>(&self, stream: I) -> bool where
    I: for<'a> IntoStreamer<'a, Into = S, Item = &'a [u8]>,
    S: 'f + for<'a> Streamer<'a, Item = &'a [u8]>, 

Returns true if and only if the self set is a subset of stream.

stream must be a lexicographically ordered sequence of byte strings.

Example

use fst::Set;

let set1 = Set::from_iter(&["a", "b", "c"]).unwrap();
let set2 = Set::from_iter(&["x", "y", "z"]).unwrap();

assert_eq!(set1.is_subset(&set2), false);

let set3 = Set::from_iter(&["a", "c"]).unwrap();

assert_eq!(set1.is_subset(&set3), false);
assert_eq!(set3.is_subset(&set1), true);

pub fn is_superset<'f, I, S>(&self, stream: I) -> bool where
    I: for<'a> IntoStreamer<'a, Into = S, Item = &'a [u8]>,
    S: 'f + for<'a> Streamer<'a, Item = &'a [u8]>, 

Returns true if and only if the self set is a superset of stream.

stream must be a lexicographically ordered sequence of byte strings.

Example

use fst::Set;

let set1 = Set::from_iter(&["a", "b", "c"]).unwrap();
let set2 = Set::from_iter(&["x", "y", "z"]).unwrap();

assert_eq!(set1.is_superset(&set2), false);

let set3 = Set::from_iter(&["a", "c"]).unwrap();

assert_eq!(set1.is_superset(&set3), true);
assert_eq!(set3.is_superset(&set1), false);

pub fn as_fst(&self) -> &Fst

Returns a reference to the underlying raw finite state transducer.

Trait Implementations

impl<'s, 'a> IntoStreamer<'a> for &'s Set

type Item = &'a [u8]

The type of the item emitted by the stream.

type Into = Stream<'s>

The type of the stream to be constructed.

fn into_stream(self) -> Self::Into

Construct a stream from Self.

impl From<Fst> for Set

fn from(fst: Fst) -> Set

Performs the conversion.

impl Default for Set

fn default() -> Set

Returns the "default value" for a type.

impl AsRef<Fst> for Set

Returns the underlying finite state transducer.

fn as_ref(&self) -> &Fst

Performs the conversion.

impl Debug for Set

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

Formats the value using the given formatter.