Builtins

The compiler offers builtin constants and functions. Some are only available on certain targets. All builtins use the $$ name prefix.

Builtin constants

These constants are generated by the compiler and can safely be used by the user.

$$BENCHMARK_NAMES

An array of names of the benchmark functions as a String[].

The program must be run in benchmark mode (e.g. via the c3c benchmark shell command) for this array to be non-empty.

$$BENCHMARK_FNS

An array of addresses to the benchmark functions as a void*[].

The program must be run in benchmark mode (e.g. via the c3c benchmark command) for this array to be non-empty.

$$DATE

The current date (year, month, day) as a String.

In contrast, to retreive the time of day (hours, minutes, seconds) try using $$TIME.

$$FILE

The current source code file name (not including any of the path) as a String.

$$FILEPATH

The full (“absolute”) path to the current source code file as a String.

$$FUNC

The current function name as a String.

This will return "<GLOBAL>" if used on the global level (outside any function), such as via String global_func_name = $$FUNC;, because there is no corresponding function name in that case.

$$FUNCTION

The current function as an identifier, as if its name were written in place of $$FUNCTION.

As such, it may be queried for associated info (e.g. $$FUNCTION.nameof, $typeof($$FUNCTION), etc) or assigned to a function pointer and later called, etc. Thus, more info than just a String function name may be accessed this way, in contrast to $$FUNC.

$$LINE

The current line as an integer.

$$LINE_RAW

Usually the same as $$LINE, but in case of a macro inclusion it returns the line in the macro rather than the line where the macro was included.

$$MODULE

The current module name as a String.

Keep in mind that there can be multiple modules per file in C3 if multiple module sections are used. In contrast, for a per file name try $$FILE or $$FILEPATH.

$$TIME

The current time of day (hours, minutes, seconds) as a String.

In contrast, to retreive the calendar day (year, month, day) try using $$DATE..

Compiler builtin functions

The $$ namespace defines compiler builtin functions. These special functions are not guaranteed to exist on all platforms, and are ways to wrap compiler implemented, optimized implementations of some particular functionality. They are mainly intended for standard library internal use. The standard library has macros that wrap these builtins, so they should normally not be used on their own.

$$trap

Emits a trap instruction.

$$unreachable

Inserts an “unreachable” annotation.

$$stacktrace

Returns the current “callstack” reference if available. OS and compiler dependent.

$$volatile_store

Takes a variable and a value and stores the value as a volatile store.

$$volatile_load

Takes a variable and returns the value using a volatile load.

$$memcpy

Builtin memcpy instruction.

$$memset

Builtin memset instruction.

$$prefetch

Prefetch a memory location.

$$sysclock

Access to the cycle counter register (or similar low latency clock) on supported architectures (e.g. RDTSC on x86), otherwise $$sysclock will yield 0.

$$syscall

Makes a syscall according to the platform convention on platforms where it is supported.

Math functions

Functions $$ceil, $$trunc, $$sin, $$cos, $$log, $$log2, $$log10, $$rint, $$round $$sqrt, $$roundeven, $$floor, $$sqrt, $$pow, $$exp, $$fma and $$fabs, $$copysign, $$round, $$nearbyint.

Can be applied to float vectors or numbers. Returns the same type.

Functions $$min, $$abs and $$max can be applied to any integer or float number or vector.

Function $$pow_int takes a floating point value or vector and an integer and returns the same type as the first parameter.

Saturated addition, subtraction and left shift for integers and integer vectors: $$sat_add, $$sat_shl, $$sat_sub.

Bit functions

$$fshl and $$fshr

Funnel shift left and right, takes either two integers or two integer vectors.

$$ctz, $$clz, $$bitreverse, $$bswap, $$popcount

Bit functions work on an integer or an integer vector.

Vector functions

$$reduce_add, $$reduce_mul, $$reduce_and, $$reduce_or, $$reduce_xor work on integer vectors.

$$reduce_fadd, $$reduce_fmul works on float vectors.

$$reduce_max, $$reduce_min works on any vector.

$$reverse reverses the values in any vector.

$$shufflevector rearranges the values of two vectors using a fixed mask into a resulting vector.