NAME
    Math::SymbolicX::Complex - Complex number support for the Math::Symbolic
    parser

SYNOPSIS
      use Math::Symbolic qw/parse_from_string/;
      use Math::SymbolicX::Complex;
      
  my $formula = parse_from_string('3 * complex(3,2)^2 + polar(1, pi/2)');
      print $formula->value();
      # prints '14.9999999997949+37i'
      # (blame the inaccuracy on the floating point representation of "pi")

DESCRIPTION
    This module adds complex number support to Math::Symbolic. It does so by
    extending the parser of the Math::Symbolic module (that is, the one
    stored in $Math::Symbolic::Parser) with certain special functions that
    create complex constants. (Math::Symbolic::Variable objects have been
    able to contain complex number objects since the very beginning.)

  MOTIVATION
    All constants in strings that are parsed by Math::Symbolic::Parser are
    converted to Math::Symbolic::Constant objects holding the value
    associated to the constant in an ordinary Perl Scalar by default.
    Unfortunately, that means you are limited to real floating point
    numbers.

    On the other hand, there's the formidable Math::Complex module that
    gives complex number support to Perl. Since the Math::Symbolic::Scalar
    objects can hold any object, you can build your trees by hand using
    Math::Complex objects instead of Perl Scalars for the value of the
    constants. But since the Math::Symbolic::Parser is by far the most
    convenient interface to Math::Symbolic, there had to be a reasonably
    simple way of introducing Math::Complex support to the parser. So here
    goes.

  USAGE
    In order to complex number constants in Math::Symbolic trees from the
    parser, you just load this extension module and wrap any of the
    functions listed hereafter around any constants that are complex in
    nature.

    The aforementioned functions are "complex()" and "polar()". "complex(RE,
    IM)" takes a real portion and an imaginary portion of the complex number
    as arguments. That means, it uses the "Math::Complex-"make(RE, IM)>
    method to create the Math::Complex objects. Similarily, "polar()" uses
    the "Math::Complex-"emake(R, ARG)> syntax provided by Math::Complex.
    (Polar notation is r*e^(i*arg). It is equivalent to the "x+i*y" notation
    because it also covers the whole complex plane.)

    There are some usability extensions to the simple "complex(RE, IM)" and
    "polar(R, ARG)" notations: You can use the basic operators ('+', '-',
    '*', '/', and '**') and the symbolic constant 'pi' in the expressions
    for RE, IM, R, and ARG. That means "polar(1, pi/2)" should be translated
    to "polar(1, 1.5707963267949)" internally.

    Note, however, that the floating point representation of pi used in this
    module is far from exact. So, instead of yielding "0+i" as a result, the
    above example will be "-3.49148336110938e-015+i". Of course,
    -3.49148336110938e-015 is as close to a real zero as you'll get, but
    testing for equality with the "==" operator will break.

AUTHOR
    Copyright (C) 2004-2007 Steffen Mueller

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

    You may contact the author at symbolic-module at steffen-mueller dot net

    Please send feedback, bug reports, and support requests to the
    Math::Symbolic support mailing list: math-symbolic-support at lists dot
    sourceforge dot net. Please consider letting us know how you use
    Math::Symbolic. Thank you.

    If you're interested in helping with the development or extending the
    module's functionality, please contact the developers' mailing list:
    math-symbolic-develop at lists dot sourceforge dot net.

SEE ALSO
    New versions of this module can be found on http://steffen-mueller.net
    or CPAN.

    You should definately be familiar with Math::Complex before you start
    using this module because the objects that are returned from
    "$formula-"value()> calls are Math::Complex objects.

    Also have a look at Math::Symbolic, and at Math::Symbolic::Parser

    Refer to Math::SymbolicX::ParserExtensionFactory for the implementation
    details.