#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

#Builtin Package Documentation

#Core Types and Functions

#Assertions and Testing

#Inspect Function

#Result Type

#Option Type

#Iterator Type

#Array and FixedArray

#Views (Zero-Copy Slices)

#String Operations

#StringBuilder

#JSON Support

#Comparison Operations

#Utility Functions

#Error Handling

#Best Practices

#Performance Notes

#Add

#BitAnd

#BitOr

#BitXOr

#Compare

#Default

#Div

#Eq

#Hash

#Logger

#Mod

#Mul

#Neg

#Shl

#Show

Examples

#Shr

#Sub

#ToJson

#ToStringView

#BenchError

#Failure

#Failure::to_json

#Failure::to_string

#InspectError

#SnapshotError

#ArgsLoc

#ArgsLoc::to_json

#ArgsLoc::to_string

#Array

#Array::Array

#Array::add

#Array::all

Example

#Array::any

Example

#Array::append

#Array::at

#Array::binary_search

Example

Arguments

Returns

Notes

#Array::binary_search_by

#Array::blit_to

#Array::capacity

#Array::chunk_by

#Array::chunks

#Array::clear

Example

#Array::compare

#Array::contains

#Array::copy

#Array::count

Example

#Array::count_if

Example

#Array::dedup

#Array::drain

Example

#Array::each

#Array::eachi

Example

Add

BitAnd

BitOr

BitXOr

Compare

Default

Div

Eq

Hash

Logger

Mod

Mul

Neg

Shl

Show

Shr

Sub

ToJson

ToStringView

BenchError

Failure

Failure::to_json

Failure::to_string

InspectError

SnapshotError

ArgsLoc

ArgsLoc::to_json

ArgsLoc::to_string

Array

Array::Array

Array::add

Array::all

Array::any

Array::append

Array::at

Array::binary_search

Array::binary_search_by

Array::blit_to

Array::capacity

Array::chunk_by

Array::chunks

Array::clear

Array::compare

Array::contains

Array::copy

Array::count

Array::count_if

Array::dedup

Array::drain

Array::each

Array::eachi

Array::ends_with

Array::equal

Array::extract_if

Array::fill

Array::filter

Array::filter_map

Array::flatten

Array::fold

Array::foldi

Array::from_fixed_array

Array::from_iter

Array::get

Array::get_view

Array::hash

Array::insert

Array::is_empty

Array::is_sorted

Array::iter

Array::iter2

Array::join

Array::last

Array::length

Array::lexical_compare

Array::make

Array::makei

Array::map

Array::map_in_place

Array::mapi

Array::mapi_in_place