(       Title:  Dynamic String Arrays
         File:  dstring-array.fs
      Version:  0.1.1
       Author:  David N. Williams
      License:  LGPL
Starting date:  April 8, 2002
Last revision:  March 30, 2007
)
\ Copyright (C) 2002, 2004, 2007  David N. Williams
(
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or at your option any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free
Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
MA 02111-1307 USA.

Please see the file POLITENESS included with this distribution.

This code is written for the Dynamic-Strings word set, version
0.7.2 or later, as implemented in pfe or dstrings.fs.  It is ANS
Forth compatible when PFE has its default false value except
for:
- Case sensitivity.
- [UNDEFINED]

This file is compatible when loaded in either order with
sarray.fs.  However, please note that strings in ANS Forth
string arrays made with

  S[ C," ..." C," ..." ... ]S#
  S[ C," ..." C," ..." ... ]S

are not stored with string counts followed by string bodies.  To
put them on the dstring stack, >$S-COPY must be used.

The last revision date may reflect cosmetic changes not recorded
below.

Version 0.1.1
29Nov04 * Renamed:
          Old   New
          S,"   C,"
          ${    $[
          }$    ]$
          }$#   ]$#
          ]$@   }$@
          ]$!   }$!
        * Revised comments.
        * New syntax examples.
 6Mar07	* Fixed erroneous stack effect for ]$.
30Mar07 * Added conditional compilation switch for PFE.

Version 0.1.0
 8Apr02 * Start and release.
)
decimal

\ true constant PFE
[UNDEFINED] PFE [IF] false constant PFE [THEN]
PFE [IF]
  loadm dstrings
\ cr .( Using pfe dstrings.)
[ELSE]  \ ANS Forth
  s" dstrings.fs" included
\ cr .( Using ANS dstrings.fs.)
[THEN]

[UNDEFINED] -1cells
[IF] -1 cells constant -1cells [THEN]

[UNDEFINED] start-depth
[IF] variable start-depth [THEN]

: $[  ( -- )
(
Set START-DEPTH to $DEPTH.
)
  $depth start-depth ! ;

: ]$#  ($: $1 ... $n -- s: &array n )
(
Make a dynamic-string array in data space from the string stack
frame started by the most recently executed $[, and leave its
address and number of elements n.  Store the elements in the
order 1...n.
)
  $depth start-depth @
  2dup <= ABORT" ***Improper string data frame."
  - ( n) dup >r
  align here ( &array) >r
  ( n) cells allot
  r@ ( 'first)   here -1cells + ( 'last)
  DO
    0 i !  \ null is outside string space, so
    i $!   \ $! writes over it
  -1cells +LOOP
  r> ( &array) r> ( n) ; 

: ]$  ($: $1 ... $n -- s: &array )  ]$# drop ;

: }$@  ( &array u -- $: u-th$ )
(
Leave the u-th dynamic string in the array with layout like
$[ ... ]$.  The count starts at zero.  No array bounds check.
)
  cells + $@ ;

: }$!  ( &array u $: a$ -- )
(
Store a$ as the u-th dynamic string in the array with layout
like $[ ... ]$.  No array bounds check.
)
  cells + $! ;

0 [IF]  \ syntax examples

$[ $" El"   $" que"   $" es"   $" perico"
   $" dondequiera"   $" es"   $" verde"
]$# constant #perico$
    constant perico${

: .ith-perico$  ( u -- )  perico${ swap }$@ $. ;

: .perico$  ( -- )  cr space
  #perico$ 0 DO
    space i .ith-perico$
    perico${ i }$@ $s> s" perico" compare 0=
    IF [char] , emit THEN
  LOOP [char] . emit cr ;

.perico$

[THEN]