248 lines
12 KiB
HTML
248 lines
12 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||
<title>NumericAnnex Reference</title>
|
||
<link rel="stylesheet" type="text/css" href="css/highlight.css">
|
||
<link rel="stylesheet" type="text/css" href="css/jazzy.css">
|
||
<script src="js/jquery.min.js" defer></script>
|
||
<script src="js/jazzy.js" defer></script>
|
||
|
||
</head>
|
||
<body>
|
||
<a title="NumericAnnex Reference"></a>
|
||
<header>
|
||
<p class="primary">
|
||
<a href="index.html">NumericAnnex Reference</a>
|
||
(100% documented)
|
||
</p>
|
||
<p>
|
||
<a href="https://github.com/xwu/NumericAnnex">View on GitHub</a>
|
||
</p>
|
||
<p>
|
||
<a href="dash-feed://https%3A%2F%2Fxwu%2Egithub%2Eio%2FNumericAnnex%2Fdocsets%2FNumericAnnex%2Exml">Install in Dash</a>
|
||
</p>
|
||
</header>
|
||
<div class="wrapper">
|
||
<nav>
|
||
<ul>
|
||
<li>
|
||
<p><a href="Classes.html">Classes</a></p>
|
||
<ul>
|
||
<li>
|
||
<a href="Classes/Random.html">Random</a>
|
||
</li>
|
||
<li>
|
||
<a href="Classes/Random/Xoroshiro.html">– Xoroshiro</a>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<p><a href="Extensions.html">Extensions</a></p>
|
||
<ul>
|
||
<li>
|
||
<a href="Extensions/BinaryInteger.html">BinaryInteger</a>
|
||
</li>
|
||
<li>
|
||
<a href="Extensions/Double.html">Double</a>
|
||
</li>
|
||
<li>
|
||
<a href="Extensions/Float.html">Float</a>
|
||
</li>
|
||
<li>
|
||
<a href="Extensions/FloatingPoint.html">FloatingPoint</a>
|
||
</li>
|
||
<li>
|
||
<a href="Extensions/UnsignedInteger.html">UnsignedInteger</a>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<p><a href="Functions.html">Functions</a></p>
|
||
<ul>
|
||
<li>
|
||
<a href="Functions.html#/s:12NumericAnnex3absAA7ComplexVyxGAeA4RealRzs9DecodableRzs9EncodableRzs33_ExpressibleByBuiltinFloatLiteralRzlF">abs(_:)</a>
|
||
</li>
|
||
<li>
|
||
<a href="Functions.html#/s:12NumericAnnex3absAA8RationalVyxGAEs9DecodableRzs9EncodableRzs13SignedIntegerRzs021_ExpressibleByBuiltinH7LiteralRzs08UnsignedH09Magnitudes0A0PRpzAkM_AKQZANRSlF">abs(_:)</a>
|
||
</li>
|
||
<li>
|
||
<a href="Functions.html#/s:12NumericAnnex4ceilAA8RationalVyxGAEs9DecodableRzs9EncodableRzs13SignedIntegerRzs021_ExpressibleByBuiltinH7LiteralRzs08UnsignedH09Magnitudes0A0PRpzAkM_AKQZANRSlF">ceil(_:)</a>
|
||
</li>
|
||
<li>
|
||
<a href="Functions.html#/s:12NumericAnnex5floorAA8RationalVyxGAEs9DecodableRzs9EncodableRzs13SignedIntegerRzs021_ExpressibleByBuiltinH7LiteralRzs08UnsignedH09Magnitudes0A0PRpzAkM_AKQZANRSlF">floor(_:)</a>
|
||
</li>
|
||
<li>
|
||
<a href="Functions.html#/s:12NumericAnnex5roundAA8RationalVyxGAEs9DecodableRzs9EncodableRzs13SignedIntegerRzs021_ExpressibleByBuiltinH7LiteralRzs08UnsignedH09Magnitudes0A0PRpzAkM_AKQZANRSlF">round(_:)</a>
|
||
</li>
|
||
<li>
|
||
<a href="Functions.html#/s:12NumericAnnex4sqrtAA7ComplexVyxGAeA4RealRzs9DecodableRzs9EncodableRzs33_ExpressibleByBuiltinFloatLiteralRzlF">sqrt(_:)</a>
|
||
</li>
|
||
<li>
|
||
<a href="Functions.html#/s:12NumericAnnex5truncAA8RationalVyxGAEs9DecodableRzs9EncodableRzs13SignedIntegerRzs021_ExpressibleByBuiltinH7LiteralRzs08UnsignedH09Magnitudes0A0PRpzAkM_AKQZANRSlF">trunc(_:)</a>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<p><a href="Protocols.html">Protocols</a></p>
|
||
<ul>
|
||
<li>
|
||
<a href="Protocols/Math.html">Math</a>
|
||
</li>
|
||
<li>
|
||
<a href="Protocols/PRNG.html">PRNG</a>
|
||
</li>
|
||
<li>
|
||
<a href="Protocols/Real.html">Real</a>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<p><a href="Structs.html">Structs</a></p>
|
||
<ul>
|
||
<li>
|
||
<a href="Structs/Complex.html">Complex</a>
|
||
</li>
|
||
<li>
|
||
<a href="Structs/Rational.html">Rational</a>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<p><a href="Typealiases.html">Typealiases</a></p>
|
||
<ul>
|
||
<li>
|
||
<a href="Typealiases.html#/s:12NumericAnnex12RoundingRulea">RoundingRule</a>
|
||
</li>
|
||
<li>
|
||
<a href="Typealiases.html#/s:12NumericAnnex4Signa">Sign</a>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</nav>
|
||
<article>
|
||
<section>
|
||
<div class="wrapper">
|
||
<div class="overview">
|
||
|
||
<h1 id='numericannex' class='heading'>NumericAnnex</h1>
|
||
|
||
<p><a href="https://travis-ci.org/xwu/NumericAnnex"><img src="https://travis-ci.org/xwu/NumericAnnex.svg?branch=master" alt="Build Status"></a>
|
||
<a href="https://codecov.io/gh/xwu/NumericAnnex"><img src="https://codecov.io/gh/xwu/NumericAnnex/branch/master/graph/badge.svg" alt="codecov"></a></p>
|
||
|
||
<p>NumericAnnex supplements the numeric facilities provided in the Swift standard
|
||
library.</p>
|
||
<h2 id='features' class='heading'>Features</h2>
|
||
|
||
<ul>
|
||
<li><code>BinaryInteger</code> exponentiation, square root, cube root, greatest common
|
||
divisor, and least common multiple functions.</li>
|
||
<li><code>Complex</code>, a value type to represent complex values in Cartesian form.</li>
|
||
<li><code>Rational</code>, a value type to represent rational values, which supports division
|
||
by zero.</li>
|
||
<li><code>Random</code> and <code>Random.Xoroshiro</code>, two reference types implementing efficient
|
||
pseudo-random number generators.</li>
|
||
<li><code>Math</code>, a protocol for types providing square root, cube root, and elementary
|
||
transcendental functions.</li>
|
||
<li><code>Real</code>, a protocol for floating-point types providing a selection of special
|
||
functions.</li>
|
||
<li><code>PRNG</code>, a protocol for pseudo-random number generators.</li>
|
||
</ul>
|
||
|
||
<blockquote>
|
||
<p>Note: This project is in the early stages of development and is not
|
||
production-ready at this time.</p>
|
||
</blockquote>
|
||
<h2 id='requirements' class='heading'>Requirements</h2>
|
||
|
||
<p>NumericAnnex now requires Xcode 9 beta 5 or a recent development snapshot of
|
||
Swift 4.0 that includes the revised numeric protocols.</p>
|
||
|
||
<p>It requires either <code>Darwin.C</code> (macOS) or <code>Glibc</code> (Linux) for transcendental
|
||
functions provided by the C standard library and either <code>Security</code> (macOS) or
|
||
<code>Glibc</code> (Linux) for cryptographically secure random bytes.</p>
|
||
<h2 id='installation' class='heading'>Installation</h2>
|
||
|
||
<p>After NumericAnnex has been cloned or downloaded locally, build the library with
|
||
the command <code>swift build</code> (macOS) or <code>swift build -Xcc -D_GNU_SOURCE</code> (Linux).
|
||
Tests can be run with the command <code>swift test</code> (macOS) or
|
||
<code>swift test -Xcc -D_GNU_SOURCE</code> (Linux). An Xcode project can be generated with
|
||
the command <code>swift package generate-xcodeproj</code>.</p>
|
||
|
||
<p><a href="https://swift.org/package-manager/">Swift Package Manager</a> can also be used to
|
||
add the package as a dependency for your own project. See Swift documentation
|
||
for details.</p>
|
||
<h2 id='basic-usage' class='heading'>Basic Usage</h2>
|
||
<pre class="highlight swift"><code><span class="kd">import</span> <span class="kt">NumericAnnex</span>
|
||
|
||
<span class="k">var</span> <span class="nv">x</span><span class="p">:</span> <span class="kt">Ratio</span> <span class="o">=</span> <span class="mi">1</span> <span class="o">/</span> <span class="mi">4</span>
|
||
<span class="c1">// Ratio is a type alias for Rational<Int>.</span>
|
||
|
||
<span class="nf">print</span><span class="p">(</span><span class="n">x</span><span class="o">.</span><span class="nf">reciprocal</span><span class="p">())</span>
|
||
<span class="c1">// Prints "4".</span>
|
||
|
||
<span class="n">x</span> <span class="o">*=</span> <span class="mi">8</span>
|
||
<span class="nf">print</span><span class="p">(</span><span class="n">x</span> <span class="o">+</span> <span class="n">x</span><span class="p">)</span>
|
||
<span class="c1">// Prints "4".</span>
|
||
|
||
<span class="n">x</span> <span class="o">=</span> <span class="kt">Ratio</span><span class="p">(</span><span class="kt">Float</span><span class="o">.</span><span class="n">phi</span><span class="p">)</span> <span class="c1">// Golden ratio.</span>
|
||
<span class="nf">print</span><span class="p">(</span><span class="n">x</span><span class="p">)</span>
|
||
<span class="c1">// Prints "13573053/8388608".</span>
|
||
|
||
<span class="k">var</span> <span class="nv">z</span><span class="p">:</span> <span class="kt">Complex64</span> <span class="o">=</span> <span class="mi">42</span> <span class="o">*</span> <span class="o">.</span><span class="n">i</span>
|
||
<span class="c1">// Complex64 is a type alias for Complex<Float>.</span>
|
||
|
||
<span class="nf">print</span><span class="p">(</span><span class="kt">Complex</span><span class="o">.</span><span class="nf">sqrt</span><span class="p">(</span><span class="n">z</span><span class="p">))</span>
|
||
<span class="c1">// Prints "4.58258 + 4.58258i".</span>
|
||
|
||
<span class="n">z</span> <span class="o">=</span> <span class="o">.</span><span class="n">pi</span> <span class="o">+</span> <span class="o">.</span><span class="n">i</span> <span class="o">*</span> <span class="o">.</span><span class="nf">log</span><span class="p">(</span><span class="mi">2</span> <span class="o">-</span> <span class="o">.</span><span class="nf">sqrt</span><span class="p">(</span><span class="mi">3</span><span class="p">))</span>
|
||
<span class="nf">print</span><span class="p">(</span><span class="kt">Complex</span><span class="o">.</span><span class="nf">cos</span><span class="p">(</span><span class="n">z</span><span class="p">)</span><span class="o">.</span><span class="n">real</span><span class="p">)</span>
|
||
<span class="c1">// Prints "-2.0".</span>
|
||
</code></pre>
|
||
<h2 id='documentation' class='heading'>Documentation</h2>
|
||
|
||
<p>All public protocols, types, and functions have been carefully documented in the
|
||
code. See the <a href="https://xwu.github.io/NumericAnnex/">formatted reference</a> for
|
||
details.</p>
|
||
|
||
<p>The project adheres to many design patterns found in the Swift standard library.
|
||
For example, <code>Math</code> types provide methods such as <code>cubeRoot()</code> and <code>tangent()</code>
|
||
just as <code>FloatingPoint</code> types provide methods such as <code>squareRoot()</code>.</p>
|
||
|
||
<p>No free functions are declared in this library unless they overload existing
|
||
ones in the Swift standard library. Instead, functions such as <code>cbrt(_:)</code> and
|
||
<code>tan(_:)</code> are provided as static members. This avoids collisions with C standard
|
||
library functions that you may wish to use. It also promotes clarity at the call
|
||
site when the result of a complex operation differs from that of its real
|
||
counterpart (e.g., <code>Complex128.cbrt(-8) != -2</code>).</p>
|
||
<h2 id='future-directions' class='heading'>Future Directions</h2>
|
||
|
||
<ul>
|
||
<li>[ ] Add more tests, including performance tests</li>
|
||
<li>[ ] Design and implement additional methods on <code>PRNG</code></li>
|
||
<li>[ ] Design and implement <code>BigInt</code></li>
|
||
</ul>
|
||
<h2 id='license' class='heading'>License</h2>
|
||
|
||
<p>All original work is released under the MIT license. See
|
||
<a href="https://github.com/xwu/NumericAnnex/blob/master/LICENSE">LICENSE</a> for details.</p>
|
||
|
||
<p>Portions of the complex square root and elementary transcendental functions use
|
||
checks for special values adapted from libc++. Code in libc++ is dual-licensed
|
||
under the MIT and UIUC/NCSA licenses.</p>
|
||
|
||
</div>
|
||
</div>
|
||
</section>
|
||
</article>
|
||
</div>
|
||
<footer>
|
||
<p>© 2017 <a class="link" href="https://diploid.ca" target="_blank" rel="external">Xiaodi Wu</a>. All rights reserved. (Last updated: 2017-08-12)</p>
|
||
<p>Generated by <a href="https://github.com/realm/jazzy" target="_blank" rel="external">Jazzy</a> v0.8.3, a <a href="http://realm.io" target="_blank" rel="external">Realm</a> project.</p>
|
||
</footer>
|
||
</body>
|
||
</div>
|
||
</html>
|