Skip to content

Commit

Permalink
fix links to ziglang.org/documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
mega-dean authored and Sobeston committed Apr 7, 2024
1 parent 0959a84 commit da4a7d7
Show file tree
Hide file tree
Showing 25 changed files with 61 additions and 61 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ standard library - no allocations happen behind your back in the standard
library.

The most basic allocator is
[`std.heap.page_allocator`](https://ziglang.org/documentation/master/std/#A;std:heap.page_allocator).
[`std.heap.page_allocator`](https://ziglang.org/documentation/master/std/#std.heap.page_allocator).
Whenever this allocator makes an allocation, it will ask your OS for entire
pages of memory; an allocation of a single byte will likely reserve multiple
kibibytes. As asking the OS for memory requires a system call, this is also
Expand All @@ -30,15 +30,15 @@ with a free - this is a common pattern for memory management in Zig.
<CodeBlock language="zig">{AllocatorsAlloc}</CodeBlock>

The
[`std.heap.FixedBufferAllocator`](https://ziglang.org/documentation/master/std/#A;std:heap.FixedBufferAllocator)
[`std.heap.FixedBufferAllocator`](https://ziglang.org/documentation/master/std/#std.heap.FixedBufferAllocator)
is an allocator that allocates memory into a fixed buffer and does not make any
heap allocations. This is useful when heap usage is not wanted, for example,
when writing a kernel. It may also be considered for performance reasons. It
will give you the error `OutOfMemory` if it has run out of bytes.

<CodeBlock language="zig">{AllocatorsFba}</CodeBlock>

[`std.heap.ArenaAllocator`](https://ziglang.org/documentation/master/std/#A;std:heap.ArenaAllocator)
[`std.heap.ArenaAllocator`](https://ziglang.org/documentation/master/std/#std.heap.ArenaAllocator)
takes in a child allocator and allows you to allocate many times and only free
once. Here, `.deinit()` is called on the arena, which frees all memory. Using
`allocator.free` in this example would be a no-op (i.e. does nothing).
Expand All @@ -59,7 +59,7 @@ still be many times faster than page_allocator.
<CodeBlock language="zig">{AllocatorsGpa}</CodeBlock>

For high performance (but very few safety features!),
[`std.heap.c_allocator`](https://ziglang.org/documentation/master/std/#A;std:heap.c_allocator)
[`std.heap.c_allocator`](https://ziglang.org/documentation/master/std/#std.heap.c_allocator)
may be considered. This,however, has the disadvantage of requiring linking Libc,
which can be done with `-lc`.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ import ArrayList from "!!raw-loader!./02.arraylist.zig";
# ArrayList

The
[`std.ArrayList`](https://ziglang.org/documentation/master/std/#A;std:ArrayList)
[`std.ArrayList`](https://ziglang.org/documentation/master/std/#std.ArrayList)
is commonly used throughout Zig, and serves as a buffer which can change in
size. `std.ArrayList(T)` is similar to C++'s `std::vector<T>` and Rust's
`Vec<T>`. The `deinit()` method frees all of the ArrayList's memory. The memory
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ file before reading what we have written.
<CodeBlock language="zig">{CwdCreate}</CodeBlock>

The functions
[`std.fs.openFileAbsolute`](https://ziglang.org/documentation/master/std/#A;std:fs.openFileAbsolute)
[`std.fs.openFileAbsolute`](https://ziglang.org/documentation/master/std/#std.fs.openFileAbsolute)
and similar absolute functions exist, but we will not test them here.

We can get various information about files by using `.stat()` on them. `Stat`
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,25 +6,25 @@ import Custom from "!!raw-loader!./04.readers-and-writers-custom.zig";

# Readers and Writers

[`std.io.Writer`](https://ziglang.org/documentation/master/std/#A;std:io.Writer)
[`std.io.Writer`](https://ziglang.org/documentation/master/std/#std.io.Writer)
and
[`std.io.Reader`](https://ziglang.org/documentation/master/std/#A;std:io.Reader)
[`std.io.Reader`](https://ziglang.org/documentation/master/std/#std.io.Reader)
provide standard ways of making use of IO. `std.ArrayList(u8)` has a `writer`
method which gives us a writer. Let's use it.

<CodeBlock language="zig">{Writer}</CodeBlock>

Here we will use a reader to copy the file's contents into an allocated buffer.
The second argument of
[`readAllAlloc`](https://ziglang.org/documentation/master/std/#A;std:io.Reader.readAllAlloc)
[`readAllAlloc`](https://ziglang.org/documentation/master/std/#std.io.Reader.readAllAlloc)
is the maximum size that it may allocate; if the file is larger than this, it
will return `error.StreamTooLong`.

<CodeBlock language="zig">{Reader}</CodeBlock>

A common usecase for readers is to read until the next line (e.g. for user
input). Here we will do this with the
[`std.io.getStdIn()`](https://ziglang.org/documentation/master/std/#A;std:io.getStdIn)
[`std.io.getStdIn()`](https://ziglang.org/documentation/master/std/#std.io.getStdIn)
file.

{/* Code snippet not tested as it uses stdin/stdout */}
Expand Down Expand Up @@ -67,7 +67,7 @@ test "read until next line" {
```

An
[`std.io.Writer`](https://ziglang.org/documentation/master/std/#A;std:io.Writer)
[`std.io.Writer`](https://ziglang.org/documentation/master/std/#std.io.Writer)
type consists of a context type, error set, and a write function. The write
function must take in the context type and a byte slice. The write function must
also return an error union of the Writer type's error set and the number of
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ import Custom from "!!raw-loader!./05.formatting-custom.zig";

# Formatting

[`std.fmt`](https://ziglang.org/documentation/master/std/#A;std:fmt) provides
[`std.fmt`](https://ziglang.org/documentation/master/std/#std.fmt) provides
ways to format data to and from strings.

A basic example of creating a formatted string. The format string must be
Expand All @@ -21,7 +21,7 @@ Writers conveniently have a `print` method, which works similarly.

Take a moment to appreciate that you now know from top to bottom how printing
Hello World works.
[`std.debug.print`](https://ziglang.org/documentation/master/std/#A;std:debug.print)
[`std.debug.print`](https://ziglang.org/documentation/master/std/#std.debug.print)
works the same, except it writes to stderr and is protected by a mutex.

{/* Code snippet not tested as it uses stdin/stdout */}
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Crypto

[`std.crypto`](https://ziglang.org/documentation/master/std/#A;std:crypto)
[`std.crypto`](https://ziglang.org/documentation/master/std/#std.crypto)
includes many cryptographic utilities, including:

- AES (Aes128, Aes256)
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Threads

While Zig provides more advanced ways of writing concurrent and parallel code,
[`std.Thread`](https://ziglang.org/documentation/master/std/#A;std:Thread) is
[`std.Thread`](https://ziglang.org/documentation/master/std/#std.Thread) is
available for making use of OS threads. Let's make use of an OS thread.

```zig
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Hash Maps

The standard library provides
[`std.AutoHashMap`](https://ziglang.org/documentation/master/std/#A;std:AutoHashMap),
[`std.AutoHashMap`](https://ziglang.org/documentation/master/std/#std.AutoHashMap),
which lets you easily create a hash map type from a key type and a value type.
These must be initiated with an allocator.

Expand Down Expand Up @@ -54,7 +54,7 @@ test "fetchPut" {
}
```

[`std.StringHashMap`](https://ziglang.org/documentation/master/std/#A;std:StringHashMap)
[`std.StringHashMap`](https://ziglang.org/documentation/master/std/#std.StringHashMap)
is also provided for when you need strings as keys.

```zig
Expand All @@ -72,16 +72,16 @@ test "string hashmap" {
}
```

[`std.StringHashMap`](https://ziglang.org/documentation/master/std/#A;std:StringHashMap)
[`std.StringHashMap`](https://ziglang.org/documentation/master/std/#std.StringHashMap)
and
[`std.AutoHashMap`](https://ziglang.org/documentation/master/std/#A;std:AutoHashMap)
[`std.AutoHashMap`](https://ziglang.org/documentation/master/std/#std.AutoHashMap)
are just wrappers for
[`std.HashMap`](https://ziglang.org/documentation/master/std/#A;std:HashMap). If
[`std.HashMap`](https://ziglang.org/documentation/master/std/#std.HashMap). If
these two do not fulfil your needs, using
[`std.HashMap`](https://ziglang.org/documentation/master/std/#A;std:HashMap)
[`std.HashMap`](https://ziglang.org/documentation/master/std/#std.HashMap)
directly gives you much more control.

If having your elements backed by an array is wanted behaviour, try
[`std.ArrayHashMap`](https://ziglang.org/documentation/master/std/#A;std:ArrayHashMap)
[`std.ArrayHashMap`](https://ziglang.org/documentation/master/std/#std.ArrayHashMap)
and its wrapper
[`std.AutoArrayHashMap`](https://ziglang.org/documentation/master/std/#A;std:AutoArrayHashMap).
[`std.AutoArrayHashMap`](https://ziglang.org/documentation/master/std/#std.AutoArrayHashMap).
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Stacks

[`std.ArrayList`](https://ziglang.org/documentation/master/std/#A;std:ArrayList)
[`std.ArrayList`](https://ziglang.org/documentation/master/std/#std.ArrayList)
provides the methods necessary to use it as a stack. Here's an example of
creating a list of matched brackets.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -13,10 +13,10 @@ test "sorting" {
}
```

[`std.sort.asc`](https://ziglang.org/documentation/master/std/#A;std:sort.asc)
and [`.desc`](https://ziglang.org/documentation/master/std/#A;std:sort.desc)
[`std.sort.asc`](https://ziglang.org/documentation/master/std/#std.sort.asc)
and [`.desc`](https://ziglang.org/documentation/master/std/#std.sort.desc)
create a comparison function for the given type at comptime; if non-numerical
types should be sorted, the user must provide their own comparison function.

[`std.mem.sort`](https://ziglang.org/documentation/master/std/#A;std:mem.sort)
[`std.mem.sort`](https://ziglang.org/documentation/master/std/#std.mem.sort)
has a best case of O(n), and an average and worst case of O(n*log(n)).
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,9 @@ It is a common idiom to have a struct type with a `next` function with an
optional in its return type, so that the function may return a null to indicate
that iteration is finished.

[`std.mem.SplitIterator`](https://ziglang.org/documentation/master/std/#A;std:mem.SplitIterator)
[`std.mem.SplitIterator`](https://ziglang.org/documentation/master/std/#std.mem.SplitIterator)
(and the subtly different
[`std.mem.TokenIterator`](https://ziglang.org/documentation/master/std/#A;std:mem.TokenIterator))
[`std.mem.TokenIterator`](https://ziglang.org/documentation/master/std/#std.mem.TokenIterator))
is an example of this pattern.

```zig
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Builder

Zig's [`std.Build`](https://ziglang.org/documentation/master/std/#A;std:Build)
Zig's [`std.Build`](https://ziglang.org/documentation/master/std/#std.Build)
type contains the information used by the build runner. This includes
information such as:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ the stack, and how), and how the return value is received.

In Zig, the attribute `callconv` may be given to a function. The calling
conventions available may be found in
[std.builtin.CallingConvention](https://ziglang.org/documentation/master/std/#A;std:builtin.CallingConvention).
[std.builtin.CallingConvention](https://ziglang.org/documentation/master/std/#std.builtin.CallingConvention).
Here we make use of the cdecl calling convention.

```zig
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ standard library - no allocations happen behind your back in the standard
library.

The most basic allocator is
[`std.heap.page_allocator`](https://ziglang.org/documentation/master/std/#A;std:heap.page_allocator).
[`std.heap.page_allocator`](https://ziglang.org/documentation/master/std/#std.heap.page_allocator).
Whenever this allocator makes an allocation, it will ask your OS for entire
pages of memory; an allocation of a single byte will likely reserve multiple
kibibytes. As asking the OS for memory requires a system call, this is also
Expand All @@ -30,15 +30,15 @@ with a free - this is a common pattern for memory management in Zig.
<CodeBlock language="zig">{AllocatorsAlloc}</CodeBlock>

The
[`std.heap.FixedBufferAllocator`](https://ziglang.org/documentation/master/std/#A;std:heap.FixedBufferAllocator)
[`std.heap.FixedBufferAllocator`](https://ziglang.org/documentation/master/std/#std.heap.FixedBufferAllocator)
is an allocator that allocates memory into a fixed buffer and does not make any
heap allocations. This is useful when heap usage is not wanted, for example,
when writing a kernel. It may also be considered for performance reasons. It
will give you the error `OutOfMemory` if it has run out of bytes.

<CodeBlock language="zig">{AllocatorsFba}</CodeBlock>

[`std.heap.ArenaAllocator`](https://ziglang.org/documentation/master/std/#A;std:heap.ArenaAllocator)
[`std.heap.ArenaAllocator`](https://ziglang.org/documentation/master/std/#std.heap.ArenaAllocator)
takes in a child allocator and allows you to allocate many times and only free
once. Here, `.deinit()` is called on the arena, which frees all memory. Using
`allocator.free` in this example would be a no-op (i.e. does nothing).
Expand All @@ -59,7 +59,7 @@ still be many times faster than page_allocator.
<CodeBlock language="zig">{AllocatorsGpa}</CodeBlock>

For high performance (but very few safety features!),
[`std.heap.c_allocator`](https://ziglang.org/documentation/master/std/#A;std:heap.c_allocator)
[`std.heap.c_allocator`](https://ziglang.org/documentation/master/std/#std.heap.c_allocator)
may be considered. This,however, has the disadvantage of requiring linking Libc,
which can be done with `-lc`.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ import ArrayList from "!!raw-loader!./02.arraylist.zig";
# ArrayList

The
[`std.ArrayList`](https://ziglang.org/documentation/master/std/#A;std:ArrayList)
[`std.ArrayList`](https://ziglang.org/documentation/master/std/#std.ArrayList)
is commonly used throughout Zig, and serves as a buffer that can change in
size. `std.ArrayList(T)` is similar to C++'s `std::vector<T>` and Rust's
`Vec<T>`. The `deinit()` method frees all of the ArrayList's memory. The memory
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ file before reading what we have written.
<CodeBlock language="zig">{CwdCreate}</CodeBlock>

The functions
[`std.fs.openFileAbsolute`](https://ziglang.org/documentation/master/std/#A;std:fs.openFileAbsolute)
[`std.fs.openFileAbsolute`](https://ziglang.org/documentation/master/std/#std.fs.openFileAbsolute)
and similar absolute functions exist, but we will not test them here.

We can get various information about files by using `.stat()` on them. `Stat`
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,25 +6,25 @@ import Custom from "!!raw-loader!./04.readers-and-writers-custom.zig";

# Readers and Writers

[`std.io.Writer`](https://ziglang.org/documentation/master/std/#A;std:io.Writer)
[`std.io.Writer`](https://ziglang.org/documentation/master/std/#std.io.Writer)
and
[`std.io.Reader`](https://ziglang.org/documentation/master/std/#A;std:io.Reader)
[`std.io.Reader`](https://ziglang.org/documentation/master/std/#std.io.Reader)
provide standard ways of making use of IO. `std.ArrayList(u8)` has a `writer`
method which gives us a writer. Let's use it.

<CodeBlock language="zig">{Writer}</CodeBlock>

Here we will use a reader to copy the file's contents into an allocated buffer.
The second argument of
[`readAllAlloc`](https://ziglang.org/documentation/master/std/#A;std:io.Reader.readAllAlloc)
[`readAllAlloc`](https://ziglang.org/documentation/master/std/#std.io.Reader.readAllAlloc)
is the maximum size that it may allocate; if the file is larger than this, it
will return `error.StreamTooLong`.

<CodeBlock language="zig">{Reader}</CodeBlock>

A common usecase for readers is to read until the next line (e.g. for user
input). Here we will do this with the
[`std.io.getStdIn()`](https://ziglang.org/documentation/master/std/#A;std:io.getStdIn)
[`std.io.getStdIn()`](https://ziglang.org/documentation/master/std/#std.io.getStdIn)
file.

{/* Code snippet not tested as it uses stdin/stdout */}
Expand Down Expand Up @@ -67,7 +67,7 @@ test "read until next line" {
```

An
[`std.io.Writer`](https://ziglang.org/documentation/master/std/#A;std:io.Writer)
[`std.io.Writer`](https://ziglang.org/documentation/master/std/#std.io.Writer)
type consists of a context type, error set, and a write function. The write
function must take in the context type and a byte slice. The write function must
also return an error union of the Writer type's error set and the number of
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ import Custom from "!!raw-loader!./05.formatting-custom.zig";

# Formatting

[`std.fmt`](https://ziglang.org/documentation/master/std/#A;std:fmt) provides
[`std.fmt`](https://ziglang.org/documentation/master/std/#std.fmt) provides
ways to format data to and from strings.

A basic example of creating a formatted string. The format string must be
Expand All @@ -21,7 +21,7 @@ Writers conveniently have a `print` method, which works similarly.

Take a moment to appreciate that you now know from top to bottom how printing
Hello World works.
[`std.debug.print`](https://ziglang.org/documentation/master/std/#A;std:debug.print)
[`std.debug.print`](https://ziglang.org/documentation/master/std/#std.debug.print)
works the same, except it writes to stderr and is protected by a mutex.

{/* Code snippet not tested as it uses stdin/stdout */}
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Crypto

[`std.crypto`](https://ziglang.org/documentation/master/std/#A;std:crypto)
[`std.crypto`](https://ziglang.org/documentation/master/std/#std.crypto)
includes many cryptographic utilities, including:

- AES (Aes128, Aes256)
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Threads

While Zig provides more advanced ways of writing concurrent and parallel code,
[`std.Thread`](https://ziglang.org/documentation/master/std/#A;std:Thread) is
[`std.Thread`](https://ziglang.org/documentation/master/std/#std.Thread) is
available for making use of OS threads. Let's make use of an OS thread.

```zig
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Hash Maps

The standard library provides
[`std.AutoHashMap`](https://ziglang.org/documentation/master/std/#A;std:AutoHashMap),
[`std.AutoHashMap`](https://ziglang.org/documentation/master/std/#std.AutoHashMap),
which lets you easily create a hash map type from a key type and a value type.
These must be initiated with an allocator.

Expand Down Expand Up @@ -54,7 +54,7 @@ test "fetchPut" {
}
```

[`std.StringHashMap`](https://ziglang.org/documentation/master/std/#A;std:StringHashMap)
[`std.StringHashMap`](https://ziglang.org/documentation/master/std/#std.StringHashMap)
is also provided for when you need strings as keys.

```zig
Expand All @@ -72,16 +72,16 @@ test "string hashmap" {
}
```

[`std.StringHashMap`](https://ziglang.org/documentation/master/std/#A;std:StringHashMap)
[`std.StringHashMap`](https://ziglang.org/documentation/master/std/#std.StringHashMap)
and
[`std.AutoHashMap`](https://ziglang.org/documentation/master/std/#A;std:AutoHashMap)
[`std.AutoHashMap`](https://ziglang.org/documentation/master/std/#std.AutoHashMap)
are just wrappers for
[`std.HashMap`](https://ziglang.org/documentation/master/std/#A;std:HashMap). If
[`std.HashMap`](https://ziglang.org/documentation/master/std/#std.HashMap). If
these two do not fulfil your needs, using
[`std.HashMap`](https://ziglang.org/documentation/master/std/#A;std:HashMap)
[`std.HashMap`](https://ziglang.org/documentation/master/std/#std.HashMap)
directly gives you much more control.

If having your elements backed by an array is wanted behaviour, try
[`std.ArrayHashMap`](https://ziglang.org/documentation/master/std/#A;std:ArrayHashMap)
[`std.ArrayHashMap`](https://ziglang.org/documentation/master/std/#std.ArrayHashMap)
and its wrapper
[`std.AutoArrayHashMap`](https://ziglang.org/documentation/master/std/#A;std:AutoArrayHashMap).
[`std.AutoArrayHashMap`](https://ziglang.org/documentation/master/std/#std.AutoArrayHashMap).
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Stacks

[`std.ArrayList`](https://ziglang.org/documentation/master/std/#A;std:ArrayList)
[`std.ArrayList`](https://ziglang.org/documentation/master/std/#std.ArrayList)
provides the methods necessary to use it as a stack. Here's an example of
creating a list of matched brackets.

Expand Down
Loading

0 comments on commit da4a7d7

Please sign in to comment.