Contents

Hello! If you've been trying to learn the Odin Programming Language, but feel like there are basic concepts that you don't fully understand, then this book is for you. Also, if you have never programmed in Odin before, but have some basic programming experience, then this book should be a good starting point as well.

I wouldn't say there is one big reason for learning Odin, but rather a big number of small reasons. Odin doesn't try to fundamentally solve any new problems. There are many "big agenda" languages out there, meaning languages that try to introduce completely new ways of thinking about programming. Odin is not one of them. The reasons for learning Odin may vary depending on your background. Here are two examples of such backgrounds:

If you come from a higher level language such as C#, JavaScript or Python, but want to learn a low level language, where performance and control is easily attainable, then Odin may be for you. I think it is a great first low level language. Odin's modern features and simplicity cuts out some noise you find in older low level languages. This makes the programming fun and lets you focus on the low level concepts, without getting overwhelmed. I usually say that Odin is "low level with high level feeling".

If you've used the C Programming Language, but don't find it as fun to program in as it could be, then Odin may be for you. I have worked on big video game engines written in C. I would say that Odin point-for-point addresses many of the issues I've had with C, while also incorporating some of my favorite C best practices, straight into the language.

If you don't know C or C++, then don't be intimidated by the "From C / C++" bubble just before this paragraph. I try to keep most information that assumes you know C or C++ within those bubbles. They are safe to skip.

As a final answer to "Why learn Odin?", I'll give a short anecdote: In 2023-2024 I used Odin to create my own video game: CAT & ONION. Never before have I been able to finish and ship a whole game, all by myself. In the past I always felt some degree of friction from whichever programming language I used. That friction usually built up over time, until I dropped the project. With Odin enough friction was removed, making it possible for me to ship something.

Let's talk a bit about what Odin is, so you have some reasonable expectations before reading more.

Odin is a compiled language. You have to run the source code through the Odin compiler to produce an executable, that you can later run without having to involve the Odin compiler.

Odin is a simple language. Great care has been put into the design of the language, making the different parts work together as a simple whole.

Odin uses manual memory management. You manually decide the lifetime of dynamically allocated memory. This means that you are in control of when dynamic memory is deallocated. It is not done automatically for you. This gives benefits with regards to performance and memory usage. This may seem scary to programmers coming from languages that employ automatic memory management. But fear not, Odin comes with built-in ways to track memory leaks and practical ways to handle temporary memory allocations. In chapters 9 to 13 we will look at different aspects of manual memory management.

Odin is not object-oriented. Your code will mainly use procedures (functions), if-statements, loops and structs to get things done. This makes the code very simple. The object-oriented programmer will find new ways to write reusable and generic code, that in general has better performance characteristics than object-oriented code.

Odin is well suited for data-oriented programming. This means that it is easy to write Odin code that utilizes the CPU in an efficient manner. We will discuss data-oriented programming in chapter 20.

Finally, the language really gets out of the way and lets you do things your way. This is one of many reasons why "joy of programming" is marketed as an important feature of the language.

I wanted to write a book about Odin for two reasons. Firstly: Odin's online documentation is missing some things and it is not always very pedagogical. By transforming several years of Odin programming experience into a book, I aim to bridge that gap.

Secondly: I've been active within the Odin community for several years. During that time I've seen some questions and confusions over and over again. Sometimes these questions can only be properly answered if you take a step back and look at the big picture of why something in the language works the way it does.

With that in mind I decided to write this book. I want to provide holistic explanations of things people often find confusing, and in doing so provide a deep understanding.

Each chapter deals with a certain part of the language. I don't fully cover every aspect of the language. Instead, each chapter tries to explain the basics of a certain language feature, and then follow that up with more advanced topics. Some of these advanced topics are actually not hard to understand, it's just that some things may not be apparent until you've used the language for a long time. I hope that I can save you some of that time.

This book is not meant to be a "tutorial" where you follow step-by-step instructions to reach a specific outcome. Instead, I've tried to make this book enlightening: On top of explaining how to write Odin code, I also provide explanations of why things work the way they do. Sometimes I'll talk about how things work "under the hood". I strongly believe that understanding your tools will make you a better craftsperson.

I've written this book in an informal style, hoping that it can be enjoyed in its entirety. That said, if you already know Odin fairly well, then I think you can skip directly to chapter 6.

I will not go over how to install the Odin compiler. For that I refer to the official Getting Started guide on the Odin website.

After installing the compiler I assume that you have the folder where you installed it your path. Meaning that you can run odin from a command prompt or terminal anywhere on your computer.

Should you have any trouble installing the compiler, then I also have a video on the topic, targeted at Windows users:

https://www.youtube.com/watch?v=yq5VabsGz_4

If you can't figure out how to do something, and you can't find any help in this book, then I recommend checking these resources, in the order stated:

1. Check the official language overview. It is not exhaustive, but searching around in there will answer many questions.
2. Look inside demo.odin. It is an example that comes with the compiler. It showcases many different features of the language. You'll find a local copy in <odin>/examples.
3. Search in the core and base library collections. Pull the <odin>/core and <odin>/base folders into your text editor and just search around in there. Those library collections are well written and easy to read. See my video "Exploring Odin without leaving your editor" for more information.
4. Ask in the #beginners channel on the Odin Discord server. It is a chat server that has thousands of members. Many questions get answered very quickly.

Finally, you're warmly welcome to join my own Discord server (not the same as the official Odin Discord server mentioned above). It's a friendly place where you can ask questions about Odin and also discuss game development, or tell me about that typo you found in this book!

Thanks to all my supporters on patreon.com for their donations! It truly helped a lot.

Thanks to Tobias Möllstam for proof-reading.

Thanks to PythagoRascal for proof-reading.

Thanks to Bill Hall (gingerBill) for proof-reading, and for creating the Odin Programming Language!

Thanks to Geraldine Lee for proof-reading and being a stellar partner while I've been stuck with my nose in the computer.

Please don't redistribute this book without my explicit permission. If you somehow got hold of this book without paying for it, then please consider buying a copy at odinbook.com.

That's it for the introduction, enjoy the book!

/Karl Zylinski (December, 2024)

In this chapter we'll look at just about the smallest possible Odin program. It's a program that just shows the message "Hellope!" in a console. First I'll show the code and explain how to compile and run it. Then I'll talk about what each line of code does. Finally, I'll go over some points that I think are good insights related to this tiny program.

Here's the code of our tiny program:

package hellope

import "core:fmt"

main :: proc() {
	fmt.println("Hellope!")
} 

Open your favorite text editor and copy the code above into a file. Save the file as hellope.odin inside an empty folder.

Use a command prompt or terminal to navigate to the folder where you saved hellope.odin. Once inside it, type:

odin run .

Please include the period, with a space before it! This will compile your program into an executable, and then run it. The program should print "Hellope!".

Note that this is a console application. The message will be printed to the command-prompt or terminal. No graphical window will be opened.

Let's go through the program line-by-line, starting with this one:

main :: proc() {

This declares a new proc called main. Proc is short for procedure. Some languages refer to procedures as functions. The main procedure is where the program starts. The program runs from the main procedure's opening curly brace { to the closing curly brace }. I will talk more about procedures in chapter 7.

The only thing the main procedure does is print "Hellope!". It does this using the fmt package. The line

import "core:fmt"

fetches the fmt package from the core collection. The core collection comes with the Odin compiler and contains an enormous amount of useful code. The fmt package contains procedures that can print text and also format strings. The procedures inside fmt can be used by typing fmt.some_procedure_name(). In this case we use fmt.println and pass it the message to put on the screen:

fmt.println("Hellope!")

The line at the top of the program says

package hellope

This is the package name. For now, just note that this line must be the same for all Odin files within a folder. The name must also be unique project-wide, in the sense that no other imported package uses the same name. I go over this in more detail in chapter 17.

Let's now look at some interesting details about this example program.

The . in odin run . refers to the current folder. This means that the Odin compiler will take all files ending with .odin in the current folder, and compile them as a package. By default odin run . assumes that you want to create an executable program based on this package. It will look for a procedure called main inside the package, which will be the starting location of your program. When it has created the executable, it will run it.

If you had more than one Odin source file in the current folder, then all of them would be compiled as part of your program.

You can replace run with build. Meaning that you execute the following:

odin build .

This will compile your code into an executable, without running it. In both the build and run cases, you'll be able to find the resulting executable next to your Odin source files. The name of the executable will be the name of the folder.

There's no need to put a semicolon (;) at the end of each line, as is required in many other languages.

Semicolons are optional, but I would encourage to simply not use them. The absence of semicolons fits well with the aesthetics of Odin. However, you can use them if you really want to!

Also, if you really want to make sure that you don't accidentally use them by old habit, then there is a compiler flag to make any unnecessary semicolon into an error: -vet-semicolon

Packages are just folders with Odin files inside them. The folder with your hellope.odin file is one package. And from your hellope package you also import the core:fmt package, which is also just a folder. But where is that fmt folder?

It's part of the core collection. The core collection comes as source code along with the Odin compiler. This means that you can look at what the code inside it does. I encourage you to do this, as you can learn a lot from reading that code. You'll find the core:fmt package in <odin>/core/fmt. The println procedure you used can be found in fmt_os.odin within that folder.

If you want to just compile a single Odin file instead of all the files within a folder, then add the -file flag:

odin run hellope.odin -file

This treats a single file as a complete package instead of fetching all the files within a folder.

This chapter was just a quick crash course, an appetizer. Throughout this book we'll return to many of these concepts in depth.

From here on, most chapters will focus on specific areas of the language.

Odin has a syntax for declaring and assigning variables that will look unfamiliar to people coming from JavaScript, C or C#. But it might look familiar to those who have programmed in Pascal or Go.

In this chapter we'll look at how to create variables. We'll also look at how to convert variables from one type to another. As we shall see, there is something strange afoot with how plain numbers like 7 work in relation to variable types, which will bring us to talking about constants. By the end of the chapter, I hope you'll see how Odin's interplay between variables and constants creates an elegant whole.

Variables are, like the name suggests, possible to vary. Meaning that the code can change a variable's value.

You declare a variable like this:

number: int

This variable is named number. It is of type int, short for integer. Note the : between the name and the type. It is the symbol Odin uses for declarations.

Odin is a strongly typed language, meaning that the language is strict about types: You can only put integers into integer variables. You cannot change the type of a variable after it has been declared.

What value does number have? Since we didn't specify any, it will have the value zero. This is true for all variables of all types. Technically speaking, since we didn't specify any value, then the underlying memory that holds the variable's value will be all zeroes. As we'll see in the summary at the end of this chapter, this can have a few different meanings for non-numeric types.

You can assign a new value to an already existing variable:

number: int
number = 7

Note that doing number = 7 with no pre-existing variable called number, will fail to compile.

If you want to both declare a variable and assign a value to it, then you can combine the : and the = on a single line, like this:

number := 7

This creates a new variable number of type int and gives it the value 7. In this case you didn't have to say what type number should have. Instead, the type is inferred from the value on the right hand side. This means that the compiler looks at the value on the right and decides what type the variable should have based on the value. In this case the type is inferred to int.

Here's a small program that creates a variable, prints its value, changes it and then prints it again:

package variable_example

import "core:fmt"

main :: proc() {
	number := 7
	fmt.println(number) // prints 7
	number = 12
	fmt.println(number) // prints 12
} 

Note the usage of := on the line where we declare and initialize number and that we use a plain = when we later change its value.

We just saw the type int. A variable of that type can only store whole numbers. If we want to store any decimal number, meaning a number that can have a fractional part, then we can use the type f32:

decimal_number: f32

The f stands for "floating point number", usually called just "float". A floating point number is a way of representing a decimal number. The 32 means that it uses 32 bits of memory (or 4 bytes) to store the decimal number. Again, since we are not specifying a value, decimal_number will be zero by default.

When we previously wrote number := 7, then the compiler inferred number to be of type int. How can we declare a variable of type f32, but also initialize it to 7, using a single line of code? There are two ways:

decimal_number: f32 = 7

or

decimal_number := f32(7)

Both ways have the same end result. The first one looks like decimal_number: f32, but we've added = 7 at the end. In the second case we have skipped saying what type decimal_number is, and instead rely on the type being inferred from the right hand side: f32(7). This means that we take 7 and cast it, or convert it, to the type f32.

A decimal number can of course have a decimal point followed by a fractional part:

decimal_number: f32 = 7.42

But what happens if we do the following?

decimal_number := 7.42

In this case decimal_number will be inferred to have the type f64, not f32.

So when you write decimal_number := 42.07, then there seems to be some kind of default choice of for giving it the type f64. We shall soon see where these default choices come from.

Now we'll get to the stuff that may initially seem strange, but will end up being very useful once you get it. The following code compiles just fine:

number := 7
decimal_number: f32 = 7

However, the next snippet does not compile. It will complain that it cannot automatically convert int to f32:

number := 7
decimal_number: f32 = number

Why is that? At a surface level, 7 seems to be of type int because typing number := 7 makes a variable of type int, where the type int is inferred from the 7 on the right hand side. But this does not make any sense because you can also assign 7 to a variable of type f32 without an error:

decimal_number: f32
decimal_number = 7

As I've said Odin is strongly typed, so if 7 was of type int then assigning it to an f32 would be a compilation error.

The answer is that a plain 7 is not of type int. It is a constant, and constants have a slightly different system for types than variables do. To understand this fully, let's take a step back and talk about what constants are.

Constants are things that only exist at compile time. Since they only exist at compile time, they cannot be changed while the program is running.

I already said that a plain number like 7 is a constant. But you can also create named constants:

CONSTANT_NUMBER :: 12

We use :: to create named constants, not := that we used to create variables. You can assign a constant to a variable like this:

CONSTANT_NUMBER :: 12
number := CONSTANT_NUMBER

The type of number will be inferred to int. Why? The two lines above are actually identical to just typing:

number := 12

As your program is getting compiled, you can think of named constants having their value "copy-pasted" into wherever you use their name. You can also think of a stand-alone 12 as a nameless constant.

Now, I said that constants have a slightly different type system compared to variables. One could say that constants have a slightly weaker type system. The type of CONSTANT_NUMBER :: 12 is Untyped Integer. An Untyped Integer can be implicitly converted to any integer or floating point type, as long as that type can 'accommodate' the value.

This is why decimal_number: f32 = 7 is allowed. 7 is a constant of type Untyped Integer, and that type allows for an implicit conversion (or cast) to the type f32.

What's up with the "as long as that variable can 'accommodate' the value" part above? Here's something that will not compile:

BIG_CONSTANT_NUMBER :: 100000000
small_number: i8 = BIG_CONSTANT_NUMBER

small_number is of type i8 (8 bit signed integer), the biggest value it can contain (accommodate) is 127. BIG_CONSTANT_NUMBER is a constant of type Untyped Integer. When the compiler tries to shove BIG_CONSTANT_NUMBER into small_number, then it sees that the value of this constant is bigger than 127, so it refuses to do so.

There are more Untyped Types than just Untyped Integer. Constants containing a decimal point such as DECIMAL_CONSTANT :: 27.12 are of type Untyped Float. An Untyped Float can only be assigned to a floating point variable such as f16, f32 or f64 (with one exception, which we'll see below). The code below will not compile, because we are trying to assign an Untyped Float to an integer variable. The integer variable cannot accommodate numbers with a fractional part.

DECIMAL_CONSTANT :: 27.12
my_integer: int = DECIMAL_CONSTANT

There's an exception to this. If you have an Untyped Float with all zero decimals, then it can be implicitly converted to an integer:

DECIMAL_CONSTANT :: 7.0
my_integer: int = DECIMAL_CONSTANT

We say that Untyped Floats are allowed to be implicitly converted to integers as long as they don't get truncated, meaning that no decimals get cut off.

At the end of this chapter I'll present a list of all the Untyped Types in Odin.

As I mentioned before, when we type something like

decimal_number := 13.38

then this variable will be of type f64. This default is specified by the Untyped Type system that constants use:

• CONSTANT_NUMBER :: 7 or just a plain 7 are both of type Untyped Integer. The default inferred type is int.
• DECIMAL_CONSTANT:: 42.09 or just a plain 42.09 are both of type Untyped Float. The default inferred type is f64.

These type inference defaults should not be confused with the implicit conversions that Untyped Types also allow:

decimal_number: f32
decimal_number = 7.42

This is allowed because 7.42 is an Untyped Float, which may be implicitly cast to any float type, such as f64, f32 or f16. It has nothing to do with type inference defaults.

You can give a constant a specific type, if you really want to. Note how we wedge a type between the two : below.

DECIMAL_CONSTANT: f32 : 7.42

When using this constant, no implicit type conversions will happen. You'll need to cast the constant to be able to use it as a f16 or f64.

There is a similarity between this syntax and the := syntax used with variables. Compare the line above to the one below:

decimal_variable: f32 = 7.42

In both cases the type comes after the first :. Then you put a : or a = after the type depending on if you want a constant or a variable.

The system of Untyped Types means that both these assignments are valid:

decimal_32: f32
decimal_32 = 0.5

decimal_64: f64
decimal_64 = 0.5

This may not seem like a big deal, but if you have programmed in C or C#, then you may have been annoyed with having to type 0.5f every time you want to assign 0.5 to a 32 bit floating point number.

That is because those languages have distinct types associated with literals like 0.5 and 0.5f. In C 0.5 is a 64 bit floating point number and 0.5f is a 32 bit floating point number. Odin delays that choice of distinct type, leaving 0.5 untyped for as long as possible, until it really needs to choose a type for it.

We've seen the types f32, f64 and int. We refer to these as basic types, because they are built right into the language itself. There are more basic types in Odin. Here are some of them:

• Types: int i8 i16 i32 i64 i128
• Possible values: Negative and positive whole numbers.
• int is equivalent to i64 on a 64 bit computer and i32 on a 32 bit computer etc.

• Types: uint u8 u16 u32 u64 u128 uintptr
• Possible values: Positive whole numbers (including zero).
• uint is equivalent to u64 on a 64 bit computer and u32 on a 32 bit computer etc.
• uintptr is a special unsigned integer that is always of pointer size.

• Types: f16 f32 f64
• Possible values: Positive and negative decimal numbers (numbers with a whole and a fractional part).
• More bits make it possible to store bigger and more precise decimal numbers.
• Unlike integers, you can assign however large a number you want to floats. If it is too big, then the float will take on the value positive or negative infinity.

• Types: bool b8 b16 b32 b64
• Possible values: false or true.
• Zero value: false.
• bool is equivalent to b8. It uses 8 bits, or 1 byte, of memory.
• The specific b32 etc variants are there mostly for interfacing with other programming languages. Just use bool in your Odin code.

• Type: string
• Possible values: Text encoded as UTF-8
• Zero value: "" (empty string)
• There's also a cstring type for interfacing with the C programming language. There are procedures in core:strings to convert back and forth between string and cstring.
• There's a whole chapter on strings.

• Type: rune
• A single UTF-8 string code point (in many cases a single character, but can be part of a grapheme cluster. More about that in the strings chapter).
• Internally a 32 bit signed integer.

You'll find some additional basic types in the official overview.

Untyped Types are the types used by constants. Since constants only exist at compile time, so do Untyped Types.

There are six kinds of Untyped Types. Each has its own rules for what kind of implicit conversions it allows. Also, each Untyped Type has a default type to pick when type inference occurs.

• The type of any constant of value true or false.
• Can be implicitly cast to any boolean type such as bool, b32, b64 etc.
• Inferred type of some_variable := true is bool (equivalent to b8).

• The type of any numeric constant without a period, such as 7.
• Can be implicitly cast to any integer or floating point type given that the type can accommodate the value. For example some_variable: i8 = 10000 will not compile because the type i8 cannot store numbers bigger than 127.
• Inferred type of some_variable := 7 is int (equivalent to i64 on 64 bit systems).

• The type of any numeric constant with a period, such as 7.42.
• Can be implicitly cast to any floating point type. Can also be implicitly cast to an integer type, but only if all decimals are zero.
• Inferred type of some_variable := 23.12 is f64 (on all systems, even on a 32 bit computer).

• The type of any string constant, meaning something between two quotation marks "a_string" or between two backticks `can be multi-line`.
• Can be implicitly cast to string and cstring.
• Inferred type of some_variable := "Hellope" is string.

• The type of any single character constant, such as 'A'.
• Can be implicitly cast to the type rune but also to any integer type that can accommodate the underlying numerical value.
• Inferred type of some_variable := 'A' is rune.

• The type of nil.
• Can be implicitly cast to anything that supports being in a "nil state". Such as: pointers, enums and unions.
• Cannot be used with type inference. some_variable := nil will not compile.

I've made a video where I explain how the Untyped Types system works:

https://www.youtube.com/watch?v=qLYga3iCmt0

As mentioned in the introduction, I assume that you have done some programming before. But it doesn't have to be any deep knowledge. Having seen variables, procedures (functions), if-statements, arrays and loops should be enough.

We've already looked at variables. But before we go on, let's take a quick look at procedures, if statements, loops and fixed arrays.

I will return to procedures and fixed arrays in more depth later, this chapter is just here to make sure everyone is on the same page. If you have programmed in Odin before, you can probably skip this chapter.

We've already seen the main procedure, where our program starts.

You can declare as many procedures as you want. You can add parameters to procedures, making it possible to supply data into the procedure. You can also add return values to procedures, so that the procedure can output data.

Here's a procedure with two parameters and a single return value:

is_bigger_than :: proc(number: int, compare_to: int) -> bool {
	return number > compare_to
}

This procedure accepts two integer parameters: number and compare_to. All it does is check if number is bigger than compare_to and then returns the answer. The return values are listed after the ->. In this case the return value is of type bool.

We can run, or call, is_bigger_than and store the return value in a new variable:

result := is_bigger_than(3, 2)

In which case result will be a variable of type bool that contains the value true (since 3 is bigger than 2). The type bool is inferred from the right hand side, in this case from the return type of is_bigger_than.

In the chapter on procedures we'll look at multiple return values, named return values and what the scope of a procedure is.

Odin's if statements look like this:

if condition {
	// Code in here will run if `condition`
	// is true.
}

condition must be a value of type bool. If the condition is true, then the code between the curly braces {} will run.

As an example, you can use an if-statement to check if a variable has a specific value:

some_variable := 7

if some_variable == 7 {
	fmt.println("It's seven!")
}

Here == is a comparison operator. The result of a comparison operator is a value of type bool. Available comparison operators are:

== // left and right are equal
!= // left and right not equal
<  // left is less than right
<= // left is less than or equal to right
>  // left is greater than right
>= // left is greater than or equal to right

You can use left || right to check if left or right are true. Also, you can use left && right to check if left and right are true. Note that && is evaluated before ||. We say that && has precedence over ||. You can use parenthesis to override the precedence:

if var1 == 7 && (var2 == 12 || var3 == 42) {
	// In here var1 is 7. And at least one
	// of the following is true:
	// var2 is 12 OR var3 is 42
}

Note that && and || are short-circuiting. If you do x && y then y will not even be considered if x is false. Similarly: If you do x || y then y will not be considered if x is true. This is especially important when using conditions that are return values from procedures:

if var == 7 && some_proc() {
	// var is 7
	// some_proc() returned true
}

In this example some_proc() won't run at all if var is not equal to 7.

You can "flip" the value of a bool using !, causing true to become false and vice-versa.

some_variable := 7
my_condition := some_variable == 7

if !my_condition {
	fmt.println("some_variable is not 7")
}

if statements can be followed up with else if and else branches:

if some_variable > 7 {
	// some_variable is larger than 7
} else if some_other_variable == 2 {
	// some_variable is less or equal to 7
	// and some_other_variable is 2
} else {
	// some_variable is less or equal to 7
	// and some_other_variable is not 2
}

If statements without curly braces are not allowed. This will not compile:

if some_variable == 7
	some_proc()

However, you can write:

if some_variable == 7 { some_proc() }

alternatively you can use do:

if some_variable == 7 do some_proc()

I tend to just write the full three lines:

if some_variable == 7 {
	some_proc()
}

Some people like putting the { on a separate line. If you do that then perhaps the if X do stuff() syntax is more useful, since 4 lines can be a bit much. However, I recommend keeping the { on the same line as if because it plays nicer with Odin's lack of semicolons.

Odin has many different types of loops, but they all use the same keyword: for

This loop runs forever:

for {
	fmt.println("Printed over and over, forever")
}

In order to stop it, you can use the break keyword:

for {
	if condition {
		break
	}

	fmt.println("Printed over and over, until 'condition' becomes true")
}

Instead of using break, you can have a condition on the for line. Also, note that this "inverts" the condition: In the previous example the loop runs until condition becomes true. The following loop runs until condition becomes false.

for condition {
	fmt.println("Printed over and over, until 'condition' becomes false")
}

The following loop runs as long as the variable i is less than 10. It increases i by 1 for each lap:

i := 0
for i < 10 {
	fmt.println(i) // 0, 1, 2, 3, 4, 5, 6, 7, 8, 9
	i += 1
}

You can modify the loop above and move the i := 0 and i += 1 into the for line:

for i := 0; i < 10; i += 1 {
	fmt.println(i) // 0, 1, 2, 3, 4, 5, 6, 7, 8, 9
}

The loop above is a classic "for loop" as you might have seen them in other languages. Odin provides a more compact way of doing the same thing:

for i in 0..<10 {
	fmt.println(i) // 0, 1, 2, 3, 4, 5, 6, 7, 8, 9
}

Above 0..<10 specifies a range, we'll see ranges appear in some other situations too. Note the <. It is possible to replace it with an =

for i in 0..=10 {
	fmt.println(i) // 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
}

The first version will run as long as i is less than 10. The second version will run as long as i is less than or equal to 10.

If you have two nested loops but want to stop the outer loop, then you can do so using labels. Note the outer: label and the break outer in this code:

outer: for x in 0..<20 {
	for y in 0..<20 {
		if x == 5 && y == 5 {
			break outer
		}
	}
}

Without the label, the break would stop the inner loop, not the outer one. This avoids having to use an extra variable in order to stop the outer loop.

Use continue to skip a lap of a loop:

for i in 0..<10 {
	if i == 5 {
		// skips printing "5"
		continue
	}
	fmt.println(i) // 0, 1, 2, 3, 4, 6, 7, 8, 9
}

A fixed array is a list of things where the list has a fixed length. You cannot make the list longer or shorter.

You can create a variable that holds a fixed array of 10 integers like this:

ten_ints: [10]int

All the 10 integers within ten_ints will have the value zero. You can use := to both declare and assign a value to the array:

ten_ints := [10]int {
	61, 81, 12, 41, 5, 10, 1234, 8, 4, 1,
}

You can fetch an item from the array using brackets []:

third_item := ten_ints[2]

In this case third_item will be a variable of type int with the value 12.

You can also set items using brackets:

ten_ints[6] = 7

If you want to loop over all the 10 items, or elements, then you can use this kind of loop:

for n in ten_ints {
	fmt.println(n) // 61, 81, 12, 41, 5, 10, 1234, 8, 4, 1
}

This loop goes through all the elements of ten_ints and prints each element on a separate line.

You can also loop over the elements in reverse by adding #reverse in front of the loop:

#reverse for n in ten_ints {
	fmt.println(n) // 1, 4, 8, 1234, 10, 5, 41, 12, 81, 61
}

We'll look more at fixed arrays in chapter 8. In that chapter we'll discuss where their memory lives and how to copy them. We'll also look at what array programming is, and how it can be used to do vector maths.

Here's a small program that combines most of what we've seen so far:

package just_the_basics

import "core:fmt"

main :: proc() {
	numbers := [10]int {
		6, 4, 7, 10, 1, -1, -9, 100, 1, 54,
	}

	cmp := 6

	for n in numbers {
		if is_bigger_than(n, cmp) {
			fmt.printfln("%v is bigger than %v", n, cmp)
		}	
	}
}

is_bigger_than :: proc(number: int, compare_to: int) -> bool {
	return number > compare_to
}

This program creates a fixed array of 10 numbers. It loops over the fixed array and checks if the elements of the array are bigger than 6. For any element bigger than 6, it prints a message saying so.

As an exercise to make sure you understood this chapter, look at the program above and try to figure out what it will print without running it. Then run it to get the answer.

So far we've seen basic types such as int and f32. Let's look at how you can group such basic types into bigger, more complex types called structs. The benefit of using structs is that you can reason about them as a single thing rather than a bunch of separate tiny pieces.

In this chapter we'll also look at some additional ways to create new types, such as enums and unions. As we shall see, unions can be used to save memory, but also to create variations within structs.

A struct consist of a number of fields, where each field has a type and a name. You can see structs as a way to group variables. Let's say that we want to store the data for a rectangle. A rectangle needs a position in two dimensions (x and y), a width and a height. We can define a new struct type that contains those four things:

Rectangle :: struct {
	x: f32,
	y: f32,
	width: f32,
	height: f32,
}

Each field looks like a variable declaration, but with a comma at the end of each line.

Here we see the double colon (::) again. So far we have seen three different things use ::. Those are procedures, constants and now struct definitions. All these things are known at compile time. So whenever the compiler sees anything defined using ::, then it will be able to reason about it at compile time. In other words, :: means that you are doing a compile-time declaration.

The above just defines a new type Rectangle. In order to actually use Rectangle to store any information, we can create a variable of that type:

rect: Rectangle

This is similar to writing number: int. But the type Rectangle is a more complicated type than just a single integer.

The four fields x, y, width and height will be zero initialized.

If you want to initialize the rect when you create it, then you can use the good old := syntax:

rect := Rectangle {
	width = 20,
	height = 10,
}

This rect will have its width and height fields set to 20 and 10 respectively. Any field not mentioned will be zero-initialized. In this case the fields x and y will both be zero.

Note that we could also have written

rect: Rectangle = {
	width = 20,
	height = 10,
}

Here we have moved Rectangle between the : and the = instead of after the =. But doing rect := Rectangle { whenever possible is usually considered more idiomatic Odin. Doing so will make your code look more consistent since there will be cases when you must do Rectangle { /* initializers */ } without there being a variable.

You can replace the value of a whole struct by assigning to it, effectively re-initializing it:

rect := Rectangle {
	width = 20,
	height = 10,
}

// a bit later

rect = {
	x = 10,
	width = 5,
	height = 7,
}

Just like with basic types, we use := on the line were we declare and set the initial value of rect. But when we want to give the preexisting rect variable a new value, then we only use =.

Also note that we did not have to supply the type name Rectangle on the rect = { line. The compiler sees that we are assigning to a variable of type Rectangle so we do not need to type it.

You can also initialize structs by just writing the values directly, without providing the field names:

rect := Rectangle {
	20, 20,
	200, 200,
}

This sets x, y, width and height of our Rectangle to the values in the order they are listed. When initializing in this way, without using specific names, then you must list all the fields. In this case you must provide four numerical values since there are four fields in Rectangle.

In Rectangle, we only used the basic type f32 for our struct fields. But the fields can also use struct types:

Person_Stats :: struct {
	health: int,
	age: int,
}

Person :: struct {
	stats: Person_Stats,
	name: string,
}

Here we declare a type Person that has two fields. The stats: Person_Stats field uses another struct type.

Just as before, if we type:

p: Person

then p will be of type Person and all the fields inside it will be zero-initialized. This means that all the fields within stats will also be zeroed.

You can do nested initialization of the stats field when initializing a Person struct:

p := Person {
	stats = {
		health = 7,
	},
	name = "Bob",
}

All the non-mentioned fields will be zero.

You can fetch and set the fields inside the struct using . (a period):

p := Person {
	stats = {
		health = 7,
	},
	name = "Bob",
}

p.name = "Bobinski"
p.stats.age = 36
bobinskis_health := p.stats.health

Note the last line: We are creating a new variable by fetching the health field. The type of bobinskis_health will be inferred to int, since the health field uses that type.

In the previous example we used p.stats.age to fetch the age field of the Person_Stats within the Person.

You can make age directly accessible on p, so that you just have to write p.age. This is possible thanks to the using keyword:

Person_Stats :: struct {
	health: int,
	age: int,
}

Person :: struct {
	using stats: Person_Stats,
	name: string,
}

The only difference between this and the earlier definition of Person is that I've added using in front of stats: Person_Stats.

You can now use the fields of stats directly on a Person object:

p := Person {
	health = 20
}
p.age = 70

hs := p.health

Let's say that we are making a video game where there is a concept of an entity. This entity can be represented by a struct. Our entity needs some kind of identifier and a 2-dimensional position:

Entity :: struct {
	id: int,
	position: [2]f32,
}

Now, say that we have a player character in the game. It is controlled by whoever is playing the game. You might then want this player to also "be an entity", meaning that you want it to be possible to pass the player to procedures that expect a parameter of type Entity.

You can achieve this by putting using entity: Entity at the top of the Player struct, and then follow it with additional fields that are unique to the player:

Player :: struct {
	using entity: Entity,
	can_jump: bool,
}

We can now create a player and use the id and position on it directly:

p := Player {
	id = 7,
	position = {5, 2},
	can_jump = true,
}

fmt.println(p.position) // [5, 2]

Furthermore, you can use p as if it was of type Entity:

p := Player {
	id = 7,
	position = {5, 2},
	can_jump = true,
}

print_position :: proc(e: Entity) {
	fmt.println(e.position) // [5, 2]
}

print_position(p)

Notice how print_position has one parameter. That parameter is of type Entity. But we didn't need to do any conversion when we sent in p into print_position, even though p is of type Player. Instead, the entity field inside the player is implicitly sent along because of the using entity: Entity field.

If you come from something like C++ or C#, then you might be used to the concept of a class. You might also be used to being able to define procedures within classes and structs, usually referred to as methods. There are no classes or methods in Odin, only structs and separate procedures. A procedure cannot be defined within a struct. Use structs to store data and procedures to process data.

However, you can do something like this in order to store a procedure within a struct:

My_Interface :: struct {
	required_name_length: int,
	is_valid_name: proc(My_Interface, string) -> bool,
}

my_proc :: proc(i: My_Interface, name: string) -> bool {
	return i.required_name_length == len(name)
}

my_interface := My_Interface {
	required_name_length = 5,
	is_valid_name = my_proc,
}

But in this case each object of type My_Interface can have a different procedure assigned to the field is_valid_name. It's just a field that is a procedure, and you can assign any compatible procedure to that field. It's not in the definition of My_Interface what that procedure actually does.

I do not recommend doing the above in order to "implement methods". It is useful in some cases where the actual implementation of a procedure is unknown or somehow abstract. However, this is very rarely the case.

In general, just use structs and separate procedures. Embrace this. It will make your code nice and simple.

Sometimes you need to classify something by associating it with a name. But it would be good if that name had some simple underlying representation, such as just being represented by a number. This is what enums, short for enumerations, do.

You can define new enum types. Each enum type declares a series of members, which are actually just named numbers.

Create an enum type like so:

Computer_Type :: enum {
	Laptop,    // value 0
	Desktop,   // value 1
	Mainframe, // value 2
}

Create a variable of this enum type like so:

ct: Computer_Type

Since we didn't initialize ct, it is zero-initialized. As we see in the definition of Computer_Type, the first member (Laptop) has the value 0. This means that ct was set to Laptop when it was zero-initialized.

You can assign any of the three members we listed in Computer_Type to ct:

ct = .Mainframe

Which is equivalent to writing:

ct = Computer_Type.Mainframe

But the compiler knows that the type of ct is Computer_Type, so it's OK to skip that part.

You can use switch to do different things based on the enum's current value:

switch ct {
case .Laptop:
	fmt.println("It's a laptop")

case .Desktop:
	fmt.println("It's a desktop")

case .Mainframe:
	fmt.println("Wow, a mainframe, in 2024?")
}

You can use if-statements to achieve the same result:

if ct == .Laptop {
	fmt.println("It's a laptop")
} else if ct == .Desktop {
	fmt.println("It's a desktop")
} else if ct == .Mainframe {
	fmt.println("Wow, a mainframe, in 2024?")
}

However, the switch version is less chatty and usually faster since the compiler can generate simpler code for it.

A switch must list all members of the enum. If you want to skip some of them, then put #partial in front of switch:

#partial switch ct {
case .Laptop:
	fmt.println("It's a laptop")

case .Desktop:
	fmt.println("It's a desktop")
}

I avoid #partial unless I have a good reason to use it. By avoiding it I'll get a compile error whenever I add new members to the enum. This makes it easy to find all those switch statements and add in some new code. If you don't need to do anything for a specific enum member, then you can just add a case that does nothing.

In the previous example, we had an enum with three members. The first one had value 0, the second had 1, etc. However, you can associate a member with an explicit value. Note how it now says Laptop = 1 in the following example:

Computer_Type :: enum {
	Laptop = 1, // value 1
	Desktop,    // value 2
	Mainframe,  // value 3
}

Now the first member Laptop has the value 1, and then it counts from there. Desktop has the value 2, etc.

If you wish, you can give all members explicit values:

Computer_Type :: enum {
	Laptop = 1, 
	Desktop = 2, 
	Mainframe = 7, 
}

Any time you specify an explicit value, then the members that follow will count on from that explicit value (given that they don't have an explicit value themselves):

Computer_Type :: enum {
	Laptop = 0,    // value 0 
	Desktop,       // value 1
	Mainframe = 5, // value 5
	Broken,        // value 6
	Gamer_Rig,     // value 7
}

By default enums use int as the 'backing type'. This means that behind the scenes an enum uses an int to store the current value. You can specify a custom backing type by adding a type name after enum:

Animal_Type :: enum u8 {
	Cat,
	Rabbit,
}

Note how it says enum u8. This enum will use an unsigned 8 bit integer as backing type.

In most cases, I recommend just going with the default of int. A situation where I would use a specific backing type is when I create bindings to libraries written in other languages, as the size of the enum must match what the library expects.

You can assign a value to an enum. But it does not let you store any additional data related to the current value. In Odin, unions let you store both what something is (like an enum), and also some data associated with the current value. Here's an example:

My_Union :: union {
	f32,
	int,
	Person_Data,
}

Person_Data :: struct {
	health: int,
	age: int,
}

val: My_Union = int(12)

The three fields inside My_Union :: union {} are type names. This means that My_Union can hold a value of any of the three types f32, int or Person_Data. The union stores both which type it currently holds as well as the actual data for that type. In the example above we create a new variable val of the union type My_Union and assign int(12) to it. The union then knows that it contains an int and it also knows that the value is 12.

You can assign a new value to val, for example a Person_Data object:

val = Person_Data {
	health = 76,
	age = 14,
}

After this the union val knows that it contains a value of type Person_Data and that this Person_Data has the fields health and age set to 76 and 14 respectively.

The different possible types, such as f32 and Person_Data above, are referred to as the variants of the union.

The My_Union type will only use as much memory as the biggest variant. It can only contain one of the variants at a time, so it can use the same block of memory for all of them. You can think of it as three different variables that all share the same memory, but you're only allowed to use one of them at a time.

The biggest variant of My_Union is Person_Data, which uses 16 bytes of memory. Therefore, a variable of type My_Union uses 16 bytes to store its data. It also needs 8 additional bytes to store the tag. The tag keeps track of which variant it currently holds. More on the tag in a bit. This means that the total size of My_Union is 24 bytes, which you can confirm by printing size_of(My_Union):

fmt.println(size_of(My_Union)) // 24

Just like with an enum you can use switch to branch on the value currently held by a union:

switch v in val {
case int:
	// You can use v, it is of type int.

case f32:
	// You can use v, it is of type f32.

case Person_Data:
	// You can use v, it is of type
	// Person_Data. You can use v to access
	// the fields of Person_Data:
	fmt.println(v.age)
}

When comparing this to the switch statement we used with an enum, there are two differences to note:

• It says v in on the line switch v in val {. For an enum we just say switch some_enum {.
• The case labels are the union variant type names.

Only the case that matches the union's current variant will run. So if the program ends up inside case Person_Data: then you know that the union val is of variant Person_Data, and you can also access the data of that variant by typing v.

If you wish to make v modifiable within the case, then you need to add an & in front of v:

switch &v in val {
case int:
	v = 7

case f32:
	v = 42

case Person_Data:
	v.age = 7
}

Sometimes you're only interested in checking if the union is holding one specific variant. In that case you don't need a whole switch statement, the following will be enough:

f32_val, f32_val_ok := val.(f32)

if f32_val_ok {
	// f32_val is OK to use in here.
}

We use val.(f32) to check if the variant of the union val is of type f32. If it is then f32_val_ok contains true and f32_val contains the value.

However, the code above is a bit awkward because it litters the surrounding code with the variables f32_val and f32_val_ok. To avoid that, I recommend this special type of if-statement:

if f32_val, f32_val_ok := val.(f32); f32_val_ok {
	// f32_val is OK to use in here.
}

This if-statement first creates the two variables f32_val and f32_val_ok, then the part after the ; checks the actual condition. f32_val and f32_val_ok are only available within the if-statement, not outside of it.

You can also just do f32_val := val.(f32), skipping the f32_val_ok variable. But this means that you are expecting val to have a variant of type f32. If it doesn't, then your program will assert, which is a fancy way to say "crash with an error".

Finally, if you wish to modify the value, then you can add in an & just before val.(f32):

if f32_val, ok := &val.(f32); ok {
	f32_val^ = 7
}

In this case adding the & makes f32_val into a pointer. We haven't talked about pointers yet, but it's essentially an address to a value of type f32. The f32_val^ = 7 above changes the value which the pointer f32_val points to. I will discuss pointers more in the next chapter.

Say that you have a union of two structs, like so:

Shape :: union {
	Shape_Circle,
	Shape_Square,
}

Shape_Circle :: struct {
	radius: f32,
}

Shape_Square :: struct {
	width: f32,
}

// Zero value: nil
shape: Shape

Since we didn't provide a value when we wrote shape: Shape, it is default-initialized to zero. In this case the zero value is interpreted as nil. This means that your union does not have a value of any variant at all.

We can compare this to the zero value of an enum:

Shape :: enum {
	Circle,
	Square,
}

// Zero value: Shape.Circle
shape: Shape

This enum shape will have the value 0, which is equal to Shape.Circle.

It is possible to make unions behave in the same way as enums, meaning that it is possible to make unions use the first variant as the zero value. If we add #no_nil to the declaration of our union. Then it cannot be nil, the zero value is then instead the first variant:

Shape :: union #no_nil {
	Shape_Circle,
	Shape_Square,
}

Shape_Circle :: struct {
	radius: f32,
}

Shape_Square :: struct {
	width: f32,
}

// Zero value:
// Variant Shape_Circle
shape: Shape

In this case shape will be of variant Shape_Circle.

Let's talk a bit about how unions work under the hood. This will make us understand how #no_nil and the zero value of unions work. This is also important if you ever want to save the value of a union to a file.

The way a union keeps track of which variant it currently holds is by something known as a tag. This tag is part of the internal workings of the union. It is not readily accessible.

So if we have a union like this one, that can be nil:

Shape :: union {
	Shape_Circle,
	Shape_Square,
}

then there are three possible tag values:

• 0 -> nil
• 1 -> Shape_Circle
• 2 -> Shape_Square

When we write

shape: Shape

then the whole union is zero-initialized, including the tag. Which means that the union is interpreted as having the value nil.

On the other hand, if we add #no_nil:

Shape :: union #no_nil {
	Shape_Circle,
	Shape_Square,
}

then there are two possible tag values:

• 0 -> Shape_Circle
• 1 -> Shape_Square

So now when we write shape: Shape and get a zero-initialized union, then the tag says it is of variant Shape_Circle instead. Also, note that the data block that holds the actual memory for the variants is also zero initialized, so the fields inside Shape_Circle are also all zeroed.

There's a special type in Odin called Maybe. Variables of that type can either have no value, or some value. It's implemented using a union that has a single variant:

Maybe :: union($T: typeid) {
	T,
}

So when you type:

time: Maybe(int)
fmt.println(time) // nil
time = 5
fmt.println(time) // 5

Then time can either be nil or have a value of type int. You can check if time has some value like so:

if time_val, time_val_ok := time.?; time_val_ok {
	// Use time_val.
}

This time.? syntax is the same as writing time.(int). But since the Maybe only has a single variant then the compiler fills the type in for you.

You can also skip the ok value on the left side:

t := time.?

In that case the program will assert (crash with error) if time is nil.

The style of unions in Odin are known as tagged unions, because there is a tag inside it that keeps track of which variant it currently holds.

In C, union also exists, but it is a bit simpler. It has no tag, so you have to use an extra variable to keep track of which variant it currently holds. A common approach in C is to use both an enum and a union.

In Odin you can create these C-style unions, they are known as raw unions. You create them by putting #raw_union on a struct:

My_Raw_Union :: struct #raw_union {
	number: int,
	struct_val: My_Struct,
}

a_raw_union: My_Raw_Union

Note: We used struct, not union! There's no safety here that tells us which variant a_raw_union currently holds. You can access either variant by typing a_raw_union.number or a_raw_union.struct_val.

What #raw_union does is that it makes all the fields inside the struct start at the same point in memory, making them overlap. This is the same as the data block in the tagged union, but without the tag. So you need some extra variable to keep track of the current variant.

Again, say that you're making a video game and you have an Entity struct that represents an object in your game world:

Entity :: struct {
	position: [2]f32,
	texture: Texture,
	can_jump: bool,
	time_in_space: f32,
}

Here the first two fields sound nice and general: A 2D position that tells us where the entity is, and a texture (an image) that is used for drawing it on the screen.

However, let's say can_jump is only used when Entity represents the player character, and time_in_space is only used when Entity represents a rocket flying through space.

We can save space in the Entity struct by moving those things into a union:

Entity :: struct {
	position: [2]f32,
	texture: Texture,
	variant: Entity_Variant,
}

Entity_Player :: struct {
	can_jump: bool,
}

Entity_Rocket :: struct {
	time_in_space: f32,
}

Entity_Variant :: union {
	Entity_Player,
	Entity_Rocket,
}

So now when you create an entity, you can set the variant of it to an appropriate type:

player_entity := Entity {
	position = starting_position,
	texture = player_graphics,
	variant = Entity_Player {
		can_jump = true,
	}
}

Earlier I showed how the using keyword can make Entity into a "parent type" of some other struct. If you compare the two approaches you see that they solve a similar problem, but in different ways. Whatever problem you're trying to solve, try several methods and see which works best for you.

I have an video on using unions to create state machines:

https://www.youtube.com/watch?v=bGc7C3U89-I

Sometimes you need your code to directly modify the value of a variable that lives somewhere else. You can do that using what's known as a pointer.

A pointer is a reference. It is used to "point out" something else in memory. Internally it contains the memory address of that "something else".

Let's look at a few examples. Each section in this chapter gets a little bit more advanced. If you're new to all these things, then don't worry if it takes a while to grasp. I will also discuss topics that involve pointers in later chapters. This is just an introduction.

The final section called Under the hood: Addressables is less about pointers, and more about demystifying how the compiler does operations involving pointers.

Say that we have an integer variable and we want to make a procedure that can directly add 1 to that variable for us. We can do that using a procedure that accepts a pointer to an integer. Such a procedure can then use that pointer to directly modify the value of the integer. It will go to the memory address that the pointer contains and add 1 to the number it finds there. Here's how you can write that:

increment_number :: proc(num: ^int) {
	num^ += 1
}

number := 7
number_pointer := &number
increment_number(number_pointer)
fmt.println(number) // 8

number := 7 creates a variable number of type int that contains 7. Note the & on the next line:

number_pointer := &number

The & fetches the memory address of number. This means that the variable number_pointer now contains that address. This address tells us where in the computer's memory number is stored. We can use that address to access and modify number from other parts of our code.

The type of number_pointer is ^int. Any type that contains a ^ is a pointer. ^int can be read as "pointer to integer", meaning that we expect this pointer to contain a memory address, and at that address in memory we expect to find an integer.

The procedure increment_number has a single parameter: num: ^int. That's the same type as number_pointer. So when we run increment_number and feed it number_pointer, then its parameter num contains the address of the variable number.

Inside increment_number we see this:

increment_number :: proc(num: ^int) {
	num^ += 1
}

The line num^ += 1 fetches the integer at the address that num points to, adds 1 to it and stores it back at that address. That line is equivalent to writing:

num^ = num^ + 1

above we see that num^ can be used for two different things:

• num^ = some_value writes the value on the right side of the = into that which num points to.
• num^ + 1 reads the value that num points to and adds 1 to it.

Compare the position of the ^ in these two lines:

increment_number :: proc(num: ^int) {

and

num^ = num^ + 1

• In the first case it is to the left of type name. This is how you denote a pointer type.
• In the second case it is to the right of a pointer variable's name. This is how you read or write through a pointer.

Whenever the ^ appears on the right side, we call it the dereference operator. A pointer is essentially a reference to something, meaning that it contains information about where to find something. So to dereference it means to fetch the thing it references.

Note how I use the word through in "read or write through a pointer". This is a good way to talk about pointers: You are trying to read or write something, but you must use the address inside the pointer to get there, which is like "going through the pointer".

If you create a new variable of pointer type, like this:

my_pointer: ^int

then you are declaring a pointer to an integer, without giving it a value. As usual it will be initialized to zero. But what does zero mean for a pointer? What does the zero value of a memory address represent?

Internally a pointer is just a numerical value, comparable to an unsigned integer. On most 64 bit platforms, pointers can be seen as 64 bit unsigned integers. Or a 32 bit unsigned integer on most 32 bit platforms. This is because that's the biggest address that such a computer can reason about.

So there's nothing magical about pointers. A pointer of value zero can just be seen as the number zero. This zero value means "no address", meaning that the pointer is currently not referring to anything at all. There's a special keyword in Odin to denote pointers of value zero: nil.

Trying to read or write through a nil pointer will crash your program. The code below would crash, since it tries to write 10 through a nil pointer:

my_pointer: ^int
my_pointer^ = 10

Similarly, a procedure that reads or writes through a pointer parameter will crash if you feed nil into that parameter. In our earlier increment_number procedure, we can protect against such crashes by checking if the parameter num is not nil before trying to use it:

increment_number :: proc(num: ^int) {
	if num != nil {
		num^ += 1
	}
}

You can also use == instead of != and instead do an early return:

increment_number :: proc(num: ^int) {
	if num == nil {
		return
	}

	num^ += 1
}

These examples, where we increment integers using a pointer, aren't all that useful since you'd probably just return a new number instead of bothering with a pointer. In the next section we'll look at modifying a struct through a pointer, which is a lot more useful.

In this example we'll use a procedure in order to modify a struct. We'll feed a pointer to a struct into the procedure. The procedure will modify a field of the struct through the pointer.

Here's a struct that describes a cat. It contains its name, age and color:

Cat :: struct {
	name: string,
	age: int,
	color: Cat_Color,
}

Cat_Color :: enum {
	Black,
	White,
	Orange,
	Tabby,
	Calico,
}

Below we create a new cat called "Patches". It's Patches' birthday, so we need to increment its age and print a happy message. In this example, process_cat_birthday takes a pointer to a Cat struct and increments the age field.

process_cat_birthday :: proc(cat: ^Cat) {
	if cat == nil {
		return
	}

	cat.age += 1
}

my_cat := Cat {
	name = "Patches",
	age = 7,
	color = .Calico,
}

process_cat_birthday(&my_cat)

// Hooray, Patches is now 8 years old!
fmt.printfln("Hooray, %v is now %v years old!", my_cat.name, my_cat.age)

Output of running this program is:

Hooray, Patches is now 8 years old!

Just like previously we fetch the address of a variable using the &:

process_cat_birthday(&my_cat)

The result of &my_cat is a value of type ^Cat. It's a pointer to a struct of type Cat.

Within process_cat_birthday we increment the age field by writing through the pointer:

cat.age += 1

Note where the line that prints "Hooray, Patches is now 8 years old!" is: It's after we've called process_cat_birthday. This is an important point to understand: By passing my_cat by pointer, we let process_cat_birthday modify the variable my_cat directly. In the code that follows the line process_cat_birthday(&my_cat), we can see the changes that process_cat_birthday did to my_cat.

Unlike the examples in the previous section, we didn't have to write

cat^.age += 1

When you have a pointer to a struct, and access a field of the struct through that pointer, then the ^ is implicit. cat^.age and cat.age do the exact same thing.

On the other hand, if you want to replace the the whole struct, then you need to use ^. Below we have a procedure called replace_cat that replaces all the data that its cat: ^Cat parameter points to. Note how it uses cat^ = {}.

replace_cat :: proc(cat: ^Cat) {
	if cat == nil {
		return
	}

	cat^ = {
		name = "Klucke",
		age = 6,
		color = .Tabby,
	}
}

You can't just do cat = {} without the ^. This is because assigning to a pointer means changing the address the pointer contains. In other words, assigning to a pointer means re-directing what the pointer refers to. But we want to go through the pointer and modify the memory it points to. So we have to use cat^ = {}.

As I've mentioned throughout this chapter, you can think of a pointer as just containing a number. That number is an address that points to a location in memory. In this section we'll discuss what happens when you have two pointers containing the same address. The things we discuss here are meant to give you an intuition for what a pointer really is.

In the code below we have an integer variable number. We fetch the address of number and put it in pointer1. We then create another variable called pointer2, which is a copy of the variable pointer1. We then write the number 10 through pointer2.

number := 7
pointer1 := &number
pointer2 := pointer1
pointer2^ = 10

You can think of pointer1 and pointer2 as two variables containing the exact same number: They both contain the same memory address. To modify the original variable number you can go via any of the two pointers: pointer1^ = 10 and pointer2^ = 10 would both set the variable number to 10, because they both go through the same address.

Let's think a bit about what pointer1 and pointer2 actually are. They are two separate variables. This means that they must both store a separate copy of number's address somewhere. If you fetched the address of pointer1 and pointer2 and printed it, then you would see two different addresses:

fmt.println(&pointer1)
fmt.println(&pointer2)

Note the & in front of both. The type of &pointer1 and &pointer2 is in this case ^^int, which you can read as "pointer to a pointer to an integer". The above would print something like:

0x445C6FF868
0x445C6FF860

Note that the first one ends with 8 and the second one ends with 0. The exact numbers will not be the same on your computer. But it will be two different addresses. This shows that pointers are variables just like any other: pointer1 and pointer2 have separate locations in memory for storing whatever they contain. In this case they both store a separate copy of the same memory address. At the address that they both store, you find the value of the integer variable number.

We've seen how pointers can be used to get and set the value that the pointer refers to:

// Read a value through a pointer
read_value := some_pointer^

// Write a value through a pointer
some_pointer^ = 10

When ^ appears to the right of a pointer's name, we call it the dereference operator. But what is it that ^ actually does? As we'll see, there's more going on here than just reading and writing through the pointer.

Some of the things we talk about here aren't strictly necessary to know. But it may prove useful, interesting and demystifying. Here's an example of something we'll be able to understand at the end of this section:

How can the following code get a pointer that refers to the tenth element of array?

array: [20]int
element_pointer := &array[10]

After all, doesn't array[10] fetch something of type int? If you think about it, the above kind-of looks like it does the same as this:

array: [20]int
element := array[10]
element_pointer := &element

In which case element_pointer would not point to the tenth element of array. Instead, it would point to element, which is a copy of the tenth element. But that's not what happens when you do &array[10]. Somehow &array[10] gives you a pointer directly to the tenth element of the array. This section is all about understanding how.

Let's take a step back and look at some simple examples that will give us new insights and thereafter return to the array example.

Say that we again have an integer variable number and a pointer to that variable:

number: int
number_pointer := &number

We can now assign to number through number_pointer like this:

number_pointer^ = 10

The above seems to work like this: Whenever we find number_pointer^ on the left side of an =, then it goes through the pointer and sets the value at that address.

We can also fetch the value of number through number_pointer like this:

another_number := number_pointer^

Similarly, the above seems to work like this: Whenever we find number_pointer^ to the right of := (or to the right of =), then that fetches the number the pointer refers to.

I put emphasis on seems above, because this is a surface-level explanation. It's an explanation that suffices in most cases.

But if we talk about what the compiler is actually doing internally, then we say that number_pointer^ (the whole thing including the ^) creates what is known as an addressable. As the name suggests, addressables are things that are possible to locate in memory. Addressables can be read, fetching their value. They can also be assigned to, writing their value.

So on a line like

number_pointer^ = 10

Then we write into the addressable number_pointer^ because it is on the left side of the assignment. But on a line like

another_number := number_pointer^

then the addressable number_pointer^ is read because it is on the right side of the assignment. Here another_number is actually also an addressable: It's something we can assign to.

I want to repeat and stress something here: To the compiler, number_pointer^, including the ^, creates an addressable. An addressable is an internal thing that the compiler can use to read and write into some part of memory. I like to think of addressables as the compiler's own internal version of pointers. Meaning that when we write number_pointer^, then the compiler still retains the address of whatever number_pointer points to, so you can assign to it.

There are things that are not addressables, because they cannot be assigned to. A constant number like 7 is an example. You can never assign to it, because doing:

7 = some_variable

doesn't make any sense.

Let's return to the initial example; creating a pointer to a value you've just fetched from an array:

array: [20]int
element_pointer := &array[10]

If you have an array and fetch the element at index 10 using array[10], then you might think that you've already completely lost the original memory address of that value. After all, the result of doing element := array[10] is something of type int.

But in the example above element_pointer somehow contains the direct address to the tenth element in the array. This is because array[10] is an addressable that refers to the tenth element of the array. Taking the address of an addressable, like &array[10] does, gives you this "original address".

As a final example, if you write some_pointer^ and immediately take the address of it again, then you get the original pointer back:

number := 7
number_pointer := &number
number_pointer_again := &number_pointer^
// Both these pointers refer to `number`!

Again, one could have thought that number_pointer^ gives you some in-between value and that the pointer number_pointer_again would refer to that in-between value. But no, number_pointer^ is an addressable, and taking the address of an addressable gives back the original memory address. As long as the addressable's value hasn't crossed over the =, then you still have one last chance to fetch its original address.

We've already seen the basics of how to create procedures. Most of the procedure-related concepts we have seen so far can be summarized with this example:

is_bigger_than :: proc(number: int, compare_to: int) -> bool {
	return number > compare_to
}

result := is_bigger_than(5, 2)

• is_bigger_than is a procedure.
• It has two parameters of type int. Those parameters have the names number and compare_to.
• It returns a single bool value.
• result := is_bigger_than(5, 2) calls the procedure with the arguments 5 and 2. It stores the return value in result.

Note how I use the word parameter when I talk about the things a procedure accepts, such as number: int, compare_to: int. I use the word argument when I talk about the values sent into the procedure when calling it, such as 5 and 2 in is_bigger_than(5, 2).

Let's now dig deeper into procedures. We will look at things like default parameter values, multiple return values as well as some special properties of procedure parameters.

After that we'll also discuss what the scope of a procedure is and what the stack is. We'll finish off with talking about how the defer keyword works.

You can give a parameter a default value. This makes it possible to skip that parameter when calling the procedure.

The following procedure prints a message, but it also prints Info: in front of the message.

write_message :: proc(message: string, label: string = "Info") {
	if label != "" {
		fmt.print(label)
		fmt.print(": ")
	}

	fmt.println(message)
}

If you run the procedure like so:

write_message("Hellope!")

then it will print Info: Hellope!

However, you can replace the "Info" part by providing another parameter:

write_message("Hellope!", "Very important info")

which will make it output Very important info: Hellope!

This is possible because the second parameter looks like this:

label: string = "Info"

It looks like a normal string parameter, but with = "Info" added at the end. "Info" is referred to as the default value of the parameter. Note how this uses the exact same syntax as creating a string variable with initial value "Info". You can even write

label := "Info"

and have the type of the parameter inferred from the right side.

If you have a procedure with multiple parameters that have default values, such as this one:

my_proc :: proc(a: int, b := 1, c := "hello") {

}

Then you can use named arguments to skip over b but still give c a value:

my_proc(7, c = "bye bye")

This also means that you don't have to provide the arguments in the order the parameters are stated.

These named arguments don't actually have anything to do with default parameter values. You can always use name arguments. For example, you could specify a value for a using named arguments, even though it does not have a default value:

my_proc(c = "bye bye", a = 7)

However, note that this will not compile:

my_proc(c = "bye bye", 7)

The non-named arguments are called positional arguments. All positional arguments must come before all the named arguments.

This example comes from <odin>/core/bytes/bytes.odin and mentions both allocators and slices, which we will talk about later. It's a common pattern for passing allocators that you will see over and over.

clone :: proc(s: []byte, allocator := context.allocator, loc := #caller_location) -> []byte {
	c := make([]byte, len(s), allocator, loc)
	copy(c, s)
	return c[:len(s)]
}

clone takes a slice of bytes and clones it.

In order to do this cloning it needs to allocate memory. Memory allocation is done using an allocator. Note the allocator parameter of clone:

allocator := context.allocator

Since it has the default value context.allocator, then we can just run bytes.clone with a single argument, like so:

copy := bytes.clone(some_bytes)

Giving a parameter called allocator the default value context.allocator is very common in the core collection. It gives a sensible default, while making the user understand that they can provide their own allocator, if they so wish.

To return more than one value, use multiple types after ->:

divide_and_double :: proc(n: f32, d: f32) -> (f32, bool) {
	if d == 0 {
		return 0, false
	}

	return (n/d)*2, true
}

As you can see, there are now parentheses around the two return values:

(f32, bool)

When you have more than one return value, then you must have parentheses around them.

divide_and_double divides the number n by d and then multiples the result by 2.

However, in order to avoid division by 0, it first checks if d is 0. If it is, then it returns 0 in the first return value and false in the second return value. Returning false in the second return value indicates that there was an error.

If d is non-zero, then the computation is done as expected. The result is returned in the first return value. true is returned in the second return value, indicating that everything went OK.

If you wish to store the results of this procedure, then you use two separate variables. Below we assign the two return values to res and ok.

res, ok := divide_and_double(2, 4)

if ok {
	fmt.println(res)
}

You can also completely skip handling the return values:

divide_and_double(2, 4)

If you don't like that, then you can make it required to handle the return values. This is done by putting @require_results in front of the procedure declaration:

@require_results
divide_and_double :: proc(n: f32, d: f32) -> (f32, bool) {
	// ...
}

Which makes this line an error:

divide_and_double(2, 4)

However, if you handle at least one of the return values, then you must handle all of them. The following would be an error, regardless of if @require_results is used or not:

res := divide_and_double(2, 4)

If you wish to skip assigning one of the return values, then you must explicitly assign it to the special symbol _, which means that we throw away that value:

res, _ := divide_and_double(2, 4)

Since it can be messy to litter the code with variables such as res and ok, then you can use this special if-statement, so that res and ok are only available within it:

if res, ok := divide_and_double(2, 4); ok {
	fmt.println(res)
}

This method of returning a bool in the last return value is a common way to report errors in Odin. For more complicated errors one can also use enums and unions. We'll see more of that when we talk about error handling.

You can give names to return values. In the procedure below, note how the return values look like a list of variable declarations: (res: f32, ok: bool). In fact, these named return values act just like normal variables. You can assign to them and they are zero-initialized.

divide_and_double :: proc(n: f32, d: f32) -> (res: f32, ok: bool) {
	if d == 0 {
		return
	}

	res = (n/d)*2
	ok = true
	return
}

This procedure is similar to the one in the previous section. However, here's what the old one did when d == 0:

if d == 0 {
	return 0, false
}

now we just do

if d == 0 {
	return
}

This is called a "naked return". It's a return that doesn't specify what it is returning. It means that we are returning the named return values res and ok. Since res and ok were initialized to zero by default, they contain 0 and false respectively. So this procedure does the same thing as the procedure in the previous section.

Also, the old version of divide_and_double, did this when d was non-zero:

return (n/d)*2, true

Now we do:

res = (n/d)*2
ok = true
return

However, we are not forced to use the naked return. We can still do explicit returns like before: return (n/d)*2, true, which may in fact look cleaner.

Naked returns may seem a bit strange to some people. But when we later talk about error handling, then we will make use of named return values in combination with things like or_return. In that case we will see that being able to do naked returns is a good thing.

Procedures can be declared both directly at global file scope, but also within other procedures:

do_stuff :: proc() {
	print_message :: proc(msg: string) {
		fmt.println(msg)
	}

	print_message("Hellope!")
}

Above we see the a procedure do_stuff that lives in the global file scope, but we also have a procedure called print_message within do_stuff. print_message is only available from within do_stuff. This is useful for reusing code within a procedure without having to make a globally accessible procedure. Keeping it within do_stuff keeps the global file scope tidy.

Let's look at which variables and constants that are available to use within a nested procedure such as print_message. Say that we extend the example above with a global variable, a global constant and also a local variable within do_stuff:

global_state: int
CONSTANT_NUMBER :: 7

do_stuff :: proc() {
	local_variable: int

	print_message :: proc(msg: string) {
		fmt.println(msg)
	}

	print_message("Hellope!")
}

print_message can use these things:

• The parameter msg
• The global variable global_state
• The global constant CONSTANT_NUMBER

However, print_message cannot see or use local_variable that lives in the parent procedure do_stuff. Odin does not support any such automatic capturing.

The reason for not supporting it is that you either need automatic memory management or some complicated system for copying things from the parent procedure's scope. Odin does not do automatic memory management and strives for simplicity, so no automatic capturing at all ever happens.

The reason you can always use globals is because globals live for as long as the program runs. They are not bound to the lifetime of any procedure.

All procedure parameters are always immutable. You can never change the value of a parameter. The following would not compile because we are trying to change the value of the parameter n:

divide_numbers :: proc(n, d: f32) -> f32 {
	n = n / d
	return n
}

To make the above compile, add n := n as the first line of the proc:

divide_numbers :: proc(n, d: f32) -> f32 {
	n := n
	n = n / d
	return n
}

This creates a copy of the parameter n and stores it in a variable with the same name. After that we can modify n since it is no longer a procedure parameter. You can always create a new variable with the same name as a procedure parameter. This is handy because it gives you a mutable copy without having to come up with a new name.

Although Odin's procedure parameters are immutable, you can still modify the value that pointers refer to. The following procedure modifies the value that the pointer n refer to:

increase_number :: proc(n: ^int, amount: int) {
	n^ += amount
}

What you're not allowed to do is change what n points to:

increase_number :: proc(n: ^int, amount: int) {
	some_other_int := 7
	n = &some_other_int
	n^ += amount
}

The address that the pointer contains is the thing that is immutable, not the memory it points to.

Copying large amounts of data is slow. We say that there is an overhead related to copying. It may be tempting to use procedure parameters that are pointers, in order to avoid copying. It may be especially tempting when the parameter uses a type that is a very big struct or array. However, this is not necessary in Odin: A parameter that is larger than 16 bytes is automatically passed as an immutable reference. Let's look at what this means in detail.

Say that you have a big struct such as Person below:

Person :: struct {
	name: string,
	health: int,
	age: int,
	number_of_teeth: int,
	height_meters: f32,
}

Also, say that you have the following procedure that prints some info about a Person struct:

print_person_info :: proc(p: Person) {
	fmt.printfln("%v is %v years old and has %v teeth.", p.name, p.age, p.number_of_teeth)
}

You might think that every time some code calls print_person_info, then the value you supply into the parameter p: Person is copied. In order to avoid that copying you might then change the parameter into a pointer:

print_person_info :: proc(p: ^Person) {
	fmt.printfln("%v is %v years old and has %v teeth.", p.name, p.age, p.number_of_teeth)
}

This might seem like a very reasonable thing to do. After all, Person uses 48 bytes of memory. A pointer only uses 8 bytes (on a 64 bit computer). So it may seem like there would be way less copying if you used a pointer.

However, the above is not necessary in Odin. Why? Because the size of Person is larger than 16 bytes, so it will automatically be passed as an immutable reference.

OK, so what does "immutable reference" mean? Say that you write the following:

print_person_info :: proc(p: Person) {
	fmt.printfln("%v is %v years old and has %v teeth.", p.name, p.age, p.number_of_teeth)
}

hans := Person {
	name = "Hans",
	age = 65,
	number_of_teeth = 6,
	health = 20,
	height_meters = 1.69,
}

print_person_info(hans)

When you call print_person_info(hans), then hans outside the procedure will use the exact same memory as p inside the procedure. Under the surface the compiler has passed it as a reference. However, the reference is also immutable, meaning that you cannot alter any of its fields. This makes sure that you can't accidentally modify the variable hans. This is why we say that p is an immutable reference.

You can do p := p inside the print_person_info if you want to create a modifiable local copy of p. That would be a new, unrelated variable.

If you want to actually make a procedure that modifies something, then you can use a pointer parameter. But whenever you're making a procedure that just uses some data without modifying it, then you do not need to worry about the overhead of copying.

There is something called pointer aliasing. This means that you have two pointers that somehow reference the same data. This means that changing some data through one of the pointers alters what you see through the other pointer. Sometimes this was not intended by the programmer, and may therefore introduce bugs.

Procedure parameters larger than 16 bytes will be passed as immutable references. This means that they are susceptible to similar aliasing issues. Here's an example:

Person :: struct {
	name: string,
	health: int,
	age: int,
	number_of_teeth: int,
	height_meters: f32,
}

Couple_Data :: struct {
	person_1: Person,
	person_2: Person,
}

couple_data := Couple_Data {
	person_1 = {
		name = "Hans",
		age = 65,
	},
	person_2 = {
		name = "Maj-Britt",
		age = 50,
	},
}

aliasing_example :: proc(cd: ^Couple_Data, person: Person) {
	cd.person_1 = {
		name = "This modifies 'person' too",
	}

	fmt.println(person.name) // Prints "This modifies 'person' too"
}

aliasing_example(&couple_data, couple_data.person_1)

The procedure aliasing_example accepts two parameters: cd: ^Couple_Data and person: Person. We run aliasing_example like this:

aliasing_example(&couple_data, couple_data.person_1)

As you can see we feed &couple_data into the parameter cd: ^Couple_Data of aliasing_example. Into the parameter person: Person we feed couple_data.person_1. But since the struct Person uses 48 bytes of memory, then it is automatically passed as an immutable reference.

This means that within aliasing_example the parameter person is an immutable reference to the exact same memory as cd.person_1. Modifying cd.person_1 will modify person as well.

This can cause bugs if you do not know about it. Note what happens in aliasing_example: It modifies the name field of cd.person_1 and then prints person.name. This printing will print the new name we just gave to cd.person_1, because they share the same memory.

If you have a procedure that is susceptible to such aliasing, then you can make an explicit copy of the parameter that you think would have the issue. In our example you could put person := person at the top of the procedure:

aliasing_example :: proc(cd: ^Couple_Data, person: Person) {
	person := person

	cd.person_1 = {
		name = "This no longer modifies 'person'",
	}

	fmt.println(person.name) // Prints the original name
}

Use explicit overloading to make two or more procedures exist under the same name. Here's an example of how to implement a procedure length that accepts both [2]f32 and [3]f32 arguments:

length :: proc {
	length_float2,
	length_float3,
}

length_float2 :: proc(v: [2]f32) -> f32 {
	return math.sqrt(v.x*v.x + v.y*v.y)
}

length_float3 :: proc(v: [3]f32) -> f32 {
	return math.sqrt(v.x*v.x + v.y*v.y + v.z*v.z)
}

Note the special length :: proc {} syntax. That's how you make an explicit overload. Within those curly braces, list all the procedures you want to be available under the name length.

We can then use length with any value of type [2]f32 or [3]f32:

v2 := [2]f32 { 3, 3 }
v3 := [3]f32 { 3, 3, 3}
len_v2 := length(v2)
len_v3 := length(v3)

A positive thing about explicit overloading is that we can still use a specific variant if we so wish:

v2 := [2]f32 { 3, 3 }
len_v2 := length_float2(v2)

Put @init in front of a procedure to automatically run it when your program starts. Put @fini in front of a procedure to automatically run it when your program shuts down:

package init_fini_example

import "core:fmt"

main :: proc() {
	fmt.println("Program running")
}

@init
startup :: proc() {
	fmt.println("Program started")
}

@fini
shutdown :: proc() {
	fmt.println("Program shutting down")
}

This program will print:

Program started
Program running
Program shutting down

Let's look at what a scope is and how it relates to the concept of the stack. The scope of a procedure runs from the opening curly brace { to the closing one }:

my_proc :: proc() {
	number := 7
}

This means that number in the code above is only valid within that scope. This is why the following is a classic mistake:

my_proc :: proc() -> ^int {
	number := 7
	number_pointer := &number
	return number_pointer
}

The code above will compile, but it's going to misbehave. The type of the return value is ^int, or "pointer to integer". The value we are returning is the address of the local variable number. But that variable is only valid within the scope of the procedure. So once the procedure is over, then the pointer we are returning is pointing at garbage memory. This memory may soon be used by other parts of the program.

So what is this memory that is available within the scope of the procedure. Where does number's memory live?

Each procedure has what is known as a stack frame. A stack frame is some memory that is big enough to hold the procedure's local variables, parameters and information about where to store the return values. This means that declaring a variable like number: int will reserve memory for that variable within the stack frame. How much memory? It depends on the size of the variable. In this case number is of type int, which is a 64 bit integer (on 64 bit systems). So something of type int will use 8 bytes of memory within the stack frame.

You do not need to deallocate any memory that lives within the stack frame. Each procedure that is being executed has a stack frame. These stack frames make up what is referred to as the stack. The top-most frame of the stack is the current procedure, the one just below it in the stack is the procedure that called the current procedure, and so forth, all the way down to the main procedure. When a procedure finishes, then its stack frame is destroyed, or "popped off" the top of the stack. Since all the local variables of a procedure live within the stack frame, there's no need for any kind of deallocation of those variables.

Later we shall look at dynamically allocated memory, which usually means allocating memory that lives outside of the stack. Such dynamically allocated memory lives on, independent of any scope.

There can be scopes within scopes. Below we see an if-statement. The code between the curly braces of the if-statement is a scope of its own. The variable message is not available outside that scope.

my_proc :: proc() {
	number := 7

	if number > 5 {
		message := "It's more than 5"
		fmt.println(message)
	}

	// message is not available here
}

The code within the curly braces of any if, for or proc all have their own scope.

You can also make anonymous scopes. That just means some code contained between two curly braces:

my_proc :: proc() {
	number := 7

	{
		message := "Hellope"
		fmt.println(message)
	}

	// message is not available here
}

Anonymous scopes can be useful in long procedures where you would otherwise get variable name collisions.

Sometimes you create something that needs to be destroyed at the end of the scope. Rather than manually putting the code that handles this destruction at the end of the scope, you can instead use defer. This means that you can write some code in the middle of a scope and slap defer in front of it, making it actually happen at the end of the scope.

Here's an example, based on an example from the official overview. It uses defer in order to close a file handle when the procedure finishes:

read_file :: proc() {
	f, err := os.open("my_file.txt")

	if err != os.ERROR_NONE {
		// handle error
	}

	defer os.close(f)

	// Put code here that uses `f`
	// to read data from file.

	// os.close(f) is run at the end of
	// the procedure.
}

The line defer os.close(f) will make os.close(f) run at the end of the scope.

As I've pointed out, a procedure can have additional scopes within it. If you put the defer within an anonymous scope or within a block of an if-statement, then the defer will execute at the end of that scope, not at the end of the procedure.

Here follows a bigger example. In the procedure most_green_color we load an image using raylib (import rl "vendor:raylib") and then figure out which pixel within the image is "the most green". This means that it will figure out what pixel has the largest value in the green color channel.

rl.UnloadImage(img) is used to unload the image. We write defer rl.UnloadImage(img) near the start of the procedure, but due to the defer this unloading will wait until the procedure returns.

most_green_color :: proc(filename: cstring) -> rl.Color {
	img := rl.LoadImage(filename)

	if img.data == nil || img.width == 0 || img.height == 0 {
		return {}
	}

	defer rl.UnloadImage(img)

	most_green_color := rl.GetImageColor(img, 0, 0)

	for x in 0..<img.width {
		for y in 0..<img.height {
			color := rl.GetImageColor(img, i32(x), i32(y))

			if color.g == 255 {
				// rl.UnloadImage(img) happens after this line
				return color 
			}

			if color.g > most_green_color.g {
				most_green_color = color
			}
		}
	}

	return most_green_color
} // <-- rl.UnloadImage(img) happens here.

Note something here: There are two lines that uses return. This one:

if color.g == 255 {
	// rl.UnloadImage(img) happens after this line 
	return color
}

and this one:

	return most_green_color
} // <-- rl.UnloadImage(img) happens here.

The deferred code will run when any of these two returns happen. This is a powerful thing about defer: You can defer something once, but have it happen in different places depending on how the scope ends. It's very useful when returning early from procedures.

It may be tempting to use defer as much as you can. It reduces bugs related to having return in multiple places. But it also makes the code a bit harder to read: You can't read the code in a serial manner anymore. The opinions on how much to use defer varies. Personally I only use defer in procedures like most_green_color, where we want to run some "cleanup code" regardless of how the procedure ends. I recommend that you experiment a bit. Get a feeling for how it affects readability versus how it reduces bugs.

Containers are things in your program that can contain several items of a certain type. We had a quick look at fixed arrays earlier. In this chapter we'll go over fixed arrays in more detail, including how they can be used to provide the foundations for doing vector math.

We will also look at enumerated arrays. Enumerated arrays are very similar to fixed arrays, but have a close relationship to enums.

The containers we look at in this chapter are simple and do not require any kind of manual memory management. This means that they cannot grow larger than the initial size we give them. We say that these are fixed-memory containers.

At the end of this chapter we'll look at the Small_Array from the core collection. Small_Array uses a fixed array under the hood, but it also keeps track of how much space within the fixed array it has used. This makes it behave as if it can grow, even though it cannot grow past its initial capacity.

As the name suggest, fixed arrays are created with a fixed size. They cannot grow or shrink. They are often useful when you just need a small temporary array. But as we shall see, they can also be used to store big amounts of permanent data.

This creates a fixed array containing 7 integers:

some_ints: [7]int

As always in Odin the fixed array is zero-initialized. All the 7 integers in this fixed array will be zero. Just like with any variable, you can also set the value of a fixed array:

some_ints = { 51, 21, 621, 1, 51, 7, 12 }

Note that you must specify all the values when you set it. Actually setting a fixed array like this is mostly useful when you have a fixed array of a small size.

As usual, you can do both declaration and assignment at once:

some_ints := [7]int { 51, 21, 621, 1, 51, 7, 12 }

To set and fetch values in the array, use brackets []. Put the index of the thing you want to set or fetch between the brackets.

some_ints[3] = 500
some_ints[4] = 200
some_ints[5] = 333

fmt.println(some_ints[4]) // 200

You can fetch the length of the array using len(some_ints), but since it's fixed it will just return the fixed length, which in the example above will be 7. Indices (indexes) start at 0, meaning that the index of the last element is len(some_ints) - 1.

You can iterate over a fixed array, meaning that you can easily loop over all the items:

for v in some_ints {
	fmt.println(v)
}

If you need the index while looping, then add in another loop variable after v:

for v, i in some_ints {
	// This will print:
	// `value at 0 is <some number>`
	// etc
	fmt.printfln("value at %v is %v", i, v)
}

v is immutable (not possible to modify) in the loop above. If you want to modify the value, then add in & in front of it. For example, this loop multiplies each element in an array by 2:

for &v in some_ints {
	v *= 2
}

You can of course make fixed arrays containing more complex types than just integers. For example, we can make a fixed array of a struct type:

Rectangle :: struct {
	x, y, width, height: f32,
}

rectangles: [10]Rectangle

This makes a fixed array of 10 "Rectangles". All of them have their fields zeroed by default.

If you create a fixed array within a procedure, like this:

main :: proc() {
	some_ints: [100]int
}

Then the memory of some_ints is part of the stack frame of the procedure main. Earlier I talked about what the stack is and how local variables live within the stack memory of the procedure. The same is true for fixed arrays. The array above lives and dies with the scope of the procedure.

Fixed arrays copy in the same way as basic variable types (such as int and f32). So if you assign a fixed array to a new variable, then the new variable has its own separate copy of all the array's data:

main :: proc() {
	some_ints: [100]int
	some_ints[10] = 2
	some_ints2 := some_ints
	some_ints2[10] = 5
	fmt.println(some_ints[10]) // 2
	fmt.println(some_ints2[10]) // 5
}

This shows that there is no shared memory between these two fixed arrays. With regards to copying, they behave just like a variable of some basic type.

The above works the same if you have a fixed array that lives within a struct, and you copy the struct. For example:

My_Struct :: struct {
	some_ints: [100]int,
}

main :: proc() {
	a_struct: My_Struct
	a_struct.some_ints[10] = 2
	another_struct := a_struct
	another_struct.some_ints[10] = 5
	fmt.println(a_struct.some_ints[10]) // 2
	fmt.println(another_struct.some_ints[10]) // 5
}

This also shows that fixed arrays take up space directly within the struct. Fixed arrays don't keep the data anywhere else as some sort of reference. If you create a copy of a struct, then you get a copy of all the fields it contains, including fixed arrays.

Since the stack frame of each procedure has a limited amount of memory available, making a giant fixed array is a common way to run out of stack memory. This would lead to your program crashing. Beware of stuff like this:

main :: proc() {
	lots_of_ints: [1000000]int
}

While procedures are limited to the amount of available stack memory, what is less limited is the amount of memory you have available for global variables. The following should work fine:

lots_of_ints: [10000000]int

main :: proc() {
	// lots_of_ints is a global variable
	// that you can use for as long as your
	// program runs.
}

Global variables don't live within any procedure, so they aren't part of any procedure's stack memory. Instead they live inside what is known as the data block of the program, where you can store much bigger things.

However, if you really need a fixed array that big, then you are probably better off dynamically allocating memory, which you can read about in the next chapter.

Say that you are writing some 3D visualization software or a video game. Then you need to represent positions in 3D space. You can do so using a fixed array of three decimal numbers:

position: [3]f32

You can assign to it, swapping out the three numbers that it contains:

position = {7, 1, 2}

As usual, you can do it all in one line:

position := [3]f32 {7, 1, 2}

As we have seen, you can fetch the first element of position like so: position[0]. However, when arrays have 4 or fewer items, then you can also index them using x, y, z and w. So instead of position[0] you can write position.x. This is very handy because we can see this as the position along the x axis in 3D space!

You can also create a smaller array from a bigger one using these xyzw letters:

zx_pos := position.zx

This new variable zx_pos is of type [2]f32 and contains the z and x parts of the variable position. You can also do stuff like position.xxyy or position.zyx. These kinds of operations are known as swizzling.

Also, because some applications use 4 dimensional numbers to represent colors, you can also use the letters .rgba instead of .xyzw.

If you don't want to write [3]f32 all the time, then you can make an alias called Vector3:

Vector3 :: [3]f32

This turns Vector3 into a new type that can be used interchangeably with [3]f32. Why the name Vector3? Because Vector3 means "3D Vector". A 3D vector is a direction plus a length in 3D space, which is representable using 3 floating point numbers.

You can add two Vector3 variables, like so:

position: Vector3
velocity := Vector3 {0, 0, 10}
position += velocity
fmt.println(position) // [0, 0, 10]

This is known as array programming. As long as two fixed arrays have the same element type (f32 in this case) and the same number of elements (3 in this case), then they can be added.

You can also subtract fixed arrays of matching element type and length:

position1 := Vector3 {10, 21, 1}
position2 := Vector3 {9, 1, 3}
from_1_to_2 := position2 - position1
fmt.println(from_1_to_2) // [-1, -20, 2]

You can multiply them element-wise:

xz_vector := Vector3 {10, 0, -2}
z_scaled_up := xz_vector * {1, 1, 10}
fmt.println(z_scaled_up) // [10, 0, -20]

Finally you can also multiply a fixed array by a single number, which will multiply all the elements by that number:

one_meter_ahead := Vector3 {0, 0, 1}
ten_meters_ahead := one_meter_ahead * 10
fmt.println(ten_meters_ahead) // [0, 0, 10]

Odin does not have operator overloading. However, one of the most common use cases for operator overloading is doing vector maths. So I haven't missed operator overloading at all, because of how great array programming works.

Things like this is a good example of why I enjoy Odin so much for video games programming.

Also, as I've shown, fixed arrays live directly on the stack and making copies of them copies all the underlying data. This is good news, because you do want to be able to easily copy a vector by just assigning it to a new variable.

Procedure parameters that are fixed arrays are easy to assign to, since you can just write the value you want within curly braces. As an example, say that you have a procedure that draws an image at a specific position on the screen. That 2D position can be represented by a parameter of type [2]f32:

draw_image :: proc(image: Image, position: [2]f32) {
	// Draw image using position.
}

If you want to pass in a hard-coded position, then you can simply do this:

draw_image(my_image, {100, 200})

There's no need to write the type name since the compiler can figure it out by looking at the type of the parameter.

The above is actually just the standard way of assigning a value to a fixed array:

position: [2]f32
position = {100, 200}

but you can think of it as assigning it to the parameter instead of a local variable.

You can create arrays that map nicely to an enum and that always have the same number of elements as an enum:

Nice_People :: enum {
	Bob,
	Klucke,
	Tim,
}

nice_rating := [Nice_People]int {
	.Bob = 5,
	.Klucke = 7,
	.Tim = 3,
}

bobs_niceness := nice_rating[.Bob]

In the code above we have an enum Nice_People. The variable nice_rating is an enumerated array. Note how it uses Nice_People between the two brackets:

nice_rating := [Nice_People]int {

We can then use the values of Nice_People to index the array:

bobs_niceness := nice_rating[.Bob]

You could also skip initializing the enumerated array. It would then have the same number of items as the enum, but all of them would be zeroed:

nice_rating: [Nice_People]int

Finally, you can do a partial initialization. All non-mentioned items will be zero:

nice_rating := #partial [Nice_People]int {
	.Klucke = 10,
}

Enumerated arrays work just like fixed arrays. They live on the stack and copy in the same way. No extra memory allocations happen. It's just a convenient way to use enum member names as indices for a fixed array.

In the next chapter we'll take our first look at manual memory management. At that point we'll meet the dynamic array, which is an array than can grow and shrink. But before we go there, lets look at a type of container that is similar to a dynamic array, but doesn't require manual memory management.

It's called "Small Array". It's a package from the core collection. It is possible to add and remove items from a Small Array. Since you can add and remove items, it may seem like this array can grow. But it cannot actually become larger than the maximum size that we choose. And it will always use as much memory as the chosen maximum size.

Here's an example of how you can use it:

package small_array_example

import "core:fmt"
import sa "core:container/small_array"

main :: proc() {
	arr: sa.Small_Array(1024, int)
	fmt.printfln("len: %v", sa.len(arr))

	sa.append(&arr, 5)
	fmt.printfln("len: %v", sa.len(arr))

	sa.append(&arr, 7)
	fmt.printfln("len: %v", sa.len(arr))

	sa.unordered_remove(&arr, 0)
	fmt.printfln("arr[0]: %v", sa.get(arr, 0))
	fmt.printfln("len: %v", sa.len(arr))
}

This program creates a Small Array called arr. It uses sa.append to append things to the array. It also uses sa.unordered_remove to remove things from the array. Running the program outputs:

len: 0
len: 1
len: 2
arr[0]: 7
len: 1

How does this work? Note 1024 and int on this line:

arr: sa.Small_Array(1024, int)

This means that this Small Array internally contains a fixed array of 1024 integers.

If you look inside <odin>/core/container/small_array/small_array.odin then you can see how the type Small_Array is defined:

Small_Array :: struct($N: int, $T: typeid) where N >= 0 {
	data: [N]T,
	len:  int,
}

The things with a $ are related to parametric polymorphism, which we'll discuss in chapter 14. But as you can see the Small Array just contains two things:

• A data field, which is a fixed array.
• A len field, which keeps track of how many elements of data that are actually in use.

The Small Array in our example cannot contain more than 1024 integers and cannot grow once len hits that number. When it is full, sa.append will no longer do anything and instead just return false.

Since it uses a fixed array, the Small Array lives in stack memory. It always uses as much memory as the size you gave it when you declared it. So the Small Array with room for 1024 integers will use 1024*size_of(int) = 1024 * 8 = 8192 bytes of stack memory, regardless of how many things you append to it.

As we see, we can't "start small and grow over time" with a Small Array. In the next chapter we will look at the dynamic array, which can start tiny and then grow as it runs out of space. The downside is that it requires manual memory management.

This chapter will be our first look at manual memory management. I will start off with discussing what manual memory management is and how it relates to dynamic memory allocations.

As an example of something that requires manual memory management, we'll look at how the dynamic array works. Thereafter we'll look at how you can dynamically allocate a variable of any type and how that involves manual memory management.

Towards the end of this chapter we'll discuss the two default allocators in Odin: context.allocator and context.temp_allocator, as well as some other good-to-know things.

Note that this is just the first chapter of several that discusses manual memory management. In chapters 10, 11 and 12 we'll use what we learned in this chapter in order to understand other parts of the language. In chapter 13 we'll look at methods for making manual memory management easier.

Odin uses manual memory management. This means that the programmer is responsible for deallocating memory when it is no longer needed. This can be put into contrast to languages that employ automatic memory management, which means that the language uses certain techniques in order to automatically deallocate memory.

Manual memory management can be slightly harder than automatic. But we shall see throughout this book, with the right tools we'll be able to simplify and wrap our heads around it. When you've understood manual memory management then you'll also have an easier time understanding what the program is actually doing. Since you'll be forced to think of when memory is allocated and deallocated, you'll also be forced to structure your program in a more thoughtful way.

When I speak of manual versus automatic memory management, then I wouldn't blame you for saying the following: "But Karl, when you talked about the stack memory used by procedures, you said that variables that live on the stack are automatically deallocated when a procedure ends. Doesn't this mean that Odin also has automatic memory management?"

The answer is no. Almost all languages that use either automatic or manual memory management have the concept of a stack frame, where variables that live within the stack frame are deallocated automatically. So we can draw the conclusion that the definition of manual vs automatic memory management refers to some other type of memory.

The type of memory allocations that manual memory management concerns itself with is dynamic memory allocations. These are the kind of allocations where the amount of memory we want to allocate does not have to be known at compile time. Dynamic memory has the property that it is usually allocated somewhere else than on the stack. It can therefore live on after a procedure ends. This makes it possible to manually control the lifetime of this memory.

And that is what manual memory management is really about: Manual control over the lifetime of dynamically allocated memory.

As an example of something that requires manual memory management, let's look at the dynamic array. First I'll show you how to create one and under what circumstances memory is dynamically allocated for it. Then we'll look at how to deallocate its memory and also how to remove individual elements from the array. Finally we'll discuss how dynamic arrays work "under the hood".

When we looked at fixed arrays I said that they are, as the name suggests, of fixed size and cannot grow. If you want an array that can grow as your program runs, then you can use a dynamic array. But since dynamic arrays can grow, that means that their size is not known at compile time. Rather, it is only known when the program is running, and the size will change as the array grows. Therefore dynamic arrays need to use dynamic memory and are subject to manual memory management.

You create an empty dynamic array that holds integers like this:

dyn_arr: [dynamic]int

You can swap out int in [dynamic]int for any type you'd like to use. But for simplicity we'll use int in this chapter.

You can add the number 5 to this array of integers like so:

append(&dyn_arr, 5)

Note the &, append needs a pointer to make changes to the array.

Initially this dynamic array is empty. It has no allocated memory in which to store any elements. So when you append a first element to it, then it needs to grow. Growing means that a dynamic memory allocation needs to happen. This allocated memory will not be deallocated automatically, we'll look into how to deallocate it soon.

When the dynamic array grows, it will use an allocator to somehow acquire the required amount of memory. There are different kinds of allocators, and each has its own way of acquiring memory. There is an allocator available everywhere: context.allocator. This is the allocator that append will use by default.

When some memory has been allocated, then the element you wanted to append will be stored within that memory. At this point your dynamic array contains a single element. We can check the length of the dynamic array using the len procedure, this tells us how many elements the dynamic array currently contains. The following will print 1:

fmt.println(len(dyn_arr)) // 1

There is also a cap procedure which tells you the capacity of the dynamic array. The capacity says how many elements you can store in the dynamic array before it needs to grow again. The following will print 8:

fmt.println(cap(dyn_arr)) // 8

As you can see, after appending a single element to an empty dynamic array, it has the capacity 8. This means that the dynamic memory allocation that happened on the first call to append actually allocated space for 8 elements. If you append a second element to the dynamic array, len(dyn_arr) becomes 2, but cap(dyn_arr) will stay the same. No memory allocations will happen until the length and capacity become equal. When they are equal and you try to append another element, then the dynamic array will grow. At that point more memory needs to be allocated, increasing the capacity.

The illustration above shows how the capacity increases from 8 to 24 when the length is 8 and you try to append another element. The illustration can be translated into code, like so:

package dynamic_array_example

import "core:fmt"

main :: proc() {
	dyn_arr: [dynamic]int

	// Will make `dyn_arr` grow:
	append(&dyn_arr, 5)
	
	fmt.println("After first append:")
	fmt.println("Capacity:", cap(dyn_arr)) // 8
	fmt.println("Length:", len(dyn_arr)) // 1

	// append 7 numbers to the dynamic
	// array. This will not make `dyn_arr`
	// grow since capacity is `8` after
	// first `append`.
	for i in 0..<7 {
		append(&dyn_arr, i)
	}

	fmt.println("\nAfter 7 more appends:")
	fmt.println("Capacity:", cap(dyn_arr)) // 8
	fmt.println("Length:", len(dyn_arr)) // 8

	// Capacity is 8, length is 8. This
	// call to `append` will make `dyn_arr`
	// grow:
	append(&dyn_arr, 5)

	fmt.println("\nAfter one more append:")
	fmt.println("Capacity:", cap(dyn_arr)) // 24
	fmt.println("Length:", len(dyn_arr)) // 9
}

If you run the code above, it will print:

After first append:
Capacity: 8
Length: 1

After 7 more appends:
Capacity: 8
Length: 8

After one more append:
Capacity: 24
Length: 9

Any memory that was allocated when append ran can be deallocated using delete:

delete(dyn_arr)

Be sure that you do not need anything in the dynamic array before you run delete. Choosing when to actually run delete is what some people find a bit tricky about manual memory management. It can be tricky because you need to start thinking about the lifetimes of objects. We will discuss techniques for thinking about memory lifetimes in the Making manual memory management easier chapter.

If you continuously create dynamic arrays but never delete them, then your program's memory usage will steadily grow. This is known as a memory leak.

Other than deallocating the memory, delete will not modify your dynamic array. If you wish to reuse the same dynamic array after the delete, then it might be a good idea to reset the dynamic array to its zero value:

dyn_arr = {}

This is because dyn_arr will still keep its internal state after the delete, so trying to append to it again after a delete will cause issues.

However, in many cases a delete followed by zeroing it actually means that you just need to clear the array:

clear(&dyn_arr)

clear does not deallocate any memory. The capacity of the dynamic array remains the same and the allocated memory will still be around. It will just set length of the dynamic array to 0, so it starts over from the beginning of the allocated memory block. Later, when you are actually done with your dynamic array, then you can delete it.

You can remove items from a dynamic array in two ways. Here's the first one:

unordered_remove(&dyn_arr, index)

unordered_remove removes an element at position index, but it does it in an unordered way. It copies the last element of the array to position index and then reduces the length of the array by 1. This means that the order of the dynamic array might not be the same before as after the remove.

If you need to preserve the order of your dynamic array, then instead use:

ordered_remove(&dyn_arr, index) 

This procedure will move everything that resides at indices larger than index. It will move those things back a single index, so that the gap left by the thing you just removed is closed. Thereafter the length is decreased by 1.

Always use unordered_remove unless the order matters! It is less computationally expensive since it only has to copy a single element.

Note that while both these procedures will reduce the length of the dynamic array, the capacity will remain the same. This means that the amount of allocated memory is not reduced. If you really want to reduce the amount of allocated memory, then you can run shrink(&dyn_arr). shrink will reallocate the memory of the dynamic array so that the length and capacity becomes equal. Don't use shrink unless you have a good reason. Since you're using a dynamic array, you'll usually end up adding something new to it at some point, so there is often no point in shrinking the capacity.

As we've seen, this creates an empty dynamic array that will grow on the first call to append:

dyn_arr: [dynamic]int

You can also preallocate a dynamic array like this:

dyn_arr := make([dynamic]int, 0, 20)

This will create a dynamic array with the length 0, but with capacity for 20 items. The make procedure will allocate memory immediately, not at the first append. This also means that the dynamic array won't have to grow until you've added 20 things to it.

If you do this:

dyn_arr := make([dynamic]int, 20)

Then both the capacity and the length will be 20. This means that the dynamic array will start with 20 zeroed out items. dyn_arr := make([dynamic]int, 20) is equivalent to dyn_arr := make([dynamic]int, 20, 20)

Let's look at how append actually makes changes to the dynamic array. This will make it easier for you to understand how the memory is allocated and demystify what dynamic arrays actually are.

Say that you run the following code:

dyn_arr: [dynamic]int
append(&dyn_arr, 7)

Since append will make changes to the dynamic array, we'll start with asking ourselves: "What does a dynamic array look like internally?". It is a struct that looks like this:

Raw_Dynamic_Array :: struct {
	data:      rawptr,
	len:       int,
	cap:       int,
	allocator: Allocator,
}

So when you write

dyn_arr: [dynamic]int

then you are creating something of type [dynamic]int. But you can also see dyn_arr as being of type Raw_Dynamic_Array. That's the internal representation that append will use. Since no value is given, the dynamic array is zero initialized. This means that the data, len, cap and allocator fields of the Raw_Dynamic_Array will all be initialized to zero.

So if you then append 7 to this empty array:

append(&dyn_arr, 7)

then append will cast dyn_arr from the type ^[dynamic]int to the type ^Raw_Dynamic_Array. It then looks inside the Raw_Dynamic_Array and sees that the field cap (the capacity) is zero. This means that the array has room to store zero elements. The array needs to grow in order to add something to it.

While growing, it will check if the allocator field is set and use that allocator to allocate the memory. But in our case the allocator field is zeroed, so it will instead fall back to using context.allocator and ask that allocator for some memory. It will also make sure to store context.allocator in the empty allocator field.

How much memory does this first call to append ask for? It defaults to allocating memory for 8 elements. Since our dynamic array is of type [dynamic]int, then this means that it will allocate room for 8 integers. When the allocator has allocated that amount of memory, then it will return a pointer to that memory. That pointer will be assigned to the data field of the Raw_Dynamic_Array. Since there is room for 8 elements in that data, then the cap field will be set to 8. The len field (the length) will tell you how much of that capacity you've actually used up, which will be 1 after a single append. Finally, in the allocated memory that data now points to, the element that you wanted to append will be written.

Later, if you append more items to the dynamic array, then len is increased by 1 for each appended item. When len equals cap, append will try to allocate more memory. This time the allocator field has a value that append can use instead of defaulting to context.allocator. This new block of memory will be bigger than the old one, since the capacity is bigger. All the memory pointed to by data (the contents of the dynamic array) will be copied to this new block of memory. Thereafter data will be updated to point to the new block of memory.

However, data might or might not end up at a new memory address. With the default allocator you'll see data moving around fairly often. In cases where data does not move, then the contents of the array doesn't have to be copied to any new block.

If data moves to a new address, then the old data will be deallocated. You do not have to worry about having to delete anything else than the array's current memory.

You can't access the data field of the dynamic array directly. But you can fetch it using raw_data(array_name).

Try running this program:

package exercise_dynamic_array

import "core:fmt"

main :: proc() {
	my_ints: [dynamic]int

	for i in 0..<1024 {
		print_info(my_ints)
		append(&my_ints, 5)
	}
}

print_info :: proc(arr: [dynamic]int) {
	fmt.printfln("len: %v", len(arr))
	fmt.printfln("cap: %v", cap(arr))
	fmt.printfln("data: %p", raw_data(arr))
}

It will add one element at a time to a dynamic array and then print the len, cap and data fields of the array. It repeats this process 1024 times. From the output of the program, try to figure out these things:

• What capacity does the dynamic array get after the first append?
• When does it grow again and what is the new capacity? Can you come up with a formula for what the new capacity is based on the previous?
• The data pointer doesn't always move to a new address. How many appends did it take for your program to have the data pointer move to some other address?

We just saw how to use the dynamic array and how it uses dynamic memory. You can also dynamically allocate a single variable of any type. Doing so will make that variable's memory live outside the stack. This means that it will live on after the current procedure ends. It is the programmer's responsibility to deallocate the memory when they no longer need it.

This variable stack_number is allocated on the stack:

stack_number: f32

We can use new to instead dynamically allocate it:

number := new(f32)

The stack allocated stack_number will be of type f32. But the dynamically allocated number will be of type ^f32, meaning that it is a pointer to a 32 bit floating point number. The memory that the pointer refers to is the memory that was allocated for us. An f32 requires 4 bytes of memory, so at the address that number contains we can expect to find those 4 bytes of memory.

Since the allocated memory is not part of the stack frame, it will live on after the current procedure finishes. You'll need to manually deallocate it when you no longer need the memory. For anything you allocate using new, you deallocate it using free:

free(number)

Just like with forgetting to delete dynamic arrays, the following is true: If you run new periodically, but forget to free the memory at some point, then your program's memory usage will continuously grow. You have what is known as a memory leak.

The example we just saw, where we dynamically allocated a single f32 is often not very useful. What is more useful is dynamically allocating a whole struct:

Cat :: struct {
	age: int,
	name: string,
}

make_cat :: proc(name: string, age: int) -> ^Cat {
	cat := new(Cat)
	cat^ = {
		name = name,
		age = age,
	}
	return cat
}

cat_simulation :: proc() {
	cat := make_cat("Fluffy", 12)

	// Cat simulation code goes here

	free(cat)
}

Note how make_cat uses new(Cat) to dynamically allocate a struct object. The pointer cat points to the memory where our Cat struct actually resides. This memory will stay allocated for us until we run free(cat).

The type of the variable cat inside make_cat is ^Cat. As we saw in the chapter on pointers, we need to use cat^ = {} to go through that pointer and replace the value of the whole Cat struct.

Another use case for dynamically allocating a struct is when you have very large global variables. There's a limit to how much memory you can put into global variables, but if you instead dynamically allocate that big global variable, then you can have much bigger global data. Here's an example:

Program_Memory :: struct {
	big_array_of_numbers: [10000000]int,
}

memory: ^Program_Memory

main :: proc() {
	memory = new(Program_Memory)

	// Rest of program can use
	// global variable `memory`.
}

As you can see Program_Memory contains a really big fixed array of integers. This will make Program_Memory use 80 megabytes of memory. If we used an ordinary global variable for memory, then we might run into the limit of how big global variables can be:

memory: Program_Memory

So instead we dynamically allocate memory when the program starts.

Note that there is no free in this case. If you dynamically allocate memory once on program startup and want that memory to be around for the whole execution of the program, then having a free at the end of the program is unnecessary. A program that shuts down has all its allocations freed automatically. Using free here would actually make the program shut down slightly slower.

As we have seen, creating fixed arrays allocates their memory on the stack:

ints_stack: [128]int

However, you can pass the type [128]int to new and dynamically allocate the fixed array:

ints := new([128]int)

The type of ints is ^[128]int. new dynamically allocated the memory for the fixed array, and gave us a pointer that says where that memory is. This fixed array does not live on the stack.

Deallocate ints using free when you no longer need it:

free(ints)

When we've previously talked about fixed arrays, then I said that fixed arrays copy all their data when you assign them to a new variable. However, the type of the dynamically allocated array ints is ^[128]int. This means that if you assign ints to a new variable, then you are just assigning the pointer to that variable. You do not get a copy of the array's data. Example:

ints := new([128]int)
ints[10] = 5
ints_2 := ints
ints_2[10] = 7
fmt.println(ints[10]) // 7
fmt.println(ints_2[10]) // 7

In this example I create a dynamically allocated fixed array ints. I then create a new variable ints_2 that is set to the same value as ints. Both these variables have the type ^[128]int.

I then modify the item at index 10 in both ints and ints_2. Note how ints[10] = 5 happens first and ints_2[10] = 7 happens just thereafter. Since both ints and ints_2 are pointers that contain the same memory address, those two lines are actually just modifying the same element in the same array.

We have seen how dynamic arrays can grow when we use make and append. We've also seen how we can "manually" allocate memory using new. Let's look at the allocator parameter of those procedures, and how its default value looks.

For example, new looks like this:

new :: proc($T: typeid, allocator := context.allocator, loc := #caller_location) -> (^T, Allocator_Error) #optional_allocator_error {
	return new_aligned(T, align_of(T), allocator, loc)
}

and the overload of make that handles dynamic arrays looks like this:

make_dynamic_array :: proc($T: typeid/[dynamic]$E, allocator := context.allocator, loc := #caller_location) -> (T, Allocator_Error) #optional_allocator_error {
	return make_dynamic_array_len_cap(T, 0, 0, allocator, loc)
}

Both these procedures have a parameter allocator with default value context.allocator. Whenever something in Odin needs a default method for allocating memory, then it will usually use context.allocator.

context.allocator is set up for you automatically when the program starts. Exactly what type of allocator it is depends on your system. At the time of writing there are two possible defaults:

• On desktop operating systems such as Windows, macOS and Linux it is a heap allocator
• On web-based systems, such as WASM, it is a WASM allocator

Whenever you allocate dynamic memory using the heap allocator, your memory will be allocated from what is known as a heap. A program can have several heaps, but the heap allocator uses the default heap assigned to the program by the operating system. The heap uses an area of memory that is separate from the stack. This means that when we allocate anything using the heap allocator, then that allocation ends up outside the stack.

So when you do something like

my_num := new(f32, context.allocator)

then new will ask context.allocator to allocate memory, which will in turn ask the operating system to do a heap allocation. The memory it allocates will reside at some address in the heap. my_num will be a pointer to that heap-allocated memory.

The heap starts out small, but can grow as it runs out of space. It's essentially a list of memory blocks. These memory blocks are reserved using what is known as virtual memory. Virtual memory is a nifty invention where your program can use the whole giant 64 bit address space, even though the amount of physical memory in your computer is much, much smaller. Virtual memory is split into chunks called pages. When a page is in use it is mapped to some physical memory.

Your computer has a limited amount of memory. If you run out of memory then your allocations will fail. new, make and append all have an optional second return value that contains an error if the allocation fails:

my_dyn_arr, alloc_err := make([dynamic]f32, 100, context.allocator)

if alloc_err != nil {
	// There's an error, alloc_err could
	// for example be the "Out_Of_Memory"
	// error.
}

The WASM allocator is made for when you build an Odin program that runs in a web browser. In this case context.allocator is not a heap allocator. Instead, the WASM allocator uses a series of blocks of memory that are handed to the allocator by the browser. The WASM allocator can ask the browser for additional memory when it runs out of memory blocks.

So when you allocate memory with for example new, then you get a pointer that contains the address of some memory within one of those blocks that the browser has handed the allocator.

Note that the result of

number := new(f32)

consists of two parts:

1. number is of type ^f32. That's a pointer. It contains a memory address which tells us the location of the allocated memory.
2. At the address number points to, there are 32 bits (4 bytes) of memory that is allocated for us to use.

So within a procedure, the pointer itself lives on the stack, but the dynamically allocated memory that it points to does not. In other words, these two variables

number := new(i32)
number2 := number

are both pointers. The pointers themselves are two separate stack variables. But they both point to the same memory.

Another important thing to understand is this: What happens when you copy a variable that is a dynamic array? Say that you do this:

dyn_arr: [dynamic]int
append(&dyn_arr, 5)
dyn_arr_2 := dyn_arr

Remember, a dynamic array looks like this internally:

Raw_Dynamic_Array :: struct {
	data:      rawptr,
	len:       int,
	cap:       int,
	allocator: Allocator,
}

After the call to append, then the field data inside dyn_arr will point to the memory that was allocated.

When we do dyn_arr_2 := dyn_arr, then dyn_arr_2 becomes a new struct that has a copy of all the fields of dyn_arr. But just like len will be 1 in both dyn_arr and dyn_arr_2, data in dyn_arr_2 will contain the same memory address as data in dyn_arr.

Therefore dyn_arr and dyn_arr_2 refer to the same memory. However, if you now try to add more things to dyn_arr, which can make it grow, then this situation becomes dangerous. Why? Say that you do this:

dyn_arr: [dynamic]int
append(&dyn_arr, 5)
dyn_arr_2 := dyn_arr

// This loop will make
// `dyn_arr` grow again.
for i in 0..<1024 {
	append(&dyn_arr, 5)
}

This example starts off like the previous one. But after creating dyn_arr_2 based on dyn_arr, we use a loop to add 1024 new items to dyn_arr. This will make dyn_arr grow several times. After this has happened several things may be wrong:

• When appending to dyn_arr, the data of dyn_arr might move to some other address. When such a move happens, then it also deallocates the old data. This would mean that dyn_arr now has some other pointer data than dyn_arr_2 has. It also means that the pointer data inside dyn_arr_2 now points to deallocated memory.
• Even if data didn't move, then the cap and len fields of dyn_arr_2 will be wrong.

Instead, if you really want a clone of a dynamic array, then do this:

dyn_arr_2 := slice.clone_to_dynamic(dyn_arr[:])

The above makes a clone of dyn_arr with its own memory. Now dyn_arr and dyn_arr_2 work independently. This uses the slice package and the [:] syntax, which we'll go over in the next chapter when we talk about slices.

We've seen free and delete now. But why do both of these exist and when should we use which?

free is very simple: Whenever you allocate memory using new you are getting a plain pointer directly to that memory. So new(int) gives you something of type ^int. You deallocate that memory using free.

However, delete takes some additional explaining.

Let's look at dynamic arrays as an example. Dynamic arrays are internally represented by a struct that in turn contains a pointer to some allocated memory:

Raw_Dynamic_Array :: struct {
	data:      rawptr,
	len:       int,
	cap:       int,
	allocator: Allocator,
}

So you can't use free directly on a dynamic array because the allocated memory is pointed out by the data field. There is "one step of indirection" if you will. So instead we use delete, which is an explicit overload that looks like this:

delete :: proc{
	delete_string,
	delete_cstring,
	delete_dynamic_array,
	delete_slice,
	delete_map,
	delete_soa_slice,
	delete_soa_dynamic_array,
}

The overload delete_dynamic_array will deallocate the memory that the data field in the Raw_Dynamic_Array points to using the allocator that it stores.

All the types that are compatible with delete have an internal representation similar to Raw_Dynamic_Array, that in turn contains a data field. For example delete_string will deallocate the memory that the data field within the Raw_String refers to.

Many times you need to allocate some dynamic memory, but you only need it for "a short while". Here "a short while" could mean during the execution of an algorithm. Or in a video game, it could mean until the "end of the frame".

In these cases using a temporary allocator can simplify your code. There's a default temporary allocator: context.temp_allocator. You can use the temp allocator to make temporary dynamic arrays, temporary strings and do temporary data processing.

Here's an example of how you can make a dynamic array that uses the temp allocator:

great_algorithm :: proc() {
	numbers := make([dynamic]int, context.temp_allocator)

	for i in 0..<100 {
		append(&numbers, rand.int_max(1000))
	}

	for n in numbers {
		if n > 500 {
			fmt.println(n)
		}
	}
}

Note how make is fed context.temp_allocator. After this, the variable numbers will be a dynamic array with the allocator field set to context.temp_allocator. So when append is run and the dynamic arrays needs to grow, it will use context.temp_allocator to allocate memory.

The procedure adds 100 random numbers in the range 0 to 1000 to the dynamic array (excluding 1000: The biggest possible number is 999). Thereafter it loops over numbers again and prints the ones that are bigger than 500.

As you can see, there is no delete(numbers) at the end of this procedure. When using the temp allocator you do not need to individually deallocate memory. Instead, you need to make your program periodically free everything that allocated using the temp allocator. You do that by running the following line every now and then:

free_all(context.temp_allocator)

This means that all the memory that was allocated using the temp allocator is now deallocated. Before doing this, make sure you don't need anything allocated using the temp allocator!

Do not forget to put the free_all(context.temp_allocator) somewhere in your program. Forgetting to do so will, if you use the temp allocator, lead to memory leaks.

Placing the free_all(context.temp_allocator) somewhere can be easy or tricky depending on the type of program. It's especially easy to place in a program that runs in a loop. Such an example is a video game. Video games usually have a 'main loop' where each lap of that loop is one frame. You can then put the free_all(context.temp_allocator) at the end of that loop:

main :: proc() {
	init_game()

	for game_should_run() {
		game_update()
		game_draw()
		free_all(context.temp_allocator)
	}
}

This makes anything allocated using the temp allocator valid until the end of the frame. We say that the lifetime of the temporary allocations are "one frame".

It is more tricky to place the free_all(context.temp_allocator) in event-driven programs such as a desktop applications. In those kinds of programs there may not be a well-defined 'main loop' like above. This means that you may need to be a bit more careful with what you use the temp allocator for. If you use it for only temporary things within a procedure, then it's fine. But if you use it to return dynamically allocated data, or dispatch dynamically allocated data for later processing, then you might end up in trouble if you place the free_all in a location where it deallocates your data before you were done with it. In that case you might be better off using separate arena allocators. Read more about arena allocators in chapter 13.

You can use Odin to write programs that are similar to "scripts". By script I mean a program that does some processing and then shuts down. An example would be a program that goes through a few files and prints some statistics about them.

Your script may need to use dynamic memory. Perhaps it uses dynamic arrays. However, if you come from something like Python, which has automatic memory management, then writing scripts in Odin can feel a bit overwhelming: You don't want to deal with manual memory management when doing something quick and dirty.

Here's the thing: You probably don't have to deal with it. All dynamically allocated memory is deallocated when a program shuts down. So for a short-lived script-like program, just let it do whatever dynamic allocations it needs without care for when the memory needs to be deallocated. The program will shut down soon anyway.

There are limits to this. If you make a script that runs for a long time and processes a lot of large data, then you should still do proper memory management.

But for most script-like programs you can simply ignore memory management.

There are two built-in container types left for us to cover: Slices and maps. Let's look at them now. Maps require dynamic memory allocations and slices can optionally be allocated, so we are in a good position to talk about these container types now that we've gotten an introduction to manual memory management.

At the end of this chapter we'll also look at how to create custom iterators, making it possible to easily loop over custom container types.

When programming Odin you will use slices a lot. Slices provide a way to look at a section of an array. There are two very nice things about slices:

• You can create slices that represent a subsection of another array without any extra memory allocations.
• You can form slices from most array types, such as fixed arrays and dynamic arrays. This means that slices can be used as a generic way to represent data within a more specific type of array.

Suppose you have a fixed array of 50 integers:

my_numbers: [50]int

You can create a slice that only "sees" the first 20 items of my_numbers:

first_20 := my_numbers[0:20]

Note the [0:20] syntax: We create slices using the [:] operator, where you put in the indices you want it to span like this: [start_index:end_index]. The type of first_20 is []int. The fixed array above has type [50]int, that's a different type than []int. They just look similar:

• []int is a slice.
• [50]int is a fixed array.
• [dynamic]int is a dynamic array.

Creating a slice does not allocate any memory, it uses the same memory as the thing you slice, but looks into just a part of it.

You can also skip some of the indices:

my_numbers: [50]int
last_20 := my_numbers[30:]

Note the absence of the second index in [30:]. In this case we create a slice that runs from index 30 to the last index. Skipping the first index would make it run from index 0, for example: first_20 := my_numbers[:20].

If you skip both indices, then you get a slice that looks at the whole thing:

my_numbers: [50]int
full_slice := my_numbers[:]

You can slice most kinds of arrays in Odin. Slicing a dynamic array uses the same syntax:

dyn_arr: [dynamic]f32

for i in 0..<200 {
	append(&dyn_arr, f32(i*i))
}

half_dyn_arr_size := len(dyn_arr)/2
half_the_dyn_arr := dyn_arr[:half_dyn_arr_size]

This code adds 200 items to dyn_arr using a loop. half_the_dyn_arr is a slice that looks at the first 100 of those items.

When you've sliced something, you can loop over the slice just like you can with fixed and dynamic arrays:

for v, i in half_the_dyn_arr {

}

As I mentioned before, when you create a slice using the [:] syntax, then there are no extra dynamic memory allocations to worry about. Slices are actually very simple. They are essentially a pointer plus a length. Here's how the internal representation of a slice looks:

Raw_Slice :: struct {
	data: rawptr,
	len:  int,
}

So when you do something like this:

numbers: [50]int
my_slice := numbers[10:30]

Then the data field will be a pointer containing the memory address of the tenth element of numbers, equivalent to &numbers[10]. The len field will be 20, because we wrote [10:30], which makes it run from element 10 to element 30, and 30 - 10 = 20.

In this example we use slices to display 10 numbers at a time from a bigger list of numbers:

display_numbers :: proc(numbers: []int) {
	fmt.println(numbers)
}

my_numbers: [128]int

// Set the elements of my_numbers to
// interesting values
for i in 0..<len(my_numbers) {
	my_numbers[i] = i*i
}

// Slice my_numbers, 10 numbers per slice.
// Send each slice into display_numbers for
// printing on the screen.
for i := 0; i < len(my_numbers); i += 10 {
	slice_end := min(i+10, len(my_numbers))
	ten_numbers := my_numbers[i:slice_end]
	display_numbers(ten_numbers)
}

This loop:

for i := 0; i < len(my_numbers); i += 10 {

steps through 10 items at a time. Inside each lap of this loop we create our slice of ten elements:

slice_end := min(i+10, len(my_numbers))
ten_numbers := my_numbers[i:slice_end]

We can then call display_numbers(ten_numbers) and let it print our 10 numbers.

It's a good idea to use slices as the type for procedure parameters whenever possible. If you are creating a procedure that needs some kind of array parameter, then prefer to use a slice. Let's look at why.

As an example, below is a small program that has a dynamic array of cats. There are three procedures to manage the cats:

• add_cat_of_random_age: Takes a pointer to a dynamic array and a name. It creates a cat with that name and a random age and adds it to the dynamic array.
• print_cats: Takes a slice of cats and prints each cat's name and age.
• mutate_cats: Takes a slice of cats and gives each a new random age.

package cat_simulation

import "core:fmt"
import "core:math/rand"

Cat :: struct {
	name: string,
	age: int,
}

add_cat_of_random_age :: proc(cats: ^[dynamic]Cat, name: string) {
	random_age := rand.int_max(12) + 2
	append(cats, Cat {
		name = name,
		age = random_age,	
	})
}

print_cats :: proc(cats: []Cat) {
	for cat in cats {
		fmt.printfln("%v is %v years old", cat.name, cat.age)
	}
}

mutate_cats :: proc(cats: []Cat) {
	for &cat in cats {
		cat.age = rand.int_max(12) + 2
	}
}

main :: proc() {
	all_the_cats: [dynamic]Cat
	add_cat_of_random_age(&all_the_cats, "Klucke")
	add_cat_of_random_age(&all_the_cats, "Pontus")

	print_cats(all_the_cats[:])
	mutate_cats(all_the_cats[:])
	print_cats(all_the_cats[:])
}

add_cat_of_random_age has a parameter cats that is a pointer to a dynamic array:

add_cat_of_random_age :: proc(cats: ^[dynamic]Cat, name: string) {

The parameter cats must be of this type because the procedure uses append, and that procedure in turn expects a pointer to a dynamic array.

However, print_cats can just use a slice, since it only iterates over the cats and prints some information about them:

print_cats :: proc(cats: []Cat) {
	for cat in cats {
		fmt.printfln("%v is %v years old", cat.name, cat.age)
	}
}

Note how we call it:

print_cats(all_the_cats[:])

We make a slice that looks into the whole dynamic array using [:]. This is cheap, no extra memory allocations needs to happen when [:] is used.

Some people would make print_cats use a parameter of type [dynamic]Cat:

print_cats :: proc(cats: [dynamic]Cat) {

Some would perhaps even use cats: ^[dynamic]Cat. But we do not need a dynamic array since the slice gives us all the information we need. Also, even if we did pass a dynamic array, it would not need to be a pointer since we would not be modifying the fields of the dynamic array.

Using a slice instead of the dynamic array makes it possible to use the procedure print_cats with most types of arrays. We can make slices that look into both fixed arrays and dynamic arrays. So making a procedure accept a slice makes the procedure more generally useful!

The third procedure might be slightly surprising to some:

mutate_cats :: proc(cats: []Cat) {
	for &cat in cats {
		cat.age = rand.int_max(12) + 2
	}
}

This procedure takes a slice and modifies each cat in the slice so that it gets a new age. Note the & in for &cat in cats {, which makes it possible to modify the elements.

But now someone might say: "Hang on, the parameter cats: []Cat doesn't have a ^ in front of the type. How can you modify anything within it? Aren't all procedure parameters immutable?"

It's just the fields directly within the slice that are immutable. Remember, a slice looks like this internally:

Raw_Slice :: struct {
	data: rawptr,
	len:  int,
}

You are not allowed to modify the len field or the address that data contains. However, the loop above does not modify any of those two. It goes to the memory that data points to and modifies the data that lives there, and that is allowed.

We can summarize all of the above like so:

• If you need to modify a container, as in adding or removing items from it, then pass a pointer to the container.
• If you need to modify the existing elements of a container, then pass a slice to the contents of it.
• If you need to display (read) the information inside a container, then pass a slice to the contents of it.
• Using slices wherever possible will make your procedures more reusable, since you can create slices that look into several different types of arrays.

I hope this example illustrated why slices are used so much in Odin.

I have said that the syntax some_array[:] creates a slice that sees all the elements of some_array. I also said that slicing it doesn't cause any dynamic memory allocations.

The above is always true, [:] never does any automatic memory allocations.

However, you can create a slice that looks into memory that doesn't belong to any other array. This means that it is possible to create slices that have "their own memory".

For example, the following will make first_20_clone have its own memory, independent of my_numbers:

my_numbers: [128]int
first_20 := my_numbers[:20]
first_20_clone := slice.clone(first_20)

Note the usage of slice.clone(first_20). This clone procedure will allocate memory using context.allocator and copy the data of first_20 into that memory. This will make first_20_clone have its own, dynamically allocated memory. It will live on, independent of my_numbers. This means that you'll have to run delete(first_20_clone) in order to deallocate that memory.

This is useful in situations where you have some temporary memory, but you wish to permanently clone it (or a section of it).

You can also create a slice from scratch that has its own memory:

ints := make([]int, 128)

This uses context.allocator to allocate space for 128 integers and gives you a slice that looks into that memory. You'll need to run delete(ints) to deallocate it.

It might be a bit confusing that slices don't necessarily have to be a slice of something else. But as I've shown before, slices look like this internally:

Raw_Slice :: struct {
	data: rawptr,
	len:  int,
}

There is nothing stopping the program from having a data field in this struct that points to memory not used by anything else.

You can see slices that have their own memory as a way to dynamically allocate an array with a fixed size. Let's compare creating a standard fixed array to creating a slice of the same size:

my_numbers: [128]int

The above creates a fixed array and will not cause any dynamic memory allocations. However, this fixed array lives on the stack and will only be valid within the scope where it was created. Also, the size 128 must here be known at compile time. You cannot use a variable to set the size of a fixed array.

Compare this to the following:

my_numbers := make([]int, 128)

This does a dynamic memory allocation using context.allocator. Its memory will live on after the current scope ends. The size 128 does not have to be known at compile time. You could even be silly and create a slice of random size:

my_numbers := make([]int, rand.int_max(200) + 10)

In a previous example I showed that you can use new in combination with a fixed array type to dynamically allocate fixed arrays:

int_fixed := new([128]int)

But, what is then the difference between this:

ints_fixed := new([128]int)
ints_fixed_slice := ints_fixed[:]

compared to this?

ints_slice := make([]int, 128)

The first one dynamically allocates a fixed array of 128 integers and then makes a slice that looks at that whole fixed array. The second one makes a slice that has its own dynamically allocated memory with room for 128 integers.

In practice, there's no difference at all. The two examples are for most intents and purposes identical.

In fact, you can even use delete on ints_fixed_slice, as opposed to using free on ints_fixed:

ints_fixed := new([128]int)
ints_fixed_slice := ints_fixed[:]

// Some time later:
delete(ints_fixed_slice)

This makes sense since the data field of the slice is a pointer to the start of the fixed array. delete will deallocate the memory that data points to. So delete(ints_fixed_slice) ends up doing the same thing as free(ints_fixed) would do.

With this in mind, whenever you need a dynamically allocated array that doesn't need to grow, then I recommend just using make with a slice type.

Sometimes you want to run a procedure that needs a slice, but you only have a fixed array. So you slice the fixed array:

print_numbers :: proc(numbers: []int) {
	for n in numbers {
		fmt.println(n)
	}
}

my_numbers := [3]int { 1, 2, 3 }
print_numbers(my_numbers[:])

There is a special way to do exactly the above, but in a more compact way:

my_numbers := []int { 1, 2, 3 }
print_numbers(my_numbers)

Note how we dropped the 3 inside the []int and we no longer need the [:] after my_numbers.

[]int { 1, 2, 3 } is known as a slice literal. This:

my_numbers := []int { 1, 2, 3 }

does exactly the same thing as this:

my_numbers_arr := [3]int { 1, 2, 3 }
my_numbers := my_numbers_arr[:]

A slice literal creates a fixed array of integers that lives on the stack and then makes a slice that looks at the whole thing.

You can even use slice literals directly as an argument to a procedure:

print_numbers :: proc(numbers: []int) {
	for n in numbers {
		fmt.println(n)
	}
}

print_numbers({ 1, 2, 3 })

Note how we now have no in-between variable before calling print_numbers. We just write { 1, 2, 3 } as an argument to print_numbers. This makes a slice literal in the same way as above. Meaning that there is a hidden stack allocated fixed array that holds these three numbers, and a slice of that whole array is sent into print_numbers.

Since slice literals use a hidden fixed array that lives on the stack, one can easily make mistakes when using them. Let's look at such a mistake:

package slice_literal_pitfall

import "core:fmt"

numbers: []int

set_numbers :: proc() {
	numbers = {
		7, 42, 13
	}
	fmt.println(numbers)
}

main :: proc() {
	set_numbers()
	fmt.println(numbers)
}

This program has a set_numbers procedure that sets a global variable numbers: []int to a value that is a slice literal.

If you run the program above, then it will print something like:

[7, 42, 13]
[140700727785616, 67460135296, 72339069014638605]

The first print happens inside set_numbers and the second one happens in main after set_numbers has finished. The big numbers of the second line (140700727785616 etc) may be different on your computer. What happened here is the following: The global variable numbers is a slice that is looking into deallocated stack memory. We can see why more clearly if we change set_numbers to look like this:

numbers: []int

set_numbers :: proc() {
	numbers_arr := [3]int {
		7, 42, 13
	}
	numbers = numbers_arr[:]
	fmt.println(numbers)
}

The above is identical to the old code. When you set numbers to a slice that looks into numbers_arr then you are effectively creating a slice that looks into memory that lives on the stack of set_numbers. That memory is only valid until the procedure ends. So the data field of the slice would contain the address you'd get by doing &numbers_arr[0], which points to stack memory.

Maps are in some languages referred to as dictionaries. You use them to map keys to values. If you have a key then you can lookup which value it is associated with.

Declare a new map like this:

age_by_name: map[string]int

This map has keys of type string and values of type int.

Add entries by writing age_by_name[key] = value:

age_by_name["Karl"] = 35
age_by_name["Klucke"] = 7

Remove entries using the delete_key procedure:

delete_key(&age_by_name, "Klucke")

You also use [] to retrieve values:

karls_age := age_by_name["Karl"]

If there was no value with that key, then karls_age will have the zero value. If this isn't good enough, then you can also get a second value of type bool that says if the item existed or not:

if karls_age, ok := age_by_name["Karl"]; ok {
	// There was a value for this key! In
	// here you can safely use `karls_age`.
}

There are also two special operators called in and not_in that you can use to check if a key exists in the map:

has_karl := "Karl" in age_by_name
does_not_have_klucke := "Klucke" not_in age_by_name

The initial declaration of a map does not allocate any memory:

age_by_name: map[string]int

However, when you add items to it, like so:

age_by_name["Karl"] = 35

Then the map will grow if needed. This will cause a dynamic memory allocation. This is similar to how append() can cause a dynamic array to allocate memory.

Since the map uses dynamic memory, you'll need to destroy it manually when you no longer need it:

delete(some_map)

If you want to create a map that uses some other allocator than context.allocator, then you can use make:

age_by_name := make(map[string]int, context.temp_allocator)

This call to make does not cause any immediate memory allocation, it just saves the allocator inside the map for future usage. Later, when you add elements using for example age_by_name["Bob"] = 89, then memory may be allocated using the allocator you provided to make.

You can also provide an initial capacity to make:

age_by_name := make(map[string]int, 64, context.temp_allocator)

In this case an allocation will occur immediately.

You can iterate maps. Note how we have two loop variables below. One for the key, one for the value:

for key, value in some_map {
}

You can make the value modifiable by adding in a & in front of value:

for key, &value in some_map {
}

Use maps when you really don't know what kinds of keys you might need. Often this is because the user of the program can specify their own data. Perhaps you need to associate one user-specified value with another user-specified value. That's a good use case for a map.

If you know all possible keys, then just make an enum and use an enumerated array. There's no point in using a map for that. Enumerated arrays are much faster. With an enumerated array it can look up what element it needs very quickly, since the enum acts like an index. When fetching values from a map using a key, it instead has to search using the key, which is considerably slower.

A set is a collection where each item can only appear once. Using a set, you can easily check if an item is in the set or not.

Odin does not have any special support for sets. However, you can still create a set by making a map where the keys of the map are of the type you wished to store in a set. For the values of the map you use an empty struct. An example:

set_of_names: map[string]struct{}

// Add to set
set_of_names["Pontus"] = {}

// Check if set contains "Pontus"
if "Pontus" in set_of_names {

}

// Iterate set
for key in set_of_names {

}

// Remove from set
delete_key(&set_of_names, "Pontus")

Note how the we declare the set using the type map[string]struct{}. This means that we making a map that has strings as keys, but the value is an empty type struct{}

I don't blame you if you think the method for adding things to the set looks awkward:

set_of_names["Pontus"] = {}

This means that we are associating the key "Pontus" with a value that is an empty struct. That means that "Pontus" now exists in the set and is associated with a value, although that value is just an empty struct. A struct{} takes 0 bytes of memory. So no memory is wasted in defining a set in this way.

If you can't live with it, then you can introduce an add_to_set procedure that hides the weird = {} part:

add_to_set :: proc(s: ^map[$T]struct{}, v: T) {
	s[v] = {}
}

If you need to iterate over a collection in a special way, then you can define your own iterator. This means that you can create your own iteration loops, similar to this one:

for v, i in some_array {

}

As we shall see, using custom iterators need slightly more code than the loop above. Nevertheless, they are still very useful, since custom iterators walk through the collection in very specific ways.

In the following example there is a struct called Slot. It has a used field of type bool. I've made an iterator that iterates over a slice of Slots. But this iterator only considers those elements that have used set to true. This means that the loop at the end of the example will automatically skip all the elements where used is false.

Slot :: struct {
	important_value: int,
	used: bool,
}

Slots_Iterator :: struct {
	index: int,
	data: []Slot,
}

make_slots_iterator :: proc(data: []Slot) -> Slots_Iterator {
	return { data = data }
}

slots_iterator :: proc(it: ^Slots_Iterator) -> (val: Slot, idx: int, cond: bool) {
	cond = it.index < len(it.data)

	for ; cond; cond = it.index < len(it.data) {
		if !it.data[it.index].used {
			it.index += 1
			continue
		}

		val = it.data[it.index]
		idx = it.index
		it.index += 1
		break
	}

	return
}

slots := make([]Slot, 128)

slots[10] = {
	important_value = 7,
	used = true,
}

it := make_slots_iterator(slots[:])

for val in slots_iterator(&it) {
	fmt.println(val)
}

The program will only print the slot at index 10, despite slots having 128 entries. This is because the slot at index 10 is the only slot that has used set to true.

These lines do the actual iteration:

it := make_slots_iterator(slots[:])

for val in slots_iterator(&it) {
	fmt.println(val)
}

First it creates an iterator. At the beginning of each lap of the loop, slots_iterator is called and fed the iterator. Note how slots_iterator is defined:

slots_iterator :: proc(it: ^Slots_Iterator) -> (val: Slot, idx: int, cond: bool) { }

It has three return values. An iterator procedure can be any procedure that has the following three return values:

• A value: The element it wants the loop to consider when some_iterator returns. This is val in for val in some_iterator(&it) {}.
• A 'second loop variable', often this is an index, but it doesn't have to be. This is the optional extra thing you can add after val in the loop: for val, index in some_iterator(&it) {}
• The condition that the iteration should continue. If this return value is false then the loop will stop.

Now let's focus on what's inside slots_iterator:

slots_iterator :: proc(it: ^Slots_Iterator) -> (val: Slot, idx: int, cond: bool) {
	cond = it.index < len(it.data)

	for ; cond; cond = it.index < len(it.data) {
		if !it.data[it.index].used {
			it.index += 1
			continue
		}

		val = it.data[it.index]
		idx = it.index
		it.index += 1
		break
	}

	return
}

It uses a for loop to skip all slots that are unused. Having a loop in there might seem wasteful, but it is fine since the loop always starts from it.index. This means that it doesn't loop from the start of the slice every time, it only loops until it finds the next element that has used == true. At that point slots_iterator returns, informing the loop that it found a relevant element. Then the loop's body can run, in this case fmt.println(val). After that the loop continues, which means calling slots_iterator again. It continues to search through the slice for the next element.

Sometimes you need to modify the value from within the loop. To support that that, make a second version of the iterator procedure. That version should return a pointer to a value instead of just a value:

slots_iterator_ptr :: proc(it: ^Slots_Iterator) -> (val: ^Slot, idx: int, cond: bool) {
	cond = it.index < len(it.data)

	for ; cond; cond = it.index < len(it.data) {
		if !it.data[it.index].used {
			it.index += 1
			continue
		}

		val = &it.data[it.index]
		idx = it.index
		it.index += 1
		break
	}

	return
}

We've only changed three things from the previous implementation of slots_iterator:

• The new procedure is named slots_iterator_ptr instead of slots_iterator
• The type of return value val is now ^Slot.
• The line val = &it.data[it.index] now contains an &.

You use it just like before, but use slots_iterator_ptr instead of slots_iterator:

it := make_slots_iterator(slots[:])

for val in slots_iterator_ptr(&it) {
	// val is a pointer.
}

The type string is used to represent text. In Odin, all strings are assumed to use the UTF-8 encoding. This makes it possible to mix characters from any language within your program. You can even use exotic things such as emojis!

Let's look at how to create strings and how to iterate through a string. We'll also talk about what a single character actually is. Then we'll see how we can construct strings at run time and how the string type looks "under the hood".

This code creates a string variable and assigns a value to it:

my_string: string
my_string = "Hellope!"

Or, on a single line with type inference:

my_string := "Hellope!"

The type will be inferred to string.

Strings like "Hellope!", that are defined directly in the code, are known as string literals. The size of a string literal is known at compile time. Because of this, the data for a string literal does not need any dynamically allocated memory. Instead, the data is stored in the read-only data block of the program. Therefore the string literal is valid for as long as the program runs.

However, if you clone a string literal using strings.clone, then that clone is dynamically allocated and can be deallocated using delete:

allocated_string := strings.clone("Hellope!", context.allocator)

// later
delete(allocated_string)

Periodically allocating memory for strings, using for example strings.clone, and not deleting their memory at some point, leads to memory leaks.

You can iterate a string the same way you can iterate any array:

str := "Important Words"

for r in str {
	// r is of type `rune`
}

The loop variable r is a rune. This is the type Odin uses to represent a single UTF-8 code point. A code point is in many cases (but not all!) equivalent to a single character. So "rune" is Odin's way of saying "UTF-8 code point".

Within the string, each rune uses between 1 and 4 bytes of memory. All English characters need just a single byte. Since UTF-8 can represent all the languages in the world, we can also iterate over a string written in Simplified Chinese:

str := "小猫咪"

for r in str {
	fmt.println(r)
}

The above would print:

小
猫
咪

Each one of these Chinese characters are also represented by a rune. But while the English runes used 1 byte of memory per character, these Chinese characters uses 3 bytes of memory per character.

You can cut strings up, or create substrings, using the slice syntax [:]. Because of this, substrings are often called "string slices":

str := "Little Cat"
sub_str := str[7:]
fmt.println(sub_str) // Cat

The above prints the string slice "Cat". Please note that the slice operator [start:end] uses byte indices. You say at what byte your slice should start, and at what byte it should end. So the slice above goes from the 7th byte, to the last one. This works fine for English text, since English characters use a single byte.

But if we take the Chinese text we saw earlier and assume that we can slice it in the same way, then we'll end up in trouble:

str := "小猫咪"
sub_str := str[1:]
fmt.println(sub_str)

the above prints:

��猫咪

One could think that str[1:] would make a string that goes from the second character to the last one. But each one of these Chinese characters use 3 bytes of memory. So str[1:] actually makes a string slice where the first character's data has gotten cut up.

If you instead start the slice at index 3, then you'd get the wanted string:

str := "小猫咪"
sub_str := str[3:]
fmt.println(sub_str) // 猫咪

However, it is also possible to slice using rune indices. You can do that using strings.substring_from:

str := "小猫咪"
sub_str, _ := strings.substring_from(str, 1)
fmt.println(sub_str) // 猫咪

strings.substring_from will make a substring that starts at the rune with index 1 and then goes to the end of the string. This also gives us the expected 猫咪 string. But note that a procedure such as substring_from needs to iterate over the string. Why? In this case we want a substring that starts at rune index 1. But the string doesn't know how many bytes the rune at index 0 uses. So in order to skip the rune at index 0, it must loop from the start and count the runes.

If you want to know the byte index of the current rune when iterating a string, then you can add a second loop variable:

str := "小猫咪"

for r, i in str {
	fmt.println(i, r)
}

which prints

0 小
3 猫
6 咪

This is useful for constructing slices:

str := "小猫咪"

for r, i in str {
	from_start := str[:i]
	fmt.println(from_start)
}

The above will output

[blank line]
小
小猫

If you want the current rune included in the substring. Then you need to add the byte size of it. You can fetch the byte size using utf8.rune_size(r):

str := "小猫咪"

for r, i in str {
	from_start := str[:i + utf8.rune_size(r)]
	fmt.println(from_start)
}

Note how I added utf8.rune_size(r) when slicing. This will print:

小
小猫
小猫咪

I mentioned earlier that there are some cases where one rune is not equivalent to one character. In the English and Chinese examples we've seen so far, every character was a single rune. However, this is not true for grapheme clusters. A grapheme cluster is something that appears as a single character on the screen, but actually consists of several runes. Here's an example:

str := "g̈"

for r in str {
	fmt.println(r)
}

The code will loop over str and print each rune on a separate line. The output is:

g
̈ 

So this g̈ is a grapheme cluster: It consists of two separate runes! There are procedures to work with grapheme clusters in core/unicode/utf8/grapheme.odin. For example, you can use utf8.decode_grapheme_clusters(str) to get an array of all the grapheme clusters in a string. Beware that decode_grapheme_clusters allocates memory and is expensive to run.

You may want to construct a string by combining a few variables and values. There are a couple of ways to do this.

A simple method is to use the fmt.tprint or fmt.aprint procedures.

name := "Pontus"
age := 7
str := fmt.tprint(name, "is", age)
fmt.println(str) // Pontus is 7.

This will combine name, "is" and age with a space between each, which results in the string "Pontus is 7". The t in front of print means "temporary". This means that this procedure allocates the memory needed for the string using context.temp_allocator. You can swap out the space that tprint puts between each argument for something else. In the following example we put " really " between each word using the sep parameter of tprint:

name := "Pontus"
age := 7
str := fmt.tprint(name, "is", age, sep = " really ")
fmt.println(str) // Pontus really is really 7.

aprint is just like tprint, but you can specify which allocator you want to use. So this:

str := fmt.tprint(name, "is", age)

is identical to this:

str := fmt.aprint(name, "is", age, allocator = context.temp_allocator)

Something that is often more useful than tprint and aprint are the tprintf and aprintf procedures. Note the added f at the end of the name. These procedures take what is known as a format string:

name := "Pontus"
age := 7
str := fmt.tprintf("%v is %v", name, age)

This has the same result as when we used tprint, but here we see %v a couple of times in the first argument, those %v are replaced by name and age in the order they are stated. There's an aprintf version as well, which lets you specify your own allocator.

There are lots of different format strings you can use. The %v we used in this example just does whatever makes sense for the type of the thing you want to print. But if you want to print a floating point number and only show two decimals, then you can use %.2f instead of %v. See <odin>/core/fmt/doc.odin for a comprehensive list of format strings you can use.

There are variants of all these procedures that add in a line break at the end of the string, such as fmt.tprintfln. Note the ln (Line Break) at the end.

Finally, if you do not want to use any allocator at all, then you can use a buffer that lives on the stack combined with fmt.bprintf:

name := "Pontus"
age := 7
buf: [128]byte
str := fmt.bprintf(buf[:], "%v is %v", name, age)

str will be valid as long as buf is valid, which will be until the end of the current scope. Note that this string has a fixed limit of 128 bytes.

If you need to construct a big string that perhaps contains several lines, then I'd recommend using a string builder. Here's an example:

lines := []string {
	"I like",
	"I look for",
	"Where are the",
}
b := strings.builder_make()

for l, i in lines {
	strings.write_string(&b, l)
	if i != len(lines) - 1{
		strings.write_string(&b, " cats.\n")
	} else {
		strings.write_string(&b, " cats?")
	}
}

str := strings.to_string(b)
fmt.println(str)
strings.builder_destroy(&b)

In this example lines is a slice containing three different strings.

The loop goes over lines and writes each of them to the builder. But it also adds a different ending to each line depending on if it is the last line or not.

After the loop is done, it extracts the string str from the builder:

str := strings.to_string(b)

It then prints the constructed string and destroys the builder, which will deallocate str.

The output of the program is:

I like cats.
I look for cats.
Where are the cats?

It's important to understand where the allocations happen in this example. The line

b := strings.builder_make()

just sets up the builder. It does not allocate any memory. However, when you use strings.write_string then the builder may need to grow. This is similar to using append on a dynamic array. In fact, the builder uses a dynamic array internally.

The final string you get by running str := strings.to_string(b) does not cause any extra allocation, it just gives you a string that looks into the data of the builder. So after the builder is destroyed then str is no longer valid.

If you just need a temporary string, then you can pass context.temp_allocator to builder_make:

b := strings.builder_make(context.temp_allocator)

The builder stores this allocator internally so that it can use it when it needs to grow. You can skip the strings.builder_destroy(&b) line when using the temp allocator.

Using the temp allocator for the builder is my favorite way to construct strings, even if I need them around permanently. Here's an example of what I mean:

b := strings.builder_make(context.temp_allocator)

strings.write_string(&b, "I have ")
strings.write_int(&b, 7)
strings.write_string(&b, " cats.")

str := strings.clone(strings.to_string(b))

Here the builder uses the temp allocator for the construction of the string. At the end I use strings.clone in order to clone the builder's final string. Since this cloning uses context.allocator by default, then the final str will live on even after the temp allocator is reset.

I tend to do things in this fashion quite often: Construct intermediate values using a temp allocator and only allocate the final result on a non-temp allocator for permanent storage. For example, I tend to load entire files on the temp allocator and do intermediate processing of the file's data using the temp allocator. Only at the end do I use context.allocator in order to get a permanent copy of the final result.

Strings in Odin consist of a pointer and a length. Your code uses the type string. But internally, a string is represented by the type Raw_String, which looks like this:

Raw_String :: struct {
	data: [^]byte,
	len:  int,
}

This looks very similar to a slice! There's a data field and a length, just like in a Raw_Slice. Both slices and strings support the slice operator [:], which makes sense given how similar they are. You can see a string as a slice of bytes, with some syntactic sugar poured on top.

Depending on how you create your string, the data field may point to memory that lives in very different places. Let's look at three examples.

(1) When you assign a string literal to a string variable, like this:

my_string := "Hellope!"

then my_string is of type string. But you can also see it as a Raw_String struct that lives on the stack. The Raw_String's data field will point to memory that lives in the read-only data block of the program. One could easily think that the whole string, including the data, would live on the stack when declared like this. But that's not the case.

Never try to run delete on a string initialized from a string literal. Since the data field points to the read-only data, trying to deallocate that data will crash your program!

(2) For a dynamically allocated string, such as this:

my_string := fmt.aprint("Codin", "Odin", allocator = context.allocator)

or this:

my_string := strings.clone("Hellope!")

then my_string will be a Raw_String that lives on the stack. Its field data will point to memory that lives on the heap (assuming that context.allocator is a heap allocator).

These strings should be deallocated using delete(my_string).

(3) You can also create a fixed array of bytes and use something like fmt.bprint to create a string that lives completely on the stack:

buf: [128]byte
my_string := fmt.bprint(buf[:], "Hellope")

Not only does the Raw_String struct live on the stack, but in this case the data field within the Raw_String points to stack memory as well. This is because the string was written into buf by bprint and buf is a fixed array that lives on the stack. When the current scope ends, then my_string is no longer valid. Trying to run delete(my_string) would crash the program since the string's data is not dynamically allocated.

A common problem is figuring out how to delete dynamically allocated strings that are mixed with string constants. As I mentioned in the previous subsection, running delete on a constant string will crash your program.

Here's an example of how it can go wrong:

make_some_strings :: proc() -> [dynamic]string {
	strs: [dynamic]string
	append(&strs, "Hellope!")
	append(&strs, "Hi!")
	append(&strs, strings.clone("Dynamically allocated!"))
	append(&strs, "Constant!")
	append(&strs, strings.clone("Dynamic!"))
	return strs
}

main :: proc() {
	strs := make_some_strings()

	// Insert code here that uses `strs`
	// for something important.

	for s in strs {
		delete(s)
	}

	delete(strs)

	fmt.println("Probably didn't get here due to `delete(s)` crashing")
}

make_some_strings makes a dynamic array of strings. Some of them are constant strings, such as "Hellope!". There are also two strings that are dynamically allocated in there, such as this one: strings.clone("Dynamically allocated!").

The main procedure loops over the array of strings returned by make_some_strings, and tries to deallocate them. But it has no good way of knowing if a string is a constant or not. This program will crash when it tries to run delete on one of those string constants.

We'll look at two ways of fixing this. The simplest way wastes a bit of memory, but is very straight forward; dynamically allocate all the strings in the array:

make_some_strings :: proc() -> [dynamic]string {
	strs: [dynamic]string

	strs_add :: proc(strs: ^[dynamic]string, s: string) {
		append(strs, strings.clone(s))
	}

	strs_add(&strs, "Hellope!")
	strs_add(&strs, "Hi!")
	strs_add(&strs, "Dynamically allocated!")
	strs_add(&strs, "Not constant anymore!")
	strs_add(&strs, "Dynamic!")
	return strs
}

main :: proc() {
	strs := make_some_strings()

	// Insert code here that uses `strs`
	// for something important.

	for s in strs {
		delete(s)
	}

	delete(strs)

	fmt.println("Probably got here!")
}

In this version, all the strings inside strs are dynamically allocated. The strs_add procedure simply clones them. Now delete will no longer crash.

The second method will use a concept we haven't talked about yet: Memory arenas. I will talk about arenas in chapter 13. Here I just present this second method with some overview comments about how it works:

make_some_strings :: proc() -> ([dynamic]string, vmem.Arena) {
	arena: vmem.Arena
	strs: [dynamic]string
	arena_allocator := vmem.arena_allocator(&arena)
	append(&strs, "Hellope!")
	append(&strs, "Hi!")
	append(&strs, strings.clone("Dynamically allocated!", arena_allocator))
	append(&strs, "Constant!")
	append(&strs, strings.clone("Dynamic!", arena_allocator))
	return strs, arena
}

main :: proc() {
	strs, strs_arena := make_some_strings()

	// Insert code here that uses `strs`
	// for something important.

	vmem.arena_destroy(&strs_arena)
	delete(strs)

	fmt.println("Probably got here!")
}

Within make_some_strings we set up a virtual memory arena. The arena_allocator we send into strings.clone will allocate those cloned strings into that arena. The benefit of an arena is that we can destroy the arena in order to deallocate everything within it. Note how we have replaced this:

for s in strs {
	delete(s)
}

with this

vmem.arena_destroy(&strs_arena)

This is less wasteful since we didn't have to clone all the strings. The deallocation of the strings is simpler: We just destroy the arena. But in other ways it's more complicated: make_some_strings has to set up the arena and also has to return two values: The array and the arena.

Also, note that I didn't allocate the dynamic array using the arena. I explain why in chapter 13 when I talk about how arenas do not support individual deallocations.

For the sake of simplicity I tend to choose the first method.

This was mentioned briefly in the Untyped Types summary. You can create string constants like this:

A_STRING_CONSTANT :: "Hellope!"

String constants have the type Untyped String. These constants can be implicitly cast to both the type string, and also the type cstring. cstring is for interfacing with libraries written in the C programming language.

You can use + to combine string constants and literals into longer strings constants:

A_CONSTANT :: "Hellope!"
my_string := A_CONSTANT + " How are you?"
fmt.println(my_string) // Hellope! How are you?

You can never use + with a string assigned to a variable. If you need to combine strings that live inside variables, then use fmt or a builder.

The reason + can only be used with constants is because + (when used with strings) gets evaluated at compile time. Think of the compiler as copy-pasting together whatever you put to the left and right of the +. It could not do this copy-pasting with something in a variable, because it is only known at run time what that variable contains.

It may seem strange that the indices you feed into the slice operator, such as str[1:5], are byte indices. Why doesn't it use rune indices? Let's discuss why using rune indices would be problematic.

Each rune may occupy anything between 1 and 4 bytes of memory. If the slice operator used rune indices, then it could not directly grab the memory address where the slice should start. Instead, it would have to iterate over the string and start counting the runes.

One could avoid such rune counting by having the string store an additional array containing the byte index of each rune. But then the Raw_String type would be much more complicated. It would require a whole extra array of data. So one reason to not do this is that it is a bit complex. But there are other problems as well.

As we have seen, runes don't always represent a single character on the screen. A string may contain grapheme clusters, which use multiple runes for a single character. With this in mind, all the effort spent on making it possible to slice using rune indices would still be in vain. Making strings aware of their grapheme clusters and using some kind of grapheme-cluster indices is a very bad idea due to the complexity of just decoding grapheme clusters.

With all this in mind it is not so weird that the string slice operator uses byte indices: It is the only alternative that doesn't make weird assumptions. It is still possible to reason about runes and grapheme clusters when you need to.

There are some specifics related to strings and the Windows API that may be a bit tricky to figure out. The strings in the Windows API uses UTF-16, while strings in Odin use UTF-8. Also, the Windows API uses zero-terminated strings. So you need to do some conversions when interfacing with the Windows API.

Say that you want to change the title of a window. You do that using the following procedure from core:sys/windows:

SetWindowTextW :: proc(hWnd: HWND, lpString: LPCWSTR) -> BOOL

The lpString parameter is assumed to be one of those zero-terminated UTF-16 strings. Use windows.utf8_to_wstring to convert from an Odin string to the required string format:

window_title := "My Great Program"
windows.SetWindowTextW(hwnd, windows.utf8_to_wstring(window_title))

utf8_to_wstring both does the conversion to UTF-16 and also adds in the zero termination. It uses the temp allocator by default.

Similarly, we may need to fetch the current window title. You do that using GetWindowTextW:

GetWindowTextW :: proc(hWnd: HWND, lpString: LPWSTR, nMaxCount: INT) -> INT

This procedure wants some memory to write the window title into. That's lpString. nMaxCount says how many characters it is possible to fit into lpString.

Fetch the title and turn it into an Odin string like this:

title_wstr: [128]windows.WCHAR
title_len := windows.GetWindowTextW(hwnd, raw_data(&title_wstr), len(title_wstr))
title_str, title_str_err := windows.wstring_to_utf8(raw_data(&title_wstr), int(title_len))

if title_str_err == nil {
	fmt.println(title_str)
}

The windows.WCHAR type is the Windows UTF-16 character type. title_wstr is a stack allocated fixed array of UTF-16 characters. We send title_wstr into GetWindowTextW. That procedure will fill out title_wstr with the title string and return how many characters it actually wrote.

Then we use windows.wstring_to_utf8 to convert this UTF-16 string into an Odin UTF-8 string. windows.wstring_to_utf8 also uses the temp allocator by default.

We've seen context.allocator and context.temp_allocator a bunch of times. It has become time to talk about what this context thing is!

The context is often referred to as the Implicit Context. We say that it is implicit because it is automatically passed along to any procedure that you call. This means that when you do something like this:

fmt.println("Hellope!")

then fmt.println is automatically fed a hidden parameter called context. Its value is based on whatever value context has in the current scope.

The type of context is a struct that looks like this:

Context :: struct {
	allocator:              Allocator,
	temp_allocator:         Allocator,
	assertion_failure_proc: Assertion_Failure_Proc,
	logger:                 Logger,
	random_generator:       Random_Generator,

	user_ptr:   rawptr,
	user_index: int,

	// Internal use only
	_internal: rawptr,
}

The fields in there are:

• allocator: Default memory allocator.
• temp_allocator: Default temporary memory allocator.
• assertion_failure_proc: The procedure that is run when the condition in assert(condition, "Error message") evaluates to false.
• logger: Default logger, decides what happens when you use the procedures in core:log.
• random_generator: Defines the random generator used by for example core:math/rand.
• user_ptr, user_index: Custom extra data that you can use in any way you want.

context is automatically passed along to any procedure you call. You can modify fields in the context before calling a procedure, in order to make that procedure use different allocators, loggers etc. As we shall see, there are situations where this is a good idea and situations where it is better to pass explicit parameters.

When a scope ends, then any changes you've made to the context are reverted. The context will again look like it did at the beginning of that scope.

The rest of this chapter will talk about each of the fields of context and how you use them.

Say that you have this code:

do_work :: proc() {
	make_lots_of_ints :: proc() -> []int {
		ints := make([]int, 4096)

		// Give the numbers of `ints` some
		// values.
		for &v, idx in ints {
			v = idx * 4 
		}

		return ints
	}

	my_ints := make_lots_of_ints()
}

make_lots_of_ints dynamically allocates a slice of 4096 integers and sets them to some interesting values, and thereafter returns the slice. Say that you'd prefer to have this slice allocated using the temp allocator. We know that we can do that by changing

ints := make([]int, 4096)

to

ints := make([]int, 4096, context.temp_allocator)

However, let's pretend make_lots_of_ints is a procedure that lives somewhere else. What if we don't have access to that code, so we can't modify it. How can we then make it use the temp allocator?

We can modify context.allocator before calling it:

do_work :: proc() {
	make_lots_of_ints :: proc() -> []int {
		ints := make([]int, 4096)

		// Give the numbers of `ints` some
		// values.
		for &v, idx in ints {
			v = idx * 4 
		}

		return ints
	}

	context.allocator = context.temp_allocator
	my_ints := make_lots_of_ints()
}

Note the line

context.allocator = context.temp_allocator

And also remember that context is automatically passed along into make_lots_of_ints. So within make_lots_of_ints, whenever context.allocator is used, it is actually using the temporary allocator. Since make defaults to context.allocator, then it will now end up using the temporary allocator.

Swapping out the allocator like this makes it possible to inject an allocator into a procedure where you normally don't have access to changing the allocator.

I recommend that you make procedures that allocate memory have an explicit allocator parameter. The example in the previous section would then look like this:

do_work :: proc() {
	make_lots_of_ints :: proc(allocator := context.allocator) -> []int {
		ints := make([]int, 4096, allocator)

		// Give the numbers of `ints` some
		// values.
		for &v, idx in ints {
			v = idx * 4 
		}

		return ints
	}

	my_ints := make_lots_of_ints(context.temp_allocator)
}

Here we see that make_lots_of_ints has an allocator parameter with the default value context.allocator. This allocator is then passed to make. This means that we can call make_lots_of_ints without specifying any allocator if we are happy with the default. But we can also override it, which we do when we call make_lots_of_ints:

my_ints := make_lots_of_ints(context.temp_allocator)

Having an allocator parameter on a procedure that allocates memory is a good documentation to the programmer that uses the procedure. It gives the programmer a hint that the return value will be allocated. This is clearer than setting context.allocator before calling make_lots_of_ints.

Also, when you modify context.allocator then that will affect the remaining code in the scope. Using an explicit allocator parameter avoids that.

I recommend only overriding context.allocator in two cases:

1. When you call a procedure that allocates memory using context.allocator and you want to use some other allocator, but it doesn't have any allocator parameter that you can override.
2. When you really want all the code within a scope to use that allocator. A common example is to swap out context.allocator in the first few lines of the main procedure. This effectively makes your whole program use some other allocator. We'll see this when we talk about how to set up the tracking allocator in chapter 13.1.

In chapter 9.7 we saw how to use context.temp_allocator. But what about modifying that field on the context? Just like modifying context.allocator before calling a procedure, you could also swap out the temporary allocator. In practice this doesn't happen as often.

The most common reason to modify context.temp_allocator would be because you want your whole program to use some other temporary allocator. This would mean that you assign some other allocator to context.temp_allocator in the beginning of the main procedure, so that the rest of the program uses that temporary allocator.

Assertions ensure that something that you expect to be true actually is true.

If you do this:

number := 5
assert(number == 7, "Number has wrong value")

Then the program will crash on purpose because the condition of the assert was false (number wasn't 7).

You can modify context.assertion_failure_proc to alter what happens when an assertion fails. Here's a small program that modifies it when main starts, so that the rest of the program uses the procedure assert_fail when an assertion fails:

package assertion_test

import "core:fmt"
import "base:runtime"

assert_fail :: proc(prefix, message: string, loc := #caller_location) -> ! {
	fmt.printfln("Oh no, an assertion at line: %v", loc)
	fmt.println(message)
	runtime.trap()
}

main :: proc() {
	context.assertion_failure_proc = assert_fail
	number := 5
	assert(number == 7, "Number has wrong value")
}

Running this program will print something like:

Oh no, an assertion at line: C:/code/assertion_test/main.odin(15:2)
Number has wrong value

Note the ! at the end of

assert_fail :: proc(prefix, message: string, loc := #caller_location) -> ! {

This means that this procedure will not return, because we are expecting it to crash the program. We say that this procedure is a diverging procedure. This means that the procedure must end with calling some other diverging procedure. In this case we call runtime.trap(), which is a diverging procedure that will tell the operating system that some kind of failure has occurred.

In many 'release builds' of software, asserts are disabled to speed things up. That can be done using the -disable-assert compilation flag. That will make all calls to assert always succeed. If you need an assert that always works, then you can use ensure(condition, "Failure message). ensure will always work, even when -disable-assert is used. It also uses the assertion_failure_proc.

Odin comes with logger functionality in core:log. Instead of using fmt.println everywhere you can use log.info and log.error etc to log events. You can set up your logger to go to a file, or to a console or to wherever you want.

To make the logger messages appear in the console, just add context.logger = log.create_console_logger() at the start of your program:

package logger_test

import "core:log"

main :: proc() {
	context.logger = log.create_console_logger()

	log.info("Program started")

	// Rest of program goes here,
	// it will use context.logger whenever
	// you run `log.info`, `log.error` etc.

	log.destroy_console_logger(context.logger)
}

Since we set context.logger at the start of main, all subsequent procedure calls (your whole program), will use this logger as well.

Logging to a file requires a bit more setup:

package main

import "core:log"
import "core:os"

main :: proc() {
	mode: int = 0
	when ODIN_OS == .Linux || ODIN_OS == .Darwin {
		mode = os.S_IRUSR | os.S_IWUSR | os.S_IRGRP | os.S_IROTH
	}

	logh, logh_err := os.open("log.txt", (os.O_CREATE | os.O_TRUNC | os.O_RDWR), mode)

	if logh_err == os.ERROR_NONE {
		os.stdout = logh
		os.stderr = logh
	}

	logger := logh_err == os.ERROR_NONE ? log.create_file_logger(logh) : log.create_console_logger()
	context.logger = logger

	// Rest of program goes here, it will
	// use `context.logger` whenever you
	// run `log.info`, `log.error` etc.
	//
	// Also, fmt.println will be redirected
	// to the logger, due to the
	// `os.stdout = logh` lines above.
	all_the_code_in_your_program()

	if logh_err == os.ERROR_NONE {
		log.destroy_file_logger(logger)
	} else {
		log.destroy_console_logger(logger)
	}
}

The code above opens log.txt for writing using os.open. I have provided the flags required to make it work on Linux/macOS too. logh_err tells us if it was able to open the log file for writing. If it did succeed, then it goes ahead and creates the file logger using log.create_file_logger(logh). If it fails to open the file then it uses a console logger instead.

Regardless of which logger it was able to create, context.logger is set to that value.

This part of the code is optional:

if logh_err == os.ERROR_NONE {
	os.stdout = logh
	os.stderr = logh
}

What it does is redirect fmt.printfln() and similar procedures, so they instead go to the log file. However, if you have the logger setup properly, then I recommend just using the procedures in the core:log package whenever you can.

Available logging procedures are:

log.debug("message")
log.info("message")
log.warn("message")
log.error("message")
log.fatal("message")
log.panic("message")

These are in order for "severity". log.panic is special in the sense that it logs, but unlike the others it also crashes the program on purpose.

All those logging procedures also have a version that ends with f, such as log.errorf. Those versions use a format string so you can do stuff like log.errorf("The thing called %v is broken", name_of_thing).

Have a look in <odin>/core/log/log.odin to see how the log systems works in detail.

There is a random number generator set up by default. However, you can modify context.random_generator, changing how any code called after that point generates random numbers. While you can write your own random number generator, a common thing is to use the default one, but seed it differently:

package random_generator_example

import "base:runtime"
import "core:fmt"
import "core:math/rand"

main :: proc() {
	random_state := rand.create(42)
	context.random_generator = runtime.default_random_generator(&random_state)
	fmt.println(rand.int_max(100))
}

If you run the above then it will print 48, just like it did for me. This is because we are forcing the seed of the random generator to be 42.

If we don't override the random generator, then rand.int_max() will probably give a different value each time you run the program. This is because the seed is automatically set when the program starts up.

Instead of replacing context.random_generator, you can also just call rand.reset with your seed:

rand.reset(42)
// Should also print 48
fmt.println(rand.int_max(100))

It resets context.random_generator to use the seed 42.

context.user_ptr and context.user_index are two extra fields on the context that you can use to implicitly pass a pointer or an integer. They are useful when you need to send along some data to a callback. This way we can provide extra information into the callback. In the example below, note how we set context.user_ptr before calling slice.sort_by. We can thereby use that pointer within the sorting_proc callback.

numbers := []int { 2, 7, 42, 1}

Sort_Settings :: struct {
	put_at_end: int,
}

sorting_proc :: proc(i, j: int) -> bool {
	sort_settings := (^Sort_Settings)(context.user_ptr)

	if sort_settings != nil {
		if i == sort_settings.put_at_end {
			return false
		}

		if j == sort_settings.put_at_end {
			return true
		}
	}

	return i < j
}

sort_settings := Sort_Settings {
	put_at_end = 2,
}

context.user_ptr = &sort_settings
slice.sort_by(numbers, sorting_proc)
fmt.println(numbers) // [1, 7, 42, 2]

Each time you call a procedure the current context is passed into it. However, it does not copy the current context, it just passes a pointer to it.

If you do something like this:

context.allocator = context.temp_allocator
my_ints := make_lots_of_ints()

Then there is some behind-the-scenes magic that takes the current context and copies it to a new stack variable. All subsequent procedure calls within that scope will be fed a pointer to this new context instead of the old one. When the scope ends, it reverts to using the old context pointer when calling procedures.

Manual memory management can be quite overwhelming for the beginner. Let's take a look at two tools that can make it easier:

• Tracking memory leaks using the tracking allocator.
• Using arena allocators to group allocations according to their lifetime.

When it comes to the arena allocator we'll also discuss the different types of arena allocators that come with Odin.

Before we begin I want to mention that we've already discussed one concept that makes manual memory management easier: The temporary allocator. By doing short-lived allocations using the temporary allocator, you can greatly reduce the number of manual deallocations in your program.

Let's look at how to use Odin's tracking allocator. It's an allocator that helps you find memory leaks. This makes memory management easier since it's one less thing for us to worry about. Let's first talk about what a leak is and what it is not, and whether or not we can track them:

• If your program periodically allocates memory by for example creating dynamic arrays or allocating using new, but then never deallocates that memory using delete or free, then the program's memory usage will continuously grow. This is a memory leak and the tracking allocator can help you find these.

• If your program allocates memory once at startup and forgets to free it, then I would not label this as a memory leak since the memory usage isn't continuously growing. Nothing is "leaking"! The memory allocated once at startup will be deallocated when the program shuts down. A program can't continue to hog memory after it has shut down, so you don't have to worry about that.

• Say that your program contains a dynamic array that is created at startup. It is meant to exist until your program shuts down. If the program runs for a long time and periodically adds things to this dynamic array, but erroneously never removes anything, then your program's memory usage will grow over time. This is a memory leak, but the tracking allocator cannot help with finding this. It's more of a logic error in your code. These kind of memory leaks can happen in both manually and automatically memory managed languages.

Let's now set up the tracking allocator. Odin's core collection comes with one, you'll find it in the core:mem package. Below I show how to set it up:

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 {
				for _, entry in track.allocation_map {
					fmt.eprintf("%v leaked %v bytes\n", entry.location, entry.size)
				}
			}
			mem.tracking_allocator_destroy(&track)
		}
	}
	
	// rest of program goes here
}

In order for the tracking allocator to be set up, you must compile this program with the -debug compiler flag. This is because of the when ODIN_DEBUG {} block in main. I'll explain that in more detail soon.

To test the tracking allocator, replace the line // rest of program goes here with the line following line:

ints := make([]int, 4096)

Thereafter, run the program. When it shuts down, it should print the following: