
=pod

=head1 NAME

  Math::JS - Emulate JavaScript arithmetic in perl

=head1 DESCRIPTION

  Assign numeric values to Math::JS objects, and perform arithmetic
  operations on those values according to the rules that JavaScript
  uses.
  The main interest here is to replicate the 32-bit integer arithmetic
  as performed by JavaScript.
  For the floating point arithmetic, JavaScript behaves identically to
  perls configured to have $Config{nvsize} of 8, and therefore the building
  of Math::JS is restricted to perls that have that configuration.

=head1 SYNOPSIS

  use warnings; use strict;
  use Math::JS;

  my $js0 = Math::JS->new(2147483648);
  $js0 >>= 1;
  print $js0, "\n";
  # Outputs -1073741824 (same as JavaScript)
  my $js1 = ($js0 + 10000) & 123456789;
  print $js1, "\n";
  # Outputs 1296  (same as javascript)

=head1 FUNCTIONS

  Exports no functions.

  Overloading of the '+', '-', '*', '/', '**', '++', '--', '>=', '<=',
  '==', '!=', '>', '<', '<=>', '""', '+=', '-=', '*=', '/=', '**=', '&',
  '|', '^', '~', '&=',  '|=', '^=' operators is provided.

=head1 DISPLAYING FLOATING POINT VALUES

  This warrants some specific documentation because it's not trivial to
  get Perl to print out the values in the same form as JavaScript does.
  (That's in addition to the fact that perl's print() function likes to
  present inaccurate values, whereas JavaScript does not.)

  The overloading of '""' uses perl's sprintf() function, which might present
  more decimal mantissa digits than JavaScript does - though both forms will
  accurately represent exactly the same double-precision value.

=head1 LICENSE

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

=head1 AUTHOR

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

=cut
