silk/format

Decimal rendering and complete-text parsing shared by every integer module.

When to use

Prefer an integer module's toText and parse operations when the width is already known. Use unsignedText, signedText, unsignedValue, or signedValue when intentionally working through the widest integer representation.

Details

Rendering uses radix 10 and allocates an owned String. Parsing is allocation-free and reads the entire input: whitespace, a leading +, or trailing characters produce NotANumber, while syntactically valid values outside the destination range produce OutOfRange. Signed parsing accepts -0; unsigned parsing rejects any sign.

Examples

Parse and render one signed integer

import silk.allocator { Allocator }

import silk.effect { Effect }

import silk.format as Format

import silk.i64 as i64

import silk.result as Result

import silk.string as String

effect fn convert() -> i32
! Allocator.OutOfMemoryError {
  let mut allocator = Allocator.systemAllocatorProvider()
  let parsed = Format.signedValue("-42")
    |> Result.unwrapOr<i64, Format.ParseError>(0)
  let rendering = Format.signedText(parsed)
    |> Effect.provideMut<Allocator>(&mut allocator)
  let rendered = run rendering
  let text = String.view(&rendered)
  if text == "-42" {} else {
    return 0
  }
  return 0 - parsed
    |> i64.toI32
}

effect fn recover(error: Allocator.OutOfMemoryError) -> i32 {
  return 0
}

pub fn main() -> i32 {
  return run Effect.catchAll(convert(), recover)
}

Import as Format with import silk.format.

Public declarations: 17.

NotANumber

pub struct NotANumber

The byte offset where complete decimal parsing cannot continue.

Field offset

pub offset: usize

The offset where reading stopped. It can equal the byte length when a digit was required.

OutOfRange

pub struct OutOfRange

A well-formed decimal number whose value does not fit the requested type.

ParseError

pub struct ParseError

Why decimal text did not produce a value, narrowed with match.

Field reason

pub reason: silk/format.NotANumber | silk/format.OutOfRange

The reason the text was rejected.

unsignedText

pub effect fn unsignedText(value: u64) -> String ! OutOfMemoryError ? &mut Allocator

Renders an unsigned value as decimal text in freshly owned storage.

Details

The result contains ASCII decimal digits without a sign or leading zeroes. Zero produces "0".

signedText

pub effect fn signedText(value: i64) -> String ! OutOfMemoryError ? &mut Allocator

Renders a signed value as decimal text in freshly owned storage, with a leading - when negative.

Details

The result contains ASCII decimal digits without leading zeroes. Zero produces "0". The complete i64 range, including i64.MIN, is supported.

unsignedValue

pub fn unsignedValue(text: string) -> silk/result.Result<u64, silk/format.ParseError>

Reads complete decimal text as an unsigned value.

Details

Empty text, a leading sign, and any byte outside 0–9 are NotANumber at the offset that stopped the read. A value above u64.MAX is OutOfRange, detected before the overflow rather than after it.

signedValue

pub fn signedValue(text: string) -> silk/result.Result<i64, silk/format.ParseError>

Reads complete decimal text as a signed value, accepting one leading -.

Details

Digits accumulate negatively, so text naming i64.MIN reads like any other value. A leading + is not accepted. A value outside i64.MIN–i64.MAX is OutOfRange.

u8Value

pub fn u8Value(text: string) -> silk/result.Result<u8, silk/format.ParseError>

Reads complete decimal text as a u8, rejecting a value above u8.MAX.

u16Value

pub fn u16Value(text: string) -> silk/result.Result<u16, silk/format.ParseError>

Reads complete decimal text as a u16, rejecting a value above u16.MAX.

u32Value

pub fn u32Value(text: string) -> silk/result.Result<u32, silk/format.ParseError>

Reads complete decimal text as a u32, rejecting a value above u32.MAX.

u64Value

pub fn u64Value(text: string) -> silk/result.Result<u64, silk/format.ParseError>

Reads complete decimal text as a u64, rejecting a value above u64.MAX.

usizeValue

pub fn usizeValue(text: string) -> silk/result.Result<usize, silk/format.ParseError>

Reads complete decimal text as a usize, rejecting a value the target's pointer width cannot hold.

i8Value

pub fn i8Value(text: string) -> silk/result.Result<i8, silk/format.ParseError>

Reads complete decimal text as an i8, rejecting a value outside i8.MIN–i8.MAX.

i16Value

pub fn i16Value(text: string) -> silk/result.Result<i16, silk/format.ParseError>

Reads complete decimal text as an i16, rejecting a value outside i16.MIN–i16.MAX.

i32Value

pub fn i32Value(text: string) -> silk/result.Result<i32, silk/format.ParseError>

Reads complete decimal text as an i32, rejecting a value outside i32.MIN–i32.MAX.

i64Value

pub fn i64Value(text: string) -> silk/result.Result<i64, silk/format.ParseError>

Reads complete decimal text as an i64, rejecting a value outside i64.MIN–i64.MAX.

isizeValue

pub fn isizeValue(text: string) -> silk/result.Result<isize, silk/format.ParseError>

Reads complete decimal text as an isize, rejecting a value the target's pointer width cannot hold.