✨ Add usage test

Problem:
- There is no usage test that includes all the headers.
- There is no usage test for freestanding implementations.

Solution:
- Add a usage test.
- Fix some usage in `atomic_bitset`. `::atomic` is a namespace in the `conc`
  library but `atomic` is a class template in `stdx`.

Note:
- Some functionality is not yet available for freestanding implementations, viz:
  - `function_traits` and `for_each_n_args` use `std::function`
  - `ct_format` and `static_assert` use libfmt

Author: elbeno

.github/workflows/usage_test.yml

@@ -0,0 +1,45 @@
+name: Usage Test
+permissions: read-all
+
+on:
+  workflow_dispatch:
+  merge_group:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+env:
+  DEBIAN_FRONTEND: noninteractive
+  USER_LLVM_VERSION: 14
+  USER_CMAKE_VERSION: 3.25
+
+jobs:
+  usage_test:
+    runs-on: ${{ github.repository_owner == 'intel' && 'intel-' || '' }}ubuntu-22.04
+    strategy:
+      fail-fast: false
+      matrix:
+        cpp_implementation: [FREESTANDING, HOSTED]
+
+    steps:
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+
+      - name: Install compiler
+        run: sudo apt update && sudo apt-get install -y clang-${{env.USER_LLVM_VERSION}}
+
+      - name: Install cmake
+        run: |
+          pip3 install --upgrade pip
+          pip3 install --force cmake==${{env.USER_CMAKE_VERSION}}
+
+      - name: Configure CMake
+        working-directory: ${{github.workspace}}/usage_test
+        env:
+          CC: "/usr/lib/llvm-${{env.USER_LLVM_VERSION}}/bin/clang"
+          CXX: "/usr/lib/llvm-${{env.USER_LLVM_VERSION}}/bin/clang++"
+        run: ~/.local/bin/cmake -B build -DCPP_IMPLEMENTATION=${{matrix.cpp_implementation}}
+
+      - name: Build
+        working-directory: ${{github.workspace}}/usage_test
+        run: ~/.local/bin/cmake --build build

.gitignore

@@ -1,4 +1,4 @@
-/build
+build/
 /cmake-build-*
 /venv
 /.vscode

docs/ct_format.adoc

@@ -9,6 +9,8 @@ provides `ct_format`, a compile-time function for formatting strings.
 NOTE: Like xref:ct_string.adoc#_ct_string_hpp[`ct_string`], `ct_format` is
 available only in C++20 and later.
 
+IMPORTANT: `ct_format` is not yet available on freestanding implementations.
+
 The format string is provided as a template argument, and the arguments to be
 formatted as regular function arguments.
 

docs/for_each_n_args.adoc

@@ -5,6 +5,8 @@ https://github.com/intel/cpp-std-extensions/blob/main/include/stdx/for_each_n_ar
 provides a method for calling a function (or other callable) with batches of
 arguments from a parameter pack.
 
+IMPORTANT: `for_each_n_args` is not yet available on freestanding implementations.
+
 Examples:
 [source,cpp]
 ----

docs/function_traits.adoc

@@ -5,6 +5,8 @@ https://github.com/intel/cpp-std-extensions/blob/main/include/stdx/function_trai
 contains type traits for introspecting function signatures. It works with
 functions, lambda expressions, and classes with `operator()`.
 
+IMPORTANT: Function traits are not yet available on freestanding implementations.
+
 Examples:
 [source,cpp]
 ----

docs/static_assert.adoc

@@ -3,6 +3,8 @@
 
 `STATIC_ASSERT` is a way to produce compile-time errors using formatted strings.
 
+IMPORTANT: `STATIC_ASSERT` is not yet available on freestanding implementations.
+
 [source,cpp]
 ----
 template <typename T>

include/stdx/atomic_bitset.hpp

@@ -25,8 +25,8 @@ template <auto Size,
 class atomic_bitset {
     constexpr static std::size_t N = to_underlying(Size);
 
-    using elem_t = atomic::atomic_type_t<StorageElem>;
-    constexpr static auto alignment = atomic::alignment_of<StorageElem>;
+    using elem_t = ::atomic::atomic_type_t<StorageElem>;
+    constexpr static auto alignment = ::atomic::alignment_of<StorageElem>;
 
     static_assert(std::is_unsigned_v<elem_t>,
                   "Storage element for atomic_bitset must be an unsigned type");
@@ -39,7 +39,7 @@ class atomic_bitset {
 
     constexpr static auto mask = bit_mask<elem_t, N - 1>();
     auto salient_value(std::memory_order order) const -> elem_t {
-        return atomic::load(storage, order) & mask;
+        return ::atomic::load(storage, order) & mask;
     }
 
     [[nodiscard]] constexpr static auto value_from_string(std::string_view str,
@@ -114,7 +114,7 @@ class atomic_bitset {
     }
     auto store(bitset_t b,
                std::memory_order order = std::memory_order_seq_cst) {
-        atomic::store(storage, b.template to<elem_t>(), order);
+        ::atomic::store(storage, b.template to<elem_t>(), order);
     }
 
     constexpr static std::integral_constant<std::size_t, N> size{};
@@ -128,10 +128,10 @@ class atomic_bitset {
              std::memory_order order = std::memory_order_seq_cst) -> bitset_t {
         auto const pos = static_cast<std::size_t>(to_underlying(idx));
         if (value) {
-            return bitset_t{atomic::fetch_or(
+            return bitset_t{::atomic::fetch_or(
                 storage, static_cast<elem_t>(bit << pos), order)};
         }
-        return bitset_t{atomic::fetch_and(
+        return bitset_t{::atomic::fetch_and(
             storage, static_cast<elem_t>(~(bit << pos)), order)};
     }
 
@@ -141,9 +141,9 @@ class atomic_bitset {
         auto const m = to_underlying(msb);
         auto const shifted_value = bit_mask<elem_t>(m, l);
         if (value) {
-            return bitset_t{atomic::fetch_or(storage, shifted_value, order)};
+            return bitset_t{::atomic::fetch_or(storage, shifted_value, order)};
         }
-        return bitset_t{atomic::fetch_and(storage, ~shifted_value, order)};
+        return bitset_t{::atomic::fetch_and(storage, ~shifted_value, order)};
     }
 
     auto set(lsb_t lsb, length_t len, bool value = true,
@@ -155,15 +155,15 @@ class atomic_bitset {
 
     auto set(std::memory_order order = std::memory_order_seq_cst) LIFETIMEBOUND
         -> atomic_bitset & {
-        atomic::store(storage, mask, order);
+        ::atomic::store(storage, mask, order);
         return *this;
     }
 
     template <typename T>
     auto reset(T idx, std::memory_order order = std::memory_order_seq_cst)
         -> bitset_t {
         auto const pos = static_cast<std::size_t>(to_underlying(idx));
-        return bitset_t{atomic::fetch_and(
+        return bitset_t{::atomic::fetch_and(
             storage, static_cast<elem_t>(~(bit << pos)), order)};
     }
 
@@ -173,7 +173,7 @@ class atomic_bitset {
         auto const l = to_underlying(lsb);
         auto const m = to_underlying(msb);
         auto const shifted_value = bit_mask<elem_t>(m, l);
-        return bitset_t{atomic::fetch_and(storage, ~shifted_value, order)};
+        return bitset_t{::atomic::fetch_and(storage, ~shifted_value, order)};
     }
 
     auto reset(lsb_t lsb, length_t len,
@@ -187,24 +187,24 @@ class atomic_bitset {
     auto
     reset(std::memory_order order = std::memory_order_seq_cst) LIFETIMEBOUND
         -> atomic_bitset & {
-        atomic::store(storage, elem_t{}, order);
+        ::atomic::store(storage, elem_t{}, order);
         return *this;
     }
 
     template <typename T>
     auto flip(T idx, std::memory_order order = std::memory_order_seq_cst)
         -> bitset_t {
         auto const pos = static_cast<std::size_t>(to_underlying(idx));
-        return bitset_t{
-            atomic::fetch_xor(storage, static_cast<elem_t>(bit << pos), order)};
+        return bitset_t{::atomic::fetch_xor(
+            storage, static_cast<elem_t>(bit << pos), order)};
     }
 
     auto flip(lsb_t lsb, msb_t msb,
               std::memory_order order = std::memory_order_seq_cst) -> bitset_t {
         auto const l = to_underlying(lsb);
         auto const m = to_underlying(msb);
         auto const shifted_value = bit_mask<elem_t>(m, l);
-        return bitset_t{atomic::fetch_xor(storage, shifted_value, order)};
+        return bitset_t{::atomic::fetch_xor(storage, shifted_value, order)};
     }
 
     auto flip(lsb_t lsb, length_t len,
@@ -215,7 +215,7 @@ class atomic_bitset {
     }
 
     auto flip(std::memory_order order = std::memory_order_seq_cst) -> bitset_t {
-        return bitset_t{atomic::fetch_xor(storage, mask, order)};
+        return bitset_t{::atomic::fetch_xor(storage, mask, order)};
     }
 
     [[nodiscard]] auto

usage_test/CMakeLists.txt

@@ -0,0 +1,17 @@
+if(DEFINED ENV{USER_CMAKE_VERSION})
+    message(STATUS "Required minimum cmake version: $ENV{USER_CMAKE_VERSION}")
+    cmake_minimum_required(VERSION $ENV{USER_CMAKE_VERSION})
+endif()
+message(STATUS "Actual cmake version: ${CMAKE_VERSION}")
+
+project(stdx_usage)
+
+include(${CMAKE_CURRENT_LIST_DIR}/../cmake/get_cpm.cmake)
+cpmaddpackage(NAME stdx SOURCE_DIR "${CMAKE_CURRENT_LIST_DIR}/.." GIT_TAG HEAD)
+
+add_executable(app main.cpp)
+target_link_libraries(app PRIVATE stdx)
+if(CPP_IMPLEMENTATION STREQUAL "FREESTANDING")
+    target_compile_definitions(app PRIVATE SIMULATE_FREESTANDING)
+    target_compile_options(app PRIVATE -ffreestanding)
+endif()

usage_test/main.cpp

@@ -0,0 +1,53 @@
+#include <stdx/algorithm.hpp>
+#include <stdx/atomic.hpp>
+#include <stdx/atomic_bitset.hpp>
+#include <stdx/bit.hpp>
+#include <stdx/bitset.hpp>
+#include <stdx/byterator.hpp>
+#include <stdx/cached.hpp>
+#include <stdx/compiler.hpp>
+#include <stdx/concepts.hpp>
+#include <stdx/ct_conversions.hpp>
+#ifndef SIMULATE_FREESTANDING
+#include <stdx/ct_format.hpp>
+#endif
+#include <stdx/ct_string.hpp>
+#include <stdx/cx_map.hpp>
+#include <stdx/cx_multimap.hpp>
+#include <stdx/cx_queue.hpp>
+#include <stdx/cx_set.hpp>
+#include <stdx/cx_vector.hpp>
+#include <stdx/env.hpp>
+#ifndef SIMULATE_FREESTANDING
+#include <stdx/for_each_n_args.hpp>
+#include <stdx/function_traits.hpp>
+#endif
+#include <stdx/functional.hpp>
+#include <stdx/intrusive_forward_list.hpp>
+#include <stdx/intrusive_list.hpp>
+#include <stdx/iterator.hpp>
+#include <stdx/latched.hpp>
+#include <stdx/memory.hpp>
+#include <stdx/numeric.hpp>
+#include <stdx/optional.hpp>
+#include <stdx/panic.hpp>
+#include <stdx/pp_map.hpp>
+#include <stdx/priority.hpp>
+#include <stdx/ranges.hpp>
+#include <stdx/rollover.hpp>
+#include <stdx/span.hpp>
+#ifndef SIMULATE_FREESTANDING
+#include <stdx/static_assert.hpp>
+#endif
+#include <stdx/tuple.hpp>
+#include <stdx/tuple_algorithms.hpp>
+#include <stdx/tuple_destructure.hpp>
+#include <stdx/type_traits.hpp>
+#include <stdx/udls.hpp>
+#include <stdx/utility.hpp>
+
+#if __STDC_HOSTED__ == 0
+extern "C" auto main() -> int;
+#endif
+
+auto main() -> int { return 0; }