Forth 2012: BUFFER:

( u "<spaces>name" -- )

Skip leading space delimiters. Parse name delimited by a space. Create a definition for name, with the execution semantics defined below. Reserve u address units at an aligned address. Contiguity of this region with any other region is undefined.

name Execution:

( -- a-addr )

a-addr is the address of the space reserved by BUFFER: when it defined name. The program is responsible for initializing the contents.

See:

A.6.2.0825 BUFFER:.

Rationale:

BUFFER: provides a means of defining an uninitialized buffer. In systems that use a single memory space, this can effectively be defined as:

: BUFFER: ( u "<name>" -- ; -- addr )
CREATE ALLOT
;

However, many systems profit from a separation of uninitialized and initialized data areas. Such systems can implement BUFFER: so that it allocates memory from a separate uninitialized memory area. Embedded systems can take advantage of the lack of initialization of the memory area while hosted systems are permitted to ALLOCATE a buffer. A system may select a region of memory for performance reasons. A detailed knowledge of the memory allocation within the system is required to provide a version of BUFFER: that can take advantage of the system.

It should be noted that the memory buffer provided by BUFFER: is not initialized by the system and that if the application requires it to be initialized, it is the responsibility of the application to initialize it.

Implementation:

This implementation depends on children of CREATE returning an aligned address. Other memory location techniques require implementation-specific knowledge of the underlying Forth system.

: BUFFER: \ u "<name>" -- ; -- addr
\ Create a buffer of u address units whose address is returned at run time.
CREATE ALLOT
;

Testing:

DECIMAL
T{ 127 CHARS BUFFER: TBUF1 -> }T
T{ 127 CHARS BUFFER: TBUF2 -> }T \ Buffer is aligned
T{ TBUF1 ALIGNED -> TBUF1 }T \ Buffers do not overlap
T{ TBUF2 TBUF1 - ABS 127 CHARS < -> <FALSE> }T \ Buffer can be written to
1 CHARS CONSTANT /CHAR
: TFULL? ( c-addr n char -- flag )
   TRUE 2SWAP CHARS OVER + SWAP ?DO
     OVER I C@ = AND
   /CHAR +LOOP NIP
;

T{ TBUF1 127 CHAR * FILL -> }T
T{ TBUF1 127 CHAR * TFULL? -> <TRUE> }T

T{ TBUF1 127 0 FILL -> }T
T{ TBUF1 127 0 TFULL? -> <TRUE> }T