<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
]>
<chapter id="language-extensions">
  <title>Language Extensions</title>

  <para>
    These language extensions are provided in the following namespace URI:
    <screen>
http://www.juiblex.co.uk/ns/libxexpr
    </screen>
    People using this namespace are encouraged to use the libxexpr namespace
    prefix.
  </para>

  <sect1 id="libxexpr-pi">
    <title>Function &lt;pi&gt;</title>

    <simplesect>
      <title>Synopsis</title>
	<para>
	  &lt;pi&gt; returns the value of π.
	</para>
    </simplesect>

    <simplesect>
      <title>Arguments</title>
	<para>
	  &lt;pi&gt; takes no arguments.
	</para>
    </simplesect>

    <simplesect>
      <title>Return Values</title>
	<para>
	  &lt;pi&gt; returns the value of π.
	</para>
    </simplesect>

    <example>
      <programlisting>
&lt;libxexpr:pi/&gt; ≅ &lt;float&gt;3.14&lt;/float&gt;<!--
   --></programlisting>
    </example>
  </sect1>

  <sect1 id="libxexpr-sin">
    <title>Function &lt;sin&gt;</title>

    <simplesect>
      <title>Synopsis</title>
	<para>
	  &lt;sin&gt; computes the sine function.
	</para>
    </simplesect>

    <simplesect>
      <title>Arguments</title>
	<para>
	  &lt;sin&gt; takes one argument: x. If no argument is given, an error
	  occurs.
	</para>
    </simplesect>

    <simplesect>
      <title>Return Values</title>
	<para>
	  &lt;sin&gt; returns the sine of its argument, given in radians.
	  If the argument does not evaluate to a finite number,
	  &lt;sin&gt; returns an indeterminate result.
	</para>
    </simplesect>

    <example>
      <programlisting>
&lt;libxexpr:sin&gt;
  &lt;divide&gt;
    &lt;libxexpr:pi/&gt;
    2
  &lt;/divide&gt;
&lt;/libxexpr:sin&gt; --> &lt;float&gt;1&lt;/float&gt;<!--
   --></programlisting>
    </example>
  </sect1>

  <sect1 id="libxexpr-atan">
    <title>Function &lt;atan&gt;</title>

    <simplesect>
      <title>Synopsis</title>
	<para>
	  &lt;atan&gt; computes the arc tangent function.
	</para>
    </simplesect>

    <simplesect>
      <title>Arguments</title>
	<para>
	  &lt;atan&gt; takes two arguments: x and y. The y argument defaults to
	  1. If the x argument is missing, an error occurs.
	</para>
    </simplesect>

    <simplesect>
      <title>Return Values</title>
	<para>
	  &lt;atan&gt; returns the principal value of the arc tangent of its
	  argument(s) in radians. If either argument is indeterminate,
	  the result is also indeterminate.
	</para>
	
	<para>
	  If two arguments are given, &lt;atan&gt; returns the arc tangent of
	  y/x, using the signs of the two arguments to determine the quadrant
	  of the result which will be in the range [-π, π]. If both arguments
	  are 0, the result will also be 0.
	</para>

	<para>
	  If only one argument is given, &lt;atan&gt; returns the arc tangent of
	  its argument. The result will be in the range [-π/2, π/2].
	</para>
    </simplesect>

    <example>
      <programlisting>
&lt;libxexpr:atan&gt;1 0&lt;/libxexpr:atan&gt; --> &lt;float&gt;0&lt;/float&gt;<!--
   --></programlisting>
    </example>
  </sect1>

  <sect1 id="libxexpr-exp">
    <title>Function &lt;exp&gt;</title>

    <simplesect>
      <title>Synopsis</title>
	<para>
	  &lt;exp&gt; computes the base-e exponential function.
	</para>
    </simplesect>

    <simplesect>
      <title>Arguments</title>
	<para>
	  &lt;exp&gt; takes zero or one argument: x.
	</para>
    </simplesect>

    <simplesect>
      <title>Return Values</title>
	<para>
	  &lt;exp&gt; returns the value of e (the base of natural logarithms)
	  raised to the power of its argument (or just e if no argument is
	  supplied). If the argument does not evaluate to a finite number,
	  &lt;exp&gt; returns an indeterminate result.
	</para>
    </simplesect>

    <example>
      <programlisting>
&lt;libxexpr:exp&gt;2&lt;/libxexpr:exp&gt; ≅ &lt;float&gt;7.389&lt;/float&gt;<!--
   --></programlisting>
    </example>
  </sect1>

  <sect1 id="libxexpr-log">
    <title>Function &lt;log&gt;</title>

    <simplesect>
      <title>Synopsis</title>
	<para>
	  &lt;log&gt; computes the natural logarithmic function.
	</para>
    </simplesect>

    <simplesect>
      <title>Arguments</title>
	<para>
	  &lt;log&gt; takes one argument: x. If no argument is given, an error
	  occurs.
	</para>
    </simplesect>

    <simplesect>
      <title>Return Values</title>
	<para>
	  &lt;log&gt; returns the natural logarithm of its argument.
	  If the argument does not evaluate to a positive finite number,
	  &lt;log&gt; returns an indeterminate result.
	</para>
    </simplesect>

    <example>
      <programlisting>
&lt;libxexpr:log&gt;
  &lt;libxexpr:exp&gt;2&lt;/libxexpr:exp&gt;
&lt;/libxexpr:log&gt; --> &lt;float&gt;2&lt;/float&gt;<!--
   --></programlisting>
    </example>
  </sect1>

  <sect1 id="libxexpr-pow">
    <title>Function &lt;pow&gt;</title>

    <simplesect>
      <title>Synopsis</title>
	<para>
	  &lt;pow&gt; computes the value of its first argument raised to the
	  power of its second argument.
	</para>
    </simplesect>

    <simplesect>
      <title>Arguments</title>
	<para>
	  &lt;pow&gt; takes two arguments: x and y. If fewer arguments are
	  given, an error occurs.
	</para>
    </simplesect>

    <simplesect>
      <title>Return Values</title>
	<para>
	  &lt;pow&gt; returns the value of x (its first argument) raised to the
	  power of y (its second argument).
	</para>

	<para>
	  If x is a finite value less than 0, and y is a finite non-integer,
	  &lt;pow&gt; returns an indeterminate result. 
	</para>

	<para>
	  If the result overflows, &lt;pow&gt; returns an indeterminate result. 
	</para>

	<para>
	  If result underflows, and is not representable, 0 is returned.
	</para>

	<para>
	  Except as specified below, if either argument is indeterminate,
	  the result is also indeterminate.
	</para>

	<para>
	  If x is 1, the result is 1 (even if y is indeterminate).
	</para>

	<para>
	  If y is 0, the result is 1 (even if x is indeterminate).
	</para>

	<para>
	  If x is 0, and y is an odd integer greater than 0, the result is 0.
	</para>

	<para>
	  If x is 0, and y greater than 0 and not an odd integer, the result
	  is 0.
	</para>

	<para>
	  If x is 0, and y is less than 0,
	  &lt;pow&gt; returns an indeterminate result. 
	</para>
    </simplesect>

    <example>
      <programlisting>
  &lt;libxexpr:pow&gt;10 2&lt;/libxexpr:pow&gt; --> &lt;float&gt;100&lt;/float&gt;<!--
   --></programlisting>
    </example>
  </sect1>
</chapter>
