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>