# Strings, logging and math

> The small library you use on every line - strings, formatting, logging, math, random.

Kaigen replaces the C standard library with its own, in `hz/src/lib`. It works the same on every platform, the web included, and most of it is small enough to read in one sitting. Before writing a helper, check if it's already there: it usually is.

## Strings

A `String` is a pointer and a length (`{char *value; u32 len;}`), not a null-terminated buffer. Slicing, splitting and comparing don't copy anything. `CString` is a plain `const char *` for the places that need one.

Strings:

```
String name = STR_FROM_CSTR("player");
if (str_equal(name, other)) { ... }
String path = str_format(&ta.allocator, "levels/%.hzt", fmt_str(name));
```

For building text bit by bit there's `StringBuilder` (`sb_create`, `sb_append`, `sb_append_format`).

## Formatting and logging

Formatting uses `%` for every argument, and each argument says its own type with a `fmt_*` call. There's no `%d` or `%s`, and the types can't get out of sync with the arguments.

Logging:

```
log_info("loaded % enemies in % ms", fmt_u32(count), fmt_f32(ms));
log_warn("no spawn point in %", fmt_str(level_name));
log_error("bad state: %", fmt_struct(Player, &player));
```

`fmt_struct` prints any reflected struct, field by field (see [Reflection and data](https://kaigen3d.com/docs/data)). `fmt_f32_p(v, 2)` gives fixed decimals, and `fmt_bytes(size)` prints "1.50 MB".

## Math

Everything is in `hz/src/lib/hzmath.h`: `v2`, `v3`, `v4`, `quat`, `m3`, `m4`, plus boxes, rays and frustums. Types are passed by value, and functions are named `type_operation`: `v3_add`, `v3_normalize`, `quat_slerp`, `m4_mul`. Scalar functions start with `m_`: `m_sinf`, `m_clampf`, `m_lerpf`.

The conventions:

- **Right-handed, Y up.** `V3_FORWARD` is +Z, `V3_RIGHT` is +X.
- **Meters.** Make things the size they are in the real world.
- **Column-major matrices**, quaternions stored `xyzw`.
- **Reverse-Z depth**: the near plane is 1 and the far plane is 0.

A few you'll use a lot in gameplay: `m_damp` and `v3_damp` for smooth, frame-rate-independent following, `quat_axis_angle`, and the easing functions.

## Random

`Random rng = random_create(seed);` then `random_f32(&rng)`, `random_f32_range(&rng, min, max)` and friends. Seeded and deterministic, so the same seed plays the same game.

## Worth knowing

- Don't call `printf`, `strlen` or anything from `math.h`. They aren't there on every platform. `cstr_len` and the `m_` functions are.
- A literal `%` in a log line is an argument: `fmt_char('%')`.
