New function, clamp.

* eval.c (eval_init): Register clamp as intrinsic function.

* lib.c (clamp): New function.

* lib.h (clamp): Declared.

* txr.1: Documented.

4 files changed, 45 insertions, 0 deletions

diff --git a/eval.c b/eval.c
index b7e31992..b5e334c5 100644
--- a/eval.c
+++ b/eval.c
@@ -4349,6 +4349,7 @@ void eval_init(void)
   reg_fun(intern(lit("/="), user_package), func_n0v(numneqv));
   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("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("in"), user_package), func_n4o(in, 2));
diff --git a/lib.c b/lib.c
index 59f27aa6..4df1b1d8 100644
--- a/lib.c
+++ b/lib.c
@@ -2293,6 +2293,11 @@ val minv(val first, val rest)
   return reduce_left(func_n2(min2), rest, first, nil);
 }
 
+val clamp(val low, val high, val num)
+{
+  return max2(low, min2(high, num));
+}
+
 val exptv(val nlist)
 {
   return reduce_right(func_n2(expt), nlist, one, nil);
diff --git a/lib.h b/lib.h
index ad5194bd..646038a3 100644
--- a/lib.h
+++ b/lib.h
@@ -583,6 +583,7 @@ val max2(val a, val b);
 val min2(val a, val b);
 val maxv(val first, val rest);
 val minv(val first, val rest);
+val clamp(val low, val high, val num);
 val expt(val base, val exp);
 val exptv(val nlist);
 val exptmod(val base, val exp, val mod);
diff --git a/txr.1 b/txr.1
index fe7a8536..1e25f8e8 100644
--- a/txr.1
+++ b/txr.1
@@ -23686,6 +23686,44 @@ Thus
 means
 .codn (max (max a b) c) .
 
+.coNP Function @ clamp
+.synb
+.mets (clamp < low < high << val )
+.syne
+.desc
+The
+.code clamp
+function clamps value
+.meta val
+into the range
+.meta low
+to
+.metn high .
+
+The
+.code clamp
+function returns
+.meta low
+if
+.meta val
+is less than
+.metn low .
+If
+.meta val
+is greater than or equal to
+.metn low ,
+but less than
+.metn high ,
+then it returns
+.metn val .
+Otherwise it returns
+.meta high .
+
+More precisely,
+.code (clamp a b c)
+is equivalent to
+.codn (max a (min b c)) .
+
 .coNP Functions @, int-str @ flo-str and @ num-str
 .synb
 .mets (int-str < string <> [ radix ])