<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>book/src/function-definitions.md - fork/numbat @ v1.6.3</title>
<meta name="description" content="book/src/function-definitions.md in fork/numbat at v1.6.3.">
<meta property="og:title" content="book/src/function-definitions.md - fork/numbat @ v1.6.3">
<meta property="og:description" content="book/src/function-definitions.md in fork/numbat at v1.6.3.">
<meta property="og:type" content="website">
<meta property="og:site_name" content="git.julia.blue">
<link rel="stylesheet" href="/css/style.css?v=62">
<script type="module" src="/js/main.js?v=62"></script>
</head>
<body>
<main data-ref="v1.6.3" data-tip="52bc0d26a5b7aeb998746750385871b44749f8f4">
<noscript>
  <div class="callout">
    <p>
      hey! this is a static git repo viewer. commit diffs, file history,
      older commits and other revisions won't load without javascript.
    </p>
    <p>
      you are still able to view source files on branch/tag tips,
      but the experience is degraded.
    </p>
  </div>
</noscript>
<header class="repo"><div>
<h1>fork/numbat</h1>
</div>
<pre class="clone">git clone https://git.julia.blue/fork/numbat</pre>
</header>
<p class="snapshot-commit"><span class="commit-author">David Peter</span><span class="commit-message" data-commit="307905086f6507f8e123144ae03ce9049b1c8260">Add 'Function definitions' chapter</span><span class="snapshot-sha sha" data-commit="307905086f6507f8e123144ae03ce9049b1c8260">3079050</span><time datetime="2023-09-12T19:57:44+02:00" title="2023-09-12 19:57:44 +0200">2023-09-12</time></p>
<header class="topbar"><details class="switcher"><summary>v1.6.3</summary><div class="menu"><strong>branches</strong><a href="/fork/numbat/ref/master/">master</a><strong>tags</strong><a href="/fork/numbat/ref/v1.6.0/">v1.6.0</a><a href="/fork/numbat/ref/v1.6.1/">v1.6.1</a><a href="/fork/numbat/ref/v1.6.2/">v1.6.2</a><a class="current" href="/fork/numbat/ref/v1.6.3/">v1.6.3</a><a href="/fork/numbat/ref/v1.7.0/">v1.7.0</a><a href="/fork/numbat/ref/v1.8.0/">v1.8.0</a><a class="all" href="/fork/numbat/refs">all refs →</a></div></details><nav class="crumbs"><a href="/fork/numbat/">numbat</a> / <a href="/fork/numbat/ref/v1.6.3/tree/book/">book</a> / <a href="/fork/numbat/ref/v1.6.3/tree/book/src/">src</a> / <span class="cur">function-definitions.md</span></nav>
<span class="view-stats"><span>2.8 KiB</span><span>78 lines</span></span><span class="actions"><a class="raw" href="/fork/numbat/raw/0ddeac1b7e9f8e052ae53b7be7e1e869ab8dfb06/book/src/function-definitions.md">raw</a></span></header>
<div class="markdown-view"><input type="radio" name="markdown-view" id="markdown-rendered" checked><label for="markdown-rendered">rendered</label><input type="radio" name="markdown-view" id="markdown-code"><label for="markdown-code">code</label><section class="readme rendered"><h1>Function definitions</h1>
<p>Numbat comes with a large number of <a href="/fork/numbat/ref/v1.6.3/blob/book/src/list-functions.md">predefined functions</a>, but
it is also possible to add new functions. A function definition is introduced with
the <code>fn</code> keyword:</p>
<pre>fn max_distance(v: Speed, θ: Angle) -&gt; Length = v² · sin(2 θ) / g0
</pre>
<p>This exemplary function computes the maximum distance of a projectile under the
influence of Earths gravity. It takes two parameters (The initial speed <code>v</code> and
the launch angle <code>θ</code>), which are both annotated with their corresponding physical dimension (their type). The function returns a distance, and so the return type
is specified as <code>Length</code>.</p>
<h2>Type inference</h2>
<p>The return type annotation may be omitted, but it is often desirable to add it
for better readability of the code and in order to catch potential errors.</p>
<p>The parameter types can also (sometimes) be omitted, in which case Numbat tries
to infer their type. However, this often leads to overly generic function
signatures. For example, consider the following function to compute the kinetic
energy of a massive object in motion:</p>
<pre>fn kinetic_energy(mass, speed) = 1/2 * mass * speed^2
</pre>
<p>Without any type annotations, this function has an overly generic type where
<code>mass</code> and <code>speed</code> can have arbitrary dimensions (and the return type is
<code>type(mass) * type(speed)^2</code>). So for this case, it is probably better to add
parameter and return types.</p>
<h2>Generic functions</h2>
<p>Sometimes however, it <em>is</em> useful to write generic functions. For example, consider
<code>max(a, b)</code> — a function that returns the larger of the two arguments. We might
want to use that function with <em>dimensionful</em> arguments such as <code>max(1 m, 1 yd)</code>.
To define such a generic function, you can introduce <em>type parameters</em> in angle
brackets:</p>
<pre>fn max&lt;T&gt;(a: T, b: T) -&gt; T = if a &gt; b then a else b
</pre>
<p>This function signature tells us that <code>max</code> takes two arguments of <em>arbitrary</em>
type <code>T</code> (but they need to match!), and returns a quantity of the same type <code>T</code>.</p>
<p>Note that you can perform the usual operations with type parameters, such as
multiplying/dividing them with other types, or raising to rational powers. For
example, consider this cube-root function</p>
<pre>fn cube_root&lt;T&gt;(x: T^3) -&gt; T = x^(1/3)
</pre>
<p>that can be called with a scalar (<code>cube_root(8) == 2</code>) or a dimensionful
argument (<code>cube_root(1 liter) == 10 cm</code>).</p>
<p>Note: <code>cube_root</code> can also be defined as <code>fn cube_root&lt;T&gt;(x: T) -&gt; T^(1/3)</code>,
which is equivalent to the definition above.</p>
<h2>Recursive functions</h2>
<p>It is also possible to define recursive functions. In order to do so, you
currently need to specify the return type — as the type signature can not
(yet) be inferred otherwise.</p>
<p>For example, a naive recursive implementation to compute Fibonacci numbers
in Numbat looks like this:</p>
<pre>fn fib(n: Scalar) -&gt; Scalar =
  if n ≤ 2
    then 1
    else fib(n - 2) + fib(n - 1)
</pre>
</section><div class="code-panel"><pre class="code src language-markdown"><span class="code-line"><a class="ln" id="L1" href="#L1">1</a><span class="code-text"><a-p>#</a-p> <a-tt>Function definitions</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2" href="#L2">2</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L3" href="#L3">3</a><span class="code-text">Numbat comes with a large number of [predefined functions](./list-functions.md), but</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L4" href="#L4">4</a><span class="code-text">it is also possible to add new functions. A function definition is introduced with</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L5" href="#L5">5</a><span class="code-text">the `fn` keyword:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L6" href="#L6">6</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L7" href="#L7">7</a><span class="code-text"><a-p>```</a-p><a-tl>nbt</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L8" href="#L8">8</a><span class="code-text"><a-p>fn max_distance(v: Speed, θ: Angle) -&gt; Length = v² · sin(2 θ) / g0</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L9" href="#L9">9</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L10" href="#L10">10</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L11" href="#L11">11</a><span class="code-text"><a-p>This exemplary function computes the maximum distance of a projectile under the</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L12" href="#L12">12</a><span class="code-text"><a-p>influence of Earths gravity. It takes two parameters (The initial speed `v` and</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L13" href="#L13">13</a><span class="code-text"><a-p>the launch angle `θ`), which are both annotated with their corresponding physical dimension (their type). The function returns a distance, and so the return type</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L14" href="#L14">14</a><span class="code-text"><a-p>is specified as `Length`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L15" href="#L15">15</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L16" href="#L16">16</a><span class="code-text"><a-p>## </a-p><a-tt>Type inference</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L17" href="#L17">17</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L18" href="#L18">18</a><span class="code-text"><a-p>The return type annotation may be omitted, but it is often desirable to add it</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L19" href="#L19">19</a><span class="code-text"><a-p>for better readability of the code and in order to catch potential errors.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L20" href="#L20">20</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L21" href="#L21">21</a><span class="code-text"><a-p>The parameter types can also (sometimes) be omitted, in which case Numbat tries</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L22" href="#L22">22</a><span class="code-text"><a-p>to infer their type. However, this often leads to overly generic function</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L23" href="#L23">23</a><span class="code-text"><a-p>signatures. For example, consider the following function to compute the kinetic</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L24" href="#L24">24</a><span class="code-text"><a-p>energy of a massive object in motion:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L25" href="#L25">25</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L26" href="#L26">26</a><span class="code-text"><a-p>```</a-p><a-tl>nbt</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L27" href="#L27">27</a><span class="code-text"><a-p>fn kinetic_energy(mass, speed) = 1/2 * mass * speed^2</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L28" href="#L28">28</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L29" href="#L29">29</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L30" href="#L30">30</a><span class="code-text"><a-p>Without any type annotations, this function has an overly generic type where</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L31" href="#L31">31</a><span class="code-text"><a-p>`mass` and `speed` can have arbitrary dimensions (and the return type is</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L32" href="#L32">32</a><span class="code-text"><a-p>`type(mass) * type(speed)^2`). So for this case, it is probably better to add</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L33" href="#L33">33</a><span class="code-text"><a-p>parameter and return types.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L34" href="#L34">34</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L35" href="#L35">35</a><span class="code-text"><a-p>## </a-p><a-tt>Generic functions</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L36" href="#L36">36</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L37" href="#L37">37</a><span class="code-text"><a-p>Sometimes however, it *is* useful to write generic functions. For example, consider</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L38" href="#L38">38</a><span class="code-text"><a-p>`max(a, b)` — a function that returns the larger of the two arguments. We might</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L39" href="#L39">39</a><span class="code-text"><a-p>want to use that function with *dimensionful* arguments such as `max(1 m, 1 yd)`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L40" href="#L40">40</a><span class="code-text"><a-p>To define such a generic function, you can introduce *type parameters* in angle</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L41" href="#L41">41</a><span class="code-text"><a-p>brackets:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L42" href="#L42">42</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L43" href="#L43">43</a><span class="code-text"><a-p>```</a-p><a-tl>nbt</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L44" href="#L44">44</a><span class="code-text"><a-p>fn max&lt;T&gt;(a: T, b: T) -&gt; T = if a &gt; b then a else b</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L45" href="#L45">45</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L46" href="#L46">46</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L47" href="#L47">47</a><span class="code-text"><a-p>This function signature tells us that `max` takes two arguments of *arbitrary*</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L48" href="#L48">48</a><span class="code-text"><a-p>type `T` (but they need to match!), and returns a quantity of the same type `T`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L49" href="#L49">49</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L50" href="#L50">50</a><span class="code-text"><a-p>Note that you can perform the usual operations with type parameters, such as</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L51" href="#L51">51</a><span class="code-text"><a-p>multiplying/dividing them with other types, or raising to rational powers. For</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L52" href="#L52">52</a><span class="code-text"><a-p>example, consider this cube-root function</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L53" href="#L53">53</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L54" href="#L54">54</a><span class="code-text"><a-p>```</a-p><a-tl>nbt</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L55" href="#L55">55</a><span class="code-text"><a-p>fn cube_root&lt;T&gt;(x: T^3) -&gt; T = x^(1/3)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L56" href="#L56">56</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L57" href="#L57">57</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L58" href="#L58">58</a><span class="code-text"><a-p>that can be called with a scalar (`cube_root(8) == 2`) or a dimensionful</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L59" href="#L59">59</a><span class="code-text"><a-p>argument (`cube_root(1 liter) == 10 cm`).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L60" href="#L60">60</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L61" href="#L61">61</a><span class="code-text"><a-p>Note: `cube_root` can also be defined as `fn cube_root&lt;T&gt;(x: T) -&gt; T^(1/3)`,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L62" href="#L62">62</a><span class="code-text"><a-p>which is equivalent to the definition above.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L63" href="#L63">63</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L64" href="#L64">64</a><span class="code-text"><a-p>## </a-p><a-tt>Recursive functions</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L65" href="#L65">65</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L66" href="#L66">66</a><span class="code-text"><a-p>It is also possible to define recursive functions. In order to do so, you</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L67" href="#L67">67</a><span class="code-text"><a-p>currently need to specify the return type — as the type signature can not</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L68" href="#L68">68</a><span class="code-text"><a-p>(yet) be inferred otherwise.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L69" href="#L69">69</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L70" href="#L70">70</a><span class="code-text"><a-p>For example, a naive recursive implementation to compute Fibonacci numbers</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L71" href="#L71">71</a><span class="code-text"><a-p>in Numbat looks like this:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L72" href="#L72">72</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L73" href="#L73">73</a><span class="code-text"><a-p>```</a-p><a-tl>nbt</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L74" href="#L74">74</a><span class="code-text"><a-p>fn fib(n: Scalar) -&gt; Scalar =</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L75" href="#L75">75</a><span class="code-text"><a-p>  if n ≤ 2</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L76" href="#L76">76</a><span class="code-text"><a-p>    then 1</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L77" href="#L77">77</a><span class="code-text"><a-p>    else fib(n - 2) + fib(n - 1)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L78" href="#L78">78</a><span class="code-text"><a-p>```</a-p></span></span></pre></div></div>
</main>
</body>
</html>
