// Copyright © 2019 Trevor Spiteri

// This library is free software: you can redistribute it and/or
// modify it under the terms of either
//
//   * the Apache License, Version 2.0 or
//   * the MIT License
//
// at your option.
//
// You should have recieved copies of the Apache License and the MIT
// License along with the library. If not, see
// <https://www.apache.org/licenses/LICENSE-2.0> and
// <https://opensource.org/licenses/MIT>.

/*!
# Numeric casts

This crate provides checked, overflowing and static casts.

## Quick examples

```rust
use core::num::Wrapping;

// Panics on overflow with `debug_assertions`, otherwise wraps.
let a: u32 = az::cast(12i32);
assert_eq!(a, 12);

// Always wraps.
let b: u32 = az::wrapping_cast(-1i32);
assert_eq!(b, u32::max_value());
let c = az::overflowing_cast::<i32, u32>(-1i32);
assert_eq!(c, (u32::max_value(), true));

// Wrapping can also be obtained using `Wrapping`
let d: Wrapping<u32> = az::cast(-1);
assert_eq!(d.0, u32::max_value());
```

Conversions from floating-point to integers are also supported.
Numbers are rounded towards zero, but the [`Round`] wrapper can be
used to convert floating-point numbers to integers with rounding to
the nearest, with ties rounded to even.

```rust
use az::Round;
use core::f32;

assert_eq!(az::cast::<_, i32>(15.7), 15);
assert_eq!(az::cast::<_, i32>(Round(15.5)), 16);
assert_eq!(az::saturating_cast::<_, i32>(1.5e20), i32::max_value());
assert_eq!(az::checked_cast::<_, i32>(f32::NAN), None);
```

## Using the *az* crate

The *az* crate is available on [crates.io][*az* crate]. To use it in
your crate, add it as a dependency inside [*Cargo.toml*]:

```toml
[dependencies]
az = "0.1.0"
```

## License

This crate is free software: you can redistribute it and/or modify it
under the terms of either

  * the [Apache License, Version 2.0][LICENSE-APACHE] or
  * the [MIT License][LICENSE-MIT]

at your option.

### Contribution

Unless you explicitly state otherwise, any contribution intentionally
submitted for inclusion in the work by you, as defined in the Apache
License, Version 2.0, shall be dual licensed as above, without any
additional terms or conditions.

[*Cargo.toml*]: https://doc.rust-lang.org/cargo/guide/dependencies.html
[*az* crate]: https://crates.io/crates/az
[LICENSE-APACHE]: https://www.apache.org/licenses/LICENSE-2.0
[LICENSE-MIT]: https://opensource.org/licenses/MIT
[`Round`]: struct.Round.html
*/
#![no_std]
#![warn(missing_docs)]
#![doc(html_root_url = "https://docs.rs/az/0.1.0")]
#![doc(test(attr(deny(warnings))))]
#![cfg_attr(feature = "fail-on-warnings", deny(warnings))]

mod float;
mod int;
#[cfg(test)]
mod tests;

/**
Used to cast values.

# Panics

When debug assertions are enabled, this trait’s method panics if the
value does not fit in the destination. When debug assertions are *not*
enabled (usual in release mode), the wrapped value can be returned,
but it is not considered a breaking change if in the future it panics;
if wrapping is required use [`WrappingAs`] instead.

This trait’s method also panics with no debug assertions if the value
does not fit and cannot be wrapped, for example when trying to cast
floating-point ∞ into an integer type.

[`WrappingAs`]: trait.WrappingAs.html
*/
pub trait Az<Dst> {
    /// Casts the value.
    fn az(self) -> Dst;
}

/**
Used for checked casts.

This trait’s method returns [`None`] if the value does not fit.

[`None`]: https://doc.rust-lang.org/nightly/core/option/enum.Option.html#variant.None
*/
pub trait CheckedAs<Dst> {
    /// Casts the value.
    fn checked_as(self) -> Option<Dst>;
}

/**
Used to cast into the destination type, saturating if the value does not fit.

# Panics

This trait’s method panics if the value does not fit and saturation
does not make sense, for example when trying to cast floating-point
NaN into an integer type.
*/
pub trait SaturatingAs<Dst> {
    /// Casts the value.
    fn saturating_as(self) -> Dst;
}

/**
Wrapping cast.

# Panics

This trait’s method panics if the value does not fit and cannot be
wrapped, for example when trying to cast floating-point ∞ into an
integer type.
*/
pub trait WrappingAs<Dst> {
    /// Casts the value.
    fn wrapping_as(self) -> Dst;
}

/**
Used for overflowing casts.

This trait’s method returns a [tuple] of the value and a [`bool`],
indicating whether an overflow has occurred. On overflow, the wrapped
value is returned.

# Panics

This trait’s method panics if the value does not fit and cannot be
wrapped, for example when trying to cast floating-point ∞ into an
integer type.

[`bool`]: https://doc.rust-lang.org/nightly/std/primitive.bool.html
[tuple]: https://doc.rust-lang.org/nightly/std/primitive.tuple.html
 */
pub trait OverflowingAs<Dst> {
    /// Casts the value.
    fn overflowing_as(self) -> (Dst, bool);
}

/**
Casts into the destination type, returning [`()`] if the
destination type cannot hold all values of the source type.

[`()`]: https://doc.rust-lang.org/nightly/std/primitive.unit.html

For most cases, using [`From`] makes more sense than using this trait.
The main differences are

  * This trait is implemented even when the conversion cannot always
    take place, in which case the output will always be [`()`].
  * This trait converts all integer and floating-point primitives to
    floating-point primitives, even if some precision is lost. For
    example you can use `StaticAs` to convert [`i64`] to [`f32`] even
    though some precision may be lost.

[`()`]: https://doc.rust-lang.org/nightly/std/primitive.unit.html
[`From`]: https://doc.rust-lang.org/nightly/core/convert/trait.From.html
[`f32`]: https://doc.rust-lang.org/nightly/std/primitive.f32.html
[`i64`]: https://doc.rust-lang.org/nightly/std/primitive.i64.html
*/
pub trait StaticAs<Dst> {
    /// `Dst` if the cast always works, otherwise [`()`].
    ///
    /// [`()`]: https://doc.rust-lang.org/nightly/std/primitive.unit.html
    type Output;

    /// Casts if the conversion works for all source type values,
    /// otherwise returns [`()`].
    ///
    /// [`()`]: https://doc.rust-lang.org/nightly/std/primitive.unit.html
    fn static_as(self) -> Self::Output;
}

/// Casts the value.
///
/// # Panics
///
/// When debug assertions are enabled, panics if the value does not
/// fit in the destination. When debug assertions are *not* enabled
/// (usual in release mode), the wrapped value can be returned, but it
/// is not considered a breaking change if in the future it panics; if
/// wrapping is required use [`wrapping_cast`] instead.
///
/// This function also panics with no debug assertions if the value
/// does not fit and cannot be wrapped, for example when trying to
/// cast floating-point ∞ into an integer type.
///
/// [`wrapping_cast`]: fn.wrapping_cast.html
///
/// # Examples
///
/// ```rust
/// assert_eq!(az::cast::<i32, u32>(5), 5);
/// assert_eq!(az::cast::<f32, u8>(17.1), 17);
/// ```
#[inline]
pub fn cast<Src: Az<Dst>, Dst>(src: Src) -> Dst {
    src.az()
}

/// Casts the value, returning [`None`] if the value does not fit.
///
/// [`None`]: https://doc.rust-lang.org/nightly/core/option/enum.Option.html#variant.None
///
/// # Examples
///
/// ```rust
/// use core::f32;
///
/// assert_eq!(az::checked_cast::<i32, u32>(5), Some(5));
/// assert_eq!(az::checked_cast::<i32, u32>(-5), None);
/// assert_eq!(az::checked_cast::<f32, u8>(17.1), Some(17));
/// assert_eq!(az::checked_cast::<f32, u8>(f32::NAN), None);
/// ```
#[inline]
pub fn checked_cast<Src: CheckedAs<Dst>, Dst>(src: Src) -> Option<Dst> {
    src.checked_as()
}

/// Casts the value, saturating if the value does not fit.
///
/// # Panics
///
/// Panics if the value does not fit and saturation does not make
/// sense, for example when trying to cast floating-point NaN into an
/// integer type.
///
/// # Examples
///
/// ```rust
/// assert_eq!(az::saturating_cast::<i32, u32>(-1), 0);
/// assert_eq!(az::saturating_cast::<f32, u8>(17.0 + 256.0), 255);
/// ```
#[inline]
pub fn saturating_cast<Src: SaturatingAs<Dst>, Dst>(src: Src) -> Dst {
    src.saturating_as()
}

/// Casts the value, wrapping on overflow.
///
/// # Panics
///
/// Panics if the value does not fit and cannot be wrapped, for
/// example when trying to cast floating-point ∞ into an integer type.
///
/// # Examples
///
/// ```rust
/// assert_eq!(az::wrapping_cast::<i32, u32>(-1), u32::max_value());
/// assert_eq!(az::wrapping_cast::<f32, u8>(17.0 + 256.0), 17);
/// ```
#[inline]
pub fn wrapping_cast<Src: WrappingAs<Dst>, Dst>(src: Src) -> Dst {
    src.wrapping_as()
}

/// Overflowing cast.
///
/// Returns a [tuple] of the value and a [`bool`], indicating whether
/// an overflow has occurred. On overflow, the wrapped value is
/// returned.
///
/// # Panics
///
/// Panics if the value does not fit and cannot be wrapped, for
/// example when trying to cast floating-point ∞ into an integer type.
///
/// # Examples
///
/// ```rust
/// assert_eq!(az::overflowing_cast::<i32, u32>(-1), (u32::max_value(), true));
/// assert_eq!(az::overflowing_cast::<f32, u8>(17.0 + 256.0), (17, true));
/// ```
///
/// [`bool`]: https://doc.rust-lang.org/nightly/std/primitive.bool.html
/// [tuple]: https://doc.rust-lang.org/nightly/std/primitive.tuple.html
#[inline]
pub fn overflowing_cast<Src: OverflowingAs<Dst>, Dst>(src: Src) -> (Dst, bool) {
    src.overflowing_as()
}

/// Casts the value.
///
/// Since the bound specifies that
/// <code>&lt;Src as [StaticAs][`StaticAs`]&lt;Dst&gt;&gt;::[Output][`Output`] = Dst</code>,
/// the cast should always work.
///
/// For most cases, using <code>src.[into][`into`]()</code> makes more
/// sense than using this function. The main differences is that this
/// function can be used to convert all integer and floating-point
/// primitives to floating-point primitives, even if some precision is
/// lost. For example you can use `static_cast` to convert [`i64`] to
/// [`f32`] even though some precision may be lost.
///
/// # Examples
///
/// ```rust
/// assert_eq!(az::static_cast::<u32, i64>(15), 15);
/// assert_eq!(az::static_cast::<i32, f32>(-12), -12.0);
/// // 20_000_003 in f32 is rounded to 20_000_004 (24 bits of precision)
/// assert_eq!(az::static_cast::<u32, f32>(20_000_003), 20_000_004.0);
/// ```
///
/// The following would fail to compile because the conversions would
/// not work for all values, even though 0 fits in all types.
///
/// ```compile_fail
/// // i32 to u64 would fail for negative numbers
/// assert_eq!(az::static_cast::<i32, u64>(0), 0);
/// // f32 to i32 would fail for infinite or NaN
/// assert_eq!(az::static_cast::<f32, i32>(0.0), 0);
/// ```
///
/// [`()`]: https://doc.rust-lang.org/nightly/std/primitive.unit.html
/// [`StaticAs`]: trait.StaticAs.html
/// [`Output`]: trait.StaticAs.html#associatedtype.Output
/// [`f32`]: https://doc.rust-lang.org/nightly/std/primitive.f32.html
/// [`i64`]: https://doc.rust-lang.org/nightly/std/primitive.i64.html
/// [`into`]: https://doc.rust-lang.org/nightly/core/convert/trait.Into.html#tymethod.into
#[inline]
pub fn static_cast<Src, Dst>(src: Src) -> Dst
where
    Src: StaticAs<Dst, Output = Dst>,
{
    src.static_as()
}

/// Used to convert floating-point numbers to integers with rounding
/// to the nearest, with ties rounded to even.
///
/// The underlying value can be retrieved through the `.0` index.
///
/// # Examples
///
/// ```rust
/// use az::Round;
/// assert_eq!(az::cast::<_, i32>(Round(0.4)), 0);
/// assert_eq!(az::cast::<_, i32>(Round(0.6)), 1);
/// // ties rounded to even
/// assert_eq!(az::cast::<_, i32>(Round(-0.5)), 0);
/// assert_eq!(az::cast::<_, i32>(Round(-1.5)), -2);
/// ```
#[repr(transparent)]
#[derive(Clone, Copy, Default, Debug, PartialEq, PartialOrd)]
pub struct Round<T>(pub T);