FormatError variantv0.1.0

Why a formatting operation did not produce the text it was asked for.

pub variant FormatError {
    InvalidSpecification(uint),
    UnsupportedRequest,
    ArgumentCountMismatch(uint, uint),
    InsufficientCapacity,
    ValueOutOfRange,
    TextFailure(TextFailureKind),
    WriterFailure
}

Failure-only: every case is a failure, and success is the other channel of the ! FormatError or T ! FormatError that reports it rather than a case here. Which case arises says who must fix it, so the categories are not interchangeable and a writer may not invent the ones that belong to the parser or the value. Copy, and cheap to return: the widest payload is a pair of counts.

Cases

Name	Description
`InvalidSpecification(uint)`	The pattern or specification was malformed, at the zero-based UTF-8 byte offset carried here. The offset is into the text that was being parsed, and end-of-input is that text's length.
`UnsupportedRequest`	The style or flag asked for is not one this value supports. A precision on a boolean, or a base on a string, arrives here rather than being ignored.
`ArgumentCountMismatch(uint, uint)`	A pattern's placeholders and the arguments supplied did not agree: expected first, supplied second.
`InsufficientCapacity`	The destination is bounded and cannot accept the whole write. Nothing partial is left behind by a writer that promises otherwise; see the writer's own contract.
`ValueOutOfRange`	The value is valid but cannot be represented in the form requested, such as a timestamp outside the calendar range a format covers.
`TextFailure(TextFailureKind)`	Text handling failed, for the reason carried. This is where an allocation failure or rejected UTF-8 arrives.
`WriterFailure`	The destination failed on its own terms. Its details stay with the adapter that produced it, which is the only thing that knows what a failure of that destination means.

Methods

`IsWriterFailure`

pub func IsWriterFailure(self: &FormatError) -> bool

Whether this failure came from the destination rather than from the text or the request. Useful at a boundary that must tell an unusable destination apart from a request that was wrong: the first is worth retrying elsewhere and the second never is. Borrows the error and leaves it untouched. Cannot fail; runs in constant time and allocates nothing.

Returns: true for WriterFailure, false for every other case

Source

Implements Display

FormatError conforms to Display.

`WriteDisplay`

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

Writes the description of why a value could not be turned into text. The position an InvalidSpecification carries, and the two counts an ArgumentCountMismatch carries, are deliberately absent: they are what Debug adds. A description says what happened, and a reader who needs the byte offset is reading a log rather than a message. Reports whatever the writer reported, and UnsupportedRequest for any style or precision.

Name	Type	Description
`writer`	`&var TextWriter`	the destination
`spec`	`FormatSpec`	what the placeholder asked for

Returns: success when the whole description was accepted

Source

Implements Debug

FormatError conforms to Debug.

`WriteDebug`

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

Names the case and the payload it carries: FormatError::InvalidSpecification(12). This is where the position and the counts appear, since they are what makes one occurrence of a failure different from another and what a log is read for. Reports whatever the writer reported, and UnsupportedRequest for any style or precision.

Name	Type	Description
`writer`	`&var TextWriter`	the destination
`spec`	`FormatSpec`	what the placeholder asked for

Returns: success when the whole rendering was accepted

Source

`TextFailureKind`

pub variant TextFailureKind {
    OutOfMemory,
    LengthOverflow,
    InvalidUtf8,
    NotABoundary
}

The ways text handling fails, with no case for success. A deliberate narrowing of TextError: the same four failures, minus its None. That absence is the point, since this is what a FormatError::TextFailure carries and a failure payload must not be able to say "nothing went wrong". Copy, carrying no payload and owning nothing.

Source

Cases

Name	Description
`OutOfMemory`	The allocator could not supply the storage a write needed.
`LengthOverflow`	A length or offset computation passed what a `uint` can hold.
`InvalidUtf8`	The bytes offered were not well-formed UTF-8.
`NotABoundary`	A byte offset that is not where a character starts, and so not a place text may be cut.

Implements Display

TextFailureKind conforms to Display.

`WriteDisplay`

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

The same description TextError gives the same failure, which is the point of sharing one writer. Reports whatever the writer reported, and UnsupportedRequest for any style or precision.

Name	Type	Description
`writer`	`&var TextWriter`	the destination
`spec`	`FormatSpec`	what the placeholder asked for

Returns: success when the whole description was accepted

Source

Implements Debug

TextFailureKind conforms to Debug.

`WriteDebug`

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

Names the case, qualified by its type: TextFailureKind::InvalidUtf8. Reports whatever the writer reported, and UnsupportedRequest for any style or precision.

Name	Type	Description
`writer`	`&var TextWriter`	the destination
`spec`	`FormatSpec`	what the placeholder asked for

Returns: success when the whole name was accepted

Source

`TextFailureOf`

pub func TextFailureOf(error: TextError) -> TextFailureKind

The failure-only kind corresponding to error.

Source

Parameters

Name	Type	Description
`error`	`TextError`	the text status to narrow, which must be a failure

Returns: the matching failure kind

`FromTextError`

pub func FromTextError(error: TextError) -> FormatError

error translated across the boundary between this package's status convention and the formatting protocol. This is the only sanctioned crossing: every text failure becomes a TextFailure carrying the reason. It is the mapper a formatting operation hands a text operation's failure to, as in builder.Append(view)? else (e => FromTextError(e)).

Source

Parameters

Name	Type	Description
`error`	`TextError`	why the storage or validation operation failed

Returns: the matching formatting failure

CString

Text carrying the terminator C expects, in storage of its own.

FormatSpec

Everything a placeholder asked for.

Edit this page on GitHub