README.md

primitives API Documentation

Module entry: import mcpplibs.primitives;

Module Entry

Top-level import:

import mcpplibs.primitives;

This module exports:

• mcpplibs.primitives.underlying
• mcpplibs.primitives.policy
• mcpplibs.primitives.primitive
• mcpplibs.primitives.operations

Namespace Overview

• mcpplibs::primitives: core types, concepts, and primitive.
• mcpplibs::primitives::underlying: underlying traits and categories.
• mcpplibs::primitives::policy: policy tags, defaults, and protocols.
• mcpplibs::primitives::operations: functional dispatch API.
• mcpplibs::primitives::operators: operator overload entry.
• mcpplibs::primitives::meta: primitive metadata traits.
• mcpplibs::primitives::types: convenience aliases for common underlying types.

Core Concepts and Metadata

underlying concepts

• underlying_type<T>
• boolean_underlying_type<T>
• character_underlying_type<T>
• integer_underlying_type<T>
• floating_underlying_type<T>
• numeric_underlying_type<T>
• has_common_rep<LhsRep, RhsRep>
• common_rep_t<LhsRep, RhsRep>

policy concepts

• policy::policy_type<P>
• policy::value_policy<P>
• policy::type_policy<P>
• policy::error_policy<P>
• policy::concurrency_policy<P>
• policy::resolve_policy_t<category, Policies...>

primitive metadata

• meta::traits<primitive<...>>
  exposes value_type / policies / value_policy / type_policy / error_policy / concurrency_policy
• meta::make_primitive_t<T, PoliciesTuple>

primitive<T, Policies...>

template <underlying_type T, policy::policy_type... Policies>
class primitive;

Member types

• value_type = T
• policies = std::tuple<Policies...>

Construction and assignment

• explicit primitive(T): same-underlying construction.
• explicit primitive(U): cross-underlying construction (subject to type policy).
• Copy/move construction and assignment are supported for the same policy set.
• Cross-underlying primitive construction/assignment is supported when allowed by type policy.

Value and concurrency access APIs

• value() / value() const
• explicit operator value_type() const
• load() -> value_type
• store(desired)
• compare_exchange(expected, desired) -> bool

Notes:

• store/compare_exchange always support same-underlying types.
• Cross-underlying store/compare_exchange are available only when type policy allows.
• Access APIs are provided by policy::concurrency::handler<..., void, ...>.

Type policy impact on cross-underlying behavior

• policy::type::strict: only identical types are allowed.
• policy::type::compatible: requires same underlying category and a valid common_rep.
• policy::type::transparent: only requires a valid common_rep.

Convenience aliases (types)

• Integers: U8/U16/U32/U64, I8/I16/I32/I64
• Floating-point: F32/F64/F80
• Bool/chars: Bool/UChar/Char8/Char16/Char32/WChar

Example:

using value_t = mcpplibs::primitives::types::I32<
    mcpplibs::primitives::policy::value::checked,
    mcpplibs::primitives::policy::error::expected>;

operations API

The operations namespace provides function-style APIs with unified std::expected results.

Common result aliases

• primitive_dispatch_result_t<OpTag, Lhs, Rhs, ErrorPayload>
• mixed_primitive_dispatch_result_t<OpTag, Primitive, Underlying, ErrorPayload>
• three_way_dispatch_result_t<Lhs, Rhs, ErrorPayload>

Unary operations

• increment
• decrement
• bit_not
• unary_plus
• unary_minus

Binary arithmetic

• add
• sub
• mul
• div
• mod

Binary bitwise

• shift_left
• shift_right
• bit_and
• bit_or
• bit_xor

Comparisons

• equal
• not_equal
• three_way_compare

Compound assignments

• add_assign/sub_assign/mul_assign/div_assign/mod_assign
• shift_left_assign/shift_right_assign
• bit_and_assign/bit_or_assign/bit_xor_assign

Mixed operand support

Most binary operations support:

• primitive op primitive
• primitive op underlying
• underlying op primitive

operators overloads

To use + - * / % ... syntax, import:

using namespace mcpplibs::primitives::operators;

Operator results are still std::expected<...>, not raw values.

policy API

Built-in policy tags

• Value: policy::value::{checked, unchecked, saturating}
• Type: policy::type::{strict, compatible, transparent}
• Error: policy::error::{throwing, expected, terminate}
• Concurrency: policy::concurrency::{none, fenced, fenced_relaxed, fenced_acq_rel, fenced_seq_cst}

Defaults

• policy::defaults::value = policy::value::checked
• policy::defaults::type = policy::type::strict
• policy::defaults::error = policy::error::throwing
• policy::defaults::concurrency = policy::concurrency::none

Error kinds

policy::error::kind:

• none
• invalid_type_combination
• overflow
• underflow
• divide_by_zero
• domain_error
• unspecified

underlying Extension Points

1) Register underlying::traits<T>

Required members:

• value_type
• rep_type
• enabled
• kind
• to_rep(value)
• from_rep(rep)
• is_valid_rep(rep)

2) Customize common-rep negotiation

Specialize underlying::common_rep_traits<LhsRep, RhsRep> to override the default std::common_type_t behavior.

Result and Error Model

• Most operations/operators APIs return std::expected<...>.
• With policy::error::expected, failures are returned as unexpected(policy::error::kind).
• With policy::error::throwing, runtime failures throw exceptions (while API signatures still use std::expected).

Minimal Example

import std;
import mcpplibs.primitives;

using namespace mcpplibs::primitives;
using namespace mcpplibs::primitives::operators;

int main() {
  using value_t =
      primitive<int, policy::value::checked, policy::error::expected>;

  auto const out = value_t{40} + value_t{2};
  if (!out.has_value()) {
    return 1;
  }
  return out->value() == 42 ? 0 : 1;
}