devela 0.27.0

A development layer 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
//!
//! ### `NonExtremeU*` = `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.
//!
//! ### `NonExtremeI*` = `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*`         |
//! |---------------------|-----------|---------------|--------------|-----------------------|
//! | `NonExtremeU*`      | MAX       | `!value`      | `NOT`        | Keeps zero, drops MAX |
//! | `NonExtremeI*`      | 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    | `NonExtremeU*`            | Avoids overflow edge cases     |
//! | Mathematical purity       | `NonExtremeI*`            | 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_prim!, ne!, nv!, nz!, (NicheNew)
mod mem; // NonExtreme*, NonValue*
// mod norm; // Norm WIP

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