StringView structv0.1.0

pub struct StringView {
    // private fields
}

Copy, owning nothing. The bytes it names must outlive it.

Constructors

StringView

pub func StringView() -> StringView

A view over nothing. Cannot fail. Runs in constant time and allocates nothing.

Returns: an empty view

Source

Associated functions

FromBytes

pub func FromBytes(bytes: char8[..]) -> StringView?

A view over bytes when they are UTF-8, and none when they are not. bytes is borrowed and must outlive the view. This is the only way to make a view out of bytes whose provenance is unknown, and it costs one pass over them. Runs in time proportional to the length and allocates nothing.

Returns: a view over those bytes, or none when they are not valid UTF-8

Source

FromValidated

pub func FromValidated(bytes: char8[..]) -> StringView

A view over bytes the caller vouches are UTF-8. Skips the pass FromBytes makes, which is worth having when the bytes came from something that already guarantees it — another view, a String, a literal. The bytes must be well-formed UTF-8. Everything downstream assumes it, so bytes that are not produce wrong answers rather than errors: a scalar walk reads past a truncated sequence, and a cut lands mid-character.

Returns: a view over those bytes, taken as valid without checking

Source

Methods

StartsWith

pub func StartsWith(
    self: &StringView,
    prefix: StringView
) -> bool

Whether this view begins with prefix. Every view begins with the empty one. Runs in time proportional to the prefix and allocates nothing.

Returns: whether the text begins with prefix

Source

EndsWith

pub func EndsWith(
    self: &StringView,
    suffix: StringView
) -> bool

Whether this view ends with suffix.

Returns: whether the text ends with suffix

Source

IndexOf

pub func IndexOf(
    self: &StringView,
    needle: StringView
) -> uint?

The byte index where needle first occurs, or none. The empty needle occurs at the start, which is what makes IndexOf agree with StartsWith for it. Runs in time proportional to the product of the lengths in the worst case, which for the short needles this is used with is the same as proportional to the text.

Returns: the byte offset of the first occurrence, or none

Source

LastIndexOf

pub func LastIndexOf(
    self: &StringView,
    needle: StringView
) -> uint?

The byte index where needle last occurs, or none.

Returns: the byte offset of the last occurrence, or none

Source

Contains

pub func Contains(
    self: &StringView,
    needle: StringView
) -> bool

Whether needle occurs anywhere in this view.

Returns: whether needle occurs anywhere in the text

Source

TrimStart

pub func TrimStart(self: &StringView) -> StringView

This view without the ASCII whitespace at its start. Borrows: what comes back names the same bytes, further in.

Returns: the text without its leading ASCII spaces

Source

TrimEnd

pub func TrimEnd(self: &StringView) -> StringView

This view without the ASCII whitespace at its end.

Returns: the text without its trailing ASCII spaces

Source

Trim

pub func Trim(self: &StringView) -> StringView

This view without the ASCII whitespace at either end.

Returns: the text without its leading and trailing ASCII spaces

Source

Lines

pub func Lines(self: &StringView) -> LineIterator

A walk over the lines of this view, each without its line break. A line ends at \n or \r\n; a break at the very end does not start another, empty line, so "a\nb\n" has two lines and empty text has none. A lone \r is part of its line. self is borrowed and must outlive the walk.

Returns: a cursor over the lines

Source

Split

pub func Split(
    self: &StringView,
    separator: StringView
) -> SplitIterator

A walk over the parts of this view between occurrences of separator. self is borrowed and must outlive the walk, as must separator.

Returns: a cursor over the pieces between separators

Source

Length

pub func Length(self: &StringView) -> uint

How many bytes the view spans. Not how many characters: that is ScalarCount, and it costs a pass.

Returns: how many bytes the text occupies

Source

IsEmpty

pub func IsEmpty(self: &StringView) -> bool

Whether the view spans no bytes.

Returns: whether the text has no bytes

Source

Bytes

pub func Bytes(self: &StringView) -> char8[..]

The bytes themselves, for handing to something that reads bytes.

Returns: the text's bytes, borrowed

Source

ScalarCount

pub func ScalarCount(self: &StringView) -> uint

How many scalar values the view holds. Runs in time proportional to the length: there is no way to know without looking, which is why this is a method rather than a field.

Returns: how many Unicode scalar values the text holds, which is not its byte length

Source

IsBoundary

pub func IsBoundary(self: &StringView, index: uint) -> bool

Whether index is where a scalar value starts, and so a place this view may be cut.

Returns: whether index falls between two scalar values rather than inside one

Source

Part

pub func Part(
    self: &StringView,
    start: uint,
    end: uint
) -> StringView?

The part of this view from start up to end, or none when either is not a boundary or they are the wrong way round. Half-open, so Part(a, b) and Part(b, c) together are Part(a, c). Refusing a cut that is not on a boundary is the point: the alternative is a view whose first bytes are the tail of a character. Runs in constant time and allocates nothing.

Returns: the text between the two offsets, or none when either is not a boundary

Source

ScalarAt

pub func ScalarAt(self: &StringView, index: uint) -> char32?

The scalar value starting at index, or none when index is not a boundary inside the view.

Returns: the scalar value beginning at index, or none when it is not a boundary

Source

Equals

pub func Equals(
    self: &StringView,
    other: &StringView
) -> bool

pub func Equals(
    self: &StringView,
    other: StringView
) -> bool

Whether two views hold the same bytes. Byte equality, which for well-formed UTF-8 is scalar-by-scalar equality, since each scalar value has exactly one encoding. It is not equality after normalization, which is a different question and a different package.

Returns: whether both hold the same bytes

Source

Compare

pub func Compare(
    self: &StringView,
    other: &StringView
) -> Ordering

pub func Compare(
    self: &StringView,
    other: StringView
) -> Ordering

How this view orders against other, shortest first where one is a prefix of the other. Byte order, which for UTF-8 is also code point order: the encoding is built so that comparing bytes and comparing scalar values give the same answer. It is not alphabetical in any language.

Returns: how the two order byte by byte, which is code-point order for UTF-8

Source

Scalars

pub func Scalars(self: &StringView) -> ScalarIterator

A walk over this view's scalar values. self is borrowed and must outlive the walk.

Returns: a cursor over the text's scalar values

Source

Implements Display

StringView conforms to Display.

WriteDisplay

pub func WriteDisplay(
    self: &StringView,
    writer: &var TextWriter,
    spec: FormatSpec
) -> ! FormatError

Writes what this view spans, truncated to the spec's precision and padded to its width. Precision counts Unicode scalar values rather than bytes, and a cut lands on a character boundary by construction: the walk that counts them is the walk that finds where to stop. Reports whatever the writer reported, and UnsupportedRequest for a style, since text has none.

Returns: success when the view's text was accepted

Source

Implements Debug

StringView conforms to Debug.

WriteDebug

pub func WriteDebug(
    self: &StringView,
    writer: &var TextWriter,
    spec: FormatSpec
) -> ! FormatError

Writes what this view spans, quoted and escaped. The quotes sit outside the precision: what is kept is text, and the quotes say where it stops. Alignment is not applied, because padding a quoted rendering to a width would put the fill outside the quotes, where it would read as part of the surrounding text rather than as part of the value. Reports whatever the writer reported, stopping at the first refusal, so a failed opening quote is not followed by a body. Reports UnsupportedRequest for a style.

Returns: success when the quoted view was accepted

Source

Related

IsAsciiSpace

pub func IsAsciiSpace(byte: char8) -> bool

Whether byte is ASCII whitespace: space, tab, newline, carriage return, form feed or vertical tab. ASCII only, deliberately. Unicode calls a good many more characters whitespace, and which ones is a question for the tables; every one of them is multi-byte, so trimming by this rule never cuts a character in half.

Source

Parameters

Returns: whether the byte is one of ASCII's five space characters

SplitIterator

pub struct SplitIterator {
    // private fields
}

A walk over the parts of a view between occurrences of a separator. Every part is a borrow of the original, so splitting allocates nothing however many parts there are.

Source

Implements Iterator

SplitIterator conforms to Iterator.

Next

pub func Next(self: &var SplitIterator) -> StringView?

The next part, or none when the walk is over. Two adjacent separators give an empty part between them, and a separator at either end gives an empty part there — so the parts always number one more than the separators, and joining them back with the separator gives what was split. An empty separator gives the whole view as one part, since anything else would be an endless walk.

Returns: the next piece, or none at the end

Source

LineIterator

pub struct LineIterator {
    // private fields
}

A walk over the lines of a view, each without its line break. Every line is a borrow of the original, so walking allocates nothing.

Source

Implements Iterator

LineIterator conforms to Iterator.

Next

pub func Next(self: &var LineIterator) -> StringView?

The next line, without its \n or \r\n, or none after the last.

Returns: the next line, or none at the end

Source

ScalarIterator

pub struct ScalarIterator {
    // private fields
}

A walk over the scalar values of a view, first to last.

Source

Implements Iterator

ScalarIterator conforms to Iterator.

Next

pub func Next(self: &var ScalarIterator) -> char32?

The next scalar value, or none at the end. Bytes that are not well-formed end the walk rather than being reported: a view is validated when it is made, so reaching one means the bytes were vouched for and were not.

Returns: the next scalar value, or none at the end

Source