/ 
Math-Int113-0.05
River stage zero No dependents
/ Math::Int113

NAME

Math::Int113 - 113-bit integer arithmetic

DESCRIPTION

113-bit integer arithmetic using perl's native arithmetic operations.
This requires that perl's NV either is '__float128' or the IEEE 754
'long double'.
This module will fail to build && fail to load if that requirement is not
met.

SYNOPSIS

use Math::Int113;

A Math::Int113 object holds, by definition, an (113-bit) integer value in
the range:
-10384593717069655257060992658440191 .. 10384593717069655257060992658440191

All integer values in that range are representable as Math::Int113 objects.

-10384593717069655257060992658440192 and 10384593717069655257060992658440192
are both also exactly representable, but we exclude them because
-10384593717069655257060992658440193 and 10384593717069655257060992658440193
round to (respectively) the same values.

Inf and NaN values will cause fatal errors. (Both will be reported as
"overflows", though this is perhaps not strictly accurate with respect
to NaN.)

Any perl scalar, $x, will be evaluated as int($x), except for scalars used
in '**' and '**=' operations, where they will be evaluated as per normal.
This allows (eg) for $obj**0.5 to be evlauated as int(sqrt($obj)) rather
simply as $obj**0 (which is 1).

my $a = Math::Int113->new('123.5') # $a holds value of 123
my $b = $a + 42.5; # $b holds value of 165
$b += 35;          # $b holds value of 200
print $b, "\n";    # prints 200
$b /= 10.6;        # $b holds value of 20
$c = $b ** 0.5;    # $c holds value of int(sqrt(20))
print $c;          # prints 4.

FUNCTIONS

($count_in, $count_out) = coverage($iv_bits, $nv_prec, $max_prec);
  With an NV that has 113 bits of precision, every positive integer in
  the range 1..10384593717069655257060992658440191 can be represented.
  If you've ever wondered how many of those values are also
  representable when the IV is 64-bit and the precision of the NV is
  53 bits, then running coverage(64, 53, 113) will tell you.
  $count_in will be set to the number of representable values, and
  $count_out will be set to the number of unrepresentable values.
  Hence, $count_in + $count_out == 10384593717069655257060992658440191.
  You might also like to try arguments of (64, 64, 113) or (32, 53, 64).
  Take a look at t/coverage.t for other permutations, too.
  (Just another silly exercise ;-)

($div, $mod) = divmod($sv1, $sv2);
  If $sv1 and/or $sv2 are not already Math::Int113 objects their values,
  assessed in numeric context, will be assigned to Math::Int113 objects.
  $div is a Math::Int113 object containing the value of the (integer)
  division $sv1 / $sv2.
  $mod is a Math::Int113 object containing the value of the (integer)
  operation $sv1 % $sv2.

No other functions are exportable although, of course, new() and the
subroutines that are responsible for overloading the  '+', '-', '*',
'/', '%', '**', '++', '--', '>=', '<=', '==', '!=', '>', '<', '<=>',
'""', '+=', '-=', '*=', '/=', '/%=', '**=', '<<', '>>', '&', '|', '^',
'~', '<<=', '>>=', '&=', '|=', '^=' operations can be accessed by their
fully qualified names.

head1 BITWISE OPERATIONS ON NEGATIVE VALUES

For '<<', and '>>', a left  shift of -x is implemented as a right shift
of x, and a right shift of -x is implemented as a left shift of x.
All other negative values used in  &, |, ^, ~, <<, and >> operations
will be replaced by their respective 2s-complement value.
That is, for negative $x , we set $x = ~($x * -1) + 1 prior to
performing the operation.

head1 LICENSE

This program is free software; you may redistribute it and/or
modify it under the same terms as Perl itself.
Copyright 2023, Sisyphus

AUTHOR

Sisyphus <sisyphus at(@) cpan dot (.) org>