Skip to content

TsukiNi22/ai-utils / skills/libutils/libutils

libutils

Unverified

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.

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:
    ChoiceDone 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 skillsbash 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

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

SectionNamespaceWhat it gives
algorithmsutils::algorithms::c2dmp, ::sosc2dmp-hsm string distance (c2dmp<full>(a, b)), s.o.s steganography (sos_embed, sos_extract)
argumentsutils::argumentsArgParser (usages, flags, options, env, help), Settings/Setting (typed settings, casts)
attributemacroscompiler attributes per C++ version (_noreturn...), _legacy, _migration(x, y, z)
cliutils::cliCli interactive command line (commands, hooks, completion, Flags)
conceptsutils::conceptsoperation concepts (Addable, AddableWith, Arithmetic...) and global ones
encapsulationutils::encapsulationPipe, Dup, Process, Poll (epoll), SharedObject (.so / .dll), SharedMemory (IPC)
exceptionutils::exceptionIException/AException, Error/Warning/None/Fatal/CustomException, codes
maniputils::iomanip, utils::smanipANSI (colors, styles, cursor, mouse), format, FixedString, Base64Codec, EETPParser
mathutils::mathgeometry (rotate_point_2D/3D, to_look), trigo (deg_to_rad), CFrame
networkutils::networkServer, Client, ISocket/ASocket/TCPSocket, Address, Payload, is_ip, resolve_*
platformutils::platformPOSIX calls for Unix & Windows (close, socket, epoll_*, dlopen, tcgetattr...), UTILS_UNIX / UTILS_WINDOWS
poolutils::poolMiddlewares<T, U> chains (before/after), Cluster
securityutils::securityAESKey, RSAKey, CommonRSAKey; observers/notifiers (memory leak)
systemutils::systemIdHandler<T>, Scheduler (delayed tasks), LoadBalancer<T> (workers)
typeutils::typeVector2/3, OVector2/3, Matrix/OMatrix, BidirectionalLookupTable, Freezable, Worker
verboseutils::verboseverbose levels and macros
rootutilsutils.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 handlibutils
throw std::runtime_error(...) and the other standard exceptionsutils::exception::ErrorException(InternalCode::X, "info") (libutils-exception)
argv[i] compared / getoptutils::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_inutils::network::TCPSocket, Server, Client, Address
pipe, dup2, fork, epoll_*, shm_open + mmap, dlopen / dlsymutils::encapsulation::Pipe, Dup, Process, Poll, SharedMemory, SharedObject
std::vector<std::thread> pool, delayed tasksutils::pool::Cluster, utils::system::Scheduler, utils::system::LoadBalancer
id counter + free listutils::system::IdHandler<T>
* M_PI / 180, 180 / M_PIutils::math::trigo::deg_to_rad / rad_to_deg
base64 alphabet / encoderutils::smanip::codec::Base64Codec
if (verbose) std::cout << ...utils::verbose (set_verbose(Debug), onBasicVerbose(info), onDebugVerbose(info))
Levenshtein / edit distanceutils::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, curl -fsSL https://tsukini22.github.io/my-universe/install.sh | bash -s then sudo dnf|apt|pacman install xstyle (packages of my-universe, sources: 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: 318kUpdated Claude CodeCodexUnverifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 318kUpdated Claude CodeCodexUnverifiedInstall
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: 318kUpdated Claude CodeCodexUnverifiedInstall
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: 318kUpdated Claude CodeCodexUnverifiedInstall