1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/reference/language_extensions.xml Wed Oct 10 22:58:48 2012 +0100
1.3 @@ -0,0 +1,277 @@
1.4 +<?xml version="1.0"?>
1.5 +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
1.6 + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
1.7 +[
1.8 +]>
1.9 +<chapter id="language-extensions">
1.10 + <title>Language Extensions</title>
1.11 +
1.12 + <para>
1.13 + These language extensions are provided in the following namespace URI:
1.14 + <screen>
1.15 +http://www.juiblex.co.uk/ns/libxexpr
1.16 + </screen>
1.17 + People using this namespace are encouraged to use the libxexpr namespace
1.18 + prefix.
1.19 + </para>
1.20 +
1.21 + <sect1 id="libxexpr-pi">
1.22 + <title>Function <pi></title>
1.23 +
1.24 + <simplesect>
1.25 + <title>Synopsis</title>
1.26 + <para>
1.27 + <pi> returns the value of π.
1.28 + </para>
1.29 + </simplesect>
1.30 +
1.31 + <simplesect>
1.32 + <title>Arguments</title>
1.33 + <para>
1.34 + <pi> takes no arguments.
1.35 + </para>
1.36 + </simplesect>
1.37 +
1.38 + <simplesect>
1.39 + <title>Return Values</title>
1.40 + <para>
1.41 + <pi> returns the value of π.
1.42 + </para>
1.43 + </simplesect>
1.44 +
1.45 + <example>
1.46 + <programlisting>
1.47 +<libxexpr:pi/> ≅ <float>3.14</float><!--
1.48 + --></programlisting>
1.49 + </example>
1.50 + </sect1>
1.51 +
1.52 + <sect1 id="libxexpr-sin">
1.53 + <title>Function <sin></title>
1.54 +
1.55 + <simplesect>
1.56 + <title>Synopsis</title>
1.57 + <para>
1.58 + <sin> computes the sine function.
1.59 + </para>
1.60 + </simplesect>
1.61 +
1.62 + <simplesect>
1.63 + <title>Arguments</title>
1.64 + <para>
1.65 + <sin> takes one argument: x. If no argument is given, an error
1.66 + occurs.
1.67 + </para>
1.68 + </simplesect>
1.69 +
1.70 + <simplesect>
1.71 + <title>Return Values</title>
1.72 + <para>
1.73 + <sin> returns the sine of its argument, given in radians.
1.74 + If the argument does not evaluate to a finite number,
1.75 + <sin> returns an indeterminate result.
1.76 + </para>
1.77 + </simplesect>
1.78 +
1.79 + <example>
1.80 + <programlisting>
1.81 +<libxexpr:sin>
1.82 + <divide>
1.83 + <libxexpr:pi/>
1.84 + 2
1.85 + </divide>
1.86 +</libxexpr:sin> --> <float>1</float><!--
1.87 + --></programlisting>
1.88 + </example>
1.89 + </sect1>
1.90 +
1.91 + <sect1 id="libxexpr-atan">
1.92 + <title>Function <atan></title>
1.93 +
1.94 + <simplesect>
1.95 + <title>Synopsis</title>
1.96 + <para>
1.97 + <atan> computes the arc tangent function.
1.98 + </para>
1.99 + </simplesect>
1.100 +
1.101 + <simplesect>
1.102 + <title>Arguments</title>
1.103 + <para>
1.104 + <atan> takes two arguments: x and y. The y argument defaults to
1.105 + 1. If the x argument is missing, an error occurs.
1.106 + </para>
1.107 + </simplesect>
1.108 +
1.109 + <simplesect>
1.110 + <title>Return Values</title>
1.111 + <para>
1.112 + <atan> returns the principal value of the arc tangent of its
1.113 + argument(s) in radians. If either argument is indeterminate,
1.114 + the result is also indeterminate.
1.115 + </para>
1.116 +
1.117 + <para>
1.118 + If two arguments are given, <atan> returns the arc tangent of
1.119 + y/x, using the signs of the two arguments to determine the quadrant
1.120 + of the result which will be in the range [-π, π]. If both arguments
1.121 + are 0, the result will also be 0.
1.122 + </para>
1.123 +
1.124 + <para>
1.125 + If only one argument is given, <atan> returns the arc tangent of
1.126 + its argument. The result will be in the range [-π/2, π/2].
1.127 + </para>
1.128 + </simplesect>
1.129 +
1.130 + <example>
1.131 + <programlisting>
1.132 +<libxexpr:atan>1 0</libxexpr:atan> --> <float>0</float><!--
1.133 + --></programlisting>
1.134 + </example>
1.135 + </sect1>
1.136 +
1.137 + <sect1 id="libxexpr-exp">
1.138 + <title>Function <exp></title>
1.139 +
1.140 + <simplesect>
1.141 + <title>Synopsis</title>
1.142 + <para>
1.143 + <exp> computes the base-e exponential function.
1.144 + </para>
1.145 + </simplesect>
1.146 +
1.147 + <simplesect>
1.148 + <title>Arguments</title>
1.149 + <para>
1.150 + <exp> takes zero or one argument: x.
1.151 + </para>
1.152 + </simplesect>
1.153 +
1.154 + <simplesect>
1.155 + <title>Return Values</title>
1.156 + <para>
1.157 + <exp> returns the value of e (the base of natural logarithms)
1.158 + raised to the power of its argument (or just e if no argument is
1.159 + supplied). If the argument does not evaluate to a finite number,
1.160 + <exp> returns an indeterminate result.
1.161 + </para>
1.162 + </simplesect>
1.163 +
1.164 + <example>
1.165 + <programlisting>
1.166 +<libxexpr:exp>2</libxexpr:exp> ≅ <float>7.389</float><!--
1.167 + --></programlisting>
1.168 + </example>
1.169 + </sect1>
1.170 +
1.171 + <sect1 id="libxexpr-log">
1.172 + <title>Function <log></title>
1.173 +
1.174 + <simplesect>
1.175 + <title>Synopsis</title>
1.176 + <para>
1.177 + <log> computes the natural logarithmic function.
1.178 + </para>
1.179 + </simplesect>
1.180 +
1.181 + <simplesect>
1.182 + <title>Arguments</title>
1.183 + <para>
1.184 + <log> takes one argument: x. If no argument is given, an error
1.185 + occurs.
1.186 + </para>
1.187 + </simplesect>
1.188 +
1.189 + <simplesect>
1.190 + <title>Return Values</title>
1.191 + <para>
1.192 + <log> returns the natural logarithm of its argument.
1.193 + If the argument does not evaluate to a positive finite number,
1.194 + <log> returns an indeterminate result.
1.195 + </para>
1.196 + </simplesect>
1.197 +
1.198 + <example>
1.199 + <programlisting>
1.200 +<libxexpr:log>
1.201 + <libxexpr:exp>2</libxexpr:exp>
1.202 +</libxexpr:log> --> <float>2</float><!--
1.203 + --></programlisting>
1.204 + </example>
1.205 + </sect1>
1.206 +
1.207 + <sect1 id="libxexpr-pow">
1.208 + <title>Function <pow></title>
1.209 +
1.210 + <simplesect>
1.211 + <title>Synopsis</title>
1.212 + <para>
1.213 + <pow> computes the value of its first argument raised to the
1.214 + power of its second argument.
1.215 + </para>
1.216 + </simplesect>
1.217 +
1.218 + <simplesect>
1.219 + <title>Arguments</title>
1.220 + <para>
1.221 + <pow> takes two arguments: x and y. If fewer arguments are
1.222 + given, an error occurs.
1.223 + </para>
1.224 + </simplesect>
1.225 +
1.226 + <simplesect>
1.227 + <title>Return Values</title>
1.228 + <para>
1.229 + <pow> returns the value of x (its first argument) raised to the
1.230 + power of y (its second argument).
1.231 + </para>
1.232 +
1.233 + <para>
1.234 + If x is a finite value less than 0, and y is a finite non-integer,
1.235 + <pow> returns an indeterminate result.
1.236 + </para>
1.237 +
1.238 + <para>
1.239 + If the result overflows, <pow> returns an indeterminate result.
1.240 + </para>
1.241 +
1.242 + <para>
1.243 + If result underflows, and is not representable, 0 is returned.
1.244 + </para>
1.245 +
1.246 + <para>
1.247 + Except as specified below, if either argument is indeterminate,
1.248 + the result is also indeterminate.
1.249 + </para>
1.250 +
1.251 + <para>
1.252 + If x is 1, the result is 1 (even if y is indeterminate).
1.253 + </para>
1.254 +
1.255 + <para>
1.256 + If y is 0, the result is 1 (even if x is indeterminate).
1.257 + </para>
1.258 +
1.259 + <para>
1.260 + If x is 0, and y is an odd integer greater than 0, the result is 0.
1.261 + </para>
1.262 +
1.263 + <para>
1.264 + If x is 0, and y greater than 0 and not an odd integer, the result
1.265 + is 0.
1.266 + </para>
1.267 +
1.268 + <para>
1.269 + If x is 0, and y is less than 0,
1.270 + <pow> returns an indeterminate result.
1.271 + </para>
1.272 + </simplesect>
1.273 +
1.274 + <example>
1.275 + <programlisting>
1.276 + <libxexpr:pow>10 2</libxexpr:pow> --> <float>100</float><!--
1.277 + --></programlisting>
1.278 + </example>
1.279 + </sect1>
1.280 +</chapter>