NAME

DateTime::Util::Calc - Calculation Utilities

SYNOPSIS

  use DateTime::Util::Calc qw(polynomial);

  my @coeffs = qw(2 3 -2);
  my $x      = 5;
  my $rv     = polynomial($x, @coeffs);

  # surpress use of Math::BigFloat
  local $DateTime::Util::Calc::NoBigFloat = 1;

DESCRIPTION

This module contains some common calculation utilities that are required to perform datetime calculations, specifically from "Calendrical Calculations" -- they are NOT meant to be general purpose.

Nothing is exported by default. You must either explicitly export them, or use as fully qualified function names.

FUNCTIONS

polynomial($x, @coefs)

Calculates the value of a polynomial equation, based on Horner's Rule.

   c + b * x + a * (x ** 2)     x = 5

is expressed as:

   polynomial(5, c, b, a);

bf_downgrade($v)

If the value $v is a Math::BigFloat object, returns the "downgraded", regular Perl scalar version of $v. This is sometimes required for functions or objects that do not accept Math::BigFloat.

If $v is not Math::BigFloat object, just returns the value itself.

sin_deg($degrees)

cos_deg($degrees)

tan_deg($degrees)

asin_deg($degrees)

acos_deg($degrees)

Each of these functions calculates their respective values based on degrees, not radians (as Perl's version of sin() and cos() would do).

Since Math::BigFloat does not have corresponding trigonemetric functions, values passed to these funtions will be automatically downgraded via bf_downgrade()

mod($v,$mod)

Calculates the modulus of $v over $mod. Perl's built-in modulus operator (%) for some reason rounds numbers UP when a fractional number's modulus is taken. Many of the calculations also needed the fractional part of the calculation, so this function takes care of both.

Example:

  mod(12.234, 5) = 2.234

amod($v,$mod)

This function is almost identical to mod(), but when the regular modulus value is 0, returns $mod instead of 0.

Example:

  amod(11, 5) = 1
  amod(10, 5) = 5
  amod(9, 5)  = 4
  amod(8, 5)  = 3

search_next(%opts)

Performs a "linear" search until some condition is met. This is a generalized version of the formula defined in [1] p.22. The basic idea is :

  x = base
  while (! check(x) ) {
     x = next(x);
  }
  return x

%opts can contain the following parameters:

base

The initial value to use to start the search process. The value can be anything, but you must provide check and next parameters that are capable of handling the type of thing you specified.

check (coderef)

Code to be executed to determine the end of the search. The function receives the current value of "x", and should return a true value if the condition to end the loop has been reached

next (coderef, optional)

Code to be executed to determine the next value of "x". The function receives the current value of "x", and should return the value to be used for the next iteration.

If unspecified, it will use a function that blindly adds 1 to whatever x is. (so if you specified a number for base, it should work -- but if you passed an object like DateTime, it will probably be an error)

So for example, to iterate through 1 through 9, you could do something like this

  my $x = search_next(
    base => 1,
    check => sub { $_[0] == 9 }
  );

And $x will be set to 9. For a more interesting example, we could look for a DateTime object $dt matching a certain condition foo():

  my $dt = search_next(
    base  => $base_date,
    check => \&foo,
    next  => sub { $_[0] + DateTime::Duration->new(days => 1) }
  );

revolution($angle_in_degrees)

Reduces any angle to within the first revolution by sbtracting or adding even multiples of 360.0.

rev180($angle_in_degrees)

Reduces input to within +180..+180 degrees

CAVEATS

For performance reasons, there is absolutely no parameter validation via Params::Validate in this module!

AUTHOR

Daisuke Maki <daisuke@cpan.org>

cpanm DateTime::Util::Calc

perl -MCPAN -e shell
install DateTime::Util::Calc