Standard Library ​

Mesh's standard library is available without package installation. Module-qualified functions can be used directly; import Module is optional. Concurrency, web, database, iterator, and distributed modules have dedicated guides, while this page covers the general-purpose modules.

Strings ​

String indexing is by Unicode code point rather than byte. String.slice(text, start, end) uses a zero-based, exclusive end and clamps both positions to the string's bounds.

The <> operator concatenates two strings. println(value) writes to standard output with a newline, and print(value) writes without one.

Input, Environment, and Files ​

File operations return error text instead of terminating the program:

case File.read("settings.txt") do
  Ok(contents) -> println(contents)
  Err(error) -> IO.eprintln("settings: #{error}")
end

Regular Expressions ​

Use ~r/pattern/ for a literal pattern. Literal flags are i (case-insensitive), m (multi-line), and s (dot matches newlines). Use Regex.compile for a pattern known only at runtime.

fn main() do
  let identifier = ~r/^[a-z][a-z0-9_]*$/i
  if Regex.is_match(identifier, "mesh_14") do
    println("valid")
  end
end

Eager Collections ​

Lists and maps are polymorphic. Sets and queues currently store Int values. Collection updates are immutable: keep the returned collection.

Lists ​

List.head, List.tail, List.get, List.last, and List.nth require an existing element. Check the length or use List.find, which returns Option<T>, when absence is expected.

Maps and Sets ​

Map.get requires an existing key; call Map.has_key first when absence is normal.

Tuples, Ranges, and Queues ​

Queue.pop and Queue.peek require a non-empty queue.

Bytes ​

Bytes stores arbitrary binary data without treating it as UTF-8. It does not implicitly convert to String; use Bytes.to_utf8 when text is expected and handle its Result.

case "ff0041" |> Bytes.from_hex() do
  Ok(raw) ->
    println("#{Bytes.length(raw)}")
    raw |> Bytes.to_base64() |> println()
  Err(error) -> println(error)
end

Checked construction and fixed-width APIs use the nominal BytesError type; handle failures with Err(_) without depending on runtime error text.

The mesh-binary source package adds a bounded immutable BinaryReader. Its vectors use a canonical unsigned 32-bit big-endian length prefix, and finish rejects trailing bytes.

Wide integers ​

U64, U128, and I128 are opaque integer values for protocol fields that do not fit Mesh Int. Construction and arithmetic are checked. Convert to Int only when the value is known to fit.

case U64.parse("18446744073709551615") do
  Ok(value) -> do
    value |> U64.to_string() |> println()
    case value |> U64.to_int() do
      Ok(number) -> println("#{number}")
      Err(error) -> println(error)
    end
  end
  Err(error) -> println(error)
end

Each module exposes the same surface:

Replace U64 with U128 or I128 for the corresponding width and signedness: for example, U128.multiply(left, right) performs checked 128-bit unsigned multiplication. Bytes.read_uint_le decimal output can be passed to U64.parse.

Checked Integer Arithmetic ​

Normal Int operators are convenient for ordinary arithmetic. Use Checked at financial, protocol, and resource-accounting boundaries where overflow or invalid division must be returned as data.

Rounding is explicit: :toward_zero, :floor, :ceil, :half_away_from_zero, or :half_even.

case Checked.mul_div(1_005, 1, 100, :half_even) do
  Ok(value) -> println("#{value}")
  Err(error) -> println(error)
end

Math and Numeric Conversion ​

Crypto ​

The Crypto module is binary-first. Public data uses Bytes; private keys and derived key material are move-only resources that cannot be printed, serialized, or sent through actor mailboxes. Fallible operations return CryptoError.

Hashing ​

fn main() do
  let input = Bytes.from_utf8("hello")
  let hash = Crypto.sha256(input)
  println(Bytes.to_hex(hash))
end

Secrets and authenticated cryptography ​

fn authenticate() -> Int ! CryptoError do
  let key = Secret.random(32) ?
  let tag = Crypto.hmac_sha256(key, Bytes.from_utf8("message")) ?
  Secret.destroy(tag)
  Secret.destroy(key)
  Ok(0)
end

Borrowed keys remain owned by the caller. Crypto.aead_key and the *_from_secret constructors consume their input, including on error. Use Secret.destroy for early destruction; otherwise the compiler inserts destruction on every scope exit.

Crypto.argon2id accepts salts from 8 through 64 bytes, memory from 8 * parallelism through 65,536 KiB, 1 through 10 iterations, 1 through 8 lanes, outputs from 16 through 64 bytes, and passwords up to 65,536 bytes. The low end exists for published vectors, compatibility tests, and explicitly versioned application profiles; these bounds are resource-safety limits, not a password policy. Applications must pin a reviewed profile instead of exposing the parameters to users. Messenger recovery pins its values in the versioned backup profile and stores the salt and profile version with the ciphertext.

UUID ​

fn main() do
  let id = Crypto.uuid4()
  println(id)   # e.g. "550e8400-e29b-41d4-a716-446655440000"
end

Crypto.uuid4() generates a cryptographically random UUID v4 in the standard 8-4-4-4-12 format.

Encoding ​

Base64 ​

The Base64 module encodes and decodes the UTF-8 bytes of String values. Decoding returns Result<String, String> because the input may be malformed or decode to invalid UTF-8. Use Bytes.to_base64 and Bytes.from_base64 for arbitrary binary values.

fn main() do
  let encoded = Base64.encode("hello world")
  println(encoded)   # aGVsbG8gd29ybGQ=

  case Base64.decode(encoded) do
    Ok(s) -> println(s)   # hello world
    Err(e) -> println("decode error: #{e}")
  end

  # URL-safe variant (replaces + with - and / with _)
  let url_enc = Base64.encode_url("hello world")
  case Base64.decode_url(url_enc) do
    Ok(s) -> println(s)
    Err(e) -> println(e)
  end
end

Hex ​

The Hex module encodes and decodes the UTF-8 bytes of String values. Decoding is case-insensitive and returns Result<String, String>. Use Bytes.to_hex and Bytes.from_hex for arbitrary binary values.

fn main() do
  let h = Hex.encode("hi")
  println(h)   # 6869

  case Hex.decode(h) do
    Ok(s) -> println(s)   # hi
    Err(e) -> println("decode error: #{e}")
  end
end

DateTime ​

The DateTime module provides UTC timestamps, ISO 8601 parsing and formatting, Unix timestamp interop, arithmetic, and comparison. Internally, DateTime values are backed by a 64-bit Unix millisecond timestamp.

Current Time ​

fn main() do
  let dt = DateTime.utc_now()
  let ms = DateTime.to_unix_ms(dt)
  let iso = DateTime.to_iso8601(dt)
  println(iso)   # e.g. "2024-01-15T10:30:00.000Z"
end

Parsing and Formatting ​

fn main() do
  case DateTime.from_iso8601("2024-01-15T10:30:00Z") do
    Ok(dt) ->
      let formatted = DateTime.to_iso8601(dt)
      println(formatted)   # "2024-01-15T10:30:00.000Z"
    Err(e) -> println("parse error: #{e}")
  end
end

Unix Timestamp Interop ​

fn main() do
  case DateTime.from_unix_ms(1705316200000) do
    Ok(dt) -> println("#{DateTime.to_unix_ms(dt)}")
    Err(error) -> println(error)
  end

  case DateTime.from_unix_secs(1705316200) do
    Ok(dt) -> println("#{DateTime.to_unix_secs(dt)}")
    Err(error) -> println(error)
  end
end

Arithmetic ​

fn main() do
  case DateTime.from_iso8601("2024-01-15T10:30:00Z") do
    Ok(dt) ->
      let next_week = DateTime.add(dt, 7, :day)
      let tomorrow = DateTime.add(dt, 1, :day)
      let later = DateTime.add(dt, 2, :hour)
      let diff = DateTime.diff(next_week, dt, :day)
      println("#{diff}")   # 7.0
    Err(_) -> println("error")
  end
end

DateTime.add(dt, n, unit) supports :ms, :second, :minute, :hour, :day, and :week. Negative n subtracts.

DateTime.diff(dt1, dt2, unit) accepts the same units and returns a Float representing how much later dt1 is than dt2. It is negative if dt1 is earlier.

Comparison ​

fn main() do
  case DateTime.from_iso8601("2024-01-15T10:30:00Z") do
    Ok(dt) ->
      let future = DateTime.add(dt, 1, :day)
      let is_before = DateTime.is_before(dt, future)   # true
      let is_after = DateTime.is_after(future, dt)     # true
      println("#{is_before}")
    Err(_) -> println("error")
  end
end

Monotonic Time and Durations ​

Use DateTime for timestamps that people or external systems need to read. Use Monotonic for elapsed time and deadlines; it cannot jump when the wall clock changes.

Both duration conversions detect negative inputs and integer overflow. Their nanosecond results can be passed to APIs such as Channel.recv.

Deterministic Randomness ​

Random threads generator state explicitly, making runs reproducible:

This generator is not suitable for secrets. Use Crypto.uuid4 for cryptographically random identifiers.

What's Next? ​

• Concurrency — actors, jobs, timers, and bounded channels
• Iterators — lazy pipelines and collection terminals
• Testing — write and run tests with meshc test
• Developer Tools — meshc, meshpkg, formatter, REPL, LSP
• Web — HTTP server, client, and WebSocket