This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Re: [PATCH] Simplified magic_setisa() and improved fields.pm
[perl5.git] / lib / Math / Trig.pm
CommitLineData
5aabfad6
PP
1#
2# Trigonometric functions, mostly inherited from Math::Complex.
3# -- Jarkko Hietaniemi, April 1997
5cd24f17 4# -- Raphael Manfredi, September 1996 (indirectly: because of Math::Complex)
5aabfad6
PP
5#
6
7require Exporter;
8package Math::Trig;
9
10use strict;
11
12use Math::Complex qw(:trig);
13
14use vars qw($VERSION $PACKAGE
15 @ISA
5cd24f17 16 @EXPORT);
5aabfad6
PP
17
18@ISA = qw(Exporter);
19
20$VERSION = 1.00;
21
ace5de91
GS
22my @angcnv = qw(rad2deg rad2grad
23 deg2rad deg2grad
24 grad2rad grad2deg);
5aabfad6
PP
25
26@EXPORT = (@{$Math::Complex::EXPORT_TAGS{'trig'}},
27 @angcnv);
28
5cd24f17
PP
29use constant pi2 => 2 * pi;
30use constant DR => pi2/360;
31use constant RD => 360/pi2;
32use constant DG => 400/360;
33use constant GD => 360/400;
34use constant RG => 400/pi2;
35use constant GR => pi2/400;
5aabfad6
PP
36
37#
38# Truncating remainder.
39#
40
41sub remt ($$) {
42 # Oh yes, POSIX::fmod() would be faster. Possibly. If it is available.
43 $_[0] - $_[1] * int($_[0] / $_[1]);
44}
45
46#
47# Angle conversions.
48#
49
ace5de91 50sub rad2deg ($) { remt(RD * $_[0], 360) }
5aabfad6 51
ace5de91 52sub deg2rad ($) { remt(DR * $_[0], pi2) }
5aabfad6 53
ace5de91 54sub grad2deg ($) { remt(GD * $_[0], 360) }
5aabfad6 55
ace5de91 56sub deg2grad ($) { remt(DG * $_[0], 400) }
5aabfad6 57
ace5de91 58sub rad2grad ($) { remt(RG * $_[0], 400) }
5aabfad6 59
ace5de91 60sub grad2rad ($) { remt(GR * $_[0], pi2) }
5aabfad6
PP
61
62=head1 NAME
63
64Math::Trig - trigonometric functions
65
66=head1 SYNOPSIS
67
68 use Math::Trig;
69
70 $x = tan(0.9);
71 $y = acos(3.7);
72 $z = asin(2.4);
73
74 $halfpi = pi/2;
75
ace5de91 76 $rad = deg2rad(120);
5aabfad6
PP
77
78=head1 DESCRIPTION
79
80C<Math::Trig> defines many trigonometric functions not defined by the
4ae80833 81core Perl which defines only the C<sin()> and C<cos()>. The constant
5aabfad6
PP
82B<pi> is also defined as are a few convenience functions for angle
83conversions.
84
85=head1 TRIGONOMETRIC FUNCTIONS
86
87The tangent
88
89 tan
90
91The cofunctions of the sine, cosine, and tangent (cosec/csc and cotan/cot
92are aliases)
93
94 csc cosec sec cot cotan
95
96The arcus (also known as the inverse) functions of the sine, cosine,
97and tangent
98
99 asin acos atan
100
101The principal value of the arc tangent of y/x
102
103 atan2(y, x)
104
105The arcus cofunctions of the sine, cosine, and tangent (acosec/acsc
106and acotan/acot are aliases)
107
108 acsc acosec asec acot acotan
109
110The hyperbolic sine, cosine, and tangent
111
112 sinh cosh tanh
113
114The cofunctions of the hyperbolic sine, cosine, and tangent (cosech/csch
115and cotanh/coth are aliases)
116
117 csch cosech sech coth cotanh
118
119The arcus (also known as the inverse) functions of the hyperbolic
120sine, cosine, and tangent
121
122 asinh acosh atanh
123
124The arcus cofunctions of the hyperbolic sine, cosine, and tangent
125(acsch/acosech and acoth/acotanh are aliases)
126
127 acsch acosech asech acoth acotanh
128
129The trigonometric constant B<pi> is also defined.
130
131 $pi2 = 2 * pi;
132
5cd24f17
PP
133=head2 ERRORS DUE TO DIVISION BY ZERO
134
135The following functions
136
137 tan
138 sec
139 csc
140 cot
141 asec
142 acsc
143 tanh
144 sech
145 csch
146 coth
147 atanh
148 asech
149 acsch
150 acoth
151
152cannot be computed for all arguments because that would mean dividing
8c03c583
JH
153by zero or taking logarithm of zero. These situations cause fatal
154runtime errors looking like this
5cd24f17
PP
155
156 cot(0): Division by zero.
157 (Because in the definition of cot(0), the divisor sin(0) is 0)
158 Died at ...
159
8c03c583
JH
160or
161
162 atanh(-1): Logarithm of zero.
163 Died at...
164
165For the C<csc>, C<cot>, C<asec>, C<acsc>, C<acot>, C<csch>, C<coth>,
166C<asech>, C<acsch>, the argument cannot be C<0> (zero). For the
167C<atanh>, C<acoth>, the argument cannot be C<1> (one). For the
168C<atanh>, C<acoth>, the argument cannot be C<-1> (minus one). For the
169C<tan>, C<sec>, C<tanh>, C<sech>, the argument cannot be I<pi/2 + k *
170pi>, where I<k> is any integer.
5cd24f17
PP
171
172=head2 SIMPLE (REAL) ARGUMENTS, COMPLEX RESULTS
5aabfad6
PP
173
174Please note that some of the trigonometric functions can break out
175from the B<real axis> into the B<complex plane>. For example
176C<asin(2)> has no definition for plain real numbers but it has
177definition for complex numbers.
178
179In Perl terms this means that supplying the usual Perl numbers (also
180known as scalars, please see L<perldata>) as input for the
181trigonometric functions might produce as output results that no more
182are simple real numbers: instead they are complex numbers.
183
184The C<Math::Trig> handles this by using the C<Math::Complex> package
185which knows how to handle complex numbers, please see L<Math::Complex>
186for more information. In practice you need not to worry about getting
187complex numbers as results because the C<Math::Complex> takes care of
188details like for example how to display complex numbers. For example:
189
190 print asin(2), "\n";
191
192should produce something like this (take or leave few last decimals):
193
194 1.5707963267949-1.31695789692482i
195
5cd24f17
PP
196That is, a complex number with the real part of approximately C<1.571>
197and the imaginary part of approximately C<-1.317>.
5aabfad6
PP
198
199=head1 ANGLE CONVERSIONS
200
201(Plane, 2-dimensional) angles may be converted with the following functions.
202
ace5de91
GS
203 $radians = deg2rad($degrees);
204 $radians = grad2rad($gradians);
5aabfad6 205
ace5de91
GS
206 $degrees = rad2deg($radians);
207 $degrees = grad2deg($gradians);
5aabfad6 208
ace5de91
GS
209 $gradians = deg2grad($degrees);
210 $gradians = rad2grad($radians);
5aabfad6 211
5cd24f17 212The full circle is 2 I<pi> radians or I<360> degrees or I<400> gradians.
5aabfad6 213
5cd24f17 214=head1 BUGS
5aabfad6 215
5cd24f17
PP
216Saying C<use Math::Trig;> exports many mathematical routines in the
217caller environment and even overrides some (C<sin>, C<cos>). This is
218construed as a feature by the Authors, actually... ;-)
5aabfad6 219
5cd24f17
PP
220The code is not optimized for speed, especially because we use
221C<Math::Complex> and thus go quite near complex numbers while doing
222the computations even when the arguments are not. This, however,
223cannot be completely avoided if we want things like C<asin(2)> to give
224an answer instead of giving a fatal runtime error.
5aabfad6 225
5cd24f17 226=head1 AUTHORS
5aabfad6 227
ace5de91
GS
228Jarkko Hietaniemi <F<jhi@iki.fi>> and
229Raphael Manfredi <F<Raphael_Manfredi@grenoble.hp.com>>.
5aabfad6
PP
230
231=cut
232
233# eof