NAME
Math::Complex_C::Q - perl interface to C's __complex128 (quadmath) operations.
DEPENDENCIES
In order to compile this module, the quadmath library is needed.DESCRIPTION
use warnings;
use strict;
use Math::Complex_C::Q qw(:all);
# For brevity, use MCQ which is an alias for Math::Complex_C::Q::new
my $c = MCQ(12.5, 1125); # assign as NV
my $root = MCQ();
sqrt_cq($root, $c);
print "Square root of $c is $root\n";
See also the Math::Complex_C::Q test suite for some (simplistic) examples
of usage.
This module is written largely for the use of perl builds whose nvtype is
'__float128'. Run "perl -V:nvtype" to see what your perl's NV type is. If
your nvtype is not '__float128' you can still use this module and utilise
the extra precision it provides. See the "Which Math::Complex_C" section
of the README that ships with this module's source for a more detailed
explanation.
You can also install Math::Complex_C and/or Math::Complex_C::L if this
module won't build for you or you prefer to work with less precision.
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::Q::nnumflag() and you can manually alter the
value of the global using Math::Complex_C::Q::set_nnum and
Math::Complex_C::Q::clear_nnum. These functions are documented below.FUNCTIONS
$rop = Math::Complex_C::Q->new($re, $im);
$rop = Math::Complex_C::Q::new($re, $im);
$rop = MCQ($re, $im); # MCQ is an alias to Math::Complex_C::Q::new()
$rop is a returned Math::Complex_C::Q 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), numeric strings
or Math::Float128 objects.IV, UV and NV values will be cast to __float128
values before being assigned. Strings (PV) will be assigned using C's
strtoflt128() function.
Note that the two arguments ($re & $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::Q
object then $rop will be a duplicate of that Math::Complex_C::Q 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_cq();
$rop is a Math::Complex_C::Q object, created with both real and imaginary
values set to NaN. (Same result as calling new() without any args.)
assign_cq($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), numeric strings, or Math::Float128 objects .
set_real_cq($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), numeric string, or Math::Float128 object.
set_imag_cq($rop, $im);
The imaginary part of $rop is set to the value of $im. $im can be an integer
(IV/UV), floating point value (NV), numeric string, or Math::Float128 object.
F2cq($rop, $r_f, $i_f); #$r_f & $i_f are Math::Float128 objects
Assign the real and imaginary part of $rop from the Math::Float128 objects $r_f
and $i_f (respectively).
cq2F($r_f, $f_i, $op); #$r_f & $i_f are Math::Float128 objects
Assign the real and imaginary parts of $op to the Math::Float128 objects $r_f
and $i_f (respectively).
mul_cq ($rop, $op1, $op2);
mul_cq_iv($rop, $op1, $si);
mul_cq_uv($rop, $op1, $ui);
mul_cq_nv($rop, $op1, $nv);
mul_cq_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::Q 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 __float128 value using C's
strtoflt128() function. The UV, IV and NV values will be cast to __float128
values.
add_cq ($rop, $op1, $op2);
add_cq_iv($rop, $op1, $si);
add_cq_uv($rop, $op1, $ui);
add_cq_nv($rop, $op1, $nv);
add_cq_pv($rop, $op1, $pv);
As for mul_cq(), etc., but performs addition.
div_cq ($rop, $op1, $op2);
div_cq_iv($rop, $op1, $si);
div_cq_uv($rop, $op1, $ui);
div_cq_nv($rop, $op1, $nv);
div_cq_pv($rop, $op1, $pv);
As for mul_cq(), etc., but performs division.
sub_cq ($rop, $op1, $op2);
sub_cq_iv($rop, $op1, $si);
sub_cq_uv($rop, $op1, $ui);
sub_cq_nv($rop, $op1, $nv);
sub_cq_pv($rop, $op1, $pv);
As for mul_cq(), etc., but performs subtraction.
$nv = real_cq($op);
Returns the real part of $op as an NV. If your perl's NV is not __float128
use either real_cq2F($op) or (q_to_str($op))[1].
Wraps C's 'crealq' function.
$nv = imag_cq($op);
Returns the imaginary part of $op as an NV. If your perl's NV is not
__float128 use either real_cq2F($op) or (q_to_str($op))[1].
Wraps C's 'cimagq' function.
$f = real_cq2F($op);
$f = imag_cq2F($op);
Returns a Math::Float128 object $f set to the value of $op's real (and
respectively, imag) component. No point in using this function unless
Math::Float128 is loaded.
Wraps 'crealq' and 'cimagq' to obtain the values.
$str = real_cq2str($op);
$str = imag_cq2str($op);
Returns a string set to the value of $op's real (and respectively, imag)
component.
Wraps 'crealq' and 'cimagq' to obtain the values.
$nv = arg_cq($op);
Returns the argument of $op as an NV.If your perl's NV is not
__float128 use either arg_cq2F() or arg_cq2str().
Wraps C's 'cargq' function.
$f = arg_cq2F($op);
Returns the Math::Float128 object $f, set to the value of the argument
of $op. No point in using this function unless Math::Float128 is loaded.
Wraps C's 'cargq' function.
$str = arg_cq2str($op);
Returns the string $str, set to the value of the argument of $op. No
point in using this function unless Math::Float128 is loaded.
Wraps C's 'cargq' function.
$nv = abs_cq($op);
Returns the absolute value of $op as an NV.If your perl's NV is not
__float128 use either arg_cq2F() or arg_cq2str().
Wraps C's 'cabsq' function.
$f = abs_cq2F($op);
Returns the Math::Float128 object $f, set to the absolute value of $op.
No point in using this function unless Math::Float128 is loaded.
Wraps C's 'cabsq' function.
$str = abs_cq2str($op);
Returns the string $str, set to the absolute value of $op. No point
in using this function unless Math::Float128 is loaded.
Wraps C's 'cabsq' function.
conj_cq($rop, $op);
Sets $rop to the conjugate of $op.
Wraps C's 'conjq' function.
acos_cq($rop, $op);
Sets $rop to acos($op). Wraps C's 'cacosq' function.
asin_cq($rop, $op);
Sets $rop to asin($op). Wraps C's 'casinq' function.
atan_cq($rop, $op);
Sets $rop to atan($op). Wraps C's 'catanq' function.
cos_cq($rop, $op);
Sets $rop to cos($op). Wraps C's 'ccosq' function.
Not presently implemented with mingw-64 compilers - crashes perl.
sin_cq($rop, $op);
Sets $rop to sin($op). Wraps C's 'csinq' function.
Not presently implemented with mingw-64 compilers - crashes perl.
tan_cq($rop, $op);
Sets $rop to tan($op). Wraps C's 'ctanq' function.
Not presently implemented with mingw-64 compilers - crashes perl.
Implemented as sin divided by cos in those situations where the
Makefile.PL's investigations have indicated that the bug is
present. Math::Complex_C::Q::_gcc_tan_bug() returns true iff the
workaround has been implemented.
acosh_cq($rop, $op);
Sets $rop to acosh($op). Wraps C's 'cacoshq' function.
asinh_cq($rop, $op);
Sets $rop to asinh($op). Wraps C's 'casinhq' function.
atanh_cq($rop, $op);
Sets $rop to atanh($op). Wraps C's 'catanhq' function.
cosh_cq($rop, $op);
Sets $rop to cosh($op). Wraps C's 'ccoshq' function.
Not presently implemented with mingw-64 compilers - crashes perl.
sinh_cq($rop, $op);
Sets $rop to sinh($op). Wraps C's 'csinhq' function.
Not presently implemented with mingw-64 compilers - crashes perl.
tanh_cq($rop, $op);
Sets $rop to tanh($op). Wraps C's 'ctanhq' function.
Not presently implemented with mingw-64 compilers - crashes perl.
Implemented as sinh divided by cosh in those situations where the
Makefile.PL's investigations have indicated that the bug is
present. Math::Complex_C::Q::_gcc_tan_bug() returns true iff the
workaround has been implemented.
exp_cq($rop, $op);
Sets $rop to e ** $op. Wraps C's 'cexpq' function.
Not presently implemented with mingw-64 compilers - crashes perl.
log_cq($rop, $op);
Sets $rop to log($op). Wraps C's 'clogq' function.
Not presently implemented with mingw-64 compilers - crashes perl.
pow_cq($rop, $op1, $op2);
Sets $rop to $op1 ** $op2. Wraps C's 'cpowq' function.
Not presently implemented with mingw-64 compilers - crashes perl.
sqrt_cq($rop, $op);
Sets $rop to sqrt($op). Wraps C's 'csqrtq' function.
proj_cq($rop, $op);
Sets $rop to a projection of $op onto the Riemann sphere.
Wraps C's 'cprojq' function.
$nv = get_nanq();
Sets $nv to NaN.
$nv = get_infq();
Sets $nv to Inf.
$bool = is_nanq($nv);
Returns true if $nv is a NaN - else returns false
$bool = is_infq($nv);
Returns true if $nv is -Inf or +Inf - else returns falseOUTPUT FUNCTIONS
Default precision for output of Math::Complex_C::Q objects is 33
decimal digits.
This default can be altered using q_set_prec (see below).
q_set_prec($si);
$si = q_get_prec();
Set/get the precision of output values
$str = q_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 q_get_prec() function (above).
Use q_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 = q_to_strp($op, $si);
As for q_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_q($str);
Takes a string as per that returned by q_to_str() or q_to_strp().
Returns a Math::Complex_C::Q object set to the value represented by that
string.
cq2F($f_r, $f_i, $op);
Assign the real part of $op to the Math::Float128 object $f_r, and the
imaginary part of $op to the Math::Float128 object $f_i.OPERATOR OVERLOADING
Math::Complex_C::Q overloads the following operators:
*, +, /, -, **,
*=, +=, /=, -=, **=,
!, bool,
==, !=,
"",
abs, exp, log, cos, sin, atan2, sqrt,
=
NOTE: Making use of the '=' overloading is not recommended unless
you understand its caveats. See 'perldoc overload' and
read it thoroughly, including the documentation regarding
'copy constructors'.
Note: abs() returns an NV, not a Math::Complex_C::Q object. If your NV-type
is not __float128 then you should probably call abs_cq2F() or
abs_cq2str() instead. Check the documentation (above) of those two
alternatives.
Note: With mingw-w64 compilers exp, log, sin, cos, ** and **= overloading
is not provided because calling the underlying C functions crashes
perl. (TODO: This may no longer be the case.)
Overloaded arithmetic operations are provided the following types:
IV, UV, NV, PV, Math::Complex_C::Q object.
The IV, UV, NV and PV values are real only (ie no imaginary component). The
PV values will be converted to __float128 values using C's strtoflt128()
function. The IV, UV and NV values will be cast to __float128 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::Q::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::Q::set_nnum($iv); # not exported
Resets the global non-numeric flag to the value specified by
$iv.
Math::Complex_C::Q::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-17, Sisyphus.AUTHOR
Sisyphus <sisyphus at(@) cpan dot (.) org>