Codegen Functions Reference

This document describes the functions defined in src/main/resources/codegen_funcs.txt. Each entry lists the function's signature (arguments), its return value, and a short description. These functions form the generic API that the code generator maps to language-specific implementations (C++, Java, JavaScript, Perl, Python, Rust, Swift).

Type Notation

The metadata file uses the following type notations:

Notation Meaning
<char> A single character
<int> An integer (also <int16>, <int32>, <int64>, <uint>)
<long> A long integer
<byte> A single byte
<double> A double-precision floating point value
<bool> A boolean value
<string> A string
<char*> A string slice / immutable string
<regex> A regular expression
<codepoint_t> A Unicode code point
<optional> An optional (nullable) value
<any> / any Any type
[type] A list of type (e.g. [double], [any])
{type} A map with element type type (e.g. {string|double})
«type» A tuple (e.g. «int|int|int»)
≤any≥ An enum type
... Varargs (variable-length argument list)
? Optional/nullable variable used for output/reference parameter (value is set by the function)
* A reference/pointer to the type
void No return value

Function variants use suffixes such as @N (an overload taking N arguments) or a type qualifier like tohex<char> (a specialization for a particular argument type).

Program & Runtime

Function Return Description
build_header(<string>) <string> Build a source header from the given title.
pass() void No-op statement (used by Python for empty blocks).
exit(<int>) void Exit the program with the given return code.
exception_msg(<any>) <string> Get the message text for an exception/error value.
global(any) void Declare a variable in global scope inside a function (Python global).
todo() void Placeholder for unimplemented code.
clock_millis() <int> Current wall-clock time in milliseconds.

Command-Line Arguments

Function Return Description
program_args_equal(<int>) <bool> True if exactly N command-line arguments were supplied.
program_args_not_equal(<int>) <bool> True if the number of arguments is not N.
program_args_equal_or_more(<int>) <bool> True if at least N arguments were supplied.
program_args_less_than(<int>) <bool> True if fewer than N arguments were supplied.
program_arg(<int>) <string> Get the program argument at position [1..ARGC].

Constants & Math

Function Return Description
pi() <double> The mathematical constant π.
e() <double> The mathematical constant e (Euler's number).
sgn(<any>) <int> Sign of a value (-1, 0, +1).
abs(<int>) <int> Absolute value of an integer.
fabs(<double>) <double> Absolute value of a double.
ceil(<double>) <double> Round up toward positive infinity.
floor(<double>) <double> Round down toward negative infinity.
round(<double>) <double> Round to the nearest integer.
trunc(<double>) <double> Truncate the fractional part.
max(<int>, <int>) <int> Larger of two integers.
min(<int>, <int>) <int> Smaller of two integers.
fmax(<double>, <double>) <double> Larger of two doubles.
fmin(<double>, <double>) <double> Smaller of two doubles.
pow(<double>, <double>) <double> x raised to the power y.
sqrt(<double>) <double> Square root.
exp(<double>) <double> e raised to the power x.
log(<double>) <double> Natural logarithm.
log10(<double>) <double> Base-10 logarithm.

Trigonometric / Hyperbolic

Function Return Description
sin(<double>) <double> Sine.
cos(<double>) <double> Cosine.
tan(<double>) <double> Tangent.
asin(<double>) <double> Arc sine.
acos(<double>) <double> Arc cosine.
atan(<double>) <double> Arc tangent.
atan2(<double>, <double>) <double> Arc tangent of y/x using the signs of both.
sinh(<double>) <double> Hyperbolic sine.
cosh(<double>) <double> Hyperbolic cosine.
tanh(<double>) <double> Hyperbolic tangent.
asinh(<double>) <double> Inverse hyperbolic sine.
acosh(<double>) <double> Inverse hyperbolic cosine.
atanh(<double>) <double> Inverse hyperbolic tangent.

Random Numbers

Function Return Description
srand() void Seed the random number generator.
irandom(<int>) <int> Random integer in the range [0, x).
random() <double> Random double in the range [0, 1).

Operators & Predicates

Function Return Description
ternary(<any>, <any>, <any>) <any> Ternary conditional: cond ? a : b.
defined(any) <bool> True if the value is defined/non-null.
isfinite(<double>) <bool> True if the value is finite.
mask32(<any>) <int> Mask an integer to 32 bits.

Type Casts

Function Return Description
UInt8(<any>) <byte> Cast to an 8-bit unsigned integer (Swift/Rust).
Char(<any>) <char> Cast to a character (Swift/Rust).
Int16(<any>) <int16> Cast to a 16-bit integer (Rust/Swift).
Int32(<any>) <int32> Cast to a 32-bit integer (Rust/Swift).
Int64(<any>) <int64> Cast to a 64-bit integer (Rust/Swift).
Short(<any>) <int> Cast to a short integer (Rust/Swift).
Int(<any>) <int> Cast to a native int (Rust/Swift).
Long(<any>) <long> Cast to a long integer (Rust/Swift).
USize(<any>) <uint> Cast to a usize (Rust only).
SubscriptInt(<any>) <int> Cast to the subscript-index integer type (Rust/Swift).
Double(<any>) <double> Cast to a double (Rust/Swift).
String(<any>) <string> Cast a string literal to a string (Rust/Swift).

Number ↔ String Conversion

Function Return Description
tohex(<any>) <string> Convert an integer to a hexadecimal string.
tohex<char>(<char>) <string> Convert a character to a hexadecimal string.
tobase(<int>, <int>) <string> Convert an integer to a string in a given base (2–16).
frombase(<string>, <int>) <long> Parse a string as an integer in a given base (2–16).
stoi(<string>) <int32> Parse a string as a 32-bit int (throws on bad format).
stol(<string>) <int64> Parse a string as a 64-bit int (throws on bad format).
stod(<string>) <double> Parse a string as a double (throws on bad format).
stoi_w_default(<string>, <int>) <int> Parse a string as int, returning a default on failure.
stol_w_default(<string>, <long>) <long> Parse a string as long, returning a default on failure.
stod_w_default(<string>, <double>) <double> Parse a string as double, returning a default on failure.
optionalToString(<optional>) <string> Convert an optional value to a string.
boolToString(<any>) <string> Convert a boolean to a string.
regexToString(<regex>) <string> Convert a regular expression to a string.

String Formatting

Function Return Description
simple_message_format(<string>, ...) <string> Format a message using a simple format string plus varargs.
sprintf(<string>, ...) <string> Printf-style formatting to a returned string.
printf(<string>, ...) <string> Printf-style formatting written to standard output.
padalign(<string>, <int>, <any>, <char>, <string>, <string>) <string> Pad/align a string to a width with alignment, pad char, prefix, and front-prefix.
padalign@5(<string>, <int>, <any>, <char>, <string>) <string> padalign variant without the front-prefix argument.
padalign@4(<string>, <int>, <any>, <char>) <string> padalign variant without prefix arguments.
padalign@3(<string>, <int>, <any>) <string> padalign variant using default pad character.
padalign@2(<string>, <int>) <string> padalign variant using default alignment and pad char.

The align argument for padalign is a PadAlignType enum constant.

String Inspection & Extraction

Function Return Description
strlen(<string>) <int> Number of code points in a string.
char_at(<string>, <int>) <char> Character at the given index.
codepoint_at(<string>, <int>) <codepoint_t> Unicode code point at the given index.
substr(<string>, <int>, <int>) <string> Substring from start to end.
substrByLen(<string>, <int>, <int>) <string> Substring from start with a given length.
prefix(<string>, <int>) <string> First count characters.
right_tail(<string>, <int>) <string> Substring from position to the end.
suffix(<string>, <int>) <string> Last count characters.
find(<string>, <string>) <int> Index of the first occurrence of a substring (STRING_NOT_FOUND if absent).
find<string><codepoint_t>(<string>, <codepoint_t>) <int> Index of the first occurrence of a code point.
rfind(<string>, <string>) <int> Index of the last occurrence of a substring (STRING_NOT_FOUND if absent).
rfind<string><codepoint_t>(<string>, <codepoint_t>) <int> Index of the last occurrence of a code point.
compareto(<string>, <string>) <int> Compare strings: <0, 0, or >0.
isempty(<string>) <bool> True if the string is empty.
isblank(<string>) <bool> True if the string is empty or only whitespace.

String Transformation

Function Return Description
ltrim(<string>) <string> Remove leading whitespace.
rtrim(<string>) <string> Remove trailing whitespace.
trim(<string>) <string> Remove leading and trailing whitespace.
repeat(<char>, <int>) <string> A string of a character repeated count times.
repeatString(<string>, <int>) <string> A string repeated count times.
join(<string>, [any]) <string> Join a list with a separator.
toupper<char>(<char>) <char> Upper-case a character.
toupper<codepoint_t>(<codepoint_t>) <codepoint_t> Upper-case a code point.
toupper<string>(<string>) <string> Upper-case a string.
tolower<char>(<char>) <char> Lower-case a character.
tolower<codepoint_t>(<codepoint_t>) <codepoint_t> Lower-case a code point.
tolower<string>(<string>) <string> Lower-case a string.

Regular Expressions

Function Return Description
match(<string>, <regex>) <bool> True if the regex matches anywhere in the string.
findFirst(<string>, <regex>) [string] First match as an array of groups (group 0 = whole match).
findAll(<string>, <regex>) [string] All matches as an array.
replaceFirst(<string>, <regex>, <string>) <string> Replace the first regex match with a replacement.
replaceAll(<string>, <regex>, <string>) <string> Replace all regex matches with a replacement.
split(<string>, <regex>) [string] Split a string by a regex.

Character Classification & Conversion

Function Return Description
ord(<char>) <codepoint_t> Code point of a character.
ord<char*>(<char*>) <codepoint_t> Code point of the first char of a string slice.
ord<string>(<string>) <codepoint_t> Code point of the first char of a string.
chr(<codepoint_t>) <char> Character for a code point.
format_char(<codepoint_t>) <any> Format a code point for display.
isalpha<char> / isalpha<codepoint_t> <bool> True if alphabetic.
isalnum<char> / isalnum<codepoint_t> <bool> True if alphanumeric.
isctrl<char> / isctrl<codepoint_t> <bool> True if a control character.
isdigit<char> / isdigit<codepoint_t> <bool> True if a decimal digit.
ispunct<char> / ispunct<codepoint_t> <bool> True if punctuation.
isspace<char> / isspace<codepoint_t> <bool> True if whitespace.
isupper<char> / isupper<codepoint_t> <bool> True if upper-case.
islower<char> / islower<codepoint_t> <bool> True if lower-case.

Each classification function has two variants: one taking a <char> and one taking a <codepoint_t>.

Console & Stream I/O

Input

Function Return Description
getbyte(<getbyte_t>?) <bool> Read one byte from STDIN into the output parameter; false at EOF/error.
getbyte@2(<getbyte_t>?, <ifilehandleBinary>) <bool> Read one byte from a binary file handle; false at EOF/error.
getbyteNoCheck(<getbyte_t>?, <ifilehandleBinary>) void Read one byte without an EOF/error check.
getcodepoint(<codepoint_t>?) <bool> Read one code point from STDIN; false at EOF/error.
getcodepoint@2(<codepoint_t>?, <ifilehandle>) <bool> Read one code point from a file handle; false at EOF/error.
getline(<string>) <bool> Read a line from STDIN into the output parameter; false at EOF/error.
getline@2(<string>, <ifilehandle>) <bool> Read a line from a file handle; false at EOF/error.
prompt(<string>) <string> Print a prompt and read a line of input.

The ? parameters are set by reference. See the source file for the required loop idioms per language (Python/Swift/Rust differ).

Output

Function Return Description
putbyte(<byte>) void Write one byte to STDOUT.
putbyte@2(<byte>, <ofilehandleBinary>) void Write one byte to a binary file handle.
putchar(<char>) void Write one character to STDOUT.
putchar@2(<char>, <ofilehandle>) void Write one character to a file handle.
putcodepoint(<codepoint_t>) void Write one code point to STDOUT.
putcodepoint@2(<codepoint_t>, <ofilehandle>) void Write one code point to a file handle.
print@2(<string>, <ofilehandle>) void Write a string to a file handle.
printLine@2(<string>, <ofilehandle>) void Write a string plus newline to a file handle.
flush(<any>) void Flush a stream.

Stream Modes

Function Return Description
binmode(<any>) void Put a file handle into binary mode (Perl).
utf8mode(<any>) void Put a file handle into UTF-8 mode.
imbue(<filehandle>) void Imbue a file handle with the UTF-8 locale (C++).

Files

Function Return Description
createFile(<string>) <bool> Create a file with the given name.
openFileRead(<string>) <ifstream>? Open a text file for reading.
openFileRead@2(<ifilehandle>, <string>) <bool> Open a text file for reading into an existing handle.
openBinaryFileRead(<string>) <ifstream> Open a binary file for reading.
openBinaryFileRead@2(<ifilehandle>, <string>) <bool> Open a binary file for reading into an existing handle.
openFileWrite(<string>) <ifstream> Open a text file for writing.
openFileWrite@2(<ifilehandle>, <string>) <bool> Open a text file for writing into an existing handle.
openBinaryFileWrite(<string>) <ifstream> Open a binary file for writing.
openBinaryFileWrite@2(<ifilehandle>, <string>) <bool> Open a binary file for writing into an existing handle.
isGood(<filehandle>) <bool> True if the file handle is in a good state.
isBad(<filehandle>) <bool> True if the file handle is in an error state.
close<ifilehandle>(<ifilehandle>) void Close a text input file handle.
close<ifilehandleBinary>(<ifilehandleBinary>) void Close a binary input file handle.
close<ofilehandle>(<ofilehandle>) void Close a text output file handle.
close<ofilehandleBinary>(<ofilehandleBinary>) void Close a binary output file handle.
filesize(<any>) <uint> Size of an open file handle.
filesize<string>(<string>) <uint> Size of a file given its path (string).
filesize<char*>(<char*>) <uint> Size of a file given its path (string slice).
fseek(<any>, <long>, <int>) <uint> Seek within a file (offset, whence).
ftell(<any>) <uint> Current position within a file.
fread([any], <uint>, <ifilehandleBinary>) <uint> Read count elements into a buffer; returns the number read.
fwrite([any], <uint>, <ofilehandleBinary>) <uint> Write count elements from a buffer; returns the number written.

Byte Buffers

Function Return Description
buffer_get(<byte_buffer>, <uint>) <byte> Get the byte at an index in a byte buffer.
buffer_set(<byte_buffer>, <uint>, <byte>) <byte> Set the byte at an index in a byte buffer.

Lists

Function Return Description
list@0() [any] Create an empty list.
list(...) [any] Create a list from the given elements.
isEmptyList([any]) <bool> True if the list is empty.
listContains([any], <any>) <bool> True if the list contains a value.
push([any], any) void Append a value to the end of the list.
pop([any]) any Remove and return the last element.
peek([any]) any Return the last element without removing it.
shift([any]) any Remove and return the first element.
unshift([any], any) void Insert a value at the front of the list.
peek_front([any]) any Return the first element without removing it.
front([any]) any Return the first element.
back([any]) any Return the last element.
clearList([any]) void Remove all elements from the list.
sort([any]) [any] Sort a list (lexicographic).
sortNumeric([any]) [any] Sort a list numerically.
listToString([any]) <string> String representation of a list.

Each of the above has a corresponding reference/pointer variant (suffix [any]*) for languages that operate on list references.

Maps

Function Return Description
map@0() {any} Create an empty map.
map(...) {any} Create a map from the given key/value elements.
isEmptyMap({any}) <bool> True if the map is empty.
mapContains({any}, any) <bool> True if the map contains a key.
mapRemove({any}, any) void Remove a key from the map.
clearMap({any}) void Remove all entries from the map.
mapToString({any}) <string> String representation of a map.
sortedKeys({any}) [...] Map keys sorted lexicographically.
sortedNumericKeys({any}) [...] Map keys sorted numerically.

Each of the above has a corresponding reference/pointer variant (suffix {any}*).

Tuples

Function Return Description
tuple(...) «any» Create a tuple from the given elements.
tupleRef(...) «any» Create a tuple reference.
tupleToString(«any») <string> String representation of a tuple.

tupleToString also has a reference variant (suffix «any»*).

Enums

Function Return Description
enumToString(≤any≥) <string> Name of an enum constant.
enumToInt@1(≤any≥) <int> Integer value of an enum constant.
enumToInt@2(≤any≥, any) <int> Integer value of an enum constant, given the enum class as the second argument.
intToEnum(<enumname>, <int>) ≤any≥ Convert an integer to an enum constant of the named enum class.

Copying & References

Function Return Description
deepCopy<string>(<string>) <string> Deep copy of a string.
deepCopy[any]([any]) [any] Deep copy of a list (and pointer variant [any]*).
shallowCopy[any]([any]) [any] Shallow copy of a list (and pointer variant [any]*).
deepCopy{any}({any}) {any} Deep copy of a map (and pointer variant {any}*).
shallowCopy{any}({any}) {any} Shallow copy of a map (and pointer variant {any}*).
deepCopy«any»(«any») «any» Deep copy of a tuple (and pointer variant «any»*).
shallowCopy«any»(«any») «any» Shallow copy of a tuple (and pointer variant «any»*).
toOwned(<char*>) <string> Convert a string slice to an owned string.
toSlice(<string>) <char*> Get a string slice view of a string.
ref(any) any Take a reference to a value.
mutref(any) any Take a mutable reference to a value.
deref(any) any Dereference a reference.

Optionals & Result Unwrapping

Function Return Description
unwrap(any) any Unwrap an optional value.
unwrapRust(any) any Unwrap a Rust Option/Result.
unwrapSwift(any) any Unwrap a Swift optional.
unwrapResult(any) any Unwrap a result value.

Atomics

Function Return Description
loadAtomic(<any>) <any> Atomically load a value.
storeAtomic(<any>, <any>) <any> Atomically store a value; returns the old value.
addAtomic(<any>, <any>) <any> Atomically add; returns the old value.
subAtomic(<any>, <any>) <any> Atomically subtract; returns the old value.
cmpAndSwapAtomic(<any>, <any>, <any>) <any> Atomic compare-and-swap (value, old, new); returns the old value.

Miscellaneous

Function Return Description
shared_ptr(≤any≥, ...) ≤any≥ Construct a shared_ptr<> (C++) wrapping a new instance; other languages pass through.

This reference was generated from src/main/resources/codegen_funcs.txt. For the exact per-language code templates (C++, Java, JavaScript, Perl, Python, Rust, Swift) and any required imports, consult that source file directly.

©2026 Richard Lesh. All rights reserved.

Codegen | CodgenIDE | Pure Programmer | Glowing Cat Software