a utility for converting ASCII bytes to integers

btoi

conversion

integer

bytes

utility

Download zip

Author

justjavac

Version

0.1.10

License

MIT

Repository

github.com/justjavac/moonbit-btoi

Last updated

8 days ago

Downloads

#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, @moonbitlang/core/debug.Debug
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))

ParseIntegerError::equal

source

fn ParseIntegerError::equal(ParseIntegerError, ParseIntegerError) -> Bool

automatically derived

ParseIntegerError::not_equal

source

fn ParseIntegerError::not_equal(x : ParseIntegerError, y : ParseIntegerError) -> Bool

ParseIntegerError::to_repr

source

fn ParseIntegerError::to_repr(ParseIntegerError) -> @moonbitlang/core/debug.Repr
Repr

automatically derived

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

btoi.mbt

Site source Report issue Packages Build queue Skills Statistics

btoi

#moonbit-btoi

#Install

#Quick Start

#Error Values

#Main APIs

#ParseIntegerError

Examples

#ParseIntegerError::equal

#ParseIntegerError::not_equal

#ParseIntegerError::to_repr

#btoi

Examples

#btoi_from_string

Examples

#btoi_radix

Panics

Examples

#btoi_radix_from_string

Examples

#btoi_saturating

Examples

#btoi_saturating_radix

Panics

Examples

#btou

Examples

#btou_from_string

Examples

#btou_radix

Panics

Examples

#btou_radix_from_string

Examples

#btou_saturating

Examples

#btou_saturating_radix

Panics

Examples

Source Files

ParseIntegerError

ParseIntegerError::equal

ParseIntegerError::not_equal

ParseIntegerError::to_repr

btoi

btoi_from_string

btoi_radix

btoi_radix_from_string

btoi_saturating

btoi_saturating_radix

btou

btou_from_string

btou_radix

btou_radix_from_string

btou_saturating

btou_saturating_radix