From 90fe70b5364b205f3e17fa1de73c6b8bc8ad0bda Mon Sep 17 00:00:00 2001
From: Kaz Kylheku <kaz@kylheku.com>
Date: Sun, 24 Feb 2019 20:14:17 -0800
Subject: bracket: new function.

* eval.c (eval_init): Register bracket intrinsic.

* lib.c (bracket): New function.

* lib.h (bracket): Declared.

* txr.1: Documented.
---
 eval.c |  1 +
 lib.c  | 13 ++++++++++++
 lib.h  |  1 +
 txr.1  | 72 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 87 insertions(+)

diff --git a/eval.c b/eval.c
index 6a611e8d..cd99424e 100644
--- a/eval.c
+++ b/eval.c
@@ -6470,6 +6470,7 @@ void eval_init(void)
   reg_fun(intern(lit("max"), user_package), func_n1v(maxv));
   reg_fun(intern(lit("min"), user_package), func_n1v(minv));
   reg_fun(intern(lit("clamp"), user_package), func_n3(clamp));
+  reg_fun(intern(lit("bracket"), user_package), func_n1v(bracket));
   reg_fun(intern(lit("pos-max"), user_package), func_n3o(pos_max, 1));
   reg_fun(intern(lit("pos-min"), user_package), func_n3o(pos_min, 1));
   reg_fun(intern(lit("mismatch"), user_package), func_n4o(mismatch, 2));
diff --git a/lib.c b/lib.c
index 00807a85..194d8cb6 100644
--- a/lib.c
+++ b/lib.c
@@ -3586,6 +3586,19 @@ static val rexpt(val right, val left)
   return expt(left, right);
 }
 
+val bracket(val larg, struct args *args)
+{
+  cnum index = 0;
+
+  while (args_more(args, index)) {
+    val rarg = args_get(args, &index);
+    if (less(larg, rarg))
+      return num(index - 1);
+  }
+
+  return num(index);
+}
+
 val exptv(struct args *nlist)
 {
   cnum nargs = args_count(nlist);
diff --git a/lib.h b/lib.h
index c426fe64..cb1b2ef6 100644
--- a/lib.h
+++ b/lib.h
@@ -740,6 +740,7 @@ val minv(val first, struct args *rest);
 val maxl(val first, val rest);
 val minl(val first, val rest);
 val clamp(val low, val high, val num);
+val bracket(val larg, struct args *args);
 val expt(val base, val exp);
 val exptv(struct args *nlist);
 val exptmod(val base, val exp, val mod);
diff --git a/txr.1 b/txr.1
index 1b24e74c..be56ff2f 100644
--- a/txr.1
+++ b/txr.1
@@ -36197,6 +36197,78 @@ More precisely,
 is equivalent to
 .codn "(max a (min b c))" .
 
+.coNP Function @ bracket
+.synb
+.mets (bracket < value << level *)
+.syne
+.desc
+The
+.code bracket
+function's arguments consist of one required
+.meta value
+followed by
+.I n
+.meta level
+arguments.
+The
+.meta level
+arguments are optional; in other words,
+.I n
+may be zero.
+
+The
+.code bracket
+function calculates the
+.I bracket
+of the
+.meta value
+argument: a zero-based positional index of the value, in relation to the
+.meta level
+arguments.
+
+Each of the
+.meta level
+arguments, of which there may be none, is associated with
+an integer index, starting at zero, in left to right order. The
+.meta level
+arguments are examined in that order. When a
+.meta level
+argument is encountered which exceeds
+.metn value ,
+that
+.meta level
+argument's index is returned.
+If
+.meta value
+exceeds all of the
+.meta level
+arguments, then
+.I n
+is returned.
+
+Determining whether
+.meta value
+exceeds a
+.meta level
+is performed using the
+.code less
+function.
+
+.TP* Examples:
+
+.cblk
+  (bracket 42) -> 0
+  (bracket 5 10) -> 0
+  (bracket 15 10) -> 1
+  (bracket 15 10 20) -> 1
+  (bracket 15 10 20 30) -> 1
+  (bracket 20 10 20 30) -> 2
+  (bracket 35 10 20 30) -> 3
+  (bracket "a" "aardvark" "zebra") -> 0
+  (bracket "ant" "aardvark" "zebra") -> 1
+  (bracket "zebu" "aardvark" "zebra") -> 2
+.cble
+
 .coNP Functions @, int-str @ flo-str and @ num-str
 .synb
 .mets (int-str < string <> [ radix ])
-- 
cgit v1.2.3