OsStringView structv0.1.0

pub struct OsStringView {
    pub units: OsUnit[..];
}

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

Fields

Constructors

OsStringView

pub func OsStringView() -> OsStringView

A view over nothing.

Returns: an empty view

Source

Associated functions

FromUnits

pub func FromUnits(units: OsUnit[..]) -> OsStringView

A view over units as they stand: no validation, because there is nothing to validate against.

Returns: a view over those units, which it does not copy

Source

Methods

Length

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

How many native units the view spans — bytes or code units, not characters.

Returns: how many units the value holds

Source

IsEmpty

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

Whether the view spans nothing.

Returns: whether it holds no units at all

Source

Units

pub func Units(self: &OsStringView) -> OsUnit[..]

The units themselves.

Returns: the units, borrowed

Source

Equals

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

Whether two views hold the same units. Unit equality and nothing smarter: no case folding, no normalization. Two names the filesystem treats as one are still two names here, because which names those are is the filesystem's opinion, not the string's.

Returns: whether both hold the same units in the same order

Source

ToText

pub func ToText(
    self: &OsStringView,
    allocator: Allocator
) -> String ! TextError

This native text as UTF-8, or nothing where it is not text. The fallible direction, and fallible for a different reason per platform: Unix bytes may simply not be UTF-8, and Windows units may hold an unpaired surrogate, which no UTF-8 sequence can spell. It fails with InvalidUtf8 for both, because both mean the same thing to the caller — this name is not text, and a program that must show it anyway shows it lossily by its own policy, knowingly.

Returns: the units converted to text, or a failure when they are not valid in it

Source

Implements Display

OsStringView conforms to Display.

WriteDisplay

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

Writes the name as text, with every native unit that is not text replaced by U+FFFD. Lossy, deliberately and only here. A name the system holds is not obliged to be text, and a program reporting which file it could not open still has to name it; U+FFFD is what the standard provides for exactly that. What this produces is for a reader, never for reopening the file — two different names can render alike, and Debug is the rendering that does not. Reports whatever the writer reported, and UnsupportedRequest for any style or precision. A precision is refused rather than applied because a truncated path is a different path, and may be one that exists.

Returns: success when the whole name was accepted

Source

Implements Debug

OsStringView conforms to Debug.

WriteDebug

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

Writes the name exactly, quoted, with every unit that is not text spelled as an escape. Nothing is lost: a Unix byte outside a well-formed sequence is written \x{nn} and a Windows code unit with no partner is written \u{xxxx}, so the native units can be read back off the output and two different names never render alike. The quote, the backslash and the control characters are escaped the way this repository escapes them everywhere else. Reports whatever the writer reported, and UnsupportedRequest for any style or precision.

Returns: success when the whole name was accepted

Source