/* PFE Extensions:  Public types, prototypes, and macros for
                    IEEE floating-point word set
          Version:  0.6.2
             File:  ieeefp-ext.h
           Author:  David N. Williams
          License:  LGPL
          Revised:  May 29, 2009
                    October 2, 2009
                    August 13,19,28-30, 2020
                    September 2,4, 2020
*/
/*
 * Copyright (C) 2005, 2009, 2020 David N. Williams
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later
 * version.
 *
 * This library is distributed in the hope that it will be
 * useful, but WITHOUT ANY WARRANTY; without even the implied
 * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
 * PURPOSE.  See the GNU Library General Public License for more
 * details.
 *
 * You should have received a copy of the GNU Lesser General
 * Public License along with this library; if not, write to the
 * Free Software Foundation, 59 Temple Place, Suite 330, Boston,
 * MA 02111-1307 USA.
 *
 * If you take advantage of the option in the LGPL to put a
 * particular version of this library under the GPL, the author
 * would regard it as polite if you would put any direct
 * modifications under the LGPL as well, and include a copy of
 * this request near the beginning of the modified library
 * source.  A "direct modification" is one that enhances or
 * extends the library in line with its original concept, as
 * opposed to developing a distinct application or library which
 * might use it.
 */

#ifndef _PFE_IEEEFP_EXT_H 
#define _PFE_IEEEFP_EXT_H

/****************************************************************/
/* IEEE special constants                                       */
/****************************************************************/

extern P4_CODE (p4_plus_inf);
extern P4_CODE (p4_minus_inf);
extern P4_CODE (p4_plus_nan);
extern P4_CODE (p4_minus_nan);

/****************************************************************/
/* elementary functions new in C99				*/
/****************************************************************/

/** F*+  (f: x y z -- y*z+x )
 */
extern P4_CODE (p4_f_star_plus);

/** FCBRT  (f: x -- x^[1/3] )
 */
extern P4_CODE (p4_f_cbrt);

/** FDIM  (f: x y -- x-y | +0 )
 */
extern P4_CODE (p4_f_dim);

/** FEXP2  (f: x -- 2^x )
 */
extern P4_CODE (p4_f_exp2);

/** FLOG2  (f: x -- log.base.2[x] )
 */
extern P4_CODE (p4_f_log2);

/** FERF  (f: x -- erf[x] )
 */
extern P4_CODE (p4_f_erf);

/** FERFC  (f: x -- 1-erf[x] )
 */
extern P4_CODE (p4_f_erfc);

/** FGAMMA  (f: x -- gamma[x] )
 */
extern P4_CODE (p4_f_gamma);

/** FLNGAMMA  (f: x -- ln[gamma[x]] )
 */
extern P4_CODE (p4_f_ln_gamma);

/****************************************************************/
/* nearest integer functions					*/
/****************************************************************/

/** FCEIL  (f: r1 -- r2 )    
 */
extern P4_CODE (p4_fceil);

/** FNEARBYINT  (f: r1 -- r2 )    
 */
extern P4_CODE (p4_fnearbyint);

/****************************************************************/
/* floating-point auxiliary functions				*/
/****************************************************************/

/** FCLASSIFY (f: x -- s: type )
 * Return the appropriate value FP_INFINITE, FP_NAN, FP_NORMAL,
 * FP_SUBNORMAL, or FP_ZERO provided by the host C99 compiler. 
 * The corresponding Forth constants are FP-INFINITE, etc.
 */
extern P4_CODE (p4_fclassify);

/** FINITE? (f: x -- s: flag )
 */
extern P4_CODE (p4_finite_q);

/** FINFINITE? (f: x -- s: flag )
 */
extern P4_CODE (p4_finfinite_q);

/** FNAN? (f: x -- s: flag )
 */
extern P4_CODE (p4_fnan_q);

/** FNORMAL? (f: x -- s: flag )
 */
extern P4_CODE (p4_fnormal_q);

/** FSUBNORMAL? (f: x -- s: flag )
 */
extern P4_CODE (p4_fsubnormal_q);

/** FCOPYSIGN  (f: x y -- |x|*sgn[y] )
 */
extern P4_CODE (p4_fcopysign);

/** FNEXTAFTER (f: x y -- x.next )
 * Return the next machine representable number after x in the y
 * direction.
 */
extern P4_CODE (p4_fnextafter);

/** FSIGNBIT (f: x -- s: minus? )
 */
extern P4_CODE (p4_fsignbit);

/** FREXP  (f: x -- frac s: n )
 * Return the fractional part of x as a floating point number,
 * frac = 0.0 or 0.5 <= frac < 1.0, and the power n such that
 * frac*2^n = x.
 */
extern P4_CODE (p4_frexp);

/** FNEXTUP    (f: r1 -- r2 )
 *  FNEXTDOWN  (f: r1 -- r2 )
 * When r1 is a nonzero real number, FNEXTUP returns the next
 * affinely extended real in the default format that compares
 * larger than r1, and FNEXTDOWN returns the next one that
 * compares less than r1.  See IEEE 754-2008 5.3.1, "General
 * operations" for the behavior when r1 is an IEEE special.
 */
extern P4_CODE (p4_fnextup);
extern P4_CODE (p4_fnextdown);

/** FSCALBN  (f: x s: n -- f: x*2^n )
 */
extern P4_CODE (p4_fscalbn);

/** FMODF  (f: x -- frac integ )
 * Return the integer part of x as a double, and the fractional
 * part f of x with |f| < 1, both having the same sign as x, so
 * that x = frac + integ.
 */
extern P4_CODE (p4_fmodf);

/** FMODFD  (f: x -- frac s: d )
 * A version of MODF that returns the integer part as a
 * double-cell signed integer.  Not in C99.
 * TENTATIVE!
 */
extern P4_CODE (p4_fmodfd);

/** FLOGB  (f: x -- f: b.exponent )
 * Leave the exponent (radix b = FLT_RADIX) of the
 * floating-point representation.
 */
extern P4_CODE (p4_flogb);

/** FILOGB  (f: x -- s: b.exponent )
 * Leave the exponent (radix b = FLT_RADIX) of the
 * floating-point representation, with special values:
 *    x      exp
 *    0.0    FP_ILOGB0
 *    Inf    INT_MAX
 *   -Inf    INT_MAX
 *    Nan    FP_ILOGBNAN
 * The special output constants are defined elsewhere with Forth
 * names FP-ILOGB0, FP-ILOGBNAN, INT-MAX.
 */
extern P4_CODE (p4_filogb);


/****************************************************************/
/* floating point text format              					*/
/****************************************************************/

extern P4_CODE (p4_fh_dot);
extern P4_CODE (p4_to_ieeefloat);

/****************************************************************/
/* floating-point environment					*/
/****************************************************************/

/** /FENV  ( -- fenv_t.size )
 */

/** FE-DFL-ENV  ( -- default.env )
 */

/** FEGETENV  ( fenvp -- )
 * Store current floating-point environment at fenvp.
 */
extern P4_CODE (p4_fegetenv);

/** FESETENV  ( fenvp -- )
 * Set the floating-point environment to that pointed to by
 * fenvp.
 */
extern P4_CODE (p4_fesetenv);

/** FEHOLDEXCEPT  ( -- fenvp )
 * Leave the current floating-point environment pointer for
 * later restoration, and install an environment that turns off
 * floating-point exceptions.
 */
extern P4_CODE (p4_feholdexcept);

/** FEUPDATEENV  ( fenvp -- )
 * Set the floating-point environment to that pointed to by
 * fenvp, and raise the exceptions that were up just before the
 * call.
 */
extern P4_CODE (p4_feupdateenv);

/****************************************************************/
/* floating-point exception flags				*/
/****************************************************************/

/** GET-FFLAGS  ( excepts -- flags )
 * The flags output is the bitwise OR of the fp exception
 * constants corresponding to those flags that are both on in
 * the current fp state and present in excepts.
 */
extern P4_CODE (p4_get_fflags);

/** SET-FFLAGS  ( excepts -- )
 * Turn on the fp exception status flags corresponding to the fp
 * exceptions present in excepts.
 */
extern P4_CODE (p4_set_fflags);

/** CLEAR-FFLAGS ( excepts -- )
 * Clear the fp exception status flags corresponding to the fp
 * exceptions present in excepts.
 */
extern P4_CODE (p4_clear_fflags);

/****************************************************************/
/* floating-point rounding modes				*/
/****************************************************************/

/** GET-FROUND  ( -- round )
 * Leave the current rounding mode value.
 */
extern P4_CODE (p4_get_fround);

/** SET-FROUND  ( round --  )
 * Set the current rounding mode to round.
 */
extern P4_CODE (p4_set_fround);

/****************************************************************/
/* alternate floating-point exception handling			*/
/****************************************************************/

/** (FENABLE)   ( excepts -- )
 ** (FDISABLE)  ( excepts -- )
 */
extern P4_CODE (p4_paren_fenable);
extern P4_CODE (p4_paren_fdisable);


/** FEGETEXCEPT  ( -- excepts )
 * Leave the excepts corresponds to the fp exceptions currently
 * enabled for alternate handling.
 */
extern P4_CODE (p4_fegetexcept);

/** FEENABLEEXCEPT  ( excepts -- excepts.old )
 * Enable the exceptions in excepts for alternate handling, and
 * leave the previously enabled exceptions as excepts.old
 */
extern P4_CODE (p4_feenableexcept);

/** FENABLE  ( excepts -- )
 * Enable the fp exceptions in excepts for alternate handling,
 * after first clearing all fp exception status flags.
 */
extern P4_CODE (p4_fenable);

/** FEDISABLEEXCEPT  ( excepts -- excepts.old )
 * Disable the exceptions in excepts for alternate handling, and
 * leave the previously enabled exceptions as excepts.old.
 */
extern P4_CODE (p4_fedisableexcept);

/** FDISABLE  ( excepts -- )
 * Disable the fp exceptions in excepts for alternate handling,
 * after first clearing all fp exception status flags.
 */
extern P4_CODE (p4_fdisable);

/** SET-FHANDLER  ( xt -- )
 * Set the fp exception handler to use xt when enabled.  If
 * alternate handling is enabled and an fp exception occurs, xt
 * will be executed with the appropriate ANS Forth fp throw code
 * topmost on the data stack, possibly followed by other
 * implementation-defined data.  An ambiguous condition exists
 * if execution does not end by peforming THROW on the throw
 * code.  The default is the xt of THROW, which is initialized by
 * INSTALL-FHANDLING.
 */
extern P4_CODE (p4_set_fhandler);

/** GET-FHANDLER  ( -- xt|0 )
 * Return the last xt|0 that was set by SET-FHANDLER, or zero if
 * SET-FHANDLER has not been executed.
 */
extern P4_CODE (p4_get_fhandler);

/** INSTALL-FHANDLING  ( -- )
 * Establish the alternate fp exception handler, and initialize
 * the xt it executes to that of THROW.  Thereafter the handler
 * will fire on a floating-point exception, if alternate fp
 * handling is enabled.  This word is executed when the ieeefp
 * extensions word set is loaded.  It may also be executed by an
 * application, which may be necessary on some systems after an
 * ABORT, to reestablish the handler.
 *
 * In pfe, INSTALL-FHANDLING is in the ENVIRONMENT word set,
 * which is not in the default search order.
 */
extern P4_CODE (p4_install_fhandling);

#endif	/* ifndef _PFE_IEEEFP_EXT_H */