#Builtin Package Documentation
This package provides the core built-in types, functions, and utilities that are fundamental to MoonBit programming. It includes basic data structures, iterators, assertions, and core language features.
#Core Types and Functions
#Assertions and Testing
MoonBit provides built-in assertion functions for testing:
///|
test "assertions" {
// Basic equality assertion
@test.assert_eq(1 + 1, 2)
@test.assert_eq("hello", "hello")
// Boolean assertions
assert_true(5 > 3)
assert_false(2 > 5)
// Inequality assertion
@test.assert_not_eq(1, 2)
@test.assert_not_eq("foo", "bar")
}#Inspect Function
The inspect function is used for testing and debugging:
///|
test "inspect usage" {
let value = 42
inspect(value, content="42")
let list = [1, 2, 3]
debug_inspect(list, content="[1, 2, 3]")
let result : Result[Int, String] = Ok(100)
debug_inspect(result, content="Ok(100)")
}#Result Type
The Result[T, E] type represents operations that can succeed or fail:
///|
test "result type" {
fn divide(a : Int, b : Int) -> Result[Int, String] {
if b == 0 {
Err("Division by zero")
} else {
Ok(a / b)
}
}
// Success case
let result1 = divide(10, 2)
debug_inspect(result1, content="Ok(5)")
// Error case
let result2 = divide(10, 0)
debug_inspect(result2, content="Err(\"Division by zero\")")
// Pattern matching on Result
match result1 {
Ok(value) => inspect(value, content="5")
Err(_) => inspect(false, content="true")
}
}#Option Type
The Option[T] type represents values that may or may not exist:
///|
test "option type" {
fn find_first_even(numbers : Array[Int]) -> Int? {
for num in numbers {
if num % 2 == 0 {
return Some(num)
}
}
None
}
// Found case
let result1 = find_first_even([1, 3, 4, 5])
debug_inspect(result1, content="Some(4)")
// Not found case
let result2 = find_first_even([1, 3, 5])
debug_inspect(result2, content="None")
// Pattern matching on Option
match result1 {
Some(value) => inspect(value, content="4")
None => inspect(false, content="true")
}
}#Iterator Type
The Iter[T] type provides lazy iteration over sequences:
///|
test "iterators" {
// Create iterator from array
let numbers = [1, 2, 3, 4, 5]
let iter = numbers.iter()
// Collect back to array
let collected = iter.collect()
debug_inspect(collected, content="[1, 2, 3, 4, 5]")
// Map transformation
let doubled = numbers.iter().map(fn(x) { x * 2 }).collect()
debug_inspect(doubled, content="[2, 4, 6, 8, 10]")
// Filter elements
let evens = numbers.iter().filter(fn(x) { x % 2 == 0 }).collect()
debug_inspect(evens, content="[2, 4]")
// Fold (reduce) operation
let sum = numbers.iter().fold(init=0, fn(acc, x) { acc + x })
inspect(sum, content="15")
}#Array and FixedArray
Built-in array types for storing collections:
///|
test "arrays" {
// Dynamic arrays
let arr1 = Array()
arr1.push(1)
arr1.push(2)
arr1.push(3)
debug_inspect(arr1, content="[1, 2, 3]")
// Array from literal
let arr2 = [10, 20, 30]
debug_inspect(arr2, content="[10, 20, 30]")
// Array operations
let length = arr2.length()
inspect(length, content="3")
let first = arr2[0]
inspect(first, content="10")
}Fixed-size array for storing collections of constant size:
///|
test "fixed arrays" {
// FixedArray from literal
let fixed_arr : FixedArray[Int] = [10, 20, 30]
debug_inspect(
fixed_arr,
content=(
#|<FixedArray: [10, 20, 30]>
),
)
// FixedArray operations
let length = fixed_arr.length()
inspect(length, content="3")
let first = fixed_arr[0]
inspect(first, content="10")
}#Views (Zero-Copy Slices)
Each owning container has a matching view type created with the a[start:end]
slice syntax. A view is a small record holding a reference to the shared
storage plus its window bounds, so slicing never copies the elements:
direction: right
owners: "Owning containers" {
arr: "Array[T] / FixedArray[T] / ReadOnlyArray[T]"
bytes: "Bytes"
str: "String"
}
views: "Zero-copy views (shared storage + window bounds)" {
arrview: "ArrayView[T]"
bytesview: "BytesView"
strview: "StringView"
}
owners.arr -> views.arrview: "a[start:end]"
owners.bytes -> views.bytesview: "b[start:end]"
owners.str -> views.strview: "s[start:end]"Views are ideal for rest patterns ([first, .. rest]) and for passing
sub-sequences without allocation; functions taking a view also accept the
owning container through implicit conversion. Note that the s[start:end]
slice syntax on String panics when a boundary would split a UTF-16
surrogate pair:
///|
test "views are zero copy" {
let arr = [1, 2, 3, 4, 5]
let view = arr[1:4]
@test.assert_eq(view.length(), 3)
@test.assert_eq(view[0], 2)
view is [first, .. rest]
@test.assert_eq(first, 2)
@test.assert_eq(rest.length(), 2)
}#String Operations
Basic string functionality:
///|
test "strings" {
let text = "Hello, World!"
// String length
let len = text.length()
inspect(len, content="13")
// String concatenation
let greeting = "Hello" + ", " + "World!"
inspect(greeting, content="Hello, World!")
// String comparison
let equal = "test" == "test"
inspect(equal, content="true")
}#StringBuilder
Efficient string building:
///|
test "string builder" {
let builder = StringBuilder()
builder.write_string("Hello")
builder.write_string(", ")
builder.write_string("World!")
let result = builder.to_string()
inspect(result, content="Hello, World!")
}#JSON Support
Basic JSON operations:
///|
test "json" {
// JSON values
let json_null = null
@debug.debug_inspect(json_null, content="Null")
let json_bool = true.to_json()
@debug.debug_inspect(json_bool, content="True")
let json_number = (42 : Int).to_json()
@debug.debug_inspect(json_number, content="Number(42)")
let json_string = "hello".to_json()
@debug.debug_inspect(
json_string,
content=(
#|String("hello")
),
)
}#Comparison Operations
Built-in comparison operators:
///|
test "comparisons" {
// Equality
inspect(5 == 5, content="true")
inspect(5 != 3, content="true")
// Ordering
inspect(3 < 5, content="true")
inspect(5 > 3, content="true")
inspect(5 >= 5, content="true")
inspect(3 <= 5, content="true")
// String comparison
inspect("apple" < "banana", content="true")
inspect("hello" == "hello", content="true")
}#Utility Functions
Helpful utility functions:
///|
test "utilities" {
// Identity and ignore
let value = 42
ignore(value) // Discards the value
// Boolean negation
let result = !false
inspect(result, content="true")
// Physical equality (reference equality)
let arr1 = [1, 2, 3]
let arr2 = [1, 2, 3]
let same_ref = arr1
inspect(physical_equal(arr1, arr2), content="false") // Different objects
inspect(physical_equal(arr1, same_ref), content="true") // Same reference
}#Error Handling
Basic error handling with panic and abort:
///|
test "error handling" {
// This would panic in a real scenario, but we demonstrate the concept
fn safe_divide(a : Int, b : Int) -> Int {
if b == 0 {
// In real code: panic()
// For testing, we return a default value
0
} else {
a / b
}
}
let result = safe_divide(10, 2)
inspect(result, content="5")
let safe_result = safe_divide(10, 0)
inspect(safe_result, content="0")
}#Best Practices
- Use assertions liberally in tests: They help catch bugs early and document expected behavior
- Prefer Result over exceptions: For recoverable errors, use Result[T, E] instead of panicking
- Use Option for nullable values: Instead of null pointers, use Option[T]
- Leverage iterators for data processing: They provide composable and efficient data transformations
- Use StringBuilder for string concatenation: More efficient than repeated string concatenation
- Pattern match on Result and Option: Handle both success and failure cases explicitly
#Performance Notes
- Arrays have O(1) access and O(1) amortized append
- Iterators are lazy and don't allocate intermediate collections
- StringBuilder is more efficient than string concatenation for building large strings
- Physical equality is faster than structural equality but should be used carefully
Add
pub(open) trait Add {
fn add(Self, Self) -> Self
}types implementing this trait can use the + operator
fn add(self : Byte, that : Byte) -> ByteAdds two Byte values together and returns the result as a Byte.
Parameters:
- byte1 : The first Byte value to be added.
- byte2 : The second Byte value to be added.
Returns the sum of byte1 and byte2 as a Byte.
fn add(self : Int, other : Int) -> IntAdds two 32-bit signed integers. Performs two's complement arithmetic, which
means the operation will wrap around if the result exceeds the range of a
32-bit integer.
Parameters:
- self : The first integer operand.
- other : The second integer operand.
Returns a new integer that is the sum of the two operands. If the
mathematical sum exceeds the range of a 32-bit integer (-2,147,483,648 to
2,147,483,647), the result wraps around according to two's complement rules.
Example:
test {
inspect(42 + 1, content="43")
inspect(2147483647 + 1, content="-2147483648") // Overflow wraps around to minimum value
}fn add(self : Int64, other : Int64) -> Int64Adds two 64-bit integers together. Performs overflow checking and wrapping
according to two's complement arithmetic.
Parameters:
- self : The first 64-bit integer operand.
- other : The second 64-bit integer operand to add to the first.
Returns a new 64-bit integer representing the sum of the two operands.
Example:
test {
let a = 9223372036854775807L // Int64 maximum value
let b = 1L
inspect(a + b, content="-9223372036854775808") // Wraps around to minimum value
inspect(42L + -42L, content="0")
}fn add(self : UInt, other : UInt) -> UIntPerforms addition between two unsigned 32-bit integers. If the result
overflows, it wraps around according to the rules of modular arithmetic
(2^32).
Parameters:
- self : The first unsigned 32-bit integer operand.
- other : The second unsigned 32-bit integer operand to be added.
Returns the sum of the two unsigned integers, wrapped around if necessary.
Example:
test {
let a = 42U
let b = 100U
inspect(a + b, content="142")
// Demonstrate overflow behavior
let max = 4294967295U // UInt::max_value
inspect(max + 1U, content="0")
}fn add(self : UInt64, other : UInt64) -> UInt64Adds two 64-bit unsigned integers. This is the implementation of the +
operator for UInt64.
Parameters:
- self : The first unsigned 64-bit integer operand.
- other : The second unsigned 64-bit integer operand.
Returns the sum of the two unsigned 64-bit integers. If the result overflows,
it wraps around modulo 2^64.
Example:
test {
let a = 42UL
let b = 100UL
inspect(a + b, content="142")
// Demonstrate overflow behavior
let max = 18446744073709551615UL
inspect(max + 1UL, content="0")
}fn add(self : Double, other : Double) -> DoubleAdds two double-precision floating-point numbers together following IEEE 754
standards.
Parameters:
- self : The first double-precision floating-point number.
- other : The second double-precision floating-point number to add.
Returns the sum of the two numbers. Special cases follow IEEE 754 rules:
- If either operand is NaN, returns NaN
- If adding +∞ and -∞, returns NaN
- If adding ±∞ with any finite number, returns ±∞
- If adding +0.0 and -0.0, returns +0.0
Example:
test {
inspect(2.5 + 3.7, content="6.2")
inspect(1.0 / 0.0 + -1.0 / 0.0, content="NaN") // Infinity + -Infinity = NaN
}fn add(self : String, other : String) -> StringConcatenates two strings, creating a new string that contains all characters
from the first string followed by all characters from the second string.
Parameters:
- self : The first string to concatenate.
- other : The second string to concatenate.
Returns a new string containing the concatenation of both input strings.
Example:
test {
let hello = "Hello"
let world = " World!"
inspect(hello + world, content="Hello World!")
inspect("" + "abc", content="abc") // concatenating with empty string
}impl Add for FixedArray[T]fn[T] add(self : FixedArray[T], other : FixedArray[T]) -> FixedArray[T]Concatenates two arrays and returns a new array containing all elements from
both arrays in order.
Parameters:
- self : The first array to concatenate.
- other : The second array to concatenate.
Returns a new array that contains all elements from the first array followed
by all elements from the second array. The returned array is independent of
both input arrays.
Example:
test {
let arr1 : FixedArray[Int] = [1, 2, 3]
let arr2 : FixedArray[Int] = [4, 5, 6]
debug_inspect(
arr1 + arr2,
content=(
#|<FixedArray: [1, 2, 3, 4, 5, 6]>
),
)
}fn add(self : Bytes, other : Bytes) -> BytesConcatenates two bytes sequences.
Parameters:
- self : The first bytes sequence.
- other : The second bytes sequence.
Returns a new bytes sequence containing the bytes of self followed by the
bytes of other.
impl Add for StringViewfn add(self : StringView, other : StringView) -> StringViewBitAnd
pub(open) trait BitAnd {
fn land(Self, Self) -> Self
}types implementing this trait can use the & operator
fn land(self : Byte, that : Byte) -> BytePerforms a bitwise AND operation between two Byte values.
Parameters:
- byte1 : The first Byte value to perform the bitwise AND operation with.
- byte2 : The second Byte value to perform the bitwise AND operation with.
Returns the result of the bitwise AND operation as a Byte.
fn land(self : Int, other : Int) -> IntPerforms a bitwise AND operation between two 32-bit integers. Each bit in the
result is set to 1 only if the corresponding bits in both operands are 1.
Parameters:
- self : The first 32-bit integer operand.
- other : The second 32-bit integer operand.
Returns the result of the bitwise AND operation. The resulting value has a
bit set to 1 at each position where both input integers have a bit set to 1.
Example:
test {
let x = 0xF0 // 11110000
let y = 0xAA // 10101010
inspect(x & y, content="160") // 10100000 = 160
}fn land(self : Int64, other : Int64) -> Int64Performs a bitwise AND operation between two 64-bit signed integers.
Parameters:
- self : The first 64-bit integer operand.
- other : The second 64-bit integer operand.
Returns a 64-bit integer where each bit is set to 1 if and only if the
corresponding bits in both operands are 1.
Example:
test {
let a = 0xFF00FF00L
let b = 0x0F0F0F0FL
inspect(a & b, content="251662080") // 0x0F000F00
}fn land(self : UInt, other : UInt) -> UIntPerforms a bitwise AND operation between two unsigned 32-bit integers. For
each bit position, the result is 1 if the bits at that position in both
operands are 1, and 0 otherwise.
Parameters:
- self : The first unsigned 32-bit integer operand.
- other : The second unsigned 32-bit integer operand.
Returns an unsigned 32-bit integer representing the result of the bitwise AND
operation.
Example:
test {
let a = 0xF0F0U // 1111_0000_1111_0000
let b = 0xFF00U // 1111_1111_0000_0000
inspect(a & b, content="61440") // 1111_0000_0000_0000 = 61440
}fn land(self : UInt64, other : UInt64) -> UInt64Performs a bitwise AND operation between two unsigned 64-bit integers.
Parameters:
- self : The first unsigned 64-bit integer operand.
- other : The second unsigned 64-bit integer operand.
Returns the result of performing a bitwise AND operation on the two operands.
Example:
test {
let a = 0xF0F0F0F0F0F0F0F0UL
let b = 0xFF00FF00FF00FF00UL
inspect(a & b, content="17294086455919964160") // 0xF000F000F000F000
}BitOr
pub(open) trait BitOr {
fn lor(Self, Self) -> Self
}types implementing this trait can use the | operator
fn lor(self : Byte, that : Byte) -> BytePerforms a bitwise OR operation between two Byte values.
Parameters:
- self : The first Byte value.
- that : The second Byte value.
Returns a new Byte value resulting from the bitwise OR operation.
fn lor(self : Int, other : Int) -> IntPerforms a bitwise OR operation between two 32-bit integers. For each bit
position, the result is 1 if at least one of the corresponding bits in either
operand is 1.
Parameters:
- self : The first integer operand.
- other : The second integer operand.
Returns a new integer where each bit is set to 1 if at least one of the
corresponding bits in either operand is 1, and 0 otherwise.
Example:
test {
let x = 0xF0F0 // 1111_0000_1111_0000
let y = 0x0F0F // 0000_1111_0000_1111
inspect(x | y, content="65535") // 1111_1111_1111_1111 = 65535
}fn lor(self : Int64, other : Int64) -> Int64Performs a bitwise OR operation between two 64-bit integers.
Parameters:
- self : The first 64-bit integer operand.
- other : The second 64-bit integer operand.
Returns a new 64-bit integer where each bit is set to 1 if at least one of
the corresponding bits in either operand is 1.
Example:
test {
let a = 0xFF00L // 1111_1111_0000_0000
let b = 0x0FF0L // 0000_1111_1111_0000
inspect(a | b, content="65520") // 1111_1111_1111_0000 = 65520
}fn lor(self : UInt, other : UInt) -> UIntPerforms a bitwise OR operation between two unsigned 32-bit integers. For
each bit position, the result is 1 if at least one of the corresponding bits
in either operand is 1.
Parameters:
- self : The first unsigned 32-bit integer operand.
- other : The second unsigned 32-bit integer operand.
Returns the result of the bitwise OR operation as an unsigned 32-bit integer.
Example:
test {
let a = 0xF0F0U // Binary: 1111_0000_1111_0000
let b = 0x0F0FU // Binary: 0000_1111_0000_1111
inspect(a | b, content="65535") // Binary: 1111_1111_1111_1111
}fn lor(self : UInt64, other : UInt64) -> UInt64Performs a bitwise OR operation between two unsigned 64-bit integers.
Parameters:
- self : The first unsigned 64-bit integer operand.
- other : The second unsigned 64-bit integer operand.
Returns a new UInt64 value with bits set to 1 where either or both operands
have bits set to 1, and 0 where both operands have bits set to 0.
Example:
test {
let a = 0xF0F0F0F0UL
let b = 0x0F0F0F0FUL
inspect(a | b, content="4294967295") // All bits set to 1
}BitXOr
pub(open) trait BitXOr {
fn lxor(Self, Self) -> Self
}types implementing this trait can use the ^ operator
fn lxor(self : Byte, that : Byte) -> BytePerforms a bitwise XOR operation between two Byte values.
Parameters:
- self : The first Byte value.
- that : The second Byte value.
Returns the result of the bitwise XOR operation as a Byte.
fn lxor(self : Int, other : Int) -> IntPerforms a bitwise XOR operation between two integers.
Parameters:
- self : The first integer operand.
- other : The second integer operand.
Returns a new integer where each bit is set to 1 if the corresponding bits in
the operands are different, and 0 if they are the same.
Example:
test {
let x = 0xF0F0 // 1111_0000_1111_0000
let y = 0x0F0F // 0000_1111_0000_1111
inspect(x ^ y, content="65535") // 1111_1111_1111_1111
inspect(x ^ x, content="0") // XOR with self gives 0
}fn lxor(self : Int64, other : Int64) -> Int64Performs a bitwise XOR operation between two 64-bit integers. Each bit of the
result is set to 1 if the corresponding bits of the operands are different,
and 0 if they are the same.
Parameters:
- self : The first 64-bit integer operand.
- other : The second 64-bit integer operand.
Returns a new 64-bit integer containing the result of the bitwise XOR
operation.
Example:
test {
let a = 0xF0F0F0F0F0F0F0F0L
let b = 0x0F0F0F0F0F0F0F0FL
inspect(a ^ b, content="-1") // All bits set to 1
inspect(a ^ a, content="0") // XOR with self gives 0
}fn lxor(self : UInt, other : UInt) -> UIntPerforms a bitwise XOR (exclusive OR) operation between two unsigned 32-bit
integers. Each bit in the result is set to 1 if the corresponding bits in the
operands are different, and 0 if they are the same.
Parameters:
- self : The first unsigned 32-bit integer operand.
- other : The second unsigned 32-bit integer operand.
Returns the result of the bitwise XOR operation.
Example:
test {
let a = 0xFF00U // Binary: 1111_1111_0000_0000
let b = 0x0F0FU // Binary: 0000_1111_0000_1111
inspect(a ^ b, content="61455") // Binary: 1111_0000_0000_1111
}fn lxor(self : UInt64, other : UInt64) -> UInt64Performs a bitwise XOR operation between two unsigned 64-bit integers. For
each bit position, the result is 1 if the bits at that position in the two
operands are different, and 0 if they are the same.
Parameters:
- self : The first unsigned 64-bit integer operand.
- other : The second unsigned 64-bit integer operand.
Returns a new UInt64 value representing the bitwise XOR of the two
operands.
Example:
test {
let a = 0xF0F0F0F0UL
let b = 0x0F0F0F0FUL
inspect(a ^ b, content="4294967295") // 0xFFFFFFFF
}Compare
pub(open) trait Compare : Eq {
fn compare(Self, Self) -> Int
fn op_lt(Self, Self) -> Bool = _
fn op_gt(Self, Self) -> Bool = _
fn op_le(Self, Self) -> Bool = _
fn op_ge(Self, Self) -> Bool = _
}Trait for types whose elements are ordered
The return value of [compare] is:
- zero, if the two arguments are equal
- negative, if the first argument is smaller
- positive, if the first argument is greater
fn compare(self : Bool, other : Bool) -> IntCompares two boolean values and returns their relative order. The comparison
follows the rule that false is less than true.
Parameters:
- self : The first boolean value to compare.
- other : The second boolean value to compare against.
Returns an integer indicating the relative order:
- A negative value if self is false and other is true
- Zero if self equals other
- A positive value if self is true and other is false
Example:
test {
inspect(true.compare(false), content="1") // true > false
inspect(false.compare(true), content="-1") // false < true
inspect(true.compare(true), content="0") // true = true
}fn compare(self : Byte, that : Byte) -> IntCompares two Byte values and returns an integer indicating their relative
order.
Parameters:
- byte1 : The first Byte value to compare.
- byte2 : The second Byte value to compare.
Returns an integer where:
- A value less than 0 indicates that byte1 is less than byte2.
- A value of 0 indicates that byte1 is equal to byte2.
- A value greater than 0 indicates that byte1 is greater than byte2.
fn op_ge(x : Byte, y : Byte) -> Boolfn op_gt(x : Byte, y : Byte) -> Boolfn op_le(x : Byte, y : Byte) -> Boolfn op_lt(x : Byte, y : Byte) -> Boolfn compare(self : Char, other : Char) -> IntCompares two characters based on their Unicode code points. Returns a
negative value if the first character comes before the second, zero if they
are equal, and a positive value if the first character comes after the
second.
Parameters:
- self : The first character to compare.
- other : The second character to compare against.
Returns an integer indicating the relative ordering:
- A negative value if self is less than other
- Zero if self equals other
- A positive value if self is greater than other
Example:
test {
inspect('a'.compare('b'), content="-1")
inspect('b'.compare('a'), content="1")
inspect('a'.compare('a'), content="0")
}fn op_ge(x : Char, y : Char) -> Boolfn op_gt(x : Char, y : Char) -> Boolfn op_le(x : Char, y : Char) -> Boolfn op_lt(x : Char, y : Char) -> Boolfn compare(self : Int, other : Int) -> IntCompares two integers and returns their relative order.
Parameters:
- self : The first integer to compare.
- other : The second integer to compare against.
Returns an integer indicating the relative order:
- A negative value if self is less than other
- Zero if self equals other
- A positive value if self is greater than other
Example:
test {
let a = 42
let b = 24
inspect(a.compare(b), content="1") // 42 > 24
inspect(b.compare(a), content="-1") // 24 < 42
inspect(a.compare(a), content="0") // 42 = 42
}fn op_ge(x : Int, y : Int) -> Boolfn op_gt(x : Int, y : Int) -> Boolfn op_le(x : Int, y : Int) -> Boolfn op_lt(x : Int, y : Int) -> Boolfn compare(self : Int64, other : Int64) -> IntCompares two 64-bit integers and returns their relative order.
Parameters:
- self : The first 64-bit integer to compare.
- other : The second 64-bit integer to compare against.
Returns an integer indicating the relative order:
- A negative value if self is less than other
- Zero if self equals other
- A positive value if self is greater than other
Example:
test {
let a = 42L
let b = 24L
let c = -42L
inspect(a.compare(b), content="1") // 42 > 24
inspect(b.compare(a), content="-1") // 24 < 42
inspect(c.compare(a), content="-1") // -42 < 42
inspect(a.compare(a), content="0") // 42 = 42
}fn op_ge(x : Int64, y : Int64) -> Boolfn op_gt(x : Int64, y : Int64) -> Boolfn op_le(x : Int64, y : Int64) -> Boolfn op_lt(x : Int64, y : Int64) -> Boolfn compare(self : UInt, other : UInt) -> IntCompares two unsigned 32-bit integers and returns their relative order.
Parameters:
- self : The first unsigned integer to compare.
- other : The second unsigned integer to compare against.
Returns an integer indicating the relative order:
- A negative value if self is less than other
- Zero if self equals other
- A positive value if self is greater than other
Example:
test {
let a = 42U
let b = 24U
inspect(a.compare(b), content="1") // 42 > 24
inspect(b.compare(a), content="-1") // 24 < 42
inspect(a.compare(a), content="0") // 42 = 42
}fn op_ge(x : UInt, y : UInt) -> Boolfn op_gt(x : UInt, y : UInt) -> Boolfn op_le(x : UInt, y : UInt) -> Boolfn op_lt(x : UInt, y : UInt) -> Boolfn compare(self : UInt64, other : UInt64) -> IntCompares two unsigned 64-bit integers and determines their relative order.
Parameters:
- self : The first unsigned 64-bit integer to compare.
- other : The second unsigned 64-bit integer to compare.
Returns an integer indicating the relative order:
- A negative value if self is less than other
- Zero if self equals other
- A positive value if self is greater than other
Example:
test {
let a = 42UL
let b = 24UL
inspect(a.compare(b), content="1") // 42 > 24
inspect(b.compare(a), content="-1") // 24 < 42
inspect(a.compare(a), content="0") // 42 = 42
}fn op_ge(x : UInt64, y : UInt64) -> Boolfn op_gt(x : UInt64, y : UInt64) -> Boolfn op_le(x : UInt64, y : UInt64) -> Boolfn op_lt(x : UInt64, y : UInt64) -> Boolfn compare(self : Double, other : Double) -> IntCompares two double-precision floating-point numbers and returns their
relative order. Follows IEEE 754 rules for floating-point comparisons,
including handling of special values like NaN.
Parameters:
- self : The first double-precision floating-point number to compare.
- other : The second double-precision floating-point number to compare against.
Returns an integer indicating the relative order:
- A negative value if self is less than other
- Zero if self equals other
- A positive value if self is greater than other
- If either value is NaN, returns an implementation-defined value that is consistent with total ordering
Example:
test {
let a = 3.14
let b = 2.718
inspect(a.compare(b), content="1") // 3.14 > 2.718
inspect(b.compare(a), content="-1") // 2.718 < 3.14
inspect(a.compare(a), content="0") // 3.14 = 3.14
}fn op_ge(x : Double, y : Double) -> Boolfn op_gt(x : Double, y : Double) -> Boolfn op_le(x : Double, y : Double) -> Boolfn op_lt(x : Double, y : Double) -> Boolfn compare(self : String, other : String) -> IntStrings are ordered based on shortlex order by their charcodes (code units). This
orders Unicode characters based on their positions in the code charts. This is
not necessarily the same as "alphabetical" order, which varies by language
and locale.
impl Compare for FixedArray[T]Compares two fixed arrays based on shortlex order by their elements. First
compares the lengths of the arrays, then compares elements pairwise until a
difference is found or all elements have been compared.
Parameters:
- self : The first fixed array to compare.
- other : The second fixed array to compare.
Returns an integer that indicates the relative order:
- A negative value if self is less than other
- Zero if self equals other
- A positive value if self is greater than other
Example:
test {
let arr1 = [1, 2, 3]
let arr2 = [1, 2, 4]
let arr3 = [1, 2]
inspect(arr1.compare(arr2), content="-1") // arr1 < arr2
inspect(arr2.compare(arr1), content="1") // arr2 > arr1
inspect(arr1.compare(arr3), content="1") // arr1 > arr3 (longer)
inspect(arr1.compare(arr1), content="0") // arr1 = arr1
}impl Compare for ReadOnlyArray[T]fn compare(self : Bytes, other : Bytes) -> IntCompares two byte sequences based on shortlex order. First compares the lengths of
the sequences, then compares bytes pairwise until a difference is found or
all bytes have been compared.
Parameters:
- self : The first byte sequence to compare.
- other : The second byte sequence to compare.
Returns an integer indicating the relative order:
- A negative value if self is less than other
- Zero if self equals other
- A positive value if self is greater than other
Example:
test {
let a = b"\x01\x02\x03"
let b = b"\x01\x02\x04"
inspect(a.compare(b), content="-1") // a < b
inspect(b.compare(a), content="1") // b > a
inspect(a.compare(a), content="0") // a = a
let a = b"\x01\x02"
let b = b"\x01\x02\x03"
inspect(a.compare(b), content="-1") // shorter sequence is less
inspect(b.compare(a), content="1") // longer sequence is greater
}fn[T0 : Compare + Eq, T1 : Compare + Eq, T2 : Compare + Eq, T3 : Compare + Eq, T4 : Compare + Eq, T5 : Compare + Eq, T6 : Compare + Eq, T7 : Compare + Eq, T8 : Compare + Eq, T9 : Compare + Eq] compare(self : (T0, T1, T2, T3, T4, T5, T6, T7, T8, T9), other : (T0, T1, T2, T3, T4, T5, T6, T7, T8, T9)) -> Intfn[T0 : Compare + Eq, T1 : Compare + Eq, T2 : Compare + Eq, T3 : Compare + Eq, T4 : Compare + Eq, T5 : Compare + Eq, T6 : Compare + Eq, T7 : Compare + Eq, T8 : Compare + Eq, T9 : Compare + Eq, T10 : Compare + Eq] compare(self : (T0, T1, T2, T3, T4, T5, T6, T7, T8, T9, T10), other : (T0, T1, T2, T3, T4, T5, T6, T7, T8, T9, T10)) -> Intfn[T0 : Compare + Eq, T1 : Compare + Eq, T2 : Compare + Eq, T3 : Compare + Eq, T4 : Compare + Eq, T5 : Compare + Eq, T6 : Compare + Eq, T7 : Compare + Eq, T8 : Compare + Eq, T9 : Compare + Eq, T10 : Compare + Eq, T11 : Compare + Eq] compare(self : (T0, T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11), other : (T0, T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11)) -> Intfn[T0 : Compare + Eq, T1 : Compare + Eq, T2 : Compare + Eq, T3 : Compare + Eq, T4 : Compare + Eq, T5 : Compare + Eq, T6 : Compare + Eq, T7 : Compare + Eq, T8 : Compare + Eq, T9 : Compare + Eq, T10 : Compare + Eq, T11 : Compare + Eq, T12 : Compare + Eq] compare(self : (T0, T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12), other : (T0, T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12)) -> Intfn[T0 : Compare + Eq, T1 : Compare + Eq, T2 : Compare + Eq, T3 : Compare + Eq, T4 : Compare + Eq, T5 : Compare + Eq, T6 : Compare + Eq, T7 : Compare + Eq, T8 : Compare + Eq, T9 : Compare + Eq, T10 : Compare + Eq, T11 : Compare + Eq, T12 : Compare + Eq, T13 : Compare + Eq] compare(self : (T0, T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13), other : (T0, T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13)) -> Intfn[T0 : Compare + Eq, T1 : Compare + Eq, T2 : Compare + Eq, T3 : Compare + Eq, T4 : Compare + Eq, T5 : Compare + Eq, T6 : Compare + Eq, T7 : Compare + Eq, T8 : Compare + Eq, T9 : Compare + Eq, T10 : Compare + Eq, T11 : Compare + Eq, T12 : Compare + Eq, T13 : Compare + Eq, T14 : Compare + Eq] compare(self : (T0, T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14), other : (T0, T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14)) -> Intfn[T0 : Compare + Eq, T1 : Compare + Eq, T2 : Compare + Eq, T3 : Compare + Eq, T4 : Compare + Eq, T5 : Compare + Eq, T6 : Compare + Eq, T7 : Compare + Eq, T8 : Compare + Eq, T9 : Compare + Eq, T10 : Compare + Eq, T11 : Compare + Eq, T12 : Compare + Eq, T13 : Compare + Eq, T14 : Compare + Eq, T15 : Compare + Eq] compare(self : (T0, T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, T15), other : (T0, T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, T15)) -> Intfn compare(self : BytesView, other : BytesView) -> IntCompares two views based on shortlex order. First compares the lengths of
the views, then compares bytes pairwise until a difference is found or
all bytes have been compared.
Parameters:
- self : The first view to compare.
- other : The second byte sequence to compare.
Returns an integer indicating the relative order:
- A negative value if self is less than other
- Zero if self equals other
- A positive value if self is greater than other
Example:
test {
let bytes = b"abcabc"
inspect(bytes[0:3].compare(bytes[3:6]), content="0") // abc = abc
inspect(bytes[0:3].compare(bytes[2:5]), content="-1") // abc < cab
inspect(bytes[1:4].compare(bytes[3:6]), content="1") // bca > abc
inspect(bytes[0:3].compare(bytes[0:4]), content="-1") // abc < abca
inspect(bytes[1:5].compare(bytes[2:5]), content="1") // bcab > cab
}impl Compare for StringViewfn compare(self : StringView, other : StringView) -> IntViews are ordered based on shortlex order by their charcodes (code units). This
orders Unicode characters based on their positions in the code charts. This is
not necessarily the same as "alphabetical" order, which varies by language
and locale.
Default
pub(open) trait Default {
fn default() -> Self
}Trait for types with a default value
fn default() -> BoolReturns the default value for the Bool type, which is false.
Returns a Bool value that represents the default state of a boolean value.
Example:
test {
let b : Bool = false
inspect(b, content="false")
}fn default() -> ByteReturns the default value for a Byte, which is b'\x00'.
Parameters:
- None
Returns the default Byte value, which is b'\x00'.
fn default() -> CharReturns the default value for the Char type, which is the null character
('\x00').
Returns a Char value representing the null character.
Example:
test {
assert_true((Default::default() : Char).to_string() == "\u0000")
}fn default() -> IntReturns the default value for integers, which is 0.
Returns an integer value of 0.
Example:
test {
let x : Int = 0
inspect(x, content="0")
}fn default() -> Int64Returns the default value for Int64 type, which is zero (0L).
Returns a 64-bit signed integer with value 0.
Example:
test {
inspect(0L, content="0")
}fn default() -> DoubleReturns the default value for double-precision floating-point numbers (0.0).
Returns a Double value initialized to 0.0.
Example:
test {
inspect(0.0, content="0")
}impl Default for FixedArray[X]fn[X] default() -> FixedArray[X]Returns an empty fixed-size array of the specified type.
Parameters:
- X : The type parameter specifying the element type of the array.
Returns an empty fixed-size array of type FixedArray[X].
Example:
test {
let arr : FixedArray[Int] = ([] : FixedArray[_])
inspect(arr.length(), content="0")
inspect(arr.is_empty(), content="true")
}impl Default for ReadOnlyArray[T]fn[T] default() -> ReadOnlyArray[T]Default implementation for ReadOnlyArray - returns empty array.
fn default() -> BytesCreates a new empty bytes sequence.
Returns an empty bytes sequence.
Example:
test {
let bytes = (Default::default() : Bytes)
inspect(bytes, content="b\"\"")
inspect(bytes.length(), content="0")
}impl Default for StringViewfn default() -> StringViewThe empty view of a string
Div
pub(open) trait Div {
fn div(Self, Self) -> Self
}types implementing this trait can use the / operator
fn div(self : Byte, that : Byte) -> BytePerforms division operation between two bytes by converting them to integers,
performing the division, and converting the result back to a byte.
Parameters:
- self : The dividend byte value.
- that : The divisor byte value.
Returns the quotient of the division as a byte.
Example:
test {
let a = b'\xFF' // 255
let b = b'\x03' // 3
inspect(a / b, content="b'\\x55'") // 255 / 3 = 85 (0x55)
}fn div(self : Int, other : Int) -> IntPerforms integer division between two 32-bit integers. The result is
truncated towards zero (rounds down for positive numbers and up for negative
numbers).
Parameters:
- dividend : The first integer operand to be divided.
- divisor : The second integer operand that divides the dividend.
Returns the quotient of the division operation.
Throws a panic if divisor is zero.
Example:
test {
inspect(10 / 3, content="3") // truncates towards zero
inspect(-10 / 3, content="-3")
inspect(10 / -3, content="-3")
}fn div(self : Int64, other : Int64) -> Int64Performs integer division between two 64-bit integers. Truncates the result
towards zero.
Parameters:
- self : The dividend (the number to be divided).
- other : The divisor (the number to divide by).
Returns the quotient of the division.
Throws a panic if other is zero.
Example:
test {
let a = 42L
let b = 5L
inspect(a / b, content="8")
let c = -42L
let d = 5L
inspect(c / d, content="-8")
}fn div(self : UInt, other : UInt) -> UIntPerforms division between two unsigned 32-bit integers. The operation follows
standard unsigned integer division rules, where the result is truncated
towards zero.
Parameters:
- self : The dividend (the number to be divided).
- other : The divisor (the number to divide by).
Returns an unsigned 32-bit integer representing the quotient of the division.
Example:
test {
let a = 42U
let b = 5U
inspect(a / b, content="8") // Using infix operator
}fn div(self : UInt64, other : UInt64) -> UInt64Performs division operation between two unsigned 64-bit integers.
Parameters:
- self : The dividend unsigned 64-bit integer.
- other : The divisor unsigned 64-bit integer.
Returns the quotient of dividing the dividend by the divisor.
Throws a runtime error if other is zero.
Example:
test {
let a = 100UL
let b = 20UL
inspect(a / b, content="5") // Using infix operator
}fn div(self : Double, other : Double) -> DoublePerforms division between two double-precision floating-point numbers.
Follows IEEE 754 standard for floating-point arithmetic, including handling
of special cases like division by zero (returns infinity) and operations
involving NaN.
Parameters:
- self : The dividend (numerator) in the division operation.
- other : The divisor (denominator) in the division operation.
Returns the result of dividing self by other. Special cases follow IEEE
754:
- Division by zero returns positive or negative infinity based on the dividend's sign
- Operations involving NaN return NaN
- Division of infinity by infinity returns NaN
Example:
test {
inspect(6.0 / 2.0, content="3")
inspect(-6.0 / 2.0, content="-3")
inspect(1.0 / 0.0, content="Infinity")
}Eq
pub(open) trait Eq {
fn equal(Self, Self) -> Bool
fn not_equal(Self, Self) -> Bool = _
}Trait for types whose elements can test for equality
fn equal(self : Bool, other : Bool) -> BoolCompares two boolean values for equality.
Parameters:
- self : The first boolean value to compare.
- other : The second boolean value to compare.
Returns true if both boolean values are equal (either both true or both
false), false otherwise.
Example:
test {
inspect(true == true, content="true")
inspect(false == true, content="false")
inspect(true == false, content="false")
inspect(false == false, content="true")
}fn equal(self : Byte, that : Byte) -> BoolCompares two Byte values for equality.
Parameters:
- self : The first Byte value to compare.
- that : The second Byte value to compare.
Returns true if the two Byte values are equal, otherwise false.
fn not_equal(self : Byte, that : Byte) -> BoolCompares two Byte values for inequality.
Parameters:
- self : The first Byte value to compare.
- that : The second Byte value to compare.
Returns true if the two Byte values are not equal, otherwise false.
fn equal(self : Char, other : Char) -> BoolCompares two characters for equality.
Parameters:
- self : The first character to compare.
- other : The second character to compare.
Returns true if both characters represent the same Unicode code point,
false otherwise.
Example:
test {
let a = 'A'
let b = 'A'
let c = 'B'
inspect(a == b, content="true")
inspect(a == c, content="false")
}fn not_equal(self : Char, other : Char) -> BoolCompares two characters for inequality.
Parameters:
- self : The first character to compare.
- other : The second character to compare.
Returns true if the characters represent different Unicode code points,
false otherwise.
Example:
test {
let a = 'A'
let b = 'A'
let c = 'B'
inspect(a != b, content="false")
inspect(a != c, content="true")
}fn equal(self : Int, other : Int) -> BoolCompares two integers for equality.
Parameters:
- self : The first integer to compare.
- other : The second integer to compare.
Returns true if both integers have the same value, false otherwise.
Example:
test {
inspect(42 == 42, content="true")
inspect(42 == -42, content="false")
}fn not_equal(self : Int, other : Int) -> BoolCompares two integers for inequality.
Parameters:
- self : The first integer to compare.
- other : The second integer to compare.
Returns true if the integers have different values, false otherwise.
Example:
test {
inspect(42 != 42, content="false")
inspect(42 != -42, content="true")
}fn equal(self : Int64, other : Int64) -> BoolTests if two 64-bit integers are equal.
Parameters:
- self : The first 64-bit integer to compare.
- other : The second 64-bit integer to compare.
Returns true if both integers are equal, false otherwise.
Example:
test {
let a = 42L
let b = 42L
let c = -42L
inspect(a == b, content="true")
inspect(a == c, content="false")
}fn not_equal(self : Int64, other : Int64) -> BoolTests if two 64-bit integers are not equal.
Parameters:
- self : The first 64-bit integer to compare.
- other : The second 64-bit integer to compare.
Returns true if the integers are not equal, false otherwise.
Example:
test {
let a = 42L
let b = 42L
let c = -42L
inspect(a != b, content="false")
inspect(a != c, content="true")
}fn equal(self : UInt, other : UInt) -> BoolCompares two unsigned 32-bit integers for equality.
Parameters:
- self : The first unsigned integer operand.
- other : The second unsigned integer operand to compare with.
Returns true if both integers have the same value, false otherwise.
Example:
test {
let a = 42U
let b = 42U
let c = 24U
inspect(a == b, content="true")
inspect(a == c, content="false")
}fn not_equal(self : UInt, other : UInt) -> BoolCompares two unsigned 32-bit integers for inequality.
Parameters:
- self : The first unsigned integer operand.
- other : The second unsigned integer operand to compare with.
Returns true if the integers have different values, false otherwise.
Example:
test {
let a = 42U
let b = 42U
let c = 24U
inspect(a != b, content="false")
inspect(a != c, content="true")
}fn equal(self : UInt64, other : UInt64) -> BoolCompares two unsigned 64-bit integers for equality.
Parameters:
- self : The first unsigned 64-bit integer to compare.
- other : The second unsigned 64-bit integer to compare.
Returns true if both integers have the same value, false otherwise.
Example:
test {
let a = 42UL
let b = 42UL
let c = 24UL
inspect(a == b, content="true")
inspect(a == c, content="false")
}fn not_equal(self : UInt64, other : UInt64) -> BoolCompares two unsigned 64-bit integers for inequality.
Parameters:
- self : The first unsigned 64-bit integer to compare.
- other : The second unsigned 64-bit integer to compare.
Returns true if the integers have different values, false otherwise.
Example:
test {
let a = 42UL
let b = 42UL
let c = 24UL
inspect(a != b, content="false")
inspect(a != c, content="true")
}fn equal(self : Double, other : Double) -> BoolCompares two double-precision floating-point numbers for equality following
IEEE 754 rules. Returns true if both numbers are equal. NaN is not equal
to any value, including itself, so nan == nan evaluates to false.
Parameters:
- self : The first double-precision floating-point number to compare.
- other : The second double-precision floating-point number to compare.
Returns true if both numbers are equal, false otherwise.
Example:
test {
let a = 3.14
let b = 3.14
let c = 2.718
inspect(a == b, content="true")
inspect(a == c, content="false")
let nan = 0.0 / 0.0 // NaN
inspect(nan == nan, content="false") // NaN != NaN
}fn not_equal(self : Double, other : Double) -> BoolCompares two double-precision floating-point numbers for inequality following
IEEE 754 rules. Returns true if the numbers are not equal.
Parameters:
- self : The first double-precision floating-point number to compare.
- other : The second double-precision floating-point number to compare.
Returns true if the numbers are not equal, false otherwise.
Example:
test {
let a = 3.14
let b = 3.14
let c = 2.718
inspect(a != b, content="false")
inspect(a != c, content="true")
let nan = 0.0 / 0.0 // NaN
inspect(nan != nan, content="true") // NaN != NaN is true
}fn equal(self : String, other : String) -> BoolTests whether two strings are equal by comparing their characters.
Parameters:
- self : The first string to compare.
- other : The second string to compare.
Returns true if both strings contain exactly the same sequence of
characters, false otherwise.
Example:
test {
let str1 = "hello"
let str2 = "hello"
let str3 = "world"
inspect(str1 == str2, content="true")
inspect(str1 == str3, content="false")
}impl Eq for FixedArray[T]Checks if two fixed arrays are equal.
Two arrays are considered equal if they have the same length and all
corresponding elements are equal. The elements in the arrays must implement
the Eq trait.
Parameters:
- self : The first fixed array to compare.
- other : The second fixed array to compare.
Returns true if the arrays are equal, false otherwise.
Example:
test {
let arr1 : FixedArray[Int] = [1, 2, 3]
let arr2 : FixedArray[Int] = [1, 2, 3]
let arr3 : FixedArray[Int] = [1, 2, 4]
inspect(arr1 == arr2, content="true")
inspect(arr1 == arr3, content="false")
}impl Eq for ReadOnlyArray[T]fn equal(self : Bytes, other : Bytes) -> BoolCompares two byte sequences for equality. Returns true only if both sequences
have the same length and contain identical bytes in the same order.
Parameters:
- self : The first byte sequence to compare.
- other : The second byte sequence to compare.
Returns true if the byte sequences are equal, false otherwise.
Example:
test {
let bytes1 = b"\x01\x02\x03"
let bytes2 = b"\x01\x02\x03"
let bytes3 = b"\x01\x02\x04"
inspect(bytes1 == bytes2, content="true")
inspect(bytes1 == bytes3, content="false")
}fn[T0 : Eq, T1 : Eq, T2 : Eq, T3 : Eq, T4 : Eq, T5 : Eq, T6 : Eq, T7 : Eq, T8 : Eq, T9 : Eq, T10 : Eq, T11 : Eq, T12 : Eq, T13 : Eq, T14 : Eq] equal(self : (T0, T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14), other : (T0, T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14)) -> Boolfn[T0 : Eq, T1 : Eq, T2 : Eq, T3 : Eq, T4 : Eq, T5 : Eq, T6 : Eq, T7 : Eq, T8 : Eq, T9 : Eq, T10 : Eq, T11 : Eq, T12 : Eq, T13 : Eq, T14 : Eq, T15 : Eq] equal(self : (T0, T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, T15), other : (T0, T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, T15)) -> Boolfn equal(self : BytesView, other : BytesView) -> BoolCompares two views for equality. Returns true only if both views
have the same length and contain identical bytes in the same order.
Parameters:
- self : The first view to compare.
- other : The second view to compare.
Returns true if the byte sequences are equal, false otherwise.
Example:
test {
let bytes = b"abcabc"
inspect(bytes[0:3] == bytes[3:6], content="true")
inspect(bytes[0:3] == bytes[2:5], content="false")
inspect(bytes[0:4] == bytes[3:6], content="false")
}impl Eq for StringViewfn equal(self : StringView, other : StringView) -> BoolCompares two views for equality. Returns true only if both views
have the same length and contain identical characters in the same order.
Hash
Trait for types that can be hashed
The hash method should return a hash value for the type, which is used in hash tables and other data structures.
The hash_combine method is used to combine the hash of the current value with another hash value,
typically used to hash composite types.
When two values are equal according to the Eq trait, they should produce the same hash value.
The hash method does not need to be implemented if hash_combine is implemented,
When implemented separately, hash does not need to produce a hash value that is consistent with hash_combine.
Implements the Hash trait for Byte type by providing a hash_combine
method that combines a byte value with a hasher.
Parameters:
- self : The byte value to be hashed.
- hasher : The hasher object that will be used to combine the byte value into its internal state.
Example:
test {
let hasher = Hasher(seed=0)
hasher.combine_byte(b'\xFF')
inspect(hasher.finalize(), content="1955036104")
}fn hash(self : Int) -> IntImplements hash combination for integers by combining the integer value with
a hasher. This implementation ensures that integers can be used as keys in
hash-based collections like hash maps and hash sets.
Parameters:
- self : The integer value to be hashed.
- hasher : A Hasher object that accumulates the hash value.
Example:
test {
let hasher = Hasher(seed=0)
hasher.combine_int(42)
inspect(hasher.finalize(), content="1161967057")
}fn hash(self : UInt) -> IntCombines the hash value of an unsigned integer with a hasher object. This is
useful when you need to hash a data structure that contains unsigned
integers.
Parameters:
- value : The unsigned integer to be combined with the hasher.
- hasher : The hasher object that will incorporate the hash value of the unsigned integer.
Example:
test {
let hasher = Hasher(seed=0)
hasher.combine_uint(42U)
inspect(hasher.finalize(), content="1161967057")
}fn hash(self : UInt64) -> IntImplements the Hash trait for UInt64 by combining the hash value of an
unsigned 64-bit integer into a hasher.
Parameters:
- self : The unsigned 64-bit integer value to be hashed.
- hasher : The hasher object used to compute the combined hash value.
Example:
test {
let hasher = Hasher(seed=0)
hasher.combine_uint64(42UL)
inspect(hasher.finalize(), content="-1962516083")
}fn hash(self : String) -> IntImplements the Hash trait for String type, providing a method to combine
a string's hash value with a hasher's state.
Parameters:
- self : The string value to be hashed.
- hasher : The hasher object that will be updated with the string's hash value.
Example:
test {
let s1 = "hello"
let s2 = "hello"
let s3 = "world"
inspect(Hash::hash(s1) == Hash::hash(s2), content="true")
inspect(Hash::hash(s1) == Hash::hash(s3), content="false")
}Implements the Hash trait for Option types, allowing them to be used as
keys in hash-based collections.
Parameters:
- self : The Option value to be hashed.
- hasher : The hasher object that accumulates the hash state.
Example:
test {
let hasher = Hasher(seed=0)
let some_value : Int? = Some(42)
let none_value : Int? = None
hasher.combine(some_value)
inspect(hasher.finalize(), content="2103260413")
let hasher2 = Hasher(seed=0)
hasher2.combine(none_value)
inspect(hasher2.finalize(), content="148298089")
}Implements the Hash trait for Result type, allowing Result values to be
used in hash-based collections.
Parameters:
- self : The Result value to be hashed.
- hasher : The hasher object to which the hash value will be combined.
Example:
test {
let hasher = Hasher(seed=0)
let ok_result : Result[Int, String] = Ok(42)
let err_result : Result[Int, String] = Err("error")
hasher.combine(ok_result)
inspect(hasher.finalize(), content="-1948635851")
let hasher = Hasher(seed=0)
hasher.combine(err_result)
inspect(hasher.finalize(), content="1953766574")
}impl Hash for FixedArray[T]impl Hash for ReadOnlyArray[T]impl Hash for StringViewLogger
pub(open) trait Logger {
fn write_string(Self, String) -> Unit = _
#deprecated("use `write_view` instead")
fn write_substring(Self, String, Int, Int) -> Unit = _
fn write_view(Self, StringView) -> Unit = _
fn write_char(Self, Char) -> Unit = _
fn write_string_interpolation(Self, &Show) -> Unit = _
fn write(Self, &Show) -> Unit = _
}Trait for append-only text sinks used by Show implementations.
A logger receives formatted output without requiring callers to allocate a
complete String first.
Mod
pub(open) trait Mod {
fn mod(Self, Self) -> Self
}types implementing this trait can use the % operator
fn mod(self : Int, other : Int) -> IntCalculates the remainder of dividing one integer by another. The result
follows the formula dividend - (dividend / divisor) * divisor, maintaining
the same sign as the dividend.
Parameters:
- self : The dividend (the number being divided).
- other : The divisor (the number to divide by).
Returns the remainder of the division. If other is 0, the behavior is
undefined.
Example:
test {
inspect(7 % 3, content="1")
inspect(-7 % 3, content="-1")
inspect(7 % -3, content="1")
}fn mod(self : Int64, other : Int64) -> Int64Calculates the remainder of the division between two 64-bit integers. The
result follows the formula self - (self / other) * other, maintaining the
same sign as the dividend.
Parameters:
- self : The dividend 64-bit integer.
- other : The divisor 64-bit integer.
Returns the remainder of the division.
Throws a panic if other is zero.
Example:
test {
inspect(7L % 3L, content="1")
inspect(-7L % 3L, content="-1")
inspect(7L % -3L, content="1")
}fn mod(self : UInt, other : UInt) -> UIntCalculates the remainder of dividing one unsigned integer by another.
Parameters:
- self : The unsigned integer dividend.
- other : The unsigned integer divisor.
Returns the remainder of the division operation.
Throws a panic if other is zero.
Example:
test {
let a = 17U
let b = 5U
inspect(a % b, content="2") // 17 divided by 5 gives quotient 3 and remainder 2
inspect(7U % 4U, content="3")
}fn mod(self : UInt64, other : UInt64) -> UInt64Calculates the remainder of dividing one unsigned 64-bit integer by another.
Parameters:
- self : The dividend unsigned 64-bit integer.
- other : The divisor unsigned 64-bit integer.
Returns the remainder of the division operation.
Throws a panic if the divisor is zero.
Example:
test {
let a = 17UL
let b = 5UL
inspect(a % b, content="2") // 17 divided by 5 gives quotient 3 and remainder 2
inspect(7UL % 4UL, content="3")
}fn mod(self : Double, other : Double) -> DoubleCalculates the floating-point remainder when dividend is divided by
divisor. Returns NaN if either operand is NaN, or if dividend is
infinity, or if divisor is zero.
Parameters:
- dividend : The floating-point number to be divided.
- divisor : The floating-point number used to divide the dividend.
Returns the remainder of the division. The result has the same sign as the
dividend and has an absolute value less than the absolute value of
divisor.
Example:
test {
inspect(5.0.mod(3.0), content="2")
inspect((-5.0).mod(3.0), content="-2")
inspect(5.0.mod(@double.not_a_number), content="NaN")
inspect(@double.infinity.mod(3.0), content="NaN")
}Mul
pub(open) trait Mul {
fn mul(Self, Self) -> Self
}types implementing this trait can use the * operator
fn mul(self : Byte, that : Byte) -> BytePerforms multiplication between two byte values. The result is truncated to
fit within the byte range.
Parameters:
- self : The first byte operand in the multiplication.
- that : The second byte operand in the multiplication.
Returns the product of the two bytes, truncated to fit within the byte range
(0-255).
Example:
test {
let a = b'\x02'
let b = b'\x03'
inspect(a * b, content="b'\\x06'") // 2 * 3 = 6
let c = b'\xFF'
inspect(c * c, content="b'\\x01'") // 255 * 255 = 65025, truncated to 1
}fn mul(self : Int, other : Int) -> IntMultiplies two 32-bit integers. This is the implementation of the *
operator for Int.
Parameters:
- self : The first integer operand.
- other : The second integer operand.
Returns the product of the two integers. If the result overflows the range of
Int, it wraps around according to two's complement arithmetic.
Example:
test {
inspect(42 * 2, content="84")
inspect(-10 * 3, content="-30")
let max = 2147483647 // Int.max_value
inspect(max * 2, content="-2") // Overflow wraps around
}fn mul(self : Int64, other : Int64) -> Int64Multiplies two 64-bit integers.
Parameters:
- self : The first 64-bit integer operand.
- other : The second 64-bit integer operand.
Returns the product of the two 64-bit integers. If the result overflows the
range of Int64, it will be truncated according to two's complement
arithmetic.
Example:
test {
let a = 42L
let b = 100L
inspect(a * b, content="4200")
let c = -42L
inspect(c * b, content="-4200")
}fn mul(self : UInt, other : UInt) -> UIntPerforms multiplication between two unsigned 32-bit integers. The result
wraps around if it exceeds the maximum value of UInt.
Parameters:
- self : The first unsigned integer operand.
- other : The second unsigned integer operand.
Returns the product of the two unsigned integers. If the result exceeds the
maximum value of UInt (4294967295), it wraps around to the corresponding
value modulo 2^32.
Example:
test {
let a = 3U
let b = 4U
inspect(a * b, content="12")
let max = 4294967295U
inspect(max * 2U, content="4294967294") // Wraps around to max * 2 % 2^32
}fn mul(self : UInt64, other : UInt64) -> UInt64Performs multiplication between two unsigned 64-bit integers.
Parameters:
- self : The first unsigned 64-bit integer operand.
- other : The second unsigned 64-bit integer operand.
Returns the product of the two unsigned 64-bit integers. The result wraps
around if it exceeds the maximum value of UInt64.
Example:
test {
let a = 2UL
let b = 3UL
inspect(a * b, content="6")
// Demonstrate wrapping behavior
let max = 18446744073709551615UL
inspect(max * 2UL, content="18446744073709551614") // Wraps around to max - 1
}fn mul(self : Double, other : Double) -> DoubleMultiplies two double-precision floating-point numbers. This is the
implementation of the * operator for Double type.
Parameters:
- self : The first double-precision floating-point operand.
- other : The second double-precision floating-point operand.
Returns a new double-precision floating-point number representing the product
of the two operands. Special cases follow IEEE 754 standard:
- If either operand is NaN, returns NaN
- If one operand is infinity and the other is zero, returns NaN
- If one operand is infinity and the other is a non-zero finite number, returns infinity with the appropriate sign
- If both operands are infinity, returns infinity with the appropriate sign
Example:
test {
inspect(2.5 * 2.0, content="5")
inspect(-2.0 * 3.0, content="-6")
let nan = 0.0 / 0.0 // NaN
inspect(nan * 1.0, content="NaN")
}Neg
pub(open) trait Neg {
fn neg(Self) -> Self
}types implementing this trait can use the unary - operator
fn neg(self : Int) -> IntPerforms arithmetic negation on an integer value, returning its additive
inverse.
Parameters:
- self : The integer value to negate.
Returns the negation of the input value. For all inputs except
@int.min_value (-2147483648), returns the value with opposite sign. When
the input is @int.min_value, returns @int.min_value due to two's
complement representation.
Example:
test {
inspect(-42, content="-42")
inspect(42, content="42")
inspect(2147483647, content="2147483647") // Int maximum value
}fn neg(self : Int64) -> Int64Performs unary negation on a 64-bit signed integer, returning its arithmetic
inverse.
Parameters:
- value : The 64-bit signed integer to negate.
Returns the arithmetic negation of the input value. For all inputs except
Int64::min_value(), returns the value with opposite sign. When the input is
Int64::min_value(), returns Int64::min_value() due to two's complement
representation.
Example:
test {
inspect(-42L, content="-42")
inspect(42L, content="42")
inspect(-9223372036854775808L, content="-9223372036854775808") // negating min value
}fn neg(self : Double) -> DoubleNegates a double-precision floating-point number. For non-NaN inputs, changes
the sign of the number. For NaN inputs, returns NaN.
Parameters:
- number : The double-precision floating-point number to negate.
Returns a new double-precision floating-point number that is the negation of
the input number.
Example:
test {
inspect(-42.0, content="-42")
inspect(42.0, content="42")
inspect(-(0.0 / 0.0), content="NaN") // Negating NaN returns NaN
}Shl
pub(open) trait Shl {
fn shl(Self, Int) -> Self
}types implementing this trait can use the << operator
fn shl(self : Byte, count : Int) -> ByteShifts the bits of the Byte value to the left by the specified number of
positions.
Parameters:
- byte_value : The Byte value whose bits are to be shifted.
- shift_count : The number of bit positions to shift the byte_value to the left.
Returns the resulting Byte value after the shift operation.
fn shl(self : Int, other : Int) -> IntPerforms a left shift operation on a 32-bit integer. Shifts each bit in the
integer to the left by the specified number of positions, filling the
rightmost positions with zeros.
Parameters:
- self : The integer value to be shifted.
- shift : The number of positions to shift. Must be a non-negative value less than 32. Values outside this range will be masked with & 31.
Returns a new integer with bits shifted left by the specified number of
positions. For each position shifted, the rightmost bit is filled with 0, and
the leftmost bit is discarded.
Example:
test {
let x = 1
inspect(x << 3, content="8") // Binary: 1 -> 1000
let y = -4
inspect(y << 2, content="-16") // Binary: 100 -> 10000
}fn shl(self : Int64, other : Int) -> Int64Performs a left shift operation on a 64-bit integer value. Shifts the bits of
the first operand to the left by the number of positions specified by the
second operand. The rightmost positions are filled with zeros.
Parameters:
- self : The 64-bit integer value to be shifted.
- shift : The number of positions to shift the bits to the left. Must be non-negative and less than 64.
Returns a new Int64 value representing the result of the left shift
operation.
Example:
test {
let n = 1L
inspect(n << 3, content="8") // 1 shifted left by 3 positions becomes 8
let m = -4L
inspect(m << 2, content="-16") // -4 shifted left by 2 positions becomes -16
}fn shl(self : UInt, shift : Int) -> UIntPerforms a left shift operation on an unsigned 32-bit integer. Each bit in
the integer is shifted left by the specified number of positions, and zeros
are filled in from the right.
Parameters:
- self : The unsigned 32-bit integer to be shifted.
- shift : The number of positions to shift. Only the least significant 5 bits are used, effectively making the shift count always between 0 and 31.
Returns a new unsigned 32-bit integer that is the result of shifting self
left by shift positions.
Example:
test {
let x = 1U
inspect(x << 3, content="8") // Binary: 1 -> 1000
let y = 0xFFFFFFFFU
inspect(y << 16, content="4294901760") // All bits after position 16 are discarded
}fn shl(self : UInt64, shift : Int) -> UInt64Performs a bitwise left shift operation on an unsigned 64-bit integer.
Parameters:
- self : The unsigned 64-bit integer to be shifted.
- shift : The number of positions to shift the bits to the left. Must be between 0 and 63 inclusive, values outside this range will be masked with &63.
Returns the result of shifting self left by shift positions. For each
position shifted, the rightmost bit is filled with 0, and the leftmost bit is
discarded.
Example:
test {
let x = 1UL
inspect(x << 3, content="8") // 1 shifted left by 3 positions becomes 8
inspect(x << 63, content="9223372036854775808") // 1 shifted left by 63 positions
}Show
#must_implement_one(output, to_string)
pub(open) trait Show {
fn output(Self, &Logger) -> Unit = _
fn to_string(Self) -> String = _
}Trait for types that can be converted to String
fn to_string(self : Char) -> StringReturns the original character as a string without escaping.
Show::output for Char also writes the raw character through this
Show::to_string implementation.
Use Char::escape when a quoted and escaped representation is needed.
fn to_string(self : String) -> StringReturns the original string without escaping.
Show::output for String also writes the raw string through this
Show::to_string implementation.
Use String::escape when a quoted and escaped representation is needed.
Examples
test {
let str = "Hello \n"
inspect(str.to_string(), content="Hello \n")
inspect(str.escape(quote=true), content="\"Hello \\n\"")
}impl Show for FixedArray[X]impl Show for ReadOnlyArray[T]impl Show for StringViewShr
pub(open) trait Shr {
fn shr(Self, Int) -> Self
}types implementing this trait can use the >> operator
fn shr(self : Byte, count : Int) -> ByteShifts the bits of the Byte value to the right by the specified number of
positions.
Parameters:
- byte : The Byte value whose bits are to be shifted.
- count : The number of bit positions to shift the byte value to the right.
Returns the resulting Byte value after the bitwise right shift operation.
fn shr(self : Int, other : Int) -> IntPerforms an arithmetic right shift operation on an integer value. Shifts the
bits of the first operand to the right by the number of positions specified
by the second operand. The sign bit is preserved and copied to the leftmost
positions.
Parameters:
- self : The integer value to be shifted.
- shift : The number of positions to shift the bits to the right. Must be non-negative.
Returns an integer representing the result of the arithmetic right shift
operation.
Example:
test {
let n = -16
inspect(n >> 2, content="-4") // Sign bit is preserved during shift
let p = 16
inspect(p >> 2, content="4") // Regular right shift for positive numbers
}fn shr(self : Int64, other : Int) -> Int64Performs arithmetic right shift operation on a 64-bit integer value by a
specified number of bits. Preserves the sign bit of the original number while
shifting its bits right, filling the leftmost positions with copies of the
sign bit.
Parameters:
- self : The 64-bit integer value to be shifted.
- shift_count : The number of positions to shift right. Must be non-negative and less than 64.
Returns a new Int64 value that represents the result of shifting self
right by shift_count bits.
Example:
test {
let n = -1024L
inspect(n >> 3, content="-128") // Preserves sign bit
let p = 1024L
inspect(p >> 3, content="128") // Regular right shift for positive numbers
}fn shr(self : UInt, shift : Int) -> UIntPerforms a logical right shift operation on an unsigned 32-bit integer. The
operation shifts all bits to the right by a specified number of positions,
filling the leftmost positions with zeros.
Parameters:
- self : The unsigned 32-bit integer to be shifted.
- shift : The number of positions to shift right. If this value is negative, the behavior is undefined. Values larger than 31 are masked with &31.
Returns a new unsigned 32-bit integer containing the result of the right
shift operation.
Example:
test {
let x = 0xFF000000U
inspect(x >> 8, content="16711680") // 0x00FF0000
inspect(x >> 24, content="255") // 0x000000FF
let x = 0xFF000000U
inspect(x >> 32, content="4278190080") // Same as x >> 0 due to masking
}fn shr(self : UInt64, shift : Int) -> UInt64Performs a logical right shift operation on a 64-bit unsigned integer by a
specified number of bits. All bits shifted beyond the least significant bit
are discarded, and zeros are shifted in from the most significant bit.
Parameters:
- self : The 64-bit unsigned integer to be shifted.
- shift : The number of positions to shift right. Only the least significant 6 bits of this value are used, effectively making the shift count always between 0 and 63.
Returns a new UInt64 value representing the result of the right shift
operation.
Example:
test {
let x = 0xFF00FF00FF00FF00UL
inspect(x >> 8, content="71777214294589695") // Shifted right by 8 bits
inspect(x >> 64, content="18374966859414961920") // Equivalent to x >> 0 due to masking
}Sub
pub(open) trait Sub {
fn sub(Self, Self) -> Self
}types implementing this trait can use the - operator
fn sub(self : Byte, that : Byte) -> ByteSubtracts the second byte from the first byte and returns the result as a
byte.
Parameters:
- self : The byte from which the second byte will be subtracted.
- that : The byte to subtract from the first byte.
Returns the result of the subtraction as a byte.
fn sub(self : Int, other : Int) -> IntPerforms subtraction between two 32-bit integers, following standard two's
complement arithmetic rules. When the result overflows or underflows, it
wraps around within the 32-bit integer range.
Parameters:
- self : The minuend (the number being subtracted from).
- other : The subtrahend (the number to subtract).
Returns the difference between self and other.
Example:
test {
let a = 42
let b = 10
inspect(a - b, content="32")
let max = 2147483647 // Int maximum value
inspect(max - -1, content="-2147483648") // Overflow case
}fn sub(self : Int64, other : Int64) -> Int64Performs subtraction between two 64-bit integers.
Parameters:
- self : The minuend (the number being subtracted from).
- other : The subtrahend (the number to subtract).
Returns the difference between self and other as a 64-bit integer.
Example:
test {
let a = 9223372036854775807L // Int64 maximum value
let b = 1L
inspect(a - b, content="9223372036854775806")
let c = -9223372036854775808L // Int64 minimum value
let d = 1L
inspect(c - d, content="9223372036854775807")
}fn sub(self : UInt, other : UInt) -> UIntPerforms subtraction between two unsigned 32-bit integers. When the result
would be negative, the function wraps around using modular arithmetic (2^32).
Parameters:
- self : The first unsigned 32-bit integer (minuend).
- other : The second unsigned 32-bit integer to subtract from the first (subtrahend).
Returns a new unsigned 32-bit integer representing the difference between the
two numbers. If the result would be negative, it wraps around to a positive
number by adding 2^32 repeatedly until the result is in range.
Example:
test {
let a = 5U
let b = 3U
inspect(a - b, content="2")
let c = 3U
let d = 5U
inspect(c - d, content="4294967294") // wraps around to 2^32 - 2
}fn sub(self : UInt64, other : UInt64) -> UInt64Performs subtraction between two unsigned 64-bit integers. When the result
would be negative, the function wraps around using modular arithmetic (2^64).
Parameters:
- self : The first unsigned 64-bit integer (minuend).
- other : The second unsigned 64-bit integer to subtract from the first (subtrahend).
Returns the difference between the two numbers, wrapped around if necessary.
Example:
test {
let a = 5UL
let b = 3UL
inspect(a - b, content="2")
let c = 3UL
let d = 5UL
inspect(c - d, content="18446744073709551614") // wraps around to 2^64 - 2
}fn sub(self : Double, other : Double) -> DoublePerforms subtraction between two double-precision floating-point numbers.
Parameters:
- self : The first operand (minuend).
- other : The second operand (subtrahend).
Returns the difference between the two numbers according to IEEE 754
double-precision arithmetic rules.
Example:
test {
let a = 5.0
let b = 3.0
inspect(a - b, content="2")
inspect(0.0 / 0.0 - 1.0, content="NaN") // NaN - anything = NaN
}ToJson
Trait for types that can be converted to Json
impl ToJson for FixedArray[X]impl ToJson for ReadOnlyArray[T]Converts a Bytes value to a JSON representation.
The representation is picked for easier debugging.
Printable ASCII characters (from space to tilde, excluding '"' and '') are output as-is.
All other bytes are represented as \xHH, where HH is the two-digit hexadecimal value of the byte.
impl ToJson for StringViewToStringView
pub trait ToStringView {
fn to_string_view(Self) -> StringView
}Trait for values that can be viewed as StringView.
Types implementing this trait provide zero-copy access to string-like data.
impl ToStringView for Stringfn to_string_view(self : String) -> StringViewimpl ToStringView for StringViewfn to_string_view(self : StringView) -> StringViewBenchError
#deprecated("This type is deprecated.")
pub(all) suberror BenchError {
BenchError(String)
}Failure
Represents a generic test failure type used primarily in test assertions and
validations.
Since this is a type definition using suberror syntax, it creates an error
type Failure that wraps a String value containing the failure message.
Parameters:
- message : A string describing the nature of the failure.
Example:
test {
let err : Failure = Failure("Test assertion failed")
match err {
Failure(msg) => inspect(msg, content="Test assertion failed")
}
@json.json_inspect(err, content=["Failure", "Test assertion failed"])
}InspectError
pub(all) suberror InspectError {
InspectError(String)
}Represents an error type used by the inspect function to indicate failures
in value inspection. Contains a string message describing the nature of the
inspection failure.
Returns a type constructor that creates an error type from a string message.
Example:
test {
let x : Int = 42
inspect(x, content="42") // A mismatch would raise InspectError with a detailed message
}SnapshotError
pub(all) suberror SnapshotError {
SnapshotError(String)
}Represents an error that occurs during snapshot testing. Contains a string
message describing the error.
Used internally by the test driver to handle snapshot-related errors. Not
intended for direct use by end users.
Example:
test {
let err : SnapshotError = SnapshotError("failed to load snapshot")
match err {
SnapshotError(msg) => @test.assert_eq(msg, "failed to load snapshot")
}
}ArgsLoc
Represents a type for storing argument locations in source code. It is an
array of optional source locations, where each element corresponds to an
argument's location in the source code. Used internally by the compiler for
error reporting and debugging purposes.
ArgsLoc::to_json
Converts an array of optional source locations to its JSON string
representation. Each location in the array is either represented as a JSON
object with filename, start_line, start_column, end_line and
end_column fields if present, or "null" if absent.
Parameters:
- self : The array of optional source locations to be converted.
Returns a JSON array string where each element is either a JSON object
describing a source location or "null".
Array
type Array[T]An Array is a collection of values that supports random access and can
grow in size.
Concatenates two arrays into a new array. The resulting array contains all
elements from the first array followed by all elements from the second array.
Parameters:
- self : The first array to concatenate.
- other : The second array to concatenate.
Returns a new array containing all elements from both arrays in order.
Example:
test {
let a = [1, 2, 3]
let b = [4, 5]
debug_inspect(a + b, content="[1, 2, 3, 4, 5]")
}Compares two arrays based on shortlex order.
First compares the lengths of the arrays. If they differ, returns -1 if the
first array is shorter, 1 if it's longer. If the lengths are equal, compares
elements pairwise until a difference is found or all elements have been
compared.
Parameters:
- self : The first array to compare.
- other : The second array to compare.
Returns an integer that indicates the relative order:
- A negative value if self is less than other
- Zero if self equals other
- A positive value if self is greater than other
Example:
test {
let arr1 = [1, 2, 3]
let arr2 = [1, 2, 4]
let arr3 = [1, 2]
inspect(arr1.compare(arr2), content="-1") // arr1 < arr2
inspect(arr2.compare(arr1), content="1") // arr2 > arr1
inspect(arr1.compare(arr3), content="1") // arr1 > arr3 (longer)
inspect(arr1.compare(arr1), content="0") // arr1 = arr1
}Compares two arrays for equality. Returns true if both arrays have the same
length and contain equal elements in the same order.
Parameters:
- self : The first array to compare.
- other : The second array to compare.
Returns true if the arrays are equal, false otherwise.
Example:
test {
let arr1 = [1, 2, 3]
let arr2 = [1, 2, 3]
let arr3 = [1, 2, 4]
inspect(arr1 == arr2, content="true")
inspect(arr1 == arr3, content="false")
}Array::Array
Creates a new empty array with an optional initial capacity.
Parameters:
- capacity : The initial capacity of the array. If 0 (default), creates an array with minimum capacity. Must be non-negative.
Returns a new empty array of type Array[T] with the specified initial
capacity.
Example:
test {
let arr : Array[Int] = Array(capacity=10)
inspect(arr.length(), content="0")
inspect(arr.capacity(), content="10")
let arr : Array[Int] = Array()
inspect(arr.length(), content="0")
}Array::all
Checks whether all elements satisfy the predicate.
Example
test {
let arr = [1, 2, 3, 4, 5]
assert_true(arr.all(x => x < 6))
assert_false(arr.all(x => x < 5))
}Array::any
Checks whether any element satisfies the predicate.
Example
test {
let arr = [1, 2, 3, 4, 5]
assert_true(arr.any(x => x < 6))
assert_false(arr.any(x => x < 1))
}Array::append
Appends all elements from one array to the end of another array. The elements
are added in-place, modifying the original array.
Parameters:
- self : The array to append to.
- other : The array whose elements will be appended.
Example:
test {
let v1 = [1, 2, 3]
let v2 : ReadOnlyArray[Int] = [4, 5, 6]
v1.append(v2)
debug_inspect(v1, content="[1, 2, 3, 4, 5, 6]")
let v1 = [1, 2, 3]
let v2 : ReadOnlyArray[Int] = []
v1.append(v2)
debug_inspect(v1, content="[1, 2, 3]")
}Array::at
Retrieves an element from the array at the specified index.
Parameters:
- array : The array to get the element from.
- index : The position in the array from which to retrieve the element.
Returns the element at the specified index.
Throws a panic if the index is negative or greater than or equal to the
length of the array.
Example:
test {
let arr : Array[Int] = [1, 2, 3]
inspect(arr[1], content="2")
}Array::binary_search
Performs a binary search on a sorted array to find the index of a given element.
Example
test {
let v = [3, 4, 5]
let result = v.binary_search(3)
@test.assert_eq(result, Ok(0)) // The element 3 is found at index 0
}Arguments
- self: The array in which to perform the search.
- value: The element to search for in the array.
Returns
- Result[Int, Int]: If the element is found, an Ok variant is returned, containing the index of the matching element in the array. If there are multiple matches, the leftmost match will be returned. If the element is not found, an Err variant is returned, containing the index where the element could be inserted to maintain the sorted order.
Notes
- Ensure that the array is sorted in increasing order before calling this function.
- If the array is not sorted, the returned result is undefined and should not be relied on.
Array::binary_search_by
Performs a binary search on a sorted array using a custom comparison
function. Returns the position of the matching element if found, or the
position where the element could be inserted while maintaining the sorted
order.
Parameters:
- array : The sorted array to search in.
- comparator : A function that compares each element with the target value, returning:
- A negative integer if the element is less than the target
- Zero if the element equals the target
- A positive integer if the element is greater than the target
Returns a Result containing either:
- Ok(index) if a matching element is found at position index
- Err(index) if no match is found, where index is the position where the element could be inserted
Example:
test {
let arr = [1, 3, 5, 7, 9]
let find_3 = arr.binary_search_by(x => x.compare(3))
debug_inspect(find_3, content="Ok(1)")
let find_4 = arr.binary_search_by(x => x.compare(4))
debug_inspect(find_4, content="Err(2)")
}Notes:
- Assumes the array is sorted according to the ordering implied by the comparison function
- For multiple matches, returns the leftmost matching position
- Returns an insertion point that maintains the sort order when no match is found
Array::blit_to
Copies elements from one array to another array, with support for growing the
destination array if needed. The arrays may overlap, in which case the copy
is performed in a way that preserves the data.
Parameters:
- self : The array to copy elements from.
- dst : The array to copy elements to. Will be automatically grown if needed to accommodate the copied elements.
- len : The number of elements to copy.
- src_offset : Starting index in the source array. Defaults to 0.
- dst_offset : Starting index in the destination array. Defaults to
Example:
test {
let src = [1, 2, 3, 4, 5]
let dst = [0, 0]
src[:3].blit_to(dst, dst_offset=1)
@debug.debug_inspect(dst, content="[0, 1, 2, 3]")
}Panics if:
- len is negative
- src_offset is negative
- dst_offset is negative
- dst_offset exceeds the length of destination array
- src_offset + len exceeds the length of source array
Array::capacity
Returns the total capacity of the array, which is the number of elements that
the array can hold without requiring reallocation of its internal buffer.
Parameters:
- array : The array whose capacity is to be determined.
Returns the current capacity of the array as an integer.
NOTE: The capacity of an array may not be consistent across different backends
and/or different versions of the MoonBit compiler/core.
Array::chunk_by
Groups consecutive elements of the array into chunks where adjacent elements
satisfy the given predicate function.
Parameters:
- array : The array to be chunked.
- predicate : A function that takes two adjacent elements and returns true if they should be in the same chunk, false otherwise.
Returns an array of views, where each view is a chunk of consecutive
elements that satisfy the predicate with their adjacent elements.
Example:
test {
let v = [1, 1, 2, 3, 2, 3, 2, 3, 4]
let chunks = v.chunk_by((x, y) => x <= y)
debug_inspect(
chunks,
content=(
#|[
#| <ArrayView: [1, 1, 2, 3]>,
#| <ArrayView: [2, 3]>,
#| <ArrayView: [2, 3, 4]>,
#|]
),
)
let v : Array[Int] = []
debug_inspect(v.chunk_by((x, y) => x <= y), content="[]")
}Array::chunks
Divides an array into chunks (views) of the specified size.
Parameters:
- array : The array to be divided into chunks.
- size : The size of each chunk. Must be a positive integer, otherwise it will panic.
Returns an array of views, where each view is a chunk containing consecutive
elements of the original array. If the length of the original array is not
divisible by the chunk size, the last chunk will contain fewer elements.
Example:
test {
let arr = [1, 2, 3, 4, 5]
let chunks = arr.chunks(2)
debug_inspect(
chunks,
content=(
#|[<ArrayView: [1, 2]>, <ArrayView: [3, 4]>, <ArrayView: [5]>]
),
)
let arr : Array[Int] = []
debug_inspect(arr.chunks(3), content="[]")
}Array::clear
Clears the array, removing all values.
This method has no effect on the allocated capacity of the array, only setting the length to 0.
Emptying an array is a removal like any other: the buffer keeps referring to
the elements that were in it, and they are released once later pushes reuse
those slots, the buffer grows, or the array is dropped. Call
Array::release_unused to overwrite them at once, or Array::shrink_to_fit
to hand the buffer back entirely. On the JavaScript backend the removed
elements are released right away and Array::release_unused is a no-op.
Example
test {
let v = [3, 4, 5]
v.clear()
@test.assert_eq(v.length(), 0)
}Array::contains
Checks whether the array contains an element equal to the given value.
Parameters:
- array : The array to search in.
- value : The value to search for.
Returns true if the array contains an element equal to the given value,
false otherwise.
Example:
test {
let arr = [1, 2, 3, 4, 5]
inspect(arr.contains(3), content="true")
inspect(arr.contains(6), content="false")
let arr : Array[Int] = []
inspect(arr.contains(1), content="false")
}Array::copy
Creates and returns a new array with a copy of all elements from the input
array.
Parameters:
- array : The array to be copied.
Returns a new array containing all elements from the original array.
Example:
test {
let original = [1, 2, 3]
let copied = original.copy()
@debug.debug_inspect(copied, content="[1, 2, 3]")
inspect(physical_equal(original, copied), content="false")
}Array::count
Counts how many elements in the array are equal to value.
Example
test {
let arr = [1, 2, 1, 3, 1]
inspect(arr.count(1), content="3")
inspect(arr.count(4), content="0")
}Array::count_if
Counts how many elements in the array satisfy the predicate.
Example
test {
let arr = [1, 2, 3, 4, 5]
inspect(arr.count_if(x => x % 2 == 0), content="2")
}Array::dedup
Removes consecutive duplicate elements from an array in-place, using equality
comparison. The first occurrence of each element is retained while subsequent
equal elements are removed.
Parameters:
- array : The array to remove duplicates from. Must contain elements that implement the Eq trait for equality comparison.
Example:
test {
let arr = [1, 2, 2, 3, 3, 3, 2]
arr.dedup()
debug_inspect(arr, content="[1, 2, 3, 2]")
let arr = [1, 2, 2, 2, 3, 3]
arr.dedup()
debug_inspect(arr, content="[1, 2, 3]")
let arr : Array[Int] = []
arr.dedup()
debug_inspect(arr, content="[]")
}Note: For best results when removing all duplicates regardless of position,
sort the array before calling this function. When used on an unsorted array,
this function only removes consecutive duplicates.
Array::drain
Removes the specified range from the array and returns it.
This functions returns an array range from begin to end [begin, end)
This function will panic if the index is out of bounds.
Example
test {
let v = [3, 4, 5]
let vv = v.drain(1, 2) // vv = [4], v = [3, 5]
@test.assert_eq(vv, [4])
@test.assert_eq(v, [3, 5])
}The end - begin slots vacated at the end of the array are not cleared:
each keeps whatever it held before the survivors were shifted down, so a
drained element or a duplicate reference to a survivor stays reachable
there until the slot is reused, the buffer grows, or the array is dropped.
Call Array::release_unused to overwrite them at once, or
Array::shrink_to_fit to move the survivors into an exact-size buffer.
Array::each
Iterates through each element of the array in order, applying the given
function to each element.
Parameters:
- array : The array to iterate over.
- function : A function that takes a single element of type T as input and returns Unit. This function is applied to each element of the array in order.
Example:
test {
let arr = [1, 2, 3]
let mut sum = 0
arr.each(x => sum x)
inspect(sum, content="6")
}This method uses the array iterator. Structural mutations during traversal
are unsupported: appended elements are not visited, and shrinking the array
with operations such as remove, truncate, clear, or drain may cause
later iterator steps to fail.
Array::eachi
Iterates over the elements of the array with index.
Example
test {
let v = [3, 4, 5]
let mut sum = 0
v.eachi((i, x) => sum x + i)
inspect(sum, content="15")
}Array::ends_with
Tests if an array ends with the given suffix.
Parameters:
- self : The array to check.
- suffix : The array to test against.
Returns true if the array ends with the given suffix, false otherwise.
Example:
test {
let arr = [1, 2, 3, 4, 5]
inspect(arr.ends_with([4, 5]), content="true")
inspect(arr.ends_with([3, 4]), content="false")
inspect(arr.ends_with([]), content="true")
let arr : Array[Int] = []
inspect(arr.ends_with([]), content="true")
inspect(arr.ends_with([1]), content="false")
}Array::extract_if
Extracts elements from an array that satisfy a given predicate function. The
extracted elements are removed from the original array and returned as a new
array. The relative order of the extracted elements is preserved.
Parameters:
- array : The array to extract elements from.
- predicate : A function that takes an element and returns true if the element should be extracted, false otherwise.
Returns a new array containing all elements that satisfy the predicate
function, in the order they appeared in the original array.
Example:
test {
let arr = [1, 2, 3, 4, 5]
let extracted = arr.extract_if(x => x % 2 == 0)
debug_inspect(extracted, content="[2, 4]")
debug_inspect(arr, content="[1, 3, 5]")
}Array::fill
Fills an Array with a specified value.
This method fills all or part of an Array with the given value.
Parameters
- value: The value to fill the array with
- start: The starting index (inclusive, default: 0)
- end: The ending index (exclusive, optional)
If end is not provided, fills from start to the end of the array.
If start equals end, no elements are modified.
Panics
- Panics if start is negative or greater than or equal to the array length
- Panics if end is provided and is less than start or greater than array length
- Does nothing if the array is empty
Example
test {
// Fill entire array
let arr = [1, 2, 3, 4, 5]
arr.fill(0)
@debug.debug_inspect(arr, content="[0, 0, 0, 0, 0]")
// Fill from index 1 to 3 (exclusive)
let arr2 = [1, 2, 3, 4, 5]
arr2.fill(99, start=1, end=3)
@debug.debug_inspect(arr2, content="[1, 99, 99, 4, 5]")
// Fill from index 2 to end
let arr3 = ["a", "b", "c", "d"]
arr3.fill("x", start=2)
@debug.debug_inspect(
arr3,
content=(
#|["a", "b", "x", "x"]
),
)
}Array::filter
Creates a new array containing all elements from the input array that satisfy
the given predicate function.
Parameters:
- array : The array to filter.
- predicate : A function that takes an element and returns a boolean indicating whether the element should be included in the result.
Returns a new array containing only the elements for which the predicate
function returns true. The relative order of the elements is preserved.
Example:
test {
let arr = [1, 2, 3, 4, 5]
let evens = arr.filter(x => x % 2 == 0)
debug_inspect(evens, content="[2, 4]")
}Array::filter_map
Applies a function to each element of the array and collects the results
that are Some, discarding the elements for which the function returns
None.
Arguments
- self - The array to filter and map.
- f - The function applied to each element, returning Some(value) to keep the mapped value, or None to drop the element.
Returns
A new array containing the unwrapped Some results, in the order the
corresponding elements appeared in the original array.
Array::flatten
Flattens an array of arrays into an array.
Example:
test {
let v = [[3, 4], [5, 6]].flatten()
@test.assert_eq(v, [3, 4, 5, 6])
}Array::fold
Fold out values from an array according to certain rules.
This method traverses the array through self.iter(), so the traversal
bounds are fixed when folding starts.
Structural mutations to self inside f are unsupported. Appended
elements are not visited, and shrinking the array with operations such as
remove, truncate, clear, or drain may cause later fold steps to
fail.
Example:
test {
let sum = [1, 2, 3, 4, 5].fold(init=0, (sum, elem) => sum + elem)
@test.assert_eq(sum, 15)
}Array::foldi
Fold out values from an array according to certain rules with index.
Example:
test {
let sum = [1, 2, 3, 4, 5].foldi(init=0, (index, sum, _elem) => sum + index)
@test.assert_eq(sum, 10)
}Array::from_fixed_array
Creates a new dynamic array from a fixed-size array.
Parameters:
- arr : The fixed-size array to convert. The elements of this array will be copied to the new array.
Returns a new dynamic array containing all elements from the input fixed-size
array.
Example:
test {
let fixed = FixedArray::make(3, 42)
let dynamic = Array::from_fixed_array(fixed)
debug_inspect(dynamic, content="[42, 42, 42]")
}Array::from_iter
Creates a new array containing all elements from an iterator.
Parameters:
- iterator : An iterator containing elements of type T.
Returns a new array containing all elements from the iterator in the same
order.
Example:
test {
let iter = 42
let arr = Array::from_iter(iter)
debug_inspect(arr, content="[42]")
}Array::get
Retrieves the element at the specified index from the array.
Parameters:
- self : The array to get the element from.
- index : The position in the array from which to retrieve the element.
Returns Some(element) if the index is within bounds, or None if the index
is out of bounds.
Example:
test {
let arr = [1, 2, 3]
debug_inspect(arr.get(-1), content="None")
debug_inspect(arr.get(0), content="Some(1)")
debug_inspect(arr.get(3), content="None")
}Array::get_view
Creates a view of a portion of the array, returning None when indices are
invalid.
Parameters:
- array : The array to create a view from.
- start : The starting index of the view (inclusive). Defaults to 0.
- end : The ending index of the view (exclusive). If not provided, defaults to the length of the array.
Returns Some(ArrayView) that provides a window into the specified portion
of the array, or None when the indices are invalid.
Example:
test {
let arr = [1, 2, 3, 4, 5]
let start = 1
let end = 4
debug_inspect(
arr.get_view(start~, end~),
content=(
#|Some(<ArrayView: [2, 3, 4]>)
),
)
let start = 3
let end = 10
debug_inspect(arr.get_view(start~, end~), content="None")
}Array::insert
Inserts an element at a given index within the array.
This function will panic if the index is out of bounds.
Example
test {
let a = [1, 2, 3]
a.insert(1, 4)
@debug.debug_inspect(a, content="[1, 4, 2, 3]")
let b = [1, 2, 3]
b.insert(0, 5)
@debug.debug_inspect(b, content="[5, 1, 2, 3]")
let c = [1, 2, 3]
c.insert(3, 6)
@debug.debug_inspect(c, content="[1, 2, 3, 6]")
}Array::is_empty
Tests whether the array contains no elements.
Parameters:
- array : The array to check.
Returns true if the array has no elements, false otherwise.
Example:
test {
let empty : Array[Int] = []
inspect(empty.is_empty(), content="true")
let non_empty = [1, 2, 3]
inspect(non_empty.is_empty(), content="false")
}Array::is_sorted
Tests whether the array is sorted in ascending order.
Parameters:
- self : The array to be tested.
- T : The type of elements in the array. Must implement the Compare trait.
Returns a boolean value indicating whether the array is sorted in ascending
order:
- true if the array is empty, contains only one element, or all elements are in ascending order.
- false if any element is greater than the element that follows it.
Example:
test {
let ascending = [1, 2, 3, 4, 5]
let descending = [5, 4, 3, 2, 1]
let unsorted = [1, 3, 2, 4, 5]
inspect(ascending.is_sorted(), content="true")
inspect(descending.is_sorted(), content="false")
inspect(unsorted.is_sorted(), content="false")
}Array::iter
Creates an iterator over the elements of the array.
Parameters:
- array : The array to create an iterator from.
Returns an iterator that yields each element of the array in order.
This iterator is created from self[:], so the traversal bounds are fixed
when iteration starts.
Structural mutations after the iterator is created are unsupported.
Appended elements are not visited, and shrinking the array with operations
such as remove, truncate, clear, or drain may cause later iterator
steps to fail. The same caveat applies to rev_iter(), iter2(), and
helpers built on top of them such as each(), eachi(), and fold().
Example:
test {
let arr = [1, 2, 3]
let mut sum = 0
arr.iter().each(x => sum x)
inspect(sum, content="6")
}Array::iter2
Returns an iterator that provides both indices and values of the array in
order.
Parameters:
- self : The array to iterate over.
Returns an iterator that yields tuples of index and value pairs, where
indices start from 0.
Example:
test {
let arr = [10, 20, 30]
let mut sum = 0
arr.iter2().each((i, x) => sum i + x)
inspect(sum, content="63") // (0 + 10) + (1 + 20) + (2 + 30) = 63
}Array::join
Join an array of strings using the provided separator.
Parameters:
- separator : The string inserted between each element.
Returns a single concatenated String.
Example:
test {
let s = "hello world"
inspect(s.split(" ").to_array().join(":"), content="hello:world")
}Array::last
Returns the last element of the array, or None if the array is empty.
Parameters:
- array : The array to get the last element from.
Returns an optional value containing the last element of the array. The
result is None if the array is empty, or Some(x) where x is the last
element of the array.
Example:
test {
let arr = [1, 2, 3]
debug_inspect(arr.last(), content="Some(3)")
let empty : Array[Int] = []
debug_inspect(empty.last(), content="None")
}Array::length
Returns the number of elements in the array.
Parameters:
- array : The array whose length is to be determined.
Returns the number of elements in the array as an integer.
Example:
test {
let arr : Array[Int] = [1, 2, 3]
inspect(arr.length(), content="3")
let empty : Array[Int] = []
inspect(empty.length(), content="0")
}Array::lexical_compare
Performs a lexicographical comparison of two arrays.
This method compares the arrays element by element until a difference is
found or one array is exhausted. Unlike the Compare trait implementation
which uses shortlex order (shorter arrays come first), this method compares
based purely on element values until a difference is found.
Returns
- A negative integer if self is lexicographically less than other
- Zero if self is lexicographically equal to other
- A positive integer if self is lexicographically greater than other
Example
test {
inspect([1, 2].lexical_compare([1, 2, 3]), content="-1")
inspect([1, 2, 3].lexical_compare([1, 2]), content="1")
inspect([1, 2, 3].lexical_compare([1, 2, 3]), content="0")
inspect([1, 2, 3].lexical_compare([1, 2, 4]), content="-1")
}Array::make
Creates a new array with a specified length and initializes all elements with
the given value.
Parameters:
- length : The length of the array to create. Must be a non-negative integer.
- initial_value : The value used to initialize all elements in the array.
Returns a new array of type Array[T] with length elements, where each
element is initialized to initial_value.
Throws an error if length is negative.
Example:
test {
let arr = Array::make(3, 42)
debug_inspect(arr, content="[42, 42, 42]")
}WARNING: A common pitfall is creating with the same initial value, for example:
test {
let two_dimension_array = Array::make(10, Array::make(10, 0))
two_dimension_array[0][5] = 10
@test.assert_eq(two_dimension_array[5][5], 10)
}This is because all the cells reference to the same object (the Array[Int] in this case).
One should use makei() instead which creates an object for each index.
Array::makei
Creates a new array of the specified length, where each element is
initialized using an index-based initialization function.
Parameters:
- length : The length of the new array. If length is less than or equal to 0, returns an empty array.
- initializer : A function that takes an index (starting from 0) and returns a value of type T. This function is called for each index to initialize the corresponding element.
Returns a new array of type Array[T] with the specified length, where each
element is initialized using the provided function.
Example:
test {
let arr = Array::makei(3, i => i * 2)
debug_inspect(arr, content="[0, 2, 4]")
}Array::map
Maps a function over the elements of the array.
Example
test {
let v = [3, 4, 5]
let v2 = v.map(x => x + 1)
@test.assert_eq(v2, [4, 5, 6])
}Array::map_in_place
Maps a function over the elements of the array in place.
Example
test {
let v = [3, 4, 5]
v.map_in_place(x => x + 1)
@test.assert_eq(v, [4, 5, 6])
}Array::mapi
Maps a function over the elements of the array with index.
Example
test {
let v = [3, 4, 5]
let v2 = v.mapi((i, x) => x + i)
@test.assert_eq(v2, [3, 5, 7])
}Array::mapi_in_place
Maps a function over the elements of the array with index in place.
Example
test {
let v = [3, 4, 5]
v.mapi_in_place((i, x) => x + i)
@test.assert_eq(v, [3, 5, 7])
}Array::mut_view
Creates a mutable view of a portion of the array. The view provides read-write access
to the underlying array without copying the elements.
Parameters:
- array : The array to create a view from.
- start : The starting index of the view (inclusive). Defaults to 0.
- end : The ending index of the view (exclusive). If not provided, defaults to the length of the array.
Returns a MutArrayView that provides a window into the specified portion of
the array.
Throws a panic if the indices are invalid (i.e., start is negative, end
is greater than the array length, or start is greater than end).
Example:
test {
let arr = [1, 2, 3, 4, 5]
let view = arr.mut_view(start=1, end=4) // Create a view of elements at indices 1, 2, and 3
inspect(view[0], content="2") // First element of view is arr[1]
inspect(view.length(), content="3") // View contains 3 elements
}Array::new
Creates a new empty array with an optional initial capacity.
Deprecated: use Array(capacity=...) instead.
Array::pop
Removes the last element from an array and returns it, or None if it is empty.
The vacated slot goes on referring to the returned element, so an
ArrayView created beforehand keeps observing that element, and it is
released only once a later push reuses the slot, the buffer grows, or the
buffer is dropped. Call Array::release_unused to release it at once.
Example
test {
let v = [1, 2, 3]
@test.assert_eq(v.pop(), Some(3))
@test.assert_eq(v, [1, 2])
}Array::push
Adds an element to the end of the array.
If the array is at capacity, it will be reallocated.
Example
test {
let v = []
v.push(3)
}Array::push_iter
Adds all elements from an iterator to the end of the array.
This function iterates over each element in the provided iterator
and adds them to the array using the push method.
Example
test {
let u = [1, 2, 3]
let v = [4, 5, 6]
u.push_iter(v.iter())
@test.assert_eq(u, [1, 2, 3, 4, 5, 6])
}Array::release_unused
Overwrites the array's unused capacity -- every slot from length() up to
capacity() -- with placeholder, releasing whatever those slots held.
Shrinking an array never clears the slots it vacates, so whatever they held
-- a removed element, or a duplicate reference to a survivor that was
shifted over it -- stays reachable from the buffer and unreleased until
later pushes reuse those slots, the buffer grows, or the array is dropped.
This releases them on demand without reallocating, which is what
Array::pop, Array::remove, Array::retain and the other operations
that take no placeholder leave outstanding. Array::shrink_to_fit releases
them too, but by allocating an exact-size buffer and copying every survivor
into it; this costs one pass over the unused region and no allocation.
An ArrayView created before the call observes placeholder in that region
afterwards, in place of whatever it held.
This only matters for element types holding references -- for types such as
Int there is nothing to release and the call merely costs a pass over the
buffer.
Example:
test {
let arr = ["a", "b", "c"]
let _ = arr.pop()
arr.release_unused(placeholder="")
debug_inspect(arr, content="[\"a\", \"b\"]")
}Array::remove
Removes and returns the element at position index within the array,
shifting all elements after it to the left.
This function will panic if the index is out of bounds.
Example
test {
let v = [3, 4, 5]
@test.assert_eq(v.remove(1), 4)
@test.assert_eq(v, [3, 5])
}Array::repeat
Create an array by repeating self times times.
Aborts if times is negative. When times is 0, returns an empty array.
Example:
test {
let v = [3, 4].repeat(2)
@test.assert_eq(v, [3, 4, 3, 4])
}Array::reserve_capacity
Reserves capacity to ensure that it can hold at least the number of elements
specified by the capacity argument.
Example
test {
let v = [1]
v.reserve_capacity(10)
@test.assert_eq(v.capacity(), 10)
}Array::resize
Resizes an array to a specified length, either by truncating if the new
length is smaller, or by appending copies of a default value if the new
length is larger.
Parameters:
- array : The array to be resized.
- new_length : The desired length of the array after resizing.
- default_value : The value to append when extending the array.
Throws a panic if new_length is negative.
Examples:
test {
let arr = [1, 2, 3, 4, 5]
arr.resize(3, 0)
debug_inspect(arr, content="[1, 2, 3]")
let arr = [1, 2, 3]
arr.resize(5, 0)
debug_inspect(arr, content="[1, 2, 3, 0, 0]")
}Array::retain
Removes all elements from the array that do not satisfy the predicate
function, modifying the array in place. The order of remaining elements is
preserved.
Parameters:
- array : The array to be filtered.
- predicate : A function that takes an element and returns true if the element should be kept, false if it should be removed.
Example:
test {
let arr = [1, 2, 3, 4, 5]
arr.retain(x => x % 2 == 0)
debug_inspect(arr, content="[2, 4]")
let arr = [1, 2, 3]
arr.retain(x => x > 10)
debug_inspect(arr, content="[]")
let arr = [1, 2, 3]
arr.retain(_ => true)
debug_inspect(arr, content="[1, 2, 3]")
}Array::retain_map
In-place filter and map for Array
Example
test {
let arr = [1, 2, 3, 4, 5]
arr.retain_map(fn(x) { if x % 2 == 0 { Some(x * 2) } else { None } })
debug_inspect(arr, content="[4, 8]")
}Array::rev
Creates a new array with elements in reversed order.
Parameters:
- self : The array to be reversed.
Returns a new array containing the same elements as the input array but in
reverse order. The original array remains unchanged.
Example:
test {
let arr = [1, 2, 3, 4, 5]
debug_inspect(arr.rev(), content="[5, 4, 3, 2, 1]")
debug_inspect(arr, content="[1, 2, 3, 4, 5]") // original array unchanged
}Array::rev_each
Iterates over the elements of the array in reverse order, applying the given
function to each element.
Parameters:
- array : The array to iterate over.
- f : A function that takes an element of type T and returns Unit. This function is applied to each element of the array in reverse order.
Example:
test {
let v = [3, 4, 5]
let mut sum = 0
v.rev_each(x => sum = sum - x)
@json.json_inspect(sum, content=-12)
}Array::rev_eachi
Iterates over the elements of the array with index in reversed order.
Example
test {
let v = [3, 4, 5]
let mut sum = 0
v.rev_eachi((i, x) => sum x + i)
@test.assert_eq(sum, 15)
}Array::rev_fold
Fold out values from an array according to certain rules in reversed turn.
Example:
test {
let sum = [1, 2, 3, 4, 5].rev_fold(init=0, (sum, elem) => sum + elem)
@test.assert_eq(sum, 15)
}Array::rev_foldi
Fold out values from an array according to certain rules in reversed turn with index.
Example:
test {
let sum = [1, 2, 3, 4, 5].rev_foldi(init=0, (index, sum, _elem) => sum + index)
@test.assert_eq(sum, 10)
}Array::rev_in_place
Reverses the order of elements in an array in place, modifying the original
array.
Parameters:
- self : The array to be reversed.
Example:
test {
let arr = [1, 2, 3, 4, 5]
arr.rev_in_place()
debug_inspect(arr, content="[5, 4, 3, 2, 1]")
let arr : Array[Int] = []
arr.rev_in_place()
debug_inspect(arr, content="[]")
}Array::rev_iter
Returns an iterator that yields elements from the array in reverse order,
from the last element to the first.
Parameters:
- array : The array to iterate over in reverse order.
Returns an iterator that yields each element of the array, starting from the
last element and moving towards the first.
Example:
test {
let arr = [1, 2, 3]
let result = []
arr.rev_iter().each(x => result.push(x))
debug_inspect(result, content="[3, 2, 1]")
}Array::search
Searches for the first occurrence of a value in the array and returns its
index.
Parameters:
- self : The array to search in.
- value : The value to search for.
Returns an Option containing the index of the first occurrence of value
if found, or None if the value is not present in the array.
Example:
test {
let arr = [1, 2, 3, 2, 4]
debug_inspect(arr.search(2), content="Some(1)") // first occurrence
debug_inspect(arr.search(5), content="None") // not found
}Array::search_by
Search the index of the first element that satisfies the predicate.
Example
test {
let v = [1, 2, 3, 4, 5]
match v.search_by(x => x == 3) {
Some(index) => @test.assert_eq(index, 2) // 2
None => println("Not found")
}
}Array::set
Sets the element at the specified index in the array to a new value. The
original value at that index is overwritten.
Parameters:
- array : The array to modify.
- index : The position in the array where the value will be set.
- value : The new value to assign at the specified index.
Throws an error if index is negative or greater than or equal to the length
of the array.
Example:
test {
let arr = [1, 2, 3]
arr[1] = 42
debug_inspect(arr, content="[1, 42, 3]")
}Array::shrink_to_fit
Shrinks the capacity of the array as much as possible.
Example
test {
let v = Array(capacity=10)
v.push(1)
v.push(2)
v.push(3)
v.shrink_to_fit()
@test.assert_eq(v.capacity(), 3)
}The survivors are copied into the new buffer and the old one is released
with them, so this also releases whatever earlier removals left in the
unused capacity. It pays an allocation plus a copy of every survivor to do
so; Array::release_unused releases the same elements in one pass over the
unused region and no allocation, at the cost of leaving the capacity alone.
Array::shuffle
Shuffle the array using Knuth shuffle
To use this function, you need to provide a rand function, which takes an integer as it upper bound
and returns an integer.
rand n is expected to returns a uniformly distribution integer between 0 and n - 1
Example
let arr = [1, 2, 3, 4, 5]
fn rand(upper : Int) -> Int {
let rng = @random.Rand::new()
rng.int(limit=upper)
}
let _shuffled = Array::shuffle(arr, rand~)Array::shuffle_in_place
Shuffle the array using Knuth shuffle
To use this function, you need to provide a rand function, which takes an integer as it upper bound
and returns an integer.
rand n is expected to returns a uniformly distribution integer between 0 and n - 1
Example
test {
let arr = [1, 2, 3, 4, 5]
fn rand(upper : Int) -> Int {
let rng = @random.Rand::new()
rng.int(limit=upper)
}
Array::shuffle_in_place(arr, rand~)
}Array::sort
Sorts the array in place.
It's an in-place, unstable sort(it will reorder equal elements). The time complexity is O(n log n) in the worst case.
Example
test {
let arr = [5, 4, 3, 2, 1]
arr.sort()
@test.assert_eq(arr, [1, 2, 3, 4, 5])
}Array::sort_by
Sorts the array with a custom comparison function.
It's an in-place, unstable sort(it will reorder equal elements). The time complexity is O(n log n) in the worst case.
Example
test {
let arr = [5, 3, 2, 4, 1]
arr.sort_by((a, b) => a - b)
@test.assert_eq(arr, [1, 2, 3, 4, 5])
}Array::sort_by_key
Sorts the array with a key extraction function.
It's an in-place, unstable sort(it will reorder equal elements). The time complexity is O(n log n) in the worst case.
Example
test {
let arr = [5, 3, 2, 4, 1]
arr.sort_by_key(x => -x)
@test.assert_eq(arr, [5, 4, 3, 2, 1])
}Array::split
Splits an array into chunks using a predicate function. Creates chunks by
grouping consecutive elements that do not satisfy the predicate function.
Elements that satisfy the predicate function are excluded from the resulting
chunks and act as delimiters.
Parameters:
- array : The array to be split into chunks.
- predicate : A function that takes an element and returns true if the element should be used as a delimiter.
Returns an array of arrays, where each inner array is a chunk of consecutive
elements that do not satisfy the predicate.
Example:
test {
let arr = [1, 0, 2, 0, 3, 0, 4]
debug_inspect(arr.split(x => x == 0), content="[[1], [2], [3], [4]]")
let arr = [0, 1, 0, 0, 2, 0]
debug_inspect(arr.split(x => x == 0), content="[[], [1], [], [2]]")
}Array::starts_with
Checks if the array begins with all elements of the provided prefix array in
order.
Parameters:
- self : The array to check against.
- prefix : The array containing the sequence of elements to look for at the beginning.
Returns true if the array starts with all elements in prefix in the same
order, false otherwise. An empty prefix array always returns true, and a
prefix longer than the array always returns false.
Example:
test {
let arr = [1, 2, 3, 4, 5]
inspect(arr.starts_with([1, 2]), content="true")
inspect(arr.starts_with([2, 3]), content="false")
inspect(arr.starts_with([]), content="true")
inspect(arr.starts_with([1, 2, 3, 4, 5, 6]), content="false")
}Array::strip_prefix
Strip a prefix from the array.
If the array starts with the prefix, return a view of the array after the
prefix, otherwise return None. The returned view shares the original
backing array — no allocation.
Example
test {
let v = [1, 2, 3, 4, 5]
let v2 = v.strip_prefix([1, 2])
debug_inspect(
v2,
content=(
#|Some(<ArrayView: [3, 4, 5]>)
),
)
}Array::strip_suffix
Strip a suffix from the array.
If the array ends with the suffix, return a view of the array before the
suffix, otherwise return None. The returned view shares the original
backing array — no allocation.
Example
test {
let v = [3, 4, 5]
let v2 = v.strip_suffix([5])
debug_inspect(
v2,
content=(
#|Some(<ArrayView: [3, 4]>)
),
)
}Array::suffixes
Return an iterator over all suffix views of this array.
Suffixes are yielded from longest to shortest. Set include_empty=true to
include the final empty suffix.
Example:
test {
let xs = [1, 2]
debug_inspect(
xs.suffixes().collect(),
content=(
#|[<ArrayView: [1, 2]>, <ArrayView: [2]>]
),
)
debug_inspect(
xs.suffixes(include_empty=true).collect(),
content=(
#|[<ArrayView: [1, 2]>, <ArrayView: [2]>, <ArrayView: []>]
),
)
}Array::swap
Swaps the values at two positions in the array.
Parameters:
- array : The array in which to swap elements.
- index1 : The index of the first element to be swapped.
- index2 : The index of the second element to be swapped.
This function will panic if either index is negative or greater than or equal to
the length of the array.
Example:
test {
let arr = [1, 2, 3]
arr.swap(0, 2)
debug_inspect(arr, content="[3, 2, 1]")
}Array::truncate
Truncates the array in-place to the specified length.
If len is greater than or equal to the current array length,
the function does nothing. If len is 0, the array is cleared.
Otherwise, removes elements from the end until the array reaches the given length.
Parameters:
- self : The target array (modified in-place).
- len : The new desired length (must be non-negative).
Important:
- If len is negative, the function does nothing.
- If len exceeds current length, the array remains unchanged.
Elements beyond len are removed from the array, but the backing buffer
keeps referring to them: they are released once those slots are reused by
later pushes, once the buffer grows, or once the array is dropped. Call
Array::release_unused to overwrite them at once, or Array::shrink_to_fit
to move the survivors into an exact-size buffer. On the JavaScript backend
the removed elements are released right away and Array::release_unused is a
no-op.
Example:
test {
let arr = [1, 2, 3, 4, 5]
arr.truncate(3)
debug_inspect(arr, content="[1, 2, 3]")
}Array::unsafe_blit_fixed
Copies elements from a fixed-size array to a dynamic array. The arrays may
overlap, in which case the copy is performed in a way that preserves the
data.
Parameters:
- dst : The destination dynamic array where elements will be copied to.
- dst_offset : The starting index in the destination array where copying begins.
- src : The source fixed-size array from which elements will be copied.
- src_offset : The starting index in the source array from which copying begins.
- len : The number of elements to copy.
Example:
test {
let src = FixedArray::make(5, 0)
let dst = Array::make(5, 0)
for i in 0..<5 {
src[i] = i + 1
}
Array::unsafe_blit_fixed(dst, 1, src, 0, 2)
@debug.debug_inspect(dst, content="[0, 1, 2, 0, 0]")
}Array::unsafe_get
Retrieves the element at the specified index from an array without bounds
checking.
Parameters:
- array : The array from which to retrieve the element.
- index : The position in the array from which to retrieve the element.
Returns the element at the specified index.
Example:
test {
let arr : Array[Int] = [1, 2, 3]
inspect(arr.unsafe_get(1), content="2")
}Array::unsafe_set
Write val to idx without bounds checking.
This is unsafe: caller must ensure 0 <= idx < self.length().
Example:
test {
let arr = [1, 2, 3]
arr.unsafe_set(1, 99)
debug_inspect(arr, content="[1, 99, 3]")
}Array::unzip
Splits an array of pairs into two arrays, separating the first and second elements.
Example
test {
let arr = [(1, "a"), (2, "b"), (3, "c")]
let (nums, strs) = arr.unzip()
debug_inspect(nums, content="[1, 2, 3]")
debug_inspect(strs, content="[\"a\", \"b\", \"c\"]")
}Array::view
Creates a view of a portion of the array. The view provides read-only access
to the underlying array without copying the elements.
Parameters:
- array : The array to create a view from.
- start : The starting index of the view (inclusive). Defaults to 0.
- end : The ending index of the view (exclusive). If not provided, defaults to the length of the array.
Returns an ArrayView that provides a window into the specified portion of
the array.
Throws a panic if the indices are invalid (i.e., start is negative, end
is greater than the array length, or start is greater than end).
Example:
test {
let arr = [1, 2, 3, 4, 5]
let view = arr[1:4] // Create a view of elements at indices 1, 2, and 3
inspect(view[0], content="2") // First element of view is arr[1]
inspect(view.length(), content="3") // View contains 3 elements
}Array::windows
Generates overlapping subslices (sliding windows) of the specified size.
Parameters:
- array : The array to be processed with sliding windows.
- size : The window length. Must be a positive integer, otherwise it will panic.
Returns an array of slices, where each inner slice is a contiguous subslice
of the original array. Windows are produced with a step size of 1. If the
original array's length is less than the specified window size, the result
will be an empty array.
Example:
test {
let arr = [1, 2, 3, 4, 5]
let windows = arr.windows(2)
debug_inspect(
windows,
content=(
#|[
#| <ArrayView: [1, 2]>,
#| <ArrayView: [2, 3]>,
#| <ArrayView: [3, 4]>,
#| <ArrayView: [4, 5]>,
#|]
),
)
let arr = [1, 2]
debug_inspect(arr.windows(3), content="[]")
}Array::zip
Zips two arrays into a single array of tuples.
Parameters:
- self : The first array.
- other : The second array.
Returns an array of tuples, where each tuple contains corresponding elements
from the two input arrays.
Example:
test {
let arr1 = [1, 2, 3]
let arr2 = ['a', 'b', 'c']
debug_inspect(arr1.zip(arr2), content="[(1, 'a'), (2, 'b'), (3, 'c')]")
}Array::zip_to_iter2
Zips two arrays into an iterator that yields corresponding elements.
Parameters:
- self : The first array.
- other : The second array.
Returns an Iter2 iterator that produces corresponding elements
from both arrays. The iteration continues until the shorter array is exhausted.
Example:
test {
let arr1 = [1, 2, 3]
let arr2 = ['a', 'b', 'c']
debug_inspect(
arr1.zip_to_iter2(arr2).to_array(),
content="[(1, 'a'), (2, 'b'), (3, 'c')]",
)
}ArrayView
type ArrayView[T]An ArrayView represents a view into a section of an array without copying the data.
It stores its own start offset and length when it is created, so iteration
over a view keeps using those bounds even if the underlying array is later
structurally modified.
Mutating an array while a view of it is alive is a program error. Because a
view keeps its original bounds and does not track the array, after such a
mutation it may observe elements that have since been removed, a value
handed to Array::release_unused, or the contents of a buffer the array has
stopped using. What it yields is always a valid value of T -- never
uninitialized memory -- but is otherwise unspecified.
No removal writes to the slots it vacates, so the removed elements stay
reachable, and so unreleased, until a later push reuses the slot, until the
buffer grows, or until the buffer itself is dropped. That holds uniformly:
clear empties an array the same way pop shortens it. Two operations
release those elements on demand -- Array::release_unused overwrites the
unused capacity in place, and Array::shrink_to_fit moves the survivors
into an exact-size buffer and lets the old one go.
On the JavaScript backend this guarantee does not yet hold: operations such
as Array::pop shrink the underlying JavaScript array, so a view reaching
past the array's current length observes undefined.
Example
test {
let arr = [1, 2, 3, 4, 5]
let view = arr[1:4] // Creates a view of elements at indices 1,2,3
@test.assert_eq(view[0], 2)
@test.assert_eq(view.length(), 3)
}Concatenates two array views into a new view backed by a freshly allocated
array. The resulting view contains all elements from self followed by all
elements from other.
Note: although + looks cheap, this allocates a new owned Array[T]
because views cannot own data — the returned view spans the whole new
array.
Example:
test {
let a = [1, 2, 3, 4, 5][1:4]
let b = [10, 20, 30][:2]
debug_inspect(
a + b,
content=(
#|<ArrayView: [2, 3, 4, 10, 20]>
),
)
}ArrayView::all
Checks if all elements in the array view match the condition.
Example
test {
let v = [1, 4, 6, 8, 9]
assert_false(v[:].all(elem => elem % 2 == 0))
assert_true(v[1:4].all(elem => elem % 2 == 0))
}ArrayView::any
Check if any of the elements in the array view match the condition.
Example
test {
let v = [1, 2, 3, 4, 5][:]
assert_true(v.any(ele => ele < 6))
assert_false(v.any(ele => ele < 1))
}ArrayView::at
Retrieves an element at the specified index from the array view.
Parameters:
- self : The array view to access.
- index : The position in the array view from which to retrieve the element.
Returns the element at the specified index.
Throws a runtime error if the index is out of bounds (less than 0 or greater
than or equal to the length of the array view).
Example:
test {
let arr = [1, 2, 3, 4, 5]
let view = arr[2:4]
inspect(view[0], content="3")
inspect(view[1], content="4")
}ArrayView::binary_search
Performs a binary search on a sorted array view.
Example
test {
let view = [1, 3, 5, 7, 9][:]
debug_inspect(view.binary_search(5), content="Ok(2)")
debug_inspect(view.binary_search(6), content="Err(3)")
}ArrayView::binary_search_by
Performs a binary search using a custom comparison function.
Example
test {
let view = [1, 3, 5, 7, 9][:]
let result = view.binary_search_by(x => x.compare(5))
debug_inspect(result, content="Ok(2)")
}ArrayView::blit_to
Copies all elements from an array view to a destination array, with support
for growing the destination array if needed.
Parameters:
- self : The array view to copy elements from.
- dst : The array to copy elements to. Will be automatically grown if needed to accommodate the copied elements.
- dst_offset : Starting index in the destination array. Defaults to 0.
Example:
test {
let src = [1, 2, 3, 4, 5]
let view = src[1:4] // view = [2, 3, 4]
let dst = [0, 0]
view.blit_to(dst, dst_offset=1)
@debug.debug_inspect(dst, content="[0, 2, 3, 4]")
}Panics if:
- dst_offset is negative
- dst_offset exceeds the length of destination array
ArrayView::chunk_by
Groups consecutive elements of the view into chunks where adjacent
elements satisfy the given predicate. Each returned sub-view shares the
original backing array.
Example:
test {
let v = [1, 1, 2, 2, 2, 3, 1][:]
debug_inspect(
v.chunk_by((a, b) => a == b),
content=(
#|[
#| <ArrayView: [1, 1]>,
#| <ArrayView: [2, 2, 2]>,
#| <ArrayView: [3]>,
#| <ArrayView: [1]>,
#|]
),
)
}ArrayView::chunks
Split the array view into contiguous sub-views of length size. The last
sub-view may be shorter if the view length is not a multiple of size. The
returned sub-views share the original backing array — no elements are
copied.
Panics if size <= 0.
Example:
test {
let v = [1, 2, 3, 4, 5, 6, 7][:]
debug_inspect(
v.chunks(3),
content=(
#|[<ArrayView: [1, 2, 3]>, <ArrayView: [4, 5, 6]>, <ArrayView: [7]>]
),
)
}ArrayView::compare
ArrayView::contains
Checks whether the array view contains a specific element by comparing each
element with the target value using the equality operator.
Parameters:
- view : The array view to search in.
- target : The value to search for in the array view.
Returns a boolean value indicating whether the target value exists in the
array view.
Example:
test {
let arr = [1, 2, 3, 4, 5][:]
inspect(arr.contains(3), content="true")
inspect(arr.contains(6), content="false")
}ArrayView::count
Counts how many elements in the array view are equal to value.
Example
test {
let view = [1, 2, 1, 3, 1][:]
inspect(view.count(1), content="3")
inspect(view.count(4), content="0")
}ArrayView::count_if
Counts how many elements in the array view satisfy the predicate.
Example
test {
let view = [1, 2, 3, 4, 5][:]
inspect(view.count_if(x => x % 2 == 0), content="2")
}ArrayView::each
Iterates over each element in the array view and applies a function to it.
Parameters:
- self : The array view to iterate over.
- function : A function that takes an element of type T and returns nothing. This function will be applied to each element in the array view.
Example:
test {
let arr = [1, 2, 3][:]
let mut sum = 0
arr.each(x => sum x)
inspect(sum, content="6")
}ArrayView::eachi
Iterates over the elements of the array view with index.
Example
test {
let v = [3, 4, 5][:]
let mut sum = 0
v.eachi((i, x) => sum x + i)
inspect(sum, content="15")
}ArrayView::ends_with
Checks if the array view ends with the given suffix.
Example
test {
let view = [1, 2, 3, 4, 5][:]
inspect(view.ends_with([4, 5]), content="true")
inspect(view.ends_with([3, 4]), content="false")
}ArrayView::equal
ArrayView::filter
Filters the array view with a predicate function.
Example
test {
let arr = [1, 2, 3, 4, 5, 6]
let v = arr[2:].filter(x => x % 2 == 0)
@test.assert_eq(v, [4, 6])
}ArrayView::filter_map
Apply a function to each element of the view, keeping only the Some
results. Returns a freshly allocated Array.
Example:
test {
let v = [1, 2, 3, 4, 5][1:4]
debug_inspect(
v.filter_map(x => if x % 2 == 0 { Some(x * 10) } else { None }),
content="[20, 40]",
)
}ArrayView::fold
Fold out values from an ArrayView according to certain rules.
Example
test {
let sum = [1, 2, 3, 4, 5][:].fold(init=0, (sum, elem) => sum + elem)
inspect(sum, content="15")
}ArrayView::foldi
Fold out values from an ArrayView according to certain rules with index.
Example
test {
let sum = [1, 2, 3, 4, 5][:].foldi(init=0, (index, sum, _elem) => sum + index)
inspect(sum, content="10")
}ArrayView::get
Retrieves an element from the array view at the specified index.
Parameters:
- self : The array view to retrieve the element from.
- index : The position in the array view from which to retrieve the element.
Returns Some(element) if the index is within bounds, or None if the index
is out of bounds.
Example:
test {
let arr = [1, 2, 3, 4, 5]
let view = arr[1:4]
debug_inspect(view.get(0), content="Some(2)")
debug_inspect(view.get(1), content="Some(3)")
debug_inspect(view.get(2), content="Some(4)")
debug_inspect(view.get(5), content="None")
}ArrayView::get_view
Creates a new view into a portion of the array view, returning None when
indices are invalid.
Parameters:
- self : The array view to create a new view from.
- start : The starting index in the current view (inclusive). Defaults to
- end : The ending index in the current view (exclusive). Defaults to the length of the current view.
Returns Some(ArrayView) that provides a window into the specified portion
of the original array view, or None when the indices are invalid.
Example:
test {
let arr = [1, 2, 3, 4, 5]
let view = arr[1:4] // view = [2, 3, 4]
let start = 1
let end = 2
debug_inspect(
view.get_view(start~, end~),
content=(
#|Some(<ArrayView: [3]>)
),
)
let start = 4
let end = 5
debug_inspect(view.get_view(start~, end~), content="None")
}ArrayView::is_empty
Returns whether the array view is empty.
Example:
test {
let view = [1, 2, 3][:]
inspect(view.is_empty(), content="false")
let empty = [1, 2][0:0]
inspect(empty.is_empty(), content="true")
}ArrayView::is_sorted
Tests whether the array view is sorted in ascending order.
Parameters:
- self : The array view to be tested.
- T : The type of elements in the array view. Must implement the Compare trait.
Returns a boolean value indicating whether the array view is sorted in ascending
order:
- true if the array view is empty, contains only one element, or all elements are in ascending order.
- false if any element is greater than the element that follows it.
Example:
test {
let arr = [1, 2, 3, 4, 5]
let view = arr[1:4]
inspect(view.is_sorted(), content="true")
let descending : ReadOnlyArray[Int] = [5, 4, 3, 2, 1]
inspect(descending[:].is_sorted(), content="false")
}ArrayView::iter
Returns an iterator that yields each element of the array view in sequence
from start to end.
Parameters:
- array_view : The array view to iterate over.
Returns an iterator that yields elements of type A from the array view.
The iterator uses the view's stored length, so structural mutations to the
underlying array after the view is created do not change how many steps the
iterator attempts to take.
Structural shrinking of the underlying array is unsupported and may cause
later iterator steps to fail. The same caveat applies to rev_iter() and
iter2().
Example:
test {
let arr = [1, 2, 3]
let view = arr[1:]
let mut sum = 0
view.iter().each(x => sum x)
inspect(sum, content="5")
}ArrayView::iter2
Returns an iterator that yields tuples of index and value
indices start from 0.
Example:
test {
let arr = [1, 2, 3]
let view = arr[1:]
let mut sum = 0
let mut sum_keys = 0
view
.iter2()
.each((i, x) => {
sum x
sum_keys i
})
inspect(sum, content="5")
inspect(sum_keys, content="1")
}ArrayView::join
Concatenate strings within an array into a single complete string.
Example:
test {
let a : Array[String] = ["1", "2", "3"]
let array_view = a[:]
inspect(array_view.join(","), content="1,2,3")
}ArrayView::last
Returns the last element of the array view, if any.
Example:
test {
let view = [1, 2, 3][:]
debug_inspect(view.last(), content="Some(3)")
let empty = [1, 2][0:0]
debug_inspect(empty.last(), content="None")
}ArrayView::length
Returns the length (number of elements) of an array view.
Parameters:
- array_view : The array view whose length is to be determined.
Returns an integer representing the number of elements in the array view.
Example:
test {
let arr = [1, 2, 3, 4, 5]
let view = arr[2:4]
inspect(view.length(), content="2")
}ArrayView::lexical_compare
Performs a lexicographical comparison of two array views.
This method compares the array views element by element until a difference
is found or one view is exhausted. Unlike the Compare trait implementation
which uses shortlex order (shorter views come first), this method compares
based purely on element values until a difference is found.
Returns
- A negative integer if self is lexicographically less than other
- Zero if self is lexicographically equal to other
- A positive integer if self is lexicographically greater than other
Example
test {
inspect([1, 2][:].lexical_compare([1, 2, 3]), content="-1")
inspect([1, 2, 3][:].lexical_compare([1, 2]), content="1")
inspect([1, 2, 3][:].lexical_compare([1, 2, 3]), content="0")
inspect([1, 2, 3][:].lexical_compare([1, 2, 4]), content="-1")
}ArrayView::map
Maps a function over the elements of the array view.
Example
test {
let v = [3, 4, 5]
let v2 = v[1:].map(x => x + 1)
@test.assert_eq(v2, [5, 6])
}ArrayView::mapi
Maps a function over the elements of the array view with index.
Example
test {
let v = [3, 4, 5]
let v2 = v[1:].mapi((i, x) => x + i)
@test.assert_eq(v2, [4, 6])
}ArrayView::rev
Reverses the elements of the array view, returning a freshly allocated
array containing the elements in reverse order. The original view is not
modified.
Example:
test {
let v = [1, 2, 3, 4, 5][1:4]
debug_inspect(v.rev(), content="[4, 3, 2]")
// The view itself is unchanged.
debug_inspect(
v,
content=(
#|<ArrayView: [2, 3, 4]>
),
)
}ArrayView::rev_each
Iterates over the elements of the array view in reverse order (last to
first).
Example:
test {
let v = [1, 2, 3, 4, 5][1:4]
let out = []
v.rev_each(x => out.push(x))
debug_inspect(out, content="[4, 3, 2]")
}ArrayView::rev_eachi
Iterates over the elements of the array view in reverse order, passing the
view-relative index of each element (0 for the first element yielded, the
last position of the view).
Example:
test {
let v = [10, 20, 30][:]
let out = []
v.rev_eachi((i, x) => out.push((i, x)))
debug_inspect(out, content="[(0, 30), (1, 20), (2, 10)]")
}ArrayView::rev_fold
Fold out values from an ArrayView according to certain rules in reversed turn.
Example
test {
let sum = [1, 2, 3, 4, 5][:].rev_fold(init=0, (sum, elem) => sum + elem)
inspect(sum, content="15")
}ArrayView::rev_foldi
Fold out values from an ArrayView according to certain rules in reversed turn with index.
Example
test {
let sum = [1, 2, 3, 4, 5][:].rev_foldi(init=0, (index, sum, _elem) => {
sum + index
})
inspect(sum, content="10")
}ArrayView::rev_iter
Return a reverse iterator over elements of this view.
rev_iterator is a deprecated alias for this function.
Example:
test {
let values = [1, 2, 3][:].rev_iter().collect()
debug_inspect(values, content="[3, 2, 1]")
}ArrayView::search
Searches for the first occurrence of a value in the array view.
Example
test {
let view = [1, 2, 3, 2, 4][:]
debug_inspect(view.search(2), content="Some(1)")
debug_inspect(view.search(5), content="None")
}ArrayView::search_by
Searches for the first element in the view that satisfies the predicate
f and returns its (view-relative) index, or None if no element matches.
Example:
test {
let view = [1, 2, 3, 4, 5][1:]
debug_inspect(view.search_by(x => x > 3), content="Some(2)")
debug_inspect(view.search_by(x => x > 99), content="None")
}ArrayView::start_offset
Return the starting index of this view in the underlying array.
Example:
test {
let arr = [10, 20, 30]
let v = arr[1:]
inspect(v.start_offset(), content="1")
}ArrayView::starts_with
Checks if the array view starts with the given prefix.
Example
test {
let view = [1, 2, 3, 4, 5][:]
inspect(view.starts_with([1, 2]), content="true")
inspect(view.starts_with([2, 3]), content="false")
}ArrayView::strip_prefix
Returns a sub-view with prefix removed from the start, or None if the
view does not start with prefix. The returned view shares the original
backing array — no allocation.
Example:
test {
let v = [1, 2, 3, 4, 5][:]
debug_inspect(
v.strip_prefix([1, 2]),
content=(
#|Some(<ArrayView: [3, 4, 5]>)
),
)
debug_inspect(v.strip_prefix([2, 3]), content="None")
}ArrayView::strip_suffix
Returns a sub-view with suffix removed from the end, or None if the
view does not end with suffix. The returned view shares the original
backing array — no allocation.
Example:
test {
let v = [1, 2, 3, 4, 5][:]
debug_inspect(
v.strip_suffix([4, 5]),
content=(
#|Some(<ArrayView: [1, 2, 3]>)
),
)
debug_inspect(v.strip_suffix([3, 4]), content="None")
}ArrayView::suffixes
Return an iterator over suffix views of this array view.
Set include_empty=true to include the empty suffix at the end.
Example:
test {
let v = [1, 2][:]
debug_inspect(
v.suffixes().collect(),
content=(
#|[<ArrayView: [1, 2]>, <ArrayView: [2]>]
),
)
debug_inspect(
v.suffixes(include_empty=true).collect(),
content=(
#|[<ArrayView: [1, 2]>, <ArrayView: [2]>, <ArrayView: []>]
),
)
}ArrayView::to_owned
Copy the view elements into a newly allocated Array.
Example
test {
let view = [1, 2, 3, 4, 5, 6][2:4]
let arr = view.to_owned()
@test.assert_eq(arr, [3, 4])
}ArrayView::view
Creates a new view into a portion of the array view.
Parameters:
- self : The array view to create a new view from.
- start : The starting index in the current view (inclusive). Defaults to
- end : The ending index in the current view (exclusive). Defaults to the length of the current view.
Returns a new ArrayView that provides a window into the specified portion
of the original array view. The indices are relative to the start of the
current view.
Throws a panic if:
- start is negative
- end is greater than the length of the current view
- start is greater than end
Example:
test {
let arr = [1, 2, 3, 4, 5]
let view = arr[1:4] // view = [2, 3, 4]
let subview = view[1:2] // subview = [3]
inspect(subview[0], content="3")
}ArrayView::windows
Return all contiguous sub-views of the given size, stepping by one
element. Returns an empty array if size exceeds the view length. Each
returned sub-view shares the original backing array.
Panics if size <= 0.
Example:
test {
let v = [1, 2, 3, 4, 5][:]
debug_inspect(
v.windows(3),
content=(
#|[
#| <ArrayView: [1, 2, 3]>,
#| <ArrayView: [2, 3, 4]>,
#| <ArrayView: [3, 4, 5]>,
#|]
),
)
}Hasher
type HasherRepresents a hasher that implements the xxHash32 algorithm. The hasher
maintains a mutable accumulator that is updated with each value added to the
hash computation.
This struct provides methods for combining different types of values into a
single hash value, making it suitable for implementing hash functions for
custom types.
Example:
test {
let hasher = Hasher(seed=0)
hasher.combine_int(42)
hasher.combine_string("hello")
inspect(hasher.finalize(), content="860601284")
}Hasher::Hasher
Creates a new hasher with an optional seed value. Enables the constructor
call syntax Hasher() and Hasher(seed=...).
Parameters:
- seed : An integer value used to initialize the hasher's internal state. When omitted, a randomly chosen process-wide seed is used on native, LLVM, and JavaScript targets. Wasm targets default to 0. Pass 0 explicitly when deterministic output is required.
Returns a new Hasher instance initialized with the given seed value.
Example:
test {
let h1 = Hasher(seed=0) // Create a hasher with default seed
let h2 = Hasher(seed=42) // Create a hasher with custom seed
let x = 123
h1.combine(x)
h2.combine(x)
inspect(h1.finalize() != h2.finalize(), content="true") // Different seeds produce different hashes
}Hasher::new remains available as a deprecated alias.
Hasher::combine
Combines a hashable value with the current state of the hasher. This is
typically used to incrementally build a hash value from multiple components.
Parameters:
- self : The hasher instance to update.
- value : The value to be combined with the current hash state. Must implement the Hash trait.
Example:
test {
let hasher = Hasher(seed=0)
hasher.combine(42)
hasher.combine("hello")
inspect(hasher.finalize(), content="860601284")
}Hasher::combine_bool
Combines a boolean value into the current hash state. The boolean value is
converted to an integer (1 for true, 0 for false) before being combined with
the hash.
Parameters:
- self : The hasher instance to update.
- value : The boolean value to be combined into the hash state.
Example:
test {
let hasher = Hasher(seed=0)
hasher.combine_bool(true)
inspect(hasher.finalize(), content="-205818221")
}Hasher::combine_byte
Combines a byte value into the hash state.
Parameters:
- hasher : The hasher object to update with the byte value.
- byte : The byte value to be combined into the hash.
Example:
test {
let hasher = Hasher(seed=0)
hasher.combine_byte(b'\xFF')
inspect(hasher.finalize(), content="1955036104")
}Hasher::combine_bytes
Combines a byte sequence into the hasher's internal state using xxHash32
algorithm. Processes the input bytes in chunks of 4 bytes for efficiency,
with remaining bytes processed individually.
Parameters:
- hasher : The hasher object to update with the byte sequence.
- bytes : The byte sequence to be combined into the hash.
Example:
test {
let hasher = Hasher(seed=0)
hasher.combine_bytes(b"\xFF\x00\xFF\x00")
inspect(hasher.finalize(), content="-686861102")
}Hasher::combine_char
Combines a character value into the hasher's internal state. The character is
first converted to its Unicode code point (as an integer) before being
combined.
Parameters:
- self : The hasher instance to update.
- value : The character value to be combined into the hash state.
Example:
test {
let hasher = Hasher(seed=0)
hasher.combine_char('A')
inspect(hasher.finalize(), content="-1625495534")
}Hasher::combine_double
Combines a double-precision floating-point number into the hasher's internal
state by reinterpreting its bits as a 64-bit integer. Maintains consistent
hashing behavior regardless of the floating-point value's representation.
Parameters:
- hasher : The hasher to combine the value into.
- value : The double-precision floating-point number to be combined into the hash.
Example:
test {
let hasher = Hasher(seed=0)
hasher.combine_double(3.14)
inspect(hasher.finalize(), content="-428265677")
}Hasher::combine_float
Combines a 32-bit floating-point value into the hasher by reinterpreting its
bit pattern as a 32-bit integer. The operation maintains the same hash result
regardless of the floating-point value's representation.
Parameters:
- hasher : The hasher object that maintains the internal state of the hashing operation.
- value : The 32-bit floating-point value to be combined into the hash.
Example:
test {
let hasher = Hasher(seed=0)
hasher.combine(3.14F)
inspect(hasher.finalize(), content="635116317") // Hash of the bits of 3.14
}Hasher::combine_int
Combines a 32-bit integer value into the hasher's internal state. The value
is processed
as a 4-byte sequence, and the internal accumulator is updated accordingly.
Parameters:
- self : The hasher instance to update.
- value : A 32-bit integer value to be incorporated into the hash.
Example:
test {
let hasher = Hasher(seed=0)
hasher.combine_int(42)
inspect(hasher.finalize(), content="1161967057")
}Hasher::combine_int64
Combines a 64-bit integer value into the hash state by splitting it into two
32-bit parts and processing them separately. This method is used internally
by the hash implementation to incorporate 64-bit integers into the hash
computation.
Parameters:
- hasher : The hasher object whose internal state will be updated.
- value : The 64-bit integer value to be incorporated into the hash state.
Example:
test {
let hasher = Hasher(seed=0)
hasher.combine_int64(42L)
inspect(hasher.finalize(), content="-1962516083")
}Hasher::combine_string
Combines a string value into the current hash state by processing each
character in the string sequentially.
Parameters:
- self : The hasher object whose state will be updated.
- value : The string value to be combined into the hash state.
Example:
test {
let hasher = Hasher(seed=0)
hasher.combine_string("hello")
inspect(hasher.finalize(), content="-655549713")
}Hasher::combine_uint
Combines an unsigned 32-bit integer into the hasher's internal state by
reinterpreting it as a signed integer and incorporating it into the hash
computation.
Parameters:
- hasher : The hasher object to update.
- value : The unsigned 32-bit integer value to be combined into the hash.
Example:
test {
let hasher = Hasher(seed=0)
hasher.combine_uint(42U)
inspect(hasher.finalize(), content="1161967057")
}Hasher::combine_uint64
Combines a 64-bit unsigned integer into the hasher's internal state. Useful
for hashing UInt64 values as part of a larger composite structure.
Parameters:
- self : The hasher instance to update.
- value : The 64-bit unsigned integer value to be incorporated into the hash.
Example:
test {
let hasher = Hasher(seed=0)
hasher.combine_uint64(42UL)
inspect(hasher.finalize(), content="-1962516083")
}Hasher::combine_unit
Combines the unit value (i.e., ()) into the hasher's internal state by
hashing it as an integer value of 0.
Parameters:
- hasher : The hasher object to combine the unit value into.
Example:
test {
let hasher = Hasher(seed=0)
hasher.combine_unit()
inspect(hasher.finalize(), content="148298089")
}Hasher::finalize
Finalizes the hashing process and returns the computed hash value. Applies an
avalanche function to improve the distribution of the hash value.
Parameters:
- hasher : The hasher object containing the accumulated hash state.
Returns a 32-bit integer representing the final hash value.
Example:
test {
let hasher = Hasher(seed=0)
hasher.combine_byte(b'\xFF')
inspect(hasher.finalize(), content="1955036104")
}Iter
#alias(Iterator, deprecated="The name `Iterator` is deprecated, use `Iter` instead. Note that if you have defined `iterator()` method to support `for .. in` loop, you should also rename `iterator()` to `iter()`. See https://github.com/moonbitlang/core/pull/3127 for more details.")
type Iter[X]External iterator type.
Iterator[X] is a mutable type: iterators internally maintain mutable state
to advance iteration.
All read operations on Iterator will advance the iterator,
and would give different result when called multiple times.
Iter::all
Return true if all elements satisfy predicate f.
Function all.
Iter::any
Return true if any element satisfies predicate f.
Function any.
Iter::concat
Combines two iterators into one by appending the elements of the second iterator to the first.
Type Parameters
- X: The type of the elements in the iterators.
Arguments
- self - The first input iterator.
- other - The second input iterator to be appended to the first.
Returns
Returns a new iterator that contains the elements of self followed by the elements of other.
Note
The old iterators self and other must not be used again after calling concat.
Iter::contains
Checks if the iterator contains an element equal to the given value.
Parameters:
- self : The iterator to search in.
- value : The value to search for.
Returns true if the iterator contains an element equal to the given value,
false otherwise.
Example:
test {
let iter = 1, 2, 3, 4, 5
inspect(iter.contains(3), content="true")
inspect(iter.contains(6), content="false")
let iter =
inspect(iter.contains(1), content="false")
}Note
The old iterator self will advance past the searched element.
Iter::count
Counts the number of elements in the iterator.
Type Parameters
- X: The type of the elements in the iterator.
Arguments
- self: The iterator to consume.
Returns
Returns the number of elements in the iterator.
Iter::count_if
Counts the number of elements in the iterator that satisfy the predicate.
Type Parameters
- X: The type of the elements in the iterator.
Arguments
- self: The iterator to consume.
- f: A predicate function applied to each element.
Returns
Returns the number of elements for which f returns true.
Iter::drop
Skips the first n elements from the iterator.
Type Parameters
- X: The type of the elements in the iterator.
Arguments
- self - The input iterator.
- n - The number of elements to skip.
Returns
A new iterator that starts after skipping the first n elements.
Note
The old iterator self must not be used again after calling drop.
Iter::drop_while
Skips elements from the iterator as long as the predicate function returns true.
Type Parameters
- X: The type of the elements in the iterator.
Arguments
- self - The input iterator.
- f - The predicate function that determines whether an element should be skipped.
Returns
A new iterator that starts after skipping the elements as long as the predicate function returns true.
Note
The old iterator self must not be used again after calling drop_while.
Iter::each
Iterates over each element in the iterator, applying the function f to each element.
Type Parameters
- X: The type of the elements in the iterator.
Arguments
- self: The iterator to consume.
- f: A function that takes an element of type X and returns Unit. This function is applied to each element of the iterator.
Iter::eachi
Iterates over each element in the iterator, applying the function f to each element with index.
Type Parameters
- X: The type of the elements in the iterator.
Arguments
- self: The iterator to consume.
- f: A function that takes an index of type Int and an element of type X and returns Unit. This function is applied to each element of the iterator.
Iter::empty
Creates an empty iterator.
Prefer the iterator literal [||], which is equivalent and shorter.
Type Parameters
- X: The type of the elements in the iterator.
Returns
Returns an empty iterator of type Iter[X].
Iter::filter
Filters the elements of the iterator based on a predicate function.
Type Parameters
- X: The type of the elements in the iterator.
Arguments
- self - The input iterator.
- f - The predicate function that determines whether an element should be included in the filtered iterator.
Returns
A new iterator that only contains the elements for which the predicate function returns true.
Note
The old iterator self must not be used again after calling filter.
Iter::filter_map
Transforms the elements of the iterator using a mapping function that returns an Option.
The elements for which the function returns None are filtered out.
The old iterator self must not be used again after calling filter_map.
Iter::find_first
Finds the first element in the iterator that satisfies the predicate function.
Type Parameters
- X: The type of the elements in the iterator.
Arguments
- self - The input iterator.
- f - The predicate function that determines whether an element is the first element to be found.
Returns
An Option that contains the first element that satisfies the predicate function, or None if no such element is found.
Note
The iterator self will advance past the returned element.
Iter::flat_map
Transforms each element of the iterator into an iterator and flattens the resulting iterators into a single iterator.
Type Parameters
- X: The type of the elements in the iterator.
- Y: The type of the transformed elements.
Arguments
- self - The input iterator.
- f - The function that transforms each element of the iterator into an iterator.
Returns
A new iterator that contains the flattened elements.
Note
The old iterator self and the iterators returned by f
must not be used again after calling flat_map.
Iter::flatten
iter.map(f).flatten() == iter.flat_map(f)
Iter::fold
Folds the elements of the iterator using the given function, starting with the given initial value.
Type Parameters
- X: The type of the elements in the iterator.
- R: The type of the accumulator (result) value.
Arguments
- self: The iterator to consume.
- f: A function that takes an accumulator of type R and an element of type X, and returns a new accumulator value.
- init: The initial value for the fold operation.
Returns
Returns the final accumulator value after folding all elements of the iterator.
Iter::intersperse
Inserts a separator element sep between each element of the iterator.
Parameters
- self : The iterator to intersperse the separator into.
- sep : The separator element to insert between each element of the iterator.
Examples
test {
let arr = []
1, 2, 3.intersperse(0).each(i => arr.push(i))
@test.assert_eq(arr, [1, 0, 2, 0, 3])
}Note
The old iterator self must not be used again after calling intersperse.
Iter::iter
Return this iterator itself.
Return an iterator via iter.
Iter::iter2
Return an indexed view of this iterator.
Return an iterator via iter2.
Iter::join
Collects the string-renderable elements of the iterator into a single
string, separated by sep.
The old iterator self must not be used again after calling join.
Iter::last
Returns the last element of the iterator, or None if the iterator is empty.
The old iterator self must not be used again after calling last.
Iter::map
Transforms the elements of the iterator using a mapping function.
Type Parameters
- X: The type of the elements in the iterator.
- Y: The type of the transformed elements.
Arguments
- self - The input iterator.
- f - The mapping function that transforms each element of the iterator.
Returns
A new iterator that contains the transformed elements.
Note
The old iterator self must not be used again after calling map.
Iter::map_while
Transforms the elements of the iterator using a mapping function upto the function returns None.
The old iterator self must not be used again after calling map_while.
Iter::mapi
Transforms the elements of the iterator using a mapping function.
Type Parameters
- X: The type of the elements in the iterator.
- Y: The type of the transformed elements.
Arguments
- self - The input iterator.
- f - The mapping function that transforms each element of the iterator with index.
Returns
A new iterator that contains the transformed elements.
Note
The old iterator self must not be used again after calling mapi.
Iter::maximum
Return the maximum element, or None if empty.
Iter::minimum
Return the minimum element, or None if empty.
Iter::new
Create a new iterator by supplying a next function directly.
The supplied function should output the next element being iterated
everytime it is called.
If the number of remaining elements is known, pass it as size_hint.
This function is intended for use by data structure authors,
and should not be called by end users in general.
Iter::next
Get the next element from an iterator, or return None if no more element exists.
The returned element will be consumed from the iterator.
Calling next repeatedly will iterate through all elements in the iterator.
Iter::nth
Returns the n-th element of the iterator, counting from zero, or None if
n is negative or the iterator has fewer than n + 1 elements.
The iterator self will advance past the returned element.
Iter::repeat
Creates an iterator that repeats the given element indefinitely.
Type Parameters
- X: The type of the elements in the iterator.
Arguments
- x: The element to be repeated.
Returns
Returns an iterator of type Iter[X] that repeats the element x indefinitely.
Iter::singleton
Creates an iterator that contains a single element.
Prefer the iterator literal [|elem|], which is equivalent and shorter.
Type Parameters
- X: The type of the element in the iterator.
Arguments
- elem: The single element to be contained in the iterator.
Returns
Returns an iterator of type Iter[X] that contains the single element elem.
Iter::size_hint
Returns the hinted number of remaining elements if it is known.
The hint is intended to be exact for iterators produced by trusted
collection APIs and adapters, but it must not be used for correctness.
Iter::take
Takes the first n elements from the iterator.
Type Parameters
- X: The type of the elements in the iterator.
Arguments
- self - The input iterator.
- n - The number of elements to take.
Returns
A new iterator that contains the first n elements.
Note
The old iterator self must not be used again after calling take.
Iter::take_while
Takes elements from the iterator as long as the predicate function returns true.
Type Parameters
- X: The type of the elements in the iterator.
Arguments
- self - The input iterator.
- f - The predicate function that determines whether an element should be taken.
Returns
A new iterator that contains the elements as long as the predicate function returns true.
Note
The old iterator self must not be used again after calling take_while.
Iter::tap
Applies a function to each element of the iterator without modifying the iterator.
Type Parameters
- X: The type of the elements in the iterator.
Arguments
- self - The input iterator.
- f - The function to apply to each element of the iterator.
Returns
The same iterator.
Note
The old iterator self must not be used again after calling tap.
Iter::to_array
Collects the elements of the iterator into an array.
The old iterator self must not be used again.
Iter::view
Return a sliced iterator view in range [start, end).
Function view.
Iter::zip
Combines two iterators element-wise into an iterator of pairs.
The resulting iterator stops as soon as either input iterator is exhausted.
Type Parameters
- X: The element type of self.
- Y: The element type of other.
Arguments
- self - The first input iterator.
- other - The second input iterator.
Returns
Returns a new iterator yielding tuples (x, y) where x comes from self
and y comes from other.
Example
test {
let numbers = (1).until(5)
let letters = "a", "b", "c"
debug_inspect(
numbers.zip(letters).collect(),
content="[(1, \"a\"), (2, \"b\"), (3, \"c\")]",
)
}Note
The old iterators self and other must not be used again after calling zip.
Iter2
#alias(Iterator2, deprecated="The name `Iterator2` is deprecated, use `Iter2` instead. Note that if you have defined `iterator2()` method to support `for .. in` loop, you should also rename `iterator2()` to `iter2()`. See https://github.com/moonbitlang/core/pull/3127 for more details.")
pub(all) struct Iter2[X, Y](Iter[(X, Y)])This type is used for for _, _ in .. loop
(for .. in loop with two loop variables),
and should not be used directly in general.
Iter2::concat
Concatenate two Iter2 streams.
Iter2::each
Apply callback to each pair.
Iter2::iter
Convert to plain iterator of pairs.
Return an iterator via iter.
Iter2::iter2
Return this two-variable iterator itself.
Return an iterator via iter2.
Iter2::new
Construct an Iter2 from a pair-producing function.
If the number of remaining pairs is known, pass it as size_hint.
Iter2::next
Get the next pair from the iterator.
Json
JSON value type used by core serialization APIs.
Example:
test {
let value : Json = Json::array([Json::number(1.0), Json::null()])
inspect(value.stringify(), content="[1,null]")
}Json::Json
Converts any value implementing ToJson into a Json.
This is the constructor of Json, so it is written Json(value), and it is
re-exported by the prelude — no import is needed. Prefer it over calling
ToJson::to_json directly.
Parameters:
- value : The value to convert.
Returns the Json representation of value.
Example:
test {
@debug.debug_inspect(Json(42), content="Number(42)")
@debug.debug_inspect(Json("hello"), content="String(\"hello\")")
@debug.debug_inspect(Json([1, 2]), content="Array([Number(1), Number(2)])")
}Json::array
Creates a JSON array value from a MoonBit array.
Parameters:
- values : An array of JSON values to be converted to a JSON array value.
Returns a JSON value representing the given array.
Example:
test {
let values : Array[Json] = [1.0, "hello"]
@debug.debug_inspect(
Json::array(values),
content="Array([Number(1), String(\"hello\")])",
)
}Json::boolean
Creates a JSON boolean value from a MoonBit boolean.
Parameters:
- boolean : A MoonBit boolean to be converted to a JSON boolean value.
Returns a JSON value representing the given boolean.
Example:
test {
@debug.debug_inspect(Json::boolean(true), content="True")
@debug.debug_inspect(Json::boolean(false), content="False")
}Json::null
Creates a JSON null value.
Returns a JSON value representing null.
Json::number
Creates a JSON number value from a double-precision floating-point number.
Parameters:
- value : A double-precision floating-point number to be converted to a JSON number.
Returns a JSON value representing the given number.
Example:
test {
@debug.debug_inspect(Json::number(3.14), content="Number(3.14)")
inspect(
Json::number(@double.infinity, repr="1e9999999999999999999999999999999").stringify(),
content="1e9999999999999999999999999999999",
)
}Json::object
Creates a JSON object value from a MoonBit map.
Parameters:
- map : A map from strings to JSON values to be converted to a JSON object value.
Returns a JSON value representing the given map.
Example:
test {
let map : Map[String, Json] = { "name": "John", "age": 42.0 }
@debug.debug_inspect(
Json::object(map),
content="Object({ \"name\": String(\"John\"), \"age\": Number(42) })",
)
}Json::string
Creates a JSON string value from a MoonBit string.
Parameters:
- string : A MoonBit string to be converted to a JSON string value.
Returns a JSON value representing the given string.
Example:
test {
@debug.debug_inspect(Json::string("hello"), content="String(\"hello\")")
}Map
type Map[K, V]Mutable linked hash map that maintains the order of insertion, not thread safe.
Example
test {
let map = { 3: "three", 8: "eight", 1: "one" }
@test.assert_eq(map.get(2), None)
@test.assert_eq(map.get(3), Some("three"))
map.set(3, "updated")
@test.assert_eq(map.get(3), Some("updated"))
}Map::Map
Create a hash map from an array.
The optional capacity is treated as a minimum initial capacity and will be
rounded up to the smallest power of 2 that can hold the requested capacity.
Map::at
Get value with at access semantics.
Map::clear
Clears the map, removing all key-value pairs. Keeps the allocated space.
Map::contains
Check if the hash map contains a key.
Map::contains_kv
Checks if a map contains a specific key-value pair.
Parameters:
- map : A map of type Map[K, V] to search in.
- key : The key to look up in the map.
- value : The value to be compared with the value associated with the key.
Returns true if the map contains the specified key and its associated value
equals the given value, false otherwise.
Example:
test {
let map = { "a": 1, "b": 2 }
inspect(map.contains_kv("a", 1), content="true")
inspect(map.contains_kv("a", 2), content="false")
inspect(map.contains_kv("c", 3), content="false")
}Map::copy
Copy the map, creating a new map with the same key-value pairs and order of insertion.
Map::each
Iterate over all key-value pairs of the map in the order of insertion.
Map::eachi
Iterate over all key-value pairs of the map in the order of insertion, with index.
Map::from_iter
Create from iter.
Map::get
Retrieves the value associated with a given key in the hash map.
Parameters:
- self : The hash map to search in.
- key : The key to look up in the map.
Returns Some(value) if the key exists in the map, None otherwise.
Example:
test {
let map = { "key": 42 }
debug_inspect(map.get("key"), content="Some(42)")
debug_inspect(map.get("nonexistent"), content="None")
}Map::get_from_bytes
Retrieves the value associated with a BytesView key in a map with Bytes keys.
This function allows efficient lookups using BytesView without creating a new Bytes object.
It's particularly useful when working with byte slices or subranges of existing byte arrays.
Parameters:
- map : The hash map with Bytes keys to search in.
- key : A BytesView representing the key to look up.
Returns Some(value) if a matching key exists in the map, None otherwise.
Example:
test {
let map = { b"hello": 1, b"world": 2 }
let bytes = b"prefix_hello_suffix"
let view = bytes[7:12] // view of "hello"
debug_inspect(map.get_from_bytes(view), content="Some(1)")
}Map::get_from_string
Retrieves the value associated with a StringView key in a map with String keys.
This function allows efficient lookups using StringView without creating a new String object.
It's particularly useful when working with substrings or string slices.
Parameters:
- map : The hash map with String keys to search in.
- key : A StringView representing the key to look up.
Returns Some(value) if a matching key exists in the map, None otherwise.
Example:
test {
let map = { "hello": 1, "world": 2 }
let str = "say hello to everyone"
let view = str.view(start_offset=4, end_offset=9) // view of "hello"
debug_inspect(map.get_from_string(view), content="Some(1)")
}Map::get_or_default
Returns the value associated with the key in the map, or computes and returns
a default value if the key does not exist.
Parameters:
- map : The map to search in.
- key : The key to look up in the map.
- default : A function that returns a default value when the key is not found.
Returns either the value associated with the key if it exists, or the result
of calling the default function.
Example:
test {
let map = { "a": 1, "b": 2 }
inspect(map.get_or_default("a", 0), content="1")
inspect(map.get_or_default("c", 42), content="42")
}Map::get_or_init
Returns the value for the given key, or sets and returns a default value if the key does not exist.
Map::iter
Returns the iterator of the hash map, provide elements in the order of insertion.
Map::iter2
Return an iterator via iter2.
Map::length
Get the number of key-value pairs in the map.
Map::map
Applies a function to each key-value pair in the map and returns a new map with the results, using the original keys.
Map::merge
Merges two maps into a new map. Returns a new map containing all key-value
pairs from both maps. When both maps contain the same key, the value from
other takes precedence. The iteration order follows the order of self
followed by new entries from other.
This is a pure operation - it does not modify either of the input maps.
Parameters:
- self : The first map.
- other : The second map whose values take precedence in case of key conflicts.
Returns a new linked hash map containing all entries from both maps.
Example:
test {
let map1 : Map[String, Int] = { "a": 1, "b": 2 }
let map2 : Map[String, Int] = { "b": 3, "c": 4 }
let merged = map1.merge(map2)
@json.json_inspect(merged, content={ "a": 1, "b": 3, "c": 4 })
}Map::merge_in_place
Merges another map into this map in-place. Updates the current map by adding
all key-value pairs from other. When both maps contain the same key, the
value from other overwrites the value in this map. New entries from other
are added at the end, preserving the original order of self and appending
new keys from other.
This is a mutating operation - it modifies the receiver map.
Parameters:
- self : The map to be modified.
- other : The map whose entries will be added to self.
Example:
test {
let map1 : Map[String, Int] = { "a": 1, "b": 2 }
let map2 : Map[String, Int] = { "b": 3, "c": 4 }
map1.merge_in_place(map2)
@json.json_inspect(map1, content={ "a": 1, "b": 3, "c": 4 })
}Map::new
Create a hash map.
The capacity of the map will be the smallest power of 2 that is
greater than or equal to the provided [capacity].
Deprecated: use Map([], capacity=...) instead.
Map::of
Function of.
Map::remove
Removes the entry for the specified key from the hash map. If the key exists
in the map, removes its entry and adjusts the probe sequence length (PSL) of
subsequent entries to maintain the Robin Hood hashing invariant. If the key
does not exist, the map remains unchanged.
Parameters:
- self : The hash map to remove the entry from.
- key : The key to remove from the map.
Example:
test {
let map = { "a": 1, "b": 2 }
map.remove("a")
debug_inspect(map.get("a"), content="None")
inspect(map.length(), content="1")
}Map::retain
Retains only the key-value pairs that satisfy the given predicate function.
This method modifies the map in-place, removing all entries for which
the predicate returns false. The order of remaining elements is preserved.
Parameters:
- self : The map to be filtered.
- predicate : A function that takes a key and value as arguments and returns true if the key-value pair should be kept, false if it should be removed.
Example:
test {
let map = { "a": 1, "b": 2, "c": 3, "d": 4 }
map.retain((_k, v) => v % 2 == 0) // Keep only even values
inspect(map.length(), content="2")
debug_inspect(map.get("a"), content="None")
debug_inspect(map.get("b"), content="Some(2)")
debug_inspect(map.get("c"), content="None")
debug_inspect(map.get("d"), content="Some(4)")
}Map::set
Sets a key-value pair into the hash map. If the key already exists, updates
its value. If the hash map is near full capacity, automatically
grows the internal storage to accommodate more entries.
Parameters:
- map : The hash map to modify.
- key : The key to insert or update. Must implement Hash and Eq traits.
- value : The value to associate with the key.
Example:
test {
let map : Map[String, Int] = Map([])
map.set("key", 42)
debug_inspect(map.get("key"), content="Some(42)")
map.set("key", 24) // update existing key
debug_inspect(map.get("key"), content="Some(24)")
}Map::to_array
Converts the hash map to an array.
Map::update
Updates a value in the map based on the existing value.
This method allows you to conditionally update, insert, or remove a key-value pair
based on whether the key already exists in the map. The provided function f is
called with Some(current_value) if the key exists, or None if it doesn't.
Parameters:
- self : The map to update.
- key : The key to update.
- f : A function that takes the current value (wrapped in Option) and returns the new value (wrapped in Option). Returning None will remove the key-value pair from the map.
Behavior:
- If the key exists and f returns Some(new_value), the value is updated.
- If the key exists and f returns None, the key-value pair is removed.
- If the key doesn't exist and f returns Some(new_value), a new pair is inserted.
- If the key doesn't exist and f returns None, no operation is performed.
Example:
test {
let map = { "a": 1, "b": 2 }
// Update existing value
map.update("a", fn(v) {
match v {
Some(x) => Some(x + 10)
None => Some(0)
}
})
debug_inspect(
map,
content=(
#|{ "a": 11, "b": 2 }
),
)
// Insert new value
map.update("c", fn(v) {
match v {
Some(x) => Some(x)
None => Some(3)
}
})
debug_inspect(
map,
content=(
#|{ "a": 11, "b": 2, "c": 3 }
),
)
// Remove existing value
map.update("b", fn(_) { None })
debug_inspect(
map,
content=(
#|{ "a": 11, "c": 3 }
),
)
}Map::update_or_default
Inserts default for key if it is absent, otherwise replaces the existing
value with f(existing). The pairing of an eager default value with a
modifier function lets the canonical counter pattern read literally:
test {
let counts : Map[String, Int] = Map([])
counts.update_or_default("a", 1, x => x + 1)
counts.update_or_default("a", 1, x => x + 1)
counts.update_or_default("b", 1, x => x + 1)
debug_inspect(counts.get("a"), content="Some(2)")
debug_inspect(counts.get("b"), content="Some(1)")
}Note: f is not applied to default on first insertion — default is
the value stored when the key is absent. This mirrors Java's Map.merge
and Rust's Entry::and_modify(f).or_insert(default).
MutArrayView
type MutArrayView[T]A MutArrayView represents a view into a section of an array without copying the data.
The view provides read-write access to elements of the underlying array.
Example
test {
let arr = [1, 2, 3, 4, 5]
let view = arr.mut_view(start=1, end=4) // Creates a view of elements at indices 1,2,3
@test.assert_eq(view[0], 2)
@test.assert_eq(view.length(), 3)
}impl Compare for MutArrayView[T]impl Eq for MutArrayView[T]impl Hash for MutArrayView[A]impl Show for MutArrayView[X]MutArrayView::at
Retrieves an element at the specified index from the mutable array view.
Parameters:
- self : The mutable array view to access.
- index : The position in the array view from which to retrieve the element.
Returns the element at the specified index.
Throws a runtime error if the index is out of bounds (less than 0 or greater
than or equal to the length of the array view).
Example:
test {
let arr = [1, 2, 3, 4, 5]
let view = arr.mut_view(start=2, end=4)
inspect(view[0], content="3")
inspect(view[1], content="4")
}MutArrayView::compare
MutArrayView::equal
MutArrayView::is_empty
Returns whether the mutable array view is empty.
Example:
test {
let view = [1, 2, 3].mut_view(start=1, end=1)
inspect(view.is_empty(), content="true")
}MutArrayView::iter
#alias(iterator, deprecated="`iterator` is deprecated, use `iter` instead")
fn[X] MutArrayView::iter(self : MutArrayView[X]) -> Iter[X]Return an iterator via iter.
MutArrayView::iter2
#alias(iterator2, deprecated="`iterator2` is deprecated, use `iter2` instead")
fn[X] MutArrayView::iter2(self : MutArrayView[X]) -> Iter2[Int, X]Return an iterator via iter2.
MutArrayView::length
Returns the length (number of elements) of a mutable array view.
Parameters:
- array_view : The mutable array view whose length is to be determined.
Returns an integer representing the number of elements in the mutable array view.
Example:
test {
let arr = [1, 2, 3, 4, 5]
let view = arr.mut_view(start=2, end=4)
inspect(view.length(), content="2")
}MutArrayView::mut_view
Creates a new mutable view into a portion of the mutable array view.
Parameters:
- self : The mutable array view to create a new view from.
- start : The starting index in the current view (inclusive). Defaults to
- end : The ending index in the current view (exclusive). Defaults to the length of the current view.
Returns a new MutArrayView that provides a window into the specified portion
of the original mutable array view. The indices are relative to the start of the
current view.
Throws a panic if:
- start is negative
- end is greater than the length of the current view
- start is greater than end
Example:
test {
let arr = [1, 2, 3, 4, 5]
let view = arr.mut_view(start=1, end=4) // view = [2, 3, 4]
let subview = view.mut_view(start=1, end=2) // subview = [3]
inspect(subview[0], content="3")
}MutArrayView::rev_iter
#alias(rev_iterator, deprecated="`rev_iterator` is deprecated, use `rev_iter` instead")
fn[X] MutArrayView::rev_iter(self : MutArrayView[X]) -> Iter[X]Function rev_iter.
MutArrayView::set
Sets an element at the specified index in the mutable array view.
Parameters:
- self : The mutable array view to modify.
- index : The position in the array view at which to set the element.
- value : The value to set at the specified index.
Throws a runtime error if the index is out of bounds (less than 0 or greater
than or equal to the length of the array view).
Example:
test {
let arr = [1, 2, 3, 4, 5]
let view = arr.mut_view(start=2, end=4)
view[0] = 10
inspect(view[0], content="10")
inspect(arr[2], content="10")
}MutArrayView::sort
Sorts the array in place.
It's an in-place, unstable sort(it will reorder equal elements). The time complexity is O(n log n) in the worst case.
Example
test {
let arr = [5, 4, 3, 2, 1]
arr.mut_view().sort()
@test.assert_eq(arr, [1, 2, 3, 4, 5])
}MutArrayView::sort_by
Sorts the array with a custom comparison function.
It's an in-place, unstable sort(it will reorder equal elements). The time complexity is O(n log n) in the worst case.
Example
test {
let arr = [5, 3, 2, 4, 1]
arr.mut_view().sort_by((a, b) => a - b)
@test.assert_eq(arr, [1, 2, 3, 4, 5])
}MutArrayView::sort_by_key
Sorts the array with a key extraction function.
It's an in-place, unstable sort(it will reorder equal elements). The time complexity is O(n log n) in the worst case.
Example
test {
let arr = [5, 3, 2, 4, 1]
arr.mut_view().sort_by_key(x => -x)
@test.assert_eq(arr, [5, 4, 3, 2, 1])
}MutArrayView::stable_sort
Sorts the array
It's an stable sort(it will not reorder equal elements). The time complexity is O(n * log(n)) in the worst case.
Example
test {
let arr : FixedArray[Int] = [5, 4, 3, 2, 1]
arr.mut_view().stable_sort()
@test.assert_eq(arr, [1, 2, 3, 4, 5])
}MutArrayView::start_offset
Returns the start offset of the mutable array view in its backing array.
MutArrayView::to_owned
#alias(to_array, deprecated="`to_array` is deprecated, use `to_owned` instead")
fn[T] MutArrayView::to_owned(self : MutArrayView[T]) -> Array[T]Copies the elements of the mutable array view into a newly allocated Array.
MutArrayView::unsafe_get
#internal(unsafe, "Panic if index is out of bounds")
fn[T] MutArrayView::unsafe_get(self : MutArrayView[T], index : Int) -> TRetrieves an element from the mutable array view at the specified index without
performing bounds checking.
Parameters:
- array_view : The mutable array view to retrieve the element from.
- index : The position in the array view from which to retrieve the element.
Returns the element at the specified index in the array view.
Example:
test {
let arr = [1, 2, 3, 4, 5]
let view = arr.mut_view(start=1, end=4)
inspect(view.unsafe_get(1), content="3")
}MutArrayView::unsafe_set
#internal(unsafe, "Panic if index is out of bounds")
fn[T] MutArrayView::unsafe_set(self : MutArrayView[T], index : Int, value : T) -> UnitSets an element at the specified index in the mutable array view without
performing bounds checking.
Parameters:
- self : The mutable array view to modify.
- index : The position in the array view at which to set the element.
- value : The value to set at the specified index.
Example:
test {
let arr = [1, 2, 3, 4, 5]
let view = arr.mut_view(start=1, end=4)
view.unsafe_set(1, 10)
inspect(view[1], content="10")
}MutArrayView::view
#alias(sub, deprecated="Use _[_:_] instead")
#alias("_[_:_]")
fn[T] MutArrayView::view(self : MutArrayView[T], start? : Int, end? : Int) -> ArrayView[T]Creates a new ArrayView from a MutArrayView.
Parameters:
- self : The mutable array view to create a new view from.
- start : The starting index in the current view (inclusive). Defaults to
- end : The ending index in the current view (exclusive). Defaults to the length of the current view.
SourceLoc
pub(all) type SourceLocRepresents a source code location in a MoonBit program, containing
information about the file path, line number, and column number. Used
internally by the compiler for error reporting and debugging purposes.
This type is public to all packages but its internal representation is
opaque. Users cannot construct values of this type directly; they are
automatically created by the compiler when needed.
TODO: can not make a dummy loc
SourceLoc::to_json_string
Convert a source location to a JSON string
StringBuilder
type StringBuilderimpl Logger for StringBuilderWrites a character to the StringBuilder.
Writes a string to the StringBuilder.
Writes a string view to the StringBuilder.
Parameters:
- self : The StringBuilder to write to.
- str : The view of the string to write.
Example:
test {
let sb = StringBuilder()
sb.write_view("Hello, world!"[:5])
@test.assert_eq(sb.to_string(), "Hello")
}impl Show for StringBuilderStringBuilder::StringBuilder
#alias(new, deprecated="Use `StringBuilder()` instead")
fn StringBuilder::StringBuilder(size_hint? : Int) -> StringBuilderCreates a new string builder with an optional initial capacity hint.
Parameters:
- size_hint : An optional initial capacity hint for the internal buffer. If less than 1, a minimum capacity of 1 is used. Defaults to 0. It is the size of bytes, not the size of characters. size_hint may be ignored on some platforms, JS for example.
Returns a new StringBuilder instance with the specified initial capacity.
StringBuilder::is_empty
Return whether the given buffer is empty.
StringBuilder::reset
Resets the string builder to an empty state.
StringBuilder::to_string
Returns the current content of the StringBuilder as a string.
StringBuilder::write_char
StringBuilder::write_iter
Writes characters from an iterator to the StringBuilder.
Parameters:
- self : The StringBuilder to write to.
- iter : An iterator yielding characters to write.
Example:
test {
let sb = StringBuilder()
let chars = "Hello🤣".iter()
sb.write_iter(chars)
@test.assert_eq(sb.to_string(), "Hello🤣")
}StringBuilder::write_object
#alias(write_string_interpolation)
#alias(write)
fn[T : Show] StringBuilder::write_object(self : StringBuilder, obj : T) -> UnitWrites the string representation of an object to the StringBuilder.
StringBuilder::write_string
StringBuilder::write_stringview
Writes a StringView to the StringBuilder.
This is more efficient than converting the StringView to a String first,
as it directly writes the viewed portion without creating intermediate strings.
Parameters:
- self : The StringBuilder to write to.
- view : The StringView to write.
Example:
test {
let sb = StringBuilder()
let str = "Hello, world!"
let view = str[7:12] // "world"
sb.write_stringview(view)
@test.assert_eq(sb.to_string(), "world")
}StringBuilder::write_substring
fn StringBuilder::write_substring(self : StringBuilder, value : String, start : Int, len : Int) -> UnitStringBuilder::write_view
UninitializedArray
type UninitializedArray[T]UninitializedArray::at
Retrieves the element at the specified index from an uninitialized array.
Parameters:
- array : The uninitialized array from which to retrieve the element.
- index : The index of the element to retrieve.
Returns the element at the specified index.
UninitializedArray::length
Returns the length of an uninitialized array.
Parameters:
- array : The uninitialized array whose length is to be determined.
Returns the length of the uninitialized array as an integer.
UninitializedArray::make
Creates an uninitialized array of the specified size.
Parameters:
- size : The number of elements the array should hold.
Returns an uninitialized array of type T with the specified size.
UninitializedArray::make_and_blit
fn[T] UninitializedArray::make_and_blit(src : UninitializedArray[T], allocate_len~ : Int, len~ : Int, src_offset? : Int, dst_offset? : Int) -> UninitializedArray[T]Checked variant of unsafe_make_and_blit.
UninitializedArray::set
#alias("_[_]=_")
fn[T] UninitializedArray::set(self : UninitializedArray[T], index : Int, value : T) -> UnitSets the value at the specified index in an uninitialized array.
Parameters:
- array : The uninitialized array where the value will be set.
- index : The position in the array where the value will be set.
- value : The value to be set at the specified index.
UninitializedArray::sub
#alias("_[_:_]")
fn[T] UninitializedArray::sub(self : UninitializedArray[T], start? : Int, end? : Int) -> ArrayView[T]Creates a view into a portion of the uninitialized array.
Parameters:
- array : The uninitialized array to create a view from.
- start : The starting index of the view (inclusive). Defaults to 0.
- end : The ending index of the view (exclusive). If not provided, defaults to the length of the array.
Returns an ArrayView that provides a window into the specified portion of
the array.
Throws an error if the indices are out of bounds or if start is greater
than end.
Bool
Note
Bool is a built-in type. The documentation may not be complete here. You can find all methods and implementations in the core/builtin and core/bool package.
Bool::op_compare
#deprecated("Use `compare` instead")
fn Bool::op_compare(self : Bool, other : Bool) -> IntCompares two boolean values and returns their relative order. This is a
deprecated method and users should use compare instead.
Parameters:
- self : The first boolean value to compare.
- other : The second boolean value to compare against.
Returns an integer indicating the relative order:
- A negative value if self is less than other (i.e., self is false and other is true)
- Zero if self equals other
- A positive value if self is greater than other (i.e., self is true and other is false)
Example:
test {
let t = true
let f = false
// This usage is deprecated, use compare() instead
inspect(t.compare(f), content="1")
inspect(f.compare(t), content="-1")
inspect(t.compare(t), content="0")
}Bool::to_int
fn Bool::to_int(self : Bool) -> IntConverts a boolean value to its integer representation.
Parameters:
- self : The boolean value to convert.
Returns 1 if the boolean is true, 0 if it is false.
Example:
test {
inspect(true.to_int(), content="1")
inspect(false.to_int(), content="0")
}Bool::to_int16
fn Bool::to_int16(self : Bool) -> Int16Converts a boolean value to a 16-bit integer representation.
Parameters:
- self : The boolean value to be converted.
Returns a 16-bit integer, where true is converted to 1 and false is
converted to 0.
Example:
test {
inspect(true.to_int16(), content="1")
inspect(false.to_int16(), content="0")
}Bool::to_int64
fn Bool::to_int64(self : Bool) -> Int64Converts a boolean value to a 64-bit integer. Returns 1 for true and 0 for
false.
Parameters:
- bool : The boolean value to be converted.
Returns a 64-bit integer representation of the boolean value.
Example:
test {
inspect(true.to_int64(), content="1")
inspect(false.to_int64(), content="0")
}Bool::to_uint
fn Bool::to_uint(self : Bool) -> UIntConverts a boolean value to an unsigned integer.
Parameters:
- value : The boolean value to be converted.
Returns an unsigned integer, where true is converted to 1 and false is
converted to 0.
Example:
test {
inspect(true.to_uint(), content="1")
inspect(false.to_uint(), content="0")
}Bool::to_uint16
fn Bool::to_uint16(self : Bool) -> UInt16Converts a boolean value to an unsigned 16-bit integer.
Parameters:
- self : The boolean value to be converted.
Returns an unsigned 16-bit integer, where true is converted to 1 and
false is converted to 0.
Example:
test {
inspect(true.to_uint16(), content="1")
inspect(false.to_uint16(), content="0")
}Bool::to_uint64
fn Bool::to_uint64(self : Bool) -> UInt64Converts a boolean value to an unsigned 64-bit integer. Returns 1 for true
and 0 for false.
Parameters:
- bool : The boolean value to convert.
Returns an unsigned 64-bit integer representation of the boolean value.
Example:
test {
inspect(true.to_uint64(), content="1")
inspect(false.to_uint64(), content="0")
}Byte
Note
Byte is a built-in type. The documentation may not be complete here. You can find all methods and implementations in the core/builtin and core/byte package.
Byte::Byte
fn Byte::Byte(self : Byte) -> ByteThe identity constructor for Byte, allowing values to be written using
constructor syntax, e.g. Byte(3).
Example:
test {
inspect(Byte(3), content="b'\\x03'")
}Byte::lnot
fn Byte::lnot(self : Byte) -> BytePerforms a bitwise NOT operation on the given Byte value.
Parameters:
- value : The Byte value to apply the bitwise NOT operation on.
Returns the result of the bitwise NOT operation as a Byte.
Byte::lsl
#deprecated("Use infix operator `<<` instead")
fn Byte::lsl(self : Byte, count : Int) -> ByteShifts the bits of a Byte value to the left by the given number of bit
positions.
Parameters:
- self : The Byte value whose bits are to be shifted.
- count : The number of bit positions to shift self to the left.
Returns the resulting Byte value after the bitwise left shift operation.
Byte::lsr
#deprecated("Use infix operator `>>` instead")
fn Byte::lsr(self : Byte, count : Int) -> BytePerforms a logical (zero-filling) right shift of a Byte value by the
given number of bits.
Parameters:
- self : The Byte value to be shifted.
- count : The number of bits to shift self to the right.
Returns the result of the logical shift right operation as a Byte.
Byte::popcnt
fn Byte::popcnt(self : Byte) -> IntCounts the number of 1-bits (population count) in the byte using bitwise operations.
Parameters:
- self : The byte value whose 1-bits are to be counted.
Returns the number of 1-bits in the byte.
Example:
test {
let b = b'\x0F'
inspect(b.popcnt(), content="4")
}Byte::to_char
fn Byte::to_char(self : Byte) -> CharConverts a byte value to a character.
Parameters:
- byte : The byte value to be converted.
Returns the character corresponding to the byte value.
Byte::to_float
#deprecated("Use `Float::from_byte` instead")
fn Byte::to_float(self : Byte) -> FloatConvert Byte to Float (deprecated alias).
Convert to float.
Byte::to_hex
fn Byte::to_hex(b : Byte) -> StringConvert a byte to a two-digit lowercase hexadecimal string.
Example:
test {
inspect(Byte::to_hex(b'\x0f'), content="0f")
}Byte::to_int
fn Byte::to_int(self : Byte) -> IntConverts a byte value to a 32-bit signed integer. The resulting integer will
have the same binary representation as the byte value, preserving the
numerical value in the range [0, 255].
Parameters:
- byte : The byte value to be converted to an integer.
Returns a 32-bit signed integer representing the same numerical value as the
input byte.
Example:
test {
let b = b'\xFF' // byte with value 255
inspect(b.to_int(), content="255")
let zero = b'\x00'
inspect(zero.to_int(), content="0")
}Byte::to_int16
#deprecated("Use `Int16::from_byte` instead")
fn Byte::to_int16(self : Byte) -> Int16Converts a byte value to a 16-bit signed integer. The byte value is
zero-extended to 16 bits during the conversion, so the result is always in
the range [0, 255].
Parameters:
- byte : The byte value to be converted to an Int16.
Returns a 16-bit signed integer representing the same value as the input
byte.
Byte::to_int64
fn Byte::to_int64(self : Byte) -> Int64Converts a byte value to a 64-bit signed integer by first converting it to a
32-bit integer and then extending it to a 64-bit integer.
Parameters:
- byte : The byte value to be converted.
Returns a 64-bit signed integer representing the same numerical value as the
input byte.
Example:
test {
let b = b'\xFF'
inspect(b.to_int64(), content="255")
}Byte::to_string
fn Byte::to_string(self : Byte) -> StringConverts a Byte to its string representation in hexadecimal format.
Parameters:
- byte : The Byte value to be converted.
Returns a String representing the Byte in the format b'\xHH', where
HH is the hexadecimal representation of the byte.
Byte::to_uint
fn Byte::to_uint(self : Byte) -> UIntConverts a Byte to a UInt.
Parameters:
- byte : The Byte value to be converted.
Returns the UInt representation of the Byte.
Byte::to_uint16
fn Byte::to_uint16(self : Byte) -> UInt16Converts a byte value to a 16-bit unsigned integer by zero-extending it.
Parameters:
- byte : The byte value to be converted.
Returns a 16-bit unsigned integer (UInt16) representing the same value as
the input byte.
Example:
test {
let b = b'\xFF' // byte with value 255
inspect(b.to_uint16(), content="255")
let zero = b'\x00'
inspect(zero.to_uint16(), content="0")
}Byte::to_uint64
fn Byte::to_uint64(self : Byte) -> UInt64Converts a byte value to an unsigned 64-bit integer.
Parameters:
- byte : The byte value to be converted.
Returns an unsigned 64-bit integer representation of the byte value.
Example:
test {
let b = b'\xFF'
inspect(b.to_uint64(), content="255")
}Bytes
Note
Bytes is a built-in type. The documentation may not be complete here. You can find all methods and implementations in the core/builtin and core/bytes package.
Bytes::at
#alias("_[_]")
fn Bytes::at(self : Bytes, idx : Int) -> ByteRetrieves a byte at the specified index from a byte sequence.
Parameters:
- bytes : The byte sequence to access.
- index : The position in the byte sequence from which to retrieve the byte.
Returns a byte value from the specified position in the sequence.
Throws a panic if the index is negative or greater than or equal to the
length of the byte sequence.
Example:
test {
let bytes = b"\x01\x02\x03"
inspect(bytes[1], content="b'\\x02'")
}Bytes::chop_prefix
fn Bytes::chop_prefix(self : Bytes, prefix : BytesView) -> BytesView?Removes the given prefix from the bytes if it exists.
Bytes::chop_suffix
fn Bytes::chop_suffix(self : Bytes, suffix : BytesView) -> BytesView?Removes the given suffix from the bytes if it exists.
Bytes::copy
#alias(clone, deprecated="`clone` is deprecated, use `copy` instead")
#deprecated("Bytes are immutable. Use `FixedArray::blit_from_bytes` if it's really necessary.")
fn Bytes::copy(self : Bytes) -> BytesReturn a copied Bytes value.
Deprecated because Bytes is immutable and copying is usually unnecessary.
Example:
test {
let a = b"abc"
let b = Bytes::makei(a.length(), i => a[i])
inspect(a == b, content="true")
}Bytes::find
fn Bytes::find(target : Bytes, pattern : BytesView) -> Int?Returns the offset of the first occurrence of the given bytes substring.
If the substring is not found, None is returned.
Bytes::from_array
#alias(of, deprecated="`of` is deprecated, use `from_array` instead")
fn Bytes::from_array(arr : ArrayView[Byte]) -> BytesCreates a new bytes sequence from a byte array.
Parameters:
- array : An array of bytes to be converted.
Returns a new bytes sequence containing the same bytes as the input array.
Example:
test {
let arr : ReadOnlyArray[Byte] = [b'h', b'i']
let bytes = Bytes::from_array(arr)
inspect(
bytes,
content=(
#|b"hi"
),
)
}
test {
let arr : FixedArray[Byte] = [b'h', b'e', b'l', b'l', b'o']
let bytes = Bytes::from_array(arr)
inspect(
bytes,
content=(
#|b"hello"
),
)
}Bytes::from_fixedarray
#deprecated("Use Bytes::from_array instead")
fn Bytes::from_fixedarray(arr : FixedArray[Byte], len? : Int) -> BytesCreates a new bytes sequence from a fixed-size array of bytes with an
optional length parameter.
Parameters:
- arr : A fixed-size array of bytes to be converted into a bytes sequence.
- len : (Optional) The length of the resulting bytes sequence. If not provided, uses the full length of the input array.
Returns a new bytes sequence containing the bytes from the input array. If a
length is specified, only includes up to that many bytes.
Example:
test {
let arr : FixedArray[Byte] = [b'h', b'e', b'l', b'l', b'o']
let bytes = Bytes::from_array(arr[0:3])
inspect(
bytes,
content=(
#|b"hel"
),
)
}Panics if the length is invalid
Bytes::from_iter
#alias(from_iterator, deprecated="`from_iterator` is deprecated, use `from_iter` instead")
fn Bytes::from_iter(iter : Iter[Byte]) -> BytesCreates a new bytes sequence from an iterator of bytes.
Parameters:
- iterator : An iterator that yields bytes.
Returns a new bytes sequence containing all the bytes from the iterator.
Example:
test {
let iter = b'h'
let bytes = Bytes::from_iter(iter)
inspect(
bytes,
content=(
#|b"h"
),
)
}Bytes::get
fn Bytes::get(self : Bytes, index : Int) -> Byte?Retrieves a byte from the byte sequence at the specified index.
Parameters:
- self : The byte sequence to retrieve the byte from.
- index : The position in the byte sequence from which to retrieve the byte.
Returns the byte at the specified index, or None if the index is out of bounds.
Example:
test {
let bytes = b"\x01\x02\x03"
let byte = bytes.get(1)
debug_inspect(
byte,
content=(
#|Some(0x02)
),
)
let bytes = b"\x01\x02\x03"
let byte = bytes.get(3)
debug_inspect(byte, content="None")
}Bytes::get_view
fn Bytes::get_view(self : Bytes, start? : Int, end? : Int) -> BytesView?Returns a view of the bytes between start and end, or None if the range
is invalid. Unlike Bytes::view (a.k.a. b[start:end]), this variant does
not abort on out-of-bounds indices, making it suitable for composition with
pattern matching:
test {
let bs = b"\x00\x01\x02\x03\x04\x05"
if bs.get_view(start=1) is Some([b'\x01', b'\x02', ..]) {
()
} else {
abort("unreachable")
}
debug_inspect(bs.get_view(start=10), content="None")
}Bytes::has_prefix
fn Bytes::has_prefix(self : Bytes, prefix : BytesView) -> BoolReturns true if this bytes starts with the given prefix.
Bytes::has_suffix
fn Bytes::has_suffix(self : Bytes, suffix : BytesView) -> BoolReturns true if this bytes ends with the given suffix.
Bytes::is_empty
fn Bytes::is_empty(self : Bytes) -> BoolReturns whether the byte sequence is empty.
Example:
test {
inspect(b"".is_empty(), content="true")
inspect(b"\x00".is_empty(), content="false")
}Bytes::iter
#alias(iterator, deprecated="`iterator` is deprecated, use `iter` instead")
fn Bytes::iter(self : Bytes) -> Iter[Byte]Creates an iterator over the bytes in the sequence.
Parameters:
- bytes : A byte sequence to iterate over.
Returns an iterator that yields each byte in the sequence in order.
Example:
test {
let bytes = Bytes::from_array([b'h', b'i'])
let mut sum = 0
bytes.iter().each(b => sum b.to_int())
inspect(sum, content="209") // ASCII values: 'h'(104) + 'i'(105) = 209
}Bytes::iter2
#alias(iterator2, deprecated="`iterator2` is deprecated, use `iter2` instead")
fn Bytes::iter2(self : Bytes) -> Iter2[Int, Byte]Creates an iterator that yields tuples of index and byte,
indices start from 0.
Example:
test {
let buf = StringBuilder(size_hint=5)
let keys = []
let it = b"abcde".iter2()
while it.next() is Some((i, x)) {
buf.write_string(x.to_string())
keys.push(i)
}
inspect(buf, content="b'\\x61'b'\\x62'b'\\x63'b'\\x64'b'\\x65'")
debug_inspect(keys, content="[0, 1, 2, 3, 4]")
}Bytes::length
fn Bytes::length(self : Bytes) -> IntReturns the number of bytes in a byte sequence.
Parameters:
- bytes : The byte sequence whose length is to be determined.
Returns an integer representing the length (number of bytes) of the sequence.
Example:
test {
let bytes = b"\x01\x02\x03"
inspect(bytes.length(), content="3")
let empty = b""
inspect(empty.length(), content="0")
}Bytes::lexical_compare
fn Bytes::lexical_compare(self : Bytes, other : Bytes) -> IntPerforms a lexicographical comparison of two byte sequences.
This method compares the sequences byte by byte until a difference is found
or one sequence is exhausted. Unlike the Compare trait implementation which
uses shortlex order (shorter sequences come first), this method compares based
purely on byte values until a difference is found.
Returns
- A negative integer if self is lexicographically less than other
- Zero if self is lexicographically equal to other
- A positive integer if self is lexicographically greater than other
Example
test {
inspect(b"\x01\x02".lexical_compare(b"\x01\x02\x03"), content="-1")
inspect(b"\x01\x02\x03".lexical_compare(b"\x01\x02"), content="1")
inspect(b"\x01\x02\x03".lexical_compare(b"\x01\x02\x03"), content="0")
inspect(b"\x01\x02\x03".lexical_compare(b"\x01\x02\x04"), content="-1")
}Bytes::make
fn Bytes::make(len : Int, init : Byte) -> BytesCreates a new byte sequence of the specified length, where each byte is
initialized to the given value. Returns an empty byte sequence if the
length is negative.
Parameters:
- length : The length of the byte sequence to create. A negative value produces an empty byte sequence.
- initial_value : The byte value used to initialize each position in the sequence.
Example:
test {
let bytes = Bytes::make(3, b'\xFF')
inspect(
bytes,
content=(
#|b"\xff\xff\xff"
),
)
let empty = Bytes::make(0, b'\x00')
inspect(empty, content="b\"\"")
}Bytes::makei
fn Bytes::makei(length : Int, value : (Int) -> Byte raise?) -> Bytes raise?Creates a new byte sequence of the specified length, where each byte is
initialized using a function that maps indices to bytes.
Parameters:
- length : The length of the byte sequence to create. If length is less than or equal to 0, returns an empty byte sequence.
- value : A function that takes an index (from 0 to length - 1) and returns a byte for that position.
Returns a new byte sequence containing the bytes produced by applying the
value function to each index.
Example:
test {
let bytes = Bytes::makei(3, i => (i + 65).to_byte())
@test.assert_eq(bytes, b"ABC")
}Bytes::new
fn Bytes::new(len : Int) -> BytesCreates a new byte sequence filled with zero bytes.
Parameters:
- length : The length of the byte sequence to create. Must be a non-negative integer.
Returns a new byte sequence of the specified length, with all bytes
initialized to zero.
Example:
test {
let bytes = Bytes::new(3)
inspect(bytes, content="b\"\\x00\\x00\\x00\"")
let bytes = Bytes::new(0)
inspect(bytes, content="b\"\"")
}Bytes::of_string
#deprecated("check `@encoding/utf8.encode`")
fn Bytes::of_string(str : String) -> BytesEncode a UTF-16 string into raw bytes.
Deprecated: use @encoding/utf8.encode for text encoding.
Example:
test {
let bytes = Bytes::from_array([b'A'])
inspect(bytes.length(), content="1")
}Bytes::repeat
fn Bytes::repeat(self : Bytes, count : Int) -> BytesReturns a new Bytes consisting of self repeated count times.
Aborts if count is negative. If count == 0 or self is empty, an empty
Bytes is returned. When count == 1, self is returned directly without
allocation.
This implementation performs a single allocation sized exactly to the
result and fills it using an exponential copy (doubling) strategy so the
number of blit operations is O(log count).
Example:
test {
inspect(
b"ab".repeat(3),
content=(
#|b"ababab"
),
)
inspect(
b"xyz".repeat(0),
content=(
#|b""
),
)
}Bytes::rev_find
fn Bytes::rev_find(target : Bytes, pattern : BytesView) -> Int?Returns the offset of the last occurrence of the given
bytes substring. If the substring is not found, None is returned.
Bytes::to_array
Converts a bytes sequence into an array of bytes.
Parameters:
- bytes : A sequence of bytes to be converted into an array.
Returns an array containing the same bytes as the input sequence.
Example:
test {
let bytes = b"hello"
let arr = bytes.to_array()
debug_inspect(
arr,
content=(
#|[0x68, 0x65, 0x6c, 0x6c, 0x6f]
),
)
}Bytes::to_fixedarray
fn Bytes::to_fixedarray(self : Bytes, len? : Int) -> FixedArray[Byte]Converts a bytes sequence into a fixed-size array of bytes. If an optional
length is provided, the resulting array will have exactly that length,
otherwise it will match the length of the input bytes.
Parameters:
- self : The bytes sequence to convert.
- len : Optional. The desired length of the output array. If specified, the resulting array will have this length. If not specified, the length of the input bytes sequence will be used.
Returns a fixed-size array containing the bytes from the input sequence.
Example:
test {
let bytes = b"hello"
let arr = bytes.to_fixedarray()
debug_inspect(
arr,
content=(
#|<FixedArray: [0x68, 0x65, 0x6c, 0x6c, 0x6f]>
),
)
let arr2 = bytes[:3].to_fixedarray()
debug_inspect(
arr2,
content=(
#|<FixedArray: [0x68, 0x65, 0x6c]>
),
)
}Panics if the length is invalid
Bytes::to_unchecked_string
fn Bytes::to_unchecked_string(self : Bytes, offset? : Int, length? : Int) -> StringReturn an unchecked string, containing the subsequence of self that starts at
offset and has length length. Both offset and length
are indexed by byte.
Note this function does not validate the encoding of the byte sequence,
it simply copy the bytes into a new String.
Bytes::view
#alias(sub, deprecated="Use _[_:_] instead")
#alias("_[_:_]")
fn Bytes::view(self : Bytes, start? : Int, end? : Int) -> BytesViewCreates a new View from the given Bytes.
Example
test {
let bs = b"\x00\x01\x02\x03\x04\x05"
let bv = bs[1:4]
inspect(bv.length(), content="3")
@test.assert_eq(bv[0], b'\x01')
@test.assert_eq(bv[1], b'\x02')
@test.assert_eq(bv[2], b'\x03')
}BytesView
BytesView::at
#alias("_[_]")
fn BytesView::at(self : BytesView, index : Int) -> ByteRetrieves a byte from the view at the specified index.
Parameters:
- self : The bytes view to retrieve the byte from.
- index : The position in the view from which to retrieve the byte.
Returns the byte at the specified index.
Throws a runtime error if the index is out of bounds (less than 0 or greater
than or equal to the length of the view).
Example:
test {
let bytes = b"\x01\x02\x03\x04\x05"
let view = bytes[1:4] // view contains [0x02, 0x03, 0x04]
inspect(view[1], content="b'\\x03'")
}BytesView::chop_prefix
fn BytesView::chop_prefix(self : BytesView, prefix : BytesView) -> BytesView?Removes the given prefix from the view if it exists.
Returns Some(suffix) if the view starts with the given prefix.
Returns None otherwise.
BytesView::chop_suffix
fn BytesView::chop_suffix(self : BytesView, suffix : BytesView) -> BytesView?Removes the given suffix from the view if it exists.
Returns Some(prefix) if the view ends with the given suffix.
Returns None otherwise.
BytesView::data
fn BytesView::data(self : BytesView) -> BytesRetrieves the underlying Bytes from a View.
BytesView::equal_to_bytes
fn BytesView::equal_to_bytes(self : BytesView, other : Bytes) -> BoolCompares a BytesView to a Bytes byte-for-byte.
This is the cross-type equivalent of == and avoids materializing a fresh
Bytes (or a wrapping BytesView) when probing an owned-Bytes-keyed
container with a view-shaped key.
Returns true if the lengths match and every byte in self equals the
byte at the same index in other.
Example:
test {
let buf = b"prefix_hello_suffix"
inspect(buf[7:12].equal_to_bytes(b"hello"), content="true")
inspect(buf[7:12].equal_to_bytes(b"world"), content="false")
}BytesView::find
fn BytesView::find(target : BytesView, pattern : BytesView) -> Int?Returns the offset of the first occurrence of the given bytes substring.
If the substring is not found, None is returned.
BytesView::get
fn BytesView::get(self : BytesView, index : Int) -> Byte?Retrieves a byte from the view at the specified index.
Parameters:
- self : The bytes view to retrieve the byte from.
- index : The position in the view from which to retrieve the byte.
Returns the byte at the specified index, or None if the index is out of bounds.
Example:
test {
let bytes = b"\x01\x02\x03\x04\x05"
let view = bytes[1:4]
let result = view.get(1)
debug_inspect(
result,
content=(
#|Some(0x03)
),
)
let bytes = b"\x01\x02\x03\x04\x05"
let view = bytes[1:4]
let result = view.get(5)
debug_inspect(result, content="None")
}BytesView::get_view
fn BytesView::get_view(self : BytesView, start? : Int, end? : Int) -> BytesView?Returns a sub-view of the view between start and end, or None if the
range is invalid. The optional variant of BytesView::view (a.k.a.
bv[start:end]).
BytesView::has_prefix
fn BytesView::has_prefix(self : BytesView, prefix : BytesView) -> BoolReturns true if this bytes view starts with the given prefix.
BytesView::has_suffix
fn BytesView::has_suffix(self : BytesView, suffix : BytesView) -> BoolReturns true if this bytes view ends with the given suffix.
BytesView::is_empty
fn BytesView::is_empty(self : BytesView) -> BoolReturns whether the bytes view is empty.
Example:
test {
let view = b"\x00\x01"[1:1]
inspect(view.is_empty(), content="true")
let view = b"\x00\x01"[0:1]
inspect(view.is_empty(), content="false")
}BytesView::iter
#alias(iterator, deprecated="`iterator` is deprecated, use `iter` instead")
fn BytesView::iter(self : BytesView) -> Iter[Byte]Returns an iterator over the View.
Example
test {
let bv = b"\x00\x01\x02\x03\x04\x05"[:]
let mut sum = 0
bv.iter().each(x => sum x.to_int())
inspect(sum, content="15")
}BytesView::iter2
#alias(iterator2, deprecated="`iterator2` is deprecated, use `iter2` instead")
fn BytesView::iter2(self : BytesView) -> Iter2[Int, Byte]Returns an iterator over the View with index.
Example:
test {
let buf = StringBuilder(size_hint=5)
let keys = []
let it = b"abcde"[:].iter2()
while it.next() is Some((i, x)) {
buf.write_string(x.to_string())
keys.push(i)
}
inspect(buf, content="b'\\x61'b'\\x62'b'\\x63'b'\\x64'b'\\x65'")
debug_inspect(keys, content="[0, 1, 2, 3, 4]")
}BytesView::length
fn BytesView::length(self : BytesView) -> IntReturns the number of bytes in the view.
Parameters:
- bytes_view : The view of a byte sequence.
Returns an integer representing the length of the view.
Example:
test {
let bytes = b"\x00\x01\x02\x03\x04"
let view = bytes[2:4]
inspect(view.length(), content="2")
}BytesView::lexical_compare
fn BytesView::lexical_compare(self : BytesView, other : BytesView) -> IntPerforms a lexicographical comparison of two byte views.
This method returns the lexicographical ordering by byte value. Unlike the
Compare trait implementation which uses shortlex order (shorter views come
first), this method compares based purely on byte values until a difference
is found.
Returns
- A negative integer if self is lexicographically less than other
- Zero if self is lexicographically equal to other
- A positive integer if self is lexicographically greater than other
Example
test {
inspect(b"\x01\x02"[:].lexical_compare(b"\x01\x02\x03"), content="-1")
inspect(b"\x01\x02\x03"[:].lexical_compare(b"\x01\x02"), content="1")
inspect(b"\x01\x02\x03"[:].lexical_compare(b"\x01\x02\x03"), content="0")
inspect(b"\x01\x02\x03"[:].lexical_compare(b"\x01\x02\x04"), content="-1")
}BytesView::rev_find
fn BytesView::rev_find(target : BytesView, pattern : BytesView) -> Int?Returns the offset of the last occurrence of the given
bytes substring. If the substring is not found, None is returned.
BytesView::start_offset
fn BytesView::start_offset(self : BytesView) -> IntRetrieves the start index of the view.
BytesView::to_array
Copy this bytes view into a new mutable array.
Example:
test {
let arr = b"ab"[:].to_array()
inspect(arr.length(), content="2")
inspect(arr[0], content="b'\\x61'")
}BytesView::to_fixedarray
fn BytesView::to_fixedarray(self : BytesView) -> FixedArray[Byte]Copy this bytes view into a new fixed array.
Example:
test {
let arr = b"abcd"[1:3].to_fixedarray()
debug_inspect(
arr,
content=(
#|<FixedArray: [0x62, 0x63]>
),
)
}BytesView::to_owned
#alias(to_bytes, deprecated="Use `to_owned` to allocate an owned `Bytes` from a `BytesView`")
fn BytesView::to_owned(self : BytesView) -> BytesReturn a Bytes value containing exactly this view's range.
If the view spans the full underlying bytes, this returns the original value
without copying; otherwise it allocates and copies.
Example:
test {
let b = b"hello"
inspect(b[1:4].to_owned().length(), content="3")
}BytesView::view
#alias(sub, deprecated="Use _[_:_] instead")
#alias("_[_:_]")
fn BytesView::view(self : BytesView, start? : Int, end? : Int) -> BytesViewCreates a new View from the given View.
Example
test {
let bv = b"\x00\x01\x02\x03\x04\x05"[:]
let bv2 = bv[1:4]
inspect(bv2.length(), content="3")
@test.assert_eq(bv2[1], b'\x02')
}Char
Note
Char is a built-in type. The documentation may not be complete here. You can find all methods and implementations in the core/builtin and core/char package.
Char::escape
fn Char::escape(self : Char, quote? : Bool) -> StringReturns the escaped representation of a character.
When quote is true (default), the result is wrapped in single quotes
like a MoonBit character literal.
Escape rules:
- Single quote and backslash are backslash-escaped: \', \\
- Common control characters use named escapes: \n, \r, \b, \t
- ASCII printable characters (U+0020 to U+007E) are displayed as-is
- Printable Unicode characters outside ASCII are displayed as-is
- Non-printable characters use \u{hex} format
test {
inspect('a'.escape(), content="'a'")
inspect('a'.escape(quote=false), content="a")
inspect('\n'.escape(), content="'\\n'")
inspect('\n'.escape(quote=false), content="\\n")
}Char::from_int
#deprecated("Use `Int::unsafe_to_char` instead, and use `Int::to_char` for safe conversion")
fn Char::from_int(val : Int) -> CharDeprecated constructor from raw code point.
Create from int.
Char::is_ascii
fn Char::is_ascii(self : Char) -> BoolChecks if the value is within the ASCII range.
Char::is_ascii_alphabetic
fn Char::is_ascii_alphabetic(self : Char) -> BoolChecks if the value is an ASCII alphabetic character:
- U+0041 'A' ..= U+005A 'Z'
- U+0061 'a' ..= U+007A 'z'
Char::is_ascii_control
fn Char::is_ascii_control(self : Char) -> BoolChecks if the value is an ASCII control character:
U+0000 NUL ..= U+001F UNIT SEPARATOR, or U+007F DELETE.
Note that most ASCII whitespace characters are control characters, but SPACE is not.
Char::is_ascii_digit
fn Char::is_ascii_digit(self : Char) -> BoolChecks if the value is an ASCII decimal digit:
U+0030 '0' ..= U+0039 '9'
Char::is_ascii_graphic
fn Char::is_ascii_graphic(self : Char) -> BoolChecks if the value is an ASCII graphic character:
U+0021 '!' ..= U+007E '~'
Char::is_ascii_hexdigit
fn Char::is_ascii_hexdigit(self : Char) -> BoolChecks if the value is an ASCII hexadecimal digit:
- U+0030 '0' ..= U+0039 '9'
- U+0041 'A' ..= U+0046 'F'
- U+0061 'a' ..= U+0066 'f'
Char::is_ascii_lowercase
fn Char::is_ascii_lowercase(self : Char) -> BoolChecks if the value is an ASCII lowercase character:
U+0061 'a' ..= U+007A 'z'.
Char::is_ascii_octdigit
fn Char::is_ascii_octdigit(self : Char) -> BoolChecks if the value is an ASCII octal digit:
U+0030 '0' ..= U+0037 '7'
Char::is_ascii_punctuation
fn Char::is_ascii_punctuation(self : Char) -> BoolChecks if the value is an ASCII punctuation character:
- U+0021 ..= U+002F ! " # $ % & ' ( ) * + , - . /
- U+003A ..= U+0040 : ; < = > ? @
- U+005B ..= U+0060 [ \ ] ^ _ `
- U+007B ..= U+007E { | } ~
Char::is_ascii_uppercase
fn Char::is_ascii_uppercase(self : Char) -> BoolChecks if the value is an ASCII uppercase character:
U+0041 'A' ..= U+005A 'Z'
Char::is_ascii_whitespace
fn Char::is_ascii_whitespace(self : Char) -> BoolChecks if the value is an ASCII whitespace character:
U+0020 SPACE, U+0009 HORIZONTAL TAB, U+000A LINE FEED, U+000B VERTICAL TAB, U+000C FORM FEED, or U+000D CARRIAGE RETURN.
Char::is_bmp
fn Char::is_bmp(self : Char) -> BoolReturns true if this character is in the Basic Multilingual Plane (BMP).
The BMP (Basic Multilingual Plane) contains 65,536 code points (U+0000 to U+FFFF)
distributed as follows:
- ~57,022 actual Unicode character positions (87% of BMP)
- 2,048 surrogate code points (U+D800-U+DFFF) - reserved for UTF-16 encoding
- High surrogates: U+D800-U+DBFF (1,024 code points)
- Low surrogates: U+DC00-U+DFFF (1,024 code points)
- 6,400 private use area (U+E000-U+F8FF) - for custom characters
- 66 permanent noncharacters (including U+FFFE, U+FFFF, U+FDD0-U+FDEF)
Note: Surrogate code points are not actual characters but encoding mechanisms
for representing characters outside the BMP in UTF-16.
Example:
test {
inspect('A'.is_bmp(), content="true")
inspect('🌟'.is_bmp(), content="false")
}Char::is_control
fn Char::is_control(self : Char) -> BoolReturns true if this char has the general category for control codes.
Char::is_digit
fn Char::is_digit(self : Char, radix : UInt) -> BoolChecks if a char is a digit in the given radix (range from 2 to 36).
panic if the radix is invalid.
Char::is_numeric
fn Char::is_numeric(self : Char) -> BoolReturns true if this char has one of the general categories for numbers.
Char::is_printable
fn Char::is_printable(self : Char) -> BoolReturns true if this character is printable (visible when displayed).
Aligns with Unicode standard categories for printable characters.
Characters are considered printable if they are:
- Letters (L*)
- Marks (M*)
- Numbers (N*)
- Punctuation (P*)
- Symbols (S*)
- Spaces (Zs), with some exceptions Characters are considered non-printable if they are:
- Control characters (Cc)
- Format characters (Cf)
- Line/paragraph separators (Zl, Zp)
- Private use (Co)
- Noncharacters (U+FDD0-U+FDEF and the U+nFFFE/U+nFFFF pairs)
- Surrogates (Cs)
Char::is_whitespace
fn Char::is_whitespace(self : Char) -> BoolReturns true if this char has the White_Space property.
Char::to_ascii_lowercase
fn Char::to_ascii_lowercase(self : Char) -> CharMakes a copy of the value in its ASCII lower case equivalent.
ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
but non-ASCII letters are unchanged.
Char::to_ascii_uppercase
fn Char::to_ascii_uppercase(self : Char) -> CharMakes a copy of the value in its ASCII upper case equivalent.
ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
but non-ASCII letters are unchanged.
Char::to_int
fn Char::to_int(self : Char) -> IntConverts a character to its Unicode code point value as an integer.
Parameters:
- self : The character to be converted.
Returns an integer representing the Unicode code point value of the
character.
Example:
test {
inspect('A'.to_int(), content="65") // ASCII value of 'A'
inspect('あ'.to_int(), content="12354") // Unicode code point of 'あ'
}Char::to_uint
fn Char::to_uint(self : Char) -> UIntConverts a Unicode character to its unsigned 32-bit integer code point
representation. The character's code point value is first converted to a
signed integer and then reinterpreted as an unsigned integer.
Parameters:
- character : The Unicode character to be converted.
Returns an unsigned 32-bit integer representing the character's Unicode code
point.
Example:
test {
let c = 'A'
inspect(c.to_uint(), content="65") // ASCII value of 'A'
let emoji = '🤣'
inspect(emoji.to_uint(), content="129315") // Unicode code point U+1F923
}Char::utf16_len
#alias(length, deprecated="Use `utf16_len` instead")
fn Char::utf16_len(self : Char) -> IntReturns the number of UTF-16 code units required to encode this character.
Parameters:
- self : The character to analyze.
Returns the number of UTF-16 code units (1 or 2) needed to represent this
character.
Note surrogate pairs are counted as 2, it should not happen in general since
surrogate pair is Int instead of Char.
Example:
test {
inspect('A'.utf16_len(), content="1")
inspect('🌟'.utf16_len(), content="2")
}Double
Note
Double is a built-in type. The documentation may not be complete here. You can find all methods and implementations in the core/builtin and core/double package.
Double::Double
fn Double::Double(self : Double) -> DoubleThe identity constructor for Double, allowing values to be written using
constructor syntax, e.g. Double(3.2).
Example:
test {
inspect(Double(3.2), content="3.2")
}Double::abs
fn Double::abs(self : Double) -> DoubleReturns the absolute value of a double-precision floating-point number.
Parameters:
- value : The double-precision floating-point number to compute the absolute value of.
Returns the absolute value of the input number by clearing its sign bit, so
the result is never negative. In particular, (-0.0).abs() is 0.0.
Example:
test {
inspect((-2.5).abs(), content="2.5")
inspect(3.14.abs(), content="3.14")
inspect(0.0.abs(), content="0")
}Double::ceil
fn Double::ceil(self : Double) -> DoubleReturns the smallest integer greater than or equal to the given number.
Parameters:
- self : The floating point number to find the ceiling of.
Returns the ceiling value of the input number.
Example:
test {
inspect(3.7.ceil(), content="4")
inspect((-3.7).ceil(), content="-3")
inspect(42.0.ceil(), content="42")
}Double::clamp
fn Double::clamp(self : Double, min~ : Double, max~ : Double) -> DoubleClamps the value between min and max (inclusive).
Parameters:
- self : The value to clamp.
- min : The lower bound of the range.
- max : The upper bound of the range.
Returns min if self < min, max if self > max, and self otherwise.
Aborts if min is greater than max.
Example:
test {
inspect(0.5.clamp(min=0.0, max=1.0), content="0.5")
inspect((-1.0).clamp(min=0.0, max=1.0), content="0")
inspect(2.0.clamp(min=0.0, max=1.0), content="1")
}Double::convert_uint
fn Double::convert_uint(val : UInt) -> DoubleConverts an unsigned 32-bit integer to a double-precision floating-point
number. Since the range of unsigned 32-bit integers is smaller than what can
be precisely represented by a double-precision floating-point number, this
conversion is guaranteed to be exact.
Parameters:
- value : The unsigned 32-bit integer to be converted.
Returns a double-precision floating-point number that exactly represents the
input value.
Example:
test {
let n = 42U
inspect(Double::convert_uint(n), content="42")
let max = 4294967295U // maximum value of UInt
inspect(Double::convert_uint(max), content="4294967295")
}Double::convert_uint64
fn Double::convert_uint64(val : UInt64) -> DoubleConverts an unsigned 64-bit integer to a double-precision floating-point
number. The conversion is exact for integers up to 53 bits (the size of the
mantissa in a double-precision number), but may lose precision for larger
values.
Parameters:
- value : The unsigned 64-bit integer to be converted.
Returns a double-precision floating-point number representing the same
numerical value as the input.
Example:
let n = 12345678901234567890UL
inspect(Double::convert_uint64(n), content="12345678901234567000")Double::floor
fn Double::floor(self : Double) -> DoubleReturns the largest integer less than or equal to the given number.
Parameters:
- number : A floating-point number to be rounded down.
Returns a double-precision floating-point number representing the largest
integer less than or equal to the input.
Example:
test {
inspect(3.7.floor(), content="3")
inspect((-3.7).floor(), content="-4")
inspect(0.0.floor(), content="0")
}Double::from_int
fn Double::from_int(i : Int) -> DoubleConverts an integer to a double-precision floating-point number.
Parameters:
- integer : The integer value to be converted.
Returns a double-precision floating-point number representing the given
integer value.
Example:
test {
inspect(Double::from_int(42), content="42")
inspect(Double::from_int(-1), content="-1")
}Double::is_close
fn Double::is_close(self : Double, other : Double, relative_tolerance? : Double, absolute_tolerance? : Double) -> BoolDetermines whether two floating-point numbers are approximately equal within
specified tolerances.
The implementation follows the algorithm described in PEP 485 for Python's
math.isclose().
Parameters:
- self : The first floating-point number to compare.
- other : The second floating-point number to compare.
- relative_tolerance : The relative tolerance for the comparison. Must be non-negative. Defaults to 1e-9.
- absolute_tolerance : The absolute tolerance for the comparison. Must be non-negative. Defaults to 0.0.
Returns whether the two numbers are considered approximately equal. Returns
true if the numbers are exactly equal or if they are within either the
relative or absolute tolerance. Returns false if the numbers are not
exactly equal and either of them is infinite.
Example:
test {
let x = 1.0
let y = 1.000000001
inspect(x.is_close(y), content="false")
inspect(x.is_close(y, relative_tolerance=1.0e-10), content="false")
inspect(@double.infinity.is_close(@double.infinity), content="true")
}Double::is_inf
fn Double::is_inf(self : Double) -> BoolChecks whether a double-precision floating-point number represents positive
or negative infinity.
Parameters:
- value : The double-precision floating-point number to check.
Returns true if the value is either positive or negative infinity, false
otherwise.
Example:
test {
inspect(@double.infinity.is_inf(), content="true")
inspect(@double.neg_infinity.is_inf(), content="true")
inspect(42.0.is_inf(), content="false")
}Double::is_nan
fn Double::is_nan(self : Double) -> BoolChecks whether a double-precision floating-point number represents a "Not a
Number" (NaN) value.
Parameters:
- number : A double-precision floating-point value to be checked.
Returns true if the number is NaN, false otherwise.
Example:
test {
inspect(@double.not_a_number.is_nan(), content="true")
inspect(42.0.is_nan(), content="false")
inspect((0.0 / 0.0).is_nan(), content="true")
}Double::is_neg_inf
fn Double::is_neg_inf(self : Double) -> BoolChecks whether a double-precision floating-point number is negative infinity.
Parameters:
- self : The double-precision floating-point number to check.
Returns a boolean value indicating whether the number is negative infinity.
Example:
test {
inspect((-1.0 / 0.0).is_neg_inf(), content="true")
inspect(42.0.is_neg_inf(), content="false")
inspect((1.0 / 0.0).is_neg_inf(), content="false") // positive infinity
}Double::is_pos_inf
fn Double::is_pos_inf(self : Double) -> BoolChecks whether a double-precision floating-point number is positive infinity.
Parameters:
- value : The double-precision floating-point number to check.
Returns true if the number is positive infinity, false otherwise.
Example:
test {
inspect(@double.infinity.is_pos_inf(), content="true")
inspect(@double.neg_infinity.is_pos_inf(), content="false")
inspect(42.0.is_pos_inf(), content="false") // TODO: better formatter
}Double::lerp
fn Double::lerp(self : Double, target~ : Double, t~ : Double) -> DoublePerforms linear interpolation from self to target by factor t.
The interpolation formula is self + (target - self) * t.
Parameters:
- self : The start value.
- target : The end value.
- t : The interpolation factor.
Returns the interpolated value.
Example:
test {
inspect(0.0.lerp(target=10.0, t=0.25), content="2.5")
inspect(5.0.lerp(target=15.0, t=0.0), content="5")
inspect(5.0.lerp(target=15.0, t=1.0), content="15")
}Double::max
fn Double::max(self : Double, other : Double) -> DoubleReturns the maximum of two double-precision floating-point values.
If exactly one argument is NaN, returns the other argument.
Double::min
fn Double::min(self : Double, other : Double) -> DoubleReturns the minimum of two double-precision floating-point values.
If exactly one argument is NaN, returns the other argument.
Double::pow
#deprecated("Use `@math.pow` instead")
fn Double::pow(self : Double, other : Double) -> DoubleCalculates the power of a number by raising the base to the specified
exponent. Handles special cases and edge conditions according to IEEE 754
standards.
Parameters:
- base : The base number to be raised to a power.
- exponent : The power to raise the base number to.
Returns the result of raising base to the power of exponent.
Example:
test {
let x = 2.0
inspect(@math.pow(x, 3.0), content="8")
inspect(@math.pow(x, 0.5), content="1.4142135623730951")
inspect(@math.pow(x, 0.0), content="1")
inspect(@math.pow(-1.0, 2.0), content="1")
inspect(@math.pow(0.0, 0.0), content="1")
inspect(@math.pow(@double.infinity, -1.0), content="0")
}Double::reinterpret_as_i64
#deprecated("Use `reinterpret_as_int64` instead")
fn Double::reinterpret_as_i64(self : Double) -> Int64Reinterprets the bits of a double-precision floating-point number as a 64-bit
signed integer without any conversion. This is a low-level operation that
simply reinterprets the bit pattern of the input value.
Parameters:
- value : The double-precision floating-point number whose bits are to be reinterpreted.
Returns a 64-bit signed integer that has the same bit pattern as the input
double-precision floating-point number.
Example:
test {
let d = 1.0
// 1.0 in IEEE 754 double format has the bit pattern 0x3FF0000000000000
inspect(d.reinterpret_as_int64(), content="4607182418800017408")
}Double::reinterpret_as_int64
fn Double::reinterpret_as_int64(self : Double) -> Int64Reinterprets the bits of a double-precision floating-point number as a 64-bit
signed integer without performing any conversion. Preserves the exact bit
pattern of the input value.
Parameters:
- number : The double-precision floating-point number whose bits will be reinterpreted.
Returns a 64-bit signed integer containing the same bit pattern as the input
floating-point number.
Example:
test {
let d = 1.0
inspect(d.reinterpret_as_int64(), content="4607182418800017408") // IEEE 754 representation of 1.0
let neg = -0.0
inspect(neg.reinterpret_as_int64(), content="-9223372036854775808") // Sign bit set
}Double::reinterpret_as_u64
#deprecated("Use `reinterpret_as_uint64` instead")
fn Double::reinterpret_as_u64(self : Double) -> UInt64Reinterprets the bits of a double-precision floating-point number as an
unsigned 64-bit integer. The bit pattern is preserved during the conversion,
with no mathematical conversion performed.
Parameters:
- self : The double-precision floating-point number to be reinterpreted.
Returns an unsigned 64-bit integer containing the same bit pattern as the
input floating-point number.
Example:
test {
let zero = 0.0
let positive = 1.0
inspect(zero.reinterpret_as_uint64(), content="0")
inspect(positive.reinterpret_as_uint64(), content="4607182418800017408")
}Double::reinterpret_as_uint64
fn Double::reinterpret_as_uint64(self : Double) -> UInt64Reinterprets the bits of a double-precision floating-point number as an
unsigned 64-bit integer, preserving the exact bit pattern without performing
any numerical conversion.
Parameters:
- self : The double-precision floating-point number whose bits will be reinterpreted.
Returns an unsigned 64-bit integer that has the same bit pattern as the input
floating-point number.
Example:
test {
let d = 1.0
inspect(d.reinterpret_as_uint64(), content="4607182418800017408") // Binary: 0x3FF0000000000000
}Double::round
fn Double::round(self : Double) -> DoubleRounds a floating-point number to the nearest integer using "round half up"
rule. In this rule, when a number is halfway between two integers (like 3.5),
it is rounded up to the next integer.
Parameters:
- value : The floating-point number to be rounded.
Returns the rounded value as a double-precision floating-point number.
Example:
test {
inspect(3.7.round(), content="4")
inspect(3.2.round(), content="3")
inspect(3.5.round(), content="4")
inspect((-3.5).round(), content="-3")
}Double::signum
fn Double::signum(self : Double) -> DoubleReturns the sign of the double.
- If the double is positive, returns 1.0.
- If the double is negative, returns -1.0.
- Otherwise, returns the double itself (0.0, -0.0 and NaN).
Double::sqrt
fn Double::sqrt(self : Double) -> DoubleCalculates the square root of a double-precision floating-point number. For
non-negative numbers, returns the positive square root. For negative numbers
or NaN, returns NaN.
Parameters:
- self : The double-precision floating-point number whose square root is to be calculated.
Returns the square root of the input number, or NaN if the input is negative
or NaN.
Example:
test {
inspect(4.0.sqrt(), content="2")
inspect(0.0.sqrt(), content="0")
inspect((-1.0).sqrt(), content="NaN")
}Double::to_float
#deprecated("Use `Float::from_double` instead")
fn Double::to_float(self : Double) -> FloatTODO: enable skip_current_package=false
Convert Double to Float (deprecated alias).
Double::to_int
fn Double::to_int(self : Double) -> IntConverts a double-precision floating-point number to a 32-bit integer.
Handles special cases including NaN and numbers outside the valid Int range.
Parameters:
- self : The double-precision floating-point number to be converted.
Returns an 32-bit integer value according to the following rules:
- Returns 0 if the input is NaN
- Returns @int.MAX_VALUE (2147483647) if the input is greater than or equal to @int.MAX_VALUE
- Returns @int.MIN_VALUE (-2147483648) if the input is less than or equal to @int.MIN_VALUE
- Otherwise returns the integer part of the input by truncating towards zero
Example:
test {
inspect(42.0.to_int(), content="42")
inspect((-42.5).to_int(), content="-42")
inspect((0.0 / 0.0).to_int(), content="0") // NaN
inspect((1.0 / 0.0).to_int(), content="2147483647") // Infinity
inspect((-1.0 / 0.0).to_int(), content="-2147483648") // -Infinity
}Double::to_int64
fn Double::to_int64(self : Double) -> Int64Converts a double-precision floating-point number to a 64-bit integer.
Handles special cases including NaN and numbers outside the valid Int range.
Parameters:
- self : The double-precision floating-point number to be converted.
Returns an 64-bit integer value according to the following rules:
- Returns 0 if the input is NaN
- Returns @int64.MAX_VALUE (9223372036854775807L) if the input is greater than or equal to @int64.MAX_VALUE
- Returns @int64.MIN_VALUE (-9223372036854775808L) if the input is less than or equal to @int64.MIN_VALUE
- Otherwise returns the integer part of the input by truncating towards zero
Example:
test {
inspect(42.0.to_int64(), content="42")
inspect((-42.5).to_int64(), content="-42")
inspect((0.0 / 0.0).to_int64(), content="0") // NaN
inspect((1.0 / 0.0).to_int64(), content="9223372036854775807") // Infinity
inspect((-1.0 / 0.0).to_int64(), content="-9223372036854775808") // -Infinity
}Double::to_string
fn Double::to_string(self : Double) -> StringConverts a double-precision floating-point number to its string
representation.
Parameters:
- self: The double-precision floating-point number to be converted.
Returns a string representation of the double-precision floating-point
number.
Example:
test {
inspect(42.0.to_string(), content="42")
inspect(3.14159.to_string(), content="3.14159")
inspect((-0.0).to_string(), content="0")
inspect(@double.not_a_number.to_string(), content="NaN")
}Double::to_uint
fn Double::to_uint(self : Double) -> UIntConverts a double-precision floating-point number to a 32-bit unsigned
integer. Handles special cases including NaN and numbers outside the valid
UInt range.
Parameters:
- self : The double-precision floating-point number to be converted.
Returns a 32-bit unsigned integer value according to the following rules:
- Returns 0 if the input is NaN
- Returns @uint.MAX_VALUE (4294967295U) if the input is greater than or equal to @uint.MAX_VALUE
- Returns @uint.MIN_VALUE (0U) if the input is less than or equal to @uint.MIN_VALUE
- Otherwise returns the integer part of the input by truncating towards zero
Example:
test {
inspect(42.0.to_uint(), content="42")
inspect((-42.5).to_uint(), content="0")
inspect((0.0 / 0.0).to_uint(), content="0") // NaN
inspect((1.0 / 0.0).to_uint(), content="4294967295") // Infinity
inspect((-1.0 / 0.0).to_uint(), content="0") // -Infinity
}Double::to_uint64
fn Double::to_uint64(self : Double) -> UInt64Converts a double-precision floating-point number to a 64-bit unsigned
integer. Handles special cases including NaN and numbers outside the valid
UInt64 range.
Parameters:
- self : The double-precision floating-point number to be converted.
Returns a 64-bit unsigned integer value according to the following rules:
- Returns 0 if the input is NaN
- Returns @uint64.MAX_VALUE (18446744073709551615UL) if the input is greater than or equal to 9223372036854775807
- Returns 0 if the input is less than or equal to 0
- Otherwise returns the integer part of the input by truncating towards zero
Example:
test {
inspect(42.0.to_uint64(), content="42")
inspect((0.0 / 0.0).to_uint64(), content="0") // NaN
inspect((1.0 / 0.0).to_uint64(), content="18446744073709551615") // Infinity
inspect((-1.0 / 0.0).to_uint64(), content="0") // -Infinity
}Double::trunc
fn Double::trunc(self : Double) -> DoubleReturns an integer value by discarding the decimal part of the floating-point
number (truncation toward zero).
Parameters:
- self : The floating-point number to be truncated.
Returns a floating-point number representing the integer part of the input.
Example:
test {
inspect(3.7.trunc(), content="3")
inspect((-3.7).trunc(), content="-3")
inspect(0.0.trunc(), content="0")
}Double::until
Creates an iterator that iterates over a range of Double with default step 1.0 .
To grow the range downward, set the step parameter to a negative value.
Arguments
- start - The starting value of the range (inclusive).
- end - The ending value of the range (exclusive by default).
- step - The step size of the range (default 1.0).
- inclusive - Whether the ending value is inclusive (default false).
Returns
Returns an iterator that iterates over the range of Double from start to end - 1.
FixedArray
Note
FixedArray is a built-in type. The documentation may not be complete here. You can find all methods and implementations in the core/builtin and core/fixedarray package.
FixedArray::add
fn[T] FixedArray::add(self : FixedArray[T], other : FixedArray[T]) -> FixedArray[T]FixedArray::all
#alias(every)
fn[T] FixedArray::all(self : FixedArray[T], f : (T) -> Bool raise?) -> Bool raise?Check if all the elements in the array match the condition.
Example
test {
let arr : FixedArray[Int] = [1, 2, 3, 4, 5]
assert_true(arr.all(ele => ele < 6))
assert_false(arr.all(ele => ele < 5))
}FixedArray::any
#alias(exists)
fn[T] FixedArray::any(self : FixedArray[T], f : (T) -> Bool raise?) -> Bool raise?Check if any of the elements in the array match the condition.
Example
test {
let arr : FixedArray[Int] = [1, 2, 3, 4, 5]
assert_true(arr.any(ele => ele < 6))
assert_true(arr.any(ele => ele < 5))
}FixedArray::at
#alias("_[_]")
fn[T] FixedArray::at(self : FixedArray[T], idx : Int) -> TRetrieves an element at the specified index from a fixed-size array. This
function implements the array indexing operator [].
Parameters:
- array : The fixed-size array to access.
- index : The position in the array from which to retrieve the element.
Returns the element at the specified index.
Panics if the index is out of bounds.
Example:
test {
let arr = FixedArray::make(3, 42)
inspect(arr[1], content="42")
}FixedArray::binary_search
Performs a binary search on a sorted array to find the index of a given element.
Example
test {
let v : FixedArray[Int] = [3, 4, 5]
let result = v.binary_search(3)
@test.assert_eq(result, Ok(0)) // The element 3 is found at index 0
}Arguments
- self: The array in which to perform the search.
- value: The element to search for in the array.
Returns
- Result[Int, Int]: If the element is found, an Ok variant is returned, containing the index of the matching element in the array. If there are multiple matches, the leftmost match will be returned. If the element is not found, an Err variant is returned, containing the index where the element could be inserted to maintain the sorted order.
Notes
- Ensure that the array is sorted in increasing order before calling this function.
- If the array is not sorted, the returned result is undefined and should not be relied on.
FixedArray::binary_search_by
fn[T] FixedArray::binary_search_by(self : FixedArray[T], cmp : (T) -> Int raise?) -> Result[Int, Int] raise?Performs a binary search on a sorted array using a custom comparison
function. Returns the position of the matching element if found, or the
position where the element could be inserted while maintaining the sorted
order.
Parameters:
- array : The sorted array to search in.
- comparator : A function that compares each element with the target value, returning:
- A negative integer if the element is less than the target
- Zero if the element equals the target
- A positive integer if the element is greater than the target
Returns a Result containing either:
- Ok(index) if a matching element is found at position index
- Err(index) if no match is found, where index is the position where the element could be inserted
Example:
test {
let arr : FixedArray[Int] = [1, 3, 5, 7, 9]
let find_3 = arr.binary_search_by(x => x.compare(3))
debug_inspect(find_3, content="Ok(1)")
let find_4 = arr.binary_search_by(x => x.compare(4))
debug_inspect(find_4, content="Err(2)")
}Notes:
- Assumes the array is sorted according to the ordering implied by the comparison function
- For multiple matches, returns the leftmost matching position
- Returns an insertion point that maintains the sort order when no match is found
FixedArray::blit_from_bytes
fn FixedArray::blit_from_bytes(self : FixedArray[Byte], bytes_offset : Int, src : Bytes, src_offset : Int, length : Int) -> UnitCopy length bytes from byte sequence src, starting at src_offset,
into byte sequence self, starting at bytes_offset.
FixedArray::blit_from_bytesview
fn FixedArray::blit_from_bytesview(self : FixedArray[Byte], bytes_offset : Int, src : BytesView) -> UnitCopy bytes from a BytesView into a fixed array of bytes.
Parameters:
- self : The destination fixed array of bytes.
- bytes_offset : The starting position in the destination array where bytes will be copied.
- src : The source View to copy from.
Throws a panic if:
- bytes_offset is negative
- The destination array is too small to hold all bytes from the source View
Example:
test {
let arr = FixedArray::make(4, b'\x00')
let view = b"\x01\x02\x03"[1:]
arr.blit_from_bytesview(1, view)
debug_inspect(
arr,
content=(
#|<FixedArray: [0x00, 0x02, 0x03, 0x00]>
),
)
}FixedArray::blit_from_string
fn FixedArray::blit_from_string(self : FixedArray[Byte], bytes_offset : Int, str : String, str_offset : Int, length : Int) -> UnitCopies characters from a string to a byte sequence in UTF-16LE encoding. Each
character is converted into two bytes, with the lower byte stored first.
Parameters:
- self : The destination byte array to copy the characters into.
- bytes_offset : The starting position in the destination array where bytes will be written.
- str : The source string containing the characters to copy.
- str_offset : The starting position in the source string from which characters will be read.
- length : The number of characters to copy.
Throws a runtime error if:
- length is negative
- bytes_offset is negative
- str_offset is negative
- The range [bytes_offset, bytes_offset + length * 2) exceeds the length of the destination array
- The range [str_offset, str_offset + length) exceeds the length of the source string
Example:
test {
let bytes = FixedArray::make(6, b'\x00')
bytes.blit_from_string(0, "ABC", 0, 3)
@json.json_inspect(bytes, content=[65, 0, 66, 0, 67, 0]) // 'A'
bytes.blit_from_string(0, "你好啊", 0, 3)
@json.json_inspect(bytes, content=[96, 79, 125, 89, 74, 85]) // '你好啊'
bytes.blit_from_string(0, "😈", 0, 2)
@json.json_inspect(bytes, content=[61, 216, 8, 222, 74, 85]) // '😈'
}FixedArray::blit_to
fn[A] FixedArray::blit_to(self : FixedArray[A], dst : FixedArray[A], len~ : Int, src_offset? : Int, dst_offset? : Int) -> UnitCopies a sequence of elements from the source fixed array to a destination
fixed array. The arrays may overlap, in which case the copy is performed in a
way that preserves the data.
Parameters:
- self : The source fixed array from which elements will be copied.
- dst : The destination fixed array where elements will be copied to.
- len : The number of elements to copy.
- src_offset : The starting position in the source array. Defaults to 0.
- dst_offset : The starting position in the destination array. Defaults to
Throws a panic if:
- src_offset + len exceeds the length of the source array
- dst_offset + len exceeds the length of the destination array
Example:
test {
let src = FixedArray::make(5, 1)
let dst = FixedArray::make(5, 0)
src.blit_to(dst, len=3, src_offset=1, dst_offset=2)
debug_inspect(
dst,
content=(
#|<FixedArray: [0, 0, 1, 1, 1]>
),
)
}FixedArray::compare
FixedArray::contains
Checks if the array contains an element.
Example
test {
let arr : FixedArray[Int] = [3, 4, 5]
assert_true(arr.contains(3))
}FixedArray::copy
#alias(clone, deprecated="`clone` is deprecated, use `copy` instead")
fn[T] FixedArray::copy(self : FixedArray[T]) -> FixedArray[T]Creates a new array that is a copy of the original array.
Parameters:
- self : The array to be copied. The type of elements in the array must be T.
Returns a new array containing all elements from the original array in the
same order.
Example:
test {
let original = [1, 2, 3]
let copied = original.copy()
debug_inspect(copied, content="[1, 2, 3]")
inspect(physical_equal(original, copied), content="false")
}FixedArray::each
fn[T] FixedArray::each(self : FixedArray[T], f : (T) -> Unit raise?) -> Unit raise?Iterates over each element.
Arguments
- self: The array to iterate over.
- f: The function to apply to each element.
Example
test {
let arr = []
[1, 2, 3, 4, 5].each(x => arr.push(x))
@test.assert_eq(arr, [1, 2, 3, 4, 5])
}FixedArray::eachi
fn[T] FixedArray::eachi(self : FixedArray[T], f : (Int, T) -> Unit raise?) -> Unit raise?Iterates over the array with index.
Arguments
- self: The array to iterate over.
- f: A function that takes an Int representing the index and a T representing the element of the array, and returns Unit.
Example
test {
let arr = []
[1, 2, 3, 4, 5].eachi((index, elem) => arr.push((index, elem)))
@test.assert_eq(arr, [(0, 1), (1, 2), (2, 3), (3, 4), (4, 5)])
}FixedArray::ends_with
Check if the array ends with a given suffix.
Example
test {
let v : FixedArray[Int] = [3, 4, 5]
assert_true(v.ends_with([5]))
}FixedArray::equal
FixedArray::fill
fn[T] FixedArray::fill(self : FixedArray[T], value : T, start? : Int, end? : Int) -> UnitFill the array with a given value.
This method fills all or part of a FixedArray with the given value.
Parameters
- value: The value to fill the array with
- start: The starting index (inclusive, default: 0)
- end: The ending index (exclusive, optional)
If end is not provided, fills from start to the end of the array.
If start equals end, no elements are modified.
Panics
- Panics if start is negative or greater than or equal to the array length
- Panics if end is provided and is less than start or greater than array length
- Does nothing if the array is empty
Example
test {
// Fill entire array
let fa : FixedArray[Int] = [0, 0, 0, 0, 0]
fa.fill(3)
debug_inspect(
fa,
content=(
#|<FixedArray: [3, 3, 3, 3, 3]>
),
)
// Fill from index 1 to 3 (exclusive)
let fa2 : FixedArray[Int] = [0, 0, 0, 0, 0]
fa2.fill(9, start=1, end=3)
debug_inspect(
fa2,
content=(
#|<FixedArray: [0, 9, 9, 0, 0]>
),
)
// Fill from index 2 to end
let fa3 : FixedArray[String] = ["a", "b", "c", "d"]
fa3.fill("x", start=2)
debug_inspect(
fa3,
content=(
#|<FixedArray: ["a", "b", "x", "x"]>
),
)
}FixedArray::fold
fn[A, B] FixedArray::fold(self : FixedArray[A], init~ : B, f : (B, A) -> B raise?) -> B raise?Fold out values from an array according to certain rules.
Example
test {
let sum = [1, 2, 3, 4, 5].fold(init=0, (sum, elem) => sum + elem)
inspect(sum, content="15")
}FixedArray::foldi
fn[A, B] FixedArray::foldi(self : FixedArray[A], init~ : B, f : (Int, B, A) -> B raise?) -> B raise?Fold out values from an array according to certain rules with index.
Example
test {
let sum = [1, 2, 3, 4, 5].foldi(init=0, (index, sum, _elem) => sum + index)
inspect(sum, content="10")
}FixedArray::from_array
Creates a new fixed-size array from a dynamic array. The resulting fixed
array will have the same length and elements as the input array.
Parameters:
- array : A dynamic array containing elements of type T that will be converted to a fixed array.
Returns a new fixed array containing the same elements as the input array.
Example:
test {
let dynamic_array : ReadOnlyArray[Int] = [1, 2, 3, 4, 5]
let fixed_array = FixedArray::from_array(dynamic_array)
debug_inspect(
fixed_array,
content=(
#|<FixedArray: [1, 2, 3, 4, 5]>
),
)
}FixedArray::from_iter
#alias(from_iterator, deprecated="`from_iterator` is deprecated, use `from_iter` instead")
fn[T] FixedArray::from_iter(iter : Iter[T]) -> FixedArray[T]Creates a new fixed array from an iterator.
Parameters:
- iterator : An iterator of type Iter[T] from which elements will be collected into a fixed array.
Returns a new fixed array containing all elements from the iterator.
Example:
test {
let arr = [1, 2, 3]
let fixed_arr = FixedArray::from_iter(arr.iter())
debug_inspect(
fixed_arr,
content=(
#|<FixedArray: [1, 2, 3]>
),
)
}FixedArray::get
fn[T] FixedArray::get(self : FixedArray[T], idx : Int) -> T?Retrieves an element at the specified index from a fixed-size array.
Parameters:
- array : The fixed-size array to access.
- index : The position in the array from which to retrieve the element.
Returns Some(element) if the index is within bounds, or None if the index
is out of bounds.
Example:
test {
let arr : FixedArray[Int] = [1, 2, 3]
debug_inspect(arr.get(1), content="Some(2)")
let arr : FixedArray[Int] = [1, 2, 3]
debug_inspect(arr.get(3), content="None")
}FixedArray::get_view
Creates a new ArrayView from a FixedArray, returning None when indices
are invalid.
Parameters:
- self : The fixed array to create a new view from.
- start : The starting index in the array (inclusive). Defaults to 0.
- end : The ending index in the array (exclusive). Defaults to the length of the array.
Returns Some(ArrayView) that provides a window into the specified portion
of the original fixed array, or None when the indices are invalid.
Example:
test {
let arr : FixedArray[Int] = [1, 2, 3, 4, 5]
let start = 1
let end = 4
debug_inspect(
arr.get_view(start~, end~),
content=(
#|Some(<ArrayView: [2, 3, 4]>)
),
)
let start = 2
let end = 10
debug_inspect(arr.get_view(start~, end~), content="None")
}FixedArray::is_empty
fn[T] FixedArray::is_empty(self : FixedArray[T]) -> BoolTests whether the FixedArray contains no elements.
Parameters:
- FixedArray : The FixedArray to check.
Returns true if the FixedArray has no elements, false otherwise.
Example:
test {
let empty : FixedArray[Int] = []
inspect(empty.is_empty(), content="true")
let non_empty = [1, 2, 3]
inspect(non_empty.is_empty(), content="false")
}FixedArray::is_sorted
Checks if the elements in the array are sorted in ascending order according
to their natural ordering.
Parameters:
- array : A fixed array of type T, where T must implement the Compare trait.
Returns true if the array is sorted in ascending order, false otherwise.
An empty array or an array with a single element is considered sorted.
Example:
test {
let sorted : FixedArray[Int] = [1, 2, 3, 4, 5]
let unsorted : FixedArray[Int] = [5, 4, 3, 2, 1]
inspect(FixedArray::is_sorted(sorted), content="true")
inspect(FixedArray::is_sorted(unsorted), content="false")
}FixedArray::iter
#alias(iterator, deprecated="`iterator` is deprecated, use `iter` instead")
fn[X] FixedArray::iter(self : FixedArray[X]) -> Iter[X]Return an iterator over elements of the fixed array.
iterator is a deprecated alias for this function.
Example:
test {
debug_inspect(
([1, 2, 3] : FixedArray[Int]).iter().collect(),
content="[1, 2, 3]",
)
}FixedArray::iter2
#alias(iterator2, deprecated="`iterator2` is deprecated, use `iter2` instead")
fn[X] FixedArray::iter2(self : FixedArray[X]) -> Iter2[Int, X]Return an index-value iterator over the fixed array.
iterator2 is a deprecated alias for this function.
Example:
test {
debug_inspect(
([10, 20] : FixedArray[Int]).iter2().to_array(),
content="[(0, 10), (1, 20)]",
)
}FixedArray::join
Concatenate the string-renderable elements of the array into a single
complete string, separated by separator.
Example:
test {
let fixed_array : FixedArray[String] = ["1", "2", "3"]
inspect(fixed_array.join(","), content="1,2,3")
}FixedArray::last
fn[A] FixedArray::last(self : FixedArray[A]) -> A?Returns the last element of a fixed array if it exists.
Parameters:
- self : The fixed array to get the last element from.
Returns Some(element) containing the last element if the array is not
empty, or None if the array is empty.
Example:
test {
let array : FixedArray[Int] = [1, 2, 3]
debug_inspect(array.last(), content="Some(3)")
let empty : FixedArray[Int] = []
debug_inspect(empty.last(), content="None")
}FixedArray::length
fn[T] FixedArray::length(self : FixedArray[T]) -> IntReturns the number of elements in a fixed-size array.
Parameters:
- array : The fixed-size array whose length is to be determined.
Returns an integer representing the number of elements in the array.
Example:
test {
let arr = FixedArray::make(3, 42)
inspect(arr.length(), content="3")
}FixedArray::lexical_compare
Performs a lexicographical comparison of two fixed arrays.
This method compares the arrays element by element until a difference is
found or one array is exhausted. Unlike the Compare trait implementation
which uses shortlex order (shorter arrays come first), this method compares
based purely on element values until a difference is found.
Returns
- A negative integer if self is lexicographically less than other
- Zero if self is lexicographically equal to other
- A positive integer if self is lexicographically greater than other
Example
test {
let a : FixedArray[Int] = [1, 2]
let b : FixedArray[Int] = [1, 2, 3]
inspect(a.lexical_compare(b), content="-1")
inspect(b.lexical_compare(a), content="1")
let c : FixedArray[Int] = [1, 2, 3]
inspect(b.lexical_compare(c), content="0")
let d : FixedArray[Int] = [1, 2, 4]
inspect(b.lexical_compare(d), content="-1")
}FixedArray::make
fn[T] FixedArray::make(len : Int, init : T) -> FixedArray[T]Creates a new fixed-size array with the specified length, initializing all
elements with the given value.
Parameters:
- length : The length of the array to create. Must be non-negative.
- initial_value : The value used to initialize all elements in the array.
Returns a new fixed-size array of type FixedArray[T] with length
elements, where each element is initialized to initial_value.
Throws a panic if length is negative.
Example:
test {
let arr = FixedArray::make(3, 42)
inspect(arr[0], content="42")
inspect(arr.length(), content="3")
}WARNING: A common pitfall is creating with the same initial value, for example:
test {
let two_dimension_array = FixedArray::make(10, FixedArray::make(10, 0))
two_dimension_array[0][5] = 10
@test.assert_eq(two_dimension_array[5][5], 10)
}This is because all the cells reference to the same object (the FixedArray[Int] in this case).
One should use makei() instead which creates an object for each index.
FixedArray::make_and_blit
fn[T] FixedArray::make_and_blit(src : FixedArray[T], allocate_len~ : Int, init~ : T, len~ : Int, src_offset? : Int, dst_offset? : Int) -> FixedArray[T]Creates a fixed array initialized with init, then blits len elements
from src into it.
FixedArray::makei
fn[T] FixedArray::makei(length : Int, value : (Int) -> T raise?) -> FixedArray[T] raise?Creates a new fixed-size array of the specified length, where each element is
initialized using a function that maps indices to values.
Parameters:
- length : The length of the array to create. If length is less than or equal to 0, returns an empty array.
- initializer : A function that takes an index (from 0 to length - 1) and returns a value of type T for that position.
Returns a new fixed array containing the values produced by applying the
initializer function to each index.
Example:
test {
let arr = FixedArray::makei(3, i => i * 2)
debug_inspect(
arr,
content=(
#|<FixedArray: [0, 2, 4]>
),
)
}FixedArray::map
fn[T, U] FixedArray::map(self : FixedArray[T], f : (T) -> U raise?) -> FixedArray[U] raise?Applies a function to each element of the array and returns a new array with the results.
Example
test {
let arr = [1, 2, 3, 4, 5]
let doubled = arr.map(x => x * 2)
@test.assert_eq(doubled, [2, 4, 6, 8, 10])
}FixedArray::mapi
fn[T, U] FixedArray::mapi(self : FixedArray[T], f : (Int, T) -> U raise?) -> FixedArray[U] raise?Maps a function over the elements of the arr with index.
Example
test {
let arr = [3, 4, 5]
let added = arr.mapi((i, x) => x + i)
@test.assert_eq(added, [3, 5, 7])
}FixedArray::mut_view
Creates a new mutable ArrayView from a FixedArray.
Parameters:
- self : The fixed array to create a new view from.
- start : The starting index in the array (inclusive). Defaults to 0.
- end : The ending index in the array (exclusive). Defaults to the length of the array.
Returns a new MutArrayView that provides a window into the specified portion
of the original fixed array.
Throws a panic if:
- start is negative
- end is greater than the length of the array
- start is greater than end
Example:
test {
let arr : FixedArray[Int] = [1, 2, 3, 4, 5]
let view = arr.mut_view(start=1, end=4) // view = [2, 3, 4]
inspect(view[0], content="2")
}FixedArray::rev
fn[T] FixedArray::rev(self : FixedArray[T]) -> FixedArray[T]Returns a new array containing all elements in reverse order. The original
array remains unchanged.
Parameters:
- self : The array to be reversed.
Returns a new array with the same elements but in reverse order.
Example:
test {
let arr : FixedArray[Int] = [1, 2, 3, 4, 5]
debug_inspect(
arr.rev(),
content=(
#|<FixedArray: [5, 4, 3, 2, 1]>
),
)
// Original array remains unchanged
debug_inspect(
arr,
content=(
#|<FixedArray: [1, 2, 3, 4, 5]>
),
)
}FixedArray::rev_each
fn[T] FixedArray::rev_each(self : FixedArray[T], f : (T) -> Unit raise?) -> Unit raise?Iterates over each element in reversed turn.
Arguments
- self: The array to iterate over.
- f: The function to apply to each element.
Example
test {
let arr = []
[1, 2, 3, 4, 5].rev_each(x => arr.push(x))
@test.assert_eq(arr, [5, 4, 3, 2, 1])
}FixedArray::rev_eachi
fn[T] FixedArray::rev_eachi(self : FixedArray[T], f : (Int, T) -> Unit raise?) -> Unit raise?Iterates over the array with index in reversed turn.
Arguments
- self: The array to iterate over.
- f: A function that takes an Int representing the index and a T representing the element of the array, and returns Unit.
Example
test {
let arr = []
[1, 2, 3, 4, 5].rev_eachi((index, elem) => arr.push((index, elem)))
@test.assert_eq(arr, [(0, 5), (1, 4), (2, 3), (3, 2), (4, 1)])
}FixedArray::rev_fold
fn[A, B] FixedArray::rev_fold(self : FixedArray[A], init~ : B, f : (B, A) -> B raise?) -> B raise?Fold out values from an array according to certain rules in reversed turn.
Example
test {
let sum = [1, 2, 3, 4, 5].rev_fold(init=0, (sum, elem) => sum + elem)
inspect(sum, content="15")
}FixedArray::rev_foldi
fn[A, B] FixedArray::rev_foldi(self : FixedArray[A], init~ : B, f : (Int, B, A) -> B raise?) -> B raise?Fold out values from an array according to certain rules in reversed turn with index.
Example
test {
let sum = [1, 2, 3, 4, 5].rev_foldi(init=0, (index, sum, _elem) => sum + index)
inspect(sum, content="10")
}FixedArray::rev_in_place
#alias(rev_inplace, deprecated="`rev_inplace` is deprecated, use `rev_in_place` instead")
fn[T] FixedArray::rev_in_place(self : FixedArray[T]) -> UnitReverses the array in place by swapping elements from both ends until
reaching the middle.
Parameters:
- array : The array to be reversed. The array will be modified in place.
Example:
test {
let arr : FixedArray[_] = [1, 2, 3, 4, 5]
arr.rev_in_place()
debug_inspect(
arr,
content=(
#|<FixedArray: [5, 4, 3, 2, 1]>
),
)
}FixedArray::search
Search the array index for a given element.
Example
test {
let arr : FixedArray[Int] = [3, 4, 5]
@test.assert_eq(arr.search(3), Some(0))
}FixedArray::set
#alias("_[_]=_")
fn[T] FixedArray::set(self : FixedArray[T], idx : Int, val : T) -> UnitSets the value at the specified index in a fixed-size array.
Parameters:
- array : The fixed-size array to be modified.
- index : The index at which to set the value. Must be non-negative and less than the array's length.
- value : The value to be set at the specified index.
Throws a runtime error if the index is out of bounds (less than 0 or greater
than or equal to the array's length).
Example:
test {
let arr = FixedArray::make(3, 0)
arr.set(1, 42)
inspect(arr[1], content="42")
}FixedArray::set_utf16be_char
fn FixedArray::set_utf16be_char(self : FixedArray[Byte], offset : Int, value : Char) -> IntFill UTF16BE encoded char value into byte sequence self, starting at offset.
It return the length of bytes has been written.
This function will panic if the value is out of range.
FixedArray::set_utf16le_char
fn FixedArray::set_utf16le_char(self : FixedArray[Byte], offset : Int, value : Char) -> IntFill UTF16LE encoded char value into byte sequence self, starting at offset.
It return the length of bytes has been written.
This function will panic if the value is out of range.
FixedArray::set_utf8_char
fn FixedArray::set_utf8_char(self : FixedArray[Byte], offset : Int, value : Char) -> IntEncodes a Unicode character into UTF-8 bytes and writes them into a fixed
array of bytes at the specified offset.
Parameters:
- array : The fixed array of bytes to write into.
- offset : The starting position in the array where the encoded bytes will be written.
- char : The Unicode character to be encoded.
Returns the number of bytes written (1 to 4 bytes depending on the
character's code point).
Throws a panic if:
- The character's code point is greater than 0x10FFFF.
test {
let buf = FixedArray::make(4, b'\x00')
let written = buf.set_utf8_char(0, '€') // Euro symbol (U+20AC)
inspect(written, content="3") // UTF-8 encoding takes 3 bytes
inspect(buf[0], content="b'\\xE2'")
inspect(buf[1], content="b'\\x82'")
inspect(buf[2], content="b'\\xAC'")
}FixedArray::sort
Sorts the array
It's an in-place, unstable sort(it will reorder equal elements). The time complexity is O(n log n) in the worst case.
Example
test {
let arr : FixedArray[Int] = [5, 4, 3, 2, 1]
arr.sort()
@test.assert_eq(arr, [1, 2, 3, 4, 5])
}FixedArray::sort_by
fn[T] FixedArray::sort_by(self : FixedArray[T], cmp : (T, T) -> Int) -> UnitSorts the array with a custom comparison function.
It's an in-place, unstable sort(it will reorder equal elements). The time complexity is O(n log n) in the worst case.
Example
test {
let arr : FixedArray[Int] = [5, 3, 2, 4, 1]
arr.sort_by((a, b) => a - b)
@test.assert_eq(arr, [1, 2, 3, 4, 5])
}FixedArray::sort_by_key
Sorts the array with a key extraction function.
It's an in-place, unstable sort(it will reorder equal elements). The time complexity is O(n log n) in the worst case.
Example
test {
let arr : FixedArray[Int] = [5, 3, 2, 4, 1]
arr.sort_by_key(x => -x)
@test.assert_eq(arr, [5, 4, 3, 2, 1])
}FixedArray::stable_sort
Sorts the array
It's a stable sort(it will not reorder equal elements). The time complexity is O(n * log(n)) in the worst case.
Example
test {
let arr : FixedArray[Int] = [5, 4, 3, 2, 1]
arr.stable_sort()
@test.assert_eq(arr, [1, 2, 3, 4, 5])
}FixedArray::starts_with
Check if the array starts with a given prefix.
Example
test {
let arr : FixedArray[Int] = [3, 4, 5]
assert_true(arr.starts_with([3, 4]))
}FixedArray::swap
fn[T] FixedArray::swap(self : FixedArray[T], i : Int, j : Int) -> UnitSwap two elements in the array.
Example
test {
let arr = [1, 2, 3, 4, 5]
arr.swap(0, 1)
@test.assert_eq(arr, [2, 1, 3, 4, 5])
}FixedArray::unsafe_blit
fn[A] FixedArray::unsafe_blit(dst : FixedArray[A], dst_offset : Int, src : FixedArray[A], src_offset : Int, len : Int) -> UnitCopies a slice of elements from one fixed array to another.
This function copies len elements from src starting at src_offset to dst starting at dst_offset.
The arrays may overlap, in which case the copy is performed in a way that preserves the data.
Example
test {
let src = FixedArray::from_array([1, 2, 3, 4, 5])
let dst = FixedArray::from_array([0, 0, 0, 0, 0])
FixedArray::unsafe_blit(dst, 0, src, 0, 3)
@test.assert_eq(dst, FixedArray::from_array([1, 2, 3, 0, 0]))
}The behavior is undefined and platform-specific if:
- len < 0
- src_offset < 0
- dst_offset < 0
- dst_offset + len > dst.length()
- src_offset + len > src.length()
FixedArray::unsafe_write_uint16_be
fn FixedArray::unsafe_write_uint16_be(bytes : FixedArray[Byte], index : Int, value : UInt16) -> UnitUNSAFE: Writes a UInt16 to the FixedArray[Byte] in big-endian byte order.
⚠️ Warning: This function is unsafe and can cause undefined behavior!
Safety
- No bounds checking: This function does not verify that index + 1 < bytes.length()
- Buffer overrun risk: Writing beyond the array boundary may corrupt memory
- Alignment: No alignment requirements, but misaligned access may be slower on some architectures
- Responsibility: Caller must ensure sufficient space is available
Parameters
- bytes: The FixedArray[Byte] to write to
- index: Starting byte index (0-based)
- value: The UInt16 value to write
Behavior
Writes 2 bytes starting at index in big-endian order:
- bytes[index] ← bits 8-15 (most significant)
- bytes[index+1] ← bits 0-7 (least significant)
FixedArray::unsafe_write_uint16_le
fn FixedArray::unsafe_write_uint16_le(bytes : FixedArray[Byte], index : Int, value : UInt16) -> UnitUNSAFE: Writes a UInt16 to the FixedArray[Byte] in little-endian byte order.
⚠️ Warning: This function is unsafe and can cause undefined behavior!
Safety
- No bounds checking: This function does not verify that index + 1 < bytes.length()
- Buffer overrun risk: Writing beyond the array boundary may corrupt memory
- Alignment: No alignment requirements, but misaligned access may be slower on some architectures
- Responsibility: Caller must ensure sufficient space is available
Parameters
- bytes: The FixedArray[Byte] to write to
- index: Starting byte index (0-based)
- value: The UInt16 value to write
Behavior
Writes 2 bytes starting at index in little-endian order:
- bytes[index] ← bits 0-7 (least significant)
- bytes[index+1] ← bits 8-15 (most significant)
FixedArray::unsafe_write_uint32_be
fn FixedArray::unsafe_write_uint32_be(bytes : FixedArray[Byte], index : Int, value : UInt) -> UnitUNSAFE: Writes a UInt32 to the FixedArray[Byte] in big-endian byte order.
⚠️ Warning: This function is unsafe and can cause undefined behavior!
Safety
- No bounds checking: This function does not verify that index + 3 < bytes.length()
- Buffer overrun risk: Writing beyond the array boundary may corrupt memory
- Alignment: No alignment requirements, but misaligned access may be slower on some architectures
- Responsibility: Caller must ensure sufficient space is available
Parameters
- bytes: The FixedArray[Byte] to write to
- index: Starting byte index (0-based)
- value: The UInt32 value to write
Behavior
Writes 4 bytes starting at index in big-endian order:
- bytes[index] ← bits 24-31 (most significant)
- bytes[index+1] ← bits 16-23
- bytes[index+2] ← bits 8-15
- bytes[index+3] ← bits 0-7 (least significant)
FixedArray::unsafe_write_uint32_le
fn FixedArray::unsafe_write_uint32_le(bytes : FixedArray[Byte], index : Int, value : UInt) -> UnitUNSAFE: Writes a UInt32 to the FixedArray[Byte] in little-endian byte order.
⚠️ Warning: This function is unsafe and can cause undefined behavior!
Safety
- No bounds checking: This function does not verify that index + 3 < bytes.length()
- Buffer overrun risk: Writing beyond the array boundary may corrupt memory
- Alignment: No alignment requirements, but misaligned access may be slower on some architectures
- Responsibility: Caller must ensure sufficient space is available
Parameters
- bytes: The FixedArray[Byte] to write to
- index: Starting byte index (0-based)
- value: The UInt32 value to write
Behavior
Writes 4 bytes starting at index in little-endian order:
- bytes[index] ← bits 0-7 (least significant)
- bytes[index+1] ← bits 8-15
- bytes[index+2] ← bits 16-23
- bytes[index+3] ← bits 24-31 (most significant)
FixedArray::unsafe_write_uint64_be
fn FixedArray::unsafe_write_uint64_be(bytes : FixedArray[Byte], index : Int, value : UInt64) -> UnitUNSAFE: Writes a UInt64 to the FixedArray[Byte] in big-endian byte order.
⚠️ Warning: This function is unsafe and can cause undefined behavior!
Safety
- No bounds checking: This function does not verify that index + 7 < bytes.length()
- Buffer overrun risk: Writing beyond the array boundary may corrupt memory
- Alignment: No alignment requirements, but misaligned access may be slower on some architectures
- Responsibility: Caller must ensure sufficient space is available
Parameters
- bytes: The FixedArray[Byte] to write to
- index: Starting byte index (0-based)
- value: The UInt64 value to write
Behavior
Writes 8 bytes starting at index in big-endian order:
- bytes[index] ← bits 56-63 (most significant)
- bytes[index+1] ← bits 48-55
- ...
- bytes[index+7] ← bits 0-7 (least significant)
FixedArray::unsafe_write_uint64_le
fn FixedArray::unsafe_write_uint64_le(bytes : FixedArray[Byte], index : Int, value : UInt64) -> UnitUNSAFE: Writes a UInt64 to the FixedArray[Byte] in little-endian byte order.
⚠️ Warning: This function is unsafe and can cause undefined behavior!
Safety
- No bounds checking: This function does not verify that index + 7 < bytes.length()
- Buffer overrun risk: Writing beyond the array boundary may corrupt memory
- Alignment: No alignment requirements, but misaligned access may be slower on some architectures
- Responsibility: Caller must ensure sufficient space is available
Parameters
- bytes: The FixedArray[Byte] to write to
- index: Starting byte index (0-based)
- value: The UInt64 value to write
Behavior
Writes 8 bytes starting at index in little-endian order:
- bytes[index] ← bits 0-7 (least significant)
- bytes[index+1] ← bits 8-15
- ...
- bytes[index+7] ← bits 56-63 (most significant)
FixedArray::view
#alias(sub, deprecated="Use _[_:_] instead")
#alias("_[_:_]")
fn[T] FixedArray::view(self : FixedArray[T], start? : Int, end? : Int) -> ArrayView[T]Creates a new ArrayView from a FixedArray.
Parameters:
- self : The fixed array to create a new view from.
- start : The starting index in the array (inclusive). Defaults to 0.
- end : The ending index in the array (exclusive). Defaults to the length of the array.
Returns a new ArrayView that provides a window into the specified portion
of the original fixed array.
Throws a panic if:
- start is negative
- end is greater than the length of the array
- start is greater than end
Example:
test {
let arr : FixedArray[Int] = [1, 2, 3, 4, 5]
let view = arr[1:4] // view = [2, 3, 4]
inspect(view[0], content="2")
}Int
Note
Int is a built-in type. The documentation may not be complete here. You can find all methods and implementations in the core/builtin and core/int package.
Int::Int
fn Int::Int(self : Int) -> IntThe identity constructor for Int, allowing values to be written using
constructor syntax, e.g. Int(3).
Example:
test {
inspect(Int(3), content="3")
}Int::abs
fn Int::abs(self : Int) -> IntComputes the absolute value of an integer.
Parameters:
- self : The integer whose absolute value is to be computed.
Returns the absolute value of the integer. When the input is
@int.min_value (-2147483648), returns @int.min_value itself, since its
absolute value is not representable as an Int.
Example:
test {
inspect(Int::abs(42), content="42")
inspect(Int::abs(-42), content="42")
inspect(Int::abs(0), content="0")
}Int::asr
#deprecated("Use infix operator `>>` instead")
fn Int::asr(self : Int, other : Int) -> IntPerforms an arithmetic right shift operation on a 32-bit integer value,
preserving the sign bit by replicating it into the positions vacated by the
shift. This is a deprecated function; use the infix operator >> instead.
Parameters:
- self : The integer value to be shifted.
- shift : The number of positions to shift right. Must be non-negative.
Returns a new integer value that is the result of arithmetically shifting
self right by shift positions.
Example:
test {
let x = -16
inspect(x >> 2, content="-4") // Right shift preserves sign bit
}Int::clamp
fn Int::clamp(self : Int, min~ : Int, max~ : Int) -> IntClamps the value self between min and max. Aborts if min is greater
than max.
Example:
test {
inspect((1).clamp(min=0, max=2), content="1")
inspect((-1).clamp(min=0, max=2), content="0")
inspect((3).clamp(min=0, max=2), content="2")
inspect((-1).clamp(min=0, max=2), content="0")
}Int::clz
fn Int::clz(self : Int) -> IntCounts the number of consecutive zero bits at the most significant end of
the integer's binary representation.
Parameters:
- self : The integer value whose leading zeros are to be counted.
Returns the number of leading zero bits (0 to 32). For example, returns 0 if
the value is negative (the sign bit is 1), returns 32 if the value is 0
(all bits are zeros).
Example:
test {
let x = 0
inspect(x.clz(), content="32") // All bits are zero
let y = -1
inspect(y.clz(), content="0") // The sign bit is set
let z = 16
inspect(z.clz(), content="27") // Binary: ...00010000
}Int::ctz
fn Int::ctz(self : Int) -> IntCounts the number of consecutive zero bits at the least significant end of
the integer's binary representation.
Parameters:
- self : The integer value whose trailing zeros are to be counted.
Returns the number of trailing zero bits (0 to 32). For example, returns 0 if
the value is odd (least significant bit is 1), returns 32 if the value is 0
(all bits are zeros).
Example:
test {
let x = 0
inspect(x.ctz(), content="32") // All bits are zero
let y = 1
inspect(y.ctz(), content="0") // No trailing zeros
let z = 16
inspect(z.ctz(), content="4") // Binary: ...10000
}Int::is_leading_surrogate
fn Int::is_leading_surrogate(self : Int) -> BoolChecks if the integer value represents a UTF-16 leading surrogate.
Leading surrogates are in the range 0xD800 to 0xDBFF.
Example:
test {
inspect((0xD800).is_leading_surrogate(), content="true")
inspect((0xDBFF).is_leading_surrogate(), content="true")
inspect((0xDC00).is_leading_surrogate(), content="false")
inspect((0x41).is_leading_surrogate(), content="false") // 'A'
}Int::is_neg
fn Int::is_neg(self : Int) -> BoolTests whether an integer is negative.
Parameters:
- self : The integer to test.
Returns true if the integer is negative, false otherwise.
Example:
test {
let neg = -42
let zero = 0
let pos = 42
inspect(neg.is_neg(), content="true")
inspect(zero.is_neg(), content="false")
inspect(pos.is_neg(), content="false")
}Int::is_non_neg
fn Int::is_non_neg(self : Int) -> BoolTests whether an integer is non-negative (greater than or equal to zero).
Parameters:
- self : The integer to test.
Returns true if the integer is greater than or equal to zero, false
otherwise.
Example:
test {
let neg = -42
let zero = 0
let pos = 42
inspect(neg.is_non_neg(), content="false")
inspect(zero.is_non_neg(), content="true")
inspect(pos.is_non_neg(), content="true")
}Int::is_non_pos
fn Int::is_non_pos(self : Int) -> BoolTests whether an integer is non-positive (less than or equal to zero).
Parameters:
- self : The integer to test.
Returns true if the integer is less than or equal to zero, false
otherwise.
Example:
test {
let neg = -42
let zero = 0
let pos = 42
inspect(neg.is_non_pos(), content="true")
inspect(zero.is_non_pos(), content="true")
inspect(pos.is_non_pos(), content="false")
}Int::is_pos
fn Int::is_pos(self : Int) -> BoolTests whether an integer is strictly positive.
Parameters:
- self : The integer to test.
Returns true if the integer is strictly positive, false otherwise.
Example:
test {
let neg = -42
let zero = 0
let pos = 42
inspect(neg.is_pos(), content="false")
inspect(zero.is_pos(), content="false")
inspect(pos.is_pos(), content="true")
}Int::is_surrogate
fn Int::is_surrogate(self : Int) -> BoolChecks if the integer value represents any UTF-16 surrogate (leading or trailing).
Surrogates are in the range 0xD800 to 0xDFFF.
Example:
test {
inspect((0xD800).is_surrogate(), content="true") // leading surrogate
inspect((0xDC00).is_surrogate(), content="true") // trailing surrogate
inspect((0xDFFF).is_surrogate(), content="true") // trailing surrogate
inspect((0x41).is_surrogate(), content="false") // 'A'
inspect((0x1F600).is_surrogate(), content="false") // 😀 emoji codepoint
}Int::is_trailing_surrogate
fn Int::is_trailing_surrogate(self : Int) -> BoolChecks if the integer value represents a UTF-16 trailing surrogate.
Trailing surrogates are in the range 0xDC00 to 0xDFFF.
Example:
test {
inspect((0xDC00).is_trailing_surrogate(), content="true")
inspect((0xDFFF).is_trailing_surrogate(), content="true")
inspect((0xD800).is_trailing_surrogate(), content="false")
inspect((0x41).is_trailing_surrogate(), content="false") // 'A'
}Int::lnot
fn Int::lnot(self : Int) -> IntPerforms a bitwise NOT operation on a 32-bit integer. Flips each bit in the
integer's binary representation (0 becomes 1 and 1 becomes 0).
Parameters:
- value : The 32-bit integer on which to perform the bitwise NOT operation.
Returns a new integer with all bits flipped from the input value.
Example:
test {
let a = -1 // All bits are 1
let b = 0 // All bits are 0
inspect(a.lnot(), content="0")
inspect(b.lnot(), content="-1")
}Int::lsl
#deprecated("Use infix operator `<<` instead")
fn Int::lsl(self : Int, other : Int) -> IntPerforms a left shift operation on a 32-bit integer. Shifts each bit in the
integer to the left by the specified number of positions, filling the vacated
bit positions with zeros.
Parameters:
- self : The integer value to be shifted.
- shift : The number of positions to shift the bits to the left.
Returns an integer containing the result of shifting self left by shift
positions.
Example:
test {
let x = 1
inspect(x << 3, content="8") // Binary: 1 -> 1000
let y = 42
inspect(y << 2, content="168") // Binary: 101010 -> 10101000
}Int::lsr
#deprecated("Use UInt type and infix operator `>>` instead")
fn Int::lsr(self : Int, other : Int) -> IntPerforms a logical right shift operation on a signed 32-bit integer. In a
logical right shift, zeros are shifted in from the left, regardless of the
sign bit. This function is DEPRECATED and users should use UInt type with
the infix operator >> instead.
Parameters:
- self : The signed 32-bit integer value to be shifted.
- shift : The number of positions to shift right. Must be non-negative.
Returns a signed 32-bit integer containing the same bits as if the input were
treated as an unsigned integer and shifted right logically.
Example:
test {
let x = -4 // Binary: 11111...11100
let unsigned = x.reinterpret_as_uint() // Convert to UInt first
inspect(unsigned >> 1, content="2147483646") // Using the recommended operator
}Int::max
fn Int::max(self : Int, other : Int) -> IntReturns the maximum of two integers.
Example:
test {
inspect((1).max(2), content="2")
inspect((2).max(1), content="2")
}Int::min
fn Int::min(self : Int, other : Int) -> IntReturns the minimum of two integers.
Example:
test {
inspect((1).min(2), content="1")
inspect((2).min(1), content="1")
}Int::next_power_of_two
fn Int::next_power_of_two(self : Int) -> IntReturns the smallest power of two greater than or equal to self.
This function will panic if self is negative. For values greater than
the largest representable power of two (2^30 = 1073741824), it returns
the largest representable power of two.
Example:
test {
inspect((0).next_power_of_two(), content="1")
inspect((1).next_power_of_two(), content="1")
inspect((2).next_power_of_two(), content="2")
inspect((3).next_power_of_two(), content="4")
inspect((8).next_power_of_two(), content="8")
inspect((1073741824).next_power_of_two(), content="1073741824")
inspect((2000000000).next_power_of_two(), content="1073741824")
}Int::popcnt
fn Int::popcnt(self : Int) -> IntCounts the number of set bits (1s) in the binary representation of a 32-bit
integer.
Parameters:
- self : The 32-bit integer whose bits are to be counted.
Returns the number of bits set to 1 in the binary representation of the input
integer.
Example:
test {
let x = 0b1011 // Binary: 1011 (3 bits set)
inspect(x.popcnt(), content="3")
let y = -1 // All bits set in two's complement
inspect(y.popcnt(), content="32")
}Int::reinterpret_as_float
#deprecated("Use `Float::reinterpret_from_int` instead")
fn Int::reinterpret_as_float(self : Int) -> FloatReinterpret Int bit pattern as Float (deprecated alias).
Function reinterpret_as_float.
Int::reinterpret_as_uint
fn Int::reinterpret_as_uint(self : Int) -> UIntreinterpret the signed int as unsigned int, when the value is
non-negative, i.e, 0..=2^31-1, the value is the same. When the
value is negative, it turns into a large number,
for example, -1 turns into 2^32-1
Int::shl
#deprecated("Use infix operator `<<` instead")
fn Int::shl(self : Int, other : Int) -> IntPerforms a left shift operation on a 32-bit integer. Shifts the bits of the
first operand to the left by the specified number of positions. The rightmost
positions are filled with zeros.
Parameters:
- value : The integer value to be shifted.
- shift : The number of positions to shift left. Must be non-negative and less than 32.
Returns a new integer value after performing the left shift operation. The
value is equal to multiplying the input by 2 raised to the power of the shift
count.
Example:
test {
let x = 1
inspect(x << 3, content="8") // Equivalent to x << 3
}Int::shr
#deprecated("Use infix operator `>>` instead")
fn Int::shr(self : Int, other : Int) -> IntPerforms an arithmetic right shift operation on a 32-bit integer by the
specified number of positions. The operation preserves the sign bit,
replicating it into the positions vacated by the shift.
Parameters:
- self : The integer value to be shifted.
- shift : The number of positions to shift right.
Returns a new integer representing the result of shifting self right by
shift positions.
Example:
test {
let n = -1024
inspect(n >> 3, content="-128") // Preserves sign bit during right shift
}Int::to_byte
fn Int::to_byte(self : Int) -> ByteConverts a 32-bit signed integer to a byte by taking its least significant 8
bits. Any bits beyond the first 8 bits are truncated.
Parameters:
- value : The 32-bit signed integer to be converted. Only the least significant 8 bits will be used.
Returns a byte containing the least significant 8 bits of the input integer.
Example:
test {
let n = 258 // In binary: 100000010
inspect(n.to_byte(), content="b'\\x02'") // Only keeps 00000010
let neg = -1 // In binary: all 1's
inspect(neg.to_byte(), content="b'\\xFF'") // Only keeps 11111111
}Int::to_char
fn Int::to_char(self : Int) -> Char?Convert integer to Char if it is a valid Unicode scalar value.
Int::to_double
fn Int::to_double(self : Int) -> DoubleConverts a 32-bit integer to a double-precision floating-point number. The
conversion preserves the exact value since all integers in the range of Int
can be represented exactly as Double values.
Parameters:
- self : The 32-bit integer to be converted.
Returns a double-precision floating-point number that represents the same
numerical value as the input integer.
Example:
test {
let n = 42
inspect(n.to_double(), content="42")
let neg = -42
inspect(neg.to_double(), content="-42")
}Int::to_float
#deprecated("Use `Float::from_int` instead")
fn Int::to_float(self : Int) -> FloatConvert Int to Float (deprecated alias).
Convert to float.
Int::to_int16
#deprecated("Use `Int16::from_int` instead")
fn Int::to_int16(self : Int) -> Int16Convert Int to Int16 (deprecated alias).
Convert to int16.
Int::to_int64
fn Int::to_int64(self : Int) -> Int64Converts a 32-bit signed integer to a 64-bit signed integer. All 32-bit
integers can be represented exactly in 64-bit integer format, so the
conversion is lossless.
Parameters:
- self : The 32-bit signed integer to be converted.
Returns a 64-bit signed integer that represents the same numerical value as
the input.
Example:
test {
let n = 42
inspect(n.to_int64(), content="42")
let neg = -42
inspect(neg.to_int64(), content="-42")
}Int::to_string
fn Int::to_string(self : Int, radix? : Int) -> StringConverts an integer to its string representation in the specified radix (base).
Example:
inspect((255).to_string(radix=16), content="ff")
inspect((-255).to_string(radix=16), content="-ff")Int::to_uint
#deprecated("Use `reinterpret_as_uint` instead")
fn Int::to_uint(self : Int) -> UIntReinterprets a signed 32-bit integer as an unsigned 32-bit integer. For
numbers within the range [0, 2^31-1], the value remains the same. For
negative numbers, they are reinterpreted as large positive numbers in the
range [2^31, 2^32-1].
Parameters:
- value : The signed 32-bit integer to be reinterpreted.
Returns an unsigned 32-bit integer that has the same bit pattern as the
input.
Example:
test {
let pos = 42
let neg = -1
inspect(pos.reinterpret_as_uint(), content="42")
inspect(neg.reinterpret_as_uint(), content="4294967295") // 2^32 - 1
}Int::to_uint16
fn Int::to_uint16(self : Int) -> UInt16Converts a 32-bit signed integer to a 16-bit unsigned integer by truncating
its value to fit within the range of 0 to 65535.
Parameters:
- integer : The 32-bit signed integer to be converted. Values outside the range of UInt16 will be truncated to fit.
Returns a 16-bit unsigned integer containing the lower 16 bits of the input
value.
Example:
test {
let n = 42
inspect(n.to_uint16(), content="42")
let neg = -1
inspect(neg.to_uint16(), content="65535") // -1 becomes max value of UInt16
let large = 65536
inspect(large.to_uint16(), content="0") // Values wrap around
}Int::to_uint64
fn Int::to_uint64(self : Int) -> UInt64Converts a 32-bit signed integer to an unsigned 64-bit integer by first
converting it to a signed 64-bit integer and then reinterpreting the bits as
an unsigned value.
Parameters:
- value : The 32-bit signed integer to be converted.
Returns an unsigned 64-bit integer representing the same bit pattern as the
input value when extended to 64 bits.
Example:
test {
let pos = 42
inspect(pos.to_uint64(), content="42")
let neg = -1
inspect(neg.to_uint64(), content="18446744073709551615") // 2^64 - 1
}Int::until
Creates an iterator that iterates over a range of Int with default step 1.
To grow the range downward, set the step parameter to a negative value.
Arguments
- start - The starting value of the range (inclusive).
- end - The ending value of the range (exclusive by default).
- step - The step size of the range (default 1).
- inclusive - Whether the ending value is inclusive (default false).
Returns
Returns an iterator that iterates over the range of Int from start to end - 1.
Int64
Note
Int64 is a built-in type. The documentation may not be complete here. You can find all methods and implementations in the core/builtin and core/int64 package.
Int64::Int64
fn Int64::Int64(self : Int64) -> Int64The identity constructor for Int64, allowing values to be written using
constructor syntax, e.g. Int64(3).
Example:
test {
inspect(Int64(3), content="3")
}Int64::abs
fn Int64::abs(self : Int64) -> Int64Computes the absolute value of a 64-bit integer.
Parameters:
- self : The 64-bit integer whose absolute value is to be computed.
Returns the absolute value of the input integer. When the input is
@int64.MIN_VALUE (-9223372036854775808), returns @int64.MIN_VALUE
itself, since its absolute value is not representable as an Int64.
Example:
test {
inspect(42L.abs(), content="42")
inspect((-42L).abs(), content="42")
inspect(0L.abs(), content="0")
}Int64::asr
#deprecated("Use infix operator `>>` instead")
fn Int64::asr(self : Int64, other : Int) -> Int64DEPRECATED: Use the infix operator >> instead.
Performs an arithmetic right shift operation on a 64-bit integer. In an
arithmetic right shift, the leftmost bit (sign bit) is copied to fill in from
the left. This preserves the sign of the number.
Parameters:
- self : The 64-bit integer to be shifted.
- positions : The number of positions to shift right. Must be non-negative.
Returns a new 64-bit integer that is the result of shifting self right by
positions bits, with sign extension.
Example:
test {
let x = -240L // 0b1111_1111_0001_0000 in two's complement
inspect(x >> 4, content="-15") // 0b1111_1111_1111_0001, using recommended syntax
}Int64::clamp
fn Int64::clamp(self : Int64, min~ : Int64, max~ : Int64) -> Int64Clamps a 64-bit signed integer into the inclusive range [min, max].
Parameters:
- self : The value to clamp.
- min : The lower bound of the range.
- max : The upper bound of the range.
Returns min if self is less than min, max if self is greater
than max, and self otherwise. Aborts if min is greater than max.
Example:
test {
inspect(5L.clamp(min=0L, max=10L), content="5")
inspect((-5L).clamp(min=0L, max=10L), content="0")
inspect(15L.clamp(min=0L, max=10L), content="10")
}Int64::clz
fn Int64::clz(self : Int64) -> IntCounts the number of leading zero bits in a 64-bit signed integer, starting
from the most significant bit.
Parameters:
- number : The 64-bit signed integer whose leading zeros are to be counted.
Returns the number of leading zero bits (0 to 64).
Example:
test {
let a = 0x0000_0001_0000_0000L
inspect(a.clz(), content="31") // 31 leading zeros before the first 1 bit
let b = 0L
inspect(b.clz(), content="64") // All bits are zero
}Int64::ctz
fn Int64::ctz(self : Int64) -> IntReturns the number of trailing zero bits in a 64-bit integer. For zero input,
returns 64.
Parameters:
- value : The 64-bit integer to count trailing zeros in.
Returns the number of trailing zero bits (0 to 64).
Example:
test {
inspect(0x8000000000000000L.ctz(), content="63") // Binary: 1000...0000
inspect(0x0000000000000001L.ctz(), content="0") // Binary: ...0001
inspect(0L.ctz(), content="64") // All zeros
}Int64::from_int
fn Int64::from_int(i : Int) -> Int64Converts a 32-bit integer (Int) to a 64-bit integer (Int64).
Parameters:
- i : The integer value to be converted.
Returns the converted 64-bit integer (Int64) value.
Example:
test {
inspect(Int64::from_int(42), content="42")
}Int64::lnot
fn Int64::lnot(self : Int64) -> Int64Performs a bitwise NOT operation on a 64-bit integer. Each bit in the input
value is flipped (0 becomes 1 and 1 becomes 0).
Parameters:
- self : The 64-bit integer on which to perform the bitwise NOT operation.
Returns a new 64-bit integer where each bit is the inverse of the
corresponding bit in the input value.
Example:
test {
let a = -1L // All bits are 1
let b = 0L // All bits are 0
inspect(a.lnot(), content="0")
inspect(b.lnot(), content="-1")
}Int64::lsl
#deprecated("Use infix operator `<<` instead")
fn Int64::lsl(self : Int64, other : Int) -> Int64Performs a left shift operation on a 64-bit signed integer. Shifts each bit
in the integer to the left by the specified number of positions, filling the
vacated bit positions with zeros.
Parameters:
- self : The 64-bit signed integer to be shifted.
- shift : The number of positions to shift. Must be non-negative and less than 64.
Returns a new 64-bit integer with bits shifted left by the specified number
of positions.
Example:
test {
let x = 1L
inspect(x << 2, content="4") // Binary: 1 -> 100
}Int64::lsr
#deprecated("Use UInt64 type and infix operator `>>` instead")
fn Int64::lsr(self : Int64, other : Int) -> Int64DEPRECATED: Use UInt64 type and infix operator >> instead.
Performs a logical right shift on a 64-bit integer value. In a logical right
shift, zeros are shifted in from the left, regardless of the sign bit.
Parameters:
- value : The 64-bit integer value to be shifted.
- shift : The number of positions to shift right. Must be non-negative.
Returns a new 64-bit integer value that is the result of shifting the bits of
value right by shift positions.
Example:
test {
let x = (-4L).reinterpret_as_uint64() // Convert to UInt64 first
inspect(x >> 1, content="9223372036854775806") // Using the recommended operator
}Int64::max
fn Int64::max(self : Int64, other : Int64) -> Int64Returns the larger of two 64-bit signed integers.
Parameters:
- self : The first integer to compare.
- other : The second integer to compare.
Returns self if it is not less than other, other otherwise.
Example:
test {
inspect(1L.max(2L), content="2")
inspect(2L.max(1L), content="2")
inspect((-1L).max(0L), content="0")
}Int64::min
fn Int64::min(self : Int64, other : Int64) -> Int64Returns the smaller of two 64-bit signed integers.
Parameters:
- self : The first integer to compare.
- other : The second integer to compare.
Returns self if it is not greater than other, other otherwise.
Example:
test {
inspect(1L.min(2L), content="1")
inspect(2L.min(1L), content="1")
inspect((-1L).min(0L), content="-1")
}Int64::popcnt
fn Int64::popcnt(self : Int64) -> IntReturns the number of 1 bits ('population count') in the 64-bit integer's
binary representation.
Parameters:
- value : The 64-bit integer whose bits are to be counted.
Returns an integer representing the number of set bits (1s) in the binary
representation of the input.
Example:
test {
let x = 0x7000_0001_1F00_100FL // Binary: 0111 0000 ... 0001 1111 0000 0000 0001 0000 0000 1111
inspect(x.popcnt(), content="14")
}test {
inspect((-1L).popcnt(), content="64") // All bits set
inspect(0L.popcnt(), content="0") // No bits set
}Int64::reinterpret_as_double
fn Int64::reinterpret_as_double(self : Int64) -> DoubleReinterprets the bits of a 64-bit signed integer as a double-precision
floating-point number (IEEE 754). The bit pattern is preserved exactly, only
the type interpretation changes.
Parameters:
- value : The 64-bit signed integer whose bits are to be reinterpreted as a double-precision floating-point number.
Returns a double-precision floating-point number whose bit pattern is
identical to the input integer.
Example:
test {
let n = 4607182418800017408L // Bit pattern for 1.0
inspect(n.reinterpret_as_double(), content="1")
}Int64::reinterpret_as_uint64
fn Int64::reinterpret_as_uint64(self : Int64) -> UInt64Reinterprets a 64-bit signed integer as an unsigned 64-bit integer without
changing its bit pattern. The reinterpretation follows the standard two's
complement representation rules.
Parameters:
- self : The 64-bit signed integer to be reinterpreted.
Returns a 64-bit unsigned integer that has the same bit pattern as the input.
Example:
test {
let neg = -1L
inspect(neg.reinterpret_as_uint64(), content="18446744073709551615") // All bits set to 1
let pos = 42L
inspect(pos.reinterpret_as_uint64(), content="42") // Positive numbers remain unchanged
}Int64::shl
#deprecated("Use infix operator `<<` instead")
fn Int64::shl(self : Int64, other : Int) -> Int64Performs a left shift operation on a 64-bit integer value. Shifts the bits of
the integer to the left by a specified number of positions, filling the
rightmost positions with zeros.
Parameters:
- self : The 64-bit integer value to be shifted.
- shift : The number of positions to shift the bits to the left.
Returns a new 64-bit integer value after performing the left shift operation.
Example:
test {
let x = 1L
inspect(x << 3, content="8") // Equivalent to x << 3
}Int64::shr
#deprecated("Use infix operator `>>` instead")
fn Int64::shr(self : Int64, other : Int) -> Int64Performs an arithmetic right shift operation on a 64-bit integer value,
shifting the bits to the right by the specified number of positions. The sign
bit is copied to fill the leftmost positions.
Parameters:
- self : The 64-bit integer value to be shifted.
- shift : The number of bit positions to shift right. Must be non-negative.
Returns a new Int64 value representing the result of the arithmetic right
shift operation.
Example:
test {
let n = -1024L
inspect(n >> 3, content="-128") // Preserves sign bit
}Int64::to_byte
fn Int64::to_byte(self : Int64) -> ByteConverts a 64-bit signed integer to a byte by taking its least significant 8
bits. Any bits beyond the first 8 bits are truncated.
Parameters:
- self : The 64-bit signed integer to be converted. Only the least significant 8 bits will be used.
Returns a byte containing the least significant 8 bits of the input integer.
Example:
test {
let n = 258L // In binary: 100000010
inspect(n.to_byte(), content="b'\\x02'") // Only keeps 00000010
let neg = -1L // In binary: all 1's
inspect(neg.to_byte(), content="b'\\xFF'") // Only keeps 11111111
}Int64::to_double
fn Int64::to_double(self : Int64) -> DoubleConverts a 64-bit signed integer to a double-precision floating-point number.
Parameters:
- self : The 64-bit signed integer to be converted.
Returns a double-precision floating-point number that represents the same
value as the input integer.
Example:
test {
let big = 9223372036854775807L // max value of Int64
inspect(big.to_double(), content="9223372036854776000")
let neg = -42L
inspect(neg.to_double(), content="-42")
}Int64::to_float
#deprecated("Use `Float::from_int64` instead")
fn Int64::to_float(self : Int64) -> FloatConvert Int64 to Float (deprecated alias).
Int64::to_int
fn Int64::to_int(self : Int64) -> IntConverts a 64-bit signed integer to a 32-bit signed integer by truncating
higher bits.
Parameters:
- value : The 64-bit signed integer (Int64) to be converted.
Returns a 32-bit signed integer (Int). Note that values outside the range
of 32-bit integers will be truncated, potentially leading to loss of
information.
Example:
test {
let small = 42L
let big = 2147483648L // 2^31
inspect(small.to_int(), content="42")
inspect(big.to_int(), content="-2147483648") // Truncated to Int.min_value
}Int64::to_string
fn Int64::to_string(self : Int64, radix? : Int) -> StringConverts a 64-bit integer to its string representation in the specified radix (base).
Int64::to_uint16
fn Int64::to_uint16(self : Int64) -> UInt16Converts a 64-bit signed integer to a 16-bit unsigned integer by truncating
the value to fit within the range of UInt16 (0 to 65535).
Parameters:
- value : The 64-bit signed integer to be converted to UInt16.
Returns a 16-bit unsigned integer representing the lower 16 bits of the input
value.
Example:
test {
inspect(42L.to_uint16(), content="42")
inspect((-1L).to_uint16(), content="65535") // Wraps around to maximum UInt16 value
inspect(70000L.to_uint16(), content="4464") // Value is truncated
}Int64::to_uint64
#deprecated("Use `reinterpret_as_uint64` instead")
fn Int64::to_uint64(self : Int64) -> UInt64Reinterprets a 64-bit signed integer as an unsigned 64-bit integer without
changing its bits. When the value is non-negative, i.e., within the range
[0, 2^63-1], the value remains the same. When the value is negative, it
becomes a large number in the range [2^63, 2^64-1].
Parameters:
- value : The 64-bit signed integer (Int64) to be reinterpreted.
Returns an unsigned 64-bit integer (UInt64) containing the same bit pattern
as the input.
Example:
test {
let pos = 42L
let neg = -1L
inspect(pos.reinterpret_as_uint64(), content="42")
inspect(neg.reinterpret_as_uint64(), content="18446744073709551615") // 2^64 - 1
}Int64::until
Creates an iterator that iterates over a range of Int64 with default step 1L.
To grow the range downward, set the step parameter to a negative value.
Arguments
- start - The starting value of the range (inclusive).
- end - The ending value of the range (exclusive by default).
- step - The step size of the range (default 1L).
- inclusive - Whether the ending value is inclusive (default false).
Returns
Returns an iterator that iterates over the range of Int64 from start to end - 1.
Option
Option::bind
fn[T, U] Option::bind(self : T?, f : (T) -> U? raise?) -> U? raise?Binds an option to a function that returns another option.
Example
test {
let a = Option::Some(5)
let r1 = a.bind(x => Some(x * 2))
@test.assert_eq(r1, Some(10))
let b : Int? = None
let r2 = b.bind(x => Some(x * 2))
@test.assert_eq(r2, None)
}Option::filter
fn[T] Option::filter(self : T?, f : (T) -> Bool raise?) -> T? raise?Filters the option by applying the given predicate function f.
If the predicate function f returns true for the value contained in the option,
the same option is returned. Otherwise, None is returned.
Example
test {
let x = Some(3)
@test.assert_eq(x.filter(x => x > 5), None)
@test.assert_eq(x.filter(x => x < 5), Some(3))
}Option::flatten
#deprecated("use `option.bind(x => x)` instead")
fn[T] Option::flatten(self : T??) -> T?Flatten nested option/result value.
Option::is_empty
#deprecated("use `x is None` instead")
fn[T] Option::is_empty(self : T?) -> BoolChecks if the option is empty.
Option::is_none
#deprecated("use `x is None` instead")
fn[T] Option::is_none(self : T?) -> BoolChecks if the option is None.
Option::is_some
#deprecated("use `x is Some(_)` instead")
fn[T] Option::is_some(self : T?) -> BoolChecks if the option contains a value.
Option::iter
#alias(iterator, deprecated="`iterator` is deprecated, use `iter` instead")
fn[T] Option::iter(self : T?) -> Iter[T]Return an iterator via iter.
Option::map
fn[T, U] Option::map(self : T?, f : (T) -> U raise?) -> U? raise?Maps the value of an Option using a provided function.
Example
test {
let a = Some(5)
@test.assert_eq(a.map(x => x * 2), Some(10))
let b = None
@test.assert_eq(b.map(x => x * 2), None)
}Option::map_or
fn[T, U] Option::map_or(self : T?, default : U, f : (T) -> U raise?) -> U raise?Returns the provided default result (if none), or applies a function to the contained value (if any).
Arguments passed to map_or are eagerly evaluated; if you are passing the result of a function call, it is recommended to use map_or_else, which is lazily evaluated.
Example
test {
let a = Some(5)
@test.assert_eq(a.map_or(3, x => x * 2), 10)
}Option::map_or_else
fn[T, U] Option::map_or_else(self : T?, default : () -> U raise?, f : (T) -> U raise?) -> U raise?Computes a default function result (if none), or applies a different function to the contained value (if any).
Example
test {
let a = Some(5)
@test.assert_eq(a.map_or_else(() => 3, x => x * 2), 10)
}Option::to_string
#deprecated("Option does not have a meaningful string representation")
fn[X : Show] Option::to_string(self : X?) -> StringConvert to string.
Option::unwrap
fn[X] Option::unwrap(self : X?) -> XExtract the value in Some.
If the value is None, it throws a panic.
Option::unwrap_or
#alias(or, deprecated="`or` is deprecated, use `unwrap_or` instead")
fn[T] Option::unwrap_or(self : T?, default : T) -> TReturn the contained Some value or the provided default.
Option::unwrap_or_default
#alias(or_default, deprecated="`or_default` is deprecated, use `unwrap_or_default` instead")
fn[T : Default] Option::unwrap_or_default(self : T?) -> TReturn the contained Some value or the result of the T::default().
Option::unwrap_or_else
#alias(or_else, deprecated="`or_else` is deprecated, use `unwrap_or_else` instead")
fn[T] Option::unwrap_or_else(self : T?, default : () -> T raise?) -> T raise?Return the contained Some value or the provided default.
Default is lazily evaluated
Option::unwrap_or_error
#alias(or_error, deprecated="`or_error` is deprecated, use `unwrap_or_error` instead")
fn[T, Err : Error] Option::unwrap_or_error(self : T?, err : Err) -> T raise ErrExtract the wrapped value with unwrap_or_error semantics.
ReadOnlyArray
ReadOnlyArray::all
#alias(every)
fn[T] ReadOnlyArray::all(self : ReadOnlyArray[T], f : (T) -> Bool raise?) -> Bool raise?Checks if all elements satisfy the given predicate.
Example
test {
let arr : ReadOnlyArray[Int] = [2, 4, 6]
inspect(arr.all(fn(x) { x % 2 == 0 }), content="true")
let arr2 : ReadOnlyArray[Int] = [1, 2, 3]
inspect(arr2.all(fn(x) { x % 2 == 0 }), content="false")
}ReadOnlyArray::any
#alias(exists)
fn[T] ReadOnlyArray::any(self : ReadOnlyArray[T], f : (T) -> Bool raise?) -> Bool raise?Checks if any element satisfies the given predicate.
Example
test {
let arr : ReadOnlyArray[Int] = [1, 3, 5]
inspect(arr.any(fn(x) { x % 2 == 0 }), content="false")
let arr2 : ReadOnlyArray[Int] = [1, 2, 3]
inspect(arr2.any(fn(x) { x % 2 == 0 }), content="true")
}ReadOnlyArray::at
#alias("_[_]")
fn[T] ReadOnlyArray::at(self : ReadOnlyArray[T], index : Int) -> TAccess element at index in a read-only array.
Panics if index is out of bounds.
Example:
test {
let a : ReadOnlyArray[Int] = [10, 20, 30]
inspect(a.at(1), content="20")
}ReadOnlyArray::binary_search
Performs binary search on a sorted ReadOnlyArray.
Example
test {
let arr : ReadOnlyArray[Int] = [1, 3, 5, 7, 9]
debug_inspect(arr.binary_search(5), content="Ok(2)")
debug_inspect(arr.binary_search(6), content="Err(3)")
}ReadOnlyArray::binary_search_by
fn[T] ReadOnlyArray::binary_search_by(self : ReadOnlyArray[T], cmp : (T) -> Int raise?) -> Result[Int, Int] raise?Performs binary search using a custom comparison function.
Example
test {
let arr : ReadOnlyArray[Int] = [1, 3, 5, 7, 9]
let result = arr.binary_search_by(fn(x) { x.compare(5) })
debug_inspect(result, content="Ok(2)")
}ReadOnlyArray::chunk_by
Groups consecutive elements into chunks where each adjacent pair satisfies
pred. A new chunk starts as soon as pred(prev, cur) is false. Each
returned sub-view shares the original backing storage.
Example
test {
let arr : ReadOnlyArray[Int] = [1, 1, 2, 2, 2, 3, 1]
debug_inspect(
arr.chunk_by((a, b) => a == b),
content=(
#|[
#| <ArrayView: [1, 1]>,
#| <ArrayView: [2, 2, 2]>,
#| <ArrayView: [3]>,
#| <ArrayView: [1]>,
#|]
),
)
}ReadOnlyArray::chunks
Splits the array into consecutive non-overlapping chunks of length size,
from left to right. The final chunk is shorter when length is not a
multiple of size. Each returned sub-view shares the original backing
storage — no allocation per chunk.
Panics if size <= 0.
Example
test {
let arr : ReadOnlyArray[Int] = [1, 2, 3, 4, 5, 6, 7]
debug_inspect(
arr.chunks(3),
content=(
#|[<ArrayView: [1, 2, 3]>, <ArrayView: [4, 5, 6]>, <ArrayView: [7]>]
),
)
}ReadOnlyArray::compare
ReadOnlyArray::contains
Checks if the ReadOnlyArray contains a specific value.
Example
test {
let arr : ReadOnlyArray[Int] = [1, 2, 3]
inspect(arr.contains(2), content="true")
inspect(arr.contains(4), content="false")
}ReadOnlyArray::each
fn[T] ReadOnlyArray::each(self : ReadOnlyArray[T], f : (T) -> Unit raise?) -> Unit raise?Iterates over each element in the ReadOnlyArray.
Example
test {
let arr : ReadOnlyArray[Int] = [1, 2, 3]
let result = []
arr.each(fn(x) { result.push(x * 2) })
debug_inspect(result, content="[2, 4, 6]")
}ReadOnlyArray::eachi
fn[T] ReadOnlyArray::eachi(self : ReadOnlyArray[T], f : (Int, T) -> Unit raise?) -> Unit raise?Iterates over each element with its index.
Example
test {
let arr : ReadOnlyArray[Int] = [10, 20, 30]
let result = []
arr.eachi(fn(i, x) { result.push((i, x)) })
debug_inspect(result, content="[(0, 10), (1, 20), (2, 30)]")
}ReadOnlyArray::ends_with
Checks if the ReadOnlyArray ends with the given suffix.
Example
test {
let arr : ReadOnlyArray[Int] = [1, 2, 3, 4, 5]
inspect(arr.ends_with([4, 5]), content="true")
}ReadOnlyArray::equal
ReadOnlyArray::filter
fn[T] ReadOnlyArray::filter(self : ReadOnlyArray[T], f : (T) -> Bool raise?) -> ReadOnlyArray[T] raise?Returns a new ReadOnlyArray containing the elements for which f returns
true, in original order.
Example
test {
let arr : ReadOnlyArray[Int] = [1, 2, 3, 4, 5]
debug_inspect(
arr.filter(x => x % 2 == 0),
content=(
#|<ReadOnlyArray: [2, 4]>
),
)
}ReadOnlyArray::filter_map
fn[A, B] ReadOnlyArray::filter_map(self : ReadOnlyArray[A], f : (A) -> B? raise?) -> ReadOnlyArray[B] raise?Returns a new ReadOnlyArray that maps and filters in one pass: for each
element, Some(new_value) includes the mapped value and None drops it.
Example
test {
let arr : ReadOnlyArray[Int] = [1, 2, 3, 4, 5]
let out = arr.filter_map(x => if x % 2 == 0 { Some(x * 10) } else { None })
debug_inspect(
out,
content=(
#|<ReadOnlyArray: [20, 40]>
),
)
}ReadOnlyArray::fold
fn[A, B] ReadOnlyArray::fold(self : ReadOnlyArray[A], init~ : B, f : (B, A) -> B raise?) -> B raise?Folds the ReadOnlyArray from left to right.
Example
test {
let arr : ReadOnlyArray[Int] = [1, 2, 3, 4, 5]
let sum = arr.fold(init=0, fn(acc, x) { acc + x })
inspect(sum, content="15")
}ReadOnlyArray::foldi
fn[A, B] ReadOnlyArray::foldi(self : ReadOnlyArray[A], init~ : B, f : (Int, B, A) -> B raise?) -> B raise?Folds the ReadOnlyArray from left to right with index.
Example
test {
let arr : ReadOnlyArray[Int] = [2, 3]
let sum = arr.foldi(init=0, fn(i, acc, x) { acc + i * x })
inspect(sum, content="3") // 0 + (0*2) + (1*3) = 3
}ReadOnlyArray::from_array
Creates an ReadOnlyArray from a dynamic Array.
Example
test {
let dynamic_array : Array[Int] = [1, 2, 3, 4, 5]
let immut_array = ReadOnlyArray::from_array(dynamic_array)
inspect(immut_array[0], content="1")
}ReadOnlyArray::from_iter
#alias(from_iterator, deprecated="`from_iterator` is deprecated, use `from_iter` instead")
fn[T] ReadOnlyArray::from_iter(iter : Iter[T]) -> ReadOnlyArray[T]Creates an ReadOnlyArray from an iterator.
Example
test {
let iter = 1, 2, 3
let immut_array = ReadOnlyArray::from_iter(iter)
inspect(immut_array[0], content="1")
}ReadOnlyArray::get
fn[T] ReadOnlyArray::get(self : ReadOnlyArray[T], index : Int) -> T?Safely retrieves an element at the specified index.
Returns Some(element) if the index is valid, None otherwise.
Example
test {
let arr : ReadOnlyArray[Int] = [1, 2, 3]
debug_inspect(arr.get(1), content="Some(2)")
debug_inspect(arr.get(5), content="None")
}ReadOnlyArray::get_view
Creates a view of a subarray, returning None when indices are invalid.
Example
test {
let arr : ReadOnlyArray[Int] = [1, 2, 3, 4, 5]
let start = 1
let end = 4
debug_inspect(
arr.get_view(start~, end~),
content=(
#|Some(<ArrayView: [2, 3, 4]>)
),
)
let start = 4
let end = 10
debug_inspect(arr.get_view(start~, end~), content="None")
}ReadOnlyArray::is_empty
fn[T] ReadOnlyArray::is_empty(self : ReadOnlyArray[T]) -> BoolChecks if the ReadOnlyArray is empty.
Example
test {
let empty_arr : ReadOnlyArray[Int] = []
inspect(empty_arr.is_empty(), content="true")
let arr : ReadOnlyArray[Int] = [1, 2, 3]
inspect(arr.is_empty(), content="false")
}ReadOnlyArray::is_sorted
Checks if the ReadOnlyArray is sorted in non-decreasing order.
Example
test {
let arr : ReadOnlyArray[Int] = [1, 2, 3]
inspect(arr.is_sorted(), content="true")
let arr2 : ReadOnlyArray[Int] = [2, 1]
inspect(arr2.is_sorted(), content="false")
}ReadOnlyArray::iter
#alias(iterator, deprecated="`iterator` is deprecated, use `iter` instead")
fn[T] ReadOnlyArray::iter(self : ReadOnlyArray[T]) -> Iter[T]Creates an iterator over the elements of the ReadOnlyArray.
Example
test {
let arr : ReadOnlyArray[Int] = [1, 2, 3]
let mut sum = 0
arr.iter().each(fn(x) { sum x })
inspect(sum, content="6")
}ReadOnlyArray::iter2
Creates an iterator that yields both indices and values.
Example
test {
let arr : ReadOnlyArray[Int] = [10, 20, 30]
let mut sum = 0
arr.iter2().each(fn(i, x) { sum i + x })
inspect(sum, content="63") // (0+10) + (1+20) + (2+30) = 63
}ReadOnlyArray::join
Joins the string-renderable elements with a separator.
Example
test {
let arr : ReadOnlyArray[String] = ["hello", "world", "moon"]
inspect(arr.join(","), content="hello,world,moon")
inspect(arr.join(" "), content="hello world moon")
}ReadOnlyArray::last
fn[T] ReadOnlyArray::last(self : ReadOnlyArray[T]) -> T?Returns the last element of the ReadOnlyArray, if any.
Example
test {
let arr : ReadOnlyArray[Int] = [1, 2, 3]
debug_inspect(arr.last(), content="Some(3)")
let empty_arr : ReadOnlyArray[Int] = []
debug_inspect(empty_arr.last(), content="None")
}ReadOnlyArray::length
fn[T] ReadOnlyArray::length(self : ReadOnlyArray[T]) -> IntReturns the length of the ReadOnlyArray.
Example
test {
let arr : ReadOnlyArray[Int] = [1, 2, 3]
inspect(arr.length(), content="3")
}ReadOnlyArray::lexical_compare
Performs a lexicographical comparison of two arrays.
Unlike the Compare trait implementation (shortlex — shorter arrays come
first), this method compares purely by element values; length only breaks
ties when one array is a prefix of the other.
Example
test {
let a : ReadOnlyArray[Int] = [1, 2]
let b : ReadOnlyArray[Int] = [1, 2, 3]
inspect(a.lexical_compare(b), content="-1")
inspect(b.lexical_compare(a), content="1")
inspect(b.lexical_compare(b), content="0")
let c : ReadOnlyArray[Int] = [1, 2, 4]
inspect(b.lexical_compare(c), content="-1")
}ReadOnlyArray::makei
fn[T] ReadOnlyArray::makei(length : Int, value : (Int) -> T raise?) -> ReadOnlyArray[T] raise?Creates an ReadOnlyArray by applying a function to each index.
Example
test {
let immut_array = ReadOnlyArray::makei(3, fn(i) { i * 2 })
inspect(immut_array[1], content="2")
}ReadOnlyArray::map
fn[T, U] ReadOnlyArray::map(self : ReadOnlyArray[T], f : (T) -> U raise?) -> ReadOnlyArray[U] raise?Creates a new ReadOnlyArray by applying a function to each element.
Example
test {
let arr : ReadOnlyArray[Int] = [1, 2, 3]
let doubled = arr.map(fn(x) { x * 2 })
inspect(doubled[0], content="2")
inspect(doubled[2], content="6")
}ReadOnlyArray::mapi
fn[T, U] ReadOnlyArray::mapi(self : ReadOnlyArray[T], f : (Int, T) -> U raise?) -> ReadOnlyArray[U] raise?Creates a new ReadOnlyArray by applying a function to each element with its index.
Example
test {
let arr : ReadOnlyArray[Int] = [10, 20, 30]
let result = arr.mapi(fn(i, x) { i + x })
inspect(result[1], content="21") // index 1 + value 20 = 21
}ReadOnlyArray::rev
fn[T] ReadOnlyArray::rev(self : ReadOnlyArray[T]) -> ReadOnlyArray[T]Returns a new ReadOnlyArray with elements in reverse order.
Example
test {
let arr : ReadOnlyArray[Int] = [1, 2, 3, 4, 5]
let reversed = arr.rev()
inspect(reversed[0], content="5")
inspect(reversed[4], content="1")
}ReadOnlyArray::rev_each
fn[T] ReadOnlyArray::rev_each(self : ReadOnlyArray[T], f : (T) -> Unit raise?) -> Unit raise?Iterates over each element in reverse order.
Example
test {
let arr : ReadOnlyArray[Int] = [1, 2, 3]
let result = []
arr.rev_each(fn(x) { result.push(x) })
debug_inspect(result, content="[3, 2, 1]")
}ReadOnlyArray::rev_eachi
fn[T] ReadOnlyArray::rev_eachi(self : ReadOnlyArray[T], f : (Int, T) -> Unit raise?) -> Unit raise?Iterates over each element in reverse order with its index.
Example
test {
let arr : ReadOnlyArray[Int] = [10, 20, 30]
let result = []
arr.rev_eachi(fn(i, x) { result.push((i, x)) })
debug_inspect(result, content="[(0, 30), (1, 20), (2, 10)]")
}ReadOnlyArray::rev_fold
fn[A, B] ReadOnlyArray::rev_fold(self : ReadOnlyArray[A], init~ : B, f : (B, A) -> B raise?) -> B raise?Folds the ReadOnlyArray from right to left.
Example
test {
let arr : ReadOnlyArray[Int] = [1, 2, 3]
let result = arr.rev_fold(init="", fn(acc, x) { acc + x.to_string() })
inspect(result, content="321") // Processed in reverse order
}ReadOnlyArray::rev_foldi
fn[A, B] ReadOnlyArray::rev_foldi(self : ReadOnlyArray[A], init~ : B, f : (Int, B, A) -> B raise?) -> B raise?Folds the ReadOnlyArray from right to left with index.
Example
test {
let arr : ReadOnlyArray[Int] = [2, 3]
let sum = arr.rev_foldi(init=0, fn(i, acc, x) { acc + i * x })
inspect(sum, content="2") // 0 + (0*3) + (1*2) = 2
}ReadOnlyArray::rev_iter
Returns an iterator that yields each element from the last to the first.
Example
test {
let arr : ReadOnlyArray[Int] = [1, 2, 3]
let result = []
arr.rev_iter().each(x => result.push(x))
debug_inspect(result, content="[3, 2, 1]")
}ReadOnlyArray::search
Searches for an element and returns its index if found.
Example
test {
let arr : ReadOnlyArray[Int] = [1, 2, 3, 2, 4]
debug_inspect(arr.search(2), content="Some(1)") // Returns first occurrence
debug_inspect(arr.search(5), content="None")
}ReadOnlyArray::search_by
fn[T] ReadOnlyArray::search_by(self : ReadOnlyArray[T], f : (T) -> Bool raise?) -> Int? raise?Returns the index of the first element satisfying f, or None.
Example
test {
let arr : ReadOnlyArray[Int] = [1, 2, 3, 4, 5]
debug_inspect(arr.search_by(x => x > 3), content="Some(3)")
debug_inspect(arr.search_by(x => x > 99), content="None")
}ReadOnlyArray::starts_with
Checks if the ReadOnlyArray starts with the given prefix.
Example
test {
let arr : ReadOnlyArray[Int] = [1, 2, 3, 4, 5]
inspect(arr.starts_with([1, 2]), content="true")
}ReadOnlyArray::strip_prefix
If the array starts with prefix, returns a view of the remainder.
Otherwise returns None. The returned view shares the backing storage —
no allocation.
Example
test {
let arr : ReadOnlyArray[Int] = [1, 2, 3, 4, 5]
debug_inspect(
arr.strip_prefix([1, 2]),
content=(
#|Some(<ArrayView: [3, 4, 5]>)
),
)
debug_inspect(arr.strip_prefix([2, 3]), content="None")
}ReadOnlyArray::strip_suffix
If the array ends with suffix, returns a view of the leading portion.
Otherwise returns None. The returned view shares the backing storage —
no allocation.
Example
test {
let arr : ReadOnlyArray[Int] = [1, 2, 3, 4, 5]
debug_inspect(
arr.strip_suffix([4, 5]),
content=(
#|Some(<ArrayView: [1, 2, 3]>)
),
)
debug_inspect(arr.strip_suffix([3, 4]), content="None")
}ReadOnlyArray::suffixes
Yields all suffix views from the longest down to length 1 (and the empty
view if include_empty=true). Each suffix shares the original backing
storage.
Example
test {
let arr : ReadOnlyArray[Int] = [1, 2]
debug_inspect(
arr.suffixes().collect(),
content=(
#|[<ArrayView: [1, 2]>, <ArrayView: [2]>]
),
)
debug_inspect(
arr.suffixes(include_empty=true).collect(),
content=(
#|[<ArrayView: [1, 2]>, <ArrayView: [2]>, <ArrayView: []>]
),
)
}ReadOnlyArray::view
#alias(sub, deprecated="Use _[_:_] instead")
#alias("_[_:_]")
fn[T] ReadOnlyArray::view(self : ReadOnlyArray[T], start? : Int, end? : Int) -> ArrayView[T]Creates a view of a subarray.
Example
test {
let arr : ReadOnlyArray[Int] = [1, 2, 3, 4, 5]
let view = arr[1:4]
inspect(view[0], content="2")
inspect(view[2], content="4")
}ReadOnlyArray::windows
Returns all contiguous sub-views of length size, from left to right. The
result has length - size + 1 entries when size <= length, and is empty
otherwise. Each sub-view shares the original backing storage.
Panics if size <= 0.
Example
test {
let arr : ReadOnlyArray[Int] = [1, 2, 3, 4]
debug_inspect(
arr.windows(2),
content=(
#|[<ArrayView: [1, 2]>, <ArrayView: [2, 3]>, <ArrayView: [3, 4]>]
),
)
}Result
Result::bind
fn[T, E, U] Result::bind(self : Result[T, E], g : (T) -> Result[U, E]) -> Result[U, E]Binds a result to a function that returns another result.
Example
test {
let x : Result[Int, String] = Ok(6)
let y = x.bind((v : Int) => Ok(v * 7))
@test.assert_eq(y, Ok(42))
}Result::compare
Result::equal
Result::flatten
fn[T, E] Result::flatten(self : Result[Result[T, E], E]) -> Result[T, E]Flatten a Result of Result into a single Result.
If the outer Result is an Ok, the inner Result is returned. If the outer Result is an Err, the inner Result is ignored and the Err is returned.
Example
test {
let x : Result[Result[Int, String], String] = Ok(Ok(6))
let y = x.flatten()
@test.assert_eq(y, Ok(6))
}Result::map
fn[T, E, U] Result::map(self : Result[T, E], f : (T) -> U) -> Result[U, E]Maps the value of a Result if it is Ok into another, otherwise returns the Err value unchanged.
Example
test {
let x : Result[Int, Unit] = Ok(6)
let y = x.map((v : Int) => v * 7)
@test.assert_eq(y, Ok(42))
}Result::map_err
fn[T, E, F] Result::map_err(self : Result[T, E], f : (E) -> F) -> Result[T, F]Maps the value of a Result if it is Err into another, otherwise returns the Ok value unchanged.
Example
test {
let x : Result[Int, String] = Err("error")
let y = x.map_err((v : String) => v + "!")
@test.assert_eq(y, Err("error!"))
}Result::to_option
fn[T, E] Result::to_option(self : Result[T, E]) -> T?Converts a Result to an Option.
Converts Ok to Some and Err to None.
Example
test {
let x : Result[Int, String] = Ok(6)
let y = x.to_option()
@test.assert_eq(y, Some(6))
}Result::unwrap
fn[T, E] Result::unwrap(self : Result[T, E]) -> TExtract the wrapped value with unwrap semantics.
Result::unwrap_err
fn[T, E] Result::unwrap_err(self : Result[T, E]) -> EExtracts the error value from a Result[T, E]. If the Result is Ok,
aborts with a runtime error message.
Parameters:
- self : The Result value to extract the error from.
Returns the error value of type E if self is Err(e).
Example:
test {
let err : Result[Int, String] = Err("error message")
inspect(err.unwrap_err(), content="error message")
}Result::unwrap_or
#alias(or)
fn[T, E] Result::unwrap_or(self : Result[T, E], default : T) -> TReturn the contained Ok value or the provided default.
Example
test {
let x : Result[Int, String] = Ok(3)
let y : Result[Int, String] = Err("error")
@test.assert_eq(x.unwrap_or(5), 3)
@test.assert_eq(y.unwrap_or(5), 5)
}Result::unwrap_or_default
Return the contained Ok value or the result of the T::default().
Result::unwrap_or_else
#alias(or_else)
fn[T, E] Result::unwrap_or_else(self : Result[T, E], default : () -> T raise?) -> T raise?Return the contained Ok value or the provided default.
Default is lazily evaluated.
Example
test {
let x : Result[Int, String] = Ok(3)
let y : Result[Int, String] = Err("error")
@test.assert_eq(x.unwrap_or_else(() => 5), 3)
@test.assert_eq(y.unwrap_or_else(() => 5), 5)
}Result::unwrap_or_error
fn[T, E : Error] Result::unwrap_or_error(self : Result[T, E]) -> T raise EExtract the wrapped value with unwrap_or_error semantics.
String
Note
String is a built-in type. The documentation may not be complete here. You can find all methods and implementations in the core/builtin and core/string package.
String::after
fn String::after(self : String, needle : StringView) -> StringView?Returns the substring after the first occurrence of the separator.
Returns None if the separator is not found.
If the separator is empty, it returns the full string.
String::all
#alias(every)
fn String::all(self : String, f : (Char) -> Bool raise?) -> Bool raise?Checks if all characters in the string match the condition.
Example
test {
assert_true("abc".all(c => c.is_ascii_lowercase()))
assert_false("abc1".all(c => c.is_ascii_lowercase()))
}String::any
#alias(exists)
fn String::any(self : String, f : (Char) -> Bool raise?) -> Bool raise?Checks if any character in the string matches the condition.
Example
test {
assert_true("abc1".any(c => c.is_ascii_digit()))
assert_false("abc".any(c => c.is_ascii_digit()))
}String::at
#alias(code_unit_at)
#alias("_[_]")
fn String::at(self : String, idx : Int) -> UInt16Returns the UTF-16 code unit at the given index.
This method has O(1) complexity.
Panics if the index is out of bounds.
String::before
fn String::before(self : String, needle : StringView) -> StringView?Returns the substring before the first occurrence of the separator.
Returns None if the separator is not found.
If the separator is empty, it returns an empty string.
String::char_length
#alias(codepoint_length, deprecated="`codepoint_length` is deprecated, use `char_length` instead")
fn String::char_length(self : String, start_offset? : Int, end_offset? : Int) -> IntReturns the number of Unicode code points (characters) in the string.
This method counts actual Unicode characters, properly handling surrogate pairs
that represent single characters like emojis. For the raw UTF-16 code unit count,
use length() instead.
Examples
test {
let s = "Hello🤣"
inspect(s.char_length(), content="6") // 6 actual characters
inspect(s.length(), content="7")
} // 5 ASCII chars + 1 surrogate pair (2 code units)String::char_length_eq
fn String::char_length_eq(self : String, len : Int, start_offset? : Int, end_offset? : Int) -> BoolTest if the length of the string is equal to the given length.
This has O(n) complexity where n is the length in the parameter.
String::char_length_ge
fn String::char_length_ge(self : String, len : Int, start_offset? : Int, end_offset? : Int) -> BoolTest if the length of the string is greater than or equal to the given length.
This has O(n) complexity where n is the length in the parameter.
String::clamped_view
fn String::clamped_view(self : String, start? : Int, end? : Int) -> StringViewReturns the largest well-formed view contained in the requested range.
Total: out-of-range offsets are clamped to the string, an offset that
would split a surrogate pair is snapped inward (start forward, end
backward), and an inverted range yields an empty view — this function
never aborts and never cuts a surrogate pair in half.
Intended for truncation where the exact cut point does not matter, such
as short summaries: the result is at most one character shorter than the
requested range on each side. Unpaired surrogates already present in the
input are treated as boundaries and pass through unchanged.
See s[start:end] for the aborting variant and String::get_view for
the exact Option-returning variant.
Example
test {
let s = "ab😀cd"
inspect(s.clamped_view(end=3), content="ab") // 3 splits 😀: snapped to 2
inspect(s.clamped_view(start=3), content="cd") // snapped to 4
inspect(s.clamped_view(end=100), content="ab😀cd") // clamped
inspect(s.clamped_view(start=3, end=3), content="") // inside the pair
}String::code_units
Returns an ArrayView containing the UTF-16 code units of the string.
This method yields code units, not Unicode characters. Surrogate pairs are
represented as two UInt16 values.
String::compare_ignore_ascii_case
fn String::compare_ignore_ascii_case(self : String, other : String) -> IntPerforms a lexicographical comparison of two strings, treating ASCII
letters as case-insensitive.
Each pair of UTF-16 code units is compared after folding ASCII 'A'..'Z'
onto 'a'..'z'. Non-ASCII code units are compared by their raw value, so
this function does not perform Unicode case folding (e.g. 'Ä' and
'ä' are still considered different). Use this when you only need to
match ASCII identifiers, headers, file extensions, or similar protocol
text — not for human-language text where locale-dependent folding matters.
Aside from case folding, the semantics match lexical_compare: characters
are compared one by one and, when one string is a prefix of the other, the
shorter string is considered less. The result is independent of which
string is self.
Returns
- A negative integer if self is less than other
- Zero if self is equal to other under ASCII case folding
- A positive integer if self is greater than other
Example
test {
inspect("Hello".compare_ignore_ascii_case("hello"), content="0")
inspect("ABC".compare_ignore_ascii_case("abd"), content="-1")
inspect("abc".compare_ignore_ascii_case("AB"), content="1")
// Non-ASCII letters are NOT folded
inspect("Ä".compare_ignore_ascii_case("ä") != 0, content="true")
}String::contains
fn String::contains(self : String, str : StringView) -> BoolReturns true if this string contains the given substring.
String::contains_any
fn String::contains_any(self : String, chars~ : StringView) -> BoolReturns true if this string contains any character from the given set.
String::contains_char
fn String::contains_char(self : String, c : Char) -> BoolReturns true if this string contains the given character.
String::contains_code_unit
fn String::contains_code_unit(self : String, code : UInt16) -> BoolReturns true if this string contains the given UTF-16 code unit.
This searches raw UTF-16 code units and does not combine surrogate pairs.
Use contains_char when searching for a Unicode character.
String::equal_ignore_ascii_case
fn String::equal_ignore_ascii_case(self : String, other : String) -> BoolTests two strings for equality, treating ASCII letters as case-insensitive.
ASCII 'A'..'Z' are folded onto 'a'..'z' before comparison; all other
code units (including non-ASCII letters like 'Ä') are compared by their
raw UTF-16 value. Use this for ASCII-only protocol text — HTTP headers,
file extensions, identifiers — not for human-language text where Unicode
case folding matters.
Equivalent to self.compare_ignore_ascii_case(other) == 0 but short-
circuits on length mismatch and on the first differing code unit, so it
is preferred when only equality is needed.
Example
test {
inspect("Hello".equal_ignore_ascii_case("hello"), content="true")
inspect("Hello".equal_ignore_ascii_case("world"), content="false")
inspect("abc".equal_ignore_ascii_case("ab"), content="false")
// Non-ASCII letters are NOT folded
inspect("Ä".equal_ignore_ascii_case("ä"), content="false")
}String::escape
fn String::escape(self : String, quote? : Bool) -> StringReturns the escaped representation of a string.
When quote is true (default), the result is wrapped in double quotes
like a MoonBit string literal.
Escape rules:
- Double quote and backslash are backslash-escaped: \", \\
- Common control characters use named escapes: \n, \r, \b, \t
- Other control characters (< U+0020) use \u{hex} format
- All other characters are displayed as-is
test {
inspect("Hello \n".escape(), content="\"Hello \\n\"")
inspect("Hello \n".escape(quote=false), content="Hello \\n")
}String::find
fn String::find(self : String, str : StringView) -> Int?Returns the offset of the first occurrence of the given substring. If the
substring is not found, it returns None.
String::find_by
fn String::find_by(self : String, pred : (Char) -> Bool) -> Int?Returns the UTF-16 code-unit offset, relative to the beginning of this
string, of the first character that satisfies the given predicate. If no
such character is found, it returns None.
String::fold
fn[A] String::fold(self : String, init~ : A, f : (A, Char) -> A raise?) -> A raise?Folds the characters of the string into a single value.
String::from_array
Convert char array to string.
test {
let s = String::from_array(['H', 'e', 'l', 'l', 'o'])
@test.assert_eq(s, "Hello")
}Do not convert large data to Array[Char] and build a string with String::from_array.
For efficiency considerations, it's recommended to use Buffer instead.
String::from_iter
#alias(from_iterator, deprecated="`from_iterator` is deprecated, use `from_iter` instead")
fn String::from_iter(iter : Iter[Char]) -> StringConvert char iterator to string,
String::get
fn String::get(self : String, idx : Int) -> UInt16?Returns the UTF-16 code unit at the given index. Returns None if the index
is out of bounds.
String::get_char
fn String::get_char(self : String, idx : Int) -> Char?Returns the character at the given index. Returns None if the index is out
of bounds or the index splits a surrogate pair.
String::get_view
fn String::get_view(self : String, start? : Int, end? : Int) -> StringView?Returns a view of the string between start and end, or None if the
range is invalid — either out of bounds or splitting a UTF-16 surrogate
pair. Unlike String::sub (a.k.a. s[start:end]), this variant does not
abort, making it suitable for composition with pattern matching:
test {
let s = "Hello🤣World"
debug_inspect(
s.get_view(end=5).map(v => v.to_owned()),
content="Some(\"Hello\")",
)
// Splitting a surrogate pair is rejected rather than panicking.
debug_inspect(s.get_view(end=6), content="None")
debug_inspect(s.get_view(start=100), content="None")
}String::has_prefix
#alias(starts_with, deprecated="`starts_with` is deprecated, use `has_prefix` instead")
fn String::has_prefix(self : String, str : StringView) -> BoolReturns true if this string starts with the given substring.
String::has_suffix
#alias(ends_with, deprecated="`ends_with` is deprecated, use `has_suffix` instead")
fn String::has_suffix(self : String, str : StringView) -> BoolReturns true if the given substring is suffix of this string.
String::is_blank
fn String::is_blank(self : String) -> BoolReturns true if this string is blank.
String::is_empty
fn String::is_empty(self : String) -> BoolReturns true if this string is empty.
String::iter
#alias(iterator, deprecated="`iterator` is deprecated, use `iter` instead")
fn String::iter(self : String) -> Iter[Char]Returns an iterator over the Unicode characters in the string.
Note: This iterator yields Unicode characters, not Utf16 code units.
As a result, the count of characters returned by iter().count() may not be equal to the length of the string returned by length().
test {
let s = "Hello, World!🤣"
@test.assert_eq(s.iter().count(), 14) // Unicode characters
@test.assert_eq(s.length(), 15)
} // Utf16 code unitsString::iter2
#alias(iterator2, deprecated="`iterator2` is deprecated, use `iter2` instead")
fn String::iter2(self : String) -> Iter2[Int, Char]Return an iterator via iter2.
String::length
#alias(charcode_length, deprecated="`charcode_length` is deprecated, use `length` instead")
fn String::length(self : String) -> IntReturns the number of UTF-16 code units in the string. Note that this is not
necessarily equal to the number of Unicode characters (code points) in the
string, as some characters may be represented by multiple UTF-16 code units.
Parameters:
- string : The string whose length is to be determined.
Returns the number of UTF-16 code units in the string.
Example:
test {
inspect("hello".length(), content="5")
inspect("🤣".length(), content="2") // Emoji uses two UTF-16 code units
inspect("".length(), content="0") // Empty string
}String::lexical_compare
fn String::lexical_compare(self : String, other : String) -> IntPerforms a lexicographical comparison of two strings.
This method compares the strings character by character (UTF-16 code unit by code unit),
similar to Java's String.compareTo(). Unlike the Compare trait implementation which
uses shortlex order (shorter strings come first), this method compares based purely on
character values until a difference is found or one string is exhausted.
Returns
- A negative integer if self is lexicographically less than other
- Zero if self is lexicographically equal to other
- A positive integer if self is lexicographically greater than other
Example
test {
inspect("ab".lexical_compare("abc"), content="-1")
inspect("abc".lexical_compare("ab"), content="1")
inspect("abc".lexical_compare("abc"), content="0")
inspect("abc".lexical_compare("abd"), content="-1")
}Note
Since MoonBit strings are UTF-16 encoded (like Java), this comparison operates on
UTF-16 code units, not Unicode code points. Surrogate pairs (used for characters
outside the Basic Multilingual Plane) are compared as individual code units.
String::make
fn String::make(length : Int, value : Char) -> StringCreate new string of length, where each character is value
test {
@test.assert_eq(String::make(5, 'S'), "SSSSS")
}String::offset_of_nth_char
fn String::offset_of_nth_char(self : String, i : Int, start_offset? : Int, end_offset? : Int) -> Int?Returns the UTF-16 index of the i-th (zero-indexed) Unicode character
within the range [start, end). If i is negative, it returns the index of
the (n + i)-th character where n is the number of Unicode characters
in the range [start, end).
This functions assumes that the string is valid UTF-16.
String::pad_end
fn String::pad_end(self : String, total_width : Int, padding_char : Char) -> StringReturns a new string with padding_chars appended to self if
self.length() < total_width. The threshold and the pad count are
measured in UTF-16 code units: total_width - self.length() copies of
padding_char are appended. Characters outside the BMP count as two
code units, so with such characters in self the result has fewer than
total_width characters, and with a non-BMP padding_char the result's
UTF-16 length exceeds total_width.
String::pad_start
fn String::pad_start(self : String, total_width : Int, padding_char : Char) -> StringReturns a new string with padding_chars prefixed to self if
self.length() < total_width. The threshold and the pad count are
measured in UTF-16 code units: total_width - self.length() copies of
padding_char are prefixed. Characters outside the BMP count as two
code units, so with such characters in self the result has fewer than
total_width characters, and with a non-BMP padding_char the result's
UTF-16 length exceeds total_width.
String::repeat
fn String::repeat(self : String, n : Int) -> StringReturns a new string with self repeated n times.
Aborts if n is negative. When n is 0, returns the empty string.
String::replace
fn String::replace(self : String, old~ : StringView, new~ : StringView) -> StringReplaces the first occurrence of old with new in self.
If old is empty, it matches the beginning of the string, and new is
prepended to the string.
String::replace_all
fn String::replace_all(self : String, old~ : StringView, new~ : StringView) -> StringReplaces all non-overlapping occurrences of old with new in self.
If old is empty, it matches at the beginning of the string and after each
character in the string, so new is inserted at the beginning of the string
and after each character.
String::rev
fn String::rev(self : String) -> StringReturns a new string with the characters in reverse order. It respects
Unicode characters and surrogate pairs but not grapheme clusters.
String::rev_after
fn String::rev_after(self : String, needle : StringView) -> StringView?Returns the substring after the last occurrence of the separator.
Returns None if the separator is not found.
Example:
test {
assert_true("a/b/c.txt".rev_after("/") == Some("c.txt"))
}String::rev_before
fn String::rev_before(self : String, needle : StringView) -> StringView?Returns the substring before the last occurrence of the separator.
Returns None if the separator is not found.
Example:
test {
assert_true("a/b/c.txt".rev_before("/") == Some("a/b"))
}String::rev_find
fn String::rev_find(self : String, str : StringView) -> Int?Returns the offset (charcode index) of the last occurrence of the given
substring. If the substring is not found, it returns None.
String::rev_fold
fn[A] String::rev_fold(self : String, init~ : A, f : (A, Char) -> A raise?) -> A raise?Function rev_fold.
String::rev_iter
#alias(rev_iterator, deprecated="`rev_iterator` is deprecated, use `rev_iter` instead")
fn String::rev_iter(self : String) -> Iter[Char]Returns an iterator that yields characters from the end to the start of the string. This function handles
Unicode surrogate pairs correctly, ensuring that characters are not split across surrogate pairs.
Parameters
- self : The input String to be iterated in reverse.
Returns
- An Iter[Char] that yields characters from the end to the start of the string.
Behavior
- The function iterates over the string in reverse order.
- If a trailing surrogate is encountered, it checks for a preceding leading surrogate to form a complete Unicode code point.
- Yields each character or combined code point to the iterator.
- Stops once the beginning of the string is reached, after which the iterator yields None.
Examples
test {
let input = "Hello, World!"
let reversed = input.rev_iter().collect()
@test.assert_eq(reversed, [
'!', 'd', 'l', 'r', 'o', 'W', ' ', ',', 'o', 'l', 'l', 'e', 'H',
])
}String::rev_split_once
fn String::rev_split_once(self : String, needle : StringView) -> (StringView, StringView)?Splits the string into a pair at the last occurrence of the separator.
Returns None if the separator is not found.
Example:
test {
assert_true("a::b::c".rev_split_once("::") == Some(("a::b", "c")))
}String::split
Splits the string into all substrings separated by the given separator.
If the string does not contain the separator and the separator is not empty,
the returned iterator will contain only one element, which is the original
string.
If the separator is empty, the returned iterator will contain all the
characters in the string as single elements.
String::split_at
fn String::split_at(self : String, at : Int) -> (StringView, StringView)Splits the string into a well-formed (prefix, suffix) pair at the given
code-unit offset: the cut point is at clamped to the string and snapped
down to the nearest character boundary, so the prefix never exceeds at
units and a character straddling the cut goes to the suffix.
Total, O(1), and lossless: prefix + suffix == self always holds —
unlike composing two clamped_view calls, which would drop a character
straddling the cut from both halves. Unpaired surrogates are treated as
boundaries and pass through unchanged.
Example
test {
let s = "ab😀cd"
let (p, q) = s.split_at(3) // 3 splits 😀: the cut snaps down to 2
inspect(p, content="ab")
inspect(q, content="😀cd")
let (p2, q2) = s.split_at(100) // clamped
inspect(p2, content="ab😀cd")
inspect(q2, content="")
}String::split_once
fn String::split_once(self : String, needle : StringView) -> (StringView, StringView)?Splits the string into a pair at the first occurrence of the separator.
Returns None if the separator is not found.
If the separator is empty, it splits at the start of the string, returning
an empty prefix and the full string as the suffix.
String::strip_prefix
#alias(chop_prefix)
fn String::strip_prefix(self : String, prefix : StringView) -> StringView?Removes the given prefix from the string if it exists.
Returns Some(suffix) if the string starts with the given prefix,
where suffix is the string without the prefix.
Returns None if the string does not start with the prefix.
Example
test {
assert_true("hello world".strip_prefix("hello ") == Some("world"))
assert_true("hello world".strip_prefix("hi ") == None)
assert_true("hello".strip_prefix("hello") == Some(""))
}String::strip_suffix
#alias(chop_suffix)
fn String::strip_suffix(self : String, suffix : StringView) -> StringView?Removes the given suffix from the string if it exists.
Returns Some(prefix) if the string ends with the given suffix,
where prefix is the string without the suffix.
Returns None if the string does not end with the suffix.
Example
test {
assert_true("hello world".strip_suffix(" world") == Some("hello"))
assert_true("hello world".strip_suffix(" moon") == None)
assert_true("hello".strip_suffix("hello") == Some(""))
}String::sub
#alias("_[_:_]")
fn String::sub(self : String, start? : Int, end? : Int) -> StringViewCreates a view of a string with proper UTF-16 boundary validation.
Parameters
- start : Starting UTF-16 code unit index (default: 0), counting from the beginning of the string
- end : Ending UTF-16 code unit index (optional)
- If None: extends to the end of the string
- Otherwise: counts from the beginning of the string
Returns
- A View representing the specified substring range
Panics
- If start or end indices are out of valid range
- If start or end position would split a UTF-16 surrogate pair
This prevents creating views that would split surrogate pairs, which would
result in invalid Unicode characters.
Performance
This function has O(1) complexity as it only performs boundary checks
without scanning the string content.
Examples
test {
let str = "Hello🤣World"
let view1 = str[0:5]
inspect(view1, content="Hello")
let view2 = str[7:]
inspect(view2, content="World")
}String::substring
#deprecated("Use `str[:]` or `str[:].to_string()` instead")
fn String::substring(self : String, start? : Int, end? : Int) -> StringReturns a new string containing characters from the original string starting
at start index up to (but not including) end index.
Parameters:
- string : The source string from which to extract the substring.
- start : The starting index of the substring (inclusive). Defaults to 0.
- end : The ending index of the substring (exclusive). Defaults to the length of the string.
Returns a new string containing the specified substring.
String::suffixes
Iterates over all suffixes of the string as views that reuse the
original storage. Surrogate pairs stay intact while advancing.
String::to_array
Converts the String into an array of Chars.
String::to_bytes
#deprecated("Check `@encoding/utf8.encode`")
fn String::to_bytes(self : String) -> BytesString holds a sequence of UTF-16 code units encoded in little endian format
String::to_lower
fn String::to_lower(self : String) -> StringConverts the ASCII uppercase letters ('A' to 'Z') in this string to
lowercase. All other characters, including non-ASCII letters, are left
unchanged.
String::to_upper
fn String::to_upper(self : String) -> StringConverts the ASCII lowercase letters ('a' to 'z') in this string to
uppercase. All other characters, including non-ASCII letters, are left
unchanged.
String::trim
fn String::trim(self : String, chars? : StringView) -> StringViewReturns the view of the string without the leading and trailing characters
that are in the given string.
String::trim_end
fn String::trim_end(self : String, chars? : StringView) -> StringViewReturns the view of the string without the trailing characters that are in
the given string.
String::trim_space
#deprecated("Use `trim` with default whitespace characters instead")
fn String::trim_space(self : String) -> StringViewReturns the view of the string without the leading and trailing spaces.
String::trim_start
fn String::trim_start(self : String, chars? : StringView) -> StringViewReturns the view of the string without the leading characters that are in
the given string.
String::unsafe_char_at
#deprecated("Use `s.get_char(i).unwrap()` instead")
fn String::unsafe_char_at(self : String, index : Int) -> CharReturns the Unicode code point at the given index without bounds checking.
String::unsafe_substring
fn String::unsafe_substring(str : String, start~ : Int, end~ : Int) -> StringUnsafe variant of substring.
String::view
fn String::view(self : String, start_offset? : Int, end_offset? : Int) -> StringViewCreates a View into a String.
Example
test {
let str = "Hello🤣🤣🤣"
let view1 = str.view()
inspect(view1, content="Hello🤣🤣🤣")
let start_offset = str.offset_of_nth_char(1).unwrap()
let end_offset = str.offset_of_nth_char(6).unwrap() // the second emoji
let view2 = str.view(start_offset~, end_offset~)
inspect(view2, content="ello🤣")
}StringView
StringView::after
fn StringView::after(self : StringView, needle : StringView) -> StringView?Returns the substring after the first occurrence of the separator.
Returns None if the separator is not found.
If the separator is empty, it returns the full string.
StringView::all
#alias(every)
fn StringView::all(self : StringView, f : (Char) -> Bool raise?) -> Bool raise?Checks if all characters in the string view match the condition.
Example
test {
let view = "zabc!"[1:4]
assert_true(view.all(c => c.is_ascii_lowercase()))
assert_false(view.all(c => c == 'a'))
}StringView::any
#alias(exists)
fn StringView::any(self : StringView, f : (Char) -> Bool raise?) -> Bool raise?Checks if any character in the string view matches the condition.
Example
test {
let view = "zabc!"[1:4]
assert_true(view.any(c => c == 'b'))
assert_false(view.any(c => c.is_ascii_digit()))
}StringView::at
#alias(code_unit_at)
#alias("_[_]")
fn StringView::at(self : StringView, index : Int) -> UInt16Returns the UTF-16 code unit at the given index.
This method has O(1) complexity.
Panics if the index is out of bounds.
StringView::before
fn StringView::before(self : StringView, needle : StringView) -> StringView?Returns the substring before the first occurrence of the separator.
Returns None if the separator is not found.
If the separator is empty, it returns an empty string.
StringView::char_length
fn StringView::char_length(self : StringView) -> IntReturns the number of Unicode characters in this view.
Note this has O(n) complexity where n is the length of the code points in
the view.
StringView::char_length_eq
fn StringView::char_length_eq(self : StringView, len : Int) -> BoolTest if the length of the view is equal to the given length.
This has O(n) complexity where n is the length in the parameter.
StringView::char_length_ge
fn StringView::char_length_ge(self : StringView, len : Int) -> BoolTest if the length of the view is greater than or equal to the given length.
This has O(n) complexity where n is the length in the parameter.
StringView::clamped_view
fn StringView::clamped_view(self : StringView, start? : Int, end? : Int) -> StringViewReturns the largest well-formed sub-view contained in the requested range
of this view; offsets are relative to the view. Total like
String::clamped_view: clamps out-of-range offsets, snaps
surrogate-splitting offsets inward, and yields an empty view for an
inverted range.
Example
test {
let v = "xx ab😀cd".view(start_offset=3)
inspect(v.clamped_view(end=3), content="ab")
inspect(v.clamped_view(start=3), content="cd")
}StringView::code_units
Returns an ArrayView containing the UTF-16 code units of the string view.
This method yields code units, not Unicode characters. Surrogate pairs are
represented as two UInt16 values.
Note: the default implementation copies the entire underlying string into a
fresh FixedArray and then slices it, so the returned view does not alias
the original string's storage. Some backends lower the intrinsic to a
zero-copy view instead.
StringView::compare_ignore_ascii_case
fn StringView::compare_ignore_ascii_case(self : StringView, other : StringView) -> IntPerforms a lexicographical comparison of two string views, treating ASCII
letters as case-insensitive.
Each pair of UTF-16 code units is compared after folding ASCII 'A'..'Z'
onto 'a'..'z'. Non-ASCII code units are compared by their raw value, so
this function does not perform Unicode case folding (e.g. 'Ä' and
'ä' are still considered different). Use this when you only need to
match ASCII identifiers, headers, file extensions, or similar protocol
text — not for human-language text where locale-dependent folding matters.
Aside from case folding, the semantics match lexical_compare: characters
are compared one by one (UTF-16 code unit by code unit) and, when one view
is a prefix of the other, the shorter view is considered less. The result
is independent of which view is self.
Returns
- A negative integer if self is less than other
- Zero if self is equal to other under ASCII case folding
- A positive integer if self is greater than other
Example
test {
inspect("Hello".view().compare_ignore_ascii_case("hello".view()), content="0")
inspect("ABC".view().compare_ignore_ascii_case("abd".view()), content="-1")
inspect("abc".view().compare_ignore_ascii_case("AB".view()), content="1")
}StringView::contains
fn StringView::contains(self : StringView, str : StringView) -> BoolReturns true if this string contains the given substring.
StringView::contains_any
fn StringView::contains_any(self : StringView, chars~ : StringView) -> BoolReturns true if this string contains any character from the given set.
StringView::contains_char
fn StringView::contains_char(self : StringView, c : Char) -> BoolReturns true if this string contains the given character.
StringView::contains_code_unit
fn StringView::contains_code_unit(self : StringView, code : UInt16) -> BoolReturns true if this string view contains the given UTF-16 code unit.
This searches raw UTF-16 code units and does not combine surrogate pairs.
Use contains_char when searching for a Unicode character.
StringView::data
fn StringView::data(self : StringView) -> StringReturns the original string that is being viewed.
StringView::equal_ignore_ascii_case
fn StringView::equal_ignore_ascii_case(self : StringView, other : StringView) -> BoolTests two string views for equality, treating ASCII letters as
case-insensitive.
ASCII 'A'..'Z' are folded onto 'a'..'z' before comparison; all other
code units (including non-ASCII letters like 'Ä') are compared by their
raw UTF-16 value. Use this for ASCII-only protocol text — HTTP headers,
file extensions, identifiers — not for human-language text where Unicode
case folding matters.
Equivalent to self.compare_ignore_ascii_case(other) == 0 but short-
circuits on length mismatch and on the first differing code unit, so it
is preferred when only equality is needed.
Example
test {
inspect(
"Hello".view().equal_ignore_ascii_case("hello".view()),
content="true",
)
inspect(
"Hello".view().equal_ignore_ascii_case("world".view()),
content="false",
)
inspect("abc".view().equal_ignore_ascii_case("ab".view()), content="false")
}StringView::equal_to_string
fn StringView::equal_to_string(self : StringView, other : String) -> BoolCompares a StringView to a String code-unit-for-code-unit.
This is the cross-type equivalent of == and avoids materializing a fresh
String (or a wrapping StringView) when probing an owned-String-keyed
container with a view-shaped key. When the view spans an entire backing
string that is physically the same as other, this short-circuits.
Returns true if the lengths match and every UTF-16 code unit in self
equals the code unit at the same index in other.
Example:
test {
let s = "say hello to everyone"
inspect(
s.view(start_offset=4, end_offset=9).equal_to_string("hello"),
content="true",
)
inspect(
s.view(start_offset=4, end_offset=9).equal_to_string("world"),
content="false",
)
}StringView::escape
fn StringView::escape(self : StringView, quote? : Bool) -> StringViewReturns the escaped representation of a string view.
When quote is true (default), the result is wrapped in double quotes
like a MoonBit string literal.
Escape rules:
- Double quote and backslash are backslash-escaped: \", \\
- Common control characters use named escapes: \n, \r, \b, \t
- Other control characters (< U+0020) use \u{hex} format
- All other characters are displayed as-is
test {
inspect("Hello\nWorld"[:6].escape(), content="\"Hello\\n\"")
inspect("Hello\nWorld"[:6].escape(quote=false), content="Hello\\n")
}StringView::find
fn StringView::find(self : StringView, str : StringView) -> Int?Returns the offset (charcode index) of the first occurrence of the given
substring. If the substring is not found, it returns None.
StringView::find_by
fn StringView::find_by(self : StringView, pred : (Char) -> Bool) -> Int?Returns the UTF-16 code-unit offset, relative to the beginning of this view,
of the first character that satisfies the given predicate. If no such
character is found, it returns None.
StringView::fold
fn[A] StringView::fold(self : StringView, init~ : A, f : (A, Char) -> A raise?) -> A raise?Folds the characters of the string into a single value.
StringView::from_array
Convert char array to string view.
StringView::from_iter
#alias(from_iterator, deprecated="`from_iterator` is deprecated, use `from_iter` instead")
fn StringView::from_iter(iter : Iter[Char]) -> StringViewConvert char iterator to string view.
StringView::get
fn StringView::get(self : StringView, idx : Int) -> UInt16?Returns the UTF-16 code unit at the given index. Returns None if the index
is out of bounds.
StringView::get_char
fn StringView::get_char(self : StringView, idx : Int) -> Char?Returns the character at the given index. Returns None if the index is out
of bounds or the index splits a surrogate pair.
StringView::get_view
fn StringView::get_view(self : StringView, start? : Int, end? : Int) -> StringView?Returns a sub-view of the view between start and end, or None if the
range is invalid — either out of bounds or splitting a UTF-16 surrogate
pair. The optional variant of StringView::sub (a.k.a. sv[start:end]).
StringView::has_prefix
#alias(starts_with, deprecated="`starts_with` is deprecated, use `has_prefix` instead")
fn StringView::has_prefix(self : StringView, str : StringView) -> BoolReturns true if this string starts with the given substring.
StringView::has_suffix
#alias(ends_with, deprecated="`ends_with` is deprecated, use `has_suffix` instead")
fn StringView::has_suffix(self : StringView, str : StringView) -> BoolReturns true if the given substring is suffix of this string.
StringView::is_blank
fn StringView::is_blank(self : StringView) -> BoolReturns true if this string is blank.
StringView::is_empty
fn StringView::is_empty(self : StringView) -> BoolReturns true if this string is empty.
StringView::iter
#alias(iterator, deprecated="`iterator` is deprecated, use `iter` instead")
fn StringView::iter(self : StringView) -> Iter[Char]Returns an iterator over the Unicode characters in the string view.
StringView::iter2
#alias(iterator2, deprecated="`iterator2` is deprecated, use `iter2` instead")
fn StringView::iter2(self : StringView) -> Iter2[Int, Char]Returns an iterator over the Unicode characters in the string view,
yielding pairs of (character index, character).
StringView::length
fn StringView::length(self : StringView) -> IntReturns the length of the view.
This method counts the charcodes(code unit) in the view and has O(1) complexity.
StringView::lexical_compare
fn StringView::lexical_compare(self : StringView, other : StringView) -> IntPerforms a lexicographical comparison of two string views.
This method compares the views character by character (UTF-16 code unit by code unit),
similar to Java's String.compareTo(). Unlike the Compare trait implementation which
uses shortlex order (shorter strings come first), this method compares based purely on
character values until a difference is found or one view is exhausted.
Returns
- A negative integer if self is lexicographically less than other
- Zero if self is lexicographically equal to other
- A positive integer if self is lexicographically greater than other
Example
test {
let str = "abc"
inspect(
str
.view(start_offset=0, end_offset=2)
.lexical_compare(str.view(start_offset=0, end_offset=3)),
content="-1",
)
inspect(
str
.view(start_offset=0, end_offset=3)
.lexical_compare(str.view(start_offset=0, end_offset=2)),
content="1",
)
inspect(
str
.view(start_offset=0, end_offset=2)
.lexical_compare(str.view(start_offset=1, end_offset=3)),
content="-1",
)
}Note
Since MoonBit strings are UTF-16 encoded (like Java), this comparison operates on
UTF-16 code units, not Unicode code points. Surrogate pairs (used for characters
outside the Basic Multilingual Plane) are compared as individual code units.
StringView::make
fn StringView::make(length : Int, value : Char) -> StringViewCreate a new string by repeating the given character value length times.
StringView::offset_of_nth_char
fn StringView::offset_of_nth_char(self : StringView, i : Int) -> Int?Returns the UTF-16 index of the i-th (zero-indexed) Unicode character of
the view. If i is negative, it returns the index of the (n + i)-th character
where n is the total number of Unicode characters in the view.
StringView::pad_end
fn StringView::pad_end(self : StringView, total_width : Int, padding_char : Char) -> StringReturns a new string with padding_chars appended to self if
self.length() < total_width. The threshold and the pad count are
measured in UTF-16 code units: total_width - self.length() copies of
padding_char are appended. Characters outside the BMP count as two
code units, so with such characters in self the result has fewer than
total_width characters, and with a non-BMP padding_char the result's
UTF-16 length exceeds total_width.
StringView::pad_start
fn StringView::pad_start(self : StringView, total_width : Int, padding_char : Char) -> StringReturns a new string with padding_chars prefixed to self if
self.length() < total_width. The threshold and the pad count are
measured in UTF-16 code units: total_width - self.length() copies of
padding_char are prefixed. Characters outside the BMP count as two
code units, so with such characters in self the result has fewer than
total_width characters, and with a non-BMP padding_char the result's
UTF-16 length exceeds total_width.
StringView::repeat
fn StringView::repeat(self : StringView, n : Int) -> StringViewReturns a new string with self repeated n times.
Aborts if n is negative. When n is 0, returns the empty string.
StringView::replace
fn StringView::replace(self : StringView, old~ : StringView, new~ : StringView) -> StringViewReplaces the first occurrence of old with new in self.
If old is empty, it matches the beginning of the string, and new is
prepended to the string.
StringView::replace_all
fn StringView::replace_all(self : StringView, old~ : StringView, new~ : StringView) -> StringViewReplaces all non-overlapping occurrences of old with new in self.
If old is empty, it matches at the beginning of the string and after each
character in the string, so new is inserted at the beginning of the string
and after each character.
StringView::rev
fn StringView::rev(self : StringView) -> StringReturns a new string with the characters in reverse order. It respects
Unicode characters and surrogate pairs but not grapheme clusters.
StringView::rev_after
fn StringView::rev_after(self : StringView, needle : StringView) -> StringView?Returns the substring after the last occurrence of the separator.
Returns None if the separator is not found.
Example:
test {
assert_true("a/b/c.txt".rev_after("/") == Some("c.txt"))
}StringView::rev_before
fn StringView::rev_before(self : StringView, needle : StringView) -> StringView?Returns the substring before the last occurrence of the separator.
Returns None if the separator is not found.
Example:
test {
assert_true("a/b/c.txt".rev_before("/") == Some("a/b"))
}StringView::rev_find
fn StringView::rev_find(self : StringView, str : StringView) -> Int?Returns the offset of the last occurrence of the given substring. If the
substring is not found, it returns None.
StringView::rev_fold
fn[A] StringView::rev_fold(self : StringView, init~ : A, f : (A, Char) -> A raise?) -> A raise?Function rev_fold.
StringView::rev_iter
#alias(rev_iterator, deprecated="`rev_iterator` is deprecated, use `rev_iter` instead")
fn StringView::rev_iter(self : StringView) -> Iter[Char]Returns an iterator over the Unicode characters in the string view in reverse order.
StringView::rev_split_once
fn StringView::rev_split_once(self : StringView, needle : StringView) -> (StringView, StringView)?Splits the string into a pair at the last occurrence of the separator.
Returns None if the separator is not found.
Example:
test {
assert_true("a::b::c".rev_split_once("::") == Some(("a::b", "c")))
assert_true("nope".rev_split_once("::") == None)
}StringView::split
Splits the string into all substrings separated by the given separator.
If the string does not contain the separator and the separator is not empty,
the returned iterator will contain only one element, which is the original
string.
If the separator is empty, the returned iterator will contain all the
characters in the string as single elements.
StringView::split_at
fn StringView::split_at(self : StringView, at : Int) -> (StringView, StringView)Splits the view into a well-formed (prefix, suffix) pair at the given
view-relative code-unit offset; same contract as String::split_at.
Example
test {
let v = "xx ab😀cd".view(start_offset=3)
let (p, q) = v.split_at(3)
inspect(p, content="ab")
inspect(q, content="😀cd")
}StringView::split_once
fn StringView::split_once(self : StringView, needle : StringView) -> (StringView, StringView)?Splits the string into a pair at the first occurrence of the separator.
Returns None if the separator is not found.
If the separator is empty, it splits at the start of the string, returning
an empty prefix and the full string as the suffix.
StringView::start_offset
fn StringView::start_offset(self : StringView) -> IntReturns the starting offset (in UTF-16 code units) of this view into its
underlying string.
StringView::strip_prefix
#alias(chop_prefix)
fn StringView::strip_prefix(self : StringView, prefix : StringView) -> StringView?Removes the given prefix from the view if it exists.
Returns Some(suffix) if the view starts with the given prefix,
where suffix is the view without the prefix.
Returns None if the view does not start with the prefix.
Example
test {
let view = "hello world"[:]
assert_true(view.strip_prefix("hello ") == Some("world"))
assert_true(view.strip_prefix("hi ") == None)
assert_true(view.strip_prefix("hello world") == Some(""))
}StringView::strip_suffix
#alias(chop_suffix)
fn StringView::strip_suffix(self : StringView, suffix : StringView) -> StringView?Removes the given suffix from the view if it exists.
Returns Some(prefix) if the view ends with the given suffix,
where prefix is the view without the suffix.
Returns None if the view does not end with the suffix.
Example
test {
let view = "hello world"[:]
assert_true(view.strip_suffix(" world") == Some("hello"))
assert_true(view.strip_suffix(" moon") == None)
assert_true(view.strip_suffix("hello world") == Some(""))
}StringView::sub
#alias("_[_:_]")
fn StringView::sub(self : StringView, start? : Int, end? : Int) -> StringViewCreates a subview of an existing view with proper UTF-16 boundary validation.
Parameters
- start : Starting UTF-16 code unit index relative to this view (default: 0), counting from the beginning of this view
- end : Ending UTF-16 code unit index relative to this view (optional)
- If None: extends to the end of this view
- Otherwise: counts from the beginning of this view
Returns
- A View representing the specified subrange of this view
Panics
- If start or end indices are out of this view's range
- If start or end position would split a UTF-16 surrogate pair
This prevents creating views that would split surrogate pairs, which would
result in invalid Unicode characters.
Performance
This function has O(1) complexity as it only performs boundary checks
without scanning the string content.
Examples
test {
let str = "Hello🤣World"[1:11] // "ello🤣Worl"
let view1 = str[0:6]
inspect(view1, content="ello🤣")
let view2 = str[8:]
inspect(view2, content="rl")
}StringView::suffixes
Iterates over all suffixes of the view, advancing by a Unicode character at
a time. Each yielded suffix is itself a view into the original string.
StringView::to_array
Converts the View into an array of Chars.
Example
test {
let view = "Hello🤣xa"[1:8]
let chars = view.to_array()
@debug.debug_inspect(chars, content="['e', 'l', 'l', 'o', '🤣', 'x']")
}StringView::to_bytes
#deprecated("Check `@encoding/utf8.encode`")
fn StringView::to_bytes(self : StringView) -> BytesConvert to bytes.
StringView::to_lower
fn StringView::to_lower(self : StringView) -> StringViewConverts the ASCII uppercase letters ('A' to 'Z') in this string to
lowercase. All other characters, including non-ASCII letters, are left
unchanged.
StringView::to_owned
#alias(to_string, deprecated="Use `to_owned` to allocate an owned String from a StringView; use `Show::to_string` or format strings for display")
fn StringView::to_owned(self : StringView) -> StringMaterialize this view into an owned String.
This crosses an ownership boundary and generally allocates. Use format
strings ("\{view}") or Show::to_string(view) when you only need a
display representation — those paths go through the Show trait and are
not flagged.
Examples
test {
let str = "Hello World"
let view = str.view(
start_offset=str.offset_of_nth_char(0).unwrap(),
end_offset=str.offset_of_nth_char(5).unwrap(),
) // "Hello"
inspect(view.to_owned(), content="Hello")
}StringView::to_upper
fn StringView::to_upper(self : StringView) -> StringViewConverts the ASCII lowercase letters ('a' to 'z') in this string to
uppercase. All other characters, including non-ASCII letters, are left
unchanged.
StringView::trim
fn StringView::trim(self : StringView, chars? : StringView) -> StringViewReturns the view of the string without the leading and trailing characters
that are in the given string.
StringView::trim_end
fn StringView::trim_end(self : StringView, chars? : StringView) -> StringViewReturns the view of the string without the trailing characters that are in
the given string.
StringView::trim_space
#deprecated("Use `trim` with default whitespace characters instead")
fn StringView::trim_space(self : StringView) -> StringViewReturns the view of the string without the leading and trailing spaces.
StringView::trim_start
fn StringView::trim_start(self : StringView, chars? : StringView) -> StringViewReturns the view of the string without the leading characters that are in
the given string.
StringView::unsafe_charcode_at
#deprecated("Use `StringView::unsafe_get` instead")
fn StringView::unsafe_charcode_at(self : StringView, index : Int) -> IntReturns the charcode(code unit) at the given index without checking if the
index is within bounds.
This method has O(1) complexity.
Example
test {
let str = "B🤣🤣C"
let view = str[:]
inspect(view.unsafe_get(0), content="66")
inspect(view.unsafe_get(1), content="55358")
inspect(view.unsafe_get(2), content="56611")
inspect(view.unsafe_get(3), content="55358")
inspect(view.unsafe_get(4), content="56611")
inspect(view.unsafe_get(5), content="67")
}StringView::unsafe_get
#internal(unsafe, "Undefined behavior if index is out of bounds.")
fn StringView::unsafe_get(self : StringView, index : Int) -> UInt16Returns the UTF-16 code unit at the given index without checking if the
index is within bounds.
This method has O(1) complexity.
StringView::view
fn StringView::view(self : StringView, start_offset? : Int, end_offset? : Int) -> StringViewReturns a new view of the view with the given start and end offsets.
UInt
Note
UInt is a built-in type. The documentation may not be complete here. You can find all methods and implementations in the core/builtin and core/uint package.
UInt::UInt
fn UInt::UInt(self : UInt) -> UIntThe identity constructor for UInt, allowing values to be written using
constructor syntax, e.g. UInt(3).
Example:
test {
inspect(UInt(3), content="3")
}UInt::clamp
fn UInt::clamp(self : UInt, min~ : UInt, max~ : UInt) -> UIntClamps an unsigned integer into the inclusive range [min, max].
Parameters:
- self : The value to clamp.
- min : The lower bound of the range.
- max : The upper bound of the range.
Returns min if self is less than min, max if self is greater
than max, and self otherwise. Aborts if min is greater than max.
Example:
test {
inspect(UInt(5).clamp(min=UInt(0), max=UInt(10)), content="5")
inspect(UInt(0).clamp(min=UInt(2), max=UInt(10)), content="2")
inspect(UInt(15).clamp(min=UInt(0), max=UInt(10)), content="10")
}UInt::clz
fn UInt::clz(self : UInt) -> IntCounts the number of leading zero bits in an unsigned 32-bit integer,
starting from the most significant bit.
Parameters:
- value : The unsigned 32-bit integer whose leading zeros are to be counted.
Returns the number of consecutive zeros starting from the most significant
bit. For a zero value, returns 32.
Example:
test {
inspect(0U.clz(), content="32")
inspect(1U.clz(), content="31")
inspect(0x80000000U.clz(), content="0")
}UInt::ctz
fn UInt::ctz(self : UInt) -> IntCounts the number of trailing zero bits in an unsigned 32-bit integer,
starting from the least significant bit. For a zero input, returns 32.
Parameters:
- self : The unsigned 32-bit integer whose trailing zeros are to be counted.
Returns the number of consecutive zeros at the least significant end of the
binary representation. Returns 32 if the input is zero.
Example:
test {
let x = 24U // Binary: ...011000
inspect(x.ctz(), content="3") // 3 trailing zeros
let y = 0U
inspect(y.ctz(), content="32") // All bits are zero
}UInt::lnot
fn UInt::lnot(self : UInt) -> UIntPerforms a bitwise NOT operation on an unsigned 32-bit integer. Flips all
bits in the number (changes each 0 to 1 and each 1 to 0).
Parameters:
- self : The unsigned 32-bit integer value on which to perform the bitwise NOT operation.
Returns a new unsigned 32-bit integer where each bit is inverted from the
input value.
Example:
test {
let x = 0xFF00U // Binary: 1111_1111_0000_0000
inspect(x.lnot(), content="4294902015") // Binary: ...0000_0000_1111_1111
}UInt::lsl
#deprecated("Use infix operator `<<` instead")
fn UInt::lsl(self : UInt, shift : Int) -> UIntPerforms a left shift operation on an unsigned 32-bit integer. Shifts each
bit in the number to the left by the specified number of positions, filling
the rightmost positions with zeros.
Parameters:
- self : The unsigned 32-bit integer to be shifted.
- shift : The number of positions to shift the bits. Must be non-negative and less than 32. Values outside this range are wrapped to fit within it (i.e., shift & 31).
Returns a new UInt value representing the result of shifting the bits left
by the specified number of positions. Each position shifted multiplies the
number by 2.
Example:
test {
let x = 1U
inspect(x << 3, content="8") // Using the recommended operator
let y = 8U
inspect(y << 1, content="16") // Using the recommended operator
}UInt::lsr
#deprecated("Use infix operator `>>` instead")
fn UInt::lsr(self : UInt, shift : Int) -> UIntPerforms a logical right shift on an unsigned 32-bit integer. Each bit in the
input value is shifted right by the specified number of positions, with zeros
shifted in from the left. DEPRECATED: Use the >> operator instead.
Parameters:
- self : The unsigned 32-bit integer to be shifted.
- shift : The number of positions to shift right. Must be non-negative.
Returns a new UInt value representing the result of the logical right shift
operation.
Example:
test {
let x = 0xF0000000U
inspect(x >> 4, content="251658240") // Using the recommended operator
}UInt::max
fn UInt::max(self : UInt, other : UInt) -> UIntReturns the larger of two unsigned integers.
Parameters:
- self : The first integer to compare.
- other : The second integer to compare.
Returns self if it is not less than other, other otherwise.
Example:
test {
inspect(UInt(1).max(UInt(2)), content="2")
inspect(UInt(2).max(UInt(1)), content="2")
inspect(UInt(0).max(UInt(0)), content="0")
}UInt::min
fn UInt::min(self : UInt, other : UInt) -> UIntReturns the smaller of two unsigned integers.
Parameters:
- self : The first integer to compare.
- other : The second integer to compare.
Returns self if it is not greater than other, other otherwise.
Example:
test {
inspect(UInt(1).min(UInt(2)), content="1")
inspect(UInt(2).min(UInt(1)), content="1")
inspect(UInt(0).min(UInt(0)), content="0")
}UInt::popcnt
fn UInt::popcnt(self : UInt) -> IntCounts the number of 1 bits (population count) in the binary representation
of an unsigned 32-bit integer.
Parameters:
- self : The unsigned 32-bit integer whose bits are to be counted.
Returns an integer representing the count of set bits (1s) in the binary
representation.
Example:
test {
let x = 0xF0F0U // Binary: 1111 0000 1111 0000
inspect(x.popcnt(), content="8") // Has 8 bits set to 1
}UInt::reinterpret_as_float
#deprecated("Use `Float::reinterpret_from_uint` instead")
fn UInt::reinterpret_as_float(self : UInt) -> FloatReinterpret UInt bit pattern as Float (deprecated alias).
Function reinterpret_as_float.
UInt::reinterpret_as_int
fn UInt::reinterpret_as_int(self : UInt) -> Intreinterpret the unsigned int as signed int
For number within the range of 0..=2^31-1,
the value is the same. For number within the range of 2^31..=2^32-1,
the value is negative
UInt::shl
#deprecated("Use infix operator `<<` instead")
fn UInt::shl(self : UInt, shift : Int) -> UIntPerforms a left shift operation on an unsigned 32-bit integer. Shifts each
bit in the integer to the left by the specified number of positions, filling
the rightmost positions with zeros.
Parameters:
- self : The unsigned 32-bit integer to be shifted.
- shift : The number of positions to shift left. Must be between 0 and 31 inclusive. Values outside this range will be masked with & 31.
Returns a new UInt value containing the result of the left shift operation.
Example:
test {
let x = 1U
inspect(x << 3, content="8") // Binary: 1 -> 1000
}UInt::shr
#deprecated("Use infix operator `>>` instead")
fn UInt::shr(self : UInt, shift : Int) -> UIntPerforms a logical right shift operation on an unsigned 32-bit integer by a
specified number of positions. All bits shifted in from the left are zeros.
Parameters:
- number : The unsigned 32-bit integer to be shifted.
- shift : The number of positions to shift right. Must be non-negative.
Returns a new UInt value that represents the result of shifting all bits in
number to the right by shift positions.
Example:
test {
let x = 0xFF000000U
inspect(x >> 8, content="16711680") // 0x00FF0000
}UInt::to_byte
fn UInt::to_byte(self : UInt) -> ByteConverts an unsigned 32-bit integer to a byte by taking its least significant
8 bits. Any bits beyond the first 8 bits are truncated.
Parameters:
- self : The unsigned 32-bit integer to be converted. Only the least significant 8 bits will be used.
Returns a byte containing the least significant 8 bits of the input integer.
Example:
test {
let n = 258U // In binary: 100000010
inspect(n.to_byte(), content="b'\\x02'") // Only keeps 00000010
let big = 4294967295U // Maximum value of UInt
inspect(big.to_byte(), content="b'\\xFF'") // Only keeps 11111111
}UInt::to_double
fn UInt::to_double(self : UInt) -> DoubleConverts an unsigned 32-bit integer to a double-precision floating-point
number. Since the range of unsigned 32-bit integers is smaller than what can
be precisely represented by a double-precision floating-point number, this
conversion is guaranteed to be exact.
Parameters:
- value : The unsigned 32-bit integer to be converted.
Returns a double-precision floating-point number that exactly represents the
input value.
Example:
test {
let n = 42U
inspect(n.to_double(), content="42")
let max = 4294967295U // maximum value of UInt
inspect(max.to_double(), content="4294967295")
}UInt::to_float
#deprecated("Use `Float::from_uint` instead")
fn UInt::to_float(self : UInt) -> FloatConvert UInt to Float (deprecated alias).
Convert to float.
UInt::to_int
#deprecated("Use `reinterpret_as_int` instead")
fn UInt::to_int(self : UInt) -> IntReinterprets an unsigned 32-bit integer as a signed 32-bit integer. For
values within the range of 0 to 2^31-1, the value remains the same. For
values within the range of 2^31 to 2^32-1, the value becomes negative due to
two's complement representation.
Parameters:
- self : The unsigned 32-bit integer to be reinterpreted.
Returns a signed 32-bit integer that has the same bit pattern as the input
unsigned integer.
Example:
test {
let a = 42U
inspect(a.reinterpret_as_int(), content="42")
let b = 4294967295U // maximum value of UInt (2^32 - 1)
inspect(b.reinterpret_as_int(), content="-1") // becomes -1 when reinterpreted as Int
}UInt::to_string
fn UInt::to_string(self : UInt, radix? : Int) -> StringConverts an unsigned integer to its string representation in the specified radix (base).
UInt::to_uint16
fn UInt::to_uint16(self : UInt) -> UInt16Converts a 32-bit unsigned integer to a 16-bit unsigned integer by truncating
its value to fit within the range of 0 to 65535.
Parameters:
- integer : The 32-bit unsigned integer to be converted. Values outside the range of UInt16 will be truncated to fit.
Returns a 16-bit unsigned integer containing the lower 16 bits of the input
value.
Example:
test {
let n = 42U
inspect(n.to_uint16(), content="42")
let max = 4294967295U
inspect(max.to_uint16(), content="65535") // -1 becomes max value of UInt16
let large = 65536U
inspect(large.to_uint16(), content="0") // Values wrap around
}UInt::to_uint64
fn UInt::to_uint64(self : UInt) -> UInt64Converts an unsigned 32-bit integer to an unsigned 64-bit integer by
zero-extending it. The resulting value preserves the original number's
magnitude while using 64 bits to represent it.
Parameters:
- self : The unsigned 32-bit integer (UInt) to be converted.
Returns an unsigned 64-bit integer (UInt64) representing the same numerical
value as the input.
Example:
test {
let n = 42U
inspect(n.to_uint64(), content="42")
let max = 4294967295U // Maximum value of UInt
inspect(max.to_uint64(), content="4294967295")
}UInt::trunc_double
fn UInt::trunc_double(val : Double) -> UIntConverts a double-precision floating-point number to an unsigned 32-bit
integer by truncating the decimal part. When the input is NaN or negative,
returns 0. When the input exceeds the maximum value of UInt (4294967295),
returns 4294967295.
Parameters:
- value : The double-precision floating-point number to be converted.
Returns an unsigned 32-bit integer representing the truncated value.
Example:
test {
inspect(UInt::trunc_double(42.75), content="42")
}UInt16
UInt16::UInt16
fn UInt16::UInt16(self : UInt16) -> UInt16The identity constructor for UInt16, allowing values to be written using
constructor syntax, e.g. UInt16(3).
Example:
test {
inspect(UInt16(3), content="3")
}UInt16::is_leading_surrogate
fn UInt16::is_leading_surrogate(self : UInt16) -> BoolChecks if the integer value represents a UTF-16 leading surrogate.
Leading surrogates are in the range 0xD800 to 0xDBFF.
Example:
test {
inspect(UInt16(0xD800).is_leading_surrogate(), content="true")
inspect(UInt16(0xDBFF).is_leading_surrogate(), content="true")
inspect(UInt16(0xDC00).is_leading_surrogate(), content="false")
inspect(UInt16(0x41).is_leading_surrogate(), content="false") // 'A'
}UInt16::is_surrogate
fn UInt16::is_surrogate(self : UInt16) -> BoolChecks if the integer value represents any UTF-16 surrogate (leading or trailing).
Surrogates are in the range 0xD800 to 0xDFFF.
Example:
test {
inspect(UInt16(0xD800).is_surrogate(), content="true") // leading surrogate
inspect(UInt16(0xDC00).is_surrogate(), content="true") // trailing surrogate
inspect(UInt16(0xDFFF).is_surrogate(), content="true") // trailing surrogate
inspect(UInt16(0x41).is_surrogate(), content="false") // 'A'
}UInt16::is_trailing_surrogate
fn UInt16::is_trailing_surrogate(self : UInt16) -> BoolChecks if the integer value represents a UTF-16 trailing surrogate.
Trailing surrogates are in the range 0xDC00 to 0xDFFF.
Example:
test {
inspect(UInt16(0xDC00).is_trailing_surrogate(), content="true")
inspect(UInt16(0xDFFF).is_trailing_surrogate(), content="true")
inspect(UInt16(0xD800).is_trailing_surrogate(), content="false")
inspect(UInt16(0x41).is_trailing_surrogate(), content="false") // 'A'
}UInt16::lnot
fn UInt16::lnot(self : UInt16) -> UInt16Performs a bitwise NOT operation on a UInt16 value, flipping every bit
within its 16-bit width.
Parameters:
- self : The UInt16 value to apply the bitwise NOT operation on.
Returns the result of the bitwise NOT operation as a UInt16.
Example:
test {
inspect(UInt16(0x0000).lnot().to_int(), content="65535")
inspect(UInt16(0xFFFF).lnot().to_int(), content="0")
}UInt16::to_byte
fn UInt16::to_byte(self : UInt16) -> ByteConverts a 16-bit unsigned integer to an 8-bit byte by truncating the higher
bits.
Parameters:
- value : The 16-bit unsigned integer to be converted.
Returns a byte containing the least significant 8 bits of the input value.
Example:
test {
let x = Int::to_uint16(258) // Binary: 0000_0001_0000_0010
inspect(x.to_byte(), content="b'\\x02'") // Only keeps 0000_0010
}UInt16::to_int
fn UInt16::to_int(self : UInt16) -> IntConverts an unsigned 16-bit integer to a 32-bit signed integer. The value is
zero-extended to fill the higher bits.
Parameters:
- value : The unsigned 16-bit integer to be converted.
Returns a 32-bit signed integer. Since the input value is always non-negative
and less than 65536, the conversion never results in overflow.
Example:
test {
let x = Int::to_uint16(42)
inspect(x.to_int(), content="42")
let max = Int::to_uint16(65535) // maximum value of UInt16
inspect(max.to_int(), content="65535")
}UInt16::to_int64
fn UInt16::to_int64(self : UInt16) -> Int64Converts an unsigned 16-bit integer to a signed 64-bit integer. The resulting
value will always be non-negative since the input is unsigned.
Parameters:
- value : The unsigned 16-bit integer to be converted.
Returns a 64-bit signed integer representing the same numerical value as the
input.
Example:
test {
let x = Int::to_uint16(42)
inspect(x.to_int64(), content="42")
let max = Int::to_uint16(65535) // maximum value of UInt16
inspect(max.to_int64(), content="65535")
}UInt16::to_string
fn UInt16::to_string(self : UInt16, radix? : Int) -> StringConvert UInt16 to string with optional radix.
Example:
test {
inspect((255 : UInt16).to_string(), content="255")
inspect((255 : UInt16).to_string(radix=16), content="ff")
}UInt64
UInt64::UInt64
fn UInt64::UInt64(self : UInt64) -> UInt64The identity constructor for UInt64, allowing values to be written using
constructor syntax, e.g. UInt64(3).
Example:
test {
inspect(UInt64(3), content="3")
}UInt64::clz
fn UInt64::clz(self : UInt64) -> IntCounts the number of leading zero bits in a 64-bit unsigned integer, starting
from the most significant bit.
Parameters:
- value : The 64-bit unsigned integer to count leading zeros in.
Returns the number of consecutive zeros starting from the most significant
bit. For a zero value, returns 64.
Example:
test {
inspect(0UL.clz(), content="64")
inspect(1UL.clz(), content="63")
inspect(0x8000_0000_0000_0000UL.clz(), content="0")
}UInt64::ctz
fn UInt64::ctz(self : UInt64) -> IntCounts the number of trailing zero bits in a 64-bit unsigned integer. The
trailing zeros are the contiguous zeros at the least significant end of the
binary representation.
Parameters:
- value : The 64-bit unsigned integer to count trailing zeros in.
Returns the number of trailing zero bits in the input value. If the input is
0, returns 64.
Example:
test {
let x = 0x8000000000000000UL // Binary: 1000...0000 (63 trailing zeros)
inspect(x.ctz(), content="63")
let y = 0UL
inspect(y.ctz(), content="64")
}UInt64::extend_uint
fn UInt64::extend_uint(val : UInt) -> UInt64Converts an unsigned 32-bit integer to an unsigned 64-bit integer by
zero-extending it. The resulting value preserves the original number's
magnitude while using 64 bits to represent it.
Parameters:
- value : The unsigned 32-bit integer (UInt) to be converted.
Returns an unsigned 64-bit integer (UInt64) representing the same numerical
value as the input.
Example:
test {
let n = 42U
inspect(UInt64::extend_uint(n), content="42")
let max = 4294967295U // Maximum value of UInt
inspect(UInt64::extend_uint(max), content="4294967295")
}UInt64::lnot
fn UInt64::lnot(self : UInt64) -> UInt64Performs a bitwise NOT operation on a 64-bit unsigned integer. Flips all bits
in the number, changing each 0 to 1 and each 1 to 0.
Parameters:
- self : The 64-bit unsigned integer value on which to perform the bitwise NOT operation.
Returns a new UInt64 value with all bits flipped from the input value.
Example:
test {
let x = 0xFFFF_FFFF_0000_0000UL
inspect(x.lnot(), content="4294967295") // 0x0000_0000_FFFF_FFFF
}UInt64::lsl
#deprecated("Use infix operator `<<` instead")
fn UInt64::lsl(self : UInt64, shift : Int) -> UInt64Performs a left shift operation on a 64-bit unsigned integer by a specified
number of bits.
Parameters:
- value : The 64-bit unsigned integer to be shifted.
- shift : The number of positions to shift left. Only the lowest 6 bits are used, effectively making the shift value wrap around at 64.
Returns a new UInt64 value representing the result of shifting the bits
left by the specified number of positions. Bits shifted beyond the 64-bit
boundary are discarded, and zeros are shifted in from the right.
Example:
test {
let x = 1UL
inspect(x << 4, content="16") // 1 << 4 = 16
}UInt64::lsr
#deprecated("Use infix operator `>>` instead")
fn UInt64::lsr(self : UInt64, shift : Int) -> UInt64Performs a logical right shift operation on a 64-bit unsigned integer. Moves
all bits to the right by a specified number of positions, filling the
leftmost bits with zeros.
Parameters:
- self : The 64-bit unsigned integer to be shifted.
- shift : The number of positions to shift right. If this value is negative or greater than 63, the behavior is undefined.
Returns a new UInt64 value containing the result of the right shift
operation.
Example:
test {
let x = 0xF000000000000000UL
inspect(x >> 4, content="1080863910568919040") // 0x0F00000000000000
}UInt64::popcnt
fn UInt64::popcnt(self : UInt64) -> IntCounts the number of bits set to 1 in the binary representation of an
unsigned 64-bit integer.
Parameters:
- self : The unsigned 64-bit integer whose bits are to be counted.
Returns an integer representing the number of 1 bits (population count) in
the binary representation of the input.
Example:
test {
let n = 0x7000_0001_1F00_100FUL // Binary: 0111 0000 ... 0001 1111 0000 0000 0001 0000 0000 1111
inspect(n.popcnt(), content="14") // Has 14 bits set to 1
}UInt64::reinterpret_as_double
fn UInt64::reinterpret_as_double(self : UInt64) -> DoubleReinterprets the bits of an unsigned 64-bit integer as a double-precision
floating-point number according to IEEE 754 standard. The bit pattern of the
input is preserved, only the type interpretation changes.
Parameters:
- value : The unsigned 64-bit integer whose bits are to be reinterpreted as a double-precision floating-point number.
Returns a double-precision floating-point number that has the same bit
pattern as the input unsigned 64-bit integer.
Example:
test {
// 0x4059000000000000 represents 100.0 in IEEE 754 double format
let n = 4636737291354636288UL
inspect(n.reinterpret_as_double(), content="100")
}UInt64::reinterpret_as_int64
fn UInt64::reinterpret_as_int64(self : UInt64) -> Int64Reinterprets the bits of an unsigned 64-bit integer as a signed 64-bit
integer. The bits remain the same, but their interpretation changes. This
operation is useful for low-level bit manipulation and type conversions where
you want to preserve the exact bit pattern.
Parameters:
- value : The unsigned 64-bit integer (UInt64) to be reinterpreted.
Returns a signed 64-bit integer (Int64) that has the same bit pattern as
the input value.
Example:
test {
let max = 18446744073709551615UL // Maximum value of UInt64
inspect(max.reinterpret_as_int64(), content="-1") // All bits set to 1 represents -1 in two's complement
}UInt64::shl
#deprecated("Use infix operator `<<` instead")
fn UInt64::shl(self : UInt64, shift : Int) -> UInt64Performs a left shift operation on an unsigned 64-bit integer value, shifting
bits to the left by the specified number of positions.
Parameters:
- number : The unsigned 64-bit integer to be shifted.
- shift : The number of positions to shift the bits left. Must be non-negative.
Returns an unsigned 64-bit integer representing the result of the left shift
operation.
Example:
test {
let x = 1UL
inspect(x << 2, content="4") // 1 << 2 = 4
}UInt64::shr
#deprecated("Use infix operator `>>` instead")
fn UInt64::shr(self : UInt64, shift : Int) -> UInt64Performs a logical right shift on an unsigned 64-bit integer by a specified
number of bit positions. All bits shifted in from the left are zeros.
Parameters:
- self : The unsigned 64-bit integer to be shifted.
- shift : The number of positions to shift right.
Returns the result of shifting the bits in self right by shift positions.
Example:
test {
let x = 0xFF00000000000000UL
inspect(x >> 8, content="71776119061217280")
}UInt64::to_be_bytes
fn UInt64::to_be_bytes(self : UInt64) -> BytesConverts the UInt64 to a Bytes of 8 bytes in big-endian byte order
(most significant byte first).
Parameters:
- self : The 64-bit unsigned integer to convert.
Returns a Bytes of length 8 whose first element is the most significant
byte of self and whose last element is the least significant byte.
Example:
test {
// 0x41..0x48 are the ASCII codes for 'A'..'H'
inspect(
0x4142_4344_4546_4748UL.to_be_bytes(),
content=(
#|b"ABCDEFGH"
),
)
}UInt64::to_byte
fn UInt64::to_byte(self : UInt64) -> ByteConverts an unsigned 64-bit integer to a byte by truncating it to fit within
the byte range (0 to 255).
Parameters:
- self : The unsigned 64-bit integer to be converted.
Returns a byte containing the least significant 8 bits of the input integer.
Example:
test {
let n = 258UL // In binary: 100000010
inspect(n.to_byte(), content="b'\\x02'") // Only keeps 00000010
}UInt64::to_double
fn UInt64::to_double(self : UInt64) -> DoubleConverts an unsigned 64-bit integer to a double-precision floating-point
number.
Parameters:
- self : The unsigned 64-bit integer (UInt64) to be converted.
Returns a double-precision floating-point number (Double) that represents
the same numerical value as the input. Note that due to the limited precision
of double-precision floating-point numbers, values larger than 2^53 may lose
precision during the conversion.
Example:
let n = 12345678901234567890UL
inspect(n.to_double(), content="12345678901234567000") // Note the slight precision loss
let small = 42UL
inspect(small.to_double(), content="42")UInt64::to_float
#deprecated("Use `Float::from_uint64` instead")
fn UInt64::to_float(self : UInt64) -> FloatConvert UInt64 to Float (deprecated alias).
UInt64::to_int
fn UInt64::to_int(self : UInt64) -> IntConverts an unsigned 64-bit integer to a 32-bit signed integer. The
conversion truncates the value to fit within the 32-bit range, possibly
losing information if the input value is too large.
Parameters:
- self : The unsigned 64-bit integer to be converted.
Returns a 32-bit signed integer representing the lower 32 bits of the input
value. If the input value is larger than the maximum value of a 32-bit signed
integer (2147483647), the result will be the truncated value interpreted as a
signed integer.
Example:
test {
let a = 42UL
inspect(a.to_int(), content="42")
let b = 18446744073709551615UL // max value of UInt64
inspect(b.to_int(), content="-1") // truncated to 32 bits
}UInt64::to_int64
#deprecated("Use `reinterpret_as_int64` instead")
fn UInt64::to_int64(self : UInt64) -> Int64Reinterprets a 64-bit unsigned integer as a 64-bit signed integer. The bits
of the number remain unchanged; only the interpretation of these bits
changes. This function is deprecated; use reinterpret_as_int64 instead.
Parameters:
- value : The 64-bit unsigned integer to be reinterpreted.
Returns a 64-bit signed integer representing the same bit pattern as the
input.
Example:
test {
let max = 18446744073709551615UL
inspect(max.reinterpret_as_int64(), content="-1")
}UInt64::to_le_bytes
fn UInt64::to_le_bytes(self : UInt64) -> BytesConverts the UInt64 to a Bytes of 8 bytes in little-endian byte order
(least significant byte first).
Parameters:
- self : The 64-bit unsigned integer to convert.
Returns a Bytes of length 8 whose first element is the least significant
byte of self and whose last element is the most significant byte.
Example:
test {
// The same value as `to_be_bytes`, with the byte order reversed
inspect(
0x4142_4344_4546_4748UL.to_le_bytes(),
content=(
#|b"HGFEDCBA"
),
)
}UInt64::to_string
fn UInt64::to_string(self : UInt64, radix? : Int) -> StringConverts an unsigned 64-bit integer to its string representation in the specified radix (base).
UInt64::to_uint
fn UInt64::to_uint(self : UInt64) -> UIntConverts a 64-bit unsigned integer to a 32-bit unsigned integer by truncating
the higher 32 bits.
Parameters:
- self : The 64-bit unsigned integer to be converted.
Returns a 32-bit unsigned integer containing the lower 32 bits of the input
value.
Example:
test {
let big = 0xFFFFFFFFFFFFFFFFUL // max value of UInt64
inspect(big.to_uint(), content="4294967295") // 0xFFFFFFFF, max value of UInt
let small = 42UL
inspect(small.to_uint(), content="42")
}UInt64::to_uint16
fn UInt64::to_uint16(self : UInt64) -> UInt16Converts a 64-bit unsigned integer to a 16-bit unsigned integer by truncating
the value to fit within the range of UInt16 (0 to 65535).
Parameters:
- value : The 64-bit unsigned integer to be converted to UInt16.
Returns a 16-bit unsigned integer representing the lower 16 bits of the input
value.
Example:
test {
inspect(42UL.to_uint16(), content="42")
inspect(18446744073709551615UL.to_uint16(), content="65535") // Wraps around to maximum UInt16 value
inspect(70000UL.to_uint16(), content="4464") // Value is truncated
}UInt64::trunc_double
fn UInt64::trunc_double(val : Double) -> UInt64Converts a double-precision floating-point number to an unsigned 64-bit
integer by truncating its decimal part. This is a raw conversion function
that does not handle special cases like NaN or infinity.
Parameters:
- value : The double-precision floating-point number to be truncated and converted.
Returns an unsigned 64-bit integer. The decimal part of the input is
discarded (truncated towards zero).
Example:
test {
inspect(UInt64::trunc_double(42.75), content="42")
}Unit
assert_false
#callsite(autofill(loc))
fn assert_false(x : Bool, msg? : StringView, loc~ : SourceLoc) -> Unit raiseTests whether a boolean condition is false, throwing an error if the
condition is true.
Parameters:
- condition : The boolean condition to test.
- location : The source location where the assertion is made. Used in error messages.
Throws a Failure error if the condition is true. The error message includes
the source location and the value that was expected to be false.
Example:
test {
assert_false(false)
assert_false(1 > 2)
}assert_true
Asserts that the given boolean value is true. Throws an error with source
location information if the assertion fails.
Parameters:
- condition : The boolean value to be checked.
- location : The source location where the assertion is made. Defaults to the current location.
Throws a Failure error with a descriptive message including the source
location if the condition is false.
Example:
test {
assert_true(true)
}compare
Three-way comparison of two values, returning a negative integer, zero, or
a positive integer when x is less than, equal to, or greater than y.
This is the free-function form of the Compare::compare trait method,
symmetric with hash. Being a plain function, it can also be passed as a
function value, e.g. array.sort_by(compare).
test {
inspect(compare(1, 2).is_neg(), content="true")
inspect(compare("abc", "abc"), content="0")
}debug_assert
fn debug_assert(x : () -> Bool) -> UnitAsserts that a condition is true in debug mode.
The condition is provided as a thunk and is evaluated only when assertions
are enabled. If the condition evaluates to false, this function do panic.
In release mode, debug_assert is a no-op and does not evaluate the thunk.
Parameters:
- x : A thunk that computes the condition to check.
Panic in debug mode when x() returns false.
fail
Raises a Failure error with a given message and source location.
Parameters:
- message : A string containing the error message to be included in the failure.
- location : The source code location where the failure occurred. Automatically provided by the compiler when not specified.
Returns a value of type T wrapped in a Failure error type.
Throws an error of type Failure with a message that includes both the
source location and the provided error message.
hash
Compute the hash of value.
This is the free-function form of the Hash::hash trait method, symmetric
with @json.to_json. Prefer it over the promoted value.hash() method.
test {
inspect(hash(42) == hash(42), content="true")
}ignore
fn[T] ignore(t : T) -> UnitEvaluates an expression and discards its result. This is useful when you want
to execute an expression for its side effects but don't care about its return
value, or when you want to explicitly indicate that a value is intentionally
unused.
Parameters:
- value : The value to be ignored. Can be of any type.
Example:
test {
let x = 42
ignore(x) // Explicitly ignore the value
let mut sum = 0
ignore(1, 2, 3.each(x => sum x)) // Ignore the Unit return value of each()
inspect(sum, content="6")
}inspect
#callsite(autofill(args_loc, loc))
fn inspect(obj : &Show, content? : String, loc~ : SourceLoc, args_loc~ : ArgsLoc) -> Unit raise InspectErrorTests if the string representation of an object matches the expected content.
Used primarily in test cases to verify the correctness of Show
implementations and program outputs.
Parameters:
- object : The object to be inspected. Must implement the Show trait.
- content : The expected string representation of the object. Defaults to an empty string.
- location : Source code location information for error reporting. Automatically provided by the compiler.
- arguments_location : Location information for function arguments in source code. Automatically provided by the compiler.
Throws an InspectError if the actual string representation of the object
does not match the expected content. The error message includes detailed
information about the mismatch, including source location and both expected
and actual values.
Example:
test {
inspect(42, content="42")
inspect("hello", content="hello")
debug_inspect([1, 2, 3], content="[1, 2, 3]")
}not
#deprecated("This function is deprecated.")
fn not(x : Bool) -> BoolPerforms logical negation on a boolean value.
Parameters:
- value : The boolean value to negate.
Returns the logical NOT of the input value: true if the input is false,
and false if the input is true.
null
JSON null constant.
Equivalent to Json::null().
Example:
test {
inspect(null.stringify(), content="null")
}physical_equal
fn[T] physical_equal(a : T, b : T) -> BoolTests whether two values are physically equal.
This function is intended only for performance optimizations. Do not depend
on its result for program semantics.
NOTE: The result of physical_equal may not be consistent across different
backends and/or different compiler optimization settings.
Parameters:
- first : The first value to compare.
- second : The second value to compare.
- T : The type parameter representing the type of values being compared.
Returns a backend- and optimization-dependent result indicating whether the
two values are physically equal.
Example:
test {
let arr1 = [1, 2, 3]
let arr2 = arr1
let arr3 = [1, 2, 3]
inspect(physical_equal(arr1, arr2), content="true") // Same object
inspect(physical_equal(arr1, arr3), content="false") // Different objects with same content
}Source Files
- array.mbt
- array_block.mbt
- array_sort.mbt
- array_sort_by_impl.mbt
- array_sort_impl.mbt
- arraycore_js.mbt
- arraycore_nonjs.mbt
- arrayview.mbt
- assert.mbt
- assert_debug.mbt
- assert_release.mbt
- autoloc.mbt
- bitstring.mbt
- bitstring_v128.mbt
- bool.mbt
- bounds.mbt
- byte.mbt
- bytes.mbt
- bytes_find.mbt
- bytes_unsafe.mbt
- bytesview.mbt
- char.mbt
- compare_fn.mbt
- console.mbt
- deprecated.mbt
- double.mbt
- double_limits.mbt
- double_mod_js.mbt
- double_mod_nonjs.mbt
- double_pow_js.mbt
- double_pow_nonjs.mbt
- double_round.mbt
- double_round_js.mbt
- double_round_wasm.mbt
- double_ryu_js.mbt
- double_ryu_nonjs.mbt
- double_scalbn.mbt
- double_to_int.mbt
- double_to_int64_js_wasm.mbt
- double_to_int64_native.mbt
- double_to_int_wasm.mbt
- double_to_uint.mbt
- double_to_uint_wasm.mbt
- extends.mbt
- failure.mbt
- fixedarray.mbt
- fixedarray_block.mbt
- hash_fn.mbt
- hasher.mbt
- int.mbt
- int64.mbt
- intrinsics.mbt
- iter.mbt
- iterator.mbt
- json.mbt
- linked_hash_map.mbt
- mutarrayview.mbt
- op.mbt
- operators.mbt
- option.mbt
- range.mbt
- readonlyarray.mbt
- result.mbt
- show.mbt
- simd.mbt
- string.mbt
- string_find_code_unit.mbt
- string_like.mbt
- string_methods.mbt
- stringbuilder.mbt
- stringbuilder_buffer.mbt
- stringbuilder_concat.mbt
- stringview.mbt
- to_string.mbt
- traits.mbt
- tuple_compare.mbt
- tuple_eq.mbt
- tuple_hash.mbt
- tuple_show.mbt
- tuple_to_json.mbt
- uint.mbt
- uint16_char.mbt
- uint64.mbt
- uninitialized_array.mbt
- unit.mbt
Install
Installed by default
corestandard library
Apache-2.0
Updated 13 days ago