package base:builtin

Source

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 "build-mode".

// Defined internally by the compiler
Odin_Build_Mode_Type :: enum int {
	Executable,
	Dynamic,
	Static,
	Object,
	Assembly,
	LLVM_IR,
}

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

Equal to true if the -debug 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 -disable-assert flag has been set during compilation, otherwise false.

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 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:

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.

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 selected subtarget type, only useful for Darwin targets.

// Defined internally by the compiler
Odin_Platform_Subtarget_Type :: enum int {
	Default,
	iPhone,
	iPhoneSimulator
	Android,
}

The path to the root Odin directory.

A string specifying the current Odin compiler vendor.

A string specifying the current Odin version.

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

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

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.

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).

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

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

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.

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

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

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

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

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

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

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

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

Represents an Objective-C block with a given procedure signature T

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

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.

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.

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.

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.

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.

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.

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.

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.

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

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

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

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

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.

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.

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

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

type_info_of returns the runtime type information from a given typeid.

type_of returns the type of a given expression

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

append_elem appends an element to the end of a dynamic array.

append_elem_string appends a string to the end of a dynamic array of bytes

Note: Prefer using the procedure group append.

append_elems appends args to the end of a dynamic array.

Note: Prefer using the procedure group append.

append_nothing appends an empty value to a dynamic array. It returns 1, nil if successful, and 0, err when it was not possible, whatever err happens to be.

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

Note: Prefer using the procedure group append.

Evaluates the condition and panics the program iff the condition is false. This uses the context.assertion_failure_procedure to assert.

This routine will be ignored when ODIN_DISABLE_ASSERT is true.

Evaluates the condition and panics the program iff the condition is false. This uses the default_assertion_contextless_failure_proc to assert.

This routine will be ignored when ODIN_DISABLE_ASSERT is true.

assign_at_elem assigns a value at a given index. If the requested index is smaller than the current size of the dynamic array, it will attempt to resize the a new length of index+1 and then assign as index.

assign_at_elem_string assigns a string at a given index. If the requested index is smaller than the current size of the dynamic array, it will attempt to resize the a new length of index+len(arg) and then assign as index.

assign_at_elems assigns a values at a given index. If the requested index is smaller than the current size of the dynamic array, it will attempt to resize the a new length of index+len(args) and then assign as index.

card returns the number of bits that are set in a bit_set—its cardinality

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

Note: Prefer the procedure group clear.

clear_map will set the length of a passed map to 0

Note: Prefer the procedure group clear

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_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.

copy_from_string16 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.

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.

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.

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

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.

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_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.

Evaluates the condition and panics the program iff the condition is false. This uses the context.assertion_failure_procedure to assert. This routine ignores ODIN_DISABLE_ASSERT, and will always execute.

Evaluates the condition and panics the program iff the condition is false. This uses the default_assertion_contextless_failure_proc to assert.

Initializes the global temporary allocator used as the default context.temp_allocator. This is ignored when NO_DEFAULT_TEMP_ALLOCATOR is true.

inject_at_elem injects an element in a dynamic array at a specified index and moves the previous elements after that index "across"

inject_at_elem_string injects a string into a dynamic array at a specified index and moves the previous elements after that index "across"

inject_at_elems injects multiple elements in a dynamic array at a specified index and moves the previous elements after that index "across"

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.

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.

Retrieves a pointer to the key and value for a possibly just inserted entry into the map.

If the key was not in the map m, an entry is inserted with the zero value and just_inserted will be true. Otherwise the existing entry is left untouched and pointers to its key and value are returned.

If the map has to grow in order to insert the entry and the allocation fails, err is set and returned.

If err is nil, key_ptr and value_ptr are valid pointers and will not be nil.

WARN: User modification of the key pointed at by key_ptr should only be done if the new key is equal to (in hash) the old key. If that is not the case you will corrupt the map.

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

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

non_zero_append_elem appends an element to the end of a dynamic array, without zeroing any reserved memory

Note: Prefer using the procedure group `non_zero_append

non_zero_append_elem_string appends a string to the end of a dynamic array of bytes, without zeroing any reserved memory

Note: Prefer using the procedure group non_zero_append.

non_zero_append_elems appends args to the end of a dynamic array, without zeroing any reserved memory

Note: Prefer using the procedure group `non_zero_append

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

When a memory resize allocation is required, the memory will be asked to not be zeroed (i.e. it calls non_zero_mem_resize).

Note: Prefer the procedure group non_zero_reserve.

non_zero_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).

When a memory resize allocation is required, the memory will be asked to not be zeroed (i.e. it calls non_zero_mem_resize).

Note: Prefer the procedure group non_zero_resize

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.

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.

Panics the program with a message. This uses the context.assertion_failure_procedure to panic.

Panics the program with a message to indicate something has yet to be implemented. This uses the default_assertion_contextless_failure_proc to assert.

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_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.

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.

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.

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

When a memory resize allocation is required, the memory will be asked to be zeroed (i.e. it calls mem_resize).

Note: Prefer the procedure group reserve.

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

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).

When a memory resize allocation is required, the memory will be asked to be zeroed (i.e. it calls mem_resize).

Note: Prefer the procedure group resize

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

Note: Prefer the procedure group shrink

Panics the program with a message to indicate something has yet to be implemented. This uses the context.assertion_failure_procedure to assert.

Panics the program with a message. This uses the default_assertion_contextless_failure_proc to assert.

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.

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.

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

assign_at assigns a value at a given index. If the requested index is smaller than the current size of the dynamic array, it will attempt to resize the a new length of index+size_needed and then assign as index.

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

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).

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.

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.

inject_at injects something into a dynamic array at a specified index and moves the previous elements after that index "across"

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.

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.