feat: reciprocal operator (#769)

Author: magistau

changelog.md

@@ -43,6 +43,7 @@ This version is not yet released. If you are reading this on the website, then t
 - Add [`un °`](https://uiua.org/docs/un) and [`under ⍜`](https://uiua.org/docs/under) capability to [`&cd`](https://uiua.org/docs/&cd)
   - [`un °`](https://uiua.org/docs/un)[`&cd`](https://uiua.org/docs/&cd) will output the current working directory
   - [`under ⍜`](https://uiua.org/docs/under)[`&cd`](https://uiua.org/docs/&cd) will return to the original directory afterward
+- Add experimental [`reciprocal ⨪`](https://uiua.org/docs/reciprocal) function, which computes the multiplicative inverse AKA reciprocal of a number
 ### Interpreter
 - Speed up the implementation of [`or ∨`](https://uiua.org/docs/or)
 - The fomatter no longer truncates trailing decimal `0`s from number literals

examples/photobooth.ua

@@ -3,7 +3,7 @@
 
 # Pixelate an image with the given ratio
 # ? Ratio Image
-Pixelate ← ◌⍥(÷⊙1⟜▽⟜≡▽)2 ÷⊙1
+Pixelate ← ◌⍥(⨪⟜▽⟜≡▽)2 ⨪
 
 # Run an edge-detection algorithm on an image.
 # Uses a 5x5 kernel.

parser/src/complex.rs

@@ -204,6 +204,9 @@ impl Complex {
             im: safe_mul(self.re, rhs.im) + safe_mul(self.im, rhs.re),
         }
     }
+    pub fn recip(self) -> Self {
+        Self::ONE / self
+    }
 }
 
 fn safe_mul(a: f64, b: f64) -> f64 {

parser/src/defs.rs

@@ -202,6 +202,15 @@ primitive!(
     ///
     /// The glyph looks like the graph of `|x|`.
     (1, Abs, MonadicPervasive, ("absolute value", '⌵')),
+    /// Get the reciprocal of a number
+    ///
+    /// ex: # Experimental!
+    ///   : ⨪3
+    /// ex: # Experimental!
+    ///   : ⨪[1 2 3 6]
+    /// ex: # Experimental!
+    ///   : ⨪ℂ2 1
+    (1, Reciprocal, MonadicPervasive, ("reciprocal", '⨪'), { experimental: true }),
     /// Take the square root of a number
     ///
     /// ex: √4

site/primitives.json

@@ -1193,6 +1193,14 @@
     "description": "Call a function on the first and third values on the stack",
     "experimental": true
   },
+  "reciprocal": {
+    "glyph": "⨪",
+    "args": 1,
+    "outputs": 1,
+    "class": "MonadicPervasive",
+    "description": "Get the reciprocal of a number",
+    "experimental": true
+  },
   "recv": {
     "args": 1,
     "outputs": 1,

site/src/primitive.rs

@@ -214,6 +214,7 @@ fn all_uns() -> impl IntoView {
             { inverse_row([Identity], No, "Self inverse", "°∘ 5") }
             { inverse_row([Neg], No, "Self inverse", "°¯ 5") }
             { inverse_row([Not], No, "Self inverse", "°¬ 5") }
+            { inverse_row([Reciprocal], No, "Self inverse", "# Experimental!\n°⨪ 5") }
             { inverse_row([Sqrt], No, "", "°√ 5") }
             { inverse_row([Sin], No, "Arcsine", "°∿ 1") }
             { inverse_row([Add], Required, "", "°(+1) 5") }

site/src/tutorial.rs

@@ -270,7 +270,7 @@ fn TutorialBasic() -> impl IntoView {
         <p><Prim prim=Backward/>" swaps the arguments to a function that takes two values."</p>
         <blockquote>"Note that "<Prim prim=Backward/>" is not actually a function itself. It is something called a "<em>"modifier"</em>". We'll talk about modifiers in more depth in a "<A href="/tutorial/functions#modifiers">"later section"</A>"."</blockquote>
         <p><Prim prim=Backward/>" is useful when you want to call a function that takes two arguments, but the arguments are on the stack in the wrong order."</p>
-        <p>"For example, if you wanted to get the reciprocal of a number, you would "<Prim prim=Div/>" "<code>"1"</code>" by it. But, if the number is already on the stack, you would need to use "<Prim prim=Backward/>"."</p>
+        <p>"For example, if you wanted to get the reciprocal of a number without using "<Prim prim=Reciprocal/>", you would "<Prim prim=Div/>" "<code>"1"</code>" by it. But, if the number is already on the stack, you would need to use "<Prim prim=Backward/>"."</p>
         <Editor example=" ÷1 5\n˜÷1 5"/>
         <Editor example="    -2 5\nback-2 5"/>
         <br/>

src/algorithm/pervade.rs

@@ -941,6 +941,21 @@ pub mod sign {
         env.error(format!("Cannot get the sign of {a}"))
     }
 }
+pub mod recip {
+    use super::*;
+    pub fn num(a: f64) -> f64 {
+        a.recip()
+    }
+    pub fn byte(a: u8) -> f64 {
+        f64::from(a).recip()
+    }
+    pub fn com(a: Complex) -> Complex {
+        a.recip()
+    }
+    pub fn error<T: Display>(a: T, env: &Uiua) -> UiuaError {
+        env.error(format!("Cannot get the reciprocal of {a}"))
+    }
+}
 pub mod sqrt {
     use super::*;
     pub fn num(a: f64) -> f64 {

src/compile/invert/un.rs

@@ -1240,6 +1240,7 @@ inverse!(PrimPat, input, _, Prim(prim, span), {
         Pop => ImplPrim(UnPop, span),
         Neg => Prim(Neg, span),
         Not => Prim(Not, span),
+        Reciprocal => Prim(Reciprocal, span),
         Sin => ImplPrim(Asin, span),
         Exp => ImplPrim(Ln, span),
         Atan => ImplPrim(UnAtan, span),

src/run_prim.rs

@@ -82,6 +82,7 @@ pub fn run_prim_func(prim: &Primitive, env: &mut Uiua) -> UiuaResult {
         Primitive::Abs => env.monadic_env(Value::abs)?,
         Primitive::Sign => env.monadic_env(Value::sign)?,
         Primitive::Sqrt => env.monadic_env(Value::sqrt)?,
+        Primitive::Reciprocal => env.monadic_env(Value::recip)?,
         Primitive::Exp => env.monadic_env(Value::exp)?,
         Primitive::Sin => env.monadic_env(Value::sin)?,
         Primitive::Floor => env.monadic_env(Value::floor)?,