C CASTLE / MODULE NOTES
CASTLE/Modules/Serialization

MODULE 15 / 18

INI serialization

A fixed-capacity INI document, parser, and serializer for embedded configuration data.

#include "castle_ext/serialization/ini.hpp"

Overview

A fixed-capacity INI document, parser, and serializer for embedded configuration data. Use it when simple section/key/value text must be owned, queried, and emitted without heap allocation.

Dependencies

  • error/status
  • container/string
  • container/string_view
  • container/vector
  • utility/optional

Public API

APIDescription
enum class error_codeINI-specific diagnostics: invalid_section, invalid_key, invalid_assignment, invalid_quote, invalid_escape, capacity, output_full.
struct resultBundles castle::status, error_code, and one-based line / column diagnostics.
document<MaxEntries, MaxSectionLength, MaxKeyLength, MaxValueLength>Fixed-capacity owning INI document.
size, capacity, empty, full, clearContainer-style document inspection and reset.
contains, contains_section, find, get, readLookup helpers for global or section-scoped keys.
set, set_bool, set_integer, set_enumInsert or update values as text.
get_bool, get_integer, get_enum, get_floatingRead typed values from stored text.
remove, remove_sectionDelete one key or an entire section.
section, key, valueIndexed access to stored entries in insertion order.
parseParses INI text into a document and clears the document on failure.
serialize, writeDeterministically emits INI text into a caller-owned fixed string.

Usage example

See samples/castle_ext/serialization/ini.cpp.

#include "castle_ext/serialization/ini.hpp"

using config_t = castle::serialization::ini::document<16U, 24U, 32U, 96U>;
config_t config;

Constraints & notes

  • No heap allocation; entries are stored in fixed-capacity Castle strings and a fixed-capacity vector.
  • Supported syntax: sections ([name]), global keys, = or : assignment, leading/trailing whitespace trimming, full-line # / ; comments, trailing comments after section headers, single- or double-quoted values, and escapes \, \", \n, \r, \t.
  • Unquoted values are preserved verbatim after trimming; inline comments are not stripped from them.
  • Boolean reads accept true/false, yes/no, on/off, and 1/0 case-insensitively.
  • Integer and floating-point parsing perform overflow/range checks and report failures through castle::status plus error_code.