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. UnlikeStrictNum
, it will acceptNaN
andInf
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
ordiv_scale
method.For example,
BlessedNum[40]
would work for the default settings of Math::BigInt, and supports numbers at least as big as 128bit integers. NaN

A "notanumber" value, either embedded into the Perl native float or a blessed
NaN
, checked viais_nan
. Inf

An infinity value, either embedded into the Perl native float or a blessed
Inf
, checked viais_inf
. Inf[`s]

Inf['+'] Inf['']
An infinity value with a certain sign, either embedded into the Perl native float or a blessed
Inf
, checked viais_inf
. The parameter must be a plus or minus character. RealNum

Like
NumLike
, but does not accept NaN or Inf. Closer to the spirit ofStrictNum
, 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. (SeeSignedInt
for that.) PerlSafeInt

A Perl (unblessed) integer number than can safely hold the integer presented. This varies between 32bit and 64bit versions of Perl.
For example, for most 32bit versions of Perl, the largest integer than can be safely held in a 4byte 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. (SeeBlessedNum[`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 32bit integer is actually2**311
or2147483647
. 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.
Floatingpoint 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 floatcapable 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
andBlessedFloat
. In other words, a floatcapable number with some basic checks to make sure information is retained. FloatBinary[`b, `e]

A floatingpoint 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 floatingpoint number without losing information, then unblessed numbers are completely off the table. For example, assuming a 32bit machine:UnsignedInt[64]>check( 0 ) # pass UnsignedInt[64]>check( 2 ** 30 ) # pass UnsignedInt[64]>check( 2 ** 60 ) # fail, because 32bit NVs can't safely hold it FloatBinary[64, 11]>check( 0 ) # fail FloatBinary[64, 11]>check( $any_unblessed_number ) # fail
FloatDecimal[`d, `e]

A floatingpoint 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. (SeeFloatBinary[`b, `e]
.)
Fixedpoint numbers
RealSafeNum

Like
FloatSafeNum
, but rejects any NaN/Inf. FixedBinary[`b, `s]

A fixedpoint number, represented as a
`b
bit integer than has been shifted by`s
digits. For example, aFixedBinary[32, 4]
has a max of2**311 / 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 multilength strings, you're better off using Types::Encoding.
Char

A single character. Unicode is supported, but it must be decoded first. A multibyte 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 8bit ASCII characters vs. UTF8:
use Encode qw(encode decode); my $char = 'ђ'; Char[8]>check($char); # pass print ord($char); # 209 $char = decode("UTF8", $char); Char[8]>check($char); # fail print ord($char); # 1106 print $char; # ђ
To mitigate this effect, consider an intersection with
Chars
and possibly aDecode
coercion (both from Types::Encoding).
AVAILABILITY
The project homepage is https://github.com/SineSwiper/TypesNumbers/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/TypesNumbers/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)