NAME

Math::Trig::Units - Inverse and hyperbolic trigonemetric Functions
                     in degrees, radians or gradians.

SYNOPSIS

use Math::Trig::Units qw(dsin  dcos  tan   sec   csc   cot
                         asin  acos  atan  asec  acsc  acot
                         sinh  cosh  tanh  sech  csch  coth
                         asinh acosh atanh asech acsch acoth
                         deg_to_rad  rad_to_deg
                         grad_to_rad rad_to_grad
                         deg_to_grad grad_to_deg
                         units       zero        approx);
$v = dsin($x);
$v = dcos($x);
$v = tan($x);
$v = sec($x);
$v = csc($x);
$v = cot($x);
$v = asin($x);
$v = acos($x);
$v = atan($x);
$v = asec($x);
$v = acsc($x);
$v = acot($x);
$v = sinh($x);
$v = cosh($x);
$v = tanh($x);
$v = sech($x);
$v = csch($x);
$v = coth($x);
$v = asinh($x);
$v = acosh($x);
$v = atanh($x);
$v = asech($x);
$v = acsch($x);
$v = acoth($x);
$degrees  = rad_to_deg($radians);
$radians  = deg_to_rad($degrees);
$degrees  = grad_to_deg($gradians);
$gradians = deg_to_grad($degrees);
$radians  = grad_to_rad($gradians);
$gradians = rad_to_grad($radians);

# set radians instead of degrees (default)
Math::Trig::Units::units('radians');
# set gradians as units
Math::Trig::Units::units('gradians');
# set degrees as units
Math::Trig::Units::units('degrees');
# return current unit setting
$units = Math::Trig::Units::units();

# set the factor that allows a function that is almost zero to be zero
# if int(func($x)*factor) == 0 then the function will be assumed to
# return zero rather than 0.00000000000001
Math::Trig::Units::zero(10e10);

# to make functions in degrees or radians return the expected value
# we can use the approx() function
approx(dsin(30)) == 0.5  # without approx it would be 0.49999999999999945

DESCRIPTION

This module exports the missing inverse and hyperbolic trigonometric functions of real numbers. The inverse functions return values cooresponding to the principal values. Specifying an argument outside of the domain of the function where an illegal divion by zero would occur will cause infinity to be returned. Infinity is Perl's version of this.

This module implements the functions in degrees by default. If you want radians use Math::Trig or set the units via the units sub:

# set radians instead of degrees (default)
Math::Trig::Units::units('radians');
# set gradians as units
Math::Trig::Units::units('gradians');
# set degrees as units
Math::Trig::Units::units('degrees');
# return current unit setting
$units = Math::Trig::Units::units();

A value of Pi to 30 decimal places is used in the source. This will be truncated by your version of Perl to the longest float supported.

To avoid redefining the internal sin() and cos() functions this module calls the functions dsin() and dcos().

units

Set the units. Options are 'radians', 'degrees', 'gradians' and are case insensitive. Alternatively you can call the subclasses

Math::Trig::Degree
Math::Trig::Radian
Math::Trig::Gradian

zero

If a function returns a value like 0.0000000000001 the correct value is in fact probably 0. When we have a 1/func() expression the return value should thus be #INF rather than some arbitarily large integer. To round very small numbers to zero for this purpose we use

int( func() * factor )

By default a factor or 1e12 is used so 1e-12 is not zero but 1e-13 is. You can set any factor you want although he default should work fine.

approx

Because of the limit on the accuracy of the vaule of Pi that is easily supported via a float you will get values like dsin(30) = 0.49999999999999945 when using degrees (or gradians). This can be fixed using the approx() function.

By default the approx sub will modify numbers so if we have a number like 0.499999945 with 6 9s or 0.50000012 with 6 0s the number will be rounded to 0.5. It also works on numbers like 5.250000001. This is useful when using degrees or gradians. In degrees these functions will return 0.5 as expected

approx(dsin(30))
approx(dcos(30))

The approx sub takes a second optional argument that specifies how many 0s or 9s in a row will trigger rounding. The default is 6.

approx($num, 7);  # will return 0.5 for 0.500000001 but 0.50000001 if
                  # that is passed as it only has 6 zeros.

Numbers that do not fulfill the requisite criteria are returned unchanged. For example 0.5000001 will not be rounded to 0.5 as it only has 5 0s.

dsin

returns sin of real argument.

dcos

returns cos of real argument.

tan

returns tangent of real argument.

sec

returns secant of real argument.

csc

returns cosecant of real argument.

cot

returns cotangent of real argument.

asin

returns inverse sine of real argument.

acos

returns inverse cosine of real argument.

atan

returns inverse tangent of real argument.

asec

returns inverse secant of real argument.

acsc

returns inverse cosecant of real argument.

acot

returns inverse cotangent of real argument.

sinh

returns hyperbolic sine of real argument.

cosh

returns hyperbolic cosine of real argument.

tanh

returns hyperbolic tangent of real argument.

sech

returns hyperbolic secant of real argument.

csch

returns hyperbolic cosecant of real argument.

coth

returns hyperbolic cotangent of real argument.

asinh

returns inverse hyperbolic sine of real argument.

acosh

returns inverse hyperbolic cosine of real argument.

(positive value only)

atanh

returns inverse hyperbolic tangent of real argument.

asech

returns inverse hyperbolic secant of real argument.

(positive value only)

acsch

returns inverse hyperbolic cosecant of real argument.

acoth

returns inverse hyperbolic cotangent of real argument.

HISTORY

Modification of Math::Trig by request from stefan_k.

BUGS

Because of the limit on the accuracy of the vaule of Pi that is easily supported via a float you will get values like dsin(30) = 0.49999999999999945 when using degrees. This can be fixed using the approx() function

Let me know about any others.

AUTHOR

Initial Version John A.R. Williams <J.A.R.Williams@aston.ac.uk> Bug fixes and many additonal functions Jason Smith <smithj4@rpi.edu> This version James Freeman <james.freeman@id3.org.uk>