devela 0.28.0

A development substrate of coherence.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

// devela::num::grain::niche
//
#![doc = crate::_DOC_NUM_GRAIN_NICHE!()] // public
#![doc = crate::_doc!(modules: crate::num::grain; niche)]
#![doc = crate::_doc!(flat:"num")]
#![doc = crate::_doc!(extends: num)]
//!
//! This module provides niche-constrained numeric representations and
//! related utilities for domain modeling, sentinel values, and
//! memory-efficient data structures.
//!
//! Niche types prohibit specific values while preserving a compact
//! in-memory representation, enabling zero-cost optimizations and
//! improved layout efficiency.
//!
//! ## Core Niche Types
//!
//! - `NonZero[I|U]*` (re-exported)
//!   - Standard zero-prohibiting types with niche optimization.
//!
//! - `NonValue[I|U]*<const V>`.
//!   - General extension of `NonZero*` guaranteeing `value != V`.
//!   - **Implementation**: Stores transformed value in `NonZero*`.
//!   - **Optimizations**: Automatic instruction selection per case.
//!
//! ## Absence and Adapters
//!
//! - [`NonNiche`]
//!   - A concrete representation that mirrors the API of niche-constrained
//!     types while storing values unchanged.
//!   - Useful for selecting a non-optimized but API-compatible representation.
//!
//! - [`MaybeNiche`]
//!   - A representation-agnostic adapter over primitive integers,
//!     niche-optimized types, and non-optimized parallels.
//!   - Enables generic code to remain independent of the chosen
//!     numeric representation.
//!
//! ## Recommended Defaults
//!
//! ### `NonMaxU*` = `NonValueU*<MAX>`
//! - Preserve zero while prohibiting `MAX`.
//! - Suitable for indices and counters where `MAX` is reserved.
//! - Ideal for: collection indices, counters, bitmask handling.
//! - **Optimization**: Single `NOT` instruction.
//!
//! ### `NonMinI*` = `NonValueI*<MIN>`
//! - Preserve zero with a symmetric signed range.
//! - Useful when `MIN` is problematic.
//! - Ideal for: mathematical ranges, circular buffers, DSP algorithms.
//! - **Optimization**: `LEA` instruction fusion.
//!
//! ## Optimization Characteristics
//! | Type            | Prohibits | Storage       | Optimization | vs `NonZero*`         |
//! |-----------------|-----------|---------------|--------------|-----------------------|
//! | `NonMaxU*`      | MAX       | `!value`      | `NOT`        | Keeps zero, drops MAX |
//! | `NonMinI*`      | MIN       | `value ^ MIN` | `LEA`        | Keeps zero, drops MIN |
//! | `NonValue*`     | Custom V  | `value ^ V`   | `XOR`        | Fully general         |
//! | `NonZero*`      | 0         | raw value     | -            | Classic case          |
//!
//! ## Usage Guide
//! | Use Case                  | Recommended Type       | Advantage                     |
//! |---------------------------|------------------------|-------------------------------|
//! | Must prohibit zero        | `NonZero*`             | Standard solution             |
//! | Custom sentinel value     | `NonValue*<SENTINEL>`  | Flexible prohibited value     |
//! | Index/counter handling    | `NonMaxU*`             | Avoids overflow edge cases    |
//! | Mathematical purity       | `NonMinI*`             | Mathematical clarity          |
//! | API-only abstraction      | `MaybeNiche`           | Representation-agnostic       |
//! | No constraints needed     | Primitive / `NonNiche` | Maximum simplicity            |
//

mod _reexport_core;

mod impls; // impl ConstInit, BitSized

mod absence; // MaybeNiche, NonNiche
mod macros; // niche!, (NicheNew), niche_prim!
mod mem; // NonMax*, NonMin*, NonValue*
// mod norm; // Norm WIP

crate::structural_mods! { // _mods, _reexports, _hidden
    _mods {
        #[doc(inline)]
        pub use super::{
            absence::*,
            macros::{niche, niche_prim},
            mem::*,
            // norm::*,
        };
    }
    _reexports {
        pub use super::_reexport_core::*;
    }
    _hidden {
        pub use super::macros::NicheNew;
    }
}