1// Copyright 2018 Developers of the Rand project.
2//
3// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
4// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
5// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
6// option. This file may not be copied, modified, or distributed
7// except according to those terms.
8
9//! Error types
10
11use core::fmt;
12use core::num::NonZeroU32;
13
14#[cfg(feature = "std")] use std::boxed::Box;
15
16/// Error type of random number generators
17///
18/// In order to be compatible with `std` and `no_std`, this type has two
19/// possible implementations: with `std` a boxed `Error` trait object is stored,
20/// while with `no_std` we merely store an error code.
21pub struct Error {
22 #[cfg(feature = "std")]
23 inner: Box<dyn std::error::Error + Send + Sync + 'static>,
24 #[cfg(not(feature = "std"))]
25 code: NonZeroU32,
26}
27
28impl Error {
29 /// Codes at or above this point can be used by users to define their own
30 /// custom errors.
31 ///
32 /// This has a fixed value of `(1 << 31) + (1 << 30) = 0xC000_0000`,
33 /// therefore the number of values available for custom codes is `1 << 30`.
34 ///
35 /// This is identical to [`getrandom::Error::CUSTOM_START`](https://docs.rs/getrandom/latest/getrandom/struct.Error.html#associatedconstant.CUSTOM_START).
36 pub const CUSTOM_START: u32 = (1 << 31) + (1 << 30);
37 /// Codes below this point represent OS Errors (i.e. positive i32 values).
38 /// Codes at or above this point, but below [`Error::CUSTOM_START`] are
39 /// reserved for use by the `rand` and `getrandom` crates.
40 ///
41 /// This is identical to [`getrandom::Error::INTERNAL_START`](https://docs.rs/getrandom/latest/getrandom/struct.Error.html#associatedconstant.INTERNAL_START).
42 pub const INTERNAL_START: u32 = 1 << 31;
43
44 /// Construct from any type supporting `std::error::Error`
45 ///
46 /// Available only when configured with `std`.
47 ///
48 /// See also `From<NonZeroU32>`, which is available with and without `std`.
49 #[cfg(feature = "std")]
50 #[cfg_attr(doc_cfg, doc(cfg(feature = "std")))]
51 #[inline]
52 pub fn new<E>(err: E) -> Self
53 where
54 E: Into<Box<dyn std::error::Error + Send + Sync + 'static>>,
55 {
56 Error { inner: err.into() }
57 }
58
59 /// Reference the inner error (`std` only)
60 ///
61 /// When configured with `std`, this is a trivial operation and never
62 /// panics. Without `std`, this method is simply unavailable.
63 #[cfg(feature = "std")]
64 #[cfg_attr(doc_cfg, doc(cfg(feature = "std")))]
65 #[inline]
66 pub fn inner(&self) -> &(dyn std::error::Error + Send + Sync + 'static) {
67 &*self.inner
68 }
69
70 /// Unwrap the inner error (`std` only)
71 ///
72 /// When configured with `std`, this is a trivial operation and never
73 /// panics. Without `std`, this method is simply unavailable.
74 #[cfg(feature = "std")]
75 #[cfg_attr(doc_cfg, doc(cfg(feature = "std")))]
76 #[inline]
77 pub fn take_inner(self) -> Box<dyn std::error::Error + Send + Sync + 'static> {
78 self.inner
79 }
80
81 /// Extract the raw OS error code (if this error came from the OS)
82 ///
83 /// This method is identical to `std::io::Error::raw_os_error()`, except
84 /// that it works in `no_std` contexts. If this method returns `None`, the
85 /// error value can still be formatted via the `Display` implementation.
86 #[inline]
87 pub fn raw_os_error(&self) -> Option<i32> {
88 #[cfg(feature = "std")]
89 {
90 if let Some(e) = self.inner.downcast_ref::<std::io::Error>() {
91 return e.raw_os_error();
92 }
93 }
94 match self.code() {
95 Some(code) if u32::from(code) < Self::INTERNAL_START => Some(u32::from(code) as i32),
96 _ => None,
97 }
98 }
99
100 /// Retrieve the error code, if any.
101 ///
102 /// If this `Error` was constructed via `From<NonZeroU32>`, then this method
103 /// will return this `NonZeroU32` code (for `no_std` this is always the
104 /// case). Otherwise, this method will return `None`.
105 #[inline]
106 pub fn code(&self) -> Option<NonZeroU32> {
107 #[cfg(feature = "std")]
108 {
109 self.inner.downcast_ref::<ErrorCode>().map(|c| c.0)
110 }
111 #[cfg(not(feature = "std"))]
112 {
113 Some(self.code)
114 }
115 }
116}
117
118impl fmt::Debug for Error {
119 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
120 #[cfg(feature = "std")]
121 {
122 write!(f, "Error {{ inner: {:?} }}", self.inner)
123 }
124 #[cfg(all(feature = "getrandom", not(feature = "std")))]
125 {
126 getrandom::Error::from(self.code).fmt(f)
127 }
128 #[cfg(not(feature = "getrandom"))]
129 {
130 write!(f, "Error {{ code: {} }}", self.code)
131 }
132 }
133}
134
135impl fmt::Display for Error {
136 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
137 #[cfg(feature = "std")]
138 {
139 write!(f, "{}", self.inner)
140 }
141 #[cfg(all(feature = "getrandom", not(feature = "std")))]
142 {
143 getrandom::Error::from(self.code).fmt(f)
144 }
145 #[cfg(not(feature = "getrandom"))]
146 {
147 write!(f, "error code {}", self.code)
148 }
149 }
150}
151
152impl From<NonZeroU32> for Error {
153 #[inline]
154 fn from(code: NonZeroU32) -> Self {
155 #[cfg(feature = "std")]
156 {
157 Error {
158 inner: Box::new(ErrorCode(code)),
159 }
160 }
161 #[cfg(not(feature = "std"))]
162 {
163 Error { code }
164 }
165 }
166}
167
168#[cfg(feature = "getrandom")]
169impl From<getrandom::Error> for Error {
170 #[inline]
171 fn from(error: getrandom::Error) -> Self {
172 #[cfg(feature = "std")]
173 {
174 Error {
175 inner: Box::new(error),
176 }
177 }
178 #[cfg(not(feature = "std"))]
179 {
180 Error { code: error.code() }
181 }
182 }
183}
184
185#[cfg(feature = "std")]
186impl std::error::Error for Error {
187 #[inline]
188 fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
189 self.inner.source()
190 }
191}
192
193#[cfg(feature = "std")]
194impl From<Error> for std::io::Error {
195 #[inline]
196 fn from(error: Error) -> Self {
197 if let Some(code: i32) = error.raw_os_error() {
198 std::io::Error::from_raw_os_error(code)
199 } else {
200 std::io::Error::new(kind:std::io::ErrorKind::Other, error)
201 }
202 }
203}
204
205#[cfg(feature = "std")]
206#[derive(Debug, Copy, Clone)]
207struct ErrorCode(NonZeroU32);
208
209#[cfg(feature = "std")]
210impl fmt::Display for ErrorCode {
211 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
212 write!(f, "error code {}", self.0)
213 }
214}
215
216#[cfg(feature = "std")]
217impl std::error::Error for ErrorCode {}
218
219#[cfg(test)]
220mod test {
221 #[cfg(feature = "getrandom")]
222 #[test]
223 fn test_error_codes() {
224 // Make sure the values are the same as in `getrandom`.
225 assert_eq!(super::Error::CUSTOM_START, getrandom::Error::CUSTOM_START);
226 assert_eq!(super::Error::INTERNAL_START, getrandom::Error::INTERNAL_START);
227 }
228}
229