Number::Fraction(3pm)					User Contributed Perl Documentation				     Number::Fraction(3pm)

NAME

       Number::Fraction - Perl extension to model fractions

SYNOPSIS

	 use Number::Fraction;

	 my $f1 = Number::Fraction->new(1, 2);
	 my $f2 = Number::Fraction->new('1/2');
	 my $f3 = Number::Fraction->new($f1); # clone
	 my $f4 = Number::Fraction->new; # 0/1

       or

	 use Number::Fraction ':constants';

	 my $f1 = '1/2';
	 my $f2 = $f1;

	 my $one = $f1 + $f2;
	 my $half = $one - $f1;
	 print $half; # prints '1/2'

ABSTRACT

       Number::Fraction is a Perl module which allows you to work with fractions in your Perl programs.

DESCRIPTION

       Number::Fraction allows you to work with fractions (i.e. rational numbers) in your Perl programs in a very natural way.

       It was originally written as a demonstration of the techniques of overloading.

       If you use the module in your program in the usual way

	 use Number::Fraction;

       you can then create fraction objects using "Number::Fraction-"new> in a number of ways.

	 my $f1 = Number::Fraction->new(1, 2);

       creates a fraction with a numerator of 1 and a denominator of 2.

	 my $f2 = Number::Fraction->new('1/2');

       does the same thing but from a string constant.

	 my $f3 = Number::Fraction->new($f1);

       makes $f3 a copy of $f1

	 my $f4 = Number::Fraction->new; # 0/1

       creates a fraction with a denominator of 0 and a numerator of 1.

       If you use the alterative syntax of

	 use Number::Fraction ':constants';

       then Number::Fraction will automatically create fraction objects from string constants in your program. Any time your program contains a
       string constant of the form "d+/d+" then that will be automatically replaced with the equivalent fraction object. For example

	 my $f1 = '1/2';

       Having created fraction objects you can manipulate them using most of the normal mathematical operations.

	 my $one = $f1 + $f2;
	 my $half = $one - $f1;

       Additionally, whenever a fraction object is evaluated in a string context, it will return a string in the format x/y. When a fraction
       object is evaluated in a numerical context, it will return a floating point representation of its value.

       Fraction objects will always "normalise" themselves. That is, if you create a fraction of '2/4', it will silently be converted to '1/2'.

   Experimental Support for Exponentiation
       Version 1.13 of Number::Fraction adds experimental support for exponentiation operations. If a Number::Fraction object is used as the left
       hand operand of an exponentiation expression then the value returned will be another Number::Fraction object - if that makes sense. In all
       other cases, the expression returns a real number.

       Currently this only works if the right hand operand is an integer (or a Number::Fraction object that has a denominator of 1). Later I hope
       to extend this so support so that a Number::Fraction object is returned whenever the result of the expression is a rational number.

       For example:

	 '1/2' ** 2 #	Returns a Number::Fraction ('1/4')
	 '2/1' ** '2/1' Returns a Number::Fraction ('4/1')
	 '2/1' ** '1/2' Returns a real number (1.414213)
	  0.5  ** '2/1' Returns a real number (0.25)

METHODS

   import
       Called when module is "use"d. Use to optionally install constant handler.

   unimport
       Be a good citizen and uninstall constant handler when caller uses "no Number::Fraction".

   new
       Constructor for Number::Fraction object. Takes the following kinds of parameters:

       o   A single Number::Fraction object which is cloned.

       o   A string in the form 'x/y' where x and y are integers. x is used as the numerator and y is used as the denominator of the new object.

       o   Two integers which are used as the numerator and denominator of the new object.

       o   A single integer which is used as the numerator of the the new object.  The denominator is set to 1.

       o   No arguments, in which case a numerator of 0 and a denominator of 1 are used.

       Returns "undef" if a Number::Fraction object can't be created.

   to_string
       Returns a string representation of the fraction in the form "numerator/denominator".

   to_num
       Returns a numeric representation of the fraction by calculating the sum numerator/denominator. Normal caveats about the precision of
       floating point numbers apply.

   add
       Add a value to a fraction object and return a new object representing the result of the calculation.

       The first parameter is a fraction object. The second parameter is either another fraction object or a number.

   mult
       Multiply a fraction object by a value and return a new object representing the result of the calculation.

       The first parameter is a fraction object. The second parameter is either another fraction object or a number.

   subtract
       Subtract a value from a fraction object and return a new object representing the result of the calculation.

       The first parameter is a fraction object. The second parameter is either another fraction object or a number.

   div
       Divide a fraction object by a value and return a new object representing the result of the calculation.

       The first parameter is a fraction object. The second parameter is either another fraction object or a number.

   exp
       Raise a Number::Fraction object to a power.

       The first argument is a number fraction object. The second argument is another Number::Fraction object or a number. If the second argument
       is an integer or a Number::Fraction object containing an integer then the value returned is a Number::Fraction object, otherwise the value
       returned is a real number.

   abs
       Returns a copy of the given object with both the numerator and denominator changed to positive values.

   EXPORT
       None by default.

SEE ALSO

       perldoc overload

AUTHOR

       Dave Cross, <dave@mag-sol.com>

COPYRIGHT AND LICENSE

       Copyright 2002-8 by Dave Cross

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

perl v5.14.2							    2011-11-26						     Number::Fraction(3pm)