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 false

OUTPUT 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: 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.

    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-16, Sisyphus.

AUTHOR

   Sisyphus <sisyphus at(@) cpan dot (.) org>