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
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

// devela::num::error::definitions
//
//!
//
// TOC
// - individual errors:
//   - NoInverse
//   - MismatchedSizes
//   - IncompatibleBounds
//   - NonNegativeRequired
//   - PositiveRequired
//   - NonZeroRequired
//   - Overflow
// - composite errors:
//   - NicheValueError

use crate::{
    _tags, DOC_INVALID_VALUE, DOC_NOT_IMPLEMENTED, DOC_NOT_SUPPORTED, InvalidValue, NotImplemented,
    NotSupported, Sign, define_error,
};

/* individual errors */

define_error![individual: pub struct NoInverse;
    #[derive(Default)], +location: "num/error", +tag: _tags!(num),
    DOC_NO_INVERSE = "An inverse doesn't exist.",
    self+f => f.write_str(DOC_NO_INVERSE!()),
];
define_error![individual: pub struct MismatchedSizes;
    #[derive(Default)], +location: "num/error", +tag: _tags!(num),
    DOC_MISMATCHED_SIZES = "The provided values are not compatible in size.",
    self+f => f.write_str(DOC_MISMATCHED_SIZES!()),
];
define_error![individual: pub struct IncompatibleBounds;
    #[derive(Default)], +location: "num/error", +tag: _tags!(num),
    DOC_INCOMPATIBLE_BOUNDS = "The given bounds are incompatible.
E.g. lower bound exceeds upper bound.", // IMPROVE +docs
    self+f => f.write_str("The given bounds are incompatible."),
];

define_error![individual: pub struct NonNegativeRequired;
    #[derive(Default)], +location: "num/error", +tag: _tags!(num),
    DOC_NON_NEGATIVE_REQUIRED = "A non-negative value is required.",
    self+f => f.write_str(DOC_NON_NEGATIVE_REQUIRED!()),
];
define_error![individual: pub struct PositiveRequired;
    #[derive(Default)], +location: "num/error", +tag: _tags!(num),
    DOC_POSITIVE_REQUIRED = "A positive value is required.",
    self+f => f.write_str(DOC_POSITIVE_REQUIRED!()),
];
define_error![individual: pub struct NonZeroRequired;
    #[derive(Default)], +location: "num/error", +tag: _tags!(num),
    DOC_NON_ZERO_REQUIRED = "A non-zero value is required.",
    self+f => f.write_str(DOC_NON_ZERO_REQUIRED!()),
];

define_error![individual: pub struct Overflow(pub Option<Sign>);
    #[derive(Default)], +location: "num/error", +tag: _tags!(num),
    DOC_OVERFLOW = "An arithmetic overflow error, with an optional associated sign.",
    self+f => if let Some(sign) = self.0 {
        match sign {
            Sign::Positive => f.write_str("Positive overflow."),
            Sign::Negative => f.write_str("Negative overflow."),
            Sign::Zero => f.write_str("Unsigned overflow."), // not meaningful
        }
    } else {
        f.write_str("Overflow.")
    },
];

/* composite errors */

define_error! { composite: fmt(f)
    /// All possible integer operation errors.
    #[doc = crate::_doc_location!("num/error")]
    pub enum IntError {
        +tag: _tags!(no),
        DOC_NOT_IMPLEMENTED: +const NotImplemented => NotImplemented,
        +tag: _tags!(no),
        DOC_NOT_SUPPORTED: +const NotSupported => NotSupported,

        // used by ops: core, combinatoric, modulo, prime, root:
        DOC_OVERFLOW: +const Overflow(s|0: Option<Sign>) => Overflow(*s),
        // used by ops: modulo:
        DOC_NO_INVERSE: +const NoInverse => NoInverse,
        // used by ops: combinatoric, root:
        DOC_NON_NEGATIVE_REQUIRED: +const NonNegativeRequired => NonNegativeRequired,
        // used by ops: division, modulo, root:
        DOC_NON_ZERO_REQUIRED: +const NonZeroRequired => NonZeroRequired,
        // used by ops: combinatoric, factor:
        DOC_MISMATCHED_SIZES: +const MismatchedSizes => MismatchedSizes,

        // DOC_POSITIVE_REQUIRED: +const PositiveRequired => PositiveRequired,
        // DOC_INCOMPATIBLE_BOUNDS: +const IncompatibleBounds => IncompatibleBounds,
    }
}
// MAYBE TEMP
#[allow(dead_code)]
impl IntError {
    #[doc(hidden)]
    pub const fn ni<T>() -> IntResult<T> {
        Err(IntError::NotImplemented)
    }
    // #[doc(hidden)]
    // pub const fn ns<T>() -> IntResult<T> {
    //     Err(IntError::NotSupported)
    // }
}
#[doc = crate::_tags!(num result)]
/// A result of a fallible integer operation.
#[doc = crate::_doc_location!("num")]
pub type IntResult<T> = crate::Result<T, IntError>;

define_error! { composite: fmt(f)
    /// Invalid or problematic values for niche types.
    #[doc = crate::_doc_location!("num")]
    pub enum NicheValueError {
        +tag: _tags!(num),
        DOC_OVERFLOW: +const Overflow(s|0: Option<Sign>) => Overflow(*s),
        DOC_INVALID_VALUE: +const InvalidValue => InvalidValue,
    }
}