Standard library reference#

Meta: alphabetical reference, not a tutorial. Each entry: signature, one-line description, one tiny example. Group by module/receiver. Cross-link to the conceptual page that introduces the API.

This page is generated from the builtin registry in pkg/dang (stdlib.go, stdlib_random.go, stdlib_regexp.go, assert.go). Each entry's signature, one-line description, and example come straight from the builtin's definition, so the reference can't drift from the implementation — to change an entry, edit the builtin's .Doc(...) or .Example(...). Each example is a live REPL: press Run to evaluate it (and then keep typing — state carries across entries, just like the CLI).

Top-level functions#

assert(message: String = null, &block: a): Null

asserts that the block evaluates to a truthy value, raising an AssertionError otherwise

assert { 1 + 1 == 2 }

loop(&block: a): r

repeatedly calls the block until it exits via break

loop { break 42 }

print(value: a): Null

prints a value to stdout

print("hello, world")

toString(value: b): String!

converts a value to a string, returning strings as-is and serializing other values to JSON

toString(42)

print and assert return null — there is no Void type; treat the result as null. The JSON/YAML/TOML codec namespaces (encode/decode) are covered in depth on JSON, YAML, and TOML.

`String!` methods#

See Strings. Note: .length/.isEmpty are list-only — there is no String length/isEmpty builtin.

Regex methods take a Regexp! pattern. Backtick template strings auto-coerce to the Regexp scalar, so a pattern is usually written as `\d+` (Go regexp/syntax).

`.center`	centers the string within the specified width by padding with spaces on both sides
`.contains`	checks if the string contains the specified substring
`.containsMatch`	reports whether the string contains a match for the regexp
`.fromBase64`	decodes a standard (padded) base64 string, returning the decoded bytes as a string
`.hasPrefix`	checks if the string starts with the specified prefix
`.hasSuffix`	checks if the string ends with the specified suffix
`.match`	returns the first match for the pattern, or null
`.matchAll`	returns all non-overlapping matches for the pattern
`.padLeft`	pads the string with spaces on the left to reach the specified width
`.padRight`	pads the string with spaces on the right to reach the specified width
`.replace`	replaces occurrences of old with new in the string. The count parameter controls how many replacements to make: -1 (default) replaces all occurrences, 1 replaces only the first, etc.
`.replaceMatches`	replaces matches of pattern with `with`; supports $0/$1/$name backref expansion
`.rewriteMatches`	replaces matches of pattern using the block to compute each replacement
`.split`	splits a string by separator
`.splitMatches`	splits the string by matches of pattern
`.toBase64`	encodes the string's bytes as a standard (padded) base64 string
`.toLower`	converts a string to lowercase
`.toUpper`	converts a string to uppercase
`.trim`	removes all leading and trailing characters in cutset from the string
`.trimLeft`	removes all leading characters in cutset from the string
`.trimPrefix`	removes the specified prefix from the string if present
`.trimRight`	removes all trailing characters in cutset from the string
`.trimSpace`	removes all leading and trailing whitespace from the string
`.trimSuffix`	removes the specified suffix from the string if present

.center(width: Int!): String!

centers the string within the specified width by padding with spaces on both sides

"hi".center(6) + "|"

.contains(substring: String!): Boolean!

checks if the string contains the specified substring

"dang".contains("an")

.containsMatch(pattern: Regexp!): Boolean!

reports whether the string contains a match for the regexp

"abc123".containsMatch(`\d+`)

.fromBase64: String!

decodes a standard (padded) base64 string, returning the decoded bytes as a string

"aGVsbG8=".fromBase64

.hasPrefix(prefix: String!): Boolean!

checks if the string starts with the specified prefix

"dang".hasPrefix("da")

.hasSuffix(suffix: String!): Boolean!

checks if the string ends with the specified suffix

"dang".hasSuffix("ng")

.match(pattern: Regexp!): Match

returns the first match for the pattern, or null

"x42y".match(`\d+`)

.matchAll(pattern: Regexp!): [Match!]!

returns all non-overlapping matches for the pattern

"a1 b22 c333".matchAll(`\d+`)

.padLeft(width: Int!): String!

pads the string with spaces on the left to reach the specified width

"hi".padLeft(5) + "|"

.padRight(width: Int!): String!

pads the string with spaces on the right to reach the specified width

"hi".padRight(5) + "|"

.replace(old: String!, new: String!, count: Int = -1): String!

replaces occurrences of old with new in the string. The count parameter controls how many replacements to make: -1 (default) replaces all occurrences, 1 replaces only the first, etc.

"a-b-c".replace("-", "_")

.replaceMatches(pattern: Regexp!, with: String!, count: Int = -1): String!

replaces matches of pattern with `with`; supports $0/$1/$name backref expansion

"a1b2".replaceMatches(`\d`, "#")

.rewriteMatches(pattern: Regexp!, count: Int = -1, &block(match: Match!): String!): String!

replaces matches of pattern using the block to compute each replacement

"hello world".rewriteMatches(`\w+`) { m => m.string.toUpper }

.split(separator: String!, limit: Int = 0): [String!]!

splits a string by separator

"a,b,c".split(",")

.splitMatches(pattern: Regexp!, limit: Int = 0): [String!]!

splits the string by matches of pattern

"a1b22c".splitMatches(`\d+`)

.toBase64: String!

encodes the string's bytes as a standard (padded) base64 string

"hello".toBase64

.toLower: String!

converts a string to lowercase

"HELLO".toLower

.toUpper: String!

converts a string to uppercase

"hello".toUpper

.trim(cutset: String!): String!

removes all leading and trailing characters in cutset from the string

"__hi__".trim("_")

.trimLeft(cutset: String!): String!

removes all leading characters in cutset from the string

"__hi__".trimLeft("_")

.trimPrefix(prefix: String!): String!

removes the specified prefix from the string if present

"v1.2.3".trimPrefix("v")

.trimRight(cutset: String!): String!

removes all trailing characters in cutset from the string

"__hi__".trimRight("_")

.trimSpace: String!

removes all leading and trailing whitespace from the string

"  hi  ".trimSpace

.trimSuffix(suffix: String!): String!

removes the specified suffix from the string if present

"report.txt".trimSuffix(".txt")

`[T]!` methods#

See Collections. List methods are registered on the List module, so signatures show the element type as the type variable a (and block result types as b). Block params are named item/index — and acc for .reduce.

`.all`	returns true if all elements satisfy the predicate
`.any`	returns true if at least one element satisfies the predicate
`.contains`	checks if the list contains the specified element
`.dropFirst`	returns a new list with the first count elements removed (default 1)
`.dropLast`	returns a new list with the last count elements removed (default 1)
`.dropWhile`	returns a new list with leading elements removed for which the predicate returns true, stopping at the first false
`.each`	iterates over each element in the list, calling the block for each element
`.filter`	returns a new list containing only elements for which the predicate returns true
`.find`	returns the first element for which the predicate returns true, or null if none match
`.isEmpty`	returns true if the list contains no elements
`.join`	joins the list elements into a string, converting each element to string and separating them with the given delimiter
`.length`	returns the number of elements in the list
`.map`	returns a new list with each element transformed by the given function
`.reduce`	reduces the list to a single value using an accumulator function
`.reject`	returns a new list excluding elements for which the predicate returns true
`.takeFirst`	returns a new list containing only the first count elements (default 1)
`.takeLast`	returns a new list containing only the last count elements (default 1)
`.takeWhile`	returns a new list containing leading elements for which the predicate returns true, stopping at the first false
`.uniq`	returns a new list with duplicate elements removed, preserving first occurrence order

.all(&block(item: a): Boolean!): Boolean!

returns true if all elements satisfy the predicate

[1, 2, 3].all { x => x > 0 }

.any(&block(item: a): Boolean!): Boolean!

returns true if at least one element satisfies the predicate

[1, 2, 3].any { x => x > 2 }

.contains(element: a): Boolean!

checks if the list contains the specified element

[1, 2, 3].contains(2)

.dropFirst(count: Int = 1): [a]!

returns a new list with the first count elements removed (default 1)

[1, 2, 3, 4].dropFirst(2)

.dropLast(count: Int = 1): [a]!

returns a new list with the last count elements removed (default 1)

[1, 2, 3, 4].dropLast(2)

.dropWhile(&block(item: a): Boolean!): [a]!

returns a new list with leading elements removed for which the predicate returns true, stopping at the first false

[1, 2, 3, 1].dropWhile { x => x < 3 }

.each(&block(item: a, index: Int!): b): [a]!

iterates over each element in the list, calling the block for each element

[1, 2, 3].each { x => print(x) }

.filter(&block(item: a): Boolean!): [a]!

returns a new list containing only elements for which the predicate returns true

[1, 2, 3, 4].filter { x => x > 2 }

.find(&block(item: a): Boolean!): a

returns the first element for which the predicate returns true, or null if none match

[1, 2, 3].find { x => x > 1 }

.isEmpty: Boolean!

returns true if the list contains no elements

[1, 2, 3].isEmpty

.join(separator: String!): String!

joins the list elements into a string, converting each element to string and separating them with the given delimiter

["a", "b", "c"].join("-")

.length: Int!

returns the number of elements in the list

[1, 2, 3].length

.map(&block(item: a, index: Int!): b): [b]!

returns a new list with each element transformed by the given function

[1, 2, 3].map { x => x * 2 }

.reduce(initial: b, &block(acc: b, item: a): b): b

reduces the list to a single value using an accumulator function

[1, 2, 3, 4].reduce(0) { acc, x => acc + x }

.reject(&block(item: a): Boolean!): [a]!

returns a new list excluding elements for which the predicate returns true

[1, 2, 3, 4].reject { x => x > 2 }

.takeFirst(count: Int = 1): [a]!

returns a new list containing only the first count elements (default 1)

[1, 2, 3, 4].takeFirst(2)

.takeLast(count: Int = 1): [a]!

returns a new list containing only the last count elements (default 1)

[1, 2, 3, 4].takeLast(2)

.takeWhile(&block(item: a): Boolean!): [a]!

returns a new list containing leading elements for which the predicate returns true, stopping at the first false

[1, 2, 3, 1].takeWhile { x => x < 3 }

.uniq: [a]!

returns a new list with duplicate elements removed, preserving first occurrence order

[1, 1, 2, 3, 3].uniq

`Map[a]!` methods#

See Collections. Map methods are registered on the Map module. Keys are always String!; the value type shows as the type variable a (and block result types as b). Block params are named key/value.

`.each`	iterates over each entry in insertion order, calling the block with the key and value
`.get`	returns the value for the given key, or null if the key is absent
`.has`	returns true if the map contains the given key
`.isEmpty`	returns true if the map contains no entries
`.keys`	returns the map's keys in insertion order
`.length`	returns the number of entries in the map
`.map`	returns a new map with each value transformed by the block; keys are preserved
`.merge`	returns a new map combining this map with another; values from the other map win on key conflicts
`.values`	returns the map's values in insertion order
`.with`	returns a new map with the given key set to the given value
`.without`	returns a new map with the given key removed

.each(&block(key: String!, value: a): b): Map[a]!

iterates over each entry in insertion order, calling the block with the key and value

["a": 1, "b": 2].each { key, value => print(`${key}=${value}`) }

.get(key: String!): a

returns the value for the given key, or null if the key is absent

["a": 1, "b": 2].get("a")

.has(key: String!): Boolean!

returns true if the map contains the given key

["a": 1, "b": 2].has("a")

.isEmpty: Boolean!

returns true if the map contains no entries

[:].isEmpty

.keys: [String!]!

returns the map's keys in insertion order

["a": 1, "b": 2].keys

.length: Int!

returns the number of entries in the map

["a": 1, "b": 2].length

.map(&block(key: String!, value: a): b): Map[b]!

returns a new map with each value transformed by the block; keys are preserved

["a": 1, "b": 2].map { key, value => value * 2 }

.merge(other: Map[a]!): Map[a]!

returns a new map combining this map with another; values from the other map win on key conflicts

["a": 1, "b": 2].merge(["b": 20, "c": 3])

.values: [a]!

returns the map's values in insertion order

["a": 1, "b": 2].values

.with(key: String!, value: a): Map[a]!

returns a new map with the given key set to the given value

["a": 1].with("b", 2)

.without(key: String!): Map[a]!

returns a new map with the given key removed

["a": 1, "b": 2].without("a")

`JSON` module#

See JSON, YAML, and TOML. JSON/YAML/TOML are codec namespaces: encode serializes any value to a string, decode materializes a string against the expected type (:: T). The names double as scalar types (:: JSON) owned by Dang, and merge with a same-named schema scalar such as Dagger's JSON.

JSON.decode(data: String!): a

parses a JSON string into an opaque value that is materialized by an expected type

JSON.decode("[1, 2, 3]") :: [Int!]!

JSON.encode(value: a): String!

serializes a value to a JSON string

JSON.encode([1, 2, 3])

`YAML` module#

YAML.decode(data: String!): a

parses a YAML string into an opaque value that is materialized by an expected type

YAML.decode("[1, 2, 3]") :: [Int!]!

YAML.encode(value: a): String!

serializes a value to a YAML string

YAML.encode([1, 2, 3])

`TOML` module#

TOML.encode requires a table (record) at the top level.

TOML.decode(data: String!): a

parses a TOML string into an opaque value that is materialized by an expected type

type Settings { count: Int! }
TOML.decode("count = 3") :: Settings

TOML.encode(value: a): String!

serializes a value to a TOML string

TOML.encode({{enabled: true, count: 3}})

`Random` module#

Random.float: Float!

generates a random float between 0.0 (inclusive) and 1.0 (exclusive)

Random.float

Random.int(min: Int!, max: Int!): Int!

generates a random integer between min (inclusive) and max (exclusive)

Random.int(1, 7)

Random.string: String!

generates a cryptographically random base32 string with at least 128 bits of entropy

Random.string

`UUID` module#

UUID.v4: String!

generates a random UUID v4 string

UUID.v4

UUID.v7: String!

generates a time-ordered UUID v7 string

UUID.v7

Error types#

See Errors: try, catch, raise. These are prelude types rather than builtins, so they aren't part of the generated lists above.

Error — interface with message: String!
BasicError — concrete type behind raise "msg"; implements Error, has message: String!
AssertionError — raised by a failed assert (carries the offending expression and sub-values)

Meta: when generics land properly, update [T]! method signatures to show the actual type parameter rather than handwaving T/U.

Standard library reference#

Top-level functions#

String! methods#

[T]! methods#

Map[a]! methods#

JSON module#

YAML module#

TOML module#

Random module#

UUID module#