Merge pull request #21 from kas-gui/work

ConvApprox/CastApprox; tuple + array support; doc

.github/workflows/test.yml

@@ -40,7 +40,7 @@ jobs:
         uses: actions-rs/toolchain@v1
         with:
           profile: minimal
-          toolchain: "1.32.0"
+          toolchain: "1.53.0"
           override: true
       - name: Test
         run: |

CHANGELOG.md

@@ -1,6 +1,12 @@
 Changelog
 =========
 
+## [0.5.0] — unreleased
+
+-   Add `ConvApprox` and `CastApprox`
+-   Support `Conv` and `ConvFloat` for arrays and tuples
+-   Remove `impl<T> Conv<T> for T`
+
 ## [0.4.4] — 2021-04-12
 
 -   Fix negative int to float digits check (#18)

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "easy-cast"
-version = "0.4.4"
+version = "0.5.0"
 authors = ["Diggory Hardy <[email protected]>"]
 edition = "2018"
 license = "Apache-2.0"

README.md

@@ -6,38 +6,64 @@ Easy-cast
 
 Type conversion, success expected
 
-This library is written to make numeric type conversions easy. Such
-conversions usually fall into one of the following cases:
-
--   the conversion must preserve values exactly (use [`From`] or [`Into`]
-    or [`Conv`] or [`Cast`])
--   the conversion is expected to preserve values exactly, though this is
-    not ensured by the types in question (use [`Conv`] or [`Cast`])
--   the conversion could fail and must be checked at run-time (use
-    [`TryFrom`] or [`TryInto`] or [`Conv::try_conv`] or [`Cast::try_cast`])
--   the conversion is from floating point values to integers and should
-    round to the "nearest" integer (use [`ConvFloat`] or [`CastFloat`])
--   the conversion is from `f32` to `f64` or vice-versa; in this case use of
-    `as f32` / `as f64` is likely acceptable since `f32` has special
-    representations for non-finite values and conversion to `f64` is exact
--   truncating conversion (modular arithmetic) is desired; in this case `as`
-    probably does exactly what you want
--   saturating conversion is desired (less common; not supported here)
+This library exists to make fallible numeric type conversions easy, without
+resorting to the `as` keyword.
+
+-   [`Conv`] is like [`From`], but supports fallible conversions
+-   [`Cast`] is to [`Conv`] what [`Into`] is to [`From`]
+-   [`ConvApprox`] and [`CastApprox`] support fallible, approximate conversion
+-   [`ConvFloat`] and [`CastFloat`] are similar, providing precise control over rounding
 
 If you are wondering "why not just use `as`", there are a few reasons:
 
--   integer conversions may silently truncate
--   integer conversions to/from signed types silently reinterpret
+-   integer conversions may silently truncate or sign-extend which does not
+    preserve value
 -   prior to Rust 1.45.0 float-to-int conversions were not fully defined;
     since this version they use saturating conversion (NaN converts to 0)
 -   you want some assurance (at least in debug builds) that the conversion
-    will preserve values correctly without having to proof-read code
+    will preserve values correctly
+
+Why might you *not* want to use this library?
+
+-   You want saturating / truncating / other non-value-preserving conversion
+-   You want to convert non-numeric types ([`From`] supports a lot more
+    conversions than [`Conv`] does)!
+-   You want a thoroughly tested library (we're not quite there yet)
+
+### Error handling
+
+All traits support two methods:
+
+-   `try_*` methods return a `Result` and always fail if the correct
+    conversion is not possible
+-   other methods may panic or return incorrect results
+
+In debug builds, methods not returning `Result` must panic on failure. As
+with the overflow checks on Rust's standard integer arithmetic, this is
+considered a tool for finding logic errors. In release builds, these methods
+are permitted to return defined but incorrect results similar to the `as`
+keyword.
+
+If the `always_assert` feature flag is set, assertions will be turned on in
+all builds. Some additional feature flags are available for finer-grained
+control (see `Cargo.toml`).
 
-When should you *not* use this library?
+### Performance
 
--   Only numeric conversions are supported
--   Conversions from floats do not provide fine control of rounding modes
--   This library has not been thoroughly tested correctness
+Performance is "good enough that it hasn't been a concern".
+
+In debug builds and when `always_assert` is enabled, the priority is testing
+but overhead should be small.
+
+In release builds without `always_assert`, `conv*` methods should reduce to
+`x as T` (with necessary additions for rounding).
+
+### no_std support
+
+When the crate's default features are disabled (and `std` is not enabled)
+then the library supports `no_std`. In this case, [`ConvFloat`] and
+[`CastFloat`] are only available if the `libm` optional dependency is
+enabled.
 
 [`From`]: https://doc.rust-lang.org/stable/std/convert/trait.From.html
 [`Into`]: https://doc.rust-lang.org/stable/std/convert/trait.Into.html
@@ -50,19 +76,9 @@ When should you *not* use this library?
 [`ConvFloat`]: https://docs.rs/easy-cast/latest/easy_cast/trait.ConvFloat.html
 [`CastFloat`]: https://docs.rs/easy-cast/latest/easy_cast/trait.CastFloat.html
 
-## Assertions
-
-All type conversions which are potentially fallible assert on failure in
-debug builds. In release builds assertions may be omitted, thus making
-incorrect conversions possible.
-
-If the `always_assert` feature flag is set, assertions will be turned on in
-all builds. Some additional feature flags are available for finer-grained
-control (see [Cargo.toml](Cargo.toml)).
-
 ## MSRV and no_std
 
-The Minumum Supported Rust Version is 1.32.0 (first release of Edition 2018).
+The Minumum Supported Rust Version is 1.53.0 (`IntoIterator for [T; N]`).
 
 By default, `std` support is required. With default features disabled `no_std`
 is supported, but the `ConvFloat` and `CastFloat` traits are unavailable.