doc support

2014-04-21 11:14:18 +01:00
parent 83ec7d9072
commit 137f69ed22
19 changed files with 1476 additions and 647 deletions
--- a/C/arith0.c
+++ b/C/arith0.c
@@ -18,8 +18,72 @@
 static char     SccsId[] = "%W% %G%";
 #endif

-/*
- * This file implements arithmetic operations 
+/**
+   @file arith0.c
+
+   @defgroup arithmetic_operators Arithmetic Functions
+   @ingroup arithmetic
+
+  YAP implements several arithmetic functions.  Arithmetic expressions
+  in YAP may use the following operators:
+
+   - <b>pi [ISO]</b><p> @anchor pi_0
+
+     An approximation to the value of <em>pi</em>, that is, the ratio of a circle's circumference to its diameter.
+
+   - <b>e</b><p>    @anchor e_0
+
+     Euler's number, the base of the natural logarithms.
+
+   - <b>epsilon</b><p>  @anchor epsilon_0
+
+     The difference between the float `1.0` and the next largest floating point number.
+
+   - <b>inf</b><p>  @anchor inf_0
+
+     Infinity according to the IEEE Floating-Point standard. Note that evaluating this term will generate a domain error in the `iso` language mode.
+
+     Note also that YAP supports `+inf` and  `-inf`
+
+   - <b>nan (not a number)</b><p>  @anchor nan_0
+
+     Not-a-number according to the IEEE Floating-Point standard. Note that evaluating this term will generate a domain error in the `iso` language mode.
+
+   - <b>random</b><p>  @anchor random_0
+
+     A "random" floating point number between 0 and 1.
+
+   - <b>cputime</b><p>  @anchor cputime_0
+
+     CPU time since YAP was invoked, in seconds.
+
+   - <b>heapused</b><p>  @anchor heapused_0
+
+     Heap (data-base) space used, in bytes.
+
+   - <b>local</b><p>  @anchor local_0
+
+     Local stack in use, in bytes
+
+   - <b>$b</b><p>  @anchor b_0
+
+     current choicepoint
+
+   - <b>$env</b><p>  @anchor env_0
+
+     Environment
+
+   - <b>$tr</b><p>  @anchor tr_0
+
+     Trail in use
+
+   - <b>$free_stack</b><p>  @anchor free_stack_0
+     
+     Amount of free stack space, that is, free space between global and local stacks.
+
+   - <b>global</b><p>  @anchor global_0
+
+     Global stack in use, in bytes.
 *
 */

@@ -89,7 +153,7 @@ eval0(Int fi) {
    }
  case op_nan:
    {
-#ifdef _MSC_VER /* Microsoft's Visual C++ Compiler */
+#ifdef _MSC_VER /* Microsoft's Visual C++ Compi<ler */
      Yap_Error(TYPE_ERROR_EVALUABLE, TermNil, "evaluating infinity");
      P = (yamop *)FAILCODE;
      RERROR();
@@ -112,40 +176,62 @@ eval0(Int fi) {
      RFLOAT((Float)Yap_cputime()/1000.0);
    }
  case op_heapused:
+    /// - heapused
+    ///   Heap (data-base) space used, in bytes.
+    ///
    RINT(HeapUsed);
  case op_localsp:
+    /// - local
+    ///   Local stack in use, in bytes
+    ///
 #if YAPOR_SBA
    RINT((Int)ASP);
 #else
    RINT(LCL0 - ASP);
 #endif
  case op_b:
+    /// - $b
+    ///   current choicepoint
+    ///
 #if YAPOR_SBA
    RINT((Int)B);
 #else
    RINT(LCL0 - (CELL *)B);
 #endif
  case op_env:
+    /// - $env
+    ///   Environment
+    ///
 #if YAPOR_SBA
    RINT((Int)YENV);
 #else
    RINT(LCL0 - YENV);
 #endif
  case op_tr:
+    /// - $tr
+    ///   Trail in use
+    ///
 #if YAPOR_SBA
    RINT(TR);
 #else
    RINT(((CELL *)TR)-LCL0);
 #endif
  case op_stackfree:
+    /// - $free_stack
+    ///   
+    /// Not-a-number according to the IEEE Floating-Point standard. Note that evaluating this term will generate a domain error in the `iso` language mode.
    RINT(Unsigned(ASP) - Unsigned(HR));
  case op_globalsp:
+    /// - global
+    ///   Global stack in use, in bytes.
+    ///
 #if YAPOR_SBA
    RINT((Int)HR);
 #else
    RINT(HR - H0);
 #endif
  }
+  /// end of switch
  RERROR();
 }

@@ -210,3 +296,4 @@ Yap_ReInitConstExps(void)
  return TRUE;
 }

+/// @}
--- a/C/arith1.c
+++ b/C/arith1.c
@@ -18,10 +18,212 @@
 static char     SccsId[] = "%W% %G%";
 #endif

-/*
- * This file implements unary arithmetic operations in YAP
- *
- */
+/**
+   @file arith1.c
+   
+   @addtogroup arithmetic_operators
+   
+  - <b>exp( _X_) [ISO]</b><p> @anchor exp_1
+
+    Natural exponential.
+
+  - <b>log( _X_) [ISO]</b><p> @anchor log_1
+
+    Natural logarithm.
+
+  - <b>log10( _X_)</b><p> @anchor log10_1
+
+    Decimal logarithm.
+
+  - <b>sqrt( _X_) [ISO]</b><p> @anchor sqrt_1
+
+    Square root.
+
+  - <b>sin( _X_) [ISO]</b><p> @anchor sin_1
+
+    Sine.
+
+  - <b>cos( _X_) [ISO]</b><p> @anchor cos_1
+
+    Cosine.
+
+  - <b>tan( _X_) [ISO]</b><p> @anchor tan_1
+
+    Tangent.
+
+  - <b>asin( _X_) [ISO]</b><p> @anchor asin_1
+
+    Arc sine.
+
+  - <b>acos( _X_) [ISO]</b><p> @anchor acos_1
+
+    Arc cosine.
+
+  - <b>atan( _X_) [ISO]</b><p> @anchor atan_1
+
+    Arc tangent.
+
+  - <b>sinh( _X_)</b><p> @anchor sinh_1
+
+    Hyperbolic sine.
+
+  - <b>cosh( _X_)</b><p> @anchor cosh_1
+
+    Hyperbolic cosine.
+
+  - <b>tanh( _X_)</b><p> @anchor tanh_1
+
+    Hyperbolic tangent.
+
+  - <b>asinh( _X_)</b><p> @anchor asinh_1
+
+    Hyperbolic arc sine.
+
+  - <b>acosh( _X_)</b><p> @anchor acosh_1
+
+    Hyperbolic arc cosine.
+
+  - <b>atanh( _X_)</b><p> @anchor atanh_1
+
+    Hyperbolic arc tangent.
+
+  - <b>lgamma( _X_)</b><p> @anchor lgamma_1
+
+    Logarithm of gamma function.
+
+  - <b>erf( _X_)</b><p> @anchor erf_1
+
+    Gaussian error function.
+
+  - <b>erfc( _X_)</b><p> @anchor erfc_1
+
+    Complementary gaussian error function.
+
+  - <b>random( _X_) [ISO]</b><p> @anchor random_1_op
+
+    An integer random number between 0 and  _X_.
+
+    In `iso` language mode the argument must be a floating
+    point-number, the result is an integer and it the float is equidistant
+    it is rounded up, that is, to the least integer greater than  _X_.
+
+  - <b>integer( _X_)</b><p> @anchor integer_1_op
+
+    If  _X_ evaluates to a float, the integer between the value of  _X_ and 0 closest to the value of  _X_, else if  _X_ evaluates to an 
+    integer, the value of  _X_.
+
+  - <b>float( _X_) [ISO]</b><p> @anchor float_1_op
+
+    If  _X_ evaluates to an integer, the corresponding float, else the float itself.
+
+  - <b>float_fractional_part( _X_) [ISO]</b><p> @anchor float_fractional_part_1
+
+    The fractional part of the floating point number  _X_, or `0.0` if  _X_ is an integer. In the `iso` language mode,  _X_ must be an integer.
+
+  - <b>float_integer_part( _X_) [ISO]</b><p> @anchor float_integer_part_1
+
+    The float giving the integer part of the floating point number  _X_, or  _X_ if  _X_ is an integer. In the `iso` language mode,  _X_ must be an integer.
+
+  - <b>abs( _X_) [ISO]</b><p> @anchor abs_1
+
+    The absolute value of  _X_.
+
+  - <b>ceiling( _X_) [ISO]</b><p> @anchor ceiling_1
+
+    The integer that is the smallest integral value not smaller than  _X_.
+
+    In `iso` language mode the argument must be a floating point-number and the result is an integer.
+
+  - <b>floor( _X_) [ISO]</b><p> @anchor floor_1
+
+    The integer that is the greatest integral value not greater than  _X_.
+
+    In `iso` language mode the argument must be a floating
+    point-number and the result is an integer.
+
+  - <b>round( _X_) [ISO]</b><p> @anchor round_1
+
+    The nearest integral value to  _X_. If  _X_ is equidistant to two integers, it will be rounded to the closest even integral value.
+
+    In `iso` language mode the argument must be a floating point-number, the result is an integer and it the float is equidistant it is rounded up, that is, to the least integer greater than  _X_.
+
+  - <b>sign( _X_) [ISO]</b><p> @anchor sign_1
+
+    Return 1 if the  _X_ evaluates to a positive integer, 0 it if evaluates to 0, and -1 if it evaluates to a negative integer. If  _X_
+    evaluates to a floating-point number return 1.0 for a positive  _X_, 0.0 for 0.0, and -1.0 otherwise.
+
+  - <b>truncate( _X_) [ISO]</b><p> @anchor truncate_1
+
+    The integral value between  _X_ and 0 closest to _X_.
+
+  - <b>rational( _X_)</b><p> @anchor rational_1_op
+
+    Convert the expression  _X_ to a rational number or integer. The function returns the input on integers and rational numbers. For
+    floating point numbers, the returned rational number exactly represents
+    the float. As floats cannot exactly represent all decimal numbers the
+    results may be surprising. In the examples below, doubles can represent
+    `0.25` and the result is as expected, in contrast to the result of
+    `rational(0.1)`. The function `rationalize/1` gives a more
+    intuitive result.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~prolog
+?- A is rational(0.25).
+
+A is 1 rdiv 4
+?- A is rational(0.1).
+A = 3602879701896397 rdiv 36028797018963968
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+  - <b>rationalize( _X_)</b><p> @anchor rationalize_1
+
+    Convert the expression _X_ to a rational number or integer. The function is
+    similar to [rational/1](@ref rational_1), but the result is only accurate within the
+    rounding error of floating point numbers, generally producing a much
+    smaller denominator. 
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~prolog
+?- A is rationalize(0.25).
+
+A = 1 rdiv 4
+?- A is rationalize(0.1).
+
+A = 1 rdiv 10
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+  - <b>\\  _X_ [ISO]</b><p>
+
+    Integer bitwise negation.
+
+  - <b>msb( _X_)</b><p> @anchor msb_1
+
+    The most significant bit of the non-negative integer  _X_.
+
+  - <b>lsb( _X_)</b><p> @anchor lsb_1
+
+    The least significant bit of the non-negative integer  _X_.
+
+  - <b>popcount( _X_)</b><p> @anchor popcount_1
+
+    The number of bits set to `1` in the binary representation of the non-negative integer  _X_.
+
+  - <b>[ _X_]</b><p>
+
+    Evaluates to  _X_ for expression  _X_. Useful because character
+strings in Prolog are lists of character codes.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.prolog}
+X is Y*10+C-"0"
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+is the same as
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.prolog}
+X is Y*10+C-[48].
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+which would be evaluated as:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.prolog}
+X is Y*10+C-48.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+*/

 #include "Yap.h"
 #include "Yatom.h"
@@ -694,6 +896,7 @@ eval1(Int fi, Term t USES_REGS) {
      RERROR();
    }
  }
+  /// end of switch
  RERROR();
 }

--- a/C/arith2.c
+++ b/C/arith2.c
@@ -18,10 +18,111 @@
 static char     SccsId[] = "%W% %G%";
 #endif

-/*
- * This file implements unary arithmetic operations in YAP
- *
- */
+/**
+
+   @file arith2.c
+
+   @addtogroup arithmetic_operators
+
+These are the binary numeric operators currently supported by YAP.
+
+  - <b> _X_+ _Y_ [ISO]</b><p>
+
+    Sum.
+
+  - <b> _X_- _Y_ [ISO]</b><p>
+
+    Difference.
+
+  - <b> _X_\* _Y_ [ISO]</b><p>
+
+    Product.
+
+  - <b> _X_/ _Y_ [ISO]</b><p>
+
+    Quotient.
+
+  - <b> _X_// _Y_ [ISO]</b><p>
+
+    Integer quotient.
+
+  - <b> _X_ mod  _Y_ [ISO]</b><p> @anchor mod_2
+
+    Integer module operator, always positive.
+
+  - <b> _X_ rem  _Y_ [ISO]</b><p> @anchor rem_2
+
+    Integer remainder, similar to `mod` but always has the same sign as `X`.
+
+  - <b>  _X_ div  _Y_ [ISO]</b><p> @anchor div_2
+
+    Integer division, as if defined by `( _X_ -  _X_ mod  _Y_)//  _Y_`.
+
+  - <b> max( _X_, _Y_) [ISO]</b><p> @anchor max_2
+
+    The greater value of  _X_ and  _Y_.
+
+  - <b> min( _X_, _Y_) [ISO]</b><p> @anchor min_2
+
+    The lesser value of  _X_ and  _Y_.
+
+  - <b> _X_ ^  _Y_ [ISO]</b><p>
+
+     _X_ raised to the power of  _Y_, (from the C-Prolog syntax).
+
+  - <b> exp( _X_, _Y_)</b><p> @anchor exp_2
+
+     _X_ raised to the power of  _Y_, (from the Quintus Prolog syntax).
+
+  - <b> _X_ \*\*  _Y_ [ISO]</b><p>
+
+     _X_ raised to the power of  _Y_  (from ISO).
+
+  - <b> _X_ /\\  _Y_ [ISO]</b><p>
+
+    Integer bitwise conjunction.
+
+  - <b> _X_ \\/  _Y_ [ISO]</b><p>
+
+    Integer bitwise disjunction.
+
+  - <b> _X_ #  _Y_</b><p>
+
+    Integer bitwise exclusive disjunction.
+
+  - <b> _X_ \>\<  _Y_</b><p>
+
+    Integer bitwise exclusive disjunction.
+
+  - <b> xor( _X_ ,  _Y_) [ISO]</b><p> @anchor xor_2
+
+    Integer bitwise exclusive disjunction.
+
+  - <b> _X_ \<\<  _Y_</b><p>
+
+    Integer bitwise left logical shift of  _X_ by  _Y_ places.
+
+  - <b> _X_ \>\>  _Y_ [ISO]</b><p>
+
+    Integer bitwise right logical shift of  _X_ by  _Y_ places.
+
+  - <b> gcd( _X_, _Y_)</b><p> @anchor gcd_2
+
+    The greatest common divisor of the two integers  _X_ and  _Y_.
+
+  - <b> atan( _X_, _Y_)</b><p> @anchor atan_2
+
+    Four-quadrant arc tangent. Also available as `atan2/2`.
+
+  - <b> atan2( _X_, _Y_) [ISO]</b><p> @anchor atan2_2
+
+    Four-quadrant arc tangent.
+
+  - <b>  _X_ rdiv  _Y_ [ISO]</b><p> @anchor rdiv_2
+
+    Rational division.
+
+*/

 #include "Yap.h"
 #include "Yatom.h"
--- a/C/cmppreds.c
+++ b/C/cmppreds.c
@@ -14,6 +14,10 @@
 * comments:	comparing two prolog terms				 *
 *									 *
 *************************************************************************/
+///    @file cmppreds.c
+
+
+
 #ifdef SCCS
 static char     SccsId[] = "%W% %G%";
 #endif
@@ -647,6 +651,17 @@ a_cmp(Term t1, Term t2 USES_REGS)
  }
 }

+/**
+
+   @defgroup arithmetic_cmps Arithmetic Comparison Predicates
+   @ingroup arithmetic
+
+   Comparison of Numeric Expressions. Both arguments must be valid ground expressions at time of call.
+
+   @{
+*/
+
+
 Int
 Yap_acmp(Term t1, Term t2 USES_REGS)
 {
@@ -667,6 +682,15 @@ p_acomp( USES_REGS1 )
  return out;
 }

+/**
+   @class arith_eq_2
+   @brief  =:=/2: Equality of arithmetic expressions
+
+   <b>+ _X_ =:= + _Y_ [ISO]</b><p> @anchor ar_eq_2
+
+
+   The value of the expression  _X_ is less than the value of expression _Y_.
+ */
 static Int 
 a_eq(Term t1, Term t2)
 {
@@ -701,6 +725,15 @@ a_eq(Term t1, Term t2)
  return out == 0;
 }

+/**
+   @class arith_dif_2
+   @brief  =\\=/2: Difference of arithmetic expressions
+
+   <b>+ _X_ =\\= + _Y_ [ISO]</b><p> @anchor ar_dif_2
+
+
+   The value of the expression  _X_ is different from the value of expression _Y_.
+ */
 static Int 
 a_dif(Term t1, Term t2)
 {
@@ -710,6 +743,16 @@ a_dif(Term t1, Term t2)
  return out != 0;
 }

+/**
+   @class arith_gt_2
+   @brief \>/2: Greater than arithmetic expressions
+
+  <b>+ _X_ \> + _Y_ [ISO]</b><p> @anchor qQlg_2
+
+
+  The value of the expression  _X_ is less than or equal to the value
+  of expression  _Y_.
+*/
 static Int 
 a_gt(Term t1, Term t2)
 {				/* A > B		 */
@@ -719,6 +762,16 @@ a_gt(Term t1, Term t2)
  return out > 0;
 }

+/**
+   @class arith_ge_2
+   @brief  \>=/2: Greater than or equal to arithmetic expressions
+
+   <b>+ _X_ \>= + _Y_ [ISO]</b><p> @anchor gGqQ_2
+
+
+   The value of the expression  _X_ is greater than or equal to the
+   value of expression  _Y_.
+*/
 static Int 
 a_ge(Term t1, Term t2)
 {				/* A >= B		 */
@@ -728,6 +781,16 @@ a_ge(Term t1, Term t2)
  return out >= 0;
 }

+/**
+   @class arith_lt_2
+   @brief \</2: Lesser than arithmetic expressions
+
+   <b>+ _X_ \< + _Y_ [ISO]</b><p> @anchor sS_2
+
+
+   The value of the expression  _X_ is less than the value of expression
+   _Y_.
+*/
 static Int 
 a_lt(Term t1, Term t2)
 {				/* A < B       */
@@ -737,6 +800,17 @@ a_lt(Term t1, Term t2)
  return out < 0;
 }

+/**
+ *
+ @class arith_le_2
+ @brief =\</2: Lesser than or equal to arithmetic expressions
+
+ <b>+ _X_ =\< + _Y_ [ISO]</b><p> @anchor qQsS_2
+
+
+ The value of the expression  _X_ is less than or equal to the value
+ of expression  _Y_.
+*/
 static Int 
 a_le(Term t1, Term t2)
 {				/* A <= B */
@@ -746,6 +820,7 @@ a_le(Term t1, Term t2)
  return out <= 0;
 }

+/// @}

 static Int 
 a_noteq(Term t1, Term t2)
--- a/C/eval.c
+++ b/C/eval.c
@@ -18,10 +18,16 @@
 static char     SccsId[] = "%W% %G%";
 #endif

-/*
- * This file implements arithmetic operations 
- *
- */
+/**
+   @file eval.c
+
+   @defgroup arithmetic_preds Arithmetic Predicates
+   @ingroup arithmetic
+
+   @{
+*/
+
+
 #include "Yap.h"
 #include "Yatom.h"
 #include "YapHeap.h"
@@ -184,6 +190,23 @@ BEAM_is(void)

 #endif

+/**
+   @class is_2
+   @anchor is_2
+   @brief evaluation of arithmetic expressions
+
+   <b>? _X_:number is + _Y_:ground is det</b>
+
+   This predicate succeeds iff the result of evaluating the expression
+   _Y_ unifies with  _X_. This is the predicate normally used to
+   perform evaluation of arithmetic expressions:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+X is 2+3*4
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    succeeds with `X = 14`.
+
+*/
+
 static Int
 p_is( USES_REGS1 )
 {				/* X is Y	 */
@@ -204,6 +227,16 @@ p_is( USES_REGS1 )
  return Yap_unify_constant(ARG1,out);
 }

+/**
+   @class isnan_1
+   @anchor isnan_1
+   @brief True if _X_ is not a number
+
+   <b> isnan(? _X_:float) is det</b>
+
+   Interface to the IEE754 `isnan` test.
+*/
+
 static Int
 p_isnan( USES_REGS1 )
 {				/* X is Y	 */
@@ -232,6 +265,17 @@ p_isnan( USES_REGS1 )
  return isnan(FloatOfTerm(out));
 }

+/**
+   @class isinf_1
+   @anchor isinf_1
+   @brief True if _X_ is infinity
+
+   <b> isnan(? _X_:float) is det</b>
+
+   Interface to the IEE754 `isinf` test.
+*/
+
+
 static Int
 p_isinf( USES_REGS1 )
 {                               /* X is Y        */
@@ -260,6 +304,18 @@ p_isinf( USES_REGS1 )
  return isinf(FloatOfTerm(out));
 }

+/**
+   @class logsum_3
+   @anchor logsum_3
+   @brief sum of two logarithms
+
+   <b> logsum(+ _Log1_, + _Log2_, - _Out_ ) is det </b>
+
+True if  _Log1_ is the logarithm of the positive number  _A1_,
+ _Log2_ is the logarithm of the positive number  _A2_, and
+ _Out_ is the logarithm of the sum of the numbers  _A1_ and
+ _A2_. Useful in probability computation.
+*/
 static Int
 p_logsum( USES_REGS1 )
 {                               /* X is Y        */
@@ -391,6 +447,25 @@ static Int cont_between( USES_REGS1 )
  }
 }

+/**
+   @class between_3
+   @anchor between_3
+   @brief sequence of numbers
+
+   between(+ _Low_:int, + _High_:int, ? _Value_:int) is nondet
+
+   _Low_ and  _High_ are integers,  _High_ \>= _Low_. If
+   _Value_ is an integer,  _Low_ =\< _Value_
+   =\< _High_. When  _Value_ is a variable it is successively
+   bound to all integers between  _Low_ and  _High_. If
+   _High_ is inf or infinite [between/3](@ref between_3) is true iff
+   _Value_ \>=  _Low_, a feature that is particularly interesting
+   for generating integers from a certain value.
+
+   @}
+
+*/
+
 static Int
 init_between( USES_REGS1 )
 {