nstd_sys/core/
optional.rs

1//! Represents an optional (possibly uninitialized) value.
2use crate::{
3    NSTDAny, NSTDAnyMut, NSTDAnyRef, NSTDAnyRefMut, NSTDBool, NSTDChar, NSTDChar16, NSTDChar32,
4    NSTDChar8, NSTDFloat32, NSTDFloat64, NSTDInt, NSTDInt16, NSTDInt32, NSTDInt64, NSTDInt8,
5    NSTDRef, NSTDRefMut, NSTDUInt, NSTDUInt16, NSTDUInt32, NSTDUInt64, NSTDUInt8,
6};
7use nstdapi::nstdapi;
8
9/// Describes an `NSTDOptional` with no value.
10pub const NSTD_OPTIONAL_NONE: NSTDUInt8 = 0;
11/// Describes an `NSTDOptional` with "some" initialized value.
12pub const NSTD_OPTIONAL_SOME: NSTDUInt8 = 1;
13
14/// Represents an optional (possibly uninitialized) value.
15#[nstdapi]
16#[repr(u8)]
17#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord)]
18pub enum NSTDOptional<T> {
19    /// The uninitialized variant.
20    #[default]
21    None,
22    /// The initialized variant.
23    Some(T),
24}
25impl<T> NSTDOptional<T> {
26    /// Attempts to return the contained `Some` value in an `NSTDOptional`.
27    ///
28    /// This operation is only useful for testing code, it's use in production should be
29    /// discouraged.
30    ///
31    /// # Panics
32    ///
33    /// Panics if `self` is a `None` value.
34    #[inline]
35    pub fn unwrap(self) -> T {
36        match self {
37            Self::Some(value) => value,
38            Self::None => panic!("called `NSTDOptional::unwrap()` on a `None` value"),
39        }
40    }
41
42    /// Attempts to return the contained `Some` value in an `NSTDOptional`.
43    ///
44    /// # Panics
45    ///
46    /// Panics with `msg` if `self` is a `None` value.
47    #[inline]
48    pub fn expect(self, msg: &str) -> T {
49        match self {
50            Self::Some(value) => value,
51            Self::None => panic!("{msg}"),
52        }
53    }
54}
55
56/// Generates optional data structures.
57///
58/// `NSTDOptional` must be in scope.
59///
60/// # Example
61///
62/// ```ignore
63/// use nstd_sys::{
64///     core::optional::{gen_optional, NSTDOptional},
65///     string::NSTDString,
66/// };
67///
68/// gen_optional!(NSTDOptionalString, NSTDString);
69/// ```
70macro_rules! gen_optional {
71    ($name: ident, $T: ty) => {
72        #[doc = concat!("Represents an optional value of type `", stringify!($T), "`.")]
73        pub type $name = NSTDOptional<$T>;
74    };
75}
76pub(crate) use gen_optional;
77gen_optional!(NSTDOptionalAny, NSTDAny);
78gen_optional!(NSTDOptionalAnyMut, NSTDAnyMut);
79gen_optional!(NSTDOptionalBool, NSTDBool);
80gen_optional!(NSTDOptionalChar, NSTDChar);
81gen_optional!(NSTDOptionalChar8, NSTDChar8);
82gen_optional!(NSTDOptionalChar16, NSTDChar16);
83gen_optional!(NSTDOptionalChar32, NSTDChar32);
84gen_optional!(NSTDOptionalFloat32, NSTDFloat32);
85gen_optional!(NSTDOptionalFloat64, NSTDFloat64);
86gen_optional!(NSTDOptionalInt, NSTDInt);
87gen_optional!(NSTDOptionalUInt, NSTDUInt);
88gen_optional!(NSTDOptionalInt8, NSTDInt8);
89gen_optional!(NSTDOptionalUInt8, NSTDUInt8);
90gen_optional!(NSTDOptionalInt16, NSTDInt16);
91gen_optional!(NSTDOptionalUInt16, NSTDUInt16);
92gen_optional!(NSTDOptionalInt32, NSTDInt32);
93gen_optional!(NSTDOptionalUInt32, NSTDUInt32);
94gen_optional!(NSTDOptionalInt64, NSTDInt64);
95gen_optional!(NSTDOptionalUInt64, NSTDUInt64);
96
97/// Represents an optional value of type `NSTDRef`.
98pub type NSTDOptionalRef<'a, T> = NSTDOptional<NSTDRef<'a, T>>;
99/// Represents an optional value of type `NSTDRefMut`.
100pub type NSTDOptionalRefMut<'a, T> = NSTDOptional<NSTDRefMut<'a, T>>;
101
102/// Represents an optional value of type `NSTDAnyRef`.
103pub type NSTDOptionalAnyRef<'a> = NSTDOptional<NSTDAnyRef<'a>>;
104/// Represents an optional value of type `NSTDAnyRefMut`.
105pub type NSTDOptionalAnyRefMut<'a> = NSTDOptional<NSTDAnyRefMut<'a>>;
nstd_sys/core/optional.rs

nstd_sys/core/
optional.rs
