🥮 mooncakes.io

btoi

a utility for converting ASCII bytes to integers

btoi
conversion
integer
bytes
utility
moon add justjavac/btoi@0.1.9
Download zip
Author
Version
0.1.9
License
MIT
Repository
Last updated
2 months ago
Downloads
35
README

#moonbit-btoi

Parse integers directly from ASCII byte arrays.

justjavac/btoi is a small MoonBit utility for reading signed and unsigned integers from Array[Byte] without converting through String first. It also supports radices 2..=36 and optional saturating overflow behavior.

#Install

moon add justjavac/btoi

#Quick Start

assert_eq(@btoi.btoi(b"-42".to_array()), Ok(-42))
assert_eq(@btoi.btou_radix(b"ff".to_array(), 16), Ok(255))
assert_eq(@btoi.btoi_from_string("+17"), Ok(17))

#Error Values

  • Empty: the input has no digits, including "", "+", and "-".
  • InvalidDigit: at least one byte is not valid for the chosen radix.
  • PosOverflow: the parsed value is too large for the target type.
  • NegOverflow: the parsed signed value is too small for Int.

#Main APIs

  • btoi / btou: parse base-10 bytes.
  • btoi_radix / btou_radix: parse bytes in radix 2..=36.
  • btoi_saturating / btou_saturating: base-10 parsing with saturating overflow.
  • btoi_from_string / btou_from_string: string convenience wrappers.

More examples live in the API doc comments in src/btoi.mbt.

#
ParseIntegerError

source
pub enum ParseIntegerError {
  Empty
  InvalidDigit
  PosOverflow
  NegOverflow
} derive(Eq, 
Debug)

Reports why parsing an integer from ASCII bytes failed.

Empty is returned when the input contains no digits, including sign-only inputs such as + and -. InvalidDigit means at least one byte is not a valid digit for the selected radix. PosOverflow and NegOverflow indicate that the parsed value does not fit in the destination integer type.

Examples

assert_eq(btoi(b"".to_array()), Err(Empty))
assert_eq(btoi(b"+".to_array()), Err(Empty))
assert_eq(btou_radix(b"ff".to_array(), 10), Err(InvalidDigit))

#
btoi

source
fn btoi(bytes : Array[Byte]) -> Result[Int, ParseIntegerError]

Parse a base-10 signed integer from ASCII bytes.

This is a convenience wrapper around btoi_radix(bytes, 10).

Examples

assert_eq(btoi(b"42".to_array()), Ok(42))
assert_eq(btoi(b"-42".to_array()), Ok(-42))
assert_eq(btoi(b"12x".to_array()), Err(InvalidDigit))

#
btoi_from_string

source
fn btoi_from_string(s : String) -> Result[Int, ParseIntegerError]

Parse a base-10 signed integer from a string.

The string is UTF-8 encoded and then parsed with btoi. This is useful when your input is already a String and you do not want to convert it manually.

Examples

assert_eq(btoi_from_string("-42"), Ok(-42))
assert_eq(btoi_from_string("42x"), Err(InvalidDigit))

#
btoi_radix

source
fn btoi_radix(bytes : Array[Byte], radix : Int) -> Result[Int, ParseIntegerError]

Parse a signed integer from ASCII bytes in the given radix.

The input may start with + or -. All remaining bytes must be valid digits for radix. Positive overflow returns PosOverflow, while negative overflow returns NegOverflow.

Panics

Panics when radix is outside 2..=36.

Examples

assert_eq(btoi_radix(b"7f".to_array(), 16), Ok(127))
assert_eq(btoi_radix(b"-101010".to_array(), 2), Ok(-42))
assert_eq(btoi_radix(b"-".to_array(), 10), Err(Empty))

#
btoi_radix_from_string

source
fn btoi_radix_from_string(s : String, radix : Int) -> Result[Int, ParseIntegerError]

Parse a signed integer from a string in the given radix.

This is the string-based counterpart of btoi_radix.

Examples

assert_eq(btoi_radix_from_string("-ff", 16), Ok(-255))
assert_eq(btoi_radix_from_string("+101", 2), Ok(5))

#
btoi_saturating

source
fn btoi_saturating(bytes : Array[Byte]) -> Result[Int, ParseIntegerError]

Parse a base-10 signed integer with saturating overflow handling.

This is a convenience wrapper around btoi_saturating_radix(bytes, 10).

Examples

assert_eq(btoi_saturating(b"-42".to_array()), Ok(-42))
assert_eq(btoi_saturating(b"-999999999999999999999999".to_array()), Ok(@int.MIN_VALUE))

#
btoi_saturating_radix

source
fn btoi_saturating_radix(bytes : Array[Byte], radix : Int) -> Result[Int, ParseIntegerError]

Parse a signed integer and saturate on overflow.

Positive overflow returns Int::max_value, while negative overflow returns Int::min_value. Empty input and invalid digits still produce the same errors as btoi_radix.

Panics

Panics when radix is outside 2..=36.

Examples

assert_eq(btoi_saturating_radix(b"-ff".to_array(), 16), Ok(-255))
assert_eq(btoi_saturating_radix(b"999999999999999999999999".to_array(), 10), Ok(@int.MAX_VALUE))
assert_eq(btoi_saturating_radix(b"-999999999999999999999999".to_array(), 10), Ok(@int.MIN_VALUE))

#
btou

source
fn btou(bytes : Array[Byte]) -> Result[UInt, ParseIntegerError]

Parse a base-10 unsigned integer from ASCII bytes.

This is a convenience wrapper around btou_radix(bytes, 10). The input must not contain a leading sign.

Examples

assert_eq(btou(b"42".to_array()), Ok(42))
assert_eq(btou(b"0007".to_array()), Ok(7))
assert_eq(btou(b"-1".to_array()), Err(InvalidDigit))

#
btou_from_string

source
fn btou_from_string(s : String) -> Result[UInt, ParseIntegerError]

Parse a base-10 unsigned integer from a string.

The accepted syntax and error behavior are the same as btou.

Examples

assert_eq(btou_from_string("42"), Ok(42))
assert_eq(btou_from_string("-42"), Err(InvalidDigit))

#
btou_radix

source
fn btou_radix(bytes : Array[Byte], radix : Int) -> Result[UInt, ParseIntegerError]

Parse an unsigned integer from ASCII bytes in the given radix.

The input must contain at least one digit and may only use ASCII digits or letters that are valid for radix. Signs are rejected. Overflow is reported as PosOverflow.

Panics

Panics when radix is outside 2..=36.

Examples

assert_eq(btou_radix(b"255".to_array(), 10), Ok(255))
assert_eq(btou_radix(b"ff".to_array(), 16), Ok(255))
assert_eq(btou_radix(b"+42".to_array(), 10), Err(InvalidDigit))

#
btou_radix_from_string

source
fn btou_radix_from_string(s : String, radix : Int) -> Result[UInt, ParseIntegerError]

Parse an unsigned integer from a string in the given radix.

This is the string-based counterpart of btou_radix.

Examples

assert_eq(btou_radix_from_string("ff", 16), Ok(255))
assert_eq(btou_radix_from_string("102", 2), Err(InvalidDigit))

#
btou_saturating

source
fn btou_saturating(bytes : Array[Byte]) -> Result[UInt, ParseIntegerError]

Parse a base-10 unsigned integer with saturating overflow handling.

This is a convenience wrapper around btou_saturating_radix(bytes, 10).

Examples

assert_eq(btou_saturating(b"42".to_array()), Ok(42))
assert_eq(btou_saturating(b"999999999999999999999999".to_array()), Ok(@uint.MAX_VALUE))

#
btou_saturating_radix

source
fn btou_saturating_radix(bytes : Array[Byte], radix : Int) -> Result[UInt, ParseIntegerError]

Parse an unsigned integer and saturate to UInt::max_value on overflow.

Empty input and invalid digits still return an error. Only arithmetic overflow changes behavior compared with btou_radix.

Panics

Panics when radix is outside 2..=36.

Examples

assert_eq(btou_saturating_radix(b"ff".to_array(), 16), Ok(255))
assert_eq(btou_saturating_radix(b"999999999999999999999999".to_array(), 10), Ok(@uint.MAX_VALUE))
assert_eq(btou_saturating_radix(b"xyz".to_array(), 10), Err(InvalidDigit))

Source Files

Powered by MoonBit

Site sourceReport issuePackagesBuild queueSkillsStatistics

© 2026 mooncakes.io