Collections & Strings

The tables below are generated from the interpreter's own builtin dispatch table (the fn call_builtin match statement in engine/crates/qu-interp/src/lib.rs), not written speculatively ahead of the implementation — every function listed here runs today.

Strings

All index/length arguments are 0-based (matching every other index in this codebase) and unicode-aware: implemented on .chars(), never a raw byte slice, so a multi-byte UTF-8 string indexes by character, not by byte.

Overloads: substr

mid is the exact same builtin under a second, BASIC/Excel-flavored name; either spelling accepts either form. The example below starts with the simplest call — everything after a fixed position — then the bounded form, then shows the clamping behavior when the requested length overruns the string:

s = "Hello, World!"
print(substr(s, 7))          # "World!" — to the end

print(substr(s, 0, 5))       # "Hello" — bounded

print(substr(s, 7, 100))     # "World!" — clamped, not an error

print(mid(s, 7, 5))          # "World" — mid is substr under another name

World!
Hello
World!
World

These are the string functions reached for constantly: slicing out a piece, swapping one substring for another, padding a value so a column of output lines up, and fixing up capitalization on a name typed in whatever case a user felt like. s * n repeats a string, in either order, and a non-whole count is an error rather than a silent floor — the same operator overload 3 * 4 uses, extended to strings rather than a separate repeat_str call being the only spelling. The example below chains a slice into a replace, pads a number-turned-string with leading zeros, title-cases a name, and counts a substring's occurrences:

print("-" * 40)                                  # "----------------------------------------"

print("hello".substr(0, 2).replace("e", "i"))    # "hi"

print(pad_left(str(7), 3, "0"))                  # "007"

print(proper("ada lovelace"))                    # "Ada Lovelace"

print(count("banana", "a"))                      # 3

----------------------------------------
hi
007
Ada Lovelace
3

Overloads: remove

Picked by the TYPE of the second argument, not a flag: a Str means "delete every occurrence of this text anywhere in s"; a number means "delete this run of characters" instead, with an optional third argument narrowing how many. Returns a Str either way:

s = "hello, world"
print(remove(s, ", "))       # "helloworld" -- every occurrence of the text

print(remove(s, 0, 5))       # ", world" -- 5 characters starting at position 0

print(remove(s, 7))          # "hello, " -- position 7 to the end, count omitted

helloworld
, world
hello, 

Patterns

A regular expression is the one string tool with no workaround — everything else here can be written as a loop, and this cannot.

regex_find_all pulls out every run of digits in a string, regex_replace rearranges a date using capture-group backreferences, regex_groups reads those same captures back individually, and like answers a wildcard question without writing a full pattern:

print(regex_find_all("a1b22c333", "[0-9]+"))                                          # ("1", "22", "333")

print(regex_replace("2026-09-07", "([0-9]+)-([0-9]+)-([0-9]+)", "$3/$2/$1"))          # "07/09/2026"

print(regex_groups("v1.2.3", "v([0-9]+)\.([0-9]+)"))                                  # ("1", "2")

print(like("hello.txt", "*.txt"))                                                      # true

("1", "22", "333")
07/09/2026
("1", "2")
true

regex_match just asks yes/no, regex_find returns the first match alone, regex_split divides the string on the pattern, and regex_count tallies non-overlapping matches:

s = "sensor_1: 12.4, sensor_2: 9.8, sensor_3: 15.0"
print(regex_match(s, "sensor_[0-9]+"))    # true

print(regex_find(s, "[0-9]+\.[0-9]+"))    # "12.4"

print(regex_split(s, ", *"))              # 3-piece split on each comma

print(regex_count(s, "sensor_"))          # 3

true
12.4
("sensor_1: 12.4", "sensor_2: 9.8", "sensor_3: 15.0")
3

The engine is the regex crate, which is linear in the input by construction: a pattern typed at a prompt cannot hang the interpreter the way a backtracking engine can on (a+)+b. The price is no backreferences and no lookaround, which is the right trade for a language you drive interactively. A pattern that does not compile is an error naming the character it choked on, never a silent no-match — a typo and a genuine miss must not look the same.

like is translated into a regular expression rather than matched by a second engine, so the two cannot disagree about anchoring or Unicode. Reach for it first: most "does this look like that" questions are a wildcard question, and a wildcard is far easier to get right.

Chaining

Every string function is also a method on the value, so a chain reads left to right:

s = "  Hello, Qu World!  "
trimmed = trim(s)
parts = split(trimmed, ", ")
print(parts)                  # ["Hello", "Qu World!"]

print(upper(parts[0]))        # HELLO

print(starts_with(trimmed, "Hello"))  # true

print("hello".substr(0, 2).replace("e", "i").flip().flip())
print("hi world".split(" ").join(", ") + "!")

("Hello", "Qu World!")
HELLO
true
hi
hi, world!

More string examples

Real text rarely arrives in the shape you want it: a filename needs a substring pulled out of it, a heading needs consistent case, a field read from a form needs its leading/trailing padding stripped before it is safe to compare. This block runs one string through several of those cleanups — slicing with mid/left/right, case conversion under all of its aliases (upper/lower/ucase/lcase/toupper/tolower), and trimming/padding — to show that they compose without any of them mutating the original:

s = "Hello, Qu World!"
print(mid(s, 7, 2))          # "Qu"

print(left(s, 5))            # "Hello"

print(right(s, 6))           # "World!"

print(reverse("abc"))        # "cba"

print(lower("SHOUT"))        # "shout"

print(ucase("shout"))        # "SHOUT"

print(lcase("SHOUT"))        # "shout"

print(toupper("mix"))        # "MIX"

print(tolower("MIX"))        # "mix"

print(capitalize("ada lovelace"))  # "Ada lovelace"

print(ltrim("   padded"))    # "padded"

print(rtrim("padded   ") + "|")   # "padded|"

print(pad_right("ab", 5, "."))    # "ab..."

print(compare("apple", "banana")) # -1

print(asc("A"))              # 65

Qu
Hello
World!
cba
shout
SHOUT
shout
MIX
mix
Ada lovelace
padded
padded|
ab...
-1
    ... 1 more lines

Searching for a marker and cutting the string around it — index_of/ last_index_of from the front and back, after/before/after_last/ before_last to grab one side of it directly:

path = "report_final_v2.txt"
print(ends_with(path, ".txt"))         # true

print(index_of(path, "_"))              # 6

print(last_index_of(path, "_"))         # 12

print(insert("helloworld", 5, ", "))    # "hello, world"

print(remove("hello, world", ", "))     # "helloworld"

line = "key: value"
print(after(line, ": "))                # "value"

print(before(line, ": "))               # "key"

full = "a/b/c.txt"
print(after_last(full, "/"))            # "c.txt"

print(before_last(full, "/"))           # "a/b"

true
6
12
hello, world
helloworld
value
key
c.txt
a/b

Breaking text apart into lines or characters, and the two ways of putting it back together:

text = "one\ntwo\nthree"
print(lines(text))                     # ("one", "two", "three")

print(chars("abc"))                    # ("a", "b", "c")

print(repeat_str("ab", 3))             # "ababab"

print(as_text([1, 2, 3]).join(", "))   # "1, 2, 3"

("one", "two", "three")
("a", "b", "c")
ababab
1, 2, 3

parse_as/scan pull values out of a fixed-shape line of text; format goes the other way, a number into a picture:

n = parse_as("hello world 12", "hello world %d")
print(n)                          # 12

reading = scan("temp = 98.6 F", "temp = %f %s")
print(reading)                    # (98.6, "F")

print(format(1234.5, "#,##0.0"))  # "1,234.5"

print(format(0.256, "0.0%"))      # "25.6%"

12
(98.6, "F")
1,234.5
25.6%

Case modes and pattern languages

replace and contains take two independent keywords. Both default to today's behaviour, so existing calls are unchanged.

case= is "sensitive" (default), "insensitive", or "preserve" — where the match is case-insensitive and the replacement inherits the case of what it replaced, letter by letter:

replace("the programme, the Programme, the PROGRAMME",
        "programme", "program", case="preserve")
# "the program, the Program, the PROGRAM"

Inheritance is per character, so PrograMme becomes PrograM. Letters past the end of the match follow its last letter (PROG → PROGRAMME); non-alphabetic characters consume no position, so a digit cannot shift the pattern (A1B → X1Y); and a character whose case mapping is not one-to-one passes through unchanged, so German ß stays ß rather than becoming SS and changing the string's length.

pattern= is "literal" (default), "wildcard", or "regex":

replace("axb a.b", "a.b", "Z")                     # "axb Z"   the dot is a dot

replace("axb a.b", "a.b", "Z", pattern="regex")    # "Z Z"

replace("a1 b2 c3", "?#", "X", pattern="wildcard") # "X X X"

Literal is the default because Word, str.replace, strrep and VB's Replace all are: someone replacing a.b should not have the dot silently mean any-character. "wildcard" is the same dialect like accepts — *, ?, #, [abc], [!abc] — because both use the same translation.

The two compose: replace(s, "prog*", "X", pattern="wildcard", case="preserve").

* is greedy and runs to the end of the string. replace("the programme here", "program*", "X", pattern="wildcard") gives "the X", not "the X here" — * means "any run of characters" and there is nothing to stop it. like behaves the same way, and making * lazy for replace alone would give Qu two wildcard dialects. Use ? per character, or a regex, when you need a bounded match.

An unknown case= or pattern= value is an error naming the valid ones, never a silent fallback to the default.

A non-match is an ordinary answer, because scanning a file where only some lines are headers is the normal case. When you expected the line to fit, must_match=true says which part of the shape was missing instead:

scan("12 goodbye world", "%d hello world", must_match=true)
# error: scan: `%d hello world` did not match `12 goodbye world`

#        -- expected ` hello world` after %d

A limit worth stating. Qu cannot tell you at parse time that a template is impossible, and it does not try. \d is genuinely ambiguous — a regex habit, or the start of a Windows path like C:\data — so an unrecognised escape is kept literally rather than rejected, and scan("C:\data\x 42", r"C:\data\x %d") works. The consequence is that a template with a typo in it is a template that simply does not match, and a bare none still means "did not match" without saying why. must_match= exists because that question is answerable at the point of use, where the input is in hand, and not before.

tail for the end of a string, grep for the lines of it that match a pattern — both borrowed from their command-line namesakes:

print(tail("abcdefgh", 3))    # "fgh"

log = "INFO start\nERROR disk full\nINFO retry\nERROR timeout"
print(grep(log, "ERROR"))     # ("ERROR disk full", "ERROR timeout")

fgh
("ERROR disk full", "ERROR timeout")

Sometimes the destination for a piece of text is a file rather than the terminal — a log line, a generated report, a config value computed at runtime. write_text(path, s) writes the whole string in one call and hands back the byte count written, so a caller can confirm nothing was truncated without a separate file-size check (to a scratch path here, not anywhere inside a project -- /tmp/ resolves to the system temporary directory on every platform, including Windows):

out_path = "/tmp/qu_scratch_note.txt"
bytes = write_text(out_path, "hello from Qu\n")
print(bytes)                  # 14

Notes written as Markdown often need to become HTML for a report or a web page, and HTML pasted from somewhere else sometimes needs to become plain Markdown so it can be edited by hand. md2html/html2md convert between the two formats for the common subset — headings, paragraphs, lists, code, links, and emphasis — without pulling in an external converter:

md = "# Title\n\nSome **bold** text."
html = md2html(md)
print(html)
print(html2md(html))

<h1>Title</h1>
<p>Some <strong>bold</strong> text.</p>

# Title

Some **bold** text.

Bitwise & Number-Base Conversion

Value has no separate integer type — everything is f64 — so all of these read each argument as an integer via a strict integer check (rejecting non-integral input rather than silently truncating it), do the operation as i64, and hand back a Num. These are deliberately plain builtins, not &/|-family operators: and/or already mean logical and/or in Qu, so |/& are a clear parse error pointing here instead.

Qu also accepts 0xFF-style hex literals directly in source; hex2dec/ bin2dec are for runtime string-to-number conversion (e.g. values read from a file or built at runtime). The block below runs each bitwise, logical, and base-conversion function once so their outputs can be checked at a glance — 12 and 10 chosen because their bit patterns (1100 and 1010) make the AND/OR/XOR results easy to verify by hand:

flags = bitand(12, 10)          # 8   -- bits common to both

print(flags)
print(bitor(12, 10))            # 14

print(bitxor(12, 10))           # 6

print(bitcmp(0))                # -1

print(bitshift(1, 4))           # 16  -- left shift

print(bitshift(16, -2))         # 4   -- right shift

print(xor(true, false))         # true

print(nand(true, true))         # false

print(nor(false, false))        # true

print(hex2dec("FF"))            # 255

print(dec2hex(255))             # "FF"

print(bin2dec("1010"))          # 10

print(dec2bin(10))              # "1010"

8
14
6
-1
16
4
true
false
true
255
FF
10
1010

Collections (arrays & lists)

remove/insert/append return a NEW list/vector rather than mutating in place — Qu values are immutable by convention everywhere else.

contains/indexof compare elements via structural equality (values_equal), which does handle Str. The ==/!= operators themselves are narrower today: they fall back to numeric coercion for anything that isn't two Vecs or two same-type EnumVals, so "a" == "b" currently errors rather than returning false — a pre-existing gap, not a documentation omission. Prefer contains/indexof (or starts_with/ends_with/replace for substring checks) over == when comparing strings.

The functions below are the everyday toolkit for a numeric vector once it has been collected: sort it, get a de-duplicated set of its values, or find the order that WOULD sort it (argsort) without disturbing the original — useful when a second vector needs to be reordered in step with the first:

xs = [3, 1, 4, 1, 5, 9, 2, 6]
print(unique(xs))          # [1, 2, 3, 4, 5, 6, 9]

print(sort(xs))            # [1, 1, 2, 3, 4, 5, 6, 9]

print(argsort(xs))         # permutation of indices, ascending

print(sort(xs, true))      # descending

[1, 2, 3, 4, 5, 6, 9]
[1, 1, 2, 3, 4, 5, 6, 9]
[1, 3, 6, 0, 2, 4, 7, 5]
[9, 6, 5, 4, 3, 2, 1, 1]

Overloads: sort

Picked by the TYPE of the first argument, not a flag: a List in which every element is a Str sorts as text and comes back as a List; anything else is read as a numeric Vec and sorted as numbers, coming back as a Vec — a different return type as well as a different comparison, which matters the moment the result is chained into something that expects one or the other:

words = ["banana", "apple", "cherry"]
print(sort(words))            # ("apple", "banana", "cherry") -- a List, lexicographic

nums = [3, 1, 4, 1, 5]
print(sort(nums))             # [1, 1, 3, 4, 5] -- a Vec, numeric

print(type(sort(words)))      # "list"

print(type(sort(nums)))       # "vector"

("apple", "banana", "cherry")
[1, 1, 3, 4, 5]
list
vector

contains/indexof for membership, cumsum for a running total, and numel for the element count:

ys = [3, 1, 4, 1, 5]
print(contains(ys, 4))     # true

print(indexof(ys, 4))      # 2

print(cumsum(ys))          # [3, 4, 8, 9, 14]

print(numel(ys))           # 5

true
2
[3, 4, 8, 9, 14]
5

Enums

The enum Name ... end declaration is a small, purely symbolic enum type shipped 2026-08-24: named, validated constants, explicitly not a Rust/Swift-style tagged union with per-variant payloads (Qu has no static type system yet). Variants are reached via ordinary dot-access on the declared type (Season.Spring), and two EnumVals compare equal only when both their type and variant name match.

A declared enum's variants can always be named directly (Season.Spring), but a function that needs to iterate every possible value — filling a dropdown, generating a test matrix, printing a legend — needs a way to ask the type itself what its variants are. That's what enum_values is for:

enum Season
    Spring, Summer, Autumn, Winter
end

seasons = enum_values(Season)
for i = 0 to length(seasons) - 1
    print(seasons[i])
end for

Spring
Summer
Autumn
Winter

Data Frames / Tables

A Table (constructed via table(...)/DataFrame(...)) is Qu's DataFrame primitive — see engine/crates/qu-interp/src/table.rs for the underlying column-oriented representation (Column::Num/Column::Str). A numeric column of a table is read with df.colname (returns a plain Vec); a text column has no vector-of-strings Qu value to become yet, so it can only be used inside table operations (filter/sort_by/group_by_agg).

read_csv/write_csv also produce/consume Table values, but are documented in File I/O since they are fundamentally file operations — see that chapter's CSV section.

A Table is where several parallel columns of data live together as one value — the shape almost every real dataset actually arrives in. The example below builds one from three columns (two numeric, one broadcast string), asks it its own shape, filters it down to the rows that satisfy a condition, narrows to a subset of columns, and finally runs describe for a quick statistical summary of every numeric column at once:

df = DataFrame(x=[1, 2, 3, 4, 5], y=[10, 20, 30, 40, 50], label="sample")
print(nrow(df))            # 5

print(ncol(df))             # 3

tall = filter(df, df.x > 2)
xy = select(tall, "x", "y")
print(xy)
print(describe(df))

5
3
x   y
-  --
3  30
4  40
5  50
stat          x          y
-----  --------  ---------
count         5          5
mean          3         30
std    1.581139  15.811388
min           1         10
25%           2         20
    ... 3 more lines

df.nrows / df.ncols — property-style row/column count

df.nrows and df.ncols read as plain (no-parens) properties, returning exactly what nrow(df)/ncol(df) compute — pure sugar, same values. A real column literally named nrows/ncols always takes priority: df.col column access is tried first, so the property is only a fallback for the (overwhelmingly common) case where no such column exists.

df = DataFrame(x=[1, 2, 3], y=[4, 5, 6])
print(df.nrows)             # 3, same as nrow(df)

print(df.ncols)             # 2, same as ncol(df)

3
2

Writing a table the way the data arrives

table(x = ..., y = ...) wants the columns. Data usually arrives as rows — a header and then a line per measurement — and giving it to the column-wise form means transposing it by hand first, which is both tedious and a place to make a mistake nobody will catch.

So table also takes one string:

runs = table("
    channel, baseline, treated
    1,       0.412,    0.240
    2,       0.508,    0.301
    3,       0.377,    0.219
")
print(runs)
print(mean(runs.baseline))

channel  baseline  treated
-------  --------  -------
      1     0.412     0.24
      2     0.508    0.301
      3     0.377    0.219
0.432333

Every cell is trimmed and blank lines are ignored. That is what lets the columns line up in the source without the padding reaching the table — it matters more than it looks, because a text column would otherwise carry the spaces and runs.name == "steel" would quietly be false.

A column is numeric if every cell in it parses as a number, and text otherwise; the decision is per column, not per cell, so one stray n/a turns that whole column into text rather than silently becoming a zero.

sep= for a different delimiter, which is what makes a table drawn with pipes work:

alloys = table("
    name  | density | modulus
    steel | 7.85    | 200
    alu   | 2.70    | 69
", sep = "|")
print(alloys)

name   density  modulus
-----  -------  -------
steel     7.85      200
alu        2.7       69

and headers = false when the text is bare rows, in which case the columns are named col1, col2, and so on.

A row with the wrong number of fields is an error, not a padded row:

table: a row has 1 field, the header has 2

Silently filling the gap would make a typo look like data, which is the one failure this form has to avoid.

For CSV that lives in a *file*, use read_csv — same parsing, and it takes decimal= as well for comma-decimal locales. This form is for the table you are writing down here, in the program.

Value Constructors

The names num, bool, str, vec, mat, complex, cvec, cmat, signal, mask, table, model, list, record, nothing, enum_val, and enum_type all appear together around line 14795 of lib.rs, but on inspection that block is not part of call_builtin's dispatch at all — it is json_to_value, a private helper used only by the load(...) builtin to reconstruct a Value from the "type" tag written into a saved-value JSON file by save(...). None of num/bool/vec/mat/complex/cvec/ cmat/mask/model/list/record/nothing/enum_val/enum_type exist as callable, user-facing builtins anywhere in call_builtin — there is no vec(...)/mat(...)/complex(...) explicit-construction family; those values are built with literals ([1, 2, 3], 3 + 4j, {a = 1}) or with the domain-specific constructors documented in the other stdlib chapters (zeros, linspace, randn, ...).

Three of the sixteen names ARE genuine, independently-implemented callable builtins, documented in full above/elsewhere and unrelated to the json_to_value block:

• str(x) — see the Strings section above.
• signal(data, Fs=1]) / Signal(data, [Fs=1]) — sampled-signal constructor; see [Signal Processing & Filters. Fs is optional and defaults to 1.0 Hz when omitted — signal(data) is exactly signal(data, 1.0).
• table(name=values, ...) / DataFrame(...) — see Data Frames above.

Type Conversion

• cast(value, tag) — value is any Qu value; tag is a Str naming the target kind, using the same closed tag vocabulary a typed function parameter's : tag annotation uses (num, bool, str, vec, mat, complex, cvec, cmat, signal, mask, table, model, list, record, image, timer, file, worker, mutex, semaphore, none, plus any) — explicit conversion between value kinds, targeted by name. Not to be confused with x as vector(3) (Expr::As) — that's an unrelated shape *contract* check on an already-typed value, not a type conversion. x.cast(tag) also works, via the same generic recv.method(args) == method(recv, args) sugar every free function gets automatically. Returns a value of the kind named by tag. Only a deliberately scoped set of (source, target) pairings is wired up — anything else is a clear named error, not a silent no-op:

A conversion is most often needed right after reading raw text (every CSV cell, every parse_as non-numeric field, every value pulled from JSON arrives as a Str until something converts it) or right before writing numbers back out as text. The example below converts a tuple of numeric strings into a real Vec, does the reverse, and shows the .cast(...) method-chain spelling working identically to the free-function form:

  n = cast(("1", "2.5", "-3"), "num")
  print(n)                               # [1, 2.5, -3]

  s = cast([1, 2.5, -3], "str")
  print(s)                               # ("1", "2.5", "-3")

  b = "42".cast("num")
  print(b)                               # 42, via method-chain sugar

[1, 2.5, -3]
("1", "2.5", "-3")
42

Data Structures

Four opaque handle types (§ data structures pass, 2026-09-01), following the same Arc-wrapped shared-handle convention as timer/mutex/channel elsewhere in this codebase: cloning one of these into a variable, a function argument, or a spawn env snapshot shares the SAME live structure, not an independent copy.

fifo(capacity) — bounded circular FIFO buffer

A plain first-in-first-out buffer of values, distinct from the unrelated queue() (a queue of *deferred jobs* for a worker pool — see Concurrency — which never stores a plain value at all).

Full-buffer behavior: .push on an already-full fifo evicts the OLDEST element to make room — real ring-buffer/circular-queue semantics — rather than rejecting the new value. This is the deliberate choice: Qu already has real reject/back-pressure tools elsewhere (semaphore's acquire/release, or channel's unbounded queue), so a fixed-size "keep only the most recent N" buffer is the more broadly useful shape for a bounded container to have, and .is_full() lets a script detect an impending eviction if it needs to react first.

A fifo is the right container whenever the newest N readings matter more than the complete history — a rolling window of the last few sensor samples, a small undo buffer, a moving-average source. The example below fills a 3-slot buffer past capacity, watches the oldest value get evicted, and reads the rest back out:

f = fifo(3)
f.push(1)
f.push(2)
f.push(3)
f.push(4)          # evicts 1 -- buffer is now [2, 3, 4]

print(peek(f))       # 2 -- oldest element, still there

print(f.pop())      # 2

print(len(f))        # 2

2
2
2

double_buffer(initial) — front/back double buffering

The standard real-time/embedded/graphics pattern: .write(v) only ever touches the BACK buffer; .read() only ever returns the FRONT buffer; .swap() atomically exchanges the two. The entire reason this exists (rather than a plain mutex(initial)) is that a reader must never observe a write that hasn't been swapped in yet.

This is the pattern for a value a writer updates continuously while a reader must only ever see complete, consistent frames — a sensor-fusion result, a render target, a shared configuration snapshot. The example below writes a new value, shows it is NOT visible yet, then swaps and shows that it is:

b = double_buffer(1)
b.write(2)
print(b.read())     # 1 -- the write above is not visible yet

b.swap()
print(b.read())     # 2 -- now it is

1
2

linked_list() — double-ended list

A double-ended list of arbitrary values with O(1) push/pop at both ends. Implemented as a VecDeque-backed deque internally, not a traditional chain of individually heap-allocated nodes: Qu has no way for a script to hold a reference into the middle of a list (the one scenario a real node chain's O(1) arbitrary-position splice would ever pay for), so a VecDeque gives the identical O(1) front/back complexity with far better cache locality and no extra per-element allocation — the more honest, useful choice for how this is actually called from Qu script code.

Reach for a linked_list when values need to be added or removed from EITHER end at constant cost — a sliding window, a work queue processed from the front while new jobs arrive at the back, an undo/redo stack pair. The example below builds a small list from both ends, then drains it from both ends too:

l = linked_list()
l.push_back(1)
l.push_back(2)
l.push_front(0)
print(l.to_vec())   # (0, 1, 2)

print(pop_front(l)) # 0 -- removes from the front

print(pop_back(l))  # 2 -- removes from the back

print(l.to_vec())   # (1) -- what's left

(0, 1, 2)
0
2
(1)

graph([directed=false]) — nodes, edges, and Dijkstra's algorithm

A real node+edge graph, not a chart. Node ids are normalized the same way dict's keys are (string or number, canonicalized so 1 and 1.0 name the same node) — .neighbors always hands back string ids regardless of what kind of value was originally passed in.

Dijkstra (over a plain unweighted BFS) was chosen specifically because edges carry a real optional weight= — a weighted-shortest-path algorithm is the one that actually exercises that part of the data model. The first example below builds a small weighted graph and asks for the cheapest route between two nodes:

g = graph()
g.add_edge("A", "B", weight=4)
g.add_edge("A", "C", weight=1)
g.add_edge("C", "B", weight=2)
g.add_edge("B", "D", weight=5)
g.add_edge("C", "D", weight=8)
print(g.shortest_path("A", "D"))   # 8, via A -> C -> B -> D (1 + 2 + 5)

8

add_node on its own for an isolated node, has_edge to ask whether two nodes are joined, neighbors to list what one node connects to:

h = graph()
add_node(h, "X")          # an isolated node, no edges yet

h.add_edge("X", "Y")
print(has_edge(h, "X", "Y"))   # true

print(has_edge(h, "X", "Z"))   # false -- Z isn't even a node

print(neighbors(h, "X"))       # ("Y")

true
false
("Y")

More functions

input is where a neural-network pipeline starts — you reach for it when building a sequential model layer by layer with |> instead of hand-rolling weight matrices. input(3) alone just records the dimension and an empty layer list; piping it through dense(...) stages (documented in Statistics & ML) grows that list one layer at a time, each new record replacing the running out_dim with the layer's own output size:

spec = input(3)
print(spec.out_dim)          # 3 -- nothing built yet

print(spec.layers)           # () -- empty


net = input(3) |> dense(5, activation="relu") |> dense(1)
print(net.out_dim)            # 1 -- the last layer's output size

print(length(net.layers))     # 2 -- one record per dense() stage

3
()
1
2

and/or/mod as operators, and the print family/type/shape for inspecting a value:

i = 2
xs = [10, 20, 30]
print(i < length(xs) and xs[i] > 0)  # true -- short-circuiting guard

print(-1 mod 3)                       # 2 -- sign of the divisor

disp("disp, echo, writeline, and print are the same function")
echo("this line came from echo(...)")
writeline("and this one from writeline(...)")
print(type(3.5))                      # "number"

print(type("hi"))                     # "string"

print(shape([1, 2, 3]))               # [3, 1]

true
2
disp, echo, writeline, and print are the same function
this line came from echo(...)
and this one from writeline(...)
number
string
[3, 1]

all/any test a predicate over a collection; first/last/take slice it; distinct/flatten reshape it; fold/reduce/map/zip combine it with a named function:

function is_even(x)
    return x mod 2 == 0
end function

function add2(a, b)
    return a + b
end function

function double(x)
    return x * 2
end function

xs = [1, 2, 3, 4, 5]
print(all(xs, is_even))           # false

print(any(xs, is_even))           # true

print(first(xs))                 # 1

print(last(xs))                  # 5

print(take(xs, 3))                # (1, 2, 3)

print(distinct([1, 1, 2, 2, 3])) # (1, 2, 3) -- first-seen order

print(flatten([[1, 2], [3, 4]]))  # (1, 2, 3, 4)

print(fold(xs, add2, 0))          # 15 -- with an initial value

print(reduce(xs, add2))           # 15 -- without one

print(map(xs, double))            # (2, 4, 6, 8, 10) -- collection first

print(map(xs, (x) := x * 10))     # (10, 20, 30, 40, 50) -- or write it inline

print(map(xs, "double"))          # (2, 4, 6, 8, 10) -- the name as a string still works

print(xs.map(double))             # (2, 4, 6, 8, 10) -- and so the method form works

print(zip([1, 2, 3], ["a", "b", "c"]))  # ((1, "a"), (2, "b"), (3, "c"))

false
true
1
5
(1, 2, 3)
(1, 2, 3)
(1, 2, 3, 4)
15
15
(2, 4, 6, 8, 10)
(10, 20, 30, 40, 50)
(2, 4, 6, 8, 10)
(2, 4, 6, 8, 10)
((1, "a"), (2, "b"), (3, "c"))

dict/get/set/keys/values/items/has_key build and inspect a key-value store:

d = dict(["a", "b"], [1, 2])
d = set(d, "c", 3)
print(get(d, "b"))       # 2

print(keys(d))           # ("a", "b", "c")

print(values(d))         # (1, 2, 3)

print(items(d))          # (("a", 1), ("b", 2), ("c", 3))

print(has_key(d, "c"))   # true

print(has_key(d, "z"))   # false

2
("a", "b", "c")
(1, 2, 3)
(("a", 1), ("b", 2), ("c", 3))
true
false

at/index/insert_row on a table -- one row by position, setting a label column as the row index, and adding a new row:

df = DataFrame(id=[1, 2, 3], name=["alu", "steel", "brass"])
print(at(df, 1))                              # {id = 2, name = "steel"}

labeled = index(df, "name")
print(labeled)
grown = insert_row(df, 3, {id=4, name="glass"})
print(grown)

{id = 2, name = "steel"}
id  name 
--  -----
 1  alu  
 2  steel
 3  brass
id  name 
--  -----
 1  alu  
 2  steel
 3  brass
 4  glass

append_text adds to the end of a file without disturbing what is already there (a scratch path here, not anywhere inside a project):

path = "/tmp/qu_scratch_append.txt"
write_text(path, "first line\n")
append_text(path, "second line\n")
print(read_all_text(path))   # "first line\nsecond line\n"