--  -----------------------------------------------------------------------
--  Title:       double_algebraic_functions
--  Last Mod:    Fri Jun  7 12:57:30 1991
--  Author:      Vincent Broman <broman@nosc.mil>
--  Visibility:  withed by generic_algebraic_functions
--		 and double_elementary_functions.
--  Description: 
--		 This package provides certain algebraic functions
--		 of general utility on floating point types, viz.
--		 square, cube, square_root, cube_root, nth_root,
--		 hypot, complement, sec_to_tan, tan_to_sec, min, and max,
--		 as these are individually defined below.
--		 
--		 The rules for accuracy, exceptions, etc are analogous
--		 to those for generic_elementary_functions, except as
--		 deviations are noted below.  Unless otherwise specified,
--		 the relative accuracy of the function results must be
--		 2.0 * double'base'epsilon or better.
--		 
--  Exceptions:  Argument_error is raised if and only if the argument to a
--		 function falls outside the mathematical domain of the function.
--		 The exception which signals floating point overflow
--		 is raised only if some of the values permitted by the
--		 relative accuracy requirements for a function result
--		 exceed double'safe_large.
--		 Only square and hypot may overflow.
--  -----------------------------------------------------------------------
with algebraic_functions_exceptions,
     float_types;

use float_types;

package double_algebraic_functions is
-- 
   
   function square( x: in double) return double;
-- 
-- Returns x * x, 
-- to an accuracy satisfying the Ada model of floating point numbers.
-- 
   
   function cube( x: in double) return double;
-- 
-- Returns x * x * x, 
-- to an accuracy satisfying the Ada model of floating point numbers.
-- 

   function square_root( x: in double) return double;
-- 
-- Returns the nonnegative square root of x,
-- or raises argument_error for negative x.
-- square_root( 0.0) = 0.0
-- 

   function cube_root( x: in double;
		       y: in double := 0.0) return double;
--
-- Returns (exactly) the greatest real root, t, of the cubic equation:
-- t**3 = xx + yy*t, for some xx and yy which approximate x and y
-- to a relative accuracy of TBD * double'base'epsilon.
-- cube_root( 0.0, y) = 0.0 for y <= 0.0 .
-- 
-- Function cube_root is discontinuous near the curve
-- (x/2)**2 = (y/3)**3, x <= 0.
-- 
-- It is conjectured that the cube_root function and the rational
-- operations in package standard are sufficient to accurately compute
-- real roots of any real polynomial of degree up to four in a finite number
-- of steps, the number of steps being independent of the accuracy required.
--

   function nth_root( x: in double;
		      n: in positive) return double;
--
-- Returns the nth root of x,
-- the positive root being chosen in case n is even.
-- nth_root( 0.0, n) = 0.0 and nth_root( 1.0, n) = 1.0, for all n.
-- Argument_error is raised iff n is even and x negative.
--

   function hypot( x, y: in double) return double;
-- 
-- Returns the nonnegative square root of x**2 + y**2,
-- overflowing only if the final result makes it necessary.
-- hypot( x, 0.0) = abs( x)
-- hypot( 0.0, y) = abs( y)
-- 

   function hypot( x, y, z: in double) return double;
--
-- Returns the nonnegative square root of x**2 + y**2 + z**2,
-- overflowing only if the final result makes it necessary.
-- hypot( x, 0.0, 0.0) = abs( x)
-- hypot( 0.0, y, 0.0) = abs( y)
-- hypot( 0.0, 0.0, z) = abs( z)
-- 
   
   function complement( x: in double) return double;
--
-- Returns the nonnegative square root of (1 - x**2) if abs( x) <= 1.0,
-- raising argument_error otherwise.
-- complement(  1.0) = 0.0
-- complement( -1.0) = 0.0
-- complement(  0.0) = 1.0
--

   function sec_to_tan( x: in double) return double;
--
-- Returns the nonnegative square root of (x**2 - 1) if abs( x) >= 1.0,
-- otherwise raises argument_error.
-- Must never overflow.
-- sec_to_tan(  1.0) = 0.0
-- sec_to_tan( -1.0) = 0.0
--

   function tan_to_sec( x: in double) return double;
--
-- Returns the positive square root of (x**2 + 1).
-- Must never overflow.
-- tan_to_sec( 0.0) = 1.0
-- 

   function min( x, y: in double) return double;
--
-- Returns either x or y, choosing the minimum of the two,
-- where minimum means that some point in the safe interval
-- for the number chosen is less than or equal to some point
-- in the safe interval for the other number.
-- If the intervals overlap, the choice is implementation dependent.
--

   function min( x, y, z: in double) return double;
--
-- Returns either x or y or z, choosing the minimum of the three,
-- where minimum means that some point in the safe interval
-- for the number chosen is less than or equal to some point
-- in the safe intervals for each of the other two numbers.
-- If the intervals overlap, the choice is implementation dependent.
--

   function max( x, y: in double) return double;
--
-- Returns either x or y, choosing the maximum of the two,
-- where maximum means that some point in the safe interval
-- for the number chosen is greater than or equal to some point
-- in the safe interval for the other number.
-- If the intervals overlap, the choice is implementation dependent.
--

   function max( x, y, z: in double) return double;
--
-- Returns either x or y or z, choosing the maximum of the three,
-- where maximum means that some point in the safe interval
-- for the number chosen is greater than or equal to some point
-- in the safe intervals for each of the other two numbers.
-- If the intervals overlap, the choice is implementation dependent.
--


   argument_error: exception renames
      algebraic_functions_exceptions.argument_error;
--
-- exception raised if and only if the argument to a function
-- falls outside the function's mathematical domain.
--

private

   pragma inline( square);
   pragma inline( cube);
   pragma inline( min);
   pragma inline( max);

end double_algebraic_functions;

-- $Header: d_algebraic_functions_s.a,v 3.25 91/06/07 13:15:11 broman Rel $