RfC: Structures
Peter Knaggs
===============
2010=08-31 Revised into a documentation change (RfC)
2010-03-17 Corrected spelling of FILED:
Revised wording at Rostock meeting
Introduction of rationale text.
2010-02-24 Drafting of RfD
2009-09-03 Original wordsmithing of solution during 200x meeting.
Problem
=======
The X:structures extension defines FIELD: as:
10.6.2.xxxx FIELD: "field-colon" FACILITY EXT
( -- ) X:structures
The semantics of FIELD: are identical to the execution semantics
of the phrase:
ALIGNED 1 CELLS +FIELD
See: 10.6.2.---- +FIELD, 10.6.2.---- BEGIN-STRUCTURE and
10.6.2.---- END-STRUCTURE.
While this is a very concise definition, there are a few difficulties
with it:
1) The stack description is incorrect, it should be:
( n1 "<spaces>name" -- n2 )
2) It defines a child word which is not described. Normally this is
described in a "name Execution" clause.
3) There is no actual description of the word, simply what amounts
to a reference implementation.
This applies to CFIELD:, DFFIELD:, FFIELD: and SFFIELD: as well.
Solution
========
Replace the definition of FIELD: and friends with:
10.6.2.xxxx FIELD: "field-colon" FACILITY EXT
( n1 "<spaces>name" -- n2 ) X:structures
Skip leading space delimiters. Parse /name/ delimited by a space.
/Offset/ is the first cell aligned value greater than or equal to
n1. n2 = offset + 1 cells.
Create a definition for /name/ with the execution semantics given
below.
/name/ Execution: ( a-addr1 -- a-addr2 )
Add the /offset/ calculated during the compile time action to
a-addr1 giving the cell aligned address a-addr2.
See: 10.6.2.---- BEGIN-STRUCTURE, A.10.6.---- BEGIN-STRUCTURE,
A.10.6.2.---- FIELD:
Proposal
========
Modify the definition of the following words in accordance with the
text given in the Solution, above, with the modification of the
alignment as follows:
FIELD: cell aligned
CFIELD: character aligned
FFIELD: float aligned
SFFIELD: single-float aligned
DFFIELD: double-float aligned
Add the following as the Rationale for 10.6.2.---- FIELD:
A.10.6.2.xxxx FIELD:
Create an aligned single cell field in a data structure.
The various /x/FIELD: words provide for different alignment and
size allocation.
The /x/FIELD: words could be defined as:
: FIELD: ALIGNED 1 CELLS +FIELD ; \ cell aligned
: CFIELD: 1 CHARS +FIELD ; \ character aligned
: FFIELD: FALIGNED 1 FLOATS +FIELD ; \ float aligned
: SFFIELD: SFALIGNED 1 SFLOATS +FIELD ; \ single-float aligned
: DFFIELD: DFALIGNED 1 DFLOATS +FIELD ; \ double-float aligned
Author
======
Peter Knaggs <p...@bcs.org.uk>
Engineering, Mathematics and Physical Sciences,
University of Exeter, Exeter, Devon EX4 7QF, England