Skip to main content

quack_rs/value/
defaults.rs

1// SPDX-License-Identifier: MIT
2// Copyright 2026 Tom F. <https://github.com/tomtom215/>
3// My way of giving something small back to the open source community
4// and encouraging more Rust development!
5
6//! The defaulting accessors — `Value::as_*_or`.
7//!
8//! Each one folds the `None` of the plain getter — null handle, SQL `NULL`,
9//! failed cast — into a caller-chosen default. A null handle is refused before
10//! any `DuckDB` call, so the default path is reachable without a live engine.
11//! That is why they live here rather than in
12//! `value.rs`: `.cargo/mutants.toml` excludes that file wholesale — every function
13//! left in it wraps a `DuckDB` C call the `--lib` mutation run cannot reach —
14//! and these fourteen can be, and are, killed by ordinary unit tests.
15
16use super::Value;
17
18impl Value {
19    /// Extracts the value as a `String`, returning `default` on failure.
20    ///
21    /// Convenience for `val.as_str().unwrap_or_else(|_| default.to_owned())`.
22    #[inline]
23    #[must_use]
24    pub fn as_str_or(&self, default: &str) -> String {
25        self.as_str().unwrap_or_else(|_| default.to_owned())
26    }
27
28    /// Extracts the value as a `String`, returning an empty string on failure.
29    ///
30    /// Convenience for `val.as_str().unwrap_or_default()`.
31    #[inline]
32    #[must_use]
33    // The `-> String with String::new()` mutant is indistinguishable from the
34    // real function for every input a unit test can build: on a null handle
35    // both give `""`, and producing a non-null VARCHAR needs a live engine,
36    // which the `--cargo-arg=--lib` mutation run does not have. The end-to-end
37    // suite covers the non-empty case.
38    #[cfg_attr(test, mutants::skip)]
39    pub fn as_str_or_default(&self) -> String {
40        self.as_str().unwrap_or_default()
41    }
42
43    /// Extracts the value as an `i32`, returning `default` if it is absent or unreadable.
44    ///
45    /// `default` is returned for a null handle, a SQL `NULL`, and a failed
46    /// or impossible cast — every case in which the plain getter returns `None`.
47    #[inline]
48    #[must_use]
49    pub fn as_i32_or(&self, default: i32) -> i32 {
50        self.as_i32().unwrap_or(default)
51    }
52
53    /// Extracts the value as an `i64`, returning `default` if it is absent or unreadable.
54    ///
55    /// `default` is returned for a null handle, a SQL `NULL`, and a failed
56    /// or impossible cast — every case in which the plain getter returns `None`.
57    #[inline]
58    #[must_use]
59    pub fn as_i64_or(&self, default: i64) -> i64 {
60        self.as_i64().unwrap_or(default)
61    }
62
63    /// Extracts the value as an `f32`, returning `default` if it is absent or unreadable.
64    ///
65    /// `default` is returned for a null handle, a SQL `NULL`, and a failed
66    /// or impossible cast — every case in which the plain getter returns `None`.
67    #[inline]
68    #[must_use]
69    pub fn as_f32_or(&self, default: f32) -> f32 {
70        self.as_f32().unwrap_or(default)
71    }
72
73    /// Extracts the value as an `f64`, returning `default` if it is absent or unreadable.
74    ///
75    /// `default` is returned for a null handle, a SQL `NULL`, and a failed
76    /// or impossible cast — every case in which the plain getter returns `None`.
77    #[inline]
78    #[must_use]
79    pub fn as_f64_or(&self, default: f64) -> f64 {
80        self.as_f64().unwrap_or(default)
81    }
82
83    /// Extracts the value as a `bool`, returning `default` if it is absent or unreadable.
84    ///
85    /// `default` is returned for a null handle, a SQL `NULL`, and a failed
86    /// or impossible cast — every case in which the plain getter returns `None`.
87    #[inline]
88    #[must_use]
89    pub fn as_bool_or(&self, default: bool) -> bool {
90        self.as_bool().unwrap_or(default)
91    }
92
93    /// Extracts the value as an `i8`, returning `default` if it is absent or unreadable.
94    ///
95    /// `default` is returned for a null handle, a SQL `NULL`, and a failed
96    /// or impossible cast — every case in which the plain getter returns `None`.
97    #[inline]
98    #[must_use]
99    pub fn as_i8_or(&self, default: i8) -> i8 {
100        self.as_i8().unwrap_or(default)
101    }
102
103    /// Extracts the value as an `i16`, returning `default` if it is absent or unreadable.
104    ///
105    /// `default` is returned for a null handle, a SQL `NULL`, and a failed
106    /// or impossible cast — every case in which the plain getter returns `None`.
107    #[inline]
108    #[must_use]
109    pub fn as_i16_or(&self, default: i16) -> i16 {
110        self.as_i16().unwrap_or(default)
111    }
112
113    /// Extracts the value as a `u8`, returning `default` if it is absent or unreadable.
114    ///
115    /// `default` is returned for a null handle, a SQL `NULL`, and a failed
116    /// or impossible cast — every case in which the plain getter returns `None`.
117    #[inline]
118    #[must_use]
119    pub fn as_u8_or(&self, default: u8) -> u8 {
120        self.as_u8().unwrap_or(default)
121    }
122
123    /// Extracts the value as a `u16`, returning `default` if it is absent or unreadable.
124    ///
125    /// `default` is returned for a null handle, a SQL `NULL`, and a failed
126    /// or impossible cast — every case in which the plain getter returns `None`.
127    #[inline]
128    #[must_use]
129    pub fn as_u16_or(&self, default: u16) -> u16 {
130        self.as_u16().unwrap_or(default)
131    }
132
133    /// Extracts the value as a `u32`, returning `default` if it is absent or unreadable.
134    ///
135    /// `default` is returned for a null handle, a SQL `NULL`, and a failed
136    /// or impossible cast — every case in which the plain getter returns `None`.
137    #[inline]
138    #[must_use]
139    pub fn as_u32_or(&self, default: u32) -> u32 {
140        self.as_u32().unwrap_or(default)
141    }
142
143    /// Extracts the value as a `u64`, returning `default` if it is absent or unreadable.
144    ///
145    /// `default` is returned for a null handle, a SQL `NULL`, and a failed
146    /// or impossible cast — every case in which the plain getter returns `None`.
147    #[inline]
148    #[must_use]
149    pub fn as_u64_or(&self, default: u64) -> u64 {
150        self.as_u64().unwrap_or(default)
151    }
152
153    /// Extracts the value as an `i128`, returning `default` if it is absent or unreadable.
154    ///
155    /// `default` is returned for a null handle, a SQL `NULL`, and a failed
156    /// or impossible cast — every case in which the plain getter returns `None`.
157    #[inline]
158    #[must_use]
159    pub fn as_i128_or(&self, default: i128) -> i128 {
160        self.as_i128().unwrap_or(default)
161    }
162}
163
164#[cfg(test)]
165mod tests {
166    use super::Value;
167
168    // Every one of these builds a null handle, which is the branch that
169    // does not call into DuckDB — the only branch a `--lib` run can take.
170    // Each default is chosen so none of `0`, `1` or `-1` can impersonate it.
171
172    #[test]
173    fn as_str_or_returns_default_for_null() {
174        let val = unsafe { Value::from_raw(std::ptr::null_mut()) };
175        assert_eq!(val.as_str_or("fallback"), "fallback");
176    }
177
178    #[test]
179    fn as_str_or_default_returns_empty_for_null() {
180        let val = unsafe { Value::from_raw(std::ptr::null_mut()) };
181        assert_eq!(val.as_str_or_default(), "");
182    }
183
184    #[test]
185    fn as_i64_or_returns_default_for_null() {
186        let val = unsafe { Value::from_raw(std::ptr::null_mut()) };
187        assert_eq!(val.as_i64_or(99), 99);
188    }
189
190    #[test]
191    fn as_i32_or_returns_default_for_null() {
192        let val = unsafe { Value::from_raw(std::ptr::null_mut()) };
193        assert_eq!(val.as_i32_or(42), 42);
194    }
195
196    #[test]
197    fn as_bool_or_returns_default_for_null() {
198        let val = unsafe { Value::from_raw(std::ptr::null_mut()) };
199        assert!(val.as_bool_or(true));
200        assert!(!val.as_bool_or(false));
201    }
202
203    #[test]
204    fn as_f64_or_returns_default_for_null() {
205        let val = unsafe { Value::from_raw(std::ptr::null_mut()) };
206        assert!((val.as_f64_or(2.72) - 2.72).abs() < f64::EPSILON);
207    }
208
209    #[test]
210    fn as_f32_or_returns_default_for_null() {
211        let val = unsafe { Value::from_raw(std::ptr::null_mut()) };
212        assert!((val.as_f32_or(2.5) - 2.5).abs() < f32::EPSILON);
213    }
214
215    #[test]
216    fn as_i8_or_returns_default_for_null() {
217        let val = unsafe { Value::from_raw(std::ptr::null_mut()) };
218        assert_eq!(val.as_i8_or(7), 7);
219    }
220
221    #[test]
222    fn as_i16_or_returns_default_for_null() {
223        let val = unsafe { Value::from_raw(std::ptr::null_mut()) };
224        assert_eq!(val.as_i16_or(-300), -300);
225    }
226
227    #[test]
228    fn as_u8_or_returns_default_for_null() {
229        let val = unsafe { Value::from_raw(std::ptr::null_mut()) };
230        assert_eq!(val.as_u8_or(200), 200);
231    }
232
233    #[test]
234    fn as_u16_or_returns_default_for_null() {
235        let val = unsafe { Value::from_raw(std::ptr::null_mut()) };
236        assert_eq!(val.as_u16_or(40_000), 40_000);
237    }
238
239    #[test]
240    fn as_u32_or_returns_default_for_null() {
241        let val = unsafe { Value::from_raw(std::ptr::null_mut()) };
242        assert_eq!(val.as_u32_or(3_000_000_000), 3_000_000_000);
243    }
244
245    #[test]
246    fn as_u64_or_returns_default_for_null() {
247        let val = unsafe { Value::from_raw(std::ptr::null_mut()) };
248        assert_eq!(val.as_u64_or(u64::MAX - 1), u64::MAX - 1);
249    }
250
251    #[test]
252    fn as_i128_or_returns_default_for_null() {
253        let val = unsafe { Value::from_raw(std::ptr::null_mut()) };
254        assert_eq!(val.as_i128_or(i128::MIN + 1), i128::MIN + 1);
255    }
256}