Skip to content

TsukiNi22/ai-utils / skills/libutils/libutils

libutils

Verified

Reference of Tsukini's C++20 library libutils (namespace utils::, github TsukiNi22/libutils) - every section, header, class and public method with the version and commit hash it was generated from, how to link/include it, exceptions/error codes, verbose, and how to find what changed since. Use whenever code uses or could use libutils (utils::..., include "utils/...", find_package(utils)), when the user asks which libutils class/function does something, how to use one, or what is new in libutils, instead of searching the library sources.

FileKindSize
SKILL.mdskill md14.6 KB
reference/VERSION.mdmarkdown612 B
reference/api/algorithms.mdmarkdown10.0 KB
reference/api/arguments.mdmarkdown8.4 KB
reference/api/attribute.mdmarkdown9.0 KB
reference/api/cli.mdmarkdown5.0 KB
reference/api/concepts.mdmarkdown3.0 KB
reference/api/encapsulation.mdmarkdown9.8 KB
reference/api/exception.mdmarkdown6.7 KB
reference/api/manip.mdmarkdown10.9 KB
reference/api/math.mdmarkdown2.3 KB
reference/api/network.mdmarkdown8.4 KB
reference/api/platform.mdmarkdown6.0 KB
reference/api/pool.mdmarkdown5.1 KB
reference/api/root.mdmarkdown2.2 KB
reference/api/security.mdmarkdown8.8 KB
reference/api/system.mdmarkdown10.7 KB
reference/api/type.mdmarkdown38.5 KB
reference/api/verbose.mdmarkdown3.6 KB
reference/exception-codes.mdmarkdown7.6 KB
reference/index.mdmarkdown20.0 KB
scripts/check.shexecutablescript2.7 KB
scripts/gen_api.pyexecutablescript20.8 KB
scripts/update.shexecutablescript2.3 KB
---
name: libutils
description: Reference of Tsukini's C++20 library libutils (namespace utils::, github TsukiNi22/libutils) - every section, header, class and public method with the version and commit hash it was generated from, how to link/include it, exceptions/error codes, verbose, and how to find what changed since. Use whenever code uses or could use libutils (utils::..., include "utils/...", find_package(utils)), when the user asks which libutils class/function does something, how to use one, or what is new in libutils, instead of searching the library sources.
metadata:
  summary: 'Reference of my library [libutils](https://github.com/TsukiNi22/libutils): every section, header and public API generated from a recorded version/commit (`reference/VERSION.md`), integration and conventions, plus `scripts/update.sh` to see what changed since that commit and regenerate.'
---

# libutils reference

**Version of this reference: read `reference/VERSION.md` first** (version, commit hash, date).
Everything below `reference/` is generated by `scripts/gen_api.py` from that exact commit.
`SKILL_DIR` = the directory of this file, `LIBUTILS` = `~/personal_delivery/cpp/libutils`.

## Freshness check (first, once per conversation)
Before relying on the reference, here and in every skill that requires libutils (`libutils-exception`,
`libutils-setup`, `libutils-install`, `cpp-class`, `cpp-project`, `audit-bugs`), run
`bash SKILL_DIR/scripts/check.sh` (local, fast; `--fetch` also compares with `origin/main`; same as
`xstyle --libutils-check`). Last line:
- `status: up to date` -> go on;
- `status: unknown` (no repository, nothing installed) -> go on, say it once;
- `status: outdated` -> **if the user already answered this question earlier in the conversation, apply that answer
  again without asking**; otherwise ask once (AskUserQuestion, French, `multiSelect: true`), then remember the answer
  for the whole conversation. The updates are done **by the matching skill**, never by hand:
  | Choice | Done by |
  |---|---|
  | `Continuer avec la référence actuelle` (alone) | nothing; say once that the newer APIs / renames may be missing |
  | `Mettre à jour libutils installé` | the **`libutils-install`** skill (`libutils.sh update`, root asked by that skill, then `status`) |
  | `Mettre à jour la version requise par le projet` (only in a project using libutils) | the **`libutils-setup`** skill (`setup_project.py <root> --version <installed version>`: `find_package(utils X.Y.Z)` bumped, rebuild) |
  | `Mettre à jour la référence des skills` | `bash SKILL_DIR/scripts/update.sh` (shows the changes then regenerates); tell the user the ai-utils repository has to be committed |
  Pre-select from the lines of `check.sh`: `installed: ... (differs)` with an installed version older than the reference
  -> `libutils-install`; repository commits after the reference or an installed version newer than it -> the reference
  (+ `libutils-install` when the repository has a newer version than the installed one); the project's
  `find_package(utils X.Y.Z)` older than the installed version -> `libutils-setup`.

## How to answer a libutils question
1. `reference/index.md`: find the section / header / namespace of what is needed
   (one table per section, small enough to read entirely).
2. `reference/api/<section>.md`: public API of the headers of that section (signatures,
   default values, trailing comments = documentation). Read only the needed section.
3. Error codes: `reference/exception-codes.md`.
4. Real usage examples: the unit tests of the same commit,
   `git -C LIBUTILS show <commit>:tests/<section>/<file>` (`git -C LIBUTILS ls-tree -r --name-only <commit> tests`),
   and the wiki https://github.com/TsukiNi22/libutils/wiki.
5. Only if the answer is not in the reference: read the header itself at the commit
   (`git -C LIBUTILS show <commit>:include/utils/<path>`) for the implementation details.

## Version checks
- The project may use another version than the reference:
  - required version: `find_package(utils <version> CONFIG REQUIRED)` in the project `CMakeLists.txt`;
  - installed version: `grep __LIBUTILS_VERSION__ /usr/include/utils/version.hpp /usr/local/include/utils/version.hpp`;
  - at runtime: `utils::version` (`std::string_view`, `"vX.Y.Z"`).
- If the version differs from the reference, check the differences before advising an API:
  `git -C LIBUTILS diff --stat v<installed> <commit> -- include` and the CHANGELOG between both
  (removed/renamed APIs are listed in `### Removed` / `### Changed`, migrations keep the old name with a
  `[deprecated ~vX.Y.Z]` marker in the reference).
- New things since the reference: `bash SKILL_DIR/scripts/update.sh --check` (commits, changed headers,
  new CHANGELOG lines since the recorded hash). `bash SKILL_DIR/scripts/update.sh` regenerates the
  reference from `HEAD` (`--ref origin/main` or a tag for another commit). Uncommitted changes of
  libutils are never part of the reference. After a regeneration, tell the user (the skills repo must be
  committed by them or on request).

## Integration
```cmake
find_package(utils 4.0.0 CONFIG REQUIRED)                      # minimal version (SameMajorVersion: 3.x is refused)
target_link_libraries(${TARGET} PRIVATE utils::utils)          # static lib + include path
```
- Packages (`dnf`/`apt`, see the README `setup.sh`): `libutils` (= `libutils-dev` + `libutils-op`),
  `-db` debug, `-as` asan, `-pre` pre-release; from the sources: `cmake -S . -B build && sudo cmake --build build --target install`.
  Windows (v4.1.0): `mingw64-libutils` (= `-dev` + `-op`), `mingw64-libutils-db` (no asan), `-pre`, same mirror,
  installed in the MinGW sysroot (found by `find_package(utils)` with a MinGW toolchain: `mingw64-cmake` on Fedora).
- Platforms (v4.0.0+): Unix and Windows x86_64 (cross compiled with MinGW-w64: the packages `mingw64-libutils*`
  since v4.1.0, or `-DCMAKE_TOOLCHAIN_FILE=cmake/toolchain/mingw-w64.cmake` from the sources; `utils::utils` also links
  `ws2_32`), every class with the
  same API; on Windows `Process::spawn()` (fork) and a `Process::dup` on a fd other than 0, 1, 2 raise a
  `FatalException` (`UndefinedCall`), `Poll` / `Client` / `Server` only handle sockets. Include `<windows.h>` before
  `<utils/utils.hpp>` (or define `WIN32_LEAN_AND_MEAN`): the complete `<windows.h>` declares a `_unused` member.
- System calls: the section `_Platform` gives `utils::platform::` versions of the POSIX calls with the **same names
  and contract** (`close`, `read`, `pipe`, `poll`, `socket`, `connect`, `epoll_wait`, `dlopen`, `tcgetattr`, `strerror`...;
  -1 & `errno`): use them instead of the raw calls in a code that must also build on Windows.
- Include: **always** the root `#include <utils/utils.hpp>` (preferred; `<utils.hpp>`, `"utils/utils.hpp"`,
  `"utils.hpp"` accepted), never a libutils header one by one (`"utils/network/Server.hpp"`,
  `"utils/attribute/Attribute.hpp"`...). Only a header `utils.hpp` does not give is included directly: the
  observers (`<utils/security/observer/Observer.hpp>`...).
- Sections: every file of a project defines the sections it uses right before the root include
  (`#define _Network`, `_Exception`, `_Cli`, `_Arguments`, `_System`, `_Math`, `_IOManip`, `_SManip`,
  `_Socket`, `_CustomType`, `_Security`...; groups `_Handling`, `_Tools`; nothing defined = everything), in
  a .hpp as in a .cpp. **Mandatory, never a bare include**: `utils.hpp` has no global guard and the defines
  stay set for the rest of the translation unit, so a bare include placed after a partial one only gets the
  sections already defined (missing declarations). Header -> section table: `cpp-class`
  `reference/layout.md` "libutils includes".
- Warnings: `_Warning` enables the deprecation/backward-compatibility/linker/usage warnings,
  `_NoWarning` disables them (`add_definitions(-D_NoWarning)`).
- Linker needs: `Base64Codec`, `AESKey`, `RSAKey` (and `EETPParser`) need OpenSSL (`-lssl -lcrypto`); since
  v3.0.0 the public headers include OpenSSL, `libutils-dev` requires `openssl-devel` / `libssl-dev`.
- License: libutils is MIT, but `algorithms` (c2dmp-hsm, s.o.s) is CC BY-NC-SA 4.0 (non-commercial, see
  `THIRD_PARTY_NOTICES.md`); the RPM license is `MIT AND CC-BY-NC-SA-4.0`.

## Library conventions (to use it the right way)
- Everything is in `utils::<section>` (see the index); a few grouping folders don't add a level
  (`manip/iomanip` -> `utils::iomanip`, `network/socket` -> `utils::network`; `utils::network::socket` was removed in
  v4.0.0).
- Naming (v3.0.0): public names follow the convention (`autoCast`, `utils::cli::flags`, `isLoaded`,
  `set_style`, `read_mouse_event`, `key_to_string`, `FixedString`, `ConvertibleTo`...); the old names (`_migration`
  aliases in v3.x) were **removed in v4.0.0**: always write the new name, an old one doesn't build anymore.
- Errors: exceptions, never error codes (`throw utils::exception::ErrorException(InternalCode::X, "info")`,
  `catch (const utils::exception::IException& e) {... e.formated() ...}`). Everything about the exception
  classes, the restrictions and adding project codes (JSON + generator + CMake): the `libutils-exception` skill.
- Many APIs take a `failsafe` (warn instead of throw) or `safe_mode` (lock) boolean.
- Check hooks return `std::optional<std::string>`: `std::nullopt` = valid, string = error message
  (`ArgParser`, `Settings`, default hooks `default*ParsingHook`).
- Verbose: `set_verbose(Debug)` (`None`, `Basic`, `Advanced`, `Debug`), then `onBasicVerbose(info)`,
  `onDebugVerbose(info)`, `onVerbose(level, info)`; `*C(output, info)` for another stream, `*Fn(code)` to run code.
- Attribute macros (`_hot`, `_cold`, `_nodiscard`, `_unused`, `_likely`, `_alignas(n)`, `_nonnull(p)`...): given by
  `<utils/utils.hpp>`, always preferred to the raw form (`_alignas(std::hardware_destructive_interference_size)`,
  never `alignas(...)`); `std::hardware_*_interference_size` is guaranteed (fallback 64). Lookup order when an
  attribute is needed: the reference `api/attribute.md`, then the attribute files of the project / system
  (`cpp-class/scripts/list_attributes.sh <project>`), then only the standard `[[...]]` form (`cpp-style`).
- Most classes are non-copyable (`= delete`) and inherit `utils::security::observer::Observer<"Name">`
  (instance tracking for the memory-leak notifier, nothing to do on the user side).

## Section map
| Section | Namespace | What it gives |
|---|---|---|
| `algorithms` | `utils::algorithms::c2dmp`, `::sos` | c2dmp-hsm string distance (`c2dmp<full>(a, b)`), s.o.s steganography (`sos_embed`, `sos_extract`) |
| `arguments` | `utils::arguments` | `ArgParser` (usages, flags, options, env, help), `Settings`/`Setting` (typed settings, casts) |
| `attribute` | macros | compiler attributes per C++ version (`_noreturn`...), `_legacy`, `_migration(x, y, z)` |
| `cli` | `utils::cli` | `Cli` interactive command line (commands, hooks, completion, `Flag`s) |
| `concepts` | `utils::concepts` | operation concepts (`Addable`, `AddableWith`, `Arithmetic`...) and global ones |
| `encapsulation` | `utils::encapsulation` | `Pipe`, `Dup`, `Process`, `Poll` (epoll), `SharedObject` (.so / .dll), `SharedMemory` (IPC) |
| `exception` | `utils::exception` | `IException`/`AException`, `Error`/`Warning`/`None`/`Fatal`/`CustomException`, codes |
| `manip` | `utils::iomanip`, `utils::smanip` | ANSI (colors, styles, cursor, mouse), `format`, `FixedString`, `Base64Codec`, `EETPParser` |
| `math` | `utils::math` | geometry (`rotate_point_2D/3D`, `to_look`), trigo (`deg_to_rad`), `CFrame` |
| `network` | `utils::network` | `Server`, `Client`, `ISocket`/`ASocket`/`TCPSocket`, `Address`, `Payload`, `is_ip`, `resolve_*` |
| `platform` | `utils::platform` | POSIX calls for Unix & Windows (`close`, `socket`, `epoll_*`, `dlopen`, `tcgetattr`...), `UTILS_UNIX` / `UTILS_WINDOWS` |
| `pool` | `utils::pool` | `Middlewares<T, U>` chains (before/after), `Cluster` |
| `security` | `utils::security` | `AESKey`, `RSAKey`, `CommonRSAKey`; observers/notifiers (memory leak) |
| `system` | `utils::system` | `IdHandler<T>`, `Scheduler` (delayed tasks), `LoadBalancer<T>` (workers) |
| `type` | `utils::type` | `Vector2/3`, `OVector2/3`, `Matrix`/`OMatrix`, `BidirectionalLookupTable`, `Freezable`, `Worker` |
| `verbose` | `utils::verbose` | verbose levels and macros |
| `root` | `utils` | `utils.hpp` umbrella include, `utils::version` |

## Use libutils instead of rewriting it
In a project that uses libutils (installed **and** `find_package(utils)` / `utils.hpp` in the project), never
write by hand what a section already gives; when reviewing, flag it with the class to use:
| Written by hand | libutils |
|---|---|
| `throw std::runtime_error(...)` and the other standard exceptions | `utils::exception::ErrorException(InternalCode::X, "info")` (`libutils-exception`) |
| `argv[i]` compared / `getopt` | `utils::arguments::ArgParser` (flags, options, usages, env, help) |
| `"\033[31m"`, `"\x1b[0m"` | `utils::iomanip` (`color(Color::Red)`, `set_style({...})`, `reset()`, `file_hyperlink`, `hyperlink`) |
| `socket(AF_INET...)`, `bind` / `listen` / `accept`, `sockaddr_in` | `utils::network::TCPSocket`, `Server`, `Client`, `Address` |
| `pipe`, `dup2`, `fork`, `epoll_*`, `shm_open` + `mmap`, `dlopen` / `dlsym` | `utils::encapsulation::Pipe`, `Dup`, `Process`, `Poll`, `SharedMemory`, `SharedObject` |
| `std::vector<std::thread>` pool, delayed tasks | `utils::pool::Cluster`, `utils::system::Scheduler`, `utils::system::LoadBalancer` |
| id counter + free list | `utils::system::IdHandler<T>` |
| `* M_PI / 180`, `180 / M_PI` | `utils::math::trigo::deg_to_rad` / `rad_to_deg` |
| base64 alphabet / encoder | `utils::smanip::codec::Base64Codec` |
| `if (verbose) std::cout << ...` | `utils::verbose` (`set_verbose(Debug)`, `onBasicVerbose(info)`, `onDebugVerbose(info)`) |
| Levenshtein / edit distance | `utils::algorithms::c2dmp::c2dmp` |
| `[[nodiscard]]`, `[[maybe_unused]]`, `alignas(n)`... | `_nodiscard`, `_unused`, `_alignas(n)`... (`cpp-style` "Attributes") |
| old names (`isloaded`, `auto_cast`, `setStyle`, `utils::network::socket::*`) | new names (`isLoaded`, `autoCast`, `set_style`, `utils::network::*`) |

The checker `xstyle` ([TsukiNi22/xstyle](https://github.com/TsukiNi22/xstyle), `curl -fsSL https://tsukini22.github.io/my-universe/install.sh | bash -s` then `sudo dnf|apt|pacman install xstyle` (packages of [my-universe](https://tsukini22.github.io/my-universe/), sources: [TsukiNi22/xstyle](https://github.com/TsukiNi22/xstyle); no curl: `wget -qO-` instead of `curl -fsSL`)) enforces this table with its
`LU-*` rules (`xstyle --rtk -c LU`; `LU-INCLUDE`, `LU-SECTION`, `LU-ATTRIBUTE`, `LU-MIGRATION` are fixed by `xstyle --rtk --fix LU`).
Its migration rule reads the `_migration` aliases of the **installed** headers, so it follows the installed version.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall