Struct StringView 

pub struct StringView { /* private fields */ }

A 16 byte handle on a string.

The layout is a u32 length and 12 bytes of payload. For a string of 12 bytes or fewer the payload is the string, zero padded. For a longer one the first 4 bytes are the prefix and the last 8 are the offset into the column’s arena.

Arrow spends 4 of those 8 bytes on a buffer index and 4 on an offset within the buffer, because an Arrow array is a list of buffers. This column is one arena, so there is no buffer to name and the whole 8 bytes are the offset, which reads as one load rather than two and takes the reachable size of a column from 4 GiB to more than anything will ever put in one.

A view on its own cannot produce a long string, only a short one. That is deliberate: the arena lives in the StringColumn and the borrow checker is what stops a view from outliving it, rather than a rule somebody has to remember.

Implementations

impl StringView

pub const fn empty() -> Self

The view on the empty string.

What a copy loop writes for a position that resolved to nowhere, for the same reason a fixed width copy writes a zero there. The views are a parallel array to a validity mask, so a row that got skipped rather than filled would put every row after it at the wrong index.

pub fn inline(text: &str) -> Self

A view on a string that fits inline.

Panics

If the string is longer than INLINE_LIMIT. Callers that do not know the length go through StringColumn::push, which decides.

pub fn over(bytes: &[u8], offset: u64) -> Self

A view on bytes, whatever they are, wherever they turn out to live.

The one constructor that takes bytes rather than a &str, and the two callers want it for different reasons. A copy between two columns has bytes that were validated on the way into the first one and validating again would be work for nothing. A BLOB has bytes that were never text and are not going to become it. offset is where they are in the destination arena and is ignored for a string short enough to sit in the view.

It is public because the string view form of a vector is built from views a caller made, and a scan laying chunks over a page of strings is exactly the caller that has bytes and an offset into somebody else’s arena rather than a column to push into.

pub fn len(&self) -> usize

The length in bytes.

pub fn is_empty(&self) -> bool

Whether the string is empty.

pub fn is_inline(&self) -> bool

Whether the whole string is in the view.

pub fn prefix(&self) -> [u8; 4]

The first four bytes, zero padded.

This is the whole point of the representation. Two strings with different prefixes are different, and two strings with the same prefix are usually equal, so a filter on a string column resolves without touching the payload on almost every row.

pub fn inline_bytes(&self) -> Option<&[u8]>

The bytes, when the whole string is in the view.

A comparison wants bytes rather than a &str, because SQL’s string order is byte order and because Self::as_inline_str pays for a UTF-8 validation that a comparison has no use for. On a filter against a varchar column that validation is the whole cost of the row.

pub fn as_inline_str(&self) -> Option<&str>

The string, when it is short enough to be in the view.

pub fn bytes_in<'a>(&'a self, arena: &'a [u8]) -> Option<&'a [u8]>

The bytes, given the arena the long strings of this column live in.

A short string is in the view and the arena is not read at all, which is why this takes the arena rather than requiring one that has the string in it.

This exists because a view and the bytes it points at do not have to be held by the same object. StringColumn owns both, and the string view form of a vector holds the views itself and shares the arena with every other cut of the same page, so a cut of a varchar column is the views and nothing else. Both of them resolve a row the same way, and this is where that one way is written.

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

Whether these two views are definitely different, answered from the view alone.

A false here means the payloads have to be compared. A true means they do not, which on a filter against a selective literal is almost every row.

Trait Implementations

impl Clone for StringView

fn clone(&self) -> StringView

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for StringView

impl Debug for StringView

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

Formats the value using the given formatter.

impl Eq for StringView

impl Hash for StringView

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for StringView

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

Equality operator ==.

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

Inequality operator !=.

impl StructuralPartialEq for StringView