Skip to content

builtins

Builtins are always available without importing any module.

Function Signature Description
println (value T = "") Print value with newline. Accepts any type.
print (value T) Print value without newline. Accepts any type.
eprintln (value T = "") Print to stderr with newline. Accepts any type.
eprint (value T) Print to stderr without newline. Accepts any type.
flush () Flush buffered stdout so partial-line output appears immediately.

All types are printable: string, i64, f64, bool, arrays, maps, structs, and pointers.

stdout is buffered. print output may not appear until a newline is written (on a terminal) or the buffer fills (on a pipe or file); call flush() to force it out for prompts, progress indicators, and spinners. system flushes stdout and stderr before running the child so output is not reordered.

Function Signature Description
input () -> string Read line from stdin. Flushes stdout first so a preceding print prompt is visible. A trailing \n or \r\n is dropped and embedded NUL bytes are kept. At end of input it returns ""; use io.stdin_at_eof() to tell that from a blank line.
Function Description
i128, i256 Convert to wide signed integers (struct-based, 128/256-bit)
u128, u256 Convert to wide unsigned integers (struct-based, 128/256-bit)
Function Signature Description
len (collection T) -> i64 Length of a string (byte length, not character count), array, map, Channel (values buffered), Builder (bytes written), or range (iteration count); panics (P0155) if a range has more than i64.MAX elements, e.g. len(range(i64.MIN, i64.MAX)), including a u64 or wide-integer range whose count does not fit an i64
type_of (value T) -> string Returns the Grayscale type name as a string (e.g. "i64", "u64", "f64", "string", "i128", "u256"). Accepts any type.
size_of (Type) -> i64 Size of type in bytes
fields (instance T) -> [string] Returns the field names of a struct as an array of strings in declaration order. Accepts struct instances and pointers to structs.
copy (value T) -> T Create deep copy. Accepts any type.
new (Type) -> ^Type Allocate zero-initialized value of any type on the heap arena
ref (variable T) -> T Create a transparent reference (alias) to a variable. The return type is inferred and cannot be explicitly annotated. Reads and writes through the reference affect the original. Mutability is determined by the declaration (mut or const).
addr (variable T) -> ^T Get memory address of a variable
raw (variable T) -> ^T Get unchecked pointer — skips nil-check panics and const-source write protection
wrap_add (a T, b T) -> T Wrapping addition on any integer type: the true sum modulo 2^N, in two’s complement for signed types. Never panics. Operands type as for a binary operator. Unsafe: requires an unsafe block or an unsafe function (see Memory Safety)
wrap_sub (a T, b T) -> T Wrapping subtraction on any integer type. Wrapping negation is wrap_sub(0, x). Unsafe, like wrap_add
wrap_mult (a T, b T) -> T Wrapping multiplication on any integer type. Unsafe, like wrap_add
wrap_div (a T, b T) -> T Division on any integer type that returns MIN for MIN / -1 instead of panicking (P0079). Division by zero still panics (P0078). Unsafe, like wrap_add
error (code ErrorCode, message string = "") -> Error Create error value
assert (condition bool, message string = "") Terminate if condition is false. Message is optional.
panic (message string) Terminate with error message
exit (code i64) Exit program with code
range (start i64, end i64, step i64 = 1) Create integer range; step defaults to 1. Only valid as the source of a for loop; Range cannot be written as a type. The loop variable is i64, or the widest wide integer type among the bounds
cast (value T, Type) -> Type Explicit type conversion
to_char (s string, index i64) -> char Return the char at character position index (not byte position). The char is a 32-bit Unicode codepoint; use cast(c, i64) on the result for its numeric value. Panics if index is out of bounds.
char_count (s string) -> i64 Return the number of Unicode characters (codepoints) in a string. Unlike len(), which returns byte count, char_count() counts decoded UTF-8 characters.
from_c_string (ptr ^u8) -> string Convert a C char* return value to a Grayscale string (for C interop)
to_c_string (s string) -> ^u8 Return a NUL-terminated copy of a string as a raw C pointer that lives for the rest of the program, for storing in an extern struct field or a ^u8 variable (for C interop)
embed (path string) -> string Read a file at compile time and return its contents as a string literal baked into the binary
here () -> SourceLocation Return the file, line, and column of the call site, filled in at compile time (see Source Location Type (SourceLocation))
system (command string) -> i64 Run a shell command and return its exit code. Returns -1 if killed by signal.

Reference behavior with ref():

The ref() function creates a reference to an existing value. The mutability of the reference depends on the variable declaration:

import @arrays
do main() {
mut arr [i64] = {1, 2, 3}
// mut ref is mutable - can modify through the reference
mut r1 = ref(arr)
arrays.append(r1, 4) // OK - modifies arr
// const ref is read-only - can read but not modify
const r2 = ref(arr)
mut val = r2[0] // OK - can read
// arrays.append(r2, 5) // ERROR - cannot modify through const ref
// const ref sees changes made to the original
arrays.append(arr, 6)
println(r2[4]) // Prints 6 - r2 sees the change
println(val)
}

Mutability rules:

Reference declaration Source Allowed?
mut r = ref(x) mut yes
const r = ref(x) mut yes, read-only view of a mutable source
const r = ref(x) const yes
mut r = ref(x) const no; you cannot get a mutable reference to a const source. Use copy(x) to obtain an independent mutable instance.

Argument requirement: ref() requires a variable, struct field, array index, or pointer dereference; anything with a stable address. Literals, call results, and arithmetic expressions are rejected. The same rule applies to addr() and raw(), and the check recurses through member/index chains, so ref(some_call().field) is validated end-to-end. Indexing a dynamic [T] array is also rejected for all three (addr(arr[i]), raw(arr[i]), ref(arr[i])) — the backing store relocates when the array grows, leaving the pointer dangling. A fixed-size [T,N] array element is allowed, since its storage never moves.

assert() — runtime assertion

assert() checks a condition at runtime. If the condition is false, the program terminates immediately and prints an assertion-failed panic to stderr. An optional second argument provides a message appended to the output.

do main() {
mut x i64 = 1
mut items [i64] = {1}
mut connected bool = true
assert(x > 0, "x must be positive")
assert(len(items) > 0, "list cannot be empty")
assert(connected) // message is optional
}

assert() is a global builtin — no import required.

Rules:

  • The condition must be a bool. Passing a non-bool is a compile-time error.
  • The optional message must be a string. Passing any other type is a compile-time error.
  • Both arguments are evaluated before assert runs, so the message expression is evaluated whether or not the condition holds.
  • If the condition is true, the program continues normally. assert() has no return value.
Function Signature Description
sleep_s (seconds i64) Sleep for seconds
sleep_ms (ms i64) Sleep for milliseconds
sleep_ns (ns i64) Sleep for nanoseconds

embed(path string) -> string

embed() reads a file from disk at compile time and bakes its entire contents into the binary as a string literal. The resulting value is available as a string at runtime with no file I/O overhead.

The path is resolved relative to the directory of the source file containing the embed() call. Absolute paths are also accepted. The argument must be a string literal; variables and expressions are rejected at compile time. If the file does not exist or cannot be read when the compiler runs, it is a compile-time error.

embed() is valid at file scope (as a const initializer) or inside a function body.

// Embed a file at file scope, baked into the binary at compile time
// const LICENSE string = embed("../../LICENSE")
// const DEFAULT_CONFIG string = embed("config/defaults.json")
// do main() {
// // Also valid inside a function
// const shader string = embed("shaders/vertex.glsl")
// println(LICENSE)
// }
do main() {
println("hello")
}

The embedded file is read once during compilation. Changes to the file after compilation have no effect on the binary. The compiler resolves the path relative to the .gray source file, not the current working directory when running grayc.