new-number-type

# Scaffold a New Number System Type Create all required files, CMake wiring, and test structure for a new number type in the Universal library. ## Arguments `$ARGUMENTS` — the type name (e.g., `takum`) and optionally a description of the template parameters. If not provided, ask the user. ## Before You Start 1. Ask the user: - How many template parameters? (1-param like `integer<nbits>` or 2-param like `posit<nbits, es>`) - Is this a **static** (fixed-size) or **elastic** (adaptive) type? - What category? (integer, fixed-point, float, tapered, logarithmic, block format) - What internal building blocks does it use? (blockbinary, blocksignificand, blocktriple, etc.) 2. Read the matching skeleton template to use as the structural reference: - 1-param: `include/sw/universal/number/skeleton_1param/` - 2-param: `include/sw/universal/number/skeleton_2params/` 3. Read an existing similar type for behavioral reference (e.g., posit for tapered, cfloat for float, fixpnt for fixed-point). ## CRITICAL Rules These are hard-won lessons from past incidents. Violating them causes build failures or CI rejections. ### Triviality - Number types MUST be trivially constructible - **NO in-class member initializers**: use `uint8_t _bits;` NOT `uint8_t _bits{ 0 };` - `ReportTrivialityOfType<T>()` will `static_assert` fail if the type isn't trivial - Default constructor must have empty body or be `= default` ### Constexpr - Do NOT mark constructors/assignment operators `constexpr` if they call `std::frexp`, `std::ldexp`, `std::log2`, etc. - Only use `constexpr` if the conversion path uses only `std::memcpy` or integer arithmetic ### Exception Hierarchy - Number systems inherit from `universal_arithmetic_exception` / `universal_internal_exception` - Internal building blocks inherit from `std::runtime_error` (NEVER from `universal_*`) - Dependencies flow strictly **downward**: number system -> internal block -> never upward - Each type has its OWN exception guard macro (e.g., `TYPENAME_THROW_ARITHMETIC_EXCEPTION`) - The umbrella header forwards its exception config to building blocks: ```cpp #if !defined(TYPENAME_THROW_ARITHMETIC_EXCEPTION) #define TYPENAME_THROW_ARITHMETIC_EXCEPTION 0 #if !defined(BLOCKBINARY_THROW_ARITHMETIC_EXCEPTION) #define BLOCKBINARY_THROW_ARITHMETIC_EXCEPTION 0 #endif #else #if !defined(BLOCKBINARY_THROW_ARITHMETIC_EXCEPTION) #define BLOCKBINARY_THROW_ARITHMETIC_EXCEPTION TYPENAME_THROW_ARITHMETIC_EXCEPTION #endif #endif ``` ### Portability - Never use `long double` manual bit-shift division — use `std::ldexp(1.0l, exponent)` instead - Always initialize `blockbinary` temporaries (clang doesn't zero stack like gcc) - Test with BOTH gcc AND clang before committing ## File Creation Order Create files in this exact order (dependencies flow top-to-bottom): ### Step 1: Header files in `include/sw/universal/number/TYPE/` | File | Purpose | Key contents | |------|---------|-------------| | `TYPE_fwd.hpp` | Forward declarations + type aliases | `template<params> class TYPE;` + convenience aliases | | `exceptions.hpp` | Exception hierarchy | `TYPE_arithmetic_exception`, `TYPE_divide_by_zero`, `TYPE_internal_exception` | | `TYPE_impl.hpp` | Main class implementation | Full class with constructors, operators, conversions | | `numeric_limits.hpp` | `std::numeric_limits` specialization | All required constants and static functions | | `manipulators.hpp` | `type_tag()`, `to_binary()`, `color_print()`, `range()` | Use `enable_if_t<is_TYPE<T>>` pattern | | `attributes.hpp` | Free functions for type properties | `sign()`, `scale()`, `TYPE_range()` | | `TYPE.hpp` | Umbrella header | Includes everything in correct order (see below) | **Umbrella header include order** (MUST follow this sequence): ```text 1. Compiler directives (compiler.hpp, architecture.hpp, bit_cast.hpp, long_double.hpp) 2. Required stdlib (<iostream>, <iomanip>) 3. Behavioral compilation switches (TYPENAME_THROW_ARITHMETIC_EXCEPTION, etc.) 4. Exception config forwarding to building blocks 5. Trait function headers (number_traits.hpp, arithmetic_traits.hpp) 6. exceptions.hpp 7. TYPE_fwd.hpp 8. TYPE_impl.hpp 9. TYPE_traits.hpp (from traits/ directory) 10. numeric_limits.hpp 11. manipulators.hpp 12. attributes.hpp 13. mathlib.hpp (if applicable) ``` ### Step 2: Traits file in `include/sw/universal/traits/` | File | Purpose | |------|---------| | `TYPE_traits.hpp` | `is_TYPE` trait, `is_TYPE_trait` struct, `enable_if_TYPE` alias | The trait MUST match the exact template parameters of the class. ### Step 3: Test directory structure Create the test directory under the appropriate category. The repo uses `static/<CATEGORY>/<TYPE>/` where CATEGORY groups related types: | Category | Types | |----------|-------| | `tapered/` | posit, takum, unum2 | | `float/` | cfloat, bfloat16, dfloat, hfloat, e8m0 | | `logarithmic/` | lns, dbns | | `fixpnt/` | binary, decimal | | `integer/` | binary, decimal, octal, hexadecimal | | `block/` | microfloat, mxblock, nvblock | ```text static/<CATEGORY>/TYPE/ (or elastic/TYPE/ for adaptive types) CMakeLists.txt api/ api.cpp # Primary API test — start here conversion/ (empty initially) logic/ (empty initially) arithmetic/ (empty initially) math/ (empty initially) complex/ (empty initially, only populated when BUILD_COMPLEX=ON) ``` ### Step 4: Test CMakeLists.txt Use the standard pattern. The `compile_all` label path follows: `"Number Systems/static/<NUMBER_CATEGORY>/<ENCODING>/TYPE/<testdir>"` Check an existing sibling type's CMakeLists.txt for the exact label prefix. | Number category | Encoding | Label prefix example | |----------------|----------|---------------------| | `floating-point` | `binary` | `cfloat`, `bfloat16`, `dd`, `microfloat` | | `floating-point` | `decimal` | `dfloat` | | `floating-point` | `hexadecimal` | `hfloat` | | `floating-point` | `logarithmic` | `lns`, `dbns` | | `floating-point` | `tapered` | `posit`, `takum` | | `fixed-point` | `binary` | `fixpnt` | | `fixed-point` | `decimal` | `dfixpnt` | | `integer` | `binary` | `integer` | | `integer` | `decimal` | `dint` | | `rational` | `binary` | `rational` | ```cmake file(GLOB API_SRC "api/*.cpp") file(GLOB CONVERSION_SRC "conversion/*.cpp") file(GLOB LOGIC_SRC "logic/*.cpp") file(GLOB ARITHMETIC_SRC "arithmetic/*.cpp") file(GLOB MATH_SRC "math/*.cpp") file(GLOB COMPLEX_SRC "complex/*.cpp") # Example for lns: "Number Systems/static/floating-point/logarithmic/lns/api" # Example for fixpnt: "Number Systems/static/fixed-point/binary/fixpnt/api" # Example for dint: "Number Systems/static/integer/decimal/dint/api" compile_all("true" "TYPE" "Number Systems/static/<NUMBER_CATEGORY>/<ENCODING>/TYPE/api" "${API_SRC}") compile_all("true" "TYPE" "Number Systems/static/<NUMBER_CATEGORY>/<ENCODING>/TYPE/conversion" "${CONVERSION_SRC}") compile_all("true" "TYPE" "Number Systems/static/<NUMBER_CATEGORY>/<ENCODING>/TYPE/logic" "${LOGIC_SRC}") compile_all("true" "TYPE" "Number Systems/static/<NUMBER_CATEGORY>/<ENCODING>/TYPE/arithmetic" "${ARITHMETIC_SRC}") compile_all("true" "TYPE" "Number Systems/static/<NUMBER_CATEGORY>/<ENCODING>/TYPE/math" "${MATH_SRC}") compile_all("true" "TYPE" "Number Systems/static/<NUMBER_CATEGORY>/<ENCODING>/TYPE/complex" "${COMPLEX_SRC}") ``` ### Step 5: CMake wiring in root CMakeLists.txt **4 insertion points** (find the right alphabetical position among existing types): 1. **Option definition** (~line 160): ```cmake option(UNIVERSAL_BUILD_NUMBER_TYPE "Set to ON to build TYPE tests" OFF) ``` 2. **UNIVERSAL_BUILD_NUMBER_STATICS cascade** (~line 831): ```cmake set(UNIVERSAL_BUILD_NUMBER_TYPE ON) ``` 3. **add_subdirectory block** (~line 974): ```cmake if(UNIVERSAL_BUILD_NUMBER_TYPE) add_subdirectory("static/<CATEGORY>/TYPE") endif(UNIVERSAL_BUILD_NUMBER_TYPE) ``` 4. **CI_LITE cascade** (~line 756, optional — only if portability-critical): ```cmake set(UNIVERSAL_BUILD_NUMBER_TYPE ON) ``` ### Step 6: Initial api.cpp test Create a minimal test that: - Includes the umbrella header - Sets `TYPENAME_THROW_ARITHMETIC_EXCEPTION 1` - Tests default construction - Tests construction from native types (int, float, double) - Tests `type_tag()` output - Tests `ReportTrivialityOfType<TYPE<config>>()` - Uses `ReportTestSuiteHeader()` / `ReportTestSuiteResults()` pattern - Has full exception catch blocks ## Template Parameter Naming Conventions | Parameter | Name | Notes | |-----------|------|-------| | Total bits | `nbits` | NOT `N` or `bits` | | Exponent bits | `es` | NOT `E` or `exponent_bits` | | Fraction bits | `rbits` or `fbits` | Depends on type | | Block type | `bt` | Default to `uint8_t` | | In friend declarations | `nnbits`, `nes`, `nbt` | Prefix with `n` | ## Verification Checklist After creating all files: 1. Build with gcc: `cmake --build --preset gcc-debug --target TYPE_api` 2. Run the test: `build/gcc-debug/static/TYPE/TYPE_api` 3. Build with clang: `cmake --build --preset clang-debug --target TYPE_api` 4. Run the clang test: `build/clang-debug/static/TYPE/TYPE_api` 5. Verify triviality passes (no `static_assert` failures) 6. Verify `type_tag()` produces expected output ## Reference Implementations For behavioral reference, read an existing type that's similar: | If your type is... | Study this implementation | |--------------------|--------------------------| | Tapered floating-point | `posit/posit_impl.hpp` | | Classic floating-point | `cfloat/cfloat_impl.hpp` | | Fixed-point | `fixpnt/fixpnt_impl.hpp` | | Logarithmic | `lns/lns_impl.hpp` | | Integer | `integer/integer_impl.hpp` | | Block format | `mxblock/mxblock_impl.hpp` | | Double-double | `dd/dd_impl.hpp` |