TsukiNi22/ai-utils / skills/libutils/libutils
libutils
UnverifiedReference 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: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-installskill (libutils.sh update, root asked by that skill, thenstatus)Mettre à jour la version requise par le projet(only in a project using libutils)the libutils-setupskill (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 committedPre-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-installwhen the repository has a newer version than the installed one); the project'sfind_package(utils X.Y.Z)older than the installed version ->libutils-setup.
How to answer a libutils question
reference/index.md: find the section / header / namespace of what is needed (one table per section, small enough to read entirely).reference/api/<section>.md: public API of the headers of that section (signatures, default values, trailing comments = documentation). Read only the needed section.- Error codes:
reference/exception-codes.md. - 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. - 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 projectCMakeLists.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").
- required version:
- If the version differs from the reference, check the differences before advising an API:
git -C LIBUTILS diff --stat v<installed> <commit> -- includeand 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.shregenerates the reference fromHEAD(--ref origin/mainor 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 READMEsetup.sh):libutils(=libutils-dev+libutils-op),-dbdebug,-asasan,-prepre-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 byfind_package(utils)with a MinGW toolchain:mingw64-cmakeon 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.cmakefrom the sources;utils::utilsalso linksws2_32), every class with the same API; on WindowsProcess::spawn()(fork) and aProcess::dupon a fd other than 0, 1, 2 raise aFatalException(UndefinedCall),Poll/Client/Serveronly handle sockets. Include<windows.h>before<utils/utils.hpp>(or defineWIN32_LEAN_AND_MEAN): the complete<windows.h>declares a_unusedmember. - System calls: the section
_Platformgivesutils::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 headerutils.hppdoes 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.hpphas 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-classreference/layout.md"libutils includes". - Warnings:
_Warningenables the deprecation/backward-compatibility/linker/usage warnings,_NoWarningdisables them (add_definitions(-D_NoWarning)). - Linker needs:
Base64Codec,AESKey,RSAKey(andEETPParser) need OpenSSL (-lssl -lcrypto); since v3.0.0 the public headers include OpenSSL,libutils-devrequiresopenssl-devel/libssl-dev. - License: libutils is MIT, but
algorithms(c2dmp-hsm, s.o.s) is CC BY-NC-SA 4.0 (non-commercial, seeTHIRD_PARTY_NOTICES.md); the RPM license isMIT 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::socketwas 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 (_migrationaliases 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): thelibutils-exceptionskill. - Many APIs take a
failsafe(warn instead of throw) orsafe_mode(lock) boolean. - Check hooks return
std::optional<std::string>:std::nullopt= valid, string = error message (ArgParser,Settings, default hooksdefault*ParsingHook). - Verbose:
set_verbose(Debug)(None,Basic,Advanced,Debug), thenonBasicVerbose(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), neveralignas(...));std::hardware_*_interference_sizeis guaranteed (fallback 64). Lookup order when an attribute is needed: the referenceapi/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 inheritutils::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, Flags) |
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, 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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 implementation | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| 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 fallback | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| 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 always | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |