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)

   Version 2: Now With Added Moose
       Version 2 of Number::Fraction has been reimplemented using Moose. You should see very
       little difference in the way that the class works. The only difference I can see is that
       "new" used to return "undef" if it couldn't create a valid object from its arguments, it
       now dies. If you aren't sure of the values that are being passed into the constructor,
       then you'll want to call it within an "eval { ... }" block (or using something equivalent
       like Try::Tiny).

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".

   BUILDARGS
       Parameter massager for Number::Fraction object. Takes the following kinds of parameters:

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

       •   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.

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

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

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

       Dies if a Number::Fraction object can't be created.

   BUILD
       Object initialiser for Number::Fraction. Ensures that fractions are in a normalised
       format.

   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.