easy_cast/
lib.rs

1// Licensed under the Apache License, Version 2.0 (the "License");
2// you may not use this file except in compliance with the License.
3// You may obtain a copy of the License in the LICENSE-APACHE file or at:
4//     https://www.apache.org/licenses/LICENSE-2.0
5
6//! Type conversion, success expected
7//!
8//! This library exists to make fallible numeric type conversions easy, without
9//! resorting to the `as` keyword.
10//!
11//! -   [`Conv`] is like [`From`], but supports fallible conversions
12//! -   [`Cast`] is to [`Conv`] what [`Into`] is to [`From`]
13//! -   [`ConvApprox`] and [`CastApprox`] support fallible, approximate conversion
14//! -   [`ConvFloat`] and [`CastFloat`] are similar, providing precise control over rounding
15//!
16//! If you are wondering "why not just use `as`", there are a few reasons:
17//!
18//! -   integer conversions may silently truncate or sign-extend which does not
19//!     preserve value
20//! -   prior to Rust 1.45.0 float-to-int conversions were not fully defined;
21//!     since this version they use saturating conversion (NaN converts to 0)
22//! -   you want some assurance (at least in debug builds) that the conversion
23//!     will preserve values correctly
24//!
25//! Why might you *not* want to use this library?
26//!
27//! -   You want saturating / truncating / other non-value-preserving conversion
28//! -   You want to convert non-numeric types ([`From`] supports a lot more
29//!     conversions than [`Conv`] does)!
30//! -   You want a thoroughly tested library (we're not quite there yet)
31//!
32//! ## Error handling
33//!
34//! All traits support two methods:
35//!
36//! -   `try_*` methods return a `Result` and always fail if the correct
37//!     conversion is not possible
38//! -   other methods may panic or return incorrect results
39//!
40//! In debug builds, methods not returning `Result` must panic on failure. As
41//! with the overflow checks on Rust's standard integer arithmetic, this is
42//! considered a tool for finding logic errors. In release builds, these methods
43//! are permitted to return defined but incorrect results similar to the `as`
44//! keyword.
45//!
46//! If the `always_assert` feature flag is set, assertions will be turned on in
47//! all builds. Some additional feature flags are available for finer-grained
48//! control (see `Cargo.toml`).
49//!
50//! ## no_std support
51//!
52//! When the crate's default features are disabled (and `std` is not enabled)
53//! then the library supports `no_std`. In this case, [`ConvFloat`] and
54//! [`CastFloat`] are only available if the `libm` optional dependency is
55//! enabled.
56//!
57//! [`TryFrom`]: core::convert::TryFrom
58//! [`TryInto`]: core::convert::TryInto
59
60#![deny(missing_docs)]
61#![cfg_attr(not(feature = "std"), no_std)]
62#![cfg_attr(docsrs, feature(doc_auto_cfg))]
63
64mod impl_basic;
65mod impl_float;
66mod impl_int;
67
68pub mod traits;
69
70#[doc(inline)]
71pub use traits::*;
72
73/// Error types for conversions
74#[derive(Clone, Debug, PartialEq, Eq)]
75pub enum Error {
76    /// Source value lies outside of target type's range
77    Range,
78    /// Loss of precision and/or outside of target type's range
79    Inexact,
80}
81
82impl core::fmt::Display for Error {
83    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
84        match self {
85            Error::Range => write!(f, "source value not in target range"),
86            Error::Inexact => write!(f, "loss of precision or range error"),
87        }
88    }
89}
90
91#[cfg(feature = "std")]
92impl std::error::Error for Error {}
93
94/// Result enum with bound [`Error`] type
95pub type Result<T> = core::result::Result<T, Error>;
easy_cast/lib.rs

easy_cast/
lib.rs
