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}