Add percentage-calculation functions

book/build.py

@@ -176,6 +176,10 @@ list_of_functions(
                     "numerics::fixed_point",
                 ],
             },
+            {
+                "title": "Percentage calculations",
+                "modules": ["math::percentage_calculations"],
+            },
             {
                 "title": "Geometry",
                 "modules": ["math::geometry"],

book/src/list-functions-math.md

@@ -1,6 +1,6 @@
 # Mathematical functions
 
-[Basics](#basics) · [Transcendental functions](#transcendental-functions) · [Trigonometry](#trigonometry) · [Statistics](#statistics) · [Random sampling, distributions](#random-sampling-distributions) · [Number theory](#number-theory) · [Numerical methods](#numerical-methods) · [Geometry](#geometry) · [Algebra](#algebra) · [Trigonometry (extra)](#trigonometry-(extra))
+[Basics](#basics) · [Transcendental functions](#transcendental-functions) · [Trigonometry](#trigonometry) · [Statistics](#statistics) · [Random sampling, distributions](#random-sampling-distributions) · [Number theory](#number-theory) · [Numerical methods](#numerical-methods) · [Percentage calculations](#percentage-calculations) · [Geometry](#geometry) · [Algebra](#algebra) · [Trigonometry (extra)](#trigonometry-(extra))
 
 ## Basics
 
@@ -827,6 +827,64 @@ fixed_point(function, 0, 0.01)
 
 </details>
 
+## Percentage calculations
+
+Defined in: `math::percentage_calculations`
+
+### `increase_by`
+Increase a quantity by the given percentage.
+More information [here](https://en.wikipedia.org/wiki/Percentage#Percentage_increase_and_decrease).
+
+```nbt
+fn increase_by<D: Dim>(percentage: Scalar, quantity: D) -> D
+```
+
+<details>
+<summary>Examples</summary>
+
+<pre><div class="buttons"><button class="fa fa-play play-button" title="Run this code" aria-label="Run this code"  onclick=" window.open('https://numbat.dev/?q=72%20%E2%82%AC%20%7C%3E%20increase%5Fby%2815%25%29')""></button></div><code class="language-nbt hljs numbat">>>> 72 € |> increase_by(15%)
+
+    = 82.8 €    [Money]
+</code></pre>
+
+</details>
+
+### `decrease_by`
+Decrease a quantity by the given percentage.
+More information [here](https://en.wikipedia.org/wiki/Percentage#Percentage_increase_and_decrease).
+
+```nbt
+fn decrease_by<D: Dim>(percentage: Scalar, quantity: D) -> D
+```
+
+<details>
+<summary>Examples</summary>
+
+<pre><div class="buttons"><button class="fa fa-play play-button" title="Run this code" aria-label="Run this code"  onclick=" window.open('https://numbat.dev/?q=210%20cm%20%7C%3E%20decrease%5Fby%2810%25%29')""></button></div><code class="language-nbt hljs numbat">>>> 210 cm |> decrease_by(10%)
+
+    = 189 cm    [Length]
+</code></pre>
+
+</details>
+
+### `percentage_change`
+By how many percent has a given quantity increased or decreased?.
+More information [here](https://en.wikipedia.org/wiki/Percentage).
+
+```nbt
+fn percentage_change<D: Dim>(old: D, new: D) -> Scalar
+```
+
+<details>
+<summary>Examples</summary>
+
+<pre><div class="buttons"><button class="fa fa-play play-button" title="Run this code" aria-label="Run this code"  onclick=" window.open('https://numbat.dev/?q=percentage%5Fchange%2835%20kg%2C%2042%20kg%29')""></button></div><code class="language-nbt hljs numbat">>>> percentage_change(35 kg, 42 kg)
+
+    = 20 %
+</code></pre>
+
+</details>
+
 ## Geometry
 
 Defined in: `math::geometry`

examples/money.nbt

@@ -0,0 +1,8 @@
+let price = 100 $
+let shipping = 5 $
+let subtotal = price + shipping
+
+let discount = 10%
+let total = subtotal |> decrease_by(discount)
+
+assert_eq(total, $ 94.50)

examples/tests/percentage_calculations.nbt

@@ -0,0 +1,8 @@
+assert_eq(2.5 m |> increase_by(100%), 5 m)
+assert_eq(2.5 m |> increase_by(10%), 2.75 m)
+assert_eq(2.5 m |> increase_by(0%), 2.5 m)
+
+assert_eq(2.5 m |> decrease_by(100%), 0)
+
+assert_eq(percentage_change(40 dollar, 50 dollar), +25%)
+assert_eq(percentage_change(50 dollar, 40 dollar), -20%)

numbat/modules/math/percentage_calculations.nbt

@@ -0,0 +1,17 @@
+use core::scalar
+use units::partsperx
+
+@description("Increase a quantity by the given percentage.")
+@url("https://en.wikipedia.org/wiki/Percentage#Percentage_increase_and_decrease")
+@example("72 € |> increase_by(15%)")
+fn increase_by<D: Dim>(percentage: Scalar, quantity: D) = quantity * (1 + percentage)
+
+@description("Decrease a quantity by the given percentage.")
+@url("https://en.wikipedia.org/wiki/Percentage#Percentage_increase_and_decrease")
+@example("210 cm |> decrease_by(10%)")
+fn decrease_by<D: Dim>(percentage: Scalar, quantity: D) = increase_by(-percentage, quantity)
+
+@description("By how many percent has a given quantity increased or decreased?")
+@url("https://en.wikipedia.org/wiki/Percentage")
+@example("percentage_change(35 kg, 42 kg)")
+fn percentage_change<D: Dim>(old: D, new: D) = (new - old) / old -> %

numbat/modules/prelude.nbt

@@ -16,6 +16,7 @@ use math::statistics
 use math::number_theory
 use math::distributions
 use math::geometry
+use math::percentage_calculations
 
 use units::si
 use units::time

vscode-extension/syntaxes/numbat.tmLanguage.json

@@ -40,7 +40,7 @@
             "patterns": [
                 {
                     "name": "support.function.numbat",
-                    "match": "@(metric_prefixes|binary_prefixes|aliases|name|url|description)\\b"
+                    "match": "@(metric_prefixes|binary_prefixes|aliases|name|url|description|example)\\b"
                 }
             ]
         },