package base:builtin

Source

nil is a predeclared identifier representing the zero value for a pointer, multi-pointer, enum, bit_set, slice, dynamic array, map, procedure, any, typeid, cstring, union, #soa array, #soa pointer, #relative type

An enum value specifying the target platform's operating system.

// Defined internally by the compiler

Odin_OS_Type :: enum int {
	Unknown,
	Windows,
	Darwin,
	Linux,
	Essence,
	FreeBSD,
	OpenBSD,
	NetBSD,
	Haiku,
	WASI,
	JS,
	Orca,
	Freestanding,
}

An enum value specifying the target platform's architecture.

// Defined internally by the compiler

Odin_Arch_Type :: enum int {
	Unknown,
	amd64,
	i386,
	arm32,
	arm64,
	wasm32,
	wasm64p32,
	riscv64,
}

An enum value specifying the target platform's endiannes.

// Defined internally by the compiler

Odin_Endian_Type :: enum int {
	Unknown,
	Little,
	Big,
}

An enum value specifying the "build-mode".

// Defined internally by the compiler

Odin_Build_Mode_Type :: enum int {
	Executable,
	Dynamic,
	Static,
	Object,
	Assembly,
	LLVM_IR,
}

An enum value specifying whether errors should be stylized in the default (MSVC-like) style or a UNIX (GCC-like) style.

Default = `path(1:2) Unix = `path:1:2:

An enum value specifying the selected subtarget type, only useful for Darwin targets.

// Defined internally by the compiler

Odin_Platform_Subtarget_Type :: enum int {
	Default,
	iOS,
}

A string specifying the current Windows subsystem, only useful on Windows targets.

A string specifying the current Odin compiler vendor.

A string specifying the current Odin version.

The path to the root Odin directory.

Equal to true if the -debug flag has been set during compilation, otherwise false.

Equal to true if the -disable-assert flag has been set during compilation, otherwise false.

Equal to true if the -default-to-nil-allocator flag has been set during compilation or whether the current target defaults to the "nil allocator", otherwise false.

Equal to true if the -default-to-panic-allocator flag has been set during compilation or whether the current target defaults to the "panic allocator", otherwise false.

Equal to true if the -no-crt flag has been set during compilation (disallowing the C Run-Time library), otherwise false.

Equal to true if the -no-entry-point flag has been set during compilation, otherwise false.

Equal to true if the -no-rtti flag has been set during compilation (disabling Odin's Run-Time Type Information, only allowed on freestanding targets), otherwise false.

Equal to the UNIX timestamp in nanoseconds at the time of the program's compilation.

byte is an alias for u8 and is equivalent to u8 in all ways. It is used as a convention to distinguish values from 8-bit unsigned integer values.

bool is the set of boolean values, false and true. This is distinct to b8. bool has a size of 1 byte (8 bits).

b8 is the set of boolean values, false and true. This is distinct to bool. b8 has a size of 1 byte (8 bits).

b16 is the set of boolean values, false and true. b16 has a size of 2 bytes (16 bits).

b32 is the set of boolean values, false and true. b32 has a size of 4 bytes (32 bits).

b64 is the set of boolean values, false and true. b64 has a size of 8 bytes (64 bits).

i8 is the set of all signed 8-bit integers. Range -128 through 127.

u8 is the set of all unsigned 8-bit integers. Range 0 through 255.

i16 is the set of all signed 16-bit integers with native endianness. Range -32768 through 32767.

u16 is the set of all unsigned 16-bit integers with native endianness. Range 0 through 65535.

i32 is the set of all signed 32-bit integers with native endianness. Range -2147483648 through 2147483647.

u32 is the set of all unsigned 32-bit integers with native endianness. Range 0 through 4294967295.

i64 is the set of all signed 64-bit integers with native endianness. Range -9223372036854775808 through 9223372036854775807.

u64 is the set of all unsigned 64-bit integers with native endianness. Range 0 through 18446744073709551615.

i128 is the set of all signed 128-bit integers with native endianness. Range -170141183460469231731687303715884105728 through 170141183460469231731687303715884105727.

u128 is the set of all unsigned 128-bit integers with native endianness. Range 0 through 340282366920938463463374607431768211455.

rune is the set of all Unicode code points. It is internally the same as i32 but distinct.

f16 is the set of all IEEE-754 16-bit floating-point numbers with native endianness.

f32 is the set of all IEEE-754 32-bit floating-point numbers with native endianness.

f64 is the set of all IEEE-754 64-bit floating-point numbers with native endianness.

complex32 is the set of all complex numbers with f16 real and imaginary parts

complex64 is the set of all complex numbers with f32 real and imaginary parts

complex128 is the set of all complex numbers with f64 real and imaginary parts

quaternion64 is the set of all complex numbers with f16 real and imaginary (i, j, & k) parts

quaternion128 is the set of all complex numbers with f32 real and imaginary (i, j, & k) parts

quaternion256 is the set of all complex numbers with f64 real and imaginary (i, j, & k) parts

int is a signed integer type that is at least 32 bits in size. It is a distinct type, however, and not an alias for say, i32.

uint is an unsigned integer type that is at least 32 bits in size. It is a distinct type, however, and not an alias for say, u32.

uintptr is an unsigned integer type that is large enough to hold the bit pattern of any pointer.

rawptr represents a pointer to an arbitrary type. It is equivalent to void * in C.

string is the set of all strings of 8-bit bytes, conventionally but not necessarily representing UTF-8 encoding text. A string may be empty but not nil. Elements of string type are immutable and indexable.

cstring is the set of all strings of 8-bit bytes terminated with a NUL (0) byte, conventionally but not necessarily representing UTF-8 encoding text. A cstring may be empty or nil. Elements of string type are immutable but not indexable.

typeid is a unique identifier for an Odin type at runtime. It can be mapped to relevant type information through type_info_of.

any can reference any data type at runtime. Internally it contains a pointer to the underlying data and its relevant typeid. This is a very useful construct in order to have a runtime type safe printing procedure.

Note: The any value is only valid for as long as the underlying data is still valid. Passing a literal to an any will allocate the literal in the current stack frame.

Note: It is highly recommend that you do not use this unless you know what you are doing. Its primary use is for printing procedures.

i16le is the set of all signed 16-bit integers with little endianness. Range -32768 through 32767.

u16le is the set of all unsigned 16-bit integers with little endianness. Range 0 through 65535.

i32le is the set of all signed 32-bit integers with little endianness. Range -2147483648 through 2147483647.

u32le is the set of all unsigned 32-bit integers with little endianness. Range 0 through 4294967295.

i64le is the set of all signed 64-bit integers with little endianness. Range -9223372036854775808 through 9223372036854775807.

u64le is the set of all unsigned 64-bit integers with little endianness. Range 0 through 18446744073709551615.

i128le is the set of all signed 128-bit integers with little endianness. Range -170141183460469231731687303715884105728 through 170141183460469231731687303715884105727.

u128le is the set of all unsigned 128-bit integers with little endianness. Range 0 through 340282366920938463463374607431768211455.

i16be is the set of all signed 16-bit integers with big endianness. Range -32768 through 32767.

u16be is the set of all unsigned 16-bit integers with big endianness. Range 0 through 65535.

i32be is the set of all signed 32-bit integers with big endianness. Range -2147483648 through 2147483647.

u32be is the set of all unsigned 32-bit integers with big endianness. Range 0 through 4294967295.

i64be is the set of all signed 64-bit integers with big endianness. Range -9223372036854775808 through 9223372036854775807.

u64be is the set of all unsigned 64-bit integers with big endianness. Range 0 through 18446744073709551615.

i128be is the set of all signed 128-bit integers with big endianness. Range -170141183460469231731687303715884105728 through 170141183460469231731687303715884105727.

u128be is the set of all unsigned 128-bit integers with big endianness. Range 0 through 340282366920938463463374607431768211455.

f16le is the set of all IEEE-754 16-bit floating-point numbers with little endianness.

f32le is the set of all IEEE-754 32-bit floating-point numbers with little endianness.

f64le is the set of all IEEE-754 64-bit floating-point numbers with little endianness.

f16be is the set of all IEEE-754 16-bit floating-point numbers with big endianness.

f32be is the set of all IEEE-754 32-bit floating-point numbers with big endianness.

f64be is the set of all IEEE-754 64-bit floating-point numbers with big endianness.

The len built-in procedure returns the length of v according to its type:

Array: the number of elements in v.
Pointer to (any) array: the number of elements in `v^` (even if `v` is `nil`).
Slice, dynamic array, or map: the number of elements in `v`; if `v` is `nil`, `len(v)` is zero.
String: the number of bytes in `v`
Enumerated array: the number elements in v.`
Enum type: the number of enumeration fields.
#soa array: the number of elements in `v`; if `v` is `nil`, `len(v)` is zero.
#simd vector: the number of elements in `v`.

For some arguments, such as a string literal or a simple array expression, the result can be constant.

The cap built-in procedure returns the length of v according to its type:

Array: the number of elements in v.
Pointer to (any) array: the number of elements in `v^` (even if `v` is `nil`).
Dynamic array, or map: the reserved number of elements in `v`; if `v` is `nil`, `len(v)` is zero.
Enum type: equal to `max(Enum)-min(Enum)+1`.
#soa dynamic array: the reserved number of elements in `v`; if `v` is `nil`, `len(v)` is zero.

For some arguments, such as a string literal or a simple array expression, the result can be constant.

size_of takes an expression or type, and returns the size in bytes of the type of the expression if it was hypothetically instantiated as a variable. The size does not include any memory possibly referenced by a value. For instance, if a slice was given, size_of returns the size of the internal slice data structure and not the size of the memory referenced by the slice. For a struct, the size includes any padding introduced by field alignment (if not specified with #packed. Other types follow similar rules. The return value of size_of is a compile time known integer constant.

align_of takes an expression or type, and returns the alignment in bytes of the type of the expression if it was hypothetically instantiated as a variable v. It is the largest value m such that the address of v is always 0 mod m.

offset_of returns the offset in bytes with the struct of the field.

e.g. offset_of(t.f), where t is an instance of the type T

e.g. offset_of(T, f), where T can be the type instead of a variable

e.g. offset_of(T, "f"), where T can be the type instead of a variable

type_of returns the type of a given expression

type_info_of returns the runtime type information from a given typeid.

typeid_of returns the associated runtime known typeid of the specified type.

real returns the real part of a complex or quaternion number v. The return value will be the floating-point type corresponding to the type of v.

imag returns the i-imaginary part of a complex or quaternion number v. The return value will be the floating-point type corresponding to the type of v.

jmag returns the j-imaginary part of a quaternion number v. The return value will be the floating-point type corresponding to the type of v.

kmag returns the k-imaginary part of a quaternion number v. The return value will be the floating-point type corresponding to the type of v.

conj returns the complex conjugate of a complex or quaternion number v. This negates the imaginary component(s) whilst keeping the real component untouched.

expand_values will return multiple values corresponding to the multiple fields of the passed struct or the multiple elements of a passed fixed length array.

min returns the minimum value of passed arguments of all the same type. If one argument is passed and it is an enum or numeric type, then min returns the minimum value of the enum type's fields or its minimum / most negative numeric value respectively.

max returns the maximum value of passed arguments of all the same type. If one argument is passed and it is an enum or numeric type, then max returns the maximum value of the enum type's fields or its maximum numeric value respectively.

abs returns the absolute value of passed argument. If the argument is a complex or quaternion, this is equivalent to real(conj(value) * value).

clamp returns a value v clamped between minimum and maximum. This is calculated as the following: minimum if v < minimum else maximum if v > maximum else v.

See: https://odin-lang.org/docs/overview/#soa_zip-and-soa_unzip

See: https://odin-lang.org/docs/overview/#soa_zip-and-soa_unzip

raw_data returns the underlying data of a built-in data type as a multi-pointer.

raw_data([]$E)         -> [^]E    // slices
raw_data([dynamic]$E)  -> [^]E    // dynamic arrays
raw_data(^[$N]$E)      -> [^]E    // fixed array and enumerated arrays 
raw_data(^#simd[$N]$E) -> [^]E    // simd vectors 
raw_data(string)       -> [^]byte // string

Recovers the containing/parent struct from a pointer to one of its fields. Works by "walking back" to the struct's starting address using the offset between the field and the struct.

Inputs:
ptr: Pointer to the field of a container struct T: The type of the container struct field_name: The name of the field in the T struct

Returns:
A pointer to the container struct based on a pointer to a field in it

package container_of
import "base:runtime"

Node :: struct {
	value: int,
	prev:  ^Node,
	next:  ^Node,
}

main :: proc() {
	node: Node
	field_ptr := &node.next
	container_struct_ptr: ^Node = runtime.container_of(field_ptr, Node, "next")
	assert(container_struct_ptr == &node)
	assert(uintptr(field_ptr) - uintptr(container_struct_ptr) == size_of(node.value) + size_of(node.prev))
}

^Node

copy_slice is a built-in procedure that copies elements from a source slice src to a destination slice dst. The source and destination may overlap. Copy returns the number of elements copied, which will be the minimum of len(src) and len(dst).

Prefer the procedure group copy.

copy_from_string is a built-in procedure that copies elements from a source string src to a destination slice dst. The source and destination may overlap. Copy returns the number of elements copied, which will be the minimum of len(src) and len(dst).

Prefer the procedure group copy.

unordered_remove removed the element at the specified index. It does so by replacing the current end value with the old value, and reducing the length of the dynamic array by 1.

Note: This is an O(1) operation. Note: If you want the elements to remain in their order, use ordered_remove. Note: If the index is out of bounds, this procedure will panic.

ordered_remove removed the element at the specified index whilst keeping the order of the other elements.

Note: This is an O(N) operation. Note: If the elements do not have to remain in their order, prefer unordered_remove. Note: If the index is out of bounds, this procedure will panic.

remove_range removes a range of elements specified by the range lo and hi, whilst keeping the order of the other elements.

Note: This is an O(N) operation. Note: If the range is out of bounds, this procedure will panic.

pop will remove and return the end value of dynamic array array and reduces the length of array by 1.

Note: If the dynamic array has no elements (len(array) == 0), this procedure will panic.

pop_safe trys to remove and return the end value of dynamic array array and reduces the length of array by 1. If the operation is not possible, it will return false.

pop_front will remove and return the first value of dynamic array array and reduces the length of array by 1.

Note: If the dynamic array as no elements (len(array) == 0), this procedure will panic.

pop_front_safe trys to return and remove the first value of dynamic array array and reduces the length of array by 1. If the operation is not possible, it will return false.

delete_string will try to free the underlying data of the passed string, with the given allocator if the allocator supports this operation.

Note: Prefer the procedure group delete.

delete_cstring will try to free the underlying data of the passed string, with the given allocator if the allocator supports this operation.

Note: Prefer the procedure group delete.

delete_dynamic_array will try to free the underlying data of the passed dynamic array, with the given allocator if the allocator supports this operation.

Note: Prefer the procedure group delete.

delete_slice will try to free the underlying data of the passed sliced, with the given allocator if the allocator supports this operation.

Note: Prefer the procedure group delete.

delete_map will try to free the underlying data of the passed map, with the given allocator if the allocator supports this operation.

Note: Prefer the procedure group delete.

The new built-in procedure allocates memory. The first argument is a type, not a value, and the value return is a pointer to a newly allocated value of that type using the specified allocator, default is context.allocator

make_slice allocates and initializes a slice. Like new, the first argument is a type, not a value. Unlike new, make's return value is the same as the type of its argument, not a pointer to it.

Note: Prefer using the procedure group make.

make_dynamic_array allocates and initializes a dynamic array. Like new, the first argument is a type, not a value. Unlike new, make's return value is the same as the type of its argument, not a pointer to it.

Note: Prefer using the procedure group make.

make_dynamic_array_len allocates and initializes a dynamic array. Like new, the first argument is a type, not a value. Unlike new, make's return value is the same as the type of its argument, not a pointer to it.

Note: Prefer using the procedure group make.

make_dynamic_array_len_cap allocates and initializes a dynamic array. Like new, the first argument is a type, not a value. Unlike new, make's return value is the same as the type of its argument, not a pointer to it.

Note: Prefer using the procedure group make.

make_map initializes a map with an allocator. Like new, the first argument is a type, not a value. Unlike new, make's return value is the same as the type of its argument, not a pointer to it.

Note: Prefer using the procedure group make.

make_map_cap initializes a map with an allocator and allocates space using capacity. Like new, the first argument is a type, not a value. Unlike new, make's return value is the same as the type of its argument, not a pointer to it.

Note: Prefer using the procedure group make.

make_multi_pointer allocates and initializes a multi-pointer. Like new, the first argument is a type, not a value. Unlike new, make's return value is the same as the type of its argument, not a pointer to it.

This is "similar" to doing raw_data(make([]E, len, allocator)).

Note: Prefer using the procedure group make.

clear_map will set the length of a passed map to 0

Note: Prefer the procedure group clear

reserve_map will try to reserve memory of a passed map to the requested element count (setting the cap).

Note: Prefer the procedure group reserve

Shrinks the capacity of a map down to the current length.

Note: Prefer the procedure group shrink

The delete_key built-in procedure deletes the element with the specified key (m[key]) from the map. If m is nil, or there is no such element, this procedure is a no-op

The append_string built-in procedure appends multiple strings to the end of a [dynamic]u8 like type

clear_dynamic_array will set the length of a passed dynamic array to 0

Note: Prefer the procedure group clear.

resize_dynamic_array will try to resize memory of a passed dynamic array or map to the requested element count (setting the len, and possibly cap).

Note: Prefer the procedure group resize

Explicitly inserts a key and value into a map m, the same as map_insert, but the return values differ. prev_key will return the previous pointer of a key if it exists, check found_previous if was previously found value_ptr will return the pointer of the memory where the insertion happens, and nil if the map failed to resize found_previous will be true a previous key was found

unordered_remove_soa removed the element at the specified index. It does so by replacing the current end value with the old value, and reducing the length of the dynamic array by 1.

Note: This is an O(1) operation. Note: If you the elements to remain in their order, use ordered_remove_soa. Note: If the index is out of bounds, this procedure will panic.

ordered_remove_soa removed the element at the specified index whilst keeping the order of the other elements.

Note: This is an O(N) operation. Note: If you the elements do not have to remain in their order, prefer unordered_remove_soa. Note: If the index is out of bounds, this procedure will panic.

copy is a built-in procedure that copies elements from a source slice/string src to a destination slice dst. The source and destination may overlap. Copy returns the number of elements copied, which will be the minimum of len(src) and len(dst).

clear will set the length of a passed dynamic array or map to 0

reserve will try to reserve memory of a passed dynamic array or map to the requested element count (setting the cap).

resize will try to resize memory of a passed dynamic array to the requested element count (setting the len, and possibly cap).

Shrinks the capacity of a dynamic array or map down to the current length, or the given capacity.

free will try to free the passed pointer, with the given allocator if the allocator supports this operation.

free_all will try to free/reset all of the memory of the given allocator if the allocator supports this operation.

delete will try to free the underlying data of the passed built-in data structure (string, cstring, dynamic array, slice, or map), with the given allocator if the allocator supports this operation.

Note: Prefer delete over the specific delete_* procedures where possible.

make built-in procedure allocates and initializes a value of type slice, dynamic array, map, or multi-pointer (only).

Similar to new, the first argument is a type, not a value. Unlike new, make's return type is the same as the type of its argument, not a pointer to it. Make uses the specified allocator, default is context.allocator.

The append built-in procedure appends elements to the end of a dynamic array

The append_soa built-in procedure appends elements to the end of an #soa dynamic array