Skip to content

Builtin Functions

This reference covers the globally available functions and keywords for input, output, and system utilities like timing.

Console Output (print)

The print keyword handles all console output. It can print raw values, the results of expressions, or formatted strings.

Printing Expressions

You can pass a variable or a mathematical operation directly to print.

a = 1 m
print 1       // Prints: 1
print a       // Prints: 1m
print a * 2   // Prints: 2m

Formatted Strings

Zigma uses Zig-style formatting for strings. You can inject variables into strings using {} blocks.

Syntax: {[variable]:[fill][alignment][width].[precision]}

  • Variable: The name of the variable to print.
  • Fill: A single character used for padding (e.g., _, 0).
  • Alignment: <, ^, or > (Left, Center, Right).
  • Width: The total field width in characters.
  • Precision: The number of decimal places to display.

Examples: 

g = 9.81 m/s2

print "{g}"       // "9.81m.s⁻²"
print "{g:.0}"    // "10m.s⁻²" (Rounded)
print "{g:.4}"    // "9.8100m.s⁻²"
print "{g: <12}"  // "9.81        m.s⁻²" (Left align, width 12)
print "{g:_^12}"  // "____9.81____m.s⁻²" (Center align with underscores)

System Time (time)

The time keyword returns the current system time in nanoseconds.

  • Underlying Type: i96
  • Default Scale: ns (nanoseconds)

Benchmarking

time is primarily used for measuring the execution duration of code blocks.

start = time

// ... some complex calculation ...

duration = time - start
print "Calculation took: {duration}"

Type and Scale Conversion

You can convert the time result to different units or numeric types for easier reading.

t_sec = time in s as f64

Tensor I/O

input

Loads a raw tensor from a text file. You must explicitly declare the unit and the dimension the data represents.

Syntax: variable = input "path/to/file" unit

The file must use commas for columns and semicolons for rows: 

1, 2, 3;
4, 5, 6

Usage: 

m = input "matrix.txt" m/s

output

Saves a tensor's current values to a text file.

Syntax: output variable "path/to/file"

v = [10, 20, 30] m
output v "results.txt"

Data Tables (table)

The table function is used for importing CSV files that require interpolation. Unlike input, it expects a CSV with headers containing units.

Syntax: variable = table "path/to/file.csv"

For detailed usage on querying and interpolating tables, see the Experimental Data guide.