first commit

.clang-format

@@ -0,0 +1,31 @@
+---
+# We use clang-format to keep C++ code styling consistent
+# The rules for our specific style are delineated here
+AccessModifierOffset: "-4"
+AlignConsecutiveMacros: "true"
+# AlignConsecutiveAssignments: "true"
+AlignConsecutiveDeclarations: "true"
+AlignEscapedNewlines: Left
+AllowShortBlocksOnASingleLine: "true"
+AllowShortCaseLabelsOnASingleLine: "true"
+AllowShortFunctionsOnASingleLine: All
+AllowShortIfStatementsOnASingleLine: WithoutElse
+AllowShortLoopsOnASingleLine: "true"
+AlwaysBreakAfterReturnType: TopLevelDefinitions
+AlwaysBreakTemplateDeclarations: "Yes"
+BreakBeforeBraces: Stroustrup
+BreakBeforeTernaryOperators: "true"
+BreakConstructorInitializers: AfterColon
+BreakInheritanceList: AfterColon
+ColumnLimit: 120
+CompactNamespaces: "true"
+FixNamespaceComments: "true"
+IncludeBlocks: Regroup
+IndentCaseLabels: "true"
+IndentPPDirectives: BeforeHash
+IndentWidth: "4"
+PointerAlignment: Left
+NamespaceIndentation: Inner
+SortIncludes: false
+SortUsingDeclarations: "true"
+SpaceAfterTemplateKeyword: "false"

.clang-tidy

@@ -0,0 +1,58 @@
+Checks: "*,
+        -abseil-*,
+        -altera-*,
+        -android-*,
+        -bugprone-*,
+        -cert-err58-cpp,
+        -concurrency-mt-unsafe,
+        -cppcoreguidelines-avoid-const-or-ref-data-members,
+        -cppcoreguidelines-avoid-do-while,
+        -cppcoreguidelines-avoid-goto,
+        -cppcoreguidelines-avoid-magic-numbers,
+        -cppcoreguidelines-avoid-non-const-global-variables,
+        -cppcoreguidelines-macro-usage,
+        -cppcoreguidelines-non-private-member-variables-in-classes,
+        -cppcoreguidelines-pro-bounds-array-to-pointer-decay,
+        -cppcoreguidelines-pro-bounds-constant-array-index,
+        -cppcoreguidelines-pro-bounds-pointer-arithmetic,
+        -cppcoreguidelines-pro-type-reinterpret-cast,
+        -cppcoreguidelines-pro-type-union-access,
+        -cppcoreguidelines-virtual-class-destructor,
+        -fuchsia-*,
+        -google-*,
+        -hicpp-avoid-goto,
+        -hicpp-explicit-conversions,
+        -hicpp-function-size,
+        -hicpp-no-array-decay,
+        -hicpp-no-assembler,
+        -hicpp-signed-bitwise,
+        -hicpp-uppercase-literal-suffix,
+        -llvm-*,
+        -llvmlibc-*,
+        -misc-confusable-identifiers,
+        -misc-no-recursion,
+        -misc-non-private-member-variables-in-classes,
+        -modernize-concat-nested-namespaces,
+        -modernize-use-nodiscard,
+        -modernize-use-trailing-return-type,
+        -readability-avoid-const-params-in-decls,
+        -readability-else-after-return,
+        -readability-function-cognitive-complexity,
+        -readability-function-size,
+        -readability-identifier-length,
+        -readability-magic-numbers,
+        -readability-redundant-access-specifiers,
+        -readability-simplify-boolean-expr,
+        -readability-static-accessed-through-instance,
+        -readability-uppercase-literal-suffix',
+        -zircon-*"
+
+CheckOptions:
+  - key: hicpp-special-member-functions.AllowSoleDefaultDtor
+    value: 1
+
+WarningsAsErrors: ''
+
+HeaderFilterRegex: ''
+
+FormatStyle:     none

.editorconfig

@@ -0,0 +1,6 @@
+root = true
+
+[*.adoc]
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true

.github/workflows/archive.yml

@@ -0,0 +1,56 @@
+# Creates & releases a minimal archive of this library's core files and directories.
+# This is useful for the standard CMake module `FetchContent` and friends.
+name: Release library archive
+
+# The files & directories we archive and the name for the archive.
+# The git tag for the release is either 'current' or the relase tag like '2.1.2'
+env:
+    archive_content: LICENSE CMakeLists.txt include
+    archive_name: ${{ github.event.repository.name }}.zip
+    archive_tag: ${{github.ref == 'refs/heads/main' && 'current' || github.ref}}
+
+# We may overwrite the $archive_tag so need write permissions
+permissions:
+    contents: write
+
+# When is the workflow run?
+on:
+    # Any push to the main branch that changes the content of the archive.
+    # TODO: Perhaps we can use the $archive_content variable here?
+    push:
+        branches:
+            - main
+        paths:
+            - "LICENSE"
+            - "CMakeLists.txt"
+            - "include/**"
+    # Any formal release
+    release:
+        types: [published]
+
+    # You can trigger the workflow manually (handy to debug the workflow).
+    workflow_dispatch:
+
+# There is just a single job in the workflow
+jobs:
+    archive:
+        name: Create and release an archive of the library's core files and directories.
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+
+            - name: Zip the important files and directories
+              run: |
+                  echo "Creating archive '$archive_name' from: '$archive_content' ..."
+                  echo "The git ref is:  '${{github.ref}}'"
+                  echo "The release tag: '${{env.archive_tag}}'"
+                  zip -r $archive_name $archive_content
+
+            - name: Upload the archive to a release
+              uses: svenstaro/upload-release-action@v2
+              with:
+                  repo_token: ${{secrets.GITHUB_TOKEN}}
+                  file: ${{env.archive_name}}
+                  tag: ${{env.archive_tag}}
+                  overwrite: true
+                  body: "Latest minimal version of the library for CMake's module `FetchContent` and friends."

.gitignore

@@ -0,0 +1,27 @@
+# Specify up the folders/files that should *never* go into the git repository.
+
+# The Mac Finder produces a metadata file that is noise.
+.DS_Store
+
+# My specific Visual Code setup is only useful to me.
+.vscode/
+
+# Visual Studio puts artifacts into an out directory.
+out/
+
+# Our CMake setup puts artifacts into "build" folders.
+build*
+build*/
+
+# Some local scratch files are kept in private directories that need not go into git.
+private/
+
+# The documentation website uses Quarto and we don't need to version its cache or what it builds.
+.quarto/
+_site/
+
+# Jupyter checkpoint directories need not go into git
+.ipynb_checkpoints/.
+
+# Generally don't want to check Node.js modules into the remote repo -- just the recipes for installing them.
+node_modules/

CMakeLists.txt

@@ -0,0 +1,43 @@
+cmake_minimum_required(VERSION 3.25)
+
+# Our project
+project(utilities DESCRIPTION "C++ Utilities Library" LANGUAGES CXX)
+
+# Add a target for the "library" we are building (it is header-only, hence INTERFACE).
+# Also add the usual alias for this library name.
+add_library(utilities INTERFACE)
+add_library(utilities::utilities ALIAS utilities)
+
+# We use C++20 features
+target_compile_features(utilities INTERFACE cxx_std_20)
+
+# Where to find the project headers (e.g., how to resolve `#include "utilities/utilities.h"`).
+target_include_directories(utilities INTERFACE
+    $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/include/>
+    $<INSTALL_INTERFACE:include/>)
+
+# That's it unless we are developing the library instead of just using it!
+# If we are developing the library, then we go ahead and create targets for the executables in the examples/ directory
+if (PROJECT_IS_TOP_LEVEL)
+
+    # Append our local directory of CMake modules to the default ones searched by CMake
+    list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake")
+
+    # Prevent in-source builds for the example programs
+    include(disable_in_source_builds)
+    disable_in_source_builds()
+
+    # Make the compiler issue warnings for "bad" code, etc.
+    include(compiler_init)
+    compiler_init(utilities)
+
+    # For neatness, we want all the example executables to go in build/bin/.
+    include(GNUInstallDirs)
+    set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/${CMAKE_INSTALL_BINDIR}")
+
+    # Finally, we walk through the examples directory and build a target for each .cpp file with appropriate linkage.
+    # We have a CMake function that makes that traversal straightforward.
+    include(add_executables)
+    add_executables(examples utilities::utilities)
+
+endif()

LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2024 Nessan Fitzmaurice 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,50 @@
+# README
+
+The `utilities` library is a small collection of C++ classes, functions, and macros.
+
+It is header-only, so there is nothing to compile or link.
+Moreover, you can use any header file in this library on a standalone basis, as there are no interdependencies.
+
+## Available Facilities
+
+| Header File   | Purpose                                                                                                                                                          |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `check.h`     | Defines some `assert`-type macros that improve on the standard one in various ways. In particular, you can add a message explaining why a check failed.          |
+| `format.h`    | Functionality that connects any class with a `to_string()` method to `std::format`.                                                                              |
+| `print.h`     | Workaround for any compiler that hasn't yet implemented `std::print`.                                                                                            |
+| `macros.h`    | Defines macros often used in test and example programs. <br/>It also defines a mechanism that lets you overload a macro based on the number of passed arguments. |
+| `log.h`       | Some very simple logging macros.                                                                                                                                 |
+| `stopwatch.h` | Defines the `utilities::stopwatch` class you can use to time blocks of code.                                                                                     |
+| `stream.h`    | Defines some functions to read lines from a file, ignoring comments and allowing for continuation lines.                                                         |
+| `string.h`    | Defines several useful string functions (turn them to upper-case, trim white space, etc).                                                                        |
+| `thousands.h` | Defines functions to imbue output streams and locales with commas. This makes it easier to read large numbers–for example, printing 23000.56 as 23,000.56.       |
+| `type.h`      | Defines the function `utilities::type` which produces a string for a type.                                                                                       |
+| `utilities.h` | This “include-the-lot” header pulls in all the other files above.                                                                                                |
+
+## Installation
+
+This library is header-only, so there is nothing to compile & link. Drop the small `utilities` header directory somewhere convenient. You can even use any single header file on a stand-alone basis.
+
+Alternatively, if you are using `CMake`, you can use the standard `FetchContent` module by adding a few lines to your project's `CMakeLists.txt` file:
+
+```cmake
+include(FetchContent)
+FetchContent_Declare(utilities URL https://github.com/nessan/utilities/releases/download/current/utilities.zip)
+FetchContent_MakeAvailable(utilities)
+```
+
+This command downloads and unpacks an archive of the current version of `utilities` to your project's build folder. You can then add a dependency on `utilities::utilities`, a `CMake` alias for `utilities`. `FetchContent` will automatically ensure the build system knows where to find the downloaded header files and any needed compiler flags.
+
+## Documentation
+
+You can read the project's documentation [here](https://nessan.github.io/utilities/). \
+We used the static website generator [Quarto](https://quarto.org) to construct the documentation site.
+
+### Contact
+
+You can contact me by email [here](mailto:[email protected]).
+
+### Copyright and License
+
+Copyright (c) 2022-present Nessan Fitzmaurice. \
+You can use this software under the [MIT license](https://opensource.org/license/mit).