Overview

String and character literals

String literals are enclosed in double quotes and character literals in single quotes. Special characters are escaped with a backslash \.

"This is a string"
'A'
'\n' // newline character
"C:\\Windows\\notepad.exe"

Raw string literals are enclosed in single back ticks.

`C:\Windows\notepad.exe`

The length of a string can be found using the built-in len proc:

len("Foo")
len(some_string)

If the string passed to len is a compile-time constant, the value from len will be a compile-time constant.

greeting := """
	Hellope,
	  "World"!
	"""
assert(greeting == "Hellope,\n  \"World\"!")

path := ```
	C:\Windows\notepad.exe
	```
assert(path == `C:\Windows\notepad.exe`)

Numbers

Numerical literals are written similar to most other programming languages. A useful feature in Odin is that underscores are allowed for better readability: 1_000_000_000 (one billion). A number that contains a dot is a floating point literal: 1.0e9 (one billion). If a number literal is suffixed with i, it is an imaginary number literal: 2i (2 multiply the square root of -1). The suffixes j and k are the other two imaginary units of a quaternion: 1 + 2i + 3j + 4k.

Binary literals are prefixed with 0b, octal literals with 0o, and hexadecimal literals with 0x. A leading zero does not produce an octal constant (unlike C).

Hexadecimal float literals are prefixed with 0h and specify the exact bit pattern of an IEEE-754 floating point value. The number of hexadecimal digits determines how the bits are interpreted: 4 digits for f16, 8 digits for f32, and 16 digits for f64.

one_f16: f16 = 0h3c00
one_f32: f32 = 0h3f80_0000
one_f64: f64 = 0h3ff0_0000_0000_0000
inf:     f32 = 0h7f80_0000

In Odin, if a number constant can be represented by a type without precision loss, it will automatically convert to that type.

x: int = 1.0 // A float literal but it can be represented by an integer without precision loss

Constant literals are "untyped" which means that they can implicitly convert to a type.

x: int // `x` is typed as being of type `int`
x = 1 // `1` is an untyped integer literal which can implicitly convert to `int`

import statement

The following program imports the fmt and os packages from the core library collection.

package main

import "core:fmt"
import "core:os"

main :: proc() {
}

The core: prefix is used to state where the import is meant to look; this is called a library collection. If no prefix is present, the import will look relative to the current file.

A different import name can be used over the default package name:

import "core:fmt"
import foo "core:fmt" // reference a package by a different name

Exported names

All declarations in a package are public by default.

The private attribute can be applied to an entity to prevent it from being exported from a package.

@(private)
my_variable: int // cannot be accessed outside this package

You may also make an entity private to the file instead of the package.

@(private="file")
my_variable: int // cannot be accessed outside this file

@(private) is equivalent to @(private="package").

Authoring a package

A package is a directory of Odin code files, all of which have the same package declaration at the top, e.g. package main. Each .odin file must have the same package name. A directory cannot contain more than 1 package.

Organizing packages

Packages may be thematically organized by placing them in subdirectories of another package. For example: core:image/png and core:image/tga, as subdirectories of core:image. Nesting these packages is a helpful taxonomy. It does not imply a dependency: core:foo/bar does not need to import core:foo and reference anything from it.

for statement

Odin has only one loop statement, the for loop.

for i := 0; i < 10; i += 1 {
	fmt.println(i)
}

i := 0
for ; i < 10; {
	i += 1
}

i := 0
for i < 10 {
	i += 1
}

for {
}

for i := 0; i < 10; i += 1 {
	fmt.println(i)
}

for i in 0..<10 {
	fmt.println(i)
}
// or
for i in 0..=9 {
	fmt.println(i)
}

some_string := "Hello, 世界"
for character in some_string {
	fmt.println(character)
}

some_array := [3]int{1, 4, 9}
for value in some_array {
	fmt.println(value)
}

some_slice := []int{1, 4, 9}
for value in some_slice {
	fmt.println(value)
}

some_dynamic_array := [dynamic]int{1, 4, 9} // must be enabled with `#+feature dynamic-literals`
defer delete(some_dynamic_array)
for value in some_dynamic_array {
	fmt.println(value)
}

some_map := map[string]int{"A" = 1, "C" = 9, "B" = 4} // must be enabled with `#+feature dynamic-literals`
defer delete(some_map)
for key in some_map {
	fmt.println(key)
}

for character, index in some_string {
	fmt.println(index, character)
}
for value, index in some_array {
	fmt.println(index, value)
}
for value, index in some_slice {
	fmt.println(index, value)
}
for value, index in some_dynamic_array {
	fmt.println(index, value)
}
for key, value in some_map {
	fmt.println(key, value)
}

str: string = "Some text"
for character in str {
	assert(type_of(character) == rune)
	fmt.println(character)
}

for &value in some_array {
	value = something
}
for &value in some_slice {
	value = something
}
for &value in some_dynamic_array {
	value = something
}
// does not impact the second index value
for &value, index in some_dynamic_array {
	value = something
}

some_map := map[string]int{"A" = 1, "C" = 9, "B" = 4} // must be enabled with `#+feature dynamic-literals`
defer delete(some_map)

for key, &value in some_map {
	value += 1
}

fmt.println(some_map["A"]) // 2
fmt.println(some_map["C"]) // 10
fmt.println(some_map["B"]) // 5

iter_count := 0
some_procedure :: proc() -> (int, int, int, cond: bool) {
	iter_count += 1
	if iter_count < 4 {
		return iter_count, iter_count*2, iter_count*3, true
	} else {
		return 0, 0, 0, false
	}
}

for a, b, c in some_procedure() {
	fmt.println(a, b, c)
	// Prints
	// 1 2 3
	// 2 4 6
	// 3 6 9
}

array := [?]int { 10, 20, 30, 40, 50 }

#reverse for x in array {
	fmt.println(x) // 50 40 30 20 10
}

x: [4]u8 = 0xFF
y: [4]u8 = 0x88
#unroll for i in 0..<len(x) {
	x[i] ~= y[i]
}

if statement

Odin's if statements do not need to be surrounded by parentheses ( ) but braces { } or do are required.

if x >= 0 {
	fmt.println("x is positive")
}

Like for, the if statement can start with an initial statement to execute before the condition. Variables declared by the initial statement are only in the scope of that if statement.

if x := foo(); x < 0 {
	fmt.println("x is negative")
}

Variables declared inside an if initial statement are also available to any of the else blocks:

if x := foo(); x < 0 {
	fmt.println("x is negative")
} else if x == 0 {
	fmt.println("x is zero")
} else {
	fmt.println("x is positive")
}

switch statement

A switch statement is another way to write a sequence of if-else statements. In Odin, the default case is denoted as a case without any expression.

switch arch := ODIN_ARCH; arch {
case .i386, .wasm32, .arm32:
	fmt.println("32 bit")
case .amd64, .wasm64p32, .arm64, .riscv64:
	fmt.println("64 bit")
case .Unknown:
	fmt.println("Unknown architecture")
}

Odin's switch is like the one in C or C++, except that Odin only runs the selected case. This means that a break statement is not needed at the end of each case. Another important difference is that the case values need not be integers nor constants.

To achieve a C-like fall through into the next case block, the keyword fallthrough can be used.

Switch cases are evaluated from top to bottom, stopping when a case succeeds. For example:

switch i {
case 0:
case foo():
}

foo() does not get called if i==0. If all the case values are constants, the compiler may optimize the switch statement into a jump table (like C).

A switch statement without a condition is the same as switch true. This can be used to write a clean and long if-else chain and have the ability to break if needed

switch {
case x < 0:
	fmt.println("x is negative")
case x == 0:
	fmt.println("x is zero")
case:
	fmt.println("x is positive")
}

A switch statement can also use ranges like a range-based loop:

switch c {
case 'A'..='Z', 'a'..='z', '0'..='9':
	fmt.println("c is alphanumeric")
}

switch x {
case 0..<10:
	fmt.println("units")
case 10..<13:
	fmt.println("pre-teens")
case 13..<20:
	fmt.println("teens")
case 20..<30:
	fmt.println("twenties")
}

Foo :: enum {
	A,
	B,
	C,
	D,
}

f := Foo.A
switch f {
case .A: fmt.println("A")
case .B: fmt.println("B")
case .C: fmt.println("C")
case .D: fmt.println("D")
case:    fmt.println("?")
}

#partial switch f {
case .A: fmt.println("A")
case .D: fmt.println("D")
}

Foo :: union {int, bool}
f: Foo = 123
switch _ in f {
case int:  fmt.println("int")
case bool: fmt.println("bool")
case:
}

#partial switch _ in f {
case bool: fmt.println("bool")
}

defer statement

A defer statement defers the execution of a statement until the end of the scope it is in.

The following will print 4 then 234:

package main

import "core:fmt"

main :: proc() {
	x := 123
	defer fmt.println(x)
	{
		defer x = 4
		x = 2
	}
	fmt.println(x)

	x = 234
}

You can defer an entire block too:

{
	defer {
		foo()
		bar()
	}
	// This is equivalent to `defer { if cond { bar() } }` because the `if` is
	// a statement in its own right.
	defer if cond {
		bar()
	}
}

Defer statements are executed in the reverse order that they were declared:

defer fmt.println("1")
defer fmt.println("2")
defer fmt.println("3")

Will print 3, 2, and then 1.

A real world use case for defer may be something like the following:

f, err := os.open("my_file.txt")
if err != nil {
	// handle error
}
defer os.close(f)
// rest of code

In this case, it acts akin to an explicit C++ destructor however, the error handling is basic control flow.

It's important to note that defer cannot be used to change a procedure's named return values, as it runs after exit when the values have already been returned.

foo :: proc() -> (n: int) {
	defer {
		n = 456 // This won't affect `n`
	}
	n = 123
	return
}

when statement

The when statement is almost identical to the if statement but with some differences:

• Each condition must be a constant expression as a when statement is evaluated at compile time.
• The statements within a branch do not create a new scope
• The compiler checks the semantics and code only for statements that belong to the first condition that is true
• An initial statement is not allowed in a when statement
• when statements are allowed at file scope

Example:

when ODIN_ARCH == .i386 {
	fmt.println("32 bit")
} else when ODIN_ARCH == .amd64 {
	fmt.println("64 bit")
} else {
	fmt.println("Unsupported architecture")
}

The when statement is very useful for writing platform specific code. This is akin to the #if construct in C's preprocessor. However, in Odin, it is type checked.

See the Conditional compilation section for examples of built-in constants you can use with when statements.

Branch statements

for cond {
	switch {
	case:
		if cond {
			break // break out of the `switch` statement
		}
	}

	break // break out of the `for` statement
}

loop: for cond1 {
	for cond2 {
		break loop // leaves both loops
	}
}

outer: if cond {
	ok := check_something()
	if !ok {
		break outer // label names are required with conditionals
	}
}

exit: {
	if true {
		break exit // works with labeled blocks too
	}
	fmt.println("This line will never print.")
}

for cond {
	if get_foo() {
		continue
	}
	fmt.println("Hellope")
}

switch i {
case 0:
	foo()
	fallthrough
case 1:
	bar()
}

Parameters

Procedures can take zero or many parameters. The following example is a basic procedure that multiplies two integers together:

multiply :: proc(x: int, y: int) -> int {
	return x * y
}
fmt.println(multiply(137, 432))

When two or more consecutive parameters share a type, you can omit the other types from previous names, like with variable declarations. In this example: x: int, y: int can be shortened to x, y: int, for example:

multiply :: proc(x, y: int) -> int {
	return x * y
}
fmt.println(multiply(137, 432))

By default, Odin procedures use the "odin" calling convention. This calling convention is the same as C, however it differs in a couple of ways:

• It promotes values to a pointer if that's more efficient on the target system, and
• It includes a pointer to the current context as an implicit additional argument.

The promotion is enabled by the fact that all parameters are immutable in Odin, and its rules are consistent for a given type and platform and can be relied on since they are part of the calling convention.

Passing a pointer value makes a copy of the pointer, not the data it points to. Slices, dynamic arrays, and maps have no special considerations here; they are normal structures with pointer fields, and are passed as such. Their elements will not be copied.

foo :: proc(x: int) {
	x := x // explicit mutation
	for x > 0 {
		fmt.println(x)
		x -= 1
	}
}

sum :: proc(nums: ..int) -> (result: int) {
	for n in nums {
		result += n
	}
	return
}
fmt.println(sum())              // 0
fmt.println(sum(1, 2))          // 3
fmt.println(sum(1, 2, 3, 4, 5)) // 15

odds := []int{1, 3, 5}
fmt.println(sum(..odds))        // 9, passing a slice as varargs

Multiple results

A procedure in Odin can return any number of results. For example:

swap :: proc(x, y: int) -> (int, int) {
	return y, x
}
a, b := swap(1, 2)
fmt.println(a, b) // 2 1

A call that returns multiple values can be passed directly as multiple arguments to another procedure, including into a variadic parameter, or used as multiple elements of a compound literal:

sum :: proc(nums: ..int) -> (result: int) {
	for n in nums {
		result += n
	}
	return
}
fmt.println(sum(swap(1, 2)))    // 3
fmt.println(sum(swap(1, 2), 3)) // 6

Pair :: struct {x, y: int}
p := Pair{swap(1, 2)}            // Pair{x = 2, y = 1}
xs := []int{swap(1, 2), 3}       // [2, 1, 3]

Named results

Return values in Odin may be named. If so, they are treated as variables defined at the top of the procedure, like input parameters. A return statement without arguments returns the named return value (or values). "Naked" return statements should only be used in short procedures as it reduces clarity when reading.

do_math :: proc(input: int) -> (x, y: int) {
	x = 2*input + 1
	y = 3*input / 5
	return x, y
}
do_math_with_naked_return :: proc(input: int) -> (x, y: int) {
	x = 2*input + 1
	y = 3*input / 5
	return // A "naked" return statement, as no values are explicitly specified.
}

Assigning default values to named results is also possible:

conditionally_blue :: proc(red: bool) -> (color := "blue") {
	if red {
		return "red"
	}
	return
}

Named arguments

When calling a procedure, it is not clear in which order parameters might appear. Therefore, the arguments can be named, like a struct literal, to make it clear which argument a parameter is for:

create_window :: proc(title: string, x, y: int, width, height: int, monitor: ^Monitor) -> (^Window, Window_Error) {...}

window, err := create_window(title="Hellope Title", monitor=nil, width=854, height=480, x=0, y=0)

Named and positional arguments can be mixed. This is often useful when a procedure has a lot of arguments or you want to customize default values.

Positional arguments are not allowed after named arguments.

foo :: proc(value: int, name: string, x: bool, y: f32, z := 0) { }
foo(134, "hellope", x=true, y=4.5)

Default values

The create_window procedure may be easier to use if default values are provided, which will be used if they are not specified:

create_window :: proc(title: string, x := 0, y := 0, width := 854, height := 480, monitor: ^Monitor = nil) -> (^Window, Window_Error) {...}

window1, err1 := create_window("Title1")
window2, err2 := create_window(title="Title1", width=640, height=360)

Default values are assigned at the start of the procedure call and can be overwritten. They may also be assigned to named results.

Explicit procedure overloading

Unlike other languages, Odin provides the ability to explicitly overload procedures:

bool_to_string :: proc(b: bool) -> string {...}
int_to_string  :: proc(i: int)  -> string {...}

to_string :: proc{bool_to_string, int_to_string}

foo :: proc{
	foo_bar,
	foo_baz,
	foo_baz2,
	another_thing_entirely,
}

Zero values

Variables declared without an explicit initial value are given their zero value.

The zero value is:

• 0 for numeric and rune types
• false for boolean types
• "" (the empty string) for strings
• nil for pointer, typeid, and any types.

The expression {} can be used as the zero value of any type. This is not recommended when a type has a specific zero value shown above, as that is clearer; please prefer that.

Type conversion

The expression T(v) converts the value v to the type T.

i: int = 123
f: f64 = f64(i)
u: u32 = u32(f)

or with type inference:

i := 123
f := f64(i)
u := u32(f)

Unlike C, assignments between values of a different type require an explicit conversion.

i := 123
f := cast(f64)i
u := cast(u32)f

f := f32(123)
u := transmute(u32)f

f := f32(123)
u := (^u32)(&f)^

Untyped types

In the Odin type system, certain expressions will have an "untyped" type. An untyped type can implicitly convert to a "typed" type.

I :: 42        // untyped integer, will implicitly convert to any numeric type (int, u32, f64, quaternion128 etc)
F :: 1.37      // untyped float,  will implicitly convert to any numeric type that can support fractional parts (f64, quaternion128 etc)
S :: "Hellope" // untyped string,  will implicitly convert to string and cstring
B :: true      // untyped boolean, will implicitly convert to bool, b8, b16, etc.

(The more formal name for these "untyped" types is existential or abstract types.)

Auto cast operation

The auto_cast operator automatically casts an expression to the destination's type if possible:

x: f32 = 123
y: int = auto_cast x

Note: This operation is only recommended to be used for prototyping and quick tests. Please do not abuse it.

Built-in constants, values, and procedures

There are a few built-in constants and values in Odin which have different uses:

false // untyped boolean constant equivalent to the expression 0!=0
true  // untyped boolean constant equivalent to the expression 0==0
nil   // untyped nil value used for certain values
---   // untyped undefined value used to explicitly not initialize a variable

--- is useful if you want to explicitly not initialize a variable with any default value:

x: int // initialized with its zero value
y: int = --- // uses uninitialized memory

This is the default behaviour in C, whilst the default behaviour in Odin is to zero the memory.

Vector3 :: struct {x, y, z: f32}
v := Vector3{1, 4, 9}

x, y, z := expand_values(v)
x, y, z  = **v // equivalent

// using `sum` from the multiple results section
arr := [3]int{7, 8, 9}
fmt.println(sum(**arr)) // equivalent to `sum(arr[0], arr[1], arr[2])`

v: Vector3 = compress_values(1, 4, 9)   // Vector3{1, 4, 9}
a := compress_values(1, 2, 3)           // [3]int{1, 2, 3}
s := compress_values(1, "hi", true)     // struct{v0: int, v1: string, v2: bool}{1, "hi", true}

import "base:intrinsics"

Foo :: bit_field u16 {
	x: i32 | 3,
	y: u16 | 5,
}
#assert(intrinsics.type_field_bit_offset(Foo, "y") == 3)
#assert(intrinsics.type_field_bit_size(Foo, "y")   == 5)

n := intrinsics.count_ones(u32(0b1011)) // 3

string type

As previously mentioned the odin string type is just a rawptr + len.

The core:strings library was created to help dealing with string cloning, conversion of string<->cstring and other calls you find in standard libraries.

All procedures are documented and can be easily understood with code examples.

// by runes
x := "ABC"
for codepoint, index in x {
	fmt.println(index, codepoint)
	// 0 A
	// 1 B
	// 2 C
}

// by bytes - string length is in bytes
for index in 0..<len(x) {
	fmt.println(index, x[index])
	// 0 65
	// 1 66
	// 2 67
}

Foo :: struct {
	a: [L]u8 `fmt:"s"`, // whole buffer is a string
	b: [N]u8 `fmt:"s,0"`, // 0 terminated string
	c: [M]u8 `fmt:"q,n"`, // string with length determined by n, and use %q rather than %s
	n: int `fmt:"-"`, // ignore this from formatting
}

cstring type

The cstring type is a c-style string value, which is zero-terminated. It is equivalent to char const * in C. Its primary purpose is for easy interfacing with C. Please see the foreign system for more information.

A cstring is easily convertible to an Odin string. However, to convert a string to a cstring, it requires allocations if the value is not constant.

str:  string  = "Hellope"
cstr: cstring = "Hellope" // constant literal
cstr2 := string(cstr)     // O(n) conversion as it requires search from the zero-terminator
nstr  := len(str)  // O(1)
ncstr := len(cstr) // O(n)

string16 and cstring16 types

string16 and cstring16 are the UTF-16 counterparts of string and cstring. They are primarily useful for interfacing with APIs which use UTF-16 strings, such as the Windows API (where cstring16 is equivalent to wchar_t const *).

• string16 stores a pointer to the u16 data and its length. len returns the number of u16 code units, not the number of characters.
• cstring16 is a zero-terminated UTF-16 string.

A constant string literal implicitly converts to either type, being encoded as UTF-16 at compile time:

s: string16  = "Hellope"
c: cstring16 = "Hellope"
assert(len(s) == 7)

for r, i in s { // iterating a `string16` decodes the UTF-16 into runes
	fmt.println(i, r)
}

emoji: string16 = "😀"
assert(len(emoji) == 2) // encoded as a surrogate pair

Like their UTF-8 equivalents, they can be converted to and from related types without allocation:

Converting between UTF-8 and UTF-16 strings at runtime requires an explicit conversion, e.g. with the procedures in core:unicode/utf16 or core:sys/windows (utf8_to_wstring, wstring_to_utf8).

string type conversions

Here is a short list of possible type conversions - including whether they copy or alias. This is important to understand since Odin gives you the possibility to keep allocations to a low degree.

If some cases are missing please let us know.

Legend:

• copy = get a freshly allocated copy of the 'from' data
• alias = reuse the 'from' data, without allocation
• stream = get individual values from the string, without allocation
• st = the input string

Arithmetic operators

Unary:

+                           is 0 + x
-    negation               is 0 - x
~    bitwise complement     is m ~ x where m = "all bits set to 1" for unsigned x
                                     and m = -1 for signed x

Binary:

+       sum                        integers, enums, floats, complex values, quaternions, arrays of numeric types, matrices, constant strings
-       subtraction                integers, enums, floats, complex values, quaternions, arrays of numeric types, matrices
*       multiplication             integers, floats, complex values, quaternions, arrays of numeric types, matrices
/       division                   integers, floats, complex values, quaternions, arrays of numeric types
%       modulo (truncated)         integers
%%      remainder (floored)        integers

|       bitwise or                 integers, enums
~       bitwise xor                integers, enums
&       bitwise and                integers, enums
&~      bitwise and-not            integers, enums
<<      left shift                 integer << integer >= 0
>>      right shift                integer >> integer >= 0

Except for shift operations, if one operand is an untyped constant and the other operand is not, the constant is implicitly converted to the type of the other operand (if possible).

The right operand in a shift expression must have an unsigned integer type or be an untyped constant representable by a typed unsigned integer. If the left operand of a non-constant shift expression is an untyped constant, it is first implicitly converted to the type it would assume if the shift expression were replaced solely by the left operand alone (with type inference and hinting rules applied).

Comparison operators

==      equal
!=      not equal
<       less
<=      less or equal
>       greater
>=      greater or equal
&&      short-circuiting logical and
||      short-circuiting logical or

In any comparison, the first operand must be assignable to the type of the second, or vice versa.

The equality operators == and != apply to operands that are comparable. The ordering operators <, <=, >, and >= apply to operands that are ordered. These terms and the result of the comparisons are defined as follows:

• Boolean values are comparable.
• Integers values are comparable and ordered.
• Floating-point values are comparable and ordered, defined by the IEEE-754 standard.
• Complex values are comparable.
• Quaternion values are comparable.
• Rune values are comparable and ordered.
• String values are comparable and ordered, lexically byte-wise.
• Matrix values are comparable.
• Pointer values are comparable and ordered.
• Multi-pointer values are comparable and ordered.
• SOA pointer values are comparable.
• Enum values are comparable and ordered.
• Bit set values are comparable.
• Struct values are comparable if all their fields are comparable.
• Union values are comparable if all their variants are comparable.
• Array and enumerated array values are comparable if values of the element type are comparable.
• typeid is comparable.
• SIMD vectors are comparable.

Bit set values use different logic compared to integers when comparison operators are used: please see the section on bit sets.

Logical operators

Logical operators apply to boolean values. The right operand is evaluated conditionally

&&      conditional AND    a && b  is "b if a else false"
||      conditional OR     a || b  is "true if a else b"
!       NOT                !a      is "not a"

Compound binary operator and assign

Like many other languages, there is a shorthand for performing a binary operation and assigning the result to the first operand e.g. x = x + 5. All arithmetic and logical binary operators have this shorthand

+=       sum and assign                   a += b is a = a + b
-=       subtraction and assign           a -= b is a = a - b
*=       multiplication and assign        a *= b is a = a * b
/=       division and assign              a /= b is a = a / b
%=       modulo (truncated) and assign    a %= b is a = a % b
%%=      remainder (floored) and assign   a %%= b is a = a %% b

|=       bitwise or and assign            a |= b is a = a | b
~=       bitwise xor and assign           a ~= b is a = a ~ b
&=       bitwise and and assign           a &= b is a = a & b
&~=      bitwise and-not and assign       a &~= b is a = a &~ b
<<=      left shift and assign            a <<= b is a = a << b
>>=      right shift and assign           a >>= b is a = a >> b

&&=      conditional AND and assign       a &&= b is a = a && b
||=      conditional OR and assign        a ||= b is a = a || b

Address operator

For an operand x of type T, the address operation &x generates a pointer of ^T to x. The operand must be addressable, meaning that either a variable, pointer indirection, or slice/dynamic array indexing operator; or a field selector of an addressable struct operand; or an array index operation of an addressable array; or a type assertion of an addressable union or any; or a compound literal value.

For an operand x of pointer type ^T, the pointer indirection x^ denotes the variable of type T pointed to by x. If x is an invalid address, such as nil, an attempt to evaluate x^ will result in platform specific behaviour - on most platforms this will be a segmentation fault.

&x
&a[foo(123)]
&Foo{1, 2}

p^
pproc(a)^

x: ^int = nil
x^      // causes a runtime panic

Ternary operators

x if cond else y    // ternary runtime conditional expression
x when cond else y  // ternary compile-time conditional expression
cond ? x : y        // ternary runtime conditional expression, equivalent to "x if cond else y"

Other operators

• or_else
  • see section on or_else
• or_return
  • see section on or_return
• or_continue
  • see section on or_continue
• or_break
  • see section on or_break
• in - set membership (e in A, A contains element e)
  • Used for bit_set types and map types
• not_in - not set membership (e not_in A, A does not contain e)
  • Used for bit_set types and map types
• ** - prefix unary operator which expands a struct or array value into multiple values (**x is equivalent to expand_values(x))
  • see section on expand_values
• ..= - inclusive range
• ..< - half open range

The range operations ..= and ..< are only possible within certain contexts:

for x in a..<b {}
for x in a..=b {}

switch x {
case a..<b:
case c..=d:
}

bit_set[a..<b]
bit_set[a..=b]

foo := [?]int{0..=3 = 1} // initialises as: [1, 1, 1, 1]
bar := [?]int{0 = 0, 1..<3 = 1} // initialises as: [0, 1, 1]

in and not_in cannot be used directly as a for loop condition, as that would be ambiguous with a range-based loop; wrap the condition in parentheses instead:

for x in y {}    // range loop
for (x in y) {}  // condition-only for-loop (while-loop in some other languages)

Operator precedence

Unary operators have the highest precedence.

There are seven precedence levels for binary (and ternary) operators.

Precedence    Operator
     7           *   /   %   %%   &   &~  <<   >>
     6           +   -   |   ~    in  not_in
     5           ==  !=  <   >    <=  >=
     4           &&
     3           ||
     2           ..=    ..<
     1           or_else     ?    if  when

Binary operators of the same precedence associate from left to right. For instance x / y * z is the same as (x / y) * z.

Integer operators

For two integers values x and y, the integer quotient q = x/y and remainder r = x%y satisfies the following relationships:

x = q*y + r   and |r| < |y|

with x/y truncated towards zero (truncated division).

For two integers values x and y, the integer quotient q = x/y and remainder r = x%%y satisfies the following relationships:

r = x - y*floor(x/y)

The exception to these rules is when the dividend x is the most negative value for the integer type of x, and the quotient q = x/-1 is equal to x (and r or m = 0) due to two's complement integer overflow.

If the divisor is a constant, it must not be zero. If the divisor is zero at runtime, a runtime panic occurs.

The shift operators shift the left operand by the shift count specified by the right operand, which must be non-negative. The shift operators implement arithmetic shifts if the left operand is a signed integer and logical shifts if the left operand is an unsigned integer. There is not an upper limit on the shift count. Shifts behave as if the left operand is shifted n times by 1 for a shift count of n. Therefore, x<<1 is the same as x*2 and x>>1 is the same as x/2 but truncated towards negative infinity.

// These are equivalent:
x << y
x << y if y < 8*size_of(x) else 0

x >> y
x >> y if y < 8*size_of(x) else 0

Integer overflow

For unsigned integers, the operations +, -, *, and << are computed modulo 2ⁿ, where n is the bit width of the unsigned integer's type. In a sense, these unsigned integer operations discard the high bits upon overflow, and programs may rely on "wrap around".

For signed integers, the operations +, -, *, /, and << may legally overflow and the resulting value exists and is deterministically defined by the signed integer representation. Overflow does not cause a runtime panic. A compiler may not optimize code under the assumption that overflow does not occur. For instance, x < x+1 may not be assumed to be always true.

Floating-point operators

For floating-point, complex numbers, quaternions, and other floating-point embedded types:

• +x is the same as x
• -x is the negation of x

The result of a floating-point related division by zero is not specified beyond the IEEE-754 standard; a runtime panic will occur.

An implementation may combine multiple floating-point operations into a single fused operation, and produce a result that differs from the value obtained by executing and rounding the instructions individually.

Type alias

You can alias a named type with another name:

My_Int :: int
#assert(My_Int == int)

Distinct types

A distinct type allows for the creation of a new type with the same underlying semantics.

My_Int :: distinct int
#assert(My_Int != int)

Aggregate types (struct, enum, union) will always be distinct even when named.

Foo :: struct {}
#assert(Foo != struct{})

Fixed arrays

An array is a simplified fixed length container. Each element in an array has the same type. An array's index can be any integer, character, or enumeration type.

An array can be constructed like the following:

x := [5]int{1, 2, 3, 4, 5}
for i in 0..=4 {
	fmt.println(x[i])
}

Fixed arrays are equivalent to a struct with a field for each element. They are just a number of values in a row in memory.

The notation x[i] is used to access the i-th element of x; and 0-index based (like C).

The above array can also be constructed with a question mark (?) to automatically infer its length:

x := [?]int{1, 2, 3, 4, 5}

Construct an array with designated initializers:

favorite_animals := [?]string{
	// Assign by index
	0 = "Raven",
	1 = "Zebra",
	2 = "Spider",
	// Assign by range of indices
	3..=5 = "Frog",
	6..<8 = "Cat"
}

The built-in len proc returns the array's length.

x: [5]int
#assert(len(x) == 5)

Array access is bounds checked by default, both at compile-time (with constant indices) and at runtime. This can be disabled and enabled at a per block level with the #no_bounds_check and #bounds_check directives, respectively:

#no_bounds_check {
	x[n] = 123 // n could be in or out of range of valid indices
}

#no_bounds_check can be used to improve performance when the bounds are known to not exceed.

Vector3 :: [3]f32
a := Vector3{1, 4, 9}
b := Vector3{2, 4, 8}
c := a + b  // {3, 8, 17}
d := a * b  // {2, 16, 72}
e := c != d // true

a := [3]f32{10, 20, 30}
b := swizzle(a, 2, 1, 0)
assert(b == [3]f32{30, 20, 10})

c := swizzle(a, 0, 0)
assert(c == [2]f32{10, 10})
assert(c == 10) // assert all elements == 10

Vector3 :: distinct [3]f32
a := Vector3{1, 2, 3}
b := Vector3{5, 6, 7}
c := (a * b)/2 + 1
d := c.x + c.y + c.z
fmt.printf("%.1f\n", d) // 22.0

cross :: proc(a, b: Vector3) -> Vector3 {
	i := swizzle(a, 1, 2, 0) * swizzle(b, 2, 0, 1)
	j := swizzle(a, 2, 0, 1) * swizzle(b, 1, 2, 0)
	return i - j
}

cross_shorter :: proc(a, b: Vector3) -> Vector3 {
	i := a.yzx * b.zxy
	j := a.zxy * b.yzx
	return i - j
}

blah :: proc(a: Vector3) -> f32 {
	return a.x + a.y + a.z
}

x := cross(a, b)
fmt.println(x)
fmt.println(blah(x))

a := [4]u32{1, 2, 3, 4}
b := cast([4]f32)a      // [1.0, 2.0, 3.0, 4.0]
c := ([4]f64)(b)        // [1.0, 2.0, 3.0, 4.0]

m := [2][2]i32{{1, 2}, {3, 4}}
n := cast([2][2]f32)m   // [[1.0, 2.0], [3.0, 4.0]]

Slices

Slices look similar to arrays however, their length is not known at compile time. The type []T is a slice with elements of type T. In practice, slices are much more common than arrays.

A slice is formed by specifying two indices, a low and high bound, separated by a colon:

a[low : high]

This selects a half-open range which includes the lower element, but excludes the higher element.

fibonaccis := [6]int{0, 1, 1, 2, 3, 5}
s: []int = fibonaccis[1:4] // creates a slice which includes elements 1 through 3
fmt.println(s) // 1, 1, 2

Slices are like references to arrays; they do not store any data, rather they describe a section, or slice, of underlying data.

Internally, a slice stores a pointer to the data and an integer to store the length of the slice.

The built-in len proc returns the slice's length.

x: []int = ...
length_of_x := len(x)

[3]int{1, 6, 3}

[]int{1, 6, 3}

a: [6]int

a[0:6]
a[:6]
a[0:]
a[:]

a[offset:offset+length]

a[offset:][:length]

s: []int
if s == nil {
	fmt.println("s is nil!")
}

s := []int{1, 6, 3, 5 ,7, 3, 0}
slice.sort(s)

r := []int{1, 6, 3, 5 ,7, 3, 0}
slice.reverse_sort(r)

Dynamic arrays

Dynamic arrays are similar to slices, but their lengths may change during runtime. Dynamic arrays are resizeable and they are allocated using the current context's allocator.

x: [dynamic]int

Along with the built-in proc len, dynamic arrays also have cap which can be used to determine the dynamic array's current underlying capacity.

x: [dynamic]int
append(&x, 123)
append(&x, 4, 1, 74, 3) // append multiple values at once

y: [dynamic]int
append(&y, ..x[:]) // append a slice

x := make([dynamic]int, 0, 16)
inject_at(&x, 0, 10)
inject_at(&x, 3, 10) // resizes till length
fmt.eprintln(x[:], len(x), cap(x)) // [10, 0, 0, 10] 4 16
assign_at(&x, 3, 20)
assign_at(&x, 4, 30)
fmt.eprintln(x[:], len(x), cap(x)) // [10, 0, 0, 20, 30] 5, 16
assign_at(&x, 5, 40, 50, 60)
fmt.eprintln(x[:], len(x), cap(x)) // [10, 0, 0, 20, 30, 40, 50, 60] 8 16

x: [dynamic]int
append(&x, 1, 2, 3, 4, 5) // [1, 2, 3, 4, 5]
pop(&x) // [1, 2, 3, 4]
ordered_remove(&x, 0) // [2, 3, 4]
unordered_remove(&x, 0) // [4, 3]

s: [dynamic]int
append(&s, 1, 6, 3, 5, 7, 3, 0) // [1, 6, 3, 5, 7, 3, 0]
slice.sort(s[:]) // [0, 1, 3, 3, 5, 6, 7]

a := make([]int, 6)           // len(a) == 6
b := make([dynamic]int, 6)    // len(b) == 6, cap(b) == 6
c := make([dynamic]int, 0, 6) // len(c) == 0, cap(c) == 6
d := []int{1, 2, 3}           // a slice literal, for comparison

// with an explicit allocator:
e := make([]int, 6, context.allocator)
f := make([dynamic]int, 0, 6, context.allocator)

delete(a)
delete(b)
delete(c)
// delete(d)                  // no need to clean up slice literals
delete(e)                     // slices are always deleted from context.allocator
delete(f)                     // dynamic arrays remember their allocator

x: [dynamic]int
append(&x, 1, 2, 3, 4, 5) // [1, 2, 3, 4, 5]
fmt.println(len(x)) // 5
clear(&x) // []
fmt.println(len(x)) // 0

x: [dynamic]int
fmt.println(len(x), cap(x)) // 0 0
append(&x, 1, 2, 3) // [1, 2, 3]
fmt.println(len(x), cap(x)) // 3 8
resize(&x, 5)
fmt.println(x[:]) // [1, 2, 3, 0, 0] other values are zero'd memory
fmt.println(len(x), cap(x)) // 5 8
reserve(&x, 32)
fmt.println(len(x), cap(x)) // 5 32
shrink(&x)
fmt.println(len(x), cap(x)) // 5 5

[dynamic; N]T fixed capacity dynamic array

Odin supports a fixed capacity dynamic array [dynamic; N]T. It implements most dynamic array procedures while being able to remain on the stack.

Short Example:

x: [dynamic; 8]int
fmt.println(len(x), cap(x)) // 0 8
append(&x, 1, 2, 3)
fmt.println(len(x), cap(x)) // 3 8
fmt.println(x[:]) // [1, 2, 3]

A fixed capacity dynamic array is a value type: it stores its N elements inline along with its length, and it never allocates, meaning it has no allocator and never needs to be deleted. Its capacity is always N.

Because it cannot grow, append returns the number of elements actually appended, which is 0 if there is no room:

x: [dynamic; 4]int
n := append(&x, 1, 2, 3) // n == 3
n  = append(&x, 4, 5)    // n == 1, only `4` fits
n  = append(&x, 6)       // n == 0, the array is full
fmt.println(x[:])        // [1, 2, 3, 4]

The following built-in procedures support fixed capacity dynamic arrays: append, non_zero_append, inject_at, assign_at, pop, pop_safe, pop_front, pop_front_safe, unordered_remove, ordered_remove, remove_range, clear, resize, and non_zero_resize. They can also be sliced, iterated with for loops, and initialized with compound literals:

y := [dynamic; 8]int{1, 2, 3}
fmt.println(len(y), cap(y)) // 3 8

Enumerations

Enumeration types define a new type whose values consist of the ones specified. The values are ordered, for example:

Direction :: enum{North, East, South, West}

The following holds:

int(Direction.North) == 0
int(Direction.East)  == 1
int(Direction.South) == 2
int(Direction.West)  == 3

Enum fields can be assigned an explicit value:

Foo :: enum {
	A,
	B = 4, // Holes are valid
	C = 7,
	D = 1337,
}

If an enumeration requires a specific size, a backing integer type can be specified. By default, int is used as the backing type for an enumeration.

Foo :: enum u8 {A, B, C} // Foo will only be 8 bits

.member_name

Foo :: enum{A, B, C}
f: Foo
f = Foo.A
f = .A

switch f {
case .A:
	fmt.println("foo")
case .B:
	fmt.println("bar")
case .C:
	fmt.println("baz")
}

#+feature using-stmt
package main

main :: proc() {
	Foo :: enum {A, B, C}
	using Foo
	a := A
}

Direction :: enum{North, East, South, West}

for direction, index in Direction {
	fmt.println(index, direction)
	// 0 North
	// 1 East
	// 2 South
	// 3 West
}

Enumerated array

Enumerated arrays allow an enum to be used as the index type of a fixed array.

We'll extend the Direction enum used previously to add direction vectors.

Direction :: enum{North, East, South, West}

Direction_Vectors :: [Direction][2]int {
	.North = {  0, -1 },
	.East = { +1,  0 },
	.South = {  0, +1 },
	.West = { -1,  0 },
}

assert(Direction_Vectors[.North] == { 0, -1 })
assert(Direction_Vectors[.East] == { 1, 0 })
assert(Direction_Vectors[cast(Direction) 2] == { 0, 1 })

The #partial directive can be used to initialize an enumerated array partially.

The #sparse directive can be used to initialize an enumerated array with an enum which does not have contiguous values.

arr: [enum {A, B, C}]int
arr = #partial { // without partial the compiler would complain
	.A = 42,
}
fmt.println(arr) // [.A = 42, .B = 0, .C = 0]

Bit sets

The bit_set type models the mathematical notion of a set. A bit_set's element type can be either an enumeration or a range:

Direction :: enum{North, East, South, West}

Direction_Set :: bit_set[Direction]

Char_Set :: bit_set['A'..='Z']

Number_Set :: bit_set[0..<10] // bit_set[0..=9]

Bit sets are implemented as bit vectors internally for high performance. The zero value of a bit set is either nil or {}.

x: Char_Set
x = {'A', 'B', 'Y'}
y: Direction_Set
y = {.North, .West}

Bit sets support the following operations:

• A + B - union of two sets (equivalent to A | B)
• A - B - difference of two sets (A without B's elements) (equivalent to A &~ B)
• A & B - intersection of two sets
• A | B - union of two sets (equivalent to A + B)
• A &~ B - difference of two sets (A without B's elements) (equivalent to A - B)
• A ~ B - symmetric difference (Elements that are in A and B but not both)
• A == B - set equality
• A != B - set inequality
• A <= B - subset relation (A is a subset of B or equal to B)
• A < B - strict subset relation (A is a proper subset of B)
• A >= B - superset relation (A is a superset of B or equal to B)
• A > B - strict superset relation (A is a proper superset of B)
• e in A - set membership (A contains element e)
• e not_in A - not set membership (A does not contain element e)

Bit sets are often used to denote flags. This is much cleaner than defining integer constants that need to be bitwise or-ed together.

If a bit set requires a specific size, the underlying integer type can be specified:

Char_Set :: bit_set['A'..='Z'; u64]
#assert(size_of(Char_Set) == size_of(u64))

The underlying type may also be a fixed length array of integers. Integer backed bit sets are limited to 128 bits; an array backing allows for bit sets with more elements:

Big :: enum {A = 0, B = 100, C = 200}
Big_Set :: bit_set[Big; [4]u64] // 256 bits
#assert(size_of(Big_Set) == 32)

s := Big_Set{.A, .C}
assert(.C in s)
assert(card(s) == 2)

To get the number of elements set, its cardinality, of a bit_set, use the built-in card procedure:

x: Direction_Set
x = {.North, .West}
count := card(x)
assert(count == 2)

Pointers

Odin has pointers. A pointer is a memory address of a value. The type ^T is a pointer to a T value. Its zero value is nil.

p: ^int

The & operator takes the address of its operand (if possible):

i := 123
p := &i

The ^ operator dereferences the pointer's underlying value:

fmt.println(p^) // read `i` through the pointer `p`
p^ = 1337       // write `i` through the pointer `p`

Structs

A struct is a record type in Odin. It is a collection of fields. Struct fields are accessed by using a dot:

Vector2 :: struct {
	x: f32,
	y: f32,
}
v := Vector2{1, 2}
v.x = 4
fmt.println(v.x)

Struct fields can be accessed through a struct pointer:

v := Vector2{1, 2}
p := &v
p.x = 1335
fmt.println(v)

We could write p^.x, however, it is nice to not have to explicitly dereference the pointer. This is very useful when refactoring code to use a pointer rather than a value, and vice versa.

Vector3 :: struct {
	x, y, z: f32,
}
v: Vector3
v = Vector3{} // Zero value
v = Vector3{1, 4, 9}

v := Vector3{z=1, y=2}
assert(v.x == 0)
assert(v.y == 2)
assert(v.z == 1)

Foo :: struct {
	a, b, c: int,

	bar_1: struct {
		x, y, z: int,
	},

	bar_2: struct {
		x, y, z: int,
	},

	_: struct {
		x, y, z: int,
	},
}

struct #align(4)           {...} // align to 4 bytes
struct #raw_union          {...} // all fields share the same offset (0). This is the same as C's union
struct #packed             {...} // remove padding between fields
struct #min_field_align(4) {...} // all fields must have a minimum alignment of 4 bytes (equivalent to `#pragma pack(4)` in C extensions)
struct #max_field_align(4) {...} // all fields must have a maximum alignment of 4 bytes
struct #simple             {...} // The struct is compared as if with `memcmp`, without needing any other special behaviour

Foo :: struct #all_or_none {
	a: int,
	b: int,
	c: int,
}

test :: proc() {
	// No fields set
	a := Foo{}

	// This is an error.
	b := Foo{
		a = 10,
	}

	// All fields set
	c := Foo{
		a = 10,
		b = 10,
		c = 10,
	}
}

User :: struct {
	flag: bool, // untagged field
	age:  int    "custom whatever information",
	name: string `json:"username" xml:"user-name" fmt:"q"`, // `core:reflect` layout
}

name: string `json:"username,omitempty"`,

Unions

A union in Odin is a discriminated union, also known as a tagged union or sum type. The zero value of a union is nil.

Value :: union {
	bool,
	i32,
	f32,
	string,
}
v: Value
v = "Hellope"

// type assert that `v` is a `string` and panic otherwise
s1 := v.(string)

// type assert but with an explicit boolean check. This will not panic
s2, ok := v.(string)

value: Value = ...
switch v in value {
case string:
	#assert(type_of(v) == string)

case bool:
	#assert(type_of(v) == bool)

case i32, f32:
	// This case allows for multiple types, therefore we cannot know which type to use
	// `v` remains the original union value
	#assert(type_of(v) == Value)
case:
	// Default case
	// In this case, it is `nil`
}

Value :: union #no_nil {bool, string}
v: Value
_, ok := v.(bool)
assert(ok)

Error :: union #shared_nil {
	File_Error,
	Memory_Error,
}

File_Error :: enum {
	None = 0,
	File_Not_Found,
	Cannot_Open_File,
}

Memory_Error :: enum {
	None = 0,
	Allocation_Failed,
	Resize_Failed,
}

shared_nil_example :: proc() {
	an_error: Error
	an_error = File_Error.None

	assert(an_error == nil)
}

union #align(4) {...} // align to 4 bytes

Maps

A map maps keys to values. The zero value of a map is nil. A nil map has no keys. The built-in make proc returns an initialized map using the current context, and delete can be used to delete a map.

m := make(map[string]int)
defer delete(m)
m["Bob"] = 2
fmt.println(m["Bob"])

To insert or update an element of a map:

m[key] = elem

To retrieve an element:

elem = m[key]

To remove an element:

delete_key(&m, key)

If an element of a key does not exist, the zero value of the element will be returned. Checking to see if an element exists can be done in two ways:

elem, ok := m[key] // `ok` is true if the element for that key exists

or

ok := key in m // `ok` is true if the element for that key exists

The first approach is called the "comma ok idiom".

You can also initialize maps with map literals:

m := map[string]int{
	"Bob" = 2,
	"Chloe" = 5,
}

Modifying existing map slots needs to be done in two steps. However assigning to a struct field is prohibited.

Test :: struct {
	x: int,
	y: int,
}

m := map[string]Test{
	"Bob" = { 0, 0 },
	"Chloe" = { 1, 1 },
}

value, ok := &m["Bob"]
if ok {
	value^ = { 2, 2 }
}

fmt.println(m["Bob"]) // { 2, 2 }
m["Bob"] = { 3, 3 }
fmt.println(m["Bob"]) // { 3, 3 }
m["Chloe"].x = 0 // PROHIBITED

Bit fields

A bit_field is a record type in Odin that is akin to a bit-packed struct.

bit_field fields are accessed by using a dot:

Foo :: bit_field u16 { // backing type must be an integer or array of integers
	x: i32     | 3, // signed integers will be signed extended on use
	y: u16     | 2 + 3, // general expressions
	z: My_Enum | foo.SOME_CONSTANT, // ability to define the bit-width elsewhere
	w: bool    | 2 when foo.SOME_CONSTANT > 10 else 1,
}

v := Foo{}
v.x = 3 // truncates the value to fit into 3 bits
fmt.println(v.x) // accessing will convert `v.x` to an `i32` and do an appropriate sign extension

A bit_field is different from a struct in that you must specify the backing type. This backing type must be an integer or a fixed-length array of integers. This is useful if there needs to be a specific alignment or access pattern for the record.

Foo :: bit_field u32 {...}
Foo :: bit_field [4]u8 {...}

Notes:

• If all of the fields in a bit_field are 1-bit in size and are a boolean, please consider using a bit_set instead.
• Odin's bit_field and C's bit-fields might not be compatible
  • Odin's bit_fields have a well defined layout (Least-Significant-Bit)
  • C's bit fields on structs are undefined and are not portable across targets and compilers

Procedure type

A procedure type is internally a pointer to a procedure in memory. nil is the zero value of a procedure type.

Examples:

proc(x: int) -> bool
proc(c: proc(x: int) -> bool) -> (i32, f32)

Or you can assign them to a variable:

Callback :: proc() -> int
a: Callback // nil
assert(a == nil)
a = proc() -> int { return 0 }
fmt.println(a()) // 0
a = proc() -> int { return 100 }
fmt.println(a()) // 100

proc "c" (n: i32, data: rawptr)
proc "contextless" (s: []int)

typeid type

A typeid is a unique identifier for an Odin type. This construct is used by the any type to denote what the underlying data's type is.

a := typeid_of(bool)
i: int = 123
b := typeid_of(type_of(i))

A typeid can be mapped to relevant type information which can be used in applications such as printing types and editing data:

import "base:runtime"

main :: proc() {
	u := u8(123)
	id := typeid_of(type_of(u))
	info: ^runtime.Type_Info
	info = type_info_of(id)
}

any Type

An any type can reference any data type. 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.

Multi-pointers

Multi-Pointers in Odin are a way to describe foreign (C-like) pointers which act like arrays (pointers that map to multiple items). The type [^]T is a multi-pointer to T value(s). Its zero value is nil.

p: [^]int

What multi-pointers support:

• Index (without any bounds checking)
• Slicing (bounds checking on if both the low and high operands are given)
• Implicit conversions between ^T and [^]T
• Implicit conversion to rawptr (like all pointers)

What multi-pointers DO NOT SUPPORT:

• Dereferencing (which makes it closer to a slim-slice than a pointer)

The main purpose of this type is to aid with foreign code and act as a way to auto-document functionality and allow for easier transition to Odin code, especially converting pointers into slices.

The following are the rules for indexing and slicing for multi-pointers, and what type they produce depending on the operands given:

x: [^]T = ...

x[i]   -> T
x[:]   -> [^]T
x[i:]  -> [^]T
x[:n]  -> []T
x[i:n] -> []T

Interacting with Multi-Pointers is easiest using the builtin raw_data() call which can return a Multi-Pointer.

a: [^]int
fmt.println(a) // <nil>
b := [?]int { 10, 20, 30 }
a = raw_data(b[:])
fmt.println(a, a[1], b) // 0x7FFCBE9FE688 20 [10, 20, 30]

SOA data types

Array of Structures (AoS), Structure of Arrays (SoA), and Array of Structures of Arrays (AoSoA) refer to differing ways to arrange a sequence of data records in memory, with regard to interleaving. These are of interest in SIMD and SIMT programming.

Vector3 :: struct {x, y, z: f32}

N :: 2
v_aos: [N]Vector3
v_aos[0].x = 1
v_aos[0].y = 4
v_aos[0].z = 9

fmt.println(len(v_aos))
fmt.println(v_aos[0])
fmt.println(v_aos[0].x)
fmt.println(&v_aos[0].x)

v_aos[1] = {0, 3, 4}
v_aos[1].x = 2
fmt.println(v_aos[1])
fmt.println(v_aos)

v_soa: #soa[N]Vector3

v_soa[0].x = 1
v_soa[0].y = 4
v_soa[0].z = 9


// Same syntax as AOS and treat as if it was an array
fmt.println(len(v_soa))
fmt.println(v_soa[0])
fmt.println(v_soa[0].x)
fmt.println(&v_soa[0].x)
v_soa[1] = {0, 3, 4}
v_soa[1].x = 2
fmt.println(v_soa[1])

// Can use SOA syntax if necessary
v_soa.x[0] = 1
v_soa.y[0] = 4
v_soa.z[0] = 9
fmt.println(v_soa.x[0])

// Same pointer addresses with both syntaxes
assert(&v_soa[0].x == &v_soa.x[0])


// Same fmt printing
fmt.println(v_aos)
fmt.println(v_soa)

Vector3 :: distinct [3]f32

N :: 2
v_aos: [N]Vector3
v_aos[0].x = 1
v_aos[0].y = 4
v_aos[0].z = 9

v_soa: #soa[N]Vector3

v_soa[0].x = 1
v_soa[0].y = 4
v_soa[0].z = 9

Vector3 :: struct {x: i8, y: i16, z: f32}

N :: 3
v: #soa[N]Vector3
v[0].x = 1
v[0].y = 4
v[0].z = 9

s: #soa[]Vector3
s = v[:]
assert(len(s) == N)
fmt.println(s)
fmt.println(s[0].x)

a := s[1:2]
assert(len(a) == 1)
fmt.println(a)

d: #soa[dynamic]Vector3

append_soa(&d, Vector3{1, 2, 3}, Vector3{4, 5, 9}, Vector3{-4, -4, 3})
fmt.println(d)
fmt.println(len(d))
fmt.println(cap(d))
fmt.println(d[:])

d: #soa[dynamic]Vector3
defer delete(d)

append(&d, Vector3{1, 2, 3}, Vector3{4, 5, 6}, Vector3{7, 8, 9})
last  := pop(&d)       // Vector3{7, 8, 9}
first := pop_front(&d) // Vector3{1, 2, 3}
assert(len(d) == 1)

v: #soa[4]Vector3
p := &v[2] // p: #soa^#soa[4]Vector3
p.x = 123
assert(v[2].x == 123)
assert(v.x[2] == 123)

x := []i32{1, 3, 9}
y := []f32{2, 4, 16}
z := []b32{true, false, true}

// produce an #soa slice with the normal slices passed
s := soa_zip(a=x, b=y, c=z)

// iterate over the #soa slice
for v, i in s {
	fmt.println(v, i) // exactly the same as s[i]
	// NOTE: `v` is NOT a temporary value but has a specialized addressing mode
	// which means that when accessing v.a etc, it does the correct transformation
	// internally:
	//         s[i].a === s.a[i]
	fmt.println(v.a, v.b, v.c)
}

// Recover the slices from the #soa slice
a, b, c := soa_unzip(s)
fmt.println(a, b, c)

matrix type

A matrix is a mathematical type built into Odin. It is a regular array of numbers, arranged in rows and columns.

The following represents a matrix that has 2 rows and 3 columns:

m: matrix[2, 3]f32

m = matrix[2, 3]f32{
	1, 9, -13,
	20, 5, -6,
}

Element types of integers, float, and complex numbers are supported by matrices. There is no support for booleans, quaternions, or any compound type.

Indexing a matrix can be used with the matrix indexing syntax. This mirrors other type usages: type on the left, usage on the right.

elem := m[1, 2] // row 1, column 2

Scalars act as if they are scaled identity matrices and can be assigned to matrices as them

b := matrix[2, 2]f32{}
f := f32(3)
b = f

fmt.println("b", b)
fmt.println("b == f", b == f)

Matrices support multiplication between matrices:

a := matrix[2, 3]f32{
	2, 3, 1,
	4, 5, 0,
}

b := matrix[3, 2]f32{
	1, 2,
	3, 4,
	5, 6,
}

fmt.println("a", a)
fmt.println("b", b)

c := a * b
#assert(type_of(c) == matrix[2, 2]f32)
fmt.tprintln("c = a * b", c)

Matrices support multiplication between matrices and arrays:

m := matrix[4, 4]f32{
	1, 2, 3, 4,
	5, 5, 4, 2,
	0, 1, 3, 0,
	0, 1, 4, 1,
}

v := [4]f32{1, 5, 4, 3}

// treating `v` as a column vector
fmt.println("m * v", m * v)

// treating `v` as a row vector
fmt.println("v * m", v * m)

// Support with non-square matrices
s := matrix[2, 4]f32{ // [4][2]f32 default layout
	2, 4, 3, 1,
	7, 8, 6, 5,
}

w := [2]f32{1, 2}
r: [4]f32 = w * s
fmt.println("r", r)

Component-wise operations:

// if the element type supports it
// Not support for '/', '%', or '%%' operations

a := matrix[2, 2]i32{
	1, 2,
	3, 4,
}

b := matrix[2, 2]i32{
	-5,  1,
	 9, -7,
}

c0 := a + b
c1 := a - b
c2 := a & b
c3 := a | b
c4 := a ~ b
c5 := a &~ b

// component-wise multiplication
// since a * b would be a standard matrix multiplication
c6 := hadamard_product(a, b)

fmt.println("a + b",  c0)
fmt.println("a - b",  c1)
fmt.println("a & b",  c2)
fmt.println("a | b",  c3)
fmt.println("a ~ b",  c4)
fmt.println("a &~ b", c5)
fmt.println("hadamard_product(a, b)", c6)

mat2 :: distinct matrix[2, 2]f32
mat4 :: distinct matrix[4, 4]f32

m2 := mat2{
	1, 3,
	2, 4,
}

m4 := mat4(m2)
assert(m4[2, 2] == 1)
assert(m4[3, 3] == 1)
fmt.printf("m2 %#v\n", m2)
fmt.println("m4", m4)
fmt.println("mat2(m4)", mat2(m4))
assert(mat2(m4) == m2)

b4 := mat4{
	1, 2, 0, 0,
	3, 4, 0, 0,
	5, 0, 6, 0,
	0, 7, 0, 8,
}
fmt.println("b4", matrix_flatten(b4))

mat2x4 :: distinct matrix[2, 4]f32
mat4x2 :: distinct matrix[4, 2]f32

x := mat2x4{
	1, 3, 5, 7,
	2, 4, 6, 8,
}

y := mat4x2(x)
fmt.println("x", x)
fmt.println("y", y)

Complex numbers and quaternions

Odin has built-in complex number types (complex32, complex64, complex128) and quaternion types (quaternion64, quaternion128, quaternion256). The number in the type name is the total size in bits, e.g. a complex64 is made of two f32 values and a quaternion256 is made of four f64 values.

Values can be written using the imaginary literal suffixes i, j, and k, or constructed with the built-in procedures complex and quaternion:

c := 1 + 2i                         // untyped complex, defaults to complex128
f: f32 = 3
d := complex(f, 4)                  // complex64, from the type of `f`
e: complex64 = 3 + 4i

q := 1 + 2i + 3j + 4k               // untyped quaternion, defaults to quaternion256
r := quaternion(w=1, x=2, y=3, z=4) // `quaternion` requires named arguments
s := quaternion(real=1, imag=2, jmag=3, kmag=4) // equivalent
assert(q == r && r == s)

They support the arithmetic operators +, -, *, and /, and are comparable with == and !=. Floats implicitly convert to complex numbers and quaternions, and complex numbers implicitly convert to quaternions.

Built-in procedures for complex numbers and quaternions:

• real(x) - the real part
• imag(x) - the i imaginary part
• jmag(q), kmag(q) - the j and k imaginary parts of a quaternion
• conj(x) - the conjugate
• abs(x) - the magnitude

c := 3 + 4i
fmt.println(real(c), imag(c)) // 3 4
fmt.println(conj(c))          // 3-4i
fmt.println(abs(c))           // 5

The components of a quaternion can also be accessed as the fields x, y, z (the imaginary parts), and w (the real part). The vector part can be accessed with xyz as a [3] array of the component type:

q: quaternion128 = 1 + 2i + 3j + 4k
assert(q.w == 1 && q.x == 2 && q.y == 3 && q.z == 4)
v := q.xyz // [3]f32{2, 3, 4}
q.xyz = {10, 20, 30}
fmt.println(q) // 1+10i+20j+30k

core:math/linalg contains many more procedures for working with quaternions, such as quaternion_angle_axis, quaternion_slerp, and quaternion_mul_vector3.

SIMD vector types

The #simd[N]T type is a vector of N elements of type T which maps directly onto the SIMD (Single Instruction, Multiple Data) registers of the target where possible. N must be a power of two (up to 64), and T must be an integer, float, boolean, or rawptr type.

import "core:simd"

a := #simd[4]f32{1, 2, 3, 4}
b: #simd[4]f32 = 10  // a scalar is broadcast to every lane
c := a*b + a         // arithmetic is applied lane-wise: <11, 22, 33, 44>

x := simd.extract(c, 2)          // 33
total := simd.reduce_add_ordered(c) // 110
arr := simd.to_array(c)          // [4]f32{11, 22, 33, 44}

mask := simd.lanes_lt(a, 3)      // lane-wise comparison
d := simd.select(mask, a, b)     // <1, 2, 10, 10>
e := cast(#simd[4]i32)a          // lane-wise conversion

Unlike fixed arrays, individual lanes of a SIMD vector cannot be indexed directly or accessed with fields like .x. Use simd.extract and simd.replace for single lanes, and swizzle (or simd.shuffle) for rearranging lanes. Conditions (including those of ternary expressions) must be booleans; use simd.select for lane-wise selection.

The core:simd package (and the architecture-specific core:simd/x86 and core:simd/arm packages) provides the full set of operations, along with common vector type aliases such as simd.f32x4 and simd.u8x16. The underlying operations are the simd_* procedures in base:intrinsics.

using with struct fields

Let's take a very simple entity struct:

Vector3 :: struct{x, y, z: f32}
Entity :: struct {
	position: Vector3,
	orientation: quaternion128,
}

It can be used like this:

foo :: proc(entity: ^Entity) {
	fmt.println(entity.position.x, entity.position.y, entity.position.z)
}

using can be applied to struct fields, making all the fields of position appear as if they are on Entity itself:

Entity :: struct {
	using position: Vector3,
	orientation: quaternion128,
}
foo :: proc(entity: ^Entity) {
	fmt.println(entity.x, entity.y, entity.z)
}

using as a statement

#+feature using-stmt
package example

import "core:fmt"

bar :: proc() {
	// brings all the exported entities from the `fmt` package into this scope
	using fmt
	println("Hellope")
}

The entity members can be brought into the procedure scope by using it:

foo :: proc(entity: ^Entity) {
	using entity
	fmt.println(position.x, position.y, position.z)
}

The using can be applied to the parameter directly:

foo :: proc(using entity: ^Entity) {
	fmt.println(position.x, position.y, position.z)
}

It can also be applied to sub-fields:

foo :: proc(entity: ^Entity) {
	using entity.position
	fmt.println(x, y, z)
}

Subtype polymorphism

It is possible to get subtype polymorphism, similar to inheritance-like functionality in C++, but without the requirement of vtables or unknown struct layout:

foo :: proc(entity: Entity) {
	fmt.println(entity.x, entity.y, entity.z)
}

Frog :: struct {
	ribbit_volume: f32,
	using entity: Entity,
}

frog: Frog
// Both work
frog.x = 123
foo(frog)

If the subtyping behaviour is wanted without bringing the field names into the parent struct, the #subtype field directive can be used instead of using:

Frog :: struct {
	ribbit_volume: f32,
	#subtype entity: Entity,
}

frog: Frog
frog.entity.x = 123 // the fields of `entity` must be accessed through `entity`
foo(frog)           // but `Frog` can still be used where an `Entity` is expected

This is commonly used for COM-style interface hierarchies, e.g. in vendor:directx.

A procedure that takes a pointer to a struct can also be assigned to a procedure type which takes a pointer to one of that struct's subtypes, as long as that subtype field is at offset 0. This is useful for implementing vtables:

IFoo :: struct {
	foo: proc(self: ^IFoo) -> string,
}

Foo :: struct {
	using vtable: IFoo, // at offset 0
	name: string,
}

FOO_VTABLE :: IFoo{
	// `self` is `^Foo` rather than `^IFoo`
	foo = proc(self: ^Foo) -> string {
		return self.name
	},
}

f := Foo{vtable = FOO_VTABLE, name = "Hellope"}
fmt.println(f->foo()) // Hellope

File suffixes

Often, you want to separate multiple implementations of a package based on the OS or the architecture.

Your .odin files can have a magic suffix that will cause the compiler to either include or exclude them based on the target platform or architecture, or both.

For example, foobar_windows.odin would only be compiled on Windows, foobar_linux.odin only on Linux, and foobar_windows_amd64.odin only on Windows AMD64.

when statements

Sometimes you only want to compile a block of code if a certain compile-time expression evaluates to true. This can be done using the when statements:

when ODIN_OS == .Linux {
	// Do Linux stuff
}

The compiler provides a set of builtin constants which are available in all files in a compilation, and which can be used in a when condition. Here is a comprehensive list of them:

See the tracking allocator for an example of something that uses the ODIN_DEBUG constant in a when statement.

Command-line defines

Sometimes you want to do something conditionally based on some compile-time parameters of some sort, but globally, across the entire project. This is how you define those.

You may define a constant using the -define command line switch. e.g: -define:FOO=true. You can then fetch its value as a constant in your code like this:

FOO :: #config(FOO, false) // defines `FOO` as a constant with the default value of false
BAR :: #config(BAR_DEBUG, true) // name can be different compared to the constant

when FOO {
	// only evaluated when `FOO` is true
} else {
	// only evaluate when `FOO` is false
}

The value for a command line define may be an integer, boolean, or string. Currently, no other types are supported.

You can read up further on Built-in procedures here.

Build tags

This feature allows you to cover more edge-case situations where you want some code to be compiled on several platforms.

However, overly-liberal use of this feature can make it hard to reason about what code is included or not, based on the target platform or architecture. File Suffixes are typically a nicer approach if they cover what you need.

For the sake of demonstration, let's take POSIX: You could use foobar_unix.odin, which has no special meaning to the compiler at all, and use a tag in the file itself.

Here's an example of a file that will only be included on Linux or Darwin:

#+build linux, darwin
package foobar

The opposite, excluding the file on both Linux and Darwin, is achieved like this:

#+build !linux
#+build !darwin
package foobar

bedrock can also be used as a build tag, to include or exclude a file when compiling in bedrock mode:

#+build !bedrock
package foobar

#+build-project-name my_game, my_game_tests
package foobar

#+build-project-name !my_editor
package foobar

#+private
package foo

Bedrock mode

The -bedrock command line switch enables a restricted subset of Odin, which is useful for very low level and freestanding code where the full runtime is not wanted. In bedrock mode the following are disabled:

• map types
• 128-bit integer types
• Runtime type information (as if -no-rtti was passed)
• Global variables which are not initialized with constants (as if -disable-non-constant-globals was passed)
• @(init) and @(fini) procedures (as if -disable-init-fini was passed)
• Anything Objective-C related
• The default paths to the core and vendor library collections

The default allocator is also the nil allocator (as if -default-to-nil-allocator was passed), and main may only use the "odin" or "contextless" calling conventions.

Code can check for bedrock mode with the ODIN_BEDROCK constant, or with the bedrock build tag.

Allocators

Odin is a manual memory management based language. This means that Odin programmers must manage their own memory, allocations, and tracking. To aid with memory management, Odin has huge support for custom allocators, especially through the implicit context system.

The built-in types of dynamic arrays and map both contain a custom allocator. This allocator can be either manually set or the allocator from the current context will be assigned to the data type.

All allocations in Odin are preferably done through allocators. The core library of Odin takes advantage of allocators through the implicit context system. The following call:

ptr := new(int)

is equivalent to this:

ptr := new(int, context.allocator)

The allocator from the context is implicitly assigned as a default parameter to the built-in procedure new.

The implicit context stores two different forms of allocators: context.allocator and context.temp_allocator. Both can be reassigned to any kind of allocator. However, these allocators are to be treated slightly differently.

• context.allocator is for "general" allocations, for the subsystem it is used within.
• context.temp_allocator is for temporary and short lived allocations, which are to be freed once per cycle/frame/etc.

By default, the context.allocator is an OS heap allocator and the context.temp_allocator is assigned to a scratch allocator (a growing arena based allocator). free_all(context.temp_allocator) must be called to clear the contents of the temporary allocator's internal arena.

The following procedures are built-in (and also available in package mem with enforced allocator errors) and are encouraged for managing memory:

• new - allocates a value of the type given. The result value is a pointer to the type given.

ptr := new(int)
ptr^ = 123
x: int = ptr^

• new_clone - allocates a clone of the value passed to it. The resulting value of the type will be a pointer to the type of the value passed.

x: int = 123
ptr: ^int
ptr = new_clone(x)
assert(ptr^ == 123)

• make - allocates memory for a backing data structure of either a slice, dynamic array, or map.

slice := make([]int, 65)

dynamic_array_zero_length := make([dynamic]int)
dynamic_array_with_length := make([dynamic]int, 32)
dynamic_array_with_length_and_capacity := make([dynamic]int, 16, 64)

made_map := make(map[string]int)
made_map_with_reservation := make(map[string]int, 64)

• new_aligned and make_aligned - like new and make (for slices) but with an explicitly specified alignment.

ptr, err := new_aligned(int, 64)      // aligned to 64 bytes
data := make_aligned([]f32, 1024, 64) // 1024 elements, aligned to 64 bytes

• free - frees the memory at the pointer given. Note: only free memory with the allocator it was allocated with.

ptr := new(int)
free(ptr)

• free_all - frees all the memory of the context's allocator (or given allocator). Note: not all allocators support this procedure.

free_all()
free_all(context.temp_allocator)
free_all(my_allocator)

• delete - deletes the backing memory of a value allocated with make or a string that was allocated through an allocator.

delete(my_slice)
delete(my_dynamic_array)
delete(my_map)
delete(my_string)
delete(my_cstring)

To see more uses of allocators and allocation-related procedures, please see package mem or its sub-packages in the core library.

For more information regarding memory allocation strategies in general, please see Ginger Bill's Memory Allocation Strategy series.

package main

import "core:fmt"
import "core:mem"

main :: proc() {
	when ODIN_DEBUG {
		track: mem.Tracking_Allocator
		mem.tracking_allocator_init(&track, context.allocator)
		context.allocator = mem.tracking_allocator(&track)

		defer {
			if len(track.allocation_map) > 0 {
				fmt.eprintf("=== %v allocations not freed: ===\n", len(track.allocation_map))
				for _, entry in track.allocation_map {
					fmt.eprintf("- %v bytes @ %v\n", entry.size, entry.location)
				}
			}
			mem.tracking_allocator_destroy(&track)
		}
	}

	do_stuff()
}

// This will add the bad frees to `track.bad_free_array`,
// you must manually check the contents of that array.
track.bad_free_callback = mem.tracking_allocator_bad_free_callback_add_to_array

explicit_context_definition :: proc "c" () {
	// Try commenting the following statement out below
	context = runtime.default_context()

	fmt.println("\n#explicit context definition")
	dummy_procedure()
}

dummy_procedure :: proc() {
	fmt.println("dummy_procedure")
}

error_callback :: proc "c" (code: i32, desc: cstring) {
	context = runtime.default_context() // set the current context
	fmt.println(desc, code) // fmt.* calls use the odin calling convention
}
glfw.SetErrorCallback(error_callback)

Logging system

As part of the implicit context system, there is a built-in logging system.

To see more uses of loggers, please see package log in the core library.

Implementing C variadic procedures

#c_vararg is not only for calling foreign variadic procedures. A procedure with the "c" calling convention can also implement a C-style variadic procedure in Odin, reading its arguments with the c_va_* procedures from base:intrinsics (which are also available as va_start, va_arg, etc. in core:c/libc):

import "base:intrinsics"
import "core:c"

c_sum :: proc "c" (count: c.int, #c_vararg args: ..any) -> (total: c.int) {
	list: c.va_list
	intrinsics.c_va_start(&list, args)
	defer intrinsics.c_va_end(&list)
	for _ in 0..<count {
		total += intrinsics.c_va_arg(&list, c.int)
	}
	return
}

Explicit parametric polymorphism

Explicit parametric polymorphism means that the types of the parameters of a proc or of the data fields of a struct (when intended to potentially be used with multiple possible types) must be explicitly provided. This is similar to how C++ allows the use of templates to fill out the body of a procedure or data structure with the types that are given at compile-time as input to the template parameters, but in Odin explicit parametric polymorphism is safer and cleaner to work with.

sin_tau :: proc(angle_in_cycles: f64) -> f64 {
	angle_in_cycles := angle_in_cycles   // Allows `angle_in_cycles` to have its value changed

	TAU :: 2 * math.PI
	angle_in_cycles *= TAU
	return math.sin(angle_in_cycles)
}
assert(math.abs(sin_tau(0.25) - 1) <= 0.001)   // sin_tau(0.25) is approximately 1
assert(math.abs(sin_tau(0.75) - -1) <= 0.001)  // sin_tau(0.75) is approximately -1

make_f32_array :: #force_inline proc($N: int, $val: f32) -> (res: [N]f32) {
	for _, i in res {
		res[i] = val*val
	}
	return
}

array := make_f32_array(3, 2)

my_new :: proc($T: typeid) -> ^T {
	return (^T)(alloc(size_of(T), align_of(T)))
}

ptr := my_new(int)

Table_Slot :: struct($Key, $Value: typeid) {
	occupied: bool,
	hash:    u32,
	key:     Key,
	value:   Value,
}
slot: Table_Slot(string, int)

Error :: enum {Foo0, Foo1, Foo2}
Param_Union :: union($T: typeid) #no_nil {T, Error}
r: Param_Union(int)
r = 123
r = Error.Foo0

Implicit parametric polymorphism

Implicit implies that the type of a parameter is inferred from its input. In this case, the dollar sign $ can be placed on the type.

foo :: proc($N: $I, $T: typeid) -> (res: [N]T) {
	// `N` is the constant value passed
	// `I` is the type of `N`
	// `T` is the type passed
	fmt.printf("Generating an array of type %v from the value %v of type %v\n",
			   typeid_of(type_of(res)), N, typeid_of(I))
	for i in 0..<N {
		res[i] = i*i
	}
	return
}

T :: int
array := foo(4, T)
for v, i in array {
	assert(v == T(i*i))
}

// Only allow types that are specializations of a (polymorphic) slice
make_slice :: proc($T: typeid/[]$E, len: int) -> T {
	return make(T, len)
}

Table_Slot :: struct($Key, $Value: typeid) {
	occupied: bool,
	hash:     u32,
	key:      Key,
	value:    Value,
}
Table :: struct($Key, $Value: typeid) {
	count:     int,
	allocator: mem.Allocator,
	slots:     []Table_Slot(Key, Value),
}

// Only allow types that are specializations of `Table`
allocate :: proc(table: ^$T/Table, capacity: int) {
	...
}

// find :: proc(table: ^$T/Table, key: T.Key) -> (T.Value, bool) {
find :: proc(table: ^Table($Key, $Value), key: Key) -> (Value, bool) {
	...
}

where clauses

A bound on polymorphic parameters to a procedure or record can be expressed using a where clause immediately before opening {, rather than at the type's or constant's first mention. Additionally, where clauses can apply bounds to arbitrary types, rather than just polymorphic type parameters.

Some cases that a where clause may be useful:

• Sanity checks for parameters:

simple_sanity_check :: proc(x: [2]int)
	where len(x) > 1,
		  type_of(x) == [2]int {
	fmt.println(x)
}

• Parameter polymorphism checks for procedures:

cross_2d :: proc(a, b: $T/[2]$E) -> E
	where intrinsics.type_is_numeric(E) {
	return a.x*b.y - a.y*b.x
}
cross_3d :: proc(a, b: $T/[3]$E) -> T
	where intrinsics.type_is_numeric(E) {
	x := a.y*b.z - a.z*b.y
	y := a.z*b.x - a.x*b.z
	z := a.x*b.y - a.y*b.x
	return T{x, y, z}
}

a := [2]int{1, 2}
b := [2]int{5, -3}
fmt.println(cross_2d(a, b))

x := [3]f32{1, 4, 9}
y := [3]f32{-5, 0, 3}
fmt.println(cross_3d(x, y))

// Failure case
// i := [2]bool{true, false}
// j := [2]bool{false, true}
// fmt.println(cross_2d(i, j))

• Solving disambiguations with polymorphic procedures in a procedure grouping:

foo :: proc(x: [$N]int) -> bool
	where N > 2 {
	fmt.println(#procedure, "was called with the parameter", x)
	return true
}

bar :: proc(x: [$N]int) -> bool
	where 0 < N,
		  N <= 2 {
	fmt.println(#procedure, "was called with the parameter", x)
	return false
}

baz :: proc{foo, bar}

x := [3]int{1, 2, 3}
y := [2]int{4, 9}
ok_x := baz(x)
ok_y := baz(y)
assert(ok_x == true)
assert(ok_y == false)

• Restrictions on parametric polymorphic parameters for record types:

Foo :: struct($T: typeid, $N: int)
	where intrinsics.type_is_integer(T),
	      N > 2 {
	x: [N]T,
	y: [N-2]T,
}

T :: i32
N :: 5
f: Foo(T, N)
#assert(size_of(f) == (N+N-2)*size_of(T))

Basic idioms

bar := condition ? 1 : 42

bar := 1 if condition else 42

DEBUG_LOG_SIZE :: 1024 when ODIN_DEBUG else 0

if str, ok := value.(string); ok {
	...
} else {
	...
}

Foo :: struct {
	f: f32,
	i: i32,
}

foos := make([]Foo, num)

// By-value basic range-based loop, with implicit indexing
for v, j in foos {
	fmt.println(j, v, v.f, v.i)
}

// Alternative range-based loop, with explicit indexing
for _, j in foos {
	foo := foos[j] // copy
	fmt.println(j, foo, foo.f, foo.i)
}

// By-reference range-based explicit indexing loop
for _, j in foos {
	foo := &foos[j] // "reference", changes to `foo.f` or `foo.i` are visible outside this scope
	fmt.println(j, foo, foo.f, foo.i)
}


// By-reference range-based loop
for &v, j in foos {
	v.f += 1 // `v` is a reference to the element; changes are visible outside this scope
	fmt.println(j, v, v.f, v.i)
}

cond := false
defer {
	if cond { fmt.println("c") } // This will print last.
}
defer if cond {
	fmt.println("b") // This will print after "a".
}
defer {
	// This is first evaluated, allowing the prior `defer`s to act, as evaluation
	// happens in reverse declaration order.
	cond = true
	fmt.println("a") // This will print first.
}

halve :: proc(n: int) -> Maybe(int) {
	if n % 2 != 0 do return nil
	return n / 2
}

half, ok := halve(2).?
if ok do fmt.println(half)       // 1
half, ok = halve(3).?
if !ok do fmt.println("3/2 isn't an int")

n := halve(4).? or_else 0
fmt.println(n)                   // 2

Advanced idioms

Subtype polymorphism with run-time type-safe down-casting:

Entity :: struct {
	id:   u64,
	name: string,

	variant: union{^Frog},
}

Frog :: struct {
	using entity: Entity,
	volume: f32,
	jump_height: i32,
}


new_entity :: proc($T: typeid) -> ^T {
	e := new(T)
	e.variant = e
	return e
}

entity: ^Entity = new_entity(Frog)
switch e in entity.variant {
case ^Frog:
	fmt.println("Ribbit:", e.volume)
}