Proposal: Standardize the well-known BOUNDS

Author:

Eric Blake

Change Log:

2025-10-10 Initial proposal

Problem:

When working with strings, it is not uncommon to want to use a do/loop iteration over characters in the string. The word also works with other array types with a different stride length than characters. Several proposed example implementations have relied on use of the word bounds, because it is well-known across a number of Forth implementations.

Solution:

Standardizing bounds will guarantee that library code can use this word if present for converting an addr u pair to proper bounds for a ?do/+loop, without worrying about it having different semantics than what most users have come to expect.

A pure-Forth implementation using other standard words is fairly trivial with a public domain implementation; therefore the new word can be optional.

This proposal sticks the new word in the String Extension word set; although I'm amenable to the committee placing it in whatever word set makes the most sense.

Typical use:

type bounds ?do ... loop \ iterate over characters of input buffer
... constant arr-len  arr-len cells buffer: arr
arr arr-len cells bounds ?do ... 1 cells +loop \ iterate over cells of arr

(Editor's note: the first line relies on the existing post-2012 change to make 1 chars = 1)

The latest forth21-1.pdf draft already includes two conditional definitions of bounds (namely, E.15.6.2.---- find-name and E.17.6.2.2255 substitute), along with a use of bounds in Appendix F.15.6.2.---- find-name with no prior definition in the rest of the test suite in the draft. The tests for find-name in the draft document are not yet reflected into Gerry's testsuite repository as of v0.15.0, but that may be an intentional difference between testing Forth 2012 vs. Forth-202x.

Proposal:

Add a new glossary entry:

17.6.2.---- bounds String-Ext
( addr.start u -- addr.end addr.start )

Compute loop bounds suitable for `?do` for the array starting at addr.start and covering u addressable units, where addr.end is the first address beyond the array.

See: 6.1.1240 do, 6.2.0620 ?do

Rationale: This is a common factor for computing the bounds of a do/loop iteration over each element of an array.  Before using `bounds` on an array whose elements are larger than an addressable unit, the number of elements must first be scaled by the same amount as will later be passed to `+loop`.

Other edits needed (based on forth21-1.pdf):

In E.15.6.2.---- find-name, delete the lines:

[UNDEFINED] bounds [IF]
: bounds ( addr len -- addr+len addr )
OVER + SWAP
;
[THEN]

In E.17.6.2.2255 substitute, delete the lines:

[UNDEFINED] bounds [IF]
: bounds
\ addr len -- addr+len addr
OVER + SWAP
;
[THEN]

Reference implementation:

: bounds ( addr.start u -- addr.end addr.start ) over + swap ;

Testing:

t{ 2 3 bounds -> 5 2 }t
t{ : bnd1 2>r 0 2r> bounds ?do 1+ loop ; -> }t \ slow computation of string length
t{ 0 0 bnd1 -> 0 }t
t{ s" 123" bnd1 -> 3 }t
t{ : bnd2 bounds ?do i c@ loop ; -> }t \ breaks string into characters, last on top
t{ s" 123" bnd2 -> '1' '2' '3' }t

(Editorial note: Other than in the subject, this proposal uses lower-case naming of all words, on the grounds that other proposals in flight deal with either making future Forth case-insensitive on standard words, or with ensuring the standard words are converted to upper-case in renderings as needed.)