From f857f38f718fff586e373815a1bcad2701b4d983 Mon Sep 17 00:00:00 2001
From: Bruce Hill <bruce@bruce-hill.com>
Date: Mon, 7 Apr 2025 01:17:02 -0400
Subject: Add `is_between()` for various types

---
 docs/bytes.md    | 27 +++++++++++++++++++++++++++
 docs/integers.md | 27 +++++++++++++++++++++++++++
 docs/nums.md     | 27 +++++++++++++++++++++++++++
 3 files changed, 81 insertions(+)

(limited to 'docs')

diff --git a/docs/bytes.md b/docs/bytes.md
index 7cbf7b0c..2e139622 100644
--- a/docs/bytes.md
+++ b/docs/bytes.md
@@ -10,6 +10,7 @@ the `Byte()` constructor: `Byte(5)`.
 # Byte Methods
 
 - [`func hex(byte: Byte, uppercase=no, prefix=yes -> Text)`](#hex)
+- [`func is_between(x: Byte, low: Byte, high: Byte -> Bool)`](#is_between)
 - [`func parse(text: Text -> Byte?)`](#parse)
 - [`func to(first: Byte, last: Byte, step: Int8? = none -> Text)`](#to)
 
@@ -21,6 +22,32 @@ TODO: write docs
 
 ---------
 
+### `is_between`
+Determines if an integer is between two numbers (inclusive).
+
+```tomo
+func is_between(x: Byte, low: Byte, high: Byte -> Bool)
+```
+
+- `x`: The integer to be checked.
+- `low`: The lower bound to check (inclusive).
+- `high`: The upper bound to check (inclusive).
+
+**Returns:**  
+`yes` if `low <= x and x <= high`, otherwise `no`
+
+**Example:**  
+```tomo
+>> Byte(7).is_between(1, 10)
+= yes
+>> Byte(7).is_between(100, 200)
+= no
+>> Byte(7).is_between(1, 7)
+= yes
+```
+
+---
+
 ## `parse`
 
 TODO: write docs
diff --git a/docs/integers.md b/docs/integers.md
index 84a2d1a2..1ee47cbd 100644
--- a/docs/integers.md
+++ b/docs/integers.md
@@ -128,6 +128,7 @@ can be called either on the type itself: `Int.sqrt(x)` or as a method call:
 - [`func factorial(n: Int -> Text)`](#factorial)
 - [`func format(i: Int, digits: Int = 0 -> Text)`](#format)
 - [`func hex(i: Int, digits: Int = 0, uppercase: Bool = yes, prefix: Bool = yes -> Text)`](#hex)
+- [`func is_between(x: Int, low: Int, high: Int -> Bool)`](#is_between)
 - [`func is_prime(x: Int, reps: Int = 50 -> Bool)`](#is_prime)
 - [`func next_prime(x: Int -> Int)`](#next_prime)
 - [`func octal(i: Int, digits: Int = 0, prefix: Bool = yes -> Text)`](#octal)
@@ -268,6 +269,32 @@ The hexadecimal string representation of the integer.
 
 ---
 
+### `is_between`
+Determines if an integer is between two numbers (inclusive).
+
+```tomo
+func is_between(x: Int, low: Int, high: Int -> Bool)
+```
+
+- `x`: The integer to be checked.
+- `low`: The lower bound to check (inclusive).
+- `high`: The upper bound to check (inclusive).
+
+**Returns:**  
+`yes` if `low <= x and x <= high`, otherwise `no`
+
+**Example:**  
+```tomo
+>> (7).is_between(1, 10)
+= yes
+>> (7).is_between(100, 200)
+= no
+>> (7).is_between(1, 7)
+= yes
+```
+
+---
+
 ### `is_prime`
 Determines if an integer is a prime number.
 
diff --git a/docs/nums.md b/docs/nums.md
index 1cc3782a..62cf3564 100644
--- a/docs/nums.md
+++ b/docs/nums.md
@@ -143,6 +143,7 @@ called either on the type itself: `Num.sqrt(x)` or as a method call:
 - [`func format(n: Num, precision: Int = 0 -> Text)`](#format)
 - [`func hypot(x: Num, y: Num -> Num)`](#hypot)
 - [`func isfinite(n: Num -> Bool)`](#isfinite)
+- [`func is_between(n: Num, low: Num, high: Num -> Bool)`](#is_between)
 - [`func isinf(n: Num -> Bool)`](#isinf)
 - [`func j0(x: Num -> Num)`](#j0)
 - [`func j1(x: Num -> Num)`](#j1)
@@ -662,6 +663,32 @@ func isfinite(n: Num -> Bool)
 
 ---
 
+### `is_between`
+Determines if a number is between two numbers (inclusive).
+
+```tomo
+func is_between(x: Num, low: Num, high: Num -> Bool)
+```
+
+- `x`: The integer to be checked.
+- `low`: The lower bound to check (inclusive).
+- `high`: The upper bound to check (inclusive).
+
+**Returns:**  
+`yes` if `low <= x and x <= high`, otherwise `no`
+
+**Example:**  
+```tomo
+>> (7.5).is_between(1, 10)
+= yes
+>> (7.5).is_between(100, 200)
+= no
+>> (7.5).is_between(1, 7.5)
+= yes
+```
+
+---
+
 ### `isinf`
 Checks if a number is infinite.
 
-- 
cgit v1.2.3