Fast decimal formatting for signed and unsigned integers

itoa

conversion

integer

bytes

utility

moon add justjavac/itoa@0.2.4

Download zip

Author

justjavac

Version

0.2.4

License

MIT

Repository

github.com/justjavac/moonbit-itoa

Last updated

2 months ago

Downloads

README

#justjavac/itoa

Small and fast decimal formatting for Int, UInt, Int64, and UInt64.

#Install

moon add justjavac/itoa

#Quick Start

///|
test "format signed and unsigned values" {
  let buffer = @itoa.Buffer::new()
  inspect(buffer.format_i32(-42), content="-42")
  inspect(
    buffer.format_u64(18446744073709551615UL),
    content="18446744073709551615",
  )
}

#Reuse One Buffer

Create one Buffer and reuse it across calls when formatting multiple values.

///|
test "reuse the same buffer" {
  let buffer = @itoa.Buffer::new()
  inspect(buffer.format_u32(7U), content="7")
  inspect(buffer.format_i64(-9000000000000L), content="-9000000000000")
}

#Low-level Helper

udivmod_1e19 splits a UInt64 into a high chunk and a low 19-digit remainder.

///|
test "split a large unsigned integer" {
  let (quot, rem) = @itoa.udivmod_1e19(18446744073709551615UL)
  inspect(quot, content="1")
  inspect(rem, content="8446744073709551615")
}

#
Buffer

source

pub struct Buffer {
  bytes : FixedArray[Byte]
}

Reusable scratch space for formatting integers as decimal strings.

A Buffer keeps an internal byte array large enough for every supported integer type, so repeated formatting calls can reuse the same working memory instead of allocating a fresh temporary buffer each time.

Example

test "buffer can be reused" {
  let buffer = Buffer::new()
  inspect(buffer.format_i32(-42), content="-42")
  inspect(buffer.format_u64(9000UL), content="9000")
}

#
Buffer::format_i32

source

fn Buffer::format_i32(self : Buffer, i : Int) -> String

Format an Int as a base-10 string.

The conversion writes digits into the buffer's reusable scratch space and returns a freshly allocated String containing the final decimal text.

Example

test "format signed 32-bit value" {
  let buffer = Buffer::new()
  inspect(buffer.format_i32(-2147483648), content="-2147483648")
}

#
Buffer::format_i64

source

fn Buffer::format_i64(self : Buffer, i : Int64) -> String

Format an Int64 as a base-10 string.

Negative values are handled by emitting the sign separately and then using the fast digit-pair algorithm for the remaining absolute value.

Example

test "format signed 64-bit value" {
  let buffer = Buffer::new()
  inspect(
    buffer.format_i64(-1234567890123456789L),
    content="-1234567890123456789",
  )
}

#
Buffer::format_u32

source

fn Buffer::format_u32(self : Buffer, i : UInt) -> String

Format a UInt as a base-10 string.

This method is optimized for unsigned 32-bit values and avoids any sign handling while still reusing the same internal working buffer.

Example

test "format unsigned 32-bit value" {
  let buffer = Buffer::new()
  inspect(buffer.format_u32(4294967295U), content="4294967295")
}

#
Buffer::format_u64

source

fn Buffer::format_u64(self : Buffer, i : UInt64) -> String

Format a UInt64 as a base-10 string.

This is the widest integer conversion supported by the package and can render values all the way up to 18446744073709551615.

Example

test "format unsigned 64-bit value" {
  let buffer = Buffer::new()
  inspect(
    buffer.format_u64(18446744073709551615UL),
    content="18446744073709551615",
  )
}

#
Buffer::new

source

fn Buffer::new() -> Buffer

Create a reusable decimal formatting buffer.

The returned buffer is large enough for every integer type supported by this package, including UInt64 and the negative boundary of Int64.

Example

test "create buffer" {
  let buffer = Buffer::new()
  inspect(buffer.format_u32(7U), content="7")
}

#
udivmod_1e19

source

fn udivmod_1e19(n : UInt64) -> (UInt64, UInt64)

Divide n by 10^19 and return the quotient and remainder.

This helper is useful when splitting a very large decimal value into a high chunk and a low 19-digit remainder.

Example

test "split by 1e19" {
  let (quot, rem) = udivmod_1e19(18446744073709551615UL)
  inspect(quot, content="1")
  inspect(rem, content="8446744073709551615")
}