feat: Add examples for basic usage, conversion, and algorithms

Signed-off-by: FrozenlemonTee <1115306170@qq.com>

Author: FrozenLemonTee

examples/ex01_basic_usage.cpp

@@ -0,0 +1,71 @@
+/*
+ * Example: ex01_basic_usage
+ *
+ * Purpose:
+ * Combine checked literals, primitive factory helpers, and built-in framework
+ * operators in one compact end-to-end example.
+ *
+ * Expected results:
+ * - `with(...)` builds primitives directly from checked underlying literals.
+ * - Arithmetic, unary, bitwise, comparison, mixed, and compound operators all
+ *   dispatch successfully.
+ * - The printed values match: sum=42, neg=-2, mod=2, shl=40, band=8, final=43.
+ * - Program exits with code 0; otherwise prints an error and exits non-zero.
+ */
+
+#include <iostream>
+
+import mcpplibs.primitives;
+
+using namespace mcpplibs::primitives;
+
+int main() {
+  using namespace mcpplibs::primitives::literals;
+  using namespace mcpplibs::primitives::operators;
+
+  constexpr auto base =
+      with<policy::value::checked, policy::error::expected>(40_i32);
+  constexpr auto step =
+      with<policy::value::checked, policy::error::expected>(2_i32);
+  constexpr auto mask =
+      with<policy::value::checked, policy::error::expected>(10_i32);
+
+  constexpr auto sum = 2_i32 + base;
+  if constexpr (!sum.has_value()) {
+    std::cerr << "basic usage dispatch failed\n";
+    return 1;
+  }
+
+  constexpr auto neg = -step;
+  constexpr auto mod = *sum % 5_i32;
+  constexpr auto shl = mask << step;
+  constexpr auto band = base & 12_i32;
+  constexpr auto const eq = *sum == 42_i32;
+  constexpr auto const cmp = *sum <=> 41_i32;
+
+  auto counter =
+      with<policy::value::checked, policy::error::expected>(1_i32);
+  auto const pre_inc = ++counter;
+  constexpr auto bonus =
+      with<policy::value::checked, policy::error::expected>(41_i32);
+  auto const add_assign = (counter += bonus);
+
+  if (!pre_inc.has_value() || !add_assign.has_value()) {
+    std::cerr << "basic usage dispatch failed\n";
+    return 1;
+  }
+
+  if (pre_inc->value() != 2 ||
+      add_assign->value() != 43 || counter.load() != 43) {
+    std::cerr << "basic usage produced unexpected values\n";
+    return 1;
+  }
+
+  std::cout << "sum=" << sum->value() << ", neg=" << neg->value()
+            << ", mod=" << mod->value() << ", shl=" << shl->value()
+            << ", band=" << band->value() << ", final=" << counter.load()
+            << '\n';
+
+  std::cout << "basic_usage demo passed\n";
+  return 0;
+}

examples/ex06_conversion.cpp

@@ -0,0 +1,65 @@
+/*
+ * Example: ex06_conversion
+ *
+ * Purpose:
+ * Demonstrate the conversion helpers for checked, saturating, truncating, and
+ * exact casts across both underlying values and primitives.
+ *
+ * Expected results:
+ * - checked_cast succeeds for in-range primitive-to-underlying conversion.
+ * - checked_cast reports underflow for negative-to-unsigned conversion.
+ * - saturating_cast clamps out-of-range input.
+ * - truncating_cast drops the fractional part when targeting an integral
+ *   primitive.
+ * - exact_cast preserves exact values and reports precision loss otherwise.
+ * - Program prints a success message and exits with code 0.
+ */
+
+#include <cstdint>
+#include <iostream>
+
+import mcpplibs.primitives;
+
+using namespace mcpplibs::primitives;
+
+int main() {
+  using namespace mcpplibs::primitives::literals;
+
+  using expected_i32 =
+      types::I32<policy::value::checked, policy::error::expected>;
+  using expected_f32 =
+      types::F32<policy::value::checked, policy::error::expected>;
+
+  constexpr auto source =
+      with<policy::value::checked, policy::error::expected>(255_i32);
+
+  constexpr auto checked_u16 = conversion::checked_cast<std::uint16_t>(source);
+  constexpr auto checked_bad = conversion::checked_cast<std::uint16_t>(-1_i32);
+  constexpr auto saturated_u16 =
+      conversion::saturating_cast<std::uint16_t>(100000_i32);
+  auto const truncated_i32 =
+      conversion::truncating_cast<expected_i32>(12.75_f64);
+  auto const exact_f32 = conversion::exact_cast<expected_f32>(16777216_i32);
+  auto const exact_bad = conversion::exact_cast<expected_f32>(16777217_i32);
+  constexpr auto risk = conversion::numeric_risk<std::uint16_t>(-1_i32);
+
+  if (!checked_u16.has_value() || checked_bad.has_value() ||
+      !exact_f32.has_value() || exact_bad.has_value() || !risk.has_value()) {
+    std::cerr << "conversion demo expected success path missing\n";
+    return 1;
+  }
+
+  if (*checked_u16 != static_cast<std::uint16_t>(255) ||
+      checked_bad.error() != conversion::risk::kind::underflow ||
+      saturated_u16 != static_cast<std::uint16_t>(65535) ||
+      truncated_i32.load() != 12 ||
+      exact_f32->load() != 16777216.0F ||
+      exact_bad.error() != conversion::risk::kind::precision_loss ||
+      *risk != conversion::risk::kind::underflow) {
+    std::cerr << "conversion demo produced unexpected values\n";
+    return 1;
+  }
+
+  std::cout << "conversion demo passed\n";
+  return 0;
+}

examples/ex07_algorithms.cpp

@@ -0,0 +1,56 @@
+/*
+ * Example: ex07_algorithms
+ *
+ * Purpose:
+ * Demonstrate the built-in algorithms helpers for numeric limits metadata,
+ * special values, and hashing.
+ *
+ * Expected results:
+ * - limits<> mirrors std::numeric_limits for supported built-in underlying types.
+ * - helpers expose lowest/max/epsilon/infinity/quiet_nan values.
+ * - hash_value() matches std::hash for the same underlying literal value.
+ * - Program prints a success message and exits with code 0.
+ */
+
+#include <cstdint>
+#include <iostream>
+#include <limits>
+
+import mcpplibs.primitives;
+
+using namespace mcpplibs::primitives;
+
+int main() {
+  using namespace mcpplibs::primitives::literals;
+
+  using int_limits = algorithms::limits<decltype(42_i32)>;
+  using float_limits = algorithms::limits<double>;
+
+  static_assert(int_limits::enabled);
+  static_assert(float_limits::has_infinity);
+  static_assert(algorithms::hashable<std::int32_t>);
+
+  constexpr auto min_i32 = algorithms::min_value<std::int32_t>();
+  constexpr auto max_i32 = algorithms::max_value<std::int32_t>();
+  constexpr auto lowest_f64 = algorithms::lowest_value<double>();
+  constexpr auto epsilon_f64 = algorithms::epsilon_value<double>();
+  constexpr auto infinity_f64 = algorithms::infinity_value<double>();
+  constexpr auto nan_f64 = algorithms::quiet_nan_value<double>();
+  auto const hash_literal = algorithms::hash_value(42_i32);
+  auto const hash_builtin = algorithms::hash_value(std::int32_t{42});
+
+  if (min_i32 != std::numeric_limits<std::int32_t>::min() ||
+      max_i32 != std::numeric_limits<std::int32_t>::max() ||
+      lowest_f64 != std::numeric_limits<double>::lowest() ||
+      epsilon_f64 != std::numeric_limits<double>::epsilon() ||
+      !std::isinf(infinity_f64) || !std::isnan(nan_f64) ||
+      hash_literal != hash_builtin ||
+      int_limits::digits != std::numeric_limits<std::int32_t>::digits ||
+      float_limits::kind != underlying::category::floating) {
+    std::cerr << "algorithms demo produced unexpected values\n";
+    return 1;
+  }
+
+  std::cout << "algorithms demo passed\n";
+  return 0;
+}