Trait TextSource 

pub trait TextSource:
    Debug
    + Send
    + Sync {
    // Required methods
    fn len(&self) -> usize;
    fn bytes_at(&self, index: usize) -> Result<Option<&[u8]>>;
    fn footprint(&self) -> usize;

    // Provided methods
    fn is_empty(&self) -> bool { ... }
    fn bytes_len_at(&self, index: usize) -> Result<Option<usize>> { ... }
    fn ranks(&self) -> Option<usize> { ... }
    fn compare_rank(&self, rank: usize, wanted: &[u8]) -> Result<Ordering> { ... }
    fn code_at_rank(&self, rank: usize) -> Result<u32> { ... }
    fn equal(&self, other: &dyn TextSource) -> bool { ... }
}

Random access to immutable text kept by a storage reader.

Required Methods

fn len(&self) -> usize

Number of values available.

fn bytes_at(&self, index: usize) -> Result<Option<&[u8]>>

Bytes at one position, or no value when the position is outside the source.

fn footprint(&self) -> usize

Resident bytes retained by this source.

Provided Methods

fn is_empty(&self) -> bool

Whether this source has no values.

fn bytes_len_at(&self, index: usize) -> Result<Option<usize>>

Byte length at one position without requiring the payload when the source has an index.

fn ranks(&self) -> Option<usize>

How many ranks this source’s sorted value order has, when it has one.

A rank is a position in the values sorted by their bytes, so rank zero is the smallest value and rank ranks() - 1 is the largest. A storage format that keeps a dictionary for a whole column can afford to sort the distinct values once when it writes the file, and what that buys is a binary search where a reader that only knows the values are distinct has to ask every one of them whether it matches.

None means the source does not know its order, which is the honest answer for anything built in memory and for a file written before its format stored one. Nothing is allowed to depend on this for correctness, only for speed.

A source that answers with Some promises the ranks cover every value it has, and that compare_rank is consistent with an ordering in which the values are strictly increasing. Strictly, which is to say the values are distinct, because what reads this searches it, and a search of a run of equal values finds one of them rather than all of them. A source that holds the same value twice must answer None here even though it could sort itself perfectly well.

fn compare_rank(&self, rank: usize, wanted: &[u8]) -> Result<Ordering>

How the value at rank compares against wanted.

This is a method rather than a slice of positions the caller indexes because the answer is the only thing a search wants, and a source that knows that can answer most probes without reading a value at all. A file that stores the first few bytes of each value in rank order settles every probe from those bytes except the ones where two values start the same way, and the payload stays untouched. A caller handed positions instead would have to read a value per probe, which for a dictionary of half a million entries spread over thirty megabytes is a fresh block of the file every time.

Only called for a rank below ranks, so the default is the error a source that has no order should never be asked to produce.

fn code_at_rank(&self, rank: usize) -> Result<u32>

The position of the value at rank, which is what a search returns once it has found one.

Called about once per search rather than once per probe, so unlike compare_rank it is free to be the expensive one.

fn equal(&self, other: &dyn TextSource) -> bool

Whether another source presents the same values.

Trait Implementations

impl PartialEq for dyn TextSource

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

Equality operator ==.

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

Inequality operator !=.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors