[ { "path": ".clang-format", "content": "# Run manually to reformat a file:\n# clang-format -i --style=file \nLanguage: Cpp\nBasedOnStyle: Google\nIndentPPDirectives: AfterHash\nIndentCaseLabels: false\nDerivePointerAlignment: false\nStandard: c++20\nColumnLimit: 120\nAllowShortFunctionsOnASingleLine: Empty\nAllowShortLambdasOnASingleLine: None\nIndentRequiresClause: true\n" }, { "path": ".clang-tidy", "content": "---\n# Enable ALL the things! Except not really\n# cppcoreguidelines-avoid-magic-numbers/readability-magic-numbers: covers to many simply cases\n# modernize-use-trailing-return-type: purely stylistic suggestion\n# readability-identifier-length: not needed\n# bugprone-easily-swappable-parameters: covers to many simple cases\n# cppcoreguidelines-macro-usage: reduced to a minimum\n# bugprone-macro-parentheses: false positive\n# readability-function-cognitive-complexity: multiple if/else branches necessary to cover all use cases\n# cppcoreguidelines-non-private-member-variables-in-classes: same as misc-non-private-member-variables-in-classes\n# misc-non-private-member-variables-in-classes: allowed since classes are intended for single threading\n# cppcoreguidelines-pro-type-union-access: allowed since it is used because of performance and compile-time reasons\n# readability-else-after-return: allowed since if no else compile-time flow check fails and no optimization in debug\n# bugprone-exception-escape: to many false positives\n# cppcoreguidelines-pro-bounds-pointer-arithmetic: performance in debug\n# cppcoreguidelines-pro-bounds-constant-array-index:: performance\nChecks: >\n bugprone-*,\n concurrency-*,\n cppcoreguidelines-*,\n clang-analyzer-*,\n misc-*,\n modernize-*,\n performance-*,\n portability-*,\n readability-*,\n -clang-analyzer-osx*,\n -clang-analyzer-llvm*,\n -clang-analyzer-optin*,\n -clang-analyzer-unix*,\n -clang-analyzer-valist*,\n -clang-diagnostic-ignored-optimization-argument,\n -cppcoreguidelines-avoid-magic-numbers,\n -readability-magic-numbers,\n -modernize-use-trailing-return-type,\n -readability-identifier-length,\n -bugprone-easily-swappable-parameters,\n -cppcoreguidelines-macro-usage,\n -bugprone-macro-parentheses,\n -readability-function-cognitive-complexity,\n -cppcoreguidelines-non-private-member-variables-in-classes,\n -misc-non-private-member-variables-in-classes,\n -cppcoreguidelines-pro-type-union-access,\n -readability-else-after-return,\n -bugprone-exception-escape,\n -cppcoreguidelines-pro-bounds-pointer-arithmetic,\n -cppcoreguidelines-pro-bounds-constant-array-index,\n -cppcoreguidelines-avoid-do-while,\n -cppcoreguidelines-avoid-const-or-ref-data-members,\n -misc-include-cleaner,\n \n\nWarningsAsErrors: ''\n\nCheckOptions:\n - key: readability-identifier-naming.AbstractClassCase\n value: 'lower_case'\n - key: readability-identifier-naming.ClassCase\n value: 'lower_case'\n - key: readability-identifier-naming.ClassConstantCase\n value: 'lower_case'\n - key: readability-identifier-naming.ClassMemberCase\n value: 'lower_case'\n - key: readability-identifier-naming.ClassMethodCase\n value: 'lower_case'\n - key: readability-identifier-naming.ConstantCase\n value: 'lower_case'\n - key: readability-identifier-naming.ConstantParameterCase\n value: 'lower_case'\n - key: readability-identifier-naming.ConstantPointerParameterCase\n value: 'lower_case'\n - key: readability-identifier-naming.ConstexprFunctionCase\n value: 'lower_case'\n - key: readability-identifier-naming.ConstexprMethodCase\n value: 'lower_case'\n - key: readability-identifier-naming.ConstexprVariableCase\n value: 'lower_case'\n - key: readability-identifier-naming.EnumCase\n value: 'lower_case'\n - key: readability-identifier-naming.EnumConstantCase\n value: 'lower_case'\n - key: readability-identifier-naming.FunctionCase\n value: 'lower_case'\n - key: readability-identifier-naming.GlobalConstantCase\n value: 'lower_case'\n - key: readability-identifier-naming.GlobalConstantPointerCase\n value: 'lower_case'\n - key: readability-identifier-naming.GlobalFunctionCase\n value: 'lower_case'\n - key: readability-identifier-naming.GlobalPointerCase\n value: 'lower_case'\n - key: readability-identifier-naming.GlobalVariableCase\n value: 'lower_case'\n - key: readability-identifier-naming.InlineNamespaceCase\n value: 'lower_case'\n - key: readability-identifier-naming.LocalConstantCase\n value: 'lower_case'\n - key: readability-identifier-naming.LocalConstantPointerCase\n value: 'lower_case'\n - key: readability-identifier-naming.LocalPointerCase\n value: 'lower_case'\n - key: readability-identifier-naming.LocalVariableCase\n value: 'lower_case'\n - key: readability-identifier-naming.MacroDefinitionCase\n value: 'UPPER_CASE'\n - key: readability-identifier-naming.MemberCase\n value: 'lower_case'\n - key: readability-identifier-naming.MethodCase\n value: 'lower_case'\n - key: readability-identifier-naming.NamespaceCase\n value: 'lower_case'\n - key: readability-identifier-naming.ParameterCase\n value: 'lower_case'\n - key: readability-identifier-naming.ParameterPackCase\n value: 'lower_case'\n - key: readability-identifier-naming.PointerParameterCase\n value: 'lower_case'\n - key: readability-identifier-naming.PrivateMemberCase\n value: 'lower_case'\n - key: readability-identifier-naming.PrivateMemberSuffix\n value: '_'\n - key: readability-identifier-naming.PrivateMethodCase\n value: 'lower_case'\n - key: readability-identifier-naming.ProtectedMemberCase\n value: 'lower_case'\n - key: readability-identifier-naming.ProtectedMemberSuffix\n value: '_'\n - key: readability-identifier-naming.ProtectedMethodCase\n value: 'lower_case'\n - key: readability-identifier-naming.PublicMemberCase\n value: 'lower_case'\n - key: readability-identifier-naming.PublicMethodCase\n value: 'lower_case'\n - key: readability-identifier-naming.ScopedEnumConstantCase\n value: 'lower_case'\n - key: readability-identifier-naming.StaticConstantCase\n value: 'lower_case'\n - key: readability-identifier-naming.StaticVariableCase\n value: 'lower_case'\n - key: readability-identifier-naming.StructCase\n value: 'lower_case'\n - key: readability-identifier-naming.TemplateParameterCase\n value: 'CamelCase'\n - key: readability-identifier-naming.TypeTemplateParameterIgnoredRegexp\n value: 'expr-type' # see https://github.com/llvm/llvm-project/issues/46097\n - key: readability-identifier-naming.TemplateTemplateParameterCase\n value: 'CamelCase'\n - key: readability-identifier-naming.TypeAliasCase\n value: 'lower_case'\n - key: readability-identifier-naming.TypedefCase\n value: 'lower_case'\n - key: readability-identifier-naming.TypeTemplateParameterCase\n value: 'CamelCase'\n - key: readability-identifier-naming.UnionCase\n value: 'lower_case'\n - key: readability-identifier-naming.ValueTemplateParameterCase\n value: 'CamelCase'\n - key: readability-identifier-naming.VariableCase\n value: 'lower_case'\n - key: readability-identifier-naming.VirtualMethodCase\n value: 'lower_case'\n...\n" }, { "path": ".github/workflows/ci.yml", "content": "name: Continuous Integration\n\non:\n push:\n branches:\n - main\n pull_request:\n\njobs:\n checks:\n runs-on: ubuntu-22.04\n\n steps:\n - uses: actions/checkout@v3\n\n - name: Install GCC\n run: |\n sudo apt update && sudo apt install -y gcc-11 g++-11\n echo \"CC=gcc-11\" >> $GITHUB_ENV\n echo \"CXX=g++-11\" >> $GITHUB_ENV\n\n - name: Install cppcheck\n run: |\n sudo apt update && sudo apt install -y cppcheck\n cppcheck --version\n\n - name: Install clang-format and clang-tidy\n run: |\n wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add -\n sudo add-apt-repository 'deb http://apt.llvm.org/jammy/ llvm-toolchain-jammy-17 main'\n sudo apt update && sudo apt install -y clang-format-17 clang-tidy-17\n sudo update-alternatives --remove-all clang-format || true\n sudo update-alternatives --remove-all clang-tidy || true\n sudo update-alternatives --install /usr/bin/clang-format clang-format /usr/bin/clang-format-17 1000\n sudo update-alternatives --install /usr/bin/clang-tidy clang-tidy /usr/bin/clang-tidy-17 1000\n clang-tidy --version\n clang-format --version\n\n - name: Run clang-format\n run: cmake -D FORMAT_COMMAND=clang-format -P cmake/lint.cmake\n\n - name: Run cppcheck and clang-tidy\n # Cppcheck's checks are disabled. They are mostly redundant to clang-tidy and there are too many false positives.\n # But the parsing of cppcheck is kept to be compatible with its compiler frontend.\n if: ${{ !cancelled() }}\n run: |\n cmake --preset=ci-checks\n cmake --build build/test/static_analysis -j $(nproc)\n\n unit-tests:\n strategy:\n matrix:\n env: [ {os: ubuntu-22.04, compiler: gcc-11, std: 20},\n {os: ubuntu-22.04, compiler: gcc-12, std: 20},\n {os: ubuntu-22.04, compiler: gcc-12, std: 23},\n {os: ubuntu-24.04, compiler: gcc-13, std: 20},\n {os: ubuntu-24.04, compiler: gcc-13, std: 23},\n {os: ubuntu-24.04, compiler: gcc-14, std: 20},\n {os: ubuntu-24.04, compiler: gcc-14, std: 23},\n {os: ubuntu-22.04, compiler: clang-16, std: 20},\n {os: ubuntu-22.04, compiler: clang-16, std: 23},\n {os: ubuntu-22.04, compiler: clang-17, std: 20},\n {os: ubuntu-22.04, compiler: clang-17, std: 23},\n {os: ubuntu-24.04, compiler: clang-18, std: 20},\n {os: ubuntu-24.04, compiler: clang-18, std: 23},\n {os: ubuntu-24.04, compiler: clang-19, std: 20},\n {os: ubuntu-24.04, compiler: clang-19, std: 23}\n ]\n build_type: [ Debug, Release ]\n\n runs-on: ${{ matrix.env.os }}\n\n steps:\n - uses: actions/checkout@v3\n\n - name: Install Compiler\n run: |\n if [[ \"$compiler\" == \"gcc-11\" ]]; then\n sudo apt update && sudo apt install -y gcc-11 g++-11\n echo \"CC=gcc-11\" >> $GITHUB_ENV\n echo \"CXX=g++-11\" >> $GITHUB_ENV\n elif [[ \"$compiler\" == \"gcc-12\" ]]; then\n sudo apt update && sudo apt install -y gcc-12 g++-12\n echo \"CC=gcc-12\" >> $GITHUB_ENV\n echo \"CXX=g++-12\" >> $GITHUB_ENV\n elif [[ \"$compiler\" == \"gcc-13\" ]]; then\n sudo apt update && sudo apt install -y gcc-13 g++-13\n echo \"CC=gcc-13\" >> $GITHUB_ENV\n echo \"CXX=g++-13\" >> $GITHUB_ENV\n elif [[ \"$compiler\" == \"clang-16\" ]]; then\n wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add -\n sudo add-apt-repository 'deb http://apt.llvm.org/jammy/ llvm-toolchain-jammy-16 main'\n sudo apt update && sudo apt install -y clang-16\n echo \"CC=clang-16\" >> $GITHUB_ENV\n echo \"CXX=clang++-16\" >> $GITHUB_ENV\n elif [[ \"$compiler\" == \"clang-17\" ]]; then\n wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add -\n sudo add-apt-repository 'deb http://apt.llvm.org/jammy/ llvm-toolchain-jammy-17 main'\n sudo apt update && sudo apt install -y clang-17\n echo \"CC=clang-17\" >> $GITHUB_ENV\n echo \"CXX=clang++-17\" >> $GITHUB_ENV\n elif [[ \"$compiler\" == \"clang-18\" ]]; then\n wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add -\n sudo add-apt-repository 'deb http://apt.llvm.org/noble/ llvm-toolchain-noble-18 main'\n sudo apt update && sudo apt install -y clang-18\n echo \"CC=clang-18\" >> $GITHUB_ENV\n echo \"CXX=clang++-18\" >> $GITHUB_ENV\n elif [[ \"$compiler\" == \"clang-20\" ]]; then\n wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add -\n sudo add-apt-repository 'deb http://apt.llvm.org/noble/ llvm-toolchain-noble-20 main'\n sudo apt update && sudo apt install -y clang-20\n echo \"CC=clang-20\" >> $GITHUB_ENV\n echo \"CXX=clang++-20\" >> $GITHUB_ENV\n fi\n env:\n compiler: ${{ matrix.env.compiler }}\n\n - name: Configure\n run: cmake --preset=ci-ubuntu -DCMAKE_BUILD_TYPE=${{ matrix.build_type }} -DCMAKE_CXX_STANDARD=${{ matrix.env.std }}\n\n - name: Build Catch2\n run: cmake --build build -t Catch2WithMain -j $(nproc)\n\n - name: Build\n run: cmake --build build -j $(nproc)\n\n - name: Install\n run: cmake --install build --prefix prefix\n\n - name: Test\n working-directory: build\n run: ctest --verbose --output-on-failure\n\n coverage:\n runs-on: ubuntu-22.04\n\n steps:\n - uses: actions/checkout@v3\n\n - name: Install GCC\n run: |\n sudo apt update && sudo apt install -y gcc-11 g++-11\n echo \"CC=gcc-11\" >> $GITHUB_ENV\n echo \"CXX=g++-11\" >> $GITHUB_ENV\n\n - name: Install LCov\n run: sudo apt update && sudo apt install lcov -q -y\n\n - name: Configure\n run: cmake --preset=ci-coverage\n\n - name: Build Catch2\n run: cmake --build build -t Catch2WithMain -j $(nproc)\n\n - name: Build\n run: cmake --build build/test/unit_test -j $(nproc)\n\n - name: Test\n working-directory: build/test/unit_test\n run: ctest --output-on-failure\n\n - name: Process coverage info\n run: cmake --build build -t coverage\n\n - name: Submit to codecov.io\n uses: codecov/codecov-action@v3\n with:\n files: build/coverage.info\n\n memcheck:\n runs-on: ubuntu-24.04\n\n steps:\n - uses: actions/checkout@v3\n\n - name: Install GCC\n run: |\n sudo apt update && sudo apt install -y gcc-14 g++-14\n echo \"CC=gcc-14\" >> $GITHUB_ENV\n echo \"CXX=g++-14\" >> $GITHUB_ENV\n\n - name: Install valgrind\n run: sudo apt update && sudo apt install -y valgrind\n\n - name: Configure\n run: cmake --preset=ci-memcheck\n\n - name: Build Catch2\n run: cmake --build build -t Catch2WithMain -j $(nproc)\n\n - name: Build\n run: cmake --build build -j $(nproc)\n\n - name: Install\n run: cmake --install build --prefix prefix\n\n - name: Test\n working-directory: build\n run: |\n if ! ctest --verbose --output-on-failure -T memcheck; then\n find Testing/Temporary -name \"MemoryChecker.*.log\" -exec cat {} +\n exit 1\n fi\n\n sanitize:\n runs-on: ubuntu-24.04\n\n steps:\n - uses: actions/checkout@v3\n\n - name: Install GCC\n run: |\n sudo apt update && sudo apt install -y gcc-14 g++-14\n echo \"CC=gcc-14\" >> $GITHUB_ENV\n echo \"CXX=g++-14\" >> $GITHUB_ENV\n\n - name: Configure\n run: cmake --preset=ci-sanitize\n\n - name: Build Catch2\n run: cmake --build build -t Catch2WithMain -j $(nproc)\n\n - name: Build\n run: cmake --build build/test/unit_test -j $(nproc)\n\n - name: Test\n working-directory: build/test/unit_test\n env:\n ASAN_OPTIONS: \"strict_string_checks=1:\\\n detect_stack_use_after_return=1:\\\n check_initialization_order=1:\\\n strict_init_order=1:\\\n detect_leaks=1\"\n UBSAN_OPTIONS: print_stacktrace=1\n run: ctest --output-on-failure\n\n size-test:\n runs-on: ubuntu-22.04\n\n steps:\n - uses: actions/checkout@v3\n\n - name: Install GCC\n run: |\n sudo apt update && sudo apt install -y gcc-11 g++-11\n echo \"CC=gcc-11\" >> $GITHUB_ENV\n echo \"CXX=g++-11\" >> $GITHUB_ENV\n\n - name: Configure\n run: cmake --preset=ci-size-coverage -DCMAKE_BUILD_TYPE=MinSizeRel\n\n - name: Build\n run: cmake --build build/test/size_test -j $(nproc)\n\n - name: Size-Coverage\n run: cmake --build build -t size-coverage\n\n size-test-embedded:\n strategy:\n matrix:\n preset: [ ci-size-coverage-embedded, ci-size-coverage-embedded-nano ]\n\n runs-on: ubuntu-22.04\n\n env:\n DOWNLOAD_LINK: https://developer.arm.com/-/media/Files/downloads/gnu/11.3.rel1/binrel/arm-gnu-toolchain-11.3.rel1-x86_64-arm-none-eabi.tar.xz\n\n steps:\n - uses: actions/checkout@v3\n\n - name: Cache toolchain\n id: cache-toolchain\n uses: actions/cache@v4\n with:\n path: arm-gnu-toolchain-11.3.rel1-x86_64-arm-none-eabi\n key: ${{ env.DOWNLOAD_LINK }}\n\n - name: Install GCC ARM none eabi\n if: steps.cache-toolchain.outputs.cache-hit != 'true'\n run: |\n curl -L $DOWNLOAD_LINK | tar xJ\n\n - name: Configure\n run: cmake --preset=${{ matrix.preset }} -DCMAKE_BUILD_TYPE=MinSizeRel\n\n - name: Build\n run: cmake --build build/test/size_test -j $(nproc)\n\n - name: Size-Coverage\n run: cmake --build build -t size-coverage\n\n# - name: Coveralls - Doesn't work.\n# uses: coverallsapp/github-action@master\n# with:\n# github-token: ${{ secrets.GITHUB_TOKEN }}\n# path-to-lcov: build/test/size_test/size-coverage.info\n" }, { "path": ".github/workflows/pages.yml", "content": "name: Deploy Github Pages\n\non:\n push:\n branches:\n - main\n tags:\n - \"[0-9]+.[0-9]+.[0-9]+\"\n\njobs:\n deploy-pages:\n runs-on: ubuntu-latest\n permissions:\n contents: write\n steps:\n - name: Checkout\n uses: actions/checkout@v3\n\n - name: Generate single header file\n run: |\n pip install quom\n if [[ -z \"$(git tag --points-at HEAD)\" ]]; then\n DST=trunk\n else\n DST=$(git tag)\n fi\n mkdir -p web/dist/$DST\n quom include/emio/emio.hpp web/dist/$DST/emio.hpp\n\n - name: Deploy\n uses: JamesIves/github-pages-deploy-action@v4\n with:\n branch: gh-pages\n folder: web/\n clean: false\n" }, { "path": ".gitignore", "content": ".idea/\n.vs/\n.vscode/\nbuild/\ncmake/open-cpp-coverage.cmake\ncmake-build-*/\nprefix/\nCMakeLists.txt.user\nCMakeUserPresets.json\n" }, { "path": "CMakeLists.txt", "content": "cmake_minimum_required(VERSION 3.14)\n\ninclude(cmake/prelude.cmake)\n\nproject(\n emio\n VERSION 0.2.0\n DESCRIPTION \"Character input/output library for embedded systems.\"\n HOMEPAGE_URL \"https://github.com/viatorus/emio\"\n LANGUAGES CXX\n)\n\ninclude(cmake/project-is-top-level.cmake)\ninclude(cmake/variables.cmake)\n\n# ---- Declare library ----\n\nadd_library(emio_emio INTERFACE)\nadd_library(emio::emio ALIAS emio_emio)\n\nset_property(\n TARGET emio_emio PROPERTY\n EXPORT_NAME emio\n)\n\ntarget_include_directories(\n emio_emio ${warning_guard}\n INTERFACE\n \"$\"\n)\n\ntarget_compile_features(emio_emio INTERFACE cxx_std_20)\n\n# ---- Install rules ----\n\nif (NOT CMAKE_SKIP_INSTALL_RULES)\n include(cmake/install-rules.cmake)\nendif ()\n\n# ---- Developer mode ----\n\nif (NOT emio_DEVELOPER_MODE)\n return()\nelseif (NOT PROJECT_IS_TOP_LEVEL)\n message(\n AUTHOR_WARNING\n \"Developer mode is intended for developers of emio\"\n )\nendif ()\n\ninclude(cmake/dev-mode.cmake)\n" }, { "path": "CMakePresets.json", "content": "{\n \"version\": 2,\n \"cmakeMinimumRequired\": {\n \"major\": 3,\n \"minor\": 14,\n \"patch\": 0\n },\n \"configurePresets\": [\n {\n \"name\": \"cmake-pedantic\",\n \"hidden\": true,\n \"warnings\": {\n \"dev\": true,\n \"deprecated\": true,\n \"uninitialized\": true,\n \"unusedCli\": true,\n \"systemVars\": false\n },\n \"errors\": {\n \"dev\": true,\n \"deprecated\": true\n }\n },\n {\n \"name\": \"dev-mode\",\n \"hidden\": true,\n \"inherits\": \"cmake-pedantic\",\n \"cacheVariables\": {\n \"emio_DEVELOPER_MODE\": \"ON\"\n }\n },\n {\n \"name\": \"cppcheck\",\n \"hidden\": true,\n \"cacheVariables\": {\n \"CMAKE_CXX_CPPCHECK\": \"cppcheck;--error-exitcode=13\"\n }\n },\n {\n \"name\": \"clang-tidy\",\n \"hidden\": true,\n \"cacheVariables\": {\n \"CMAKE_CXX_CLANG_TIDY\": \"clang-tidy;--header-filter=${sourceDir}/*;-warnings-as-errors=*\"\n }\n },\n {\n \"name\": \"valgrind\",\n \"hidden\": true,\n \"cacheVariables\": {\n \"MEMORYCHECK_COMMAND_OPTIONS\": \"--error-exitcode=1 --leak-check=full\"\n }\n },\n {\n \"name\": \"ci-std\",\n \"description\": \"This preset makes sure the project actually builds with at least the specified standard\",\n \"hidden\": true,\n \"cacheVariables\": {\n \"CMAKE_CXX_EXTENSIONS\": \"OFF\",\n \"CMAKE_CXX_STANDARD\": \"23\",\n \"CMAKE_CXX_STANDARD_REQUIRED\": \"ON\"\n }\n },\n {\n \"name\": \"flags-unix\",\n \"hidden\": true,\n \"environment\": {\n \"CXX_FLAGS\": \"-Wall -Wextra -Wpedantic -Wconversion -Wsign-conversion -Wcast-qual -Wshadow -Wformat=2 -Wundef\"\n }\n },\n {\n \"name\": \"ci-unix\",\n \"generator\": \"Unix Makefiles\",\n \"hidden\": true,\n \"inherits\": [\n \"flags-unix\",\n \"ci-std\"\n ],\n \"cacheVariables\": {\n \"CMAKE_CXX_FLAGS\": \"$env{CXX_FLAGS}\",\n \"CMAKE_BUILD_TYPE\": \"Release\"\n }\n },\n {\n \"name\": \"ci-arm-none-eabi\",\n \"generator\": \"Unix Makefiles\",\n \"hidden\": true,\n \"inherits\": [\n \"flags-unix\",\n \"ci-std\"\n ],\n \"cacheVariables\": {\n \"CMAKE_TOOLCHAIN_FILE\": \"${sourceDir}/cmake/arm-none-eabi-toolchain.cmake\",\n \"CMAKE_CXX_FLAGS\": \"$env{CXX_FLAGS} -ffunction-sections -fdata-sections -mcpu=cortex-m7 -mthumb -g0 -fno-exceptions -fno-rtti\",\n \"CMAKE_EXE_LINKER_FLAGS\": \"-mcpu=cortex-m7 -mthumb -Wl,--gc-sections\",\n \"CMAKE_BUILD_TYPE\": \"MinSizeRel\"\n }\n },\n {\n \"name\": \"ci-arm-none-eabi-nano\",\n \"generator\": \"Unix Makefiles\",\n \"hidden\": true,\n \"inherits\": [\n \"ci-arm-none-eabi\"\n ],\n \"cacheVariables\": {\n \"CMAKE_EXE_LINKER_FLAGS\": \"-mcpu=cortex-m7 -mthumb -specs=nano.specs -Wl,--gc-sections\"\n }\n },\n {\n \"name\": \"coverage-unix\",\n \"inherits\": [\n \"ci-build\",\n \"ci-unix\"\n ],\n \"hidden\": true,\n \"cacheVariables\": {\n \"ENABLE_COVERAGE\": \"ON\",\n \"CMAKE_BUILD_TYPE\": \"Coverage\",\n \"CMAKE_CXX_FLAGS_COVERAGE\": \"-O0 -g --coverage\",\n \"CMAKE_EXE_LINKER_FLAGS_COVERAGE\": \"--coverage\",\n \"CMAKE_SHARED_LINKER_FLAGS_COVERAGE\": \"--coverage\"\n }\n },\n {\n \"name\": \"ci-coverage\",\n \"inherits\": [\n \"coverage-unix\",\n \"dev-mode\"\n ],\n \"cacheVariables\": {\n \"COVERAGE_HTML_COMMAND\": \"\"\n }\n },\n {\n \"name\": \"ci-sanitize\",\n \"inherits\": [\n \"ci-build\",\n \"ci-unix\",\n \"dev-mode\"\n ],\n \"cacheVariables\": {\n \"CMAKE_BUILD_TYPE\": \"Sanitize\",\n \"CMAKE_CXX_FLAGS_SANITIZE\": \"-O2 -g -fsanitize=address,undefined -fno-omit-frame-pointer -fno-common\"\n }\n },\n {\n \"name\": \"ci-build\",\n \"binaryDir\": \"${sourceDir}/build\",\n \"hidden\": true\n },\n {\n \"name\": \"ci-ubuntu\",\n \"inherits\": [\n \"ci-build\",\n \"ci-unix\",\n \"dev-mode\"\n ]\n },\n {\n \"name\": \"ci-memcheck\",\n \"inherits\": [\n \"ci-build\",\n \"ci-unix\",\n \"valgrind\",\n \"dev-mode\"\n ]\n },\n {\n \"name\": \"ci-checks\",\n \"inherits\": [\n \"ci-build\",\n \"ci-unix\",\n \"clang-tidy\",\n \"cppcheck\",\n \"dev-mode\"\n ]\n },\n {\n \"name\": \"ci-embedded\",\n \"inherits\": [\n \"ci-build\",\n \"ci-arm-none-eabi\",\n \"dev-mode\"\n ]\n },\n {\n \"name\": \"ci-size-coverage\",\n \"inherits\": [\n \"ci-build\",\n \"ci-unix\",\n \"dev-mode\"\n ],\n \"cacheVariables\": {\n \"CMAKE_CXX_FLAGS\": \"$env{CXX_FLAGS} -ffunction-sections -fdata-sections -g0 -fno-exceptions -fno-rtti -fno-asynchronous-unwind-tables\",\n \"BUILD_SIZE_COVERAGE\": \"ON\",\n \"ENABLE_SIZE_COVERAGE\": \"ON\",\n \"SIZE_COVERAGE_HTML_COMMAND\": \"\",\n \"SIZE_TOOL\": \"size\"\n }\n },\n {\n \"name\": \"ci-size-coverage-embedded\",\n \"inherits\": [\n \"ci-build\",\n \"ci-arm-none-eabi\",\n \"dev-mode\"\n ],\n \"cacheVariables\": {\n \"BUILD_SIZE_COVERAGE\": \"ON\",\n \"ENABLE_SIZE_COVERAGE\": \"ON\",\n \"SIZE_COVERAGE_HTML_COMMAND\": \"\",\n \"SIZE_TOOL\": \"arm-none-eabi-size\"\n }\n },\n {\n \"name\": \"ci-size-coverage-embedded-nano\",\n \"inherits\": [\n \"ci-build\",\n \"ci-arm-none-eabi-nano\",\n \"dev-mode\"\n ],\n \"cacheVariables\": {\n \"BUILD_SIZE_COVERAGE\": \"ON\",\n \"ENABLE_SIZE_COVERAGE\": \"ON\",\n \"SIZE_COVERAGE_HTML_COMMAND\": \"\",\n \"SIZE_TOOL\": \"arm-none-eabi-size\"\n }\n }\n ],\n \"buildPresets\": [\n {\n \"name\": \"default\",\n \"configurePreset\": \"ci-ubuntu\"\n }\n ]\n}\n" }, { "path": "LICENSE", "content": "Copyright (c) 2021 - present, Toni Neubert (viatorus/emio)\n\nCopyright (c) 2012 - present, Victor Zverovich (fmtlib/fmt)\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n" }, { "path": "README.md", "content": "![logo](docs/res/logo.png)\n\n[![Continuous Integration](https://github.com/Viatorus/emio/actions/workflows/ci.yml/badge.svg)](https://github.com/Viatorus/emio/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/Viatorus/emio/branch/main/graph/badge.svg?token=7BQFK1PNLX)](https://codecov.io/gh/Viatorus/emio)\n[![Conan Center](https://img.shields.io/conan/v/emio)](https://conan.io/center/recipes/emio)\n\n**em{io}** is a safe and fast high-level and low-level character input/output library for bare-metal and RTOS based\nembedded systems with a very small binary footprint.\n\n```cpp\n// High-level\nstd::string str = emio::format(\"The answer is {}.\", 42); // Format argument.\n\nint answer{};\nemio::result scan_res = emio::scan(str, \"The answer is {}.\", answer); // Scan input string.\nif (scan_res) {\n emio::print(\"The answer is {}.\", answer); // Output to console.\n}\n\n// Without using heap.\nemio::static_buffer<128> buf{}; \nemio::format_to(buf, \"The answer is {:#x}.\", 42).value();\nbuf.view(); // <- The answer is 0x2a.\n\n// Low-level\nemio::writer wrt{buf};\nwrt.write_str(\" In decimal: \").value();\nwrt.write_int(42).value();\nwrt.write_char('.').value();\nbuf.view(); // <- The answer is 0x2a. In decimal: 42.\n\nemio::reader rdr{\"17c\"};\nEMIO_TRY(uint32_t number, rdr.parse_int()); // <- 17\nEMIO_TRY(char suffix, rdr.read_char()); // <- c\n```\n\n[**This library is in beta status! Please help to make it fly!**](https://github.com/Viatorus/emio/milestone/1)\n\n* [API documentation](docs/API.md)\n* Try emio [online](https://godbolt.org/z/fP7z7MzbG).\n\n## Yet another character input/output library \n\nBare-metal and RTOS based embedded systems do have special requirements which are mostly overlooked by the C++ standard,\nits implementations and other libraries.\n\nTherefore, this library:\n\n* has a very small binary footprint **(~38 times smaller than fmtlib!)**\n* returns a result object instead of throwing an exception\n* provides a high-level and low-level API which can be used at compile-time\n\nRead more about it in the [DESIGN](docs/DESIGN.md) document.\n\n## Including emio in your project\n\n- With CMake and fetch content\n\n```cmake\nFetchContent_Declare(\n emio\n GIT_TAG main\n GIT_REPOSITORY https://github.com/Viatorus/emio.git\n GIT_SHALLOW TRUE\n)\nFetchContent_MakeAvailable(emio)\n```\n\n- Download the [single header file](https://viatorus.github.io/emio/) generated with [Quom](https://github.com/Viatorus/quom)\n- From [Conan Center](https://conan.io/center/recipes/emio)\n\nA compiler supporting C++20 is required. Tested with GCC 11/12/13 and Clang 16/17.\n\n## Contributing\n\nSee the [CONTRIBUTING](docs/CONTRIBUTING.md) document.\n\n## Licensing\n\nem{io} is distributed under the [MIT license](LICENSE).\n" }, { "path": "cmake/arm-none-eabi-toolchain.cmake", "content": "cmake_minimum_required(VERSION 3.14.0)\n\nset(CMAKE_SYSTEM_NAME Linux)\nset(CMAKE_SYSTEM_VERSION 1)\nset(CMAKE_SYSTEM_PROCESSOR arm)\n\nset(CMAKE_TRY_COMPILE_TARGET_TYPE STATIC_LIBRARY) # do not link executable when testing the compiler.\n\nset(TOOLCHAIN_BIN_PATH ${CMAKE_CURRENT_SOURCE_DIR}/arm-gnu-toolchain-11.3.rel1-x86_64-arm-none-eabi/bin)\n\nset(CMAKE_C_COMPILER ${TOOLCHAIN_BIN_PATH}/arm-none-eabi-gcc)\nset(CMAKE_CXX_COMPILER ${TOOLCHAIN_BIN_PATH}/arm-none-eabi-g++)\nset(CMAKE_AR ${TOOLCHAIN_BIN_PATH}/arm-none-eabi-gcc-ar)\nset(CMAKE_RANLIB ${TOOLCHAIN_BIN_PATH}/arm-none-eabi-gcc-ranlib)\n" }, { "path": "cmake/coverage.cmake", "content": "# ---- Variables ----\n\n# We use variables separate from what CTest uses, because those have\n# customization issues\nset(\n COVERAGE_TRACE_COMMAND\n lcov -c -q\n -o \"${PROJECT_BINARY_DIR}/coverage.info\"\n -d \"${PROJECT_BINARY_DIR}\"\n --include \"${PROJECT_SOURCE_DIR}/*\"\n CACHE STRING\n \"; separated command to generate a trace for the 'coverage' target\"\n)\n\nset(\n COVERAGE_HTML_COMMAND\n genhtml --legend -f -q\n \"${PROJECT_BINARY_DIR}/coverage.info\"\n -p \"${PROJECT_SOURCE_DIR}\"\n -o \"${PROJECT_BINARY_DIR}/coverage_html\"\n CACHE STRING\n \"; separated command to generate an HTML report for the 'coverage' target\"\n)\n\n# ---- Coverage target ----\n\nadd_custom_target(\n coverage\n COMMAND ${COVERAGE_TRACE_COMMAND}\n COMMAND ${COVERAGE_HTML_COMMAND}\n COMMENT \"Generating coverage report\"\n VERBATIM\n)\n" }, { "path": "cmake/dev-mode.cmake", "content": "include(cmake/folders.cmake)\n\nset_property(GLOBAL PROPERTY CTEST_TARGETS_ADDED 1)\ninclude(CTest)\n\nif (BUILD_TESTING OR BUILD_SIZE_COVERAGE)\n set(CMAKE_MODULE_PATH\n CACHE INTERNAL\n FORCE\n )\n\n set(FMT_HEADERS\n CACHE INTERNAL\n FORCE\n )\n\n set(FMT_OS OFF\n CACHE INTERNAL\n \"Path to downloaded Catch2 modules\"\n FORCE\n )\n\n\n Include(FetchContent)\n FetchContent_Declare(\n fmt\n GIT_TAG d9bc5f1320332db9a4bf7e103b0813b94e369304 # 9.1.1 - not released\n GIT_REPOSITORY https://github.com/fmtlib/fmt.git\n )\n FetchContent_MakeAvailable(fmt)\nendif ()\n\nif (BUILD_TESTING)\n Include(FetchContent)\n FetchContent_Declare(\n Catch2\n GIT_TAG v3.4.0\n GIT_REPOSITORY https://github.com/catchorg/Catch2.git\n GIT_SHALLOW TRUE\n )\n FetchContent_MakeAvailable(Catch2)\nendif ()\n\n\nif (BUILD_TESTING)\n add_subdirectory(test/benchmark)\n add_subdirectory(test/compile_test)\n add_subdirectory(test/static_analysis)\n add_subdirectory(test/unit_test)\nendif ()\n\nif (BUILD_SIZE_COVERAGE)\n add_subdirectory(test/size_test)\nendif ()\n\noption(ENABLE_COVERAGE \"Enable coverage support separate from CTest's\" OFF)\nif (ENABLE_COVERAGE)\n include(cmake/coverage.cmake)\nendif ()\n\ninclude(cmake/lint-targets.cmake)\n\nadd_folders(Project)\n" }, { "path": "cmake/elf_to_size_coverage.py", "content": "#!/usr/bin/env python3\n\nimport argparse\nimport re\nimport subprocess\nimport sys\nfrom io import StringIO\nfrom pathlib import Path\n\n\ndef parse_args(args):\n parser = argparse.ArgumentParser(\n description='Creates the size difference of a base file size to multiple other files sizes as lcov info file')\n parser.add_argument('--size-tool', type=Path, help='path to the GNU size tool', metavar='SIZE_TOOL', required=True)\n parser.add_argument('base', type=Path, help='the first file is used as base size', metavar='BASE_FILE')\n parser.add_argument('files', type=Path, nargs='+', help='file(s) to compare', metavar='FILE')\n parser.add_argument('--output', '-o', type=Path, help='specify the output file', metavar='OUTPUT_FILE',\n required=True)\n\n return parser.parse_args(args)\n\n\nclass Generator:\n def __init__(self, size_tool, base_file, out):\n self._size_tool = size_tool\n self._base_file = base_file.absolute()\n self._base_size = self._get_size(base_file)\n self._out = out\n self._out.write(\"TN:\\n\")\n\n print(\"{}: {} (base)\".format(base_file, self._base_size))\n\n def generate(self, file: Path):\n file_path = file.absolute()\n file_size = self._get_size(file)\n\n print('{} - {}'.format(file_path, file_size))\n\n if file_size < self._base_size:\n raise Exception(f'{file} cannot be smaller than {self._base_file}')\n\n self._out.write(f'SF:{file_path}\\n')\n for covered in range(self._base_size):\n self._out.write(f'DA:{covered},1\\n')\n\n for uncovered in range(self._base_size, file_size):\n self._out.write(f'DA:{uncovered},0\\n')\n self._out.write('end_of_record\\n')\n\n def _get_size(self, file: Path):\n output = subprocess.check_output([str(self._size_tool), '--format=GNU', str(file)], encoding='UTF-8')\n # text data bss total filename\n # 348 120 28 496 base\n # Get total from regex:\n total = re.search('text\\s+data\\s+bss\\s+total\\s+filename\\n\\s+\\d+\\s+\\d+\\s+\\d+\\s+(\\d+)\\s+', output)\n if not total:\n raise Exception(f'Unexpected output from size: {output}')\n return int(total[1])\n\n\ndef run():\n args = parse_args(sys.argv[1:])\n\n if not args.base.is_file():\n raise Exception(f'Base file not found: {args.base}')\n\n output = StringIO()\n generator = Generator(args.size_tool, args.base, output)\n\n for file in args.files:\n if not file.is_file():\n raise Exception(f'File not found: {file}')\n generator.generate(file)\n\n args.output.write_text(output.getvalue())\n\n\nif __name__ == '__main__':\n run()\n" }, { "path": "cmake/folders.cmake", "content": "set_property(GLOBAL PROPERTY USE_FOLDERS YES)\n\n# Call this function at the end of a directory scope to assign a folder to\n# targets created in that directory. Utility targets will be assigned to the\n# UtilityTargets folder, otherwise to the ${name}Targets folder. If a target\n# already has a folder assigned, then that target will be skipped.\nfunction(add_folders name)\n get_property(targets DIRECTORY PROPERTY BUILDSYSTEM_TARGETS)\n foreach (target IN LISTS targets)\n get_property(folder TARGET \"${target}\" PROPERTY FOLDER)\n if (DEFINED folder)\n continue()\n endif ()\n set(folder Utility)\n get_property(type TARGET \"${target}\" PROPERTY TYPE)\n if (NOT type STREQUAL \"UTILITY\")\n set(folder \"${name}\")\n endif ()\n set_property(TARGET \"${target}\" PROPERTY FOLDER \"${folder}Targets\")\n endforeach ()\nendfunction()\n" }, { "path": "cmake/install-config.cmake", "content": "include(\"${CMAKE_CURRENT_LIST_DIR}/emioTargets.cmake\")\n" }, { "path": "cmake/install-rules.cmake", "content": "if (PROJECT_IS_TOP_LEVEL)\n set(CMAKE_INSTALL_INCLUDEDIR include/emio CACHE PATH \"\")\nendif ()\n\n# Project is configured with no languages, so tell GNUInstallDirs the lib dir\nset(CMAKE_INSTALL_LIBDIR lib CACHE PATH \"\")\n\ninclude(CMakePackageConfigHelpers)\ninclude(GNUInstallDirs)\n\n# find_package() call for consumers to find this project\nset(package emio)\n\ninstall(\n DIRECTORY include/\n DESTINATION \"${CMAKE_INSTALL_INCLUDEDIR}\"\n COMPONENT emio_Development\n)\n\ninstall(\n TARGETS emio_emio\n EXPORT emioTargets\n INCLUDES DESTINATION \"${CMAKE_INSTALL_INCLUDEDIR}\"\n)\n\nwrite_basic_package_version_file(\n \"${package}ConfigVersion.cmake\"\n COMPATIBILITY SameMajorVersion\n ARCH_INDEPENDENT\n)\n\n# Allow package maintainers to freely override the path for the configs\nset(\n emio_INSTALL_CMAKEDIR \"${CMAKE_INSTALL_DATADIR}/${package}\"\n CACHE PATH \"CMake package config location relative to the install prefix\"\n)\nmark_as_advanced(emio_INSTALL_CMAKEDIR)\n\ninstall(\n FILES cmake/install-config.cmake\n DESTINATION \"${emio_INSTALL_CMAKEDIR}\"\n RENAME \"${package}Config.cmake\"\n COMPONENT emio_Development\n)\n\ninstall(\n FILES \"${PROJECT_BINARY_DIR}/${package}ConfigVersion.cmake\"\n DESTINATION \"${emio_INSTALL_CMAKEDIR}\"\n COMPONENT emio_Development\n)\n\ninstall(\n EXPORT emioTargets\n NAMESPACE emio::\n DESTINATION \"${emio_INSTALL_CMAKEDIR}\"\n COMPONENT emio_Development\n)\n\nif (PROJECT_IS_TOP_LEVEL)\n include(CPack)\nendif ()\n" }, { "path": "cmake/lint-targets.cmake", "content": "set(\n FORMAT_PATTERNS\n source/*.cpp source/*.hpp\n include/*.hpp\n test/*.cpp test/*.hpp\n example/*.cpp example/*.hpp\n CACHE STRING\n \"; separated patterns relative to the project source dir to format\"\n)\n\nset(FORMAT_COMMAND clang-format CACHE STRING \"Formatter to use\")\n\nadd_custom_target(\n format-check\n COMMAND \"${CMAKE_COMMAND}\"\n -D \"FORMAT_COMMAND=${FORMAT_COMMAND}\"\n -D \"PATTERNS=${FORMAT_PATTERNS}\"\n -P \"${PROJECT_SOURCE_DIR}/cmake/lint.cmake\"\n WORKING_DIRECTORY \"${PROJECT_SOURCE_DIR}\"\n COMMENT \"Linting the code\"\n VERBATIM\n)\n\nadd_custom_target(\n format-fix\n COMMAND \"${CMAKE_COMMAND}\"\n -D \"FORMAT_COMMAND=${FORMAT_COMMAND}\"\n -D \"PATTERNS=${FORMAT_PATTERNS}\"\n -D FIX=YES\n -P \"${PROJECT_SOURCE_DIR}/cmake/lint.cmake\"\n WORKING_DIRECTORY \"${PROJECT_SOURCE_DIR}\"\n COMMENT \"Fixing the code\"\n VERBATIM\n)\n" }, { "path": "cmake/lint.cmake", "content": "cmake_minimum_required(VERSION 3.14)\n\nmacro(default name)\n if (NOT DEFINED \"${name}\")\n set(\"${name}\" \"${ARGN}\")\n endif ()\nendmacro()\n\ndefault(FORMAT_COMMAND clang-format)\ndefault(\n PATTERNS\n source/*.cpp source/*.hpp\n include/*.hpp\n test/*.cpp test/*.hpp\n example/*.cpp example/*.hpp\n)\ndefault(FIX NO)\n\nset(flag --output-replacements-xml)\nset(args OUTPUT_VARIABLE output)\nif (FIX)\n set(flag -i)\n set(args \"\")\nendif ()\n\nfile(GLOB_RECURSE files ${PATTERNS})\nset(badly_formatted \"\")\nset(output \"\")\nstring(LENGTH \"${CMAKE_SOURCE_DIR}/\" path_prefix_length)\n\nforeach (file IN LISTS files)\n execute_process(\n COMMAND \"${FORMAT_COMMAND}\" --style=file \"${flag}\" \"${file}\"\n WORKING_DIRECTORY \"${CMAKE_SOURCE_DIR}\"\n RESULT_VARIABLE result\n ${args}\n )\n if (NOT result EQUAL \"0\")\n message(FATAL_ERROR \"'${file}': formatter returned with ${result}\")\n endif ()\n if (NOT FIX AND output MATCHES \"\\n string_view`\n\n- Returns the name of the error code.\n\n*Example*\n\n```cpp\nstd::string_view error_msg = emio::to_string(emio::err::invalid_format); // invalid_format\n```\n\n## result\n\n`template class result;`\n\n- The return type of almost all functions to propagate a value of type `T` on success or an error of type `emio::err`\n on failure.\n\n*constructor(arg)*\n\n- Constructable either from T or `emio::err`.\n\n`has_value() -> bool`\n\n- Checks whether the object holds a value.\n\n`has_error() -> bool`\n\n- Checks whether the object holds an error.\n\n`value() -> T`\n\n- Returns the value or throws/terminates if no value is held.\n\n`value_or(T) -> T`\n\n- Returns the value or returns the passed alternative if no value is held.\n\n`assume_value() -> T`\n\n- Returns the value without any checks. Invokes undefined behavior if no value is held.\n\n`error() -> emio::err`\n\n- Returns the error or throws/terminates if no error is held.\n\n`assume_error() -> emio::err`\n\n- Returns the error without any checks. Invokes undefined behavior if no error is held.\n\nThere exists two helper macros to simplify the control flow:\n\n`EMIO_TRYV(expr)`\n\n- Evaluates an expression *expr*. If successful, continues the execution. If unsuccessful, immediately returns from the\n calling function.\n\n`EMIO_TRY(var, expr)`\n\n- Evaluates an expression *expr*. If successful, assigns the value to a declaration *var*. If unsuccessful, immediately\n returns from the calling function.\n\n*Example*\n\n```cpp\nresult parse_one(std::string_view sv) {\n if (sv.empty()) {\n return emio::err::eof;\n }\n if (sv == \"1\") {\n return 1;\n } else {\n return emio::err::invalid_data;\n }\n}\n\nemio::result parse(std::string_view sv) {\n EMIO_TRY(int val, parse_one(sv));\n \n emio::result res = parse_one(sv);\n if (!res) {\n return res.error();\n }\n if (res.assume_value() == val) {\n return emio::success;\n }\n return emio::err::invalid_format;\n}\n```\n\n## Buffer\n\nAn abstract class which provides functionality for receiving a contiguous memory region of chars to write into.\n\nThere exist multiple implementation of a buffer, all fulfilling a different use case.\nSome buffers have an internal cache to provide a contiguous memory if the actually output object doesn't provide on.\n\nAdditionally, some buffers can be reset to reuse the total capacity of the storage for the next operation.\nThis invalidates any obtaining view!\n\n### memory_buffer\n\n- An endless growing buffer with an internal storage for small buffer optimization.\n\n*Example*\n\n```cpp\nemio::memory_buffer buf;\n\nemio::result> area = buf.get_write_area_of(50);\nassert(area);\nstd::string_view view = buf.view();\nassert(buf.capacity() >= view.size());\nstd::string str = buf.str();\nbuf.reset();\n```\n\n### span_buffer\n\n- A buffer over a specific contiguous range.\n\n*Example*\n\n```cpp\nstd::array storage;\nemio::span_buffer buf{storage};\nassert(buf.capacity() == 512);\n\nemio::result> area = buf.get_write_area_of(50);\nassert(area);\nstd::string_view view = buf.view();\nstd::string str = buf.str();\nbuf.reset();\n```\n\n### static_buffer\n\n- A buffer containing a fixed-size storage.\n\n*Example*\n\n```cpp\nemio::static_buffer<512> buf{storage}; \nassert(buf.capacity() == 512);\n\nemio::result> area = buf.get_write_area_of(50);\nassert(area);\nstd::string_view view = buf.view();\nstd::string str = buf.str();\nbuf.reset();\n```\n\n### iterator_buffer\n\n- A buffer for all kinds of output iterators (raw-pointers, back_insert_iterator or any other output iterator).\n- The buffer's with a direct output iterator (e.g. std::string::iterator) do have an internal cache.\n\n*Example*\n\n```cpp\nstd::string storage{\"filled with something up\"};\nemio::iterator_buffer buf{std::back_inserter(storage)}; \n\nemio::result> area = buf.get_write_area_of(50);\nassert(area);\nassert(buf.flush());\nstd::back_insert_iterator out = buf.out();\n```\n\n### file_buffer\n\n- A buffer over an std::File (file stream) with an internal cache.\n\n*Example*\n\n```cpp\nstd::FILE* file = std::fopen(\"test\", \"w\");\nemio::file_buffer buf{file}; \n\nemio::result> area = buf.get_write_area_of(50);\nassert(area);\nassert(buf.flush());\nbuf.reset();\n```\n\n### truncating_buffer\n\n- A buffer which truncates the remaining output if the limit of another provided buffer is reached.\n\n*Example*\n\n```cpp\nemio::static_buffer<48> primary_buf{};\nemio::truncating_buffer buf{primary_buf, 32};\n\nemio::result> area = buf.get_write_area_of(50);\nassert(area);\nassert(buf.flush());\nassert(primary_buf.view().size() == 32); // Only 32 bytes are flushed.\n```\n\n## Reader\n\n` class reader;`\n\n- A class to read and parse a char sequence like a finite input stream.\n\n*constructor(input)*\n\n- Constructable from any suitable char sequence.\n\n*Example*\n\n```cpp\nemio::reader input{\"1\"};\nassert(input.cnt_remaining() == 1);\nassert(input.view_remaining() == \"1\");\n\nstd::string foo{\"foo\"};\nemio::reader input2{foo};\nassert(input2.cnt_remaining() == 3);\nassert(input2.view_remaining() == \"foo\");\n```\n\n`peek() -> result`\n\n- Returns the next char without consuming it.\n\n*Example*\n\n```cpp\nemio::reader input{\"abc\"};\nemio::result res = input.peek();\nassert(res == 'a');\n```\n\n`read_char() -> result`\n\n- Returns one char.\n\n*Example*\n\n```cpp\nemio::reader input{\"abc\"};\nemio::result res = input.read_char();\nassert(res == 'a');\n```\n\n`read_n_char(n) -> result`\n\n- Returns *n* chars.\n\n*Example*\n\n```cpp\nemio::reader input{\"abc\"};\nemio::result res = input.read_n_char(3);\nassert(res == \"abc\");\n```\n\n`parse_int(base = 10) -> result`\n\n- Parses an integer of type *T* with a specific *base*.\n\n*Example*\n\n```cpp\nemio::reader input{\"abc\"};\nemio::result res = input.read_int(16 /* hexadecimal */);\nassert(res == 0xabc);\n```\n\n`read_until/_char/str/any_of/none_of/([predicate,] options) -> result`\n\n- Reads n chars until a given *predicate* (delimiter/group/function) applies.\n- Has *options* to configure what should happen with the predicate and what should happen if EOF is reached.\n\n*Example*\n\n```cpp\nemio::reader get_input() {\n return emio::reader{\"abc\"};\n}\n\n// read_until_char\nemio::result res = get_input().read_until_char('c');\nassert(res == \"ab\");\n\n// read_until_str\nemio::result res = get_input().read_until_str(\"bc\");\nassert(res == \"a\");\n\n// read_until_any_of\nemio::result res = get_input().read_until_any_of(\"cd\");\nassert(res == \"ab\");\n\n// read_until_none_of\nemio::result res = get_input().read_until_none_of(\"ab\");\nassert(res == \"ab\");\n\n// read_until with predicate\nemio::result res = get_input().read_until([](char c) { return c != 'a';});\nassert(res == \"a\");\n```\n\n```cpp\n// Different options.\nemio::reader input{\"abc 123 Hello\"};\n\n// with include_delimiter option \nemio::result res = input.read_until_str(\" \", {.include_delimiter = true});\nassert(res == \"abc \");\n\n// with keep keep_delimiter option \nemio::result res = input.read_until_str(\"Hello\", {.keep_delimiter = true});\nassert(res == \"123 \");\n\n// with ignore_eof option \nemio::result res = input.read_until_str(\"xyz\", {.ignore_eof = true});\nassert(res == \"Hello\");\n```\n\n`read_if_match_char/str(c/str) -> result`\n\n- Reads one/multiple chars if *c/str* matches the next char/chars.\n\n*Example*\n\n```cpp\nemio::reader input{\"abc\"};\nif (input.read_if_match_char('a')) {\n emio::result res = input.read_if_match_str(\"bc\"); \n assert(res == \"bc\"); \n}\n```\n\n## Writer\n\n`class writer;`\n\n- A class to write sequences of characters or other kinds of data into an output buffer.\n\n*constructor(buffer)*\n\n*Example*\n\n```cpp\nemio::static_buffer<128> buf;\nemio::writer output{buf};\n```\n\n- Constructable from a reference to a buffer.\n\n`write_char(c) -> result`\n\n- Writes a char *c* into the buffer.\n\n*Example*\n\n```cpp\nemio::writer output{get_buffer()};\nemio::result res = output.write_char('a'); // Buffer contains \"a\"\nassert(res);\n```\n\n`write_char_n(c, n) -> result`\n\n- Writes a char *c* *n* times into the buffer.\n\n*Example*\n\n```cpp\nemio::writer output{get_buffer()};\nemio::result res = output.write_char_n('a', 5); // Buffer contains \"aaaaa\"\nassert(res);\n```\n\n`write_char_escaped(c) -> result`\n\n- Writes a char *c* escaped into the buffer.\n\n*Example*\n\n```cpp\nemio::writer output{get_buffer()};\nemio::result res = output.write_char_escaped('\\n', 5); // Buffer contains \"\\\\n\"\nassert(res);\n```\n\n`write_str(sv) -> result`\n\n- Writes a char sequence *sv* into the buffer.\n\n*Example*\n\n```cpp\nemio::writer output{get_buffer()};\nemio::result res = output.write_str(\"Hello\"); // Buffer contains \"Hello\"\nassert(res);\n```\n\n`write_str_escaped(sv) -> result`\n\n- Writes a char sequence *sv* escaped into the buffer.\n\n*Example*\n\n```cpp\nemio::writer output{get_buffer()};\nemio::result res = output.write_str(\"\\t 'and'\"); // Buffer contains \"\\\\t \\'and\\'\"\nassert(res);\n```\n\n`write_int(integer, options) -> result`\n\n- Writes an *integer* into the buffer.\n- Has *options* to configure the base and if the alphanumerics should be in lower or upper case.\n\n*Example*\n\n```cpp\nemio::writer output{get_buffer()};\nemio::result res = output.write_int(15); // Buffer contains \"15\"\nassert(res);\n\nres = output.write_int(15, {.base = 16, upper_case = true}); // Buffer contains \"15F\"\nassert(res);\n```\n\n## Format\n\nThe following functions use a format string syntax which is nearly identical to the one used in\n[fmt](https://fmt.dev/latest/syntax.html), which is similar to\n[str.format](https://docs.python.org/3/library/stdtypes.html#str.format) in Python.\n\nThings that are missing:\n\n- chrono syntax (planned)\n- 'a'/'A' for hexadecimal floating point format (TBD)\n- UTF-8 support (TBD)\n- using an identifier as arg_id: `fmt::format(\"{nbr}\", fmt::arg(\"nbr\", 42)` (TBD)\n- `'L'` options for locale (somehow possible but not with std::locale because of the binary size)\n\nThe grammar for the replacement field is as follows:\n\n```sass\nreplacement_field ::= \"{\" [arg_id] [\":\" format_spec] \"}\"\n\narg_id ::= integer\n\ninteger ::= digit+\n\ndigit ::= \"0\"...\"9\"\n```\n\nThe grammar for the format specification is as follows:\n\n```sass\nformat_spec ::= [[fill]align][sign][\"#\"][\"0\"][width][type]\n\nfill ::= \n\nalign ::= \"<\" | \">\" | \"^\"\n\nsign ::= \"+\" | \"-\" | \" \"\n\nwidth ::= integer\n\ntype ::= \"b\" | \"B\" | \"c\" | \"d\" | \"o\" | \"s\" | \"x\" | \"X\" | \"e\" | \"E\" | \"f\" | \"F\" | \"g\" | \"G\"\n```\n\nThe syntax of the format string is validated at compile-time. If a validation at runtime is required, the string\nmust be wrapped inside a `runtime_string` object. There is a simple helper function for that:\n\n`runtime(string_view) -> runtime_string`\n\nSome functions (like `format` or `formatted_size`) are further optimized (simplified) in their return type if the format\nstring is a valid-only format string that could be ensured at compile-time.\n\n`format(format_str, ...args) -> string/result`\n\n*Example*\n\n```cpp\nstd::string str = emio::format(\"Hello {}!\", 42);\nassert(str == \"Hello 42!\");\n\nstd::string format_str = \"Good by {}!\";\nemio::result res = emio::format(emio::runtime(format_str), 42);\nassert(res == \"Good by 42!\");\n```\n\n- Formats arguments according to the format string, and returns the result as a string.\n- The return value depends on the type of the format string (valid-only type or not).\n\n`format_to(out, format_str, ...args) -> result`\n\n- Formats arguments according to the format string, and writes the result to the output iterator/buffer.\n **Note** If a raw output pointer or simple output iterator is used, no range checking can take place!\n\n*Example*\n\n```cpp\nstd::string out;\nout.resize(10);\nemio::result res = emio::format_to(out.begin(), \"Hello {}!\", 42);\nassert(res);\nassert(out == \"Hello 42!\");\n```\n\n`format_to_n(out, n, format_str, ...args) -> result>`\n\n- Formats arguments according to the format string, and writes the result to the output iterator/buffer. At most *n*\n characters are written.\n\n*Example*\n\n```cpp\nstd::string out;\nout.resize(10);\nemio::result> res = \n emio::format_to_n(out.begin(), 7, \"Hello {}!\", 42);\nassert(res)\nassert(res->out == \"Hello 4\");\nassert(res->size == 7);\n```\n\n`formatted_size(format_str, ...args) -> size_t/result`\n\n- Determines the total number of characters in the formatted string by formatting args according to the format string.\n- The return value depends on the type of the format string (valid-only type or not).\n\n*Example*\n\n```cpp\nsize_t size = emio::formatted_size(\"> {}\", 42);\nassert(size == 4);\n```\n\nFor each function there exists a function prefixed with v (e.g. `vformat`) which takes `format_args` instead of a\nformat string and arguments. The types are erased and can be used in non-template functions to reduce build-time, hide\nimplementations and reduce the binary size. **Note:** These type erased functions cannot be used at compile-time.\n\n`format_args` can be created with:\n\n`make_format_args(format_str, ...args) -> internal format_args_storage`\n\n- Returns an object that stores a format string with an array of all arguments to format.\n- Keep in mind that the storage uses reference semantics and does not extend the lifetime of args. It is the\n programmer's responsibility to ensure that args outlive the return value.\n\n*Example*\n\n```cpp\nemio::result internal_info(const emio::format_args& args) {\n emio::memory_buffer buf;\n \n emio::writer out{buf}; // Prefix message.\n EMIO_TRYV(out.write_str(\"INFO: \")); \n \n EMIO_TRYV(emio::vformat_to(out, args));\n log_message(out.view()); // Forward result. \n return emio::success;\n}\n\ntemplate\nvoid log_info(emio::format_string fmt, const Args&...args) {\n emio::result res = internal_info(emio::make_format_args(fmt, args...)); // type-erasing takes place \n res.value(); // Throw on any error.\n}\n\nvoid do_something(int i) {\n log_info(\"Do something started with {}.\", i);\n}\n\nint main() {\n do_something(42); // INFO: Do something started with 42. \n}\n```\n\n### Dynamic format specification\n\nUnlike other libraries, the format specification cannot be changed through extra replacement fields, as it is possible\ne.g. with fmt to dynamically set the precision to 1 with `fmt::format(\"{:.{}f}\", 3.14, 1);`.\n\nWith emio it is possible to dynamically define _width_ and _precision_ through a `format_spec` object which is then\npassed as an argument with the original value to the format function.\n\n`format_spec{.width = , .precision = }`\n\n- If a spec is not defined inside the struct, the spec of the parsed format string will be applied.\n\n*Example*\n\n```cpp\nemio::format_spec spec{.precision = 1};\nemio::format(\"{}\", spec.with(3.141592653)); // 3.1\n```\n\n### Formatter\n\nThere exists formatter for builtin types like bool, char, string, integers, floats, void* and non-scoped enums, ranges\nand tuple like types. Support for other standard types (e.g. chrono duration, optional) is planned.\n\nFor formatting values of pointer-like types, simply use `emio::ptr(p)`.\n\n*Example*\n\n```cpp\nint* value = get();\nemio::format(\"{}\", emio::ptr(value));\n```\n\nUse `is_formattable_v` to check if a type is formattable.\n\nA formatter exists of one optional function `validate` and two mandatory functions `parse` and `format`. If `validate`\nis not present, `parse` must validate the format string.\n\n*Example*\n\n```cpp\nstruct foo {\n int x;\n};\n\ntemplate <>\nclass emio::formatter {\n public:\n /**\n * Optional static function to validate the format string syntax for this type.\n * @note If not present, the parse function is invoked for validation.\n * @param format_rdr The reader over the format string.\n * @return Success if the format string is valid.\n */\n static constexpr result validate(reader& format_rdr) noexcept {\n return format_rdr.read_if_match_char('}');\n }\n\n /**\n * Function to parse the format specs for this type.\n * @param format_rdr The reader over the format string.\n * @return Success if the format string is valid and could be parsed.\n */\n constexpr result parse(reader& format_rdr) noexcept {\n return format_rdr.read_if_match_char('}');\n }\n\n /**\n * Function to format the object of this type according to the parsed format specs.\n * @param out The output writer.\n * @param arg The argument to format.\n * @return Success if the formatting could be done.\n */\n constexpr result format(writer& out, const foo& arg) const noexcept {\n return wtr.write_int(arg.x);\n }\n};\n\nint main() {\n emio::format(\"{}\", foo{42}); // 42 \n}\n```\n\nIt is also possible to reuse existing formatters via inheritance or composition.\n\n*Example*\n\n```cpp\nstruct foo {\n int x;\n};\n\ntemplate <>\nclass emio::formatter : public emio::format {\n public:\n constexpr result format(writer& out, const foo& arg) noexcept {\n return emio::format::format(wtr, arg.x);\n }\n};\n\n\nint main() {\n emio::format(\"{:#x}\", foo{42}); // 0x2a \n}\n```\n\nIf the `validate` (or if absent the `parse`) function is not constexpr, a runtime format strings must be used. The\n`format` function don't need to be constexpr if the formatting shouldn't be done at compile-time.\n\nFor simple type formatting, like formatting an enum class to its underlying integer or to a string, the function\n`format_as` could be provided. The function must be in the same namespace since ADL is used.\n\n*Example*\n\n```cpp\nnamespace foo {\n \nenum class bar {\n foobar,\n barfoo\n};\n\nconstexpr auto format_as(const bar& w) noexcept {\n return static_cast>(w);\n}\n\n}\n```\n\n## Print\n\nIt is possible to directly print to the standard output or other file streams.\n\n`print(format_str, ...args) -> void/result`\n\n- Formats arguments according to the format string, and writes the result to the standard output stream.\n- The return value depends on the type of the format string (valid-only type or not).\n\n*Example*\n\n```cpp\nemio::print(\"{}!\", 42); // Outputs: \"42!\"\n\nemio::result res = emio::print(emio::runtime(\"{}!\"), 42); // Outputs: \"42!\"\nassert(res);\n```\n\n`print(file, format_str, ...args) -> result`\n\n- Formats arguments according to the format string, and writes the result to a file stream.\n\n*Example*\n\n```cpp\nemio::result res = emio::print(stderr, \"{}!\", 42); // Outputs: \"42!\" to stderr\nassert(res);\n```\n\n`println(format_str, ...args) -> void/result`\n\n- Formats arguments according to the format string, and writes the result to the standard output stream with a new line\n at the end.\n- The return value depends on the type of the format string (valid-only type or not).\n\n*Example*\n\n```cpp\nemio::println(\"{}!\", 42); // Outputs: \"42!\" with a line break\n\nemio::result res = emio::println(emio::runtime(\"{}!\"), 42); // Outputs: \"42!\" with a line break\nassert(res);\n```\n\n`println(file, format_str, ...args) -> result`\n\n- Formats arguments according to the format string, and writes the result to a file stream with a new line at the end.\n\n*Example*\n\n```cpp\nemio::result res = emio::println(stderr, \"{}!\", 42); // Outputs: \"42!\" with a line break to stderr\nassert(res);\n```\n\nFor each function there exists a function prefixed with v (e.g. `vprint`) which allow the same functionality as\ne.g. `vformat(...)` does for `format(...)`.\n\n## Scan\n\nThe following functions use a format string syntax which is similar to the format syntax of `format`.\n\nThe grammar for the replacement field is the same. The grammar for the scan specific syntax is as follows:\n\n```sass\nformat_spec ::= [\"#\"][width][type]\n\ntype ::= \"b\" | \"B\" | \"c\" | \"d\" | \"o\" | \"s\" | \"x\" | \"X\"\n```\n\n`#`\n\n- for integral types: the alternate form\n - b/B: `0b` (e.g. 0b10110)\n - d: nothing (e.g. 9825)\n - o: leading `0` (e.g. 057)\n - x/X: `0x` (e.g 0x2fA3)\n- if `#` is present but not the `type`, the base is deduced from the scanned alternate form.\n\n*Example*\n\n```cpp\nint i;\nint j;\nint k;\nint l;\nscan(\"0b101 101 0101 0x101\", \"{:#} {:#} {:#} {:#}\", i, j, k, l);\nassert(i == 0b101);\nassert(j == 101);\nassert(k == 0101);\nassert(l == 0x101);\n```\n\n`width`\n\n- specifies the number of characters to include when parsing an argument\n\n*Example*\n\n```cpp\nint i;\nstd::string_view j;\nint k;\nscan(\"125673\", \"{:2}{:3}{}\", i, j, k);\nassert(i == 12);\nassert(j == \"567\");\nassert(k == 3);\n```\n\n`type`\n\n- for integral types: the base to assume\n - b/B: base 2 (binary)\n - d: base 10 (decimal)\n - o: base 8 (octal)\n - x/X: base 16 (hexadecimal)\n- c for char\n- s for string/string_view\n\n*Example*\n\n```cpp\nint i;\nint j;\nint k;\nint l;\nscan(\"101 101 101 101\", \"{:b} {:d} {:o} {:x}\", i, j, k, l);\nassert(i == 0b101);\nassert(j == 101);\nassert(k == 0101);\nassert(l == 0x101);\n```\n\nThe syntax of the format string is validated at compile-time. If a validation at runtime is required, the string must\nbe wrapped inside a `runtime_string` object. There is a simple helper function for that:\n\n`runtime(string_view) -> runtime_string`\n\nThe API is structured as follows:\n\n`scan(input, format_str, ...args) -> result`\n\n*Example*\n\n```cpp\nint32_t i;\nuint32_t j;\nemio::result res = emio::scan(\"-1,2\", \"{},{}\", i, j);\nassert(res);\nassert(i == -1);\nassert(j == 2);\n```\n\n- Scans the input string for the given arguments according to the format string.\n\n`scan_from(reader, format_str, ...args) -> result`\n\n- Scans the content of the reader for the given arguments according to the format string.\n\n*Example*\n\n```cpp\nint32_t i;\nuint32_t j;\nemio::reader input{\"-1,2...\"};\nemio::result res = emio::scan_from(input, \"{},{}\", i, j);\nassert(res);\nassert(i == -1);\nassert(j == 2);\nassert(input.view_remaining() == \"...\");\n```\n\nFor each function there exists a function prefixed with v (e.g. `vscan`) which takes `scan_args` instead of a format\nstring and arguments. The types are erased and can be used in non-template functions to reduce build-time, hide\nimplementations and reduce the binary size. **Note:** These type erased functions cannot be used at compile-time.\n\n`scan_args` can be created with:\n\n`make_scan_args(format_str, ...args) -> internal scan_args_storage`\n\n- Returns an object that stores a format string with an array of all arguments to scan.\n- Keep in mind that the storage uses reference semantics and does not extend the lifetime of args. It is the\n programmer's responsibility to ensure that args outlive the return value.\n\n### Scanner\n\nThere exists scanner for builtin types like char, string and integers. Support for other types (e.g. float) is planned.\n\nUse `is_scanner_v` to check if a type is scannable.\n\nA scanner exists of one optional function `validate` and two mandatory functions `parse` and `scan`. If `validate`\nis not present, `parse` must validate the format string.\n\n*Example*\n\n```cpp\nstruct foo {\n int x;\n};\n\ntemplate <>\nclass emio::scanner {\n public:\n /**\n * Optional static function to validate the format string syntax for this type.\n * @note If not present, the parse function is invoked for validation.\n * @param format_rdr The reader over the format string.\n * @return Success if the format string is valid.\n */\n static constexpr result validate(reader& format_rdr) noexcept {\n return format_rdr.read_if_match_char('}');\n }\n\n /**\n * Function to parse the format specs for this type.\n * @param format_rdr The reader over the format string.\n * @return Success if the format string is valid and could be parsed.\n */\n constexpr result parse(reader& format_rdr) noexcept {\n return format_rdr.read_if_match_char('}');\n }\n\n /**\n * Function to scan the object of this type according to the parsed format specs.\n * @param input The input reader.\n * @param arg The argument to scan.\n * @return Success if the scanning could be done.\n */\n constexpr result scan(reader& input, foo& arg) const noexcept {\n EMIO_TRYV(input.read_int(arg.x));\n return success;\n }\n};\n\nint main() {\n foo f{};\n emio::scan(\"42\", \"{}\", i); // f.x == 42\n}\n```\n\nIt is also possible to reuse existing scanner via inheritance or composition.\n\n*Example*\n\n```cpp\nstruct foo {\n int x;\n};\n\ntemplate <>\nclass emio::scanner : public emio::scanner {\n public:\n constexpr result scan(reader& input, foo& arg) const noexcept {\n return emio::scanner::scan(input, arg.x);\n }\n};\n\nint main() {\n foo f{};\n emio::scan(\"0x2A\", \"{:x}\", f); // f.x == 42\n}\n```\n\nIf the `validate` (or if absent the `parse`) function is not constexpr, a runtime strings must be used. The `scan`\nfunction don't need to be constexpr if the scanning shouldn't be done at compile-time.\n" }, { "path": "docs/CODE_OF_CONDUCT.md", "content": "# Code of Conduct\n\n* You will be judged by your contributions first, and your sense of humor second.\n* Nobody owes you anything.\n" }, { "path": "docs/CONTRIBUTING.md", "content": "# Contributing\n\n\n\n## Code of Conduct\n\nPlease see the [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) document.\n\n## Getting started\n\nHelpful notes for developers can be found in the [`DEVELOPING.md`](DEVELOPING.md) document.\n" }, { "path": "docs/DESIGN.md", "content": "# Design\n\nThis is a short design overview of *emio*.\n\n**Note:** [fmtlib/fmt](https://github.com/fmtlib/fmt) is an awesome library with great concepts and implementations\nwhich are partly reused in this library. All statements made here by comparing *emio* with *fmt* are only objective and\nshouldn't insult anybody's work.\n\n## Binary footprint\n\nThe API provides a low level API for reading or writing builtin-types and also a high-level API for parsing (TODO) or\nformatting, which reuses the low-level API. Additional, even when using the high-level API, only used types increase the\nbinary size. Furthermore, since the parse or format string can be validated at compile-time, the validation can be\nomitted at runtime.\n\nThis is e.g. different in *fmt*, which doesn't provide a low-level API. Also, *fmt* instantiates all builtin types (e.g.\nbool, int64_t, int128_t, long double...) even if only int32_t should be formatted. Last but not least, the format\nstring is validated at compile-time and runtime.\n\nTake the following code snippet as example which is compiled and statically linked.\n\n```cpp\nstd::string f = emio::format(\"{}\", 1);\n```\n\nIf compiled with *fmt*, **191 kBytes** of flash memory is required. If *emio* is used, only **5 kBytes** are requires.\nThis is **38 times** less! Keep in mind that flash memory of many microcontrollers is between 128 kBytes and 2 MBytes.\n\nThis huge advantage of *emio* comes with a price: *emio* doesn't support all features of *fmt*. But these features are\nlikely not so important for embedded systems. Some missing features are:\n\n- no std::locale support (no internationalization)\n- if a runtime format string is used, validation and parsing happens sequential (performance overhead)\n- some features cannot be API compatible and have to be done differently (e.g. make_format_args requires the format\n string or dynamic width and precision is implemented by a wrapper object)\n\n## Result type\n\nInstead of C++-exceptions, `emio:result` is used for returning and propagating errors. It is similar to `std::expected`,\n`boost::outcome` or Rust's `Result`.\n\n`emio::result` does either holds the expected value of type T or an unexpected error of type `emio::err`. Through\nobserver methods, the state and the value or the error can be visited.\n\n```cpp\nemio::result format(...) noexcept;\n\nemio::result get_first_digit_of_pi() noexcept {\n emio::result pi_as_str = format(\"{}\", M_PI);\n if (pi_as_str) {\n return pi_as_str->at(0);\n }\n return emio::err::invalid_data;\n}\n```\n\nTo reduce the if/else chain, emio provides two simple macros (similar to *boost::outcome*) `EMIO_TRY` and `EMIO_TRYV`.\nThe above function could be rewritten into:\n\n```cpp\nemio::result format(...) noexcept;\n\nemio::result get_first_digit_of_pi() noexcept {\n EMIO_TRY(std::string pi_as_str, format(\"{}\", M_PI));\n return pi_as_str.at(0);\n}\n```\n\nThe biggest advantage of using a result type is that error handling is still possible even if C++-exceptions are\ndisabled. Unlike other libraries like *fmt*, which mostly terminate deep inside their library if an error occurs, the\nresult object propagates the error back to the callee. The drawback is of course the small performance overhead and\nthe explicit handling of the control flow.\n\n## Performance\n\nThe current benchmarks show that the formatting is round about 1.5 - 2 times slower than fmtlib and the performance is\nsimilar to printf (e.g. for integer types). Scanning on the other hand is around twice as fast then scanf. See the\nbenchmark tests inside the CI for more details.\n\n## Class diagram\n\n![class diagram](res/class_diagram.png)\n\nSee also [API](API.md) notes." }, { "path": "docs/DEVELOPING.md", "content": "# Contributing\n\nHere is some wisdom to help you build and test this project as a developer and potential contributor.\n\nThe project template is generated with [cmake-init](https://github.com/friendlyanon/cmake-init).\n\nIf you plan to contribute, please read the [CONTRIBUTING](CONTRIBUTING.md) guide.\n\n## Install\n\nOnly two commands are necessary to install this library on your system.\n\n```sh\ncmake -S . -B build\ncmake --install build\n```\n\n## Developer mode\n\nBuild system targets that are only useful for developers of this project are hidden if the `emio_DEVELOPER_MODE` option\nis disabled. Enabling this option makes tests and other developer targets and options available. Not enabling this\noption means that you are a consumer of this project and thus you have no need for these targets and options.\n\nDeveloper mode is always set to on in CI workflows.\n\n### Presets\n\nThis project makes use of [presets][1] to simplify the process of configuring the project. As a developer, you are\nrecommended to always have the [latest CMake version][2] installed to make use of the latest Quality-of-Life additions.\n\nYou have a few options to pass `emio_DEVELOPER_MODE` to the configure command, but this project prefers to use presets.\n\nAs a developer, you should create a `CMakeUserPresets.json` file at the root of the project:\n\n```json\n{\n \"version\": 2,\n \"cmakeMinimumRequired\": {\n \"major\": 3,\n \"minor\": 14,\n \"patch\": 0\n },\n \"configurePresets\": [\n {\n \"name\": \"dev\",\n \"binaryDir\": \"${sourceDir}/build/dev\",\n \"inherits\": [\"dev-mode\", \"ci-\"],\n \"cacheVariables\": {\n \"CMAKE_BUILD_TYPE\": \"Debug\"\n }\n }\n ],\n \"buildPresets\": [\n {\n \"name\": \"dev\",\n \"configurePreset\": \"dev\",\n \"configuration\": \"Debug\"\n }\n ],\n \"testPresets\": [\n {\n \"name\": \"dev\",\n \"configurePreset\": \"dev\",\n \"configuration\": \"Debug\",\n \"output\": {\n \"outputOnFailure\": true\n }\n }\n ]\n}\n```\n\nYou should replace `` in your newly created presets file with the name of the operating system you have, which may\nbe `win64` or `unix`. You can see what these correspond to in the [`CMakePresets.json`](CMakePresets.json) file.\n\n`CMakeUserPresets.json` is also the perfect place in which you can put all sorts of things that you would otherwise want\nto pass to the configure command in the terminal.\n\n### Configure, build and test\n\nIf you followed the above instructions, then you can configure, build and test the project respectively with the\nfollowing commands from the project root on any operating system with any build system:\n\n```sh\ncmake --preset=dev\ncmake --build --preset=dev\nctest --preset=dev\n```\n\nPlease note that both the build and test command accepts a `-j` flag to specify the number of jobs to use, which should\nideally be specified to the number of threads your CPU has. You may also want to add that to your preset using the\n`jobs` property, see the [presets documentation][1] for more details.\n\n[1]: https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html\n\n[2]: https://cmake.org/download/\n" }, { "path": "docs/res/class_diagram.puml", "content": "@startuml\n\nclass \"scan functions\" << (F,#FF7700) >> {\n scan(input, format_str, args...) -> result\n}\n\nclass \"format functions\" << (F,#FF7700) >> {\n format(format_str, args...) -> result\n}\n\nclass reader\nclass \"std::string_view\" as sv\nreader *-- sv\n\nabstract class buffer\n\nclass memory_buffer\nclass static_buffer\nclass span_buffer\nclass iterator_buffer\n\nbuffer <|-- iterator_buffer\nbuffer <|-- static_buffer\nbuffer <|-- span_buffer\nbuffer <|-- memory_buffer\n\nclass writer\nwriter o-- buffer\n\niterator_buffer o-- \"output iterator\"\n\npackage \"output iterator\" {\n class truncating_iterator\n class \"std::vector::iterator\"\n class \"const char *\"\n}\n\npackage \"contiguous container\" {\n class \"std::array\"\n class \"std::string\" as s2\n class \"std::vector\"\n}\n\nspan_buffer o-- \"contiguous container\"\n\nclass format_string\n\nclass formatter {\n validate(reader&) [0..1]\n parse(reader&)\n format(writer& out, T)\n}\n\nformat_string -.> \"validate & parse\" formatter\n\n\"format functions\" *-.- \"format_string\"\n\"format functions\" -.-> \"writer\" : \"write formatted\\noutput\"\n\"format functions\" -.-> \"reader\" : read format\\nstring\n\"format functions\" -.-> \"formatter\" : parse,\\nformat\n\nclass format_scan_string\n\nclass scanner {\n validate(reader&) [0..1]\n parse(reader&)\n scan(reader& in, T&)\n}\n\nformat_scan_string -.> \"validate & parse\" scanner\n\n\"scan functions\" *-.- \"format_scan_string\"\n\"scan functions\" -.-> \"reader\" : read input & \\nformat string\n\"scan functions\" -.-> \"scanner\" : parse,\\nscan\n\n@enduml" }, { "path": "include/emio/buffer.hpp", "content": "//\n// Copyright (c) 2021 - present, Toni Neubert\n// All rights reserved.\n//\n// For the license information refer to emio.hpp\n\n#pragma once\n\n#include \n#include \n#include \n#include \n\n#if __STDC_HOSTED__\n# include \n#endif\n\n#include \n#include \n\n#include \"detail/ct_vector.hpp\"\n#include \"result.hpp\"\n\nnamespace emio {\n\n/// The default cache size of buffers with an internal cache.\ninline constexpr size_t default_cache_size{128};\n\n/**\n * This class provides the basic API and functionality for receiving a contiguous memory region of chars to write into.\n * @note Use a specific subclass for a concrete instantiation.\n */\nclass buffer {\n public:\n constexpr buffer(const buffer& other) = delete;\n constexpr buffer(buffer&& other) = delete;\n constexpr buffer& operator=(const buffer& other) = delete;\n constexpr buffer& operator=(buffer&& other) = delete;\n virtual constexpr ~buffer() noexcept = default;\n\n /**\n * Returns a write area with the requested size on success.\n * @param size The size the write area should have.\n * @return The write area with the requested size on success or eof if no write area is available.\n */\n constexpr result> get_write_area_of(size_t size) noexcept {\n EMIO_TRY(const std::span area, get_write_area_of_max(size));\n if (area.size() < size) {\n used_ -= area.size();\n return err::eof;\n }\n return area;\n }\n\n /**\n * Returns a write area which may be smaller than the requested size.\n * @note This function should be used to support subclasses with a limited internal buffer.\n * E.g. Writing a long string in chunks.\n * @param size The size the write area should maximal have.\n * @return The write area with the requested size as maximum on success or eof if no write area is available.\n */\n constexpr result> get_write_area_of_max(size_t size) noexcept {\n // If there is enough remaining capacity in the current write area, return it.\n // Otherwise, request a new write area from the concrete implementation.\n // There is a special case for fixed size buffers. Since they cannot grow, they simply return the\n // remaining capacity or EOF, if hitting zero capacity.\n\n const size_t remaining_capacity = area_.size() - used_;\n if (remaining_capacity >= size || fixed_size_ == fixed_size::yes) {\n if (remaining_capacity == 0 && size != 0) {\n return err::eof;\n }\n const size_t max_size = std::min(remaining_capacity, size);\n const std::span area = area_.subspan(used_, max_size);\n used_ += max_size;\n return area;\n }\n EMIO_TRY(const std::span area, request_write_area(used_, size));\n used_ += area.size();\n return area;\n }\n\n protected:\n /// Flag to indicate if the buffer's size is fixed and cannot grow.\n enum class fixed_size : bool { no, yes };\n\n /**\n * Constructs the buffer.\n * @brief fixed Flag to indicate if the buffer's size is fixed and cannot grow.\n */\n constexpr explicit buffer(fixed_size fixed = fixed_size::no) noexcept : fixed_size_{fixed} {}\n\n /**\n * Requests a write area of the given size from a subclass.\n * @param used Already written characters into the current write area.\n * @param size The requested size of a new write area.\n * @return The write area with the requested size as maximum on success or eof if no write area is available.\n */\n virtual constexpr result> request_write_area(const size_t used, const size_t size) noexcept {\n static_cast(used); // Keep params for documentation.\n static_cast(size);\n return err::eof;\n }\n\n /**\n * Sets a new write area in the base class object to use.\n * @param area The new write area.\n */\n constexpr void set_write_area(const std::span area) noexcept {\n area_ = area;\n used_ = 0;\n }\n\n /**\n * Returns the count of written characters of the current hold write area.\n * @return The count.\n */\n [[nodiscard]] constexpr size_t get_used_count() const noexcept {\n return used_;\n }\n\n private:\n fixed_size fixed_size_{fixed_size::no};\n size_t used_{};\n std::span area_{};\n};\n\n/**\n * This class fulfills the buffer API by providing an endless growing buffer.\n * @tparam StorageSize The size of the internal storage used for small buffer optimization.\n */\ntemplate \nclass memory_buffer final : public buffer {\n public:\n /**\n * Constructs and initializes the buffer with the internal storage size.\n */\n constexpr memory_buffer() noexcept : memory_buffer{0} {}\n\n /**\n * Constructs and initializes the buffer with the given capacity.\n * @param capacity The initial capacity.\n */\n constexpr explicit memory_buffer(const size_t capacity) noexcept {\n // Request at least the internal storage size. Should never fail.\n request_write_area(0, std::max(vec_.capacity(), capacity)).value();\n }\n\n constexpr memory_buffer(const memory_buffer& other)\n : buffer{}, used_{other.used_ + other.get_used_count()}, vec_{other.vec_} {\n this->set_write_area({vec_.data() + used_, vec_.data() + vec_.capacity()});\n }\n\n constexpr memory_buffer(memory_buffer&& other) noexcept\n : buffer{}, used_{other.used_ + other.get_used_count()}, vec_{std::move(other).vec_} {\n this->set_write_area({vec_.data() + used_, vec_.data() + vec_.capacity()});\n other.reset();\n }\n\n constexpr memory_buffer& operator=(const memory_buffer& other) {\n if (&other == this) {\n return *this;\n }\n\n used_ = other.used_ + other.get_used_count();\n vec_ = other.vec_;\n this->set_write_area({vec_.data() + used_, vec_.data() + vec_.capacity()});\n return *this;\n }\n\n constexpr memory_buffer& operator=(memory_buffer&& other) noexcept {\n if (&other == this) {\n return *this;\n }\n\n used_ = other.used_ + other.get_used_count();\n vec_ = std::move(other).vec_;\n this->set_write_area({vec_.data() + used_, vec_.data() + vec_.capacity()});\n other.reset();\n return *this;\n }\n\n constexpr ~memory_buffer() override = default;\n\n /**\n * Obtains a view over the underlying string object.\n * @return The view.\n */\n [[nodiscard]] constexpr std::string_view view() const noexcept {\n return {vec_.data(), used_ + this->get_used_count()};\n }\n\n#if __STDC_HOSTED__\n /**\n * Obtains a copy of the underlying string object.\n * @return The string.\n */\n [[nodiscard]] std::string str() const {\n return std::string{view()};\n }\n#endif\n\n /**\n * Resets the buffer's read and write position to the beginning of the internal storage.\n */\n constexpr void reset() noexcept {\n used_ = 0;\n vec_.clear();\n request_write_area(0, vec_.capacity()).value();\n }\n\n /**\n * Returns the number of chars that the buffer has currently allocated space for.\n * @return The capacity.\n */\n [[nodiscard]] constexpr size_t capacity() const noexcept {\n return vec_.capacity();\n }\n\n protected:\n constexpr result> request_write_area(const size_t used, const size_t size) noexcept override {\n const size_t new_size = vec_.size() + size;\n vec_.reserve(new_size);\n used_ += used;\n const std::span area{vec_.data() + used_, size};\n this->set_write_area(area);\n return area;\n }\n\n private:\n size_t used_{};\n detail::ct_vector vec_{};\n};\n\n/**\n * This class fulfills the buffer API by using a span over an contiguous range.\n */\nclass span_buffer : public buffer {\n public:\n /**\n * Constructs and initializes the buffer with an empty span.\n */\n constexpr span_buffer() : buffer{fixed_size::yes} {};\n\n /**\n * Constructs and initializes the buffer with the given span.\n * @param span The span.\n */\n constexpr explicit span_buffer(const std::span span) noexcept : buffer{fixed_size::yes}, span_{span} {\n this->set_write_area(span_);\n }\n\n constexpr span_buffer(const span_buffer& other) : buffer{fixed_size::yes}, span_{other.span_} {\n this->set_write_area(span_);\n get_write_area_of(other.get_used_count()).value();\n }\n\n // NOLINTNEXTLINE(performance-move-constructor-init): optimized move not possible\n constexpr span_buffer(span_buffer&& other) noexcept : span_buffer{std::as_const(other)} {}\n\n constexpr span_buffer& operator=(const span_buffer& other) {\n if (&other == this) {\n return *this;\n }\n\n span_ = other.span_;\n this->set_write_area(span_);\n get_write_area_of(other.get_used_count()).value();\n return *this;\n }\n\n constexpr span_buffer& operator=(span_buffer&& other) noexcept {\n *this = std::as_const(other);\n return *this;\n }\n\n constexpr ~span_buffer() override;\n\n /**\n * Obtains a view over the underlying string object.\n * @return The view.\n */\n [[nodiscard]] constexpr std::string_view view() const noexcept {\n return {span_.data(), this->get_used_count()};\n }\n\n#if __STDC_HOSTED__\n /**\n * Obtains a copy of the underlying string object.\n * @return The string.\n */\n [[nodiscard]] std::string str() const {\n return std::string{view()};\n }\n#endif\n\n /**\n * Resets the buffer's read and write position to the beginning of the span.\n */\n constexpr void reset() noexcept {\n this->set_write_area(span_);\n }\n\n /**\n * Returns the number of chars that the buffer has space for.\n * @return The capacity.\n */\n [[nodiscard]] constexpr size_t capacity() const noexcept {\n return span_.size();\n }\n\n private:\n std::span span_;\n};\n\n// Out-of-line definition because of a GCC bug (93413). Fixed in GCC 13.\ninline constexpr span_buffer::~span_buffer() = default;\n\n/**\n * This class fulfills the buffer API by providing a fixed-size storage.\n * @tparam StorageSize The size of the storage.\n */\ntemplate \nclass static_buffer final : private std::array, public span_buffer {\n public:\n /**\n * Constructs and initializes the buffer with the storage.\n */\n constexpr static_buffer() noexcept : span_buffer{std::span{*this}} {}\n\n constexpr static_buffer(const static_buffer& other) : static_buffer() {\n const std::span area = get_write_area_of(other.get_used_count()).value();\n detail::copy_n(&*other.begin(), area.size(), area.data());\n }\n\n // NOLINTNEXTLINE(performance-move-constructor-init): optimized move not possible\n constexpr static_buffer(static_buffer&& other) noexcept : static_buffer(std::as_const(other)) {}\n\n constexpr static_buffer& operator=(const static_buffer& other) {\n if (&other == this) {\n return *this;\n }\n\n set_write_area(std::span{*this});\n const std::span area = get_write_area_of(other.get_used_count()).value();\n detail::copy_n(&*other.begin(), area.size(), area.data());\n return *this;\n }\n\n constexpr static_buffer& operator=(static_buffer&& other) noexcept {\n *this = std::as_const(other);\n return *this;\n }\n\n constexpr ~static_buffer() override = default;\n\n // Note: We inherit from std::array to put the storage lifetime before span_buffer.\n // Clang will otherwise complain if the storage is a member variable and used during compile-time.\n};\n\nnamespace detail {\n\n// Extracts a reference to the container from back_insert_iterator.\ntemplate \nContainer& get_container(std::back_insert_iterator it) noexcept {\n using bi_iterator = std::back_insert_iterator;\n struct accessor : bi_iterator {\n accessor(bi_iterator iter) : bi_iterator(iter) {}\n using bi_iterator::container;\n };\n return *accessor{it}.container;\n}\n\n// Helper struct to get the value type of different iterators.\ntemplate \nstruct get_value_type {\n using type = typename std::iterator_traits::value_type;\n};\n\ntemplate \nstruct get_value_type> {\n using type = typename Container::value_type;\n};\n\n#if __STDC_HOSTED__\ntemplate \nstruct get_value_type> {\n using type = Char;\n};\n#endif\n\ntemplate \nusing get_value_type_t = typename get_value_type::type;\n\ntemplate \nconstexpr auto copy_str(InputIt it, InputIt end, OutputIt out) -> OutputIt {\n while (it != end) {\n *out++ = static_cast(*it++);\n }\n return out;\n}\n\n} // namespace detail\n\n/**\n * This class template is used to create a buffer around different iterator types.\n */\ntemplate \nclass iterator_buffer;\n\n/**\n * This class fulfills the buffer API by using an output iterator and an internal cache.\n * @tparam Iterator The output iterator type.\n * @tparam CacheSize The size of the internal cache.\n */\ntemplate \n requires(std::input_or_output_iterator &&\n std::output_iterator>)\nclass iterator_buffer final : public buffer {\n public:\n /**\n * Constructs and initializes the buffer with the given output iterator.\n * @param it The output iterator.\n */\n // NOLINTNEXTLINE(cppcoreguidelines-pro-type-member-init): cache_ can be left uninitialized\n constexpr explicit iterator_buffer(Iterator it) noexcept : it_{it} {\n this->set_write_area(cache_);\n }\n\n iterator_buffer(const iterator_buffer&) = delete;\n iterator_buffer(iterator_buffer&&) = delete;\n iterator_buffer& operator=(const iterator_buffer&) = delete;\n iterator_buffer& operator=(iterator_buffer&&) = delete;\n ~iterator_buffer() override = default;\n\n /**\n * Flushes the internal cache to the output iterator.\n * @return Always succeeds.\n */\n constexpr result flush() noexcept {\n it_ = detail::copy_str(cache_.data(), cache_.data() + this->get_used_count(), it_);\n this->set_write_area(cache_);\n return success;\n }\n\n /**\n * Flushes and returns the output iterator at the next write position.\n * @return The output iterator.\n */\n constexpr Iterator out() noexcept {\n flush().assume_value(); // Will never fail.\n return it_;\n }\n\n protected:\n constexpr result> request_write_area(const size_t /*used*/, const size_t size) noexcept override {\n flush().assume_value(); // Will never fail.\n const std::span area{cache_};\n this->set_write_area(area);\n if (size > cache_.size()) {\n return area;\n }\n return area.subspan(0, size);\n }\n\n private:\n Iterator it_;\n std::array cache_;\n};\n\n/**\n * This class fulfills the buffer API by using an output pointer.\n * @tparam Iterator The output iterator type.\n */\ntemplate \n requires(std::input_or_output_iterator &&\n std::output_iterator>)\nclass iterator_buffer final : public buffer {\n public:\n /**\n * Constructs and initializes the buffer with the given output pointer.\n * @param ptr The output pointer.\n */\n constexpr explicit iterator_buffer(OutputPtr* ptr) noexcept : ptr_{ptr} {\n this->set_write_area({ptr, std::numeric_limits::max()});\n }\n\n iterator_buffer(const iterator_buffer&) = delete;\n iterator_buffer(iterator_buffer&&) = delete;\n iterator_buffer& operator=(const iterator_buffer&) = delete;\n iterator_buffer& operator=(iterator_buffer&&) = delete;\n ~iterator_buffer() override = default;\n\n /**\n * Does nothing. Kept for uniformity with other iterator_buffer implementations.\n * @return Always succeeds.\n */\n constexpr result flush() noexcept {\n // Nothing.\n return success;\n }\n\n /**\n * Returns the output pointer at the next write position.\n * @return The output pointer.\n */\n constexpr OutputPtr* out() noexcept {\n return ptr_ + this->get_used_count();\n }\n\n private:\n OutputPtr* ptr_;\n};\n\n/**\n * This class fulfills the buffer API by using the container of an contiguous back-insert iterator.\n * @tparam Container The container type of the back-insert iterator.\n * @tparam Capacity The minimum initial requested capacity of the container.\n */\ntemplate \n requires std::contiguous_iterator\nclass iterator_buffer, Capacity> final : public buffer {\n public:\n /**\n * Constructs and initializes the buffer with the given back-insert iterator.\n * @param it The back-insert iterator.\n */\n constexpr explicit iterator_buffer(std::back_insert_iterator it) noexcept\n : container_{detail::get_container(it)} {\n request_write_area(0, std::min(container_.capacity(), Capacity)).value();\n }\n\n iterator_buffer(const iterator_buffer&) = delete;\n iterator_buffer(iterator_buffer&&) = delete;\n iterator_buffer& operator=(const iterator_buffer&) = delete;\n iterator_buffer& operator=(iterator_buffer&&) = delete;\n ~iterator_buffer() override = default;\n\n /**\n * Flushes the back-insert iterator by adjusting the size.\n * @return Always succeeds.\n */\n constexpr result flush() noexcept {\n container_.resize(used_ + this->get_used_count());\n return success;\n }\n\n /**\n * Flushes and returns the back-insert iterator.\n * @return The back-insert iterator.\n */\n constexpr std::back_insert_iterator out() noexcept {\n flush().assume_value(); // Will never fail.\n return std::back_inserter(container_);\n }\n\n protected:\n constexpr result> request_write_area(const size_t used, const size_t size) noexcept override {\n const size_t new_size = container_.size() + size;\n container_.resize(new_size);\n used_ += used;\n const std::span area{container_.data() + used_, new_size};\n this->set_write_area(area);\n return area.subspan(0, size);\n }\n\n private:\n size_t used_{};\n Container& container_;\n};\n\ntemplate \niterator_buffer(Iterator&&) -> iterator_buffer>;\n\n/**\n * This class fulfills the buffer API by using a file stream and an internal cache.\n * @tparam CacheSize The size of the internal cache.\n */\ntemplate \nclass file_buffer final : public buffer {\n public:\n /**\n * Constructs and initializes the buffer with the given file stream.\n * @param file The file stream.\n */\n // NOLINTNEXTLINE(cppcoreguidelines-pro-type-member-init): cache_ can be left uninitialized\n constexpr explicit file_buffer(std::FILE* file) noexcept : file_{file} {\n this->set_write_area(cache_);\n }\n\n file_buffer(const file_buffer&) = delete;\n file_buffer(file_buffer&&) = delete;\n file_buffer& operator=(const file_buffer&) = delete;\n file_buffer& operator=(file_buffer&&) = delete;\n ~file_buffer() override = default;\n\n /**\n * Flushes the internal cache to the file stream.\n * @note Does not flush the file stream itself!\n */\n result flush() noexcept {\n const size_t written = std::fwrite(cache_.data(), sizeof(char), this->get_used_count(), file_);\n if (written != this->get_used_count()) {\n return err::eof;\n }\n this->set_write_area(cache_);\n return success;\n }\n\n /**\n * Resets the buffer's read and write position to the beginning of the file stream.\n */\n constexpr void reset() noexcept {\n this->set_write_area(cache_);\n std::fseek(file_, 0, SEEK_SET);\n }\n\n protected:\n result> request_write_area(const size_t /*used*/, const size_t size) noexcept override {\n EMIO_TRYV(flush());\n const std::span area{cache_};\n this->set_write_area(area);\n if (size > cache_.size()) {\n return area;\n }\n return area.subspan(0, size);\n }\n\n private:\n std::FILE* file_;\n std::array cache_;\n};\n\n/**\n * This class fulfills the buffer API by using a primary buffer and an internal cache.\n * Only a limited amount of characters is written to the primary buffer. The remaining characters are truncated.\n * @tparam CacheSize The size of the internal cache.\n */\ntemplate \nclass truncating_buffer final : public buffer {\n public:\n /**\n * Constructs and initializes the buffer with the given primary buffer and limit.\n * @param primary The primary buffer.\n * @param limit The limit.\n */\n // NOLINTNEXTLINE(cppcoreguidelines-pro-type-member-init): cache_ can be left uninitialized.\n constexpr explicit truncating_buffer(buffer& primary, size_t limit) : primary_{primary}, limit_{limit} {\n this->set_write_area(cache_);\n }\n\n truncating_buffer(const truncating_buffer&) = delete;\n truncating_buffer(truncating_buffer&&) = delete;\n truncating_buffer& operator=(const truncating_buffer&) = delete;\n truncating_buffer& operator=(truncating_buffer&&) = delete;\n constexpr ~truncating_buffer() noexcept override = default;\n\n /**\n * Returns the count of the total (not truncated) written characters.\n * @return The count.\n */\n [[nodiscard]] constexpr size_t count() const noexcept {\n return used_ + this->get_used_count();\n }\n\n /**\n * Flushes the internal cache to the primary buffer.\n */\n [[nodiscard]] constexpr result flush() noexcept {\n size_t bytes_to_write = get_used_count();\n used_ += bytes_to_write;\n while (written_ < limit_ && bytes_to_write > 0) {\n EMIO_TRY(const auto area, primary_.get_write_area_of_max(std::min(bytes_to_write, limit_ - written_)));\n detail::copy_n(detail::begin(cache_), area.size(), area.data());\n written_ += area.size();\n bytes_to_write -= area.size();\n }\n this->set_write_area(cache_);\n return success;\n }\n\n protected:\n constexpr result> request_write_area(const size_t /*used*/, const size_t size) noexcept override {\n EMIO_TRYV(flush());\n const std::span area{cache_};\n this->set_write_area(area);\n if (size > cache_.size()) {\n return area;\n }\n return area.subspan(0, size);\n }\n\n private:\n buffer& primary_;\n size_t limit_;\n size_t written_{};\n size_t used_{};\n std::array cache_;\n};\n\nnamespace detail {\n\n/**\n * A buffer that counts the number of characters written. Discards the output.\n * @tparam CacheSize The size of the internal cache.\n */\n// NOLINTNEXTLINE(cppcoreguidelines-pro-type-member-init): cache_ can be left uninitialized.\ntemplate \nclass counting_buffer final : public buffer {\n public:\n // NOLINTNEXTLINE(cppcoreguidelines-pro-type-member-init): cache_ can be left uninitialized.\n constexpr counting_buffer() noexcept = default;\n constexpr counting_buffer(const counting_buffer&) = delete;\n constexpr counting_buffer(counting_buffer&&) noexcept = delete;\n constexpr counting_buffer& operator=(const counting_buffer&) = delete;\n constexpr counting_buffer& operator=(counting_buffer&&) noexcept = delete;\n constexpr ~counting_buffer() noexcept override = default;\n\n /**\n * Calculates the number of Char's that were written.\n * @return The number of Char's.\n */\n [[nodiscard]] constexpr size_t count() const noexcept {\n return used_ + this->get_used_count();\n }\n\n protected:\n constexpr result> request_write_area(const size_t used, const size_t size) noexcept override {\n used_ += used;\n const std::span area{cache_};\n this->set_write_area(area);\n if (size > cache_.size()) {\n return area;\n }\n return area.subspan(0, size);\n }\n\n private:\n size_t used_{};\n std::array cache_;\n};\n\n} // namespace detail\n\n} // namespace emio\n" }, { "path": "include/emio/detail/args.hpp", "content": "//\n// Copyright (c) 2023 - present, Toni Neubert\n// All rights reserved.\n//\n// For the license information refer to emio.hpp\n\n#pragma once\n\n#include \n#include \n#include \n\n#include \"validated_string_storage.hpp\"\n\nnamespace emio::detail {\n\n/**\n * Type erased argument to validate.\n */\ntemplate