NAME
Math::Complex_C - perl interface to C's double precision complex operations.
DESCRIPTION
use
warnings;
use
strict;
# For brevity, use MCD which is an alias for Math::Complex_C::new
my
$c
= MCD(12.5, 1125);
# assign as NV
my
$root
= MCD();
sqrt_c(
$root
,
$c
);
"Square root of $c is $root\n"
;
See also the Math::Complex_C test suite
for
some (simplistic) examples
of usage.
'double'
. Run
"perl -V:nvtype"
to see what your perl's NV type is. If your
nvtype is
'long double'
consider using Math::Complex_C::L instead, and
if
your nvtype is
'__float128'
consider using Math::Complex_C::Q.
that there are a number of functions returning
'double'
- which,
for
'long
double
' and '
__float128' builds
do
not utilise the full precision that the
'long double'
or
'__float128'
NV provides.
nvtype is double - so long as your compiler supports the building of those
modules. See the
"Which Math::Complex_C"
section of the README that ships
with
this module's source
for
a more detailed explanation.
A number of the functions below
accept
string arguments. These arguments
will be tested by the perl API function looks_like_number()
for
the
presence of non-numeric characters. If any such non-numeric characters
are detected, then the global non-numeric flag (which is initially set to
0) will be incremented. You can query the value this global flag holds by
running Math::Complex_C::nnumflag() and you can manually alter the value of
the global using Math::Complex_C::set_nnum and Math::Complex_C::clear_nnum.
These functions are documented below.
FUNCTIONS
$rop
= Math::Complex_C->new(
$re
,
$im
);
$rop
= Math::Complex_C::new(
$re
,
$im
);
$rop
= MCD(
$re
,
$im
);
# MCD is an alias to Math::Complex_C::new()
$rop
is a returned Math::Complex_C object;
$re
and
$im
are the real and
imaginary
values
(respectively) that
$rop
holds. They (ie
$re
,
$im
) can be
integer
values
(IV or UV), floating point
values
(NV) or numeric strings
IV, UV, and NV
values
will be cast to double
before
being assigned.
Strings (PV) will be assigned using C's strtod() function. Note that the
two arguments (
$re
and
$im
) are optional - ie they can be omitted.
If
no
arguments are supplied, then
$rop
will be assigned NaN
for
both the real
and imaginary parts.
If only one argument is supplied, and that argument is a Math::Complex_C
object then
$rop
will be a duplicate of that Math::Complex_C object.
Otherwise the single argument will be assigned to the real part of
$rop
, and
the imaginary part will be set to zero.
The functions croak
if
an invalid arg is supplied.
$rop
= create_c();
$rop
is a Math::Complex_C object, created
with
both real and imaginary
values
set to NaN. (Same result as calling new() without any args.)
assign_c(
$rop
,
$re
,
$im
);
The real part of
$rop
is set to the value of
$re
, the imaginary part is set to
the value of
$im
.
$re
and
$im
can be integers (IV or UV), floating point
values
(NV) or strings (PV).
set_real_c(
$rop
,
$re
);
The real part of
$rop
is set to the value of
$re
.
$re
can be an integer (IV or
UV), floating point value (NV) or a string (PV).
set_imag_c(
$rop
,
$im
);
The imaginary part of
$rop
is set to the value of
$re
.
$re
can be an integer
(IV or UV), floating point value (NV) or a string (PV).
mul_c (
$rop
,
$op1
,
$op2
);
mul_c_iv(
$rop
,
$op1
,
$si
);
mul_c_uv(
$rop
,
$op1
,
$ui
);
mul_c_nv(
$rop
,
$op1
,
$nv
);
mul_c_pv(
$rop
,
$op1
,
$pv
);
Multiply
$op1
by the 3rd arg, and store the result in
$rop
.
The
"3rd arg"
is (respectively, from top) a Math::Complex_C object,
a signed integer value (IV), an unsigned integer value (UV), a floating point
value (NV), a numeric string (PV). The UV, IV, NV and PV
values
are real only -
ie
no
imaginary component. The PV will be set to a long double value using C's
strtod() function. The UV, IV and NV
values
will be cast to long double
values
.
add_c (
$rop
,
$op1
,
$op2
);
add_c_iv(
$rop
,
$op1
,
$si
);
add_c_uv(
$rop
,
$op1
,
$ui
);
add_c_nv(
$rop
,
$op1
,
$nv
);
add_c_pv(
$rop
,
$op1
,
$pv
);
As
for
mul_c(), etc., but performs addition.
div_c (
$rop
,
$op1
,
$op2
);
div_c_iv(
$rop
,
$op1
,
$si
);
div_c_uv(
$rop
,
$op1
,
$ui
);
div_c_nv(
$rop
,
$op1
,
$nv
);
div_c_pv(
$rop
,
$op1
,
$pv
);
As
for
mul_c(), etc., but performs division.
sub_c (
$rop
,
$op1
,
$op2
);
sub_c_iv(
$rop
,
$op1
,
$si
);
sub_c_uv(
$rop
,
$op1
,
$ui
);
sub_c_nv(
$rop
,
$op1
,
$nv
);
sub_c_pv(
$rop
,
$op1
,
$pv
);
As
for
mul_c(), etc., but performs subtraction.
$nv
= real_c(
$op
);
Returns the real part of
$op
as a (double precision) NV.
Wraps C
's '
creal' function.
$nv
= imag_c(
$op
);
Returns the imaginary part of
$op
as a (double precision) NV.
$nv
= arg_c(
$op
);
Returns the argument of
$op
as a (double precision) NV.
Wraps C
's '
carg' function.
$nv
= abs_c(
$op
);
Returns the absolute value of
$op
as a (double precision) NV.
Wraps C
's '
cabs' function.
conj_c(
$rop
,
$op
);
Sets
$rop
to the conjugate of
$op
.
Wraps C
's '
conj' function.
acos_c(
$rop
,
$op
);
Sets
$rop
to acos(
$op
). Wraps C
's '
cacos' function.
asin_c(
$rop
,
$op
);
Sets
$rop
to asin(
$op
). Wraps C
's '
casin' function.
atan_c(
$rop
,
$op
);
Sets
$rop
to atan(
$op
). Wraps C
's '
catan' function.
cos_c(
$rop
,
$op
);
Sets
$rop
to
cos
(
$op
). Wraps C
's '
ccos' function.
sin_c(
$rop
,
$op
);
Sets
$rop
to
sin
(
$op
). Wraps C
's '
csin' function.
tan_c(
$rop
,
$op
);
Sets
$rop
to tan(
$op
). Wraps C
's '
ctan' function.
acosh_c(
$rop
,
$op
);
Sets
$rop
to acosh(
$op
). Wraps C
's '
cacosh' function.
asinh_c(
$rop
,
$op
);
Sets
$rop
to asinh(
$op
). Wraps C
's '
casinh' function.
atanh_c(
$rop
,
$op
);
Sets
$rop
to atanh(
$op
). Wraps C
's '
catanh' function.
cosh_c(
$rop
,
$op
);
Sets
$rop
to cosh(
$op
). Wraps C
's '
ccosh' function.
sinh_c(
$rop
,
$op
);
Sets
$rop
to sinh(
$op
). Wraps C
's '
csinh' function.
tanh_c(
$rop
,
$op
);
Sets
$rop
to tanh(
$op
). Wraps C
's '
ctanh' function.
exp_c(
$rop
,
$op
);
Sets
$rop
to e **
$op
. Wraps C
's '
cexp' function.
log_c(
$rop
,
$op
);
Sets
$rop
to
log
(
$op
). Wraps C
's '
clog' function.
pow_c(
$rop
,
$op1
,
$op2
);
Sets
$rop
to
$op1
**
$op2
. Wraps C
's '
cpow' function.
sqrt_c(
$rop
,
$op
);
Sets
$rop
to
sqrt
(
$op
). Wraps C
's '
csqrt' function.
proj_c(
$rop
,
$op
);
Sets
$rop
to a projection of
$op
onto the Riemann sphere.
Wraps C
's '
cproj' function.
$nv
= get_nan();
Sets
$nv
to NaN.
$nv
= get_inf();
Sets
$nv
to Inf.
$bool
= is_nan(
$nv
);
Returns true
if
$nv
is a NaN -
else
returns false
$bool
= is_inf(
$nv
);
Returns true
if
$nv
is -Inf or +Inf -
else
returns false
OUTPUT FUNCTIONS
Default precision
for
output of Math::Complex_C objects is whatever is
17 decimal digits.
This
default
can be altered using d_set_prec (see below).
d_set_prec(
$si
);
$si
= d_get_prec();
Set/get the precision (decimal digits) of output
values
$str
= d_to_str(
$op
);
Return a string of the form
"real imag"
.
Both
"real"
and
"imag"
will be expressed in scientific
notation, to the precision returned by the d_get_prec() function (above).
Use d_set_prec() to alter this precision.
Infinities are stringified to
'inf'
(or
'-inf'
for
-ve infinity).
NaN
values
(including positive and negative NaN vlaues) are stringified to
'nan'
.
$str
= d_to_strp(
$op
,
$si
);
As
for
d_to_str, except that the precision setting
for
the output value
is set by the 2nd arg (which must be greater than 1).
$rop
= str_to_d(
$str
);
Takes a string as per that returned by d_to_str() or d_to_strp().
Returns a Math::Complex_C object set to the value represented by that
string.
OPERATOR OVERLOADING
Math::Complex_C overloads the following operators:
*, +, /, -, **,
*=, +=, /=, -=, **=,
!, bool,
==, !=,
""
,
abs
,
exp
,
log
,
cos
,
sin
,
atan2
,
sqrt
,
=
you understand its caveats. See
'perldoc overload'
and
read
it thoroughly, including the documentation regarding
'copy constructors'
.
Note:
abs
() returns a (double precision) NV, not a Math::Complex_C object.
Overloaded arithmetic operations are provided the following types:
IV, UV, NV, PV, Math::Complex_C object.
The IV, UV, NV and PV
values
are real only (ie
no
imaginary
component). The PV
values
will be converted to double
values
using C's strtod() function. The IV, UV and NV
values
will be
cast to double precision
values
.
Note: For the purposes of the overloaded
'not'
,
'!'
and
'bool'
operators, a
"false"
Math::Complex_C object is one
with
real
and imaginary parts that are both
"false"
- where
"false"
currently means either 0 (including -0) or NaN.
(A
"true"
Math::Complex_C object is, of course, simply one
that is not
"false"
.)
OTHER FUNCTIONS
$iv
= Math::Complex_C::nnumflag();
# not exported
Returns the value of the non-numeric flag. This flag is
initialized to zero, but incemented by 1 whenever a function
is handed a string containing non-numeric characters. The
value of the flag therefore tells us how many
times
functions
have been handed such a string. The flag can be
reset
to 0 by
running clear_nnum().
Math::Complex_C::set_nnum(
$iv
);
# not exported
Resets the global non-numeric flag to the value specified by
$iv
.
Math::Complex_C::clear_nnum();
# not exported
Resets the global non-numeric flag to 0.(Essentially the same
as running set_nnum(0).)
LICENSE
This module is free software; you may redistribute it and/or modify it under
the same terms as Perl itself.
Copyright 2014, 2016 Sisyphus.
AUTHOR
Sisyphus <sisyphus at(@) cpan dot (.) org>