Scalar

Scalar :: # (opaque)

A Unicode scalar value: a code point other than a surrogate.

Scalar is sealed. The only public numeric constructor checks both the Unicode upper bound and the surrogate range. Every scalar decoded from a Roc Str therefore needs no repeated validity check in later algorithms.

from_u32 : U32 -> Try(Scalar, [InvalidScalar])

Construct a scalar after rejecting surrogates and values above U+10FFFF.

This is constant time, does not allocate, and is total for every U32.

from_code_point : CodePoint -> Try(Scalar, [Surrogate])

Validate a full-domain code point as a scalar.

This is constant time and does not allocate.

to_u32 : Scalar -> U32

Return the numeric Unicode scalar value.

This is constant time and does not allocate.

to_code_point : Scalar -> CodePoint

Convert this scalar to the corresponding full-domain code point.

This cannot fail because every scalar is in the code-point domain. It is constant time and does not allocate.

iter : Str -> Iter(LocatedScalar)

Iterate lazily over the scalars in a valid Roc Str.

Each result carries a half-open UTF-8 byte range and zero-based scalar index, both absolute from the beginning of source. The scan is O(B) in visited bytes, uses constant algorithmic state and stack, and creates no per-scalar byte or scalar list. Heap-backed strings provide a borrowed indexed byte view; an inline string may require one fixed byte-list materialization. Stopping iteration early leaves the suffix undecoded. The iterator retains source for its own lifetime; yielded scalars and integer ranges do not retain it.

utf8_len : Scalar -> U8

Return the number of bytes in this scalar's UTF-8 encoding.

This is constant time and does not allocate.

to_utf8 : Scalar -> List(U8)

Encode one scalar as a newly allocated list of one to four UTF-8 bytes.

The sealed input makes surrogate encoding impossible. Work and output size are constant. The returned list owns its bytes.

append_utf8 : List(U8), Scalar, U64 -> Try(List(U8), [OutputLimitExceeded({ limit : U64, required : U64 })])

Append one scalar's UTF-8 encoding to an existing byte list, provided the result does not exceed max_output_bytes.

This is O(1) excluding a possible reallocation/copy of bytes. It never emits a surrogate encoding. The caller-supplied, operation-specific limit and all length arithmetic are checked before reserve or append; failure leaves the caller's original list available.

to_str : Scalar -> Try(Str, [InternalEncodingFault])

Encode this scalar as an independently owned Str and validate the exact bytes before returning it.

Work and output size are constant. The implementation creates at most the fixed one-to-four-byte encoding and does not retain another source. InternalEncodingFault detects an implementation invariant violation; it is never a lossy replacement path.

is_eq : Scalar, Scalar -> Bool

Compare two scalars. This is constant time and does not allocate.

LocatedScalar : {
    scalar : Scalar,
    byte_range : ByteRange,
    scalar_index : U64,
}

A scalar and its absolute coordinates in the original logical source. byte_range is half-open and scalar_index is zero based.