String structv0.1.0

pub struct String {
    pub data: *var char8;
    pub length: uint;
    // private fields
}

Copyable with value semantics: each copy owns an independent block and gives it back when it dies.

Fields

Constructors

String

pub func String(allocator: Allocator) -> String

Text of no length, which has allocated nothing. allocator is borrowed for the call and kept, so an empty string can still grow into one that allocates. Cannot fail. Runs in constant time and allocates nothing.

Returns: an empty string that has taken no storage yet

Source

Associated functions

FromValidated

pub func FromValidated(
    allocator: Allocator,
    bytes: char8[..]
) -> String ! TextError

A copy of bytes the caller vouches are UTF-8. Skips the pass FromBytes makes, which is what to use when the bytes came from something that already guarantees it — another string, a view, this package's own output. Fails with OutOfMemory when the copy cannot be made. The bytes must be well-formed UTF-8. Everything downstream assumes it, so bytes that are not produce wrong answers rather than errors.

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

Source

FromBytes

pub func FromBytes(
    allocator: Allocator,
    bytes: char8[..]
) -> String ! TextError

A copy of bytes as text, or why it could not be made. bytes is borrowed and copied, so what it names stays the caller's. It fails with InvalidUtf8 when the bytes are not text and OutOfMemory when the copy cannot be made. Runs in time proportional to the length — one pass to check, one to copy — and allocates once.

Returns: a string over those bytes, or an empty one when they are not valid UTF-8

Source

FromView

pub func FromView(
    allocator: Allocator,
    view: StringView
) -> String ! TextError

A copy of what view spans. The view was checked when it was made, so this copies without checking again.

Returns: a copy of that text this string owns

Source

Methods

Length

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

How many bytes the text 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: &String) -> bool

Whether the text spans no bytes.

Returns: whether the text has no bytes

Source

Bytes

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

The bytes themselves, borrowed.

Returns: the text's bytes, borrowed

Source

View

pub func View(self: &String) -> StringView

A view over this string, which is what to pass to anything that only reads. Copies nothing. The view borrows this string and must not outlive it.

Returns: a borrowed view of the text

Source

ScalarCount

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

How many characters the text holds.

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

Source

IsBoundary

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

Whether index is where a character starts, and so a place the text may be cut.

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

Source

Part

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

A borrowed view of the part from start up to end, or none when either end is not a boundary. Borrows rather than copying, since a part of a string is bytes the string already owns. Substring is what makes an owning copy.

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

Source

Substring

pub func Substring(
    self: &String,
    start: uint,
    end: uint
) -> String ! TextError

An owning copy of the part from start up to end. Fails with NotABoundary when either end would cut a character in half.

Returns: an owned copy of that range, or why it could not be made

Source

Clone

pub func Clone(self: &String) -> String ! TextError

An independent copy, with a block of its own from the same allocator.

Returns: an independent copy

Source

Equals

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

Whether two strings hold the same bytes.

Returns: whether both hold the same bytes

Source

Compare

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

How this string orders against other, by bytes, which for UTF-8 is also by code point.

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

Source

Clear

pub func Clear(self: &var String)

Gives the block back and leaves text of no length behind. Rarely needed: a string releases itself when it dies. This is for releasing one early, and is safe to call twice because what it leaves behind owns nothing.

Source

ReplaceWith

pub func ReplaceWith(self: &var String, value: String)

Replaces this string with value, transferring its block after releasing the old one. A fresh value transfers directly. Passing a named string first invokes its deep copy, so the caller keeps an independent original.

Source

Operators

=

pub func =(self: &var String, other: &String)

Deep-copies other into independent storage from the same allocator. The special copy operation cannot report allocation failure, so it terminates on exhaustion. Use Clone when failure must be handled. The source remains valid and unchanged.

Source

Implements Display

String conforms to Display.

WriteDisplay

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

Writes this string's bytes. Reports whatever the writer reported, and UnsupportedRequest for a style, since text has none.

Returns: success when the string's text was accepted

Source

Implements Debug

String conforms to Debug.

WriteDebug

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

Writes this string quoted and escaped. Reports whatever the writer reported, and UnsupportedRequest for a style.

Returns: success when the quoted string was accepted

Source

Destructor

func ~String(self: &var String)

Gives the block back. Runs when the string dies. Copies have independent blocks, so each destructor releases exactly its own.

Source