From c7438d144bad86e3ad41a071b102c9a93d5077c8 Mon Sep 17 00:00:00 2001
From: Kaz Kylheku <kaz@kylheku.com>
Date: Fri, 5 Jun 2020 09:34:24 -0700
Subject: doc: update iter-begin documentation.

* txr.1: Add more detail about list handling, and cover
numbers and ranges.
---
 txr.1 | 176 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 168 insertions(+), 8 deletions(-)

diff --git a/txr.1 b/txr.1
index cc1a9bb7..9690b4c7 100644
--- a/txr.1
+++ b/txr.1
@@ -33095,13 +33095,12 @@ group. The latter are obsolescent.
 .desc
 The
 .code iter-begin
-function returns an iterator object specialized for the task of traversing
-the sequence
-.metn seq .
-
-If
-.meta object
-isn't a sequence, an exception is thrown.
+function returns an iterator object specialized for the task of traversing the
+.meta seq
+object. The
+.meta seq
+argument may be any sequence. Additionally, it may be a character, number or
+a numeric or character range.
 
 Note: if
 .meta seq
@@ -33109,7 +33108,28 @@ is a list-like sequence, then
 .code iter-begin
 may return
 .meta seq
-itself as the iterator.
+itself as the iterator. Likewise if
+.meta seq
+is a number.
+
+A range is considered to be a numeric or character range if the
+.code from
+element is a number or character. The
+.code to
+is then required to to be either value which is comparable with that number
+or character using the
+.code <
+function, or else it must be one of the two objects
+.code t
+or
+.codn : ,
+either of which indicate that the range is unbounded. In this unbounded range
+case, the expressions
+.code "(iter-begin X..:)"
+and
+.code "(iter-begin X..t)"
+are equivalent to
+.codn "(iter-begin X)" .
 
 .coNP Function @ iter-more
 .synb
@@ -33137,6 +33157,72 @@ The
 function doesn't change the state of
 .metn iter .
 
+If
+.code iter
+is the object
+.code nil
+then
+.code nil
+is returned.
+Note: the
+.code iter-begin
+may return
+.code nil
+if its argument is
+.code nil
+or any empty sequence, or an empty range (a range whose
+.code to
+and
+.code from
+fields are the same number or character).
+
+If
+.meta iter
+is a
+.code cons
+cell, then
+.code iter-more
+returns
+.codn t .
+
+If
+.meta iter
+is a number, then
+.code iter-more
+returns
+.codn t .
+This is the case even if calculating the successor of that number isn't possible
+due to floating-point overflow or insufficient system resources.
+
+If
+.meta iter
+is a character, then
+.code iter-more
+returns
+.code t
+if
+.meta iter
+isn't the highest possible character code, otherwise
+.codn nil .
+
+If
+.meta iter
+was formed from a descending range, meaning that
+.code iter-begin
+was invoked on a range with a
+.code from
+fielding exceeding its
+.code to
+value, then
+.code iter-begin
+returns true while the current iterator value is greater than the
+the limiting value given by the
+.code to
+field. For an ascending range, it returns true if the current iterator value is
+lower than the limiting value. However, note the peculiar semantics of
+.code iter-item
+with regard to descending range iteration.
+
 .coNP Function @ iter-item
 .synb
 .mets (iter-item << iter )
@@ -33167,6 +33253,62 @@ is invoked on an iterator which indicates that no more items
 remain to be visited, the return value is
 .codn nil .
 
+If
+.meta iter
+is a
+.code cons
+cell, then
+.code iter-item
+returns the
+.code car
+field of that cell.
+
+If
+.meta iter
+is a character or number, then
+.code iter-item
+returns that character or number itself.
+
+If
+.meta iter
+is based on an ascending numeric or character range, then
+.code iter-item
+returns the current iteration value, which is initialized by
+.code iter-begin
+as a copy of the range's
+.code from
+field. Thus, the range
+.code 0..3
+traverses the values
+.codn 0 ,
+.code 1
+and
+.codn 2 ,
+excluding the
+.codn 3 .
+
+If
+.meta iter
+is based on a descending numeric or character range, then
+.code iter-item
+returns the predecessor of the current iteration value, which is initialized
+.code iter-begin
+as a copy of the range's
+.code from
+field.
+Thus, the range
+.code 3..0
+traverses the values
+.codn 2 ,
+.code 1
+and
+.codn 0 ,
+excluding the
+.codn 3 :
+exactly the same values are visited as for the range
+.code 0..3
+only in reverse order.
+
 .coNP Function @ iter-step
 .synb
 .mets (iter-step << iter )
@@ -33209,6 +33351,24 @@ If
 is invoked on an iterator which indicates that no more items
 remain to be visited, the return value is unspecified.
 
+If
+.meta iter
+is a
+.code cons
+cell, then
+.code iter-step
+returns the
+.code cdr
+field of that cell.
+
+If
+.meta iter
+is a character or number, then
+.code iter-step
+returns its successor, as if using the
+.code succ
+function.
+
 .coNP Function @ iter-reset
 .synb
 .mets (iter-reset < iter << seq )
-- 
cgit v1.2.3