view release on metacpan or  search on metacpan

lib/Math/Taylor.pm  view on Meta::CPAN

=head2 Methods

=over 2

=cut

=item Constructor new(OPTION => ARGUMENT)

new() is the constructor for Math::Taylor objects. It takes key => value
style named arguments. Valid options are 'function', 'variable', 'point'
and 'remainder_type'.

new() may be called as a class method (C<Math::Taylor->new(...)> to create
an object from scratch or on an existing object to clone the object. In that
case, the function and variable objects are I<deeply cloned>. (If you don't
know what that means, rest assured that it's the sane behaviour.) If you
use key => value pairs to set attributes, these overwrite the attributes
copied from the prototype.

Any Math::Taylor object requires that at least a function attribute is defined.
that means, if you create objects from scratch, you have to specify
a C<function => $ms_tree> attribute.

Details on the attributes of the Math::Taylor objects can be learned from the
documentation of the accessor methods for these attributes (below).

new() returns a Math::Taylor object.

=cut

sub new {
    my $proto = shift;
    my $class = ref($proto) || $proto;

    confess "Math::Taylor called with uneven number of arguments."
      if @_ % 2;

    my %args = @_;

    # function to approximate,
    # variable of the function
    # point to approximate about
    my $self = {
        function       => undef,
        variable       => $Default_Variable,
        point          => $Default_Point,
        remainder_type => $Default_Remainder_Type,
    };

    # Clone prototype if applicable.
    if ( ref($proto) ) {
        $self->{function} = $proto->{function}->new();
        $self->{variable} = $proto->{variable}->new()
          if defined $proto->{variable};
        $self->{point} = $proto->{point} if defined $proto->{point};
        $self->{remainder_type} = $proto->{remainder_type}
          if defined $proto->{remainder_type};
    }

    bless $self => $class;

    $self->function( $args{function} ) if exists $args{function};
    $self->variable( $args{variable} ) if exists $args{variable};
    $self->point( $args{point} )       if exists $args{point};

    confess "Cannot create a Math::Taylor object without at least a function."
      if not defined $self->function();

    return $self;
}

=item Accessor function()

This accessor can be used to get or set the function to approximate through the
Math::Taylor object.

Called with no arguments, the method just returns the Math::Symbolic tree that
internally represents the function.

Called with an argument, the first argument is treated as a new function for
the approximation and the corresponding attribute is set. The function may be
specified in one of two formats: Either as a Math::Symbolic tree or as a string
which will be parsed as a Math::Symbolic tree. For details on the syntax of
such strings, please refer to L<Math::Symbolic> and L<Math::Symbolic::Parser>.
it should, however be relatively straighforward. A few examples:

  $taylor->function('sin(x)^2/x'); # (square of the sine of x) divided by x
  my $func = $taylor->function();  # returns the tree for the above
  print $func."\n";                # print out the function
  $taylor->function($anotherfunc); # set the function differently

Please note that when setting the function to an existing Math::Symbolic tree,
the tree is I<not> cloned. If you modify the tree thereafter, the modifications
will propagate to the function in the Math::Taylor object. This is not a bug,
it is a documented feature and wanted action-at-a-distance.

When using function() to access the function attribute, the Math::Symbolic tree
is not cloned either.

=cut

sub function {
    my $self = shift;
    if ( not @_ ) {
        return $self->{function};
    }
    my $function = shift;

    if ( not defined $function ) {
        confess "Won't set the function of a Math::Taylor object to 'undef'.\n";
    }
    elsif ( ref($function) =~ /^Math::Symbolic/ ) {
        $self->{function} = $function;
    }
    elsif ( not ref($function) ) {
        my $parsed;
        eval { $parsed = parse_from_string($function); };
        if (   $@
            or not defined $parsed
            or not ref($parsed) =~ /^Math::Symbolic/ )