From 24fb5194ad18da2c25f969d288777c881f28d4d6 Mon Sep 17 00:00:00 2001
From: Kaz Kylheku <kaz@kylheku.com>
Date: Tue, 6 Mar 2018 06:10:25 -0800
Subject: New function: bignum-len.

* arith.c (bignum_len): Wew function.
(arith_init): Register bignum-len intrinsic.

* arith.h (bignum_len): Declared.

* txr.1: Documented.
---
 arith.c | 13 +++++++++++++
 arith.h |  1 +
 txr.1   | 32 ++++++++++++++++++++++++++++++++
 3 files changed, 46 insertions(+)

diff --git a/arith.c b/arith.c
index ec1eff5b..c9c1bf3e 100644
--- a/arith.c
+++ b/arith.c
@@ -192,6 +192,18 @@ val unum(ucnum u)
   }
 }
 
+val bignum_len(val num)
+{
+  switch (type(num)) {
+  case CHR: case NUM:
+    return zero;
+  case BGNUM:
+    return unum(mp(num)->used);
+  default:
+    type_mismatch(lit("bignum-digits: ~s is not an integer"), num, nao);
+  }
+}
+
 int highest_bit(int_ptr_t n)
 {
 #if SIZEOF_PTR == 8
@@ -3089,6 +3101,7 @@ void arith_init(void)
   reg_varl(intern(lit("*e*"), user_package), flo(M_E));
   reg_varl(intern(lit("%e%"), user_package), flo(M_E));
 
+  reg_fun(intern(lit("bignum-len"), user_package), func_n1(bignum_len));
   reg_fun(intern(lit("divides"), user_package), func_n2(divides));
   reg_fun(intern(lit("bits"), system_package), func_n1(bits));
   reg_fun(intern(lit("digpow"), user_package), func_n2o(digpow, 1));
diff --git a/arith.h b/arith.h
index a07a4bed..922a693a 100644
--- a/arith.h
+++ b/arith.h
@@ -36,6 +36,7 @@ val normalize(val bignum);
 val in_int_ptr_range(val bignum);
 ucnum c_unum(val num);
 val unum(ucnum u);
+val bignum_len(val num);
 val cum_norm_dist(val x);
 val inv_cum_norm(val p);
 val n_choose_k(val n, val k);
diff --git a/txr.1 b/txr.1
index a8a482b2..bf334df5 100644
--- a/txr.1
+++ b/txr.1
@@ -35650,6 +35650,38 @@ that value is then added to the result accumulator.
   (rpoly 10 '(1 2 3)) -> 321
 .cble
 
+.coNP Function @ bignum-len
+.synb
+.mets (bignum-len << arg )
+.syne
+.desc
+The
+.code bignum-len
+function reports the machine-specific
+.I "bignum order"
+of the integer or character argument
+.metn arg .
+
+If
+.meta arg
+is a character or
+.code fixnum
+integer, the function returns zero.
+
+Otherwise
+.meta arg
+is expected to be a
+.code bignum
+integer, and the function returns the number of "limbs" used for its
+representation, a positive integer.
+
+Note: the
+.code bignum-len
+function is intended to be of use in algorithms whose performance
+benefits from ordering the operations on multiple integer operands
+according to the magnitudes of those operands. The function provides an
+estimate of magnitude which trades accuracy for efficiency.
+
 .SS* Bit Operations
 In \*(TL, similarly to Common Lisp, bit operations on integers are based
 on a concept that might be called "infinite two's-complement".  
-- 
cgit v1.2.3