292 lines
15 KiB
HTML
292 lines
15 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/DoubleWidth.html">DoubleWidth</a>
|
||
</li>
|
||
<li>
|
||
<a href="Extensions/Float.html">Float</a>
|
||
</li>
|
||
<li>
|
||
<a href="Extensions/FloatingPoint.html">FloatingPoint</a>
|
||
</li>
|
||
<li>
|
||
<a href="Extensions/Int.html">Int</a>
|
||
</li>
|
||
<li>
|
||
<a href="Extensions/Int16.html">Int16</a>
|
||
</li>
|
||
<li>
|
||
<a href="Extensions/Int32.html">Int32</a>
|
||
</li>
|
||
<li>
|
||
<a href="Extensions/Int64.html">Int64</a>
|
||
</li>
|
||
<li>
|
||
<a href="Extensions/Int8.html">Int8</a>
|
||
</li>
|
||
<li>
|
||
<a href="Extensions/UInt.html">UInt</a>
|
||
</li>
|
||
<li>
|
||
<a href="Extensions/UInt16.html">UInt16</a>
|
||
</li>
|
||
<li>
|
||
<a href="Extensions/UInt32.html">UInt32</a>
|
||
</li>
|
||
<li>
|
||
<a href="Extensions/UInt64.html">UInt64</a>
|
||
</li>
|
||
<li>
|
||
<a href="Extensions/UInt8.html">UInt8</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">Structures</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">Type Aliases</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='img-src-https-xwu-github-io-numericannex-img-numericannex-2017-09-02-svg-alt-numericannex-height-72-br-numericannex' class='heading'><img src="https://xwu.github.io/NumericAnnex/img/NumericAnnex-2017-09-02.svg" alt="NumericAnnex" height="72"><br>NumericAnnex</h1>
|
||
|
||
<p>NumericAnnex supplements the numeric facilities provided in the Swift standard
|
||
library.</p>
|
||
|
||
<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>
|
||
<h2 id='features' class='heading'>Features</h2>
|
||
|
||
<ul>
|
||
<li>The exponentiation operator <code>**</code> and the compound assignment operator <code>**=</code>.</li>
|
||
<li>Extension methods for <code>BinaryInteger</code> exponentiation, square root, cube root,
|
||
greatest common divisor, and least common multiple.</li>
|
||
<li><code><a href="Protocols/Math.html">Math</a></code>, a protocol for signed numeric types that support elementary functions.</li>
|
||
<li><code><a href="Protocols/Real.html">Real</a></code>, a protocol for floating-point types that support elementary functions
|
||
and a selection of special functions.</li>
|
||
<li><code><a href="Protocols/PRNG.html">PRNG</a></code>, a protocol for pseudo-random number generators.</li>
|
||
<li><code><a href="Structs/Rational.html">Rational</a></code>, a value type to represent rational values which supports division
|
||
by zero.</li>
|
||
<li><code><a href="Structs/Complex.html">Complex</a></code>, a value type to represent complex values in Cartesian form.</li>
|
||
<li><code><a href="Classes/Random.html">Random</a></code> and <code><a href="Classes/Random/Xoroshiro.html">Random.Xoroshiro</a></code>, two reference types implementing efficient
|
||
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 requires Swift 4.0. On Apple platforms, it also requires the
|
||
Security framework 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
|
||
using the command <code>swift build</code> (macOS) or <code>swift build -Xcc -D_GNU_SOURCE</code>
|
||
(Linux). Run tests 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>To add the package as a dependency using <a href="https://cocoapods.org">CocoaPods</a>,
|
||
insert the following line in your <code>Podfile</code>:</p>
|
||
<pre class="highlight ruby"><code><span class="n">pod</span> <span class="s1">'NumericAnnex'</span><span class="p">,</span> <span class="s1">'~> 0.1.19'</span>
|
||
</code></pre>
|
||
|
||
<p><a href="https://swift.org/package-manager/">Swift Package Manager</a> can also be used to
|
||
add the package as a dependency. 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="nf">print</span><span class="p">(</span><span class="mi">2</span> <span class="o">**</span> <span class="mi">3</span><span class="p">)</span>
|
||
<span class="c1">// Prints "8".</span>
|
||
|
||
<span class="nf">print</span><span class="p">(</span><span class="mf">4.0</span> <span class="o">**</span> <span class="mf">5.0</span><span class="p">)</span>
|
||
<span class="c1">// Prints "1024.0".</span>
|
||
|
||
<span class="nf">print</span><span class="p">(</span><span class="kt">Int</span><span class="o">.</span><span class="nf">cbrt</span><span class="p">(</span><span class="mi">8</span><span class="p">))</span>
|
||
<span class="c1">// Prints "2".</span>
|
||
|
||
<span class="nf">print</span><span class="p">(</span><span class="kt">Double</span><span class="o">.</span><span class="nf">cbrt</span><span class="p">(</span><span class="mf">27.0</span><span class="p">))</span>
|
||
<span class="c1">// Prints "3.0".</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><a href="Protocols/Math.html">Math</a></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><a href="Protocols/PRNG.html">PRNG</a></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-09-30)</p>
|
||
<p>Generated by <a href="https://github.com/realm/jazzy" target="_blank" rel="external">Jazzy</a> v0.8.4, a <a href="http://realm.io" target="_blank" rel="external">Realm</a> project.</p>
|
||
</footer>
|
||
</body>
|
||
</div>
|
||
</html>
|