NAME
    Types::Numbers - Type constraints for numbers

DESCRIPTION
    Because we deal with numbers every day in our programs and modules, this
    is an extensive Type::Tiny library of number validations. Like
    Type::Tiny, these types work with all modern OO platforms and as a
    standalone type system.

TYPES
  Overview
    All of these types strive for the accurate storage and validation of
    many different types of numbers, including some storage types that Perl
    doesn't natively support.

    The hierarchy of the types is as follows:

        (T:S = From Types::Standard)
 
        Item (T:S)
           Defined (T:S)
              NumLike
                 NumRange[`n, `p]
                 IntLike
                    SignedInt[`b]
                    UnsignedInt[`b]
                 PerlNum
                    PerlSafeInt
                    PerlSafeFloat
                 BlessedNum[`d]
                    BlessedInt[`d]
                    BlessedFloat[`d]
                 NaN
                 Inf[`s]
                 FloatSafeNum
                    FloatBinary[`b, `e]
                    FloatDecimal[`d, `e]
                 RealNum
                    RealSafeNum
                       FixedBinary[`b, `s]
                       FixedDecimal[`d, `s]
 
              Value (T:S)
                 Str (T:S)
                    Char[`b]

  Basic types
    "NumLike"
        Behaves like "LaxNum" from Types::Standard, but will also accept
        blessed number types. Unlike "StrictNum", it will accept "NaN" and
        "Inf" numbers.

    "NumRange[`n, `p]"
        Only accepts numbers within a certain range. The two parameters are
        the minimums and maximums, inclusive.

    "PerlNum"
        Exactly like "LaxNum", but with a different parent. Only accepts
        unblessed numbers.

    "BlessedNum"
        Only accepts blessed numbers. A blessed number would be using
        something like Math::BigInt or Math::BigFloat. It doesn't directly
        "isa" check those classes, just that the number is blessed.

    "BlessedNum[`d]"
        A blessed number that supports at least certain amount of digit
        accuracy. The blessed number must support the "accuracy" or
        "div_scale" method.

        For example, "BlessedNum[40]" would work for the default settings of
        Math::BigInt, and supports numbers at least as big as 128-bit
        integers.

    "NaN"
        A "not-a-number" value, either embedded into the Perl native float
        or a blessed "NaN", checked via "is_nan".

    "Inf"
        An infinity value, either embedded into the Perl native float or a
        blessed "Inf", checked via "is_inf".

    "Inf[`s]"
           Inf['+']
           Inf['-']

        An infinity value with a certain sign, either embedded into the Perl
        native float or a blessed "Inf", checked via "is_inf". The parameter
        must be a plus or minus character.

    "RealNum"
        Like "NumLike", but does not accept NaN or Inf. Closer to the spirit
        of "StrictNum", but accepts blessed numbers as well.

  Integers
    "IntLike"
        Behaves like "Int" from Types::Standard, but will also accept
        blessed number types and integers in E notation. There are no
        expectations of storage limitations here. (See "SignedInt" for
        that.)

    "PerlSafeInt"
        A Perl (unblessed) integer number than can safely hold the integer
        presented. This varies between 32-bit and 64-bit versions of Perl.

        For example, for most 32-bit versions of Perl, the largest integer
        than can be safely held in a 4-byte NV (floating point number) is
        18446744073709551614. Numbers can go higher than that, but due to
        the NV's mantissa length (accuracy), information is lost beyond this
        point.

        In this case, "...614" would pass and "...615" would fail.

        (Technically, the max integer is "...615", but we can't tell the
        difference between "...615" and "...616", so the cut off point is
        "...614", inclusive.)

    "BlessedInt"
        A blessed number than is holding an integer. (A Math::BigFloat with
        an integer value would still pass.)

    "BlessedInt[`d]"
        A blessed number holding an integer of at most "`d" digits
        (inclusive). The blessed number container must also have digit
        accuracy to support this number. (See "BlessedNum[`d]".)

    "SignedInt"
        A signed integer (blessed or otherwise) that can safely hold its own
        number. This is different than "IntLike", which doesn't check for
        storage limitations.

    "SignedInt[`b]"
        A signed integer that can hold a "`b" bit number and is within those
        boundaries. One bit is reserved for the sign, so the max limit on a
        32-bit integer is actually "2**31-1" or 2147483647.

    "UnsignedInt"
        Like "SignedInt", but with a minimum boundary of zero.

    "UnsignedInt[`b]"
        Like "SignedInt[`b]", but for unsigned integers. Also, unsigned
        integers gain their extra bit, so the maximum is twice as high.

  Floating-point numbers
    "PerlSafeFloat"
        A Perl native float that is in the "integer safe" range, or is a
        NaN/Inf value.

        This doesn't guarantee that every single fractional number is going
        to retain all of its information here. It only guarantees that the
        whole number will be retained, even if the fractional part is partly
        or completely lost.

    "BlessedFloat"
        A blessed number that will support fractional numbers. A
        Math::BigFloat number will pass, whereas a Math::BigInt number will
        fail. However, if that Math::BigInt number is capable of upgrading
        to a Math::BigFloat, it will pass.

    "BlessedFloat[`d]"
        A float-capable blessed number that supports at least certain amount
        of digit accuracy. The number itself is not boundary checked, as it
        is excessively difficult to figure out the exact dimensions of a
        floating point number. It would also not be useful for numbers like
        0.333333... to fail checks.

    "FloatSafeNum"
        A Union of "PerlSafeFloat" and "BlessedFloat". In other words, a
        float-capable number with some basic checks to make sure information
        is retained.

    "FloatBinary[`b, `e]"
        A floating-point number that can hold a "`b" bit number with "`e"
        bits of exponent, and is within those boundaries (or is NaN/Inf).
        The bit breakdown follows traditional IEEE 754 floating point
        standards. For example:

           FloatBinary[32, 8] =
              32 bits total (`b)
              23 bit  mantissa (significand precision)
               8 bit  exponent (`e)
               1 bit  sign (+/-)

        Unlike the *Int types, if Perl's native number cannot support all
        dimensions of the floating-point number without losing information,
        then unblessed numbers are completely off the table. For example,
        assuming a 32-bit machine:

           UnsignedInt[64]->check( 0 )        # pass
           UnsignedInt[64]->check( 2 ** 30 )  # pass
           UnsignedInt[64]->check( 2 ** 60 )  # fail, because 32-bit NVs can't safely hold it

           FloatBinary[64, 11]->check( 0 )    # fail
           FloatBinary[64, 11]->check( $any_unblessed_number )  # fail

    "FloatDecimal[`d, `e]"
        A floating-point number that can hold a "`d" digit number with "`e"
        digits of exponent. Modeled after the IEEE 754 "decimal" float.
        Rejects all Perl NVs that won't support the dimensions. (See
        "FloatBinary[`b, `e]".)

  Fixed-point numbers
    "RealSafeNum"
        Like "FloatSafeNum", but rejects any NaN/Inf.

    "FixedBinary[`b, `s]"
        A fixed-point number, represented as a "`b" bit integer than has
        been shifted by "`s" digits. For example, a "FixedBinary[32, 4]" has
        a max of "2**31-1 / 10**4 = 214748.3647". Because integers do not
        hold NaN/Inf, this type fails on those.

        Otherwise, it has the same properties and caveats as the
        parameterized "Float*" types.

    "FixedDecimal[`d, `s]"
        Like "FixedBinary[`b, `s]", but for a "`d" digit integer. Or, you
        could think of "`d" and "`s" as accuracy (significant figures) and
        decimal precision, respectively.

  Characters
    Characters are basically encoded numbers, so there's a few types here.
    If you need types that handle multi-length strings, you're better off
    using Types::Encoding.

    "Char"
        A single character. Unicode is supported, but it must be decoded
        first. A multi-byte character that Perl thinks is two separate
        characters will fail this type.

    "Char[`b]"
        A single character that fits within "`b" bits. Unicode is supported,
        but it must be decoded first.

        Also, be aware of the ambiguous nature of 8-bit ASCII characters vs.
        UTF8:

           use Encode qw(encode decode);

           my $char = 'ђ';
           Char[8]->check($char);   # pass
           print ord($char);        # 209

           $char = decode("UTF-8", $char);
           Char[8]->check($char);   # fail
           print ord($char);        # 1106
           print $char;             # ђ

        To mitigate this effect, consider an intersection with "Chars" and
        possibly a "Decode" coercion (both from Types::Encoding).

AVAILABILITY
    The project homepage is
    <https://github.com/SineSwiper/Types-Numbers/wiki>.

    The latest version of this module is available from the Comprehensive
    Perl Archive Network (CPAN). Visit <http://www.perl.com/CPAN/> to find a
    CPAN site near you, or see
    <https://metacpan.org/module/Types::Numbers/>.

SUPPORT
  Internet Relay Chat
    You can get live help by using IRC ( Internet Relay Chat ). If you don't
    know what IRC is, please read this excellent guide:
    <http://en.wikipedia.org/wiki/Internet_Relay_Chat>. Please be courteous
    and patient when talking to us, as we might be busy or sleeping! You can
    join those networks/channels and get help:

    *   irc.perl.org

        You can connect to the server at 'irc.perl.org' and talk to this
        person for help: SineSwiper.

  Bugs / Feature Requests
    Please report any bugs or feature requests via
    <https://github.com/SineSwiper/Types-Numbers/issues>.

AUTHOR
    Brendan Byrd <BBYRD@CPAN.org>

CONTRIBUTOR
    Brendan Byrd <bbyrd@cpan.org>

COPYRIGHT AND LICENSE
    This software is Copyright (c) 2013 by Brendan Byrd.

    This is free software, licensed under:

      The Artistic License 2.0 (GPL Compatible)

