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) { a }: Null
asserts that the block evaluates to a truthy value, raising an AssertionError otherwise
assert { 1 + 1 == 2 }fromJSON(data: String!): a
parses JSON into an opaque value that is materialized by an expected type
fromJSON("[1, 2, 3]") :: [Int!]!fromYAML(data: String!): a
parses YAML into an opaque value that is materialized by an expected type
fromYAML("[a, b, c]") :: [String!]!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. toJSON/fromJSON/fromYAML are covered in depth on JSON and YAML.
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 |
.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 |
.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+`).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) { 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+`).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("_").trimSuffix(suffix: String!): String!
removes the specified suffix from the string if present
"report.txt".trimSuffix(".txt")
Match object
Returned by .match (and as elements of .matchAll); a missing match is null. See Strings.
.capture(name: String!): String
named capture; null if no such group or the group did not match
"555-1212".match(`(?P<area>\d{3})-(\d{4})`).capture("area").captures: [String!]!
positional captures, with `captures[0]` corresponding to $1
"42-99".match(`(\d+)-(\d+)`).captures
[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 |
.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 { item => Boolean! }: Boolean!
returns true if all elements satisfy the predicate
[1, 2, 3].all { x => x > 0 }.any { item => 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 { item => 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 { item, index => b }: [a]!
iterates over each element in the list, calling the block for each element
[1, 2, 3].each { x => print(x) }.filter { item => Boolean! }: [a]!
returns a new list containing only elements for which the predicate returns true
[1, 2, 3, 4].filter { x => x > 2 }.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("-").map { item, index => b }: [b]!
returns a new list with each element transformed by the given function
[1, 2, 3].map { x => x * 2 }.reduce(initial: b) { acc, item => b }: b
reduces the list to a single value using an accumulator function
[1, 2, 3, 4].reduce(0) { acc, x => acc + x }.reject { item => 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 { item => 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
Random module
Random.float: Float!
generates a random float between 0.0 (inclusive) and 1.0 (exclusive)
Random.floatRandom.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
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 withpub message: String!BasicError— concrete type behindraise "msg"; implementsError, haspub message: String!AssertionError— raised by a failedassert(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.