Ch26.1: Modules and the Four Concept Categories

1. The Module Is the API Contract

fast_io ships headers and C++20 module interfaces. The headers expose almost the whole implementation. The modules expose a curated subset: the names listed in share/fast_io/fast_io_inc/*.inc. That subset is the API surface an importer should treat as public.

This is the distinction the rest of this reference follows. A name is documented as a module API only when the module exports it. A useful header-only helper that is not in the export list is marked as such; it is not silently presented as part of the module contract.

The header interface remains valid. #include <fast_io.h> is still how the tutorial builds, and it is the escape hatch when a module is incomplete. But when both exist, the module export list is the smaller and more stable surface.

2. Module Inventory

The naming is not uniform: fast_io.floating, fast_io.i18n, fast_io.tls and fast_io.json use dotted names, while fast_io_crypto and fast_io_legacy use underscores. Treat the spelling in the table as part of the current interface, not as a style you should extrapolate from.

3. The Four Concept Categories

fast_io is easier to learn when its types are sorted by the concept they satisfy rather than by the header they live in. Four categories carry almost everything:

They compose in one direction: a device receives the result, a strlike can be the destination when the result is text in memory, an I/O type carries the intermediate representation, and a manipulator changes one argument on its way through.

::fast_io::println(device, ::fast_io::mnp::hex(value));
//                ^device  ^manipulator

What about transcoders?

transcoder is an older category. It described a stateful conversion pipeline between encodings. Most of what it was for is now expressed by the code_cvt manipulator and the code_cvt_os_c_str alias, which convert one value inside a print call without a separate object. Treat the transcoder family as legacy and under review: do not design a new API around it, and check whether code_cvt already does the job.

4. What the Umbrella Module Exports

The export list is the best table of contents for the library. The main groups are:

5. The Exported Manipulator Surface

These are the manipulators the fast_io module exports today, grouped by what they do. All of them are in ::fast_io::mnp (the alias for ::fast_io::manipulators).

The module also exports the types behind these values: scalar_flags, scalar_manip_t, scalar_placement, floating_format, percentage_flag, lc_time_flag, ip_flags, ip_manip_t, ip_scan_manip_t, member_function_pointer_holder_t and whole_get_t.

6. The Locale Module

fast_io.i18n is a separate module because locale data is bulky and optional. It exports fast_io and adds the locale layer on top:

• Wire types. l10n::lc_locale is a flat, position-independent image. Pointers inside it are lc_rva values and strings are lc_scatter values, so the bytes work from a file mapping, an embedded array, a WebAssembly module or a resource.
• Loading. l10n::load_l10n maps a locale blob, checks magic and version, verifies the image once, and returns an lc_locale const *. Sandboxed callers can pass a pointer to an image they already have.
• Binding. imbue(loc, out) wraps an output stream. The lc_ctx is built lazily, only when an argument actually needs locale formatting.
• Formatting. lc_concat / lc_concatln produce locale-formatted strings; mnp::lc_dump prints a textual dump of a locale; lc_time_flag selects a time format.

import fast_io.i18n;

int main()
{
    using namespace ::fast_io::io;

    auto const *loc{::fast_io::l10n::load_l10n(u8"de_DE.UTF-8")};

    // Grouping and separators come from LC_NUMERIC.
    println(::fast_io::imbue(loc, ::fast_io::out()), 1234567);

    // The whole locale as text, for inspection.
    println(::fast_io::imbue(loc, ::fast_io::out()), ::fast_io::mnp::lc_dump(loc));
}

The locale categories available through basic_lc_all are identification, monetary, numeric, time, messages, paper, telephone, name, address, measurement and keyboard. The numeric layer carries the thousands separator and grouping; the time layer carries the POSIX format strings and alternate digits. A locale with no grouping takes the plain formatting path and never builds an lc_ctx.

The header interface is #include <fast_io_i18n.h>. The module compiles the loader into itself, so importing fast_io.i18n does not require a separate fast_io_i18n library.

7. Importing and Building

The module files live in {fast_io}/share/fast_io. Build fast_io first, then the module that imports it. The dependency order is:

fast_io
  ├── fast_io.i18n
  ├── fast_io_crypto
  │     └── fast_io.tls
  ├── fast_io_legacy
  ├── fast_io.json
  └── fast_io.floating   (separately compiled conversion support)

import fast_io;

int main()
{
    ::fast_io::io::println("Hello from the module");
    ::fast_io::vector<int> v{1, 2, 3};
    for (auto x : v)
    {
        ::fast_io::io::print(x, " ");
    }
}

Clang is the supported path for modules today; GCC module support is experimental and the herbceptions GCC build is known to ICE on some fast_io module units. MSVC is not supported because it has no herbceptions. The exact precompile and link commands are in Ch1.8.

Key Takeaways

• The module export list is the public API contract; headers expose more, but not all of it is exported.
• The module set is fast_io, fast_io.floating, fast_io.i18n, fast_io_crypto, fast_io.tls, fast_io_legacy and fast_io.json.
• The four concept categories are device, I/O type, manipulator and strlike; transcoder is legacy and under review.
• Manipulators are one-argument formatting wrappers, not persistent stream state.
• fast_io.i18n owns the locale blob, loader, imbue and locale-aware concatenation.
• Build fast_io first; Clang is the reliable module compiler today.