Home Building DHTML Scripting Using Diaperglu Documention Key Script Commands Reference C Library API Reference Handy References About License Contact Forth Draft Standard
Directory Documentation key   C Functions How string stack works dg_forthcomparestring dg_forthgetmidstring dg_forthcatstring dg_forthlengthstring dg_forthshortenstring dg_forthpickstring dg_forthdupstring dg_forthoverstring dg_forthdropstring dg_forthdeletestring dg_forthswapstring dg_forthnipstring dg_forthrotstring dg_forthdepthstring dg_forthnewstring dg_forthctonewstring dg_forthtonewstring dg_forthturnstringinto0string dg_forthinsertinstring dg_forthdeleteinstring dg_forthstringcfetch dg_forthstringcstore dg_forthstringtoc dg_forthstringto dg_forthctostring dg_forthtostring dg_forthstringquotes dg_forthholdstring dg_forthnumbersignstring dg_forthnumbersignsstring dg_forthsignstring dg_forthsplitstring dg_forthputmidstring dg_forthstostring dg_forthgetsstringnd dg_forthprintstring dg_forthloadfilestring dg_forthsavefilestring dg_forthincludefilestring dg_forthqueryincludefilestring dg_forthfreelibrary dg_forthgetenvstring dg_forthgetmethodstring dg_forthgetquerystring dg_forthcscanstring dg_forthminuscscanstring dg_forthasciitounicodestring dg_forthunicodetoasciistring dg_forthgrowstring dg_forthrollstring dg_forthminusrollstring dg_forthdeleteinstringnd dg_forthinsertinstringnd dg_forthcatstringnd dg_forthurlencodestring dg_forthurldecodestring dg_forthstringtobackslashstring dg_forthbackslashstringtostring dg_forthstripstring dg_forthdotstrings dg_forthstrippathfromfilenamestring dg_forthvariableflstring dg_forthfillnewstring dg_forthpzerostrtonewstr dg_forthnglufilestring dg_forthglufilestring dg_forthwordsstringquotes dg_forthwords0stringquotes dg_forthgetargsfromnstrings dg_forthrunfileandwaitnoenvquotes dg_forthtostarulestring dg_forthtoslashulestring dg_forthulestringtonumberstring dg_forthnotstring dg_forthreversestring dg_forthlelshiftstring dg_forthulershiftstring dg_forthslershiftstring dg_forthlelshiftcstring dg_forthlershiftcstring dg_forthuleandstring dg_forthuleorstring dg_forthulexorstring dg_forthulenandstring dg_forthulenorstring dg_forthulexnorstring dg_forthtofactorialulestring
// //////////////////////////////////////////////////////////////////////////////////////
//
// How the string stack works
//
// The string stack is just an lstring stack. The string stack will grow in size
//  as needed up until the operating system runs out of memory. Indexes into the
//  string stack are 0 based depth indexes where 0 indexes the top of the string
//  stack. Offsets into a string are 0 based and are in bytes. Lengths are in bytes.
//
// Many of the string stack operations are designed for efficiency and speed, to
//  eliminate as many unnecessary copies as possible. For example, the catenate
//  string function does not need to move any bytes of either string. It just
//  deletes the end offset of one of the strings from the lstring stack.
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthcomparestring ( COMPARE$ =$ )
//
// C prototype:
//  void dg_forthcomparestring ( Bufferhandle* pBHarrayhead )
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( $1 $2 -$- $1 $2 )
//  ( -- flag )
//
// String stack in:
//  $1 $2
//
// String stack out:
//  $1 $2
//
// Data stack out:
//  flag                          flag = 1 if $1 > $2, 
//                                flag = 0 if $1 = $2, 
//                                flag = -1 if $1 < $2
//                                                            
// Action:
//  pops parameters from the data stack
//  removes the top lstring from the lstring stack
//
// Failure cases:
//  error getting number of strings on string stack
//  string stack underflow
//  error getting pointer to string 1
//  error getting pointer to string 2
//  error pushing flag
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthgetmidstring ( GETMID$ )
//
// C prototype:
//  void dg_forthgetmidstring ( Bufferhandle* pBHarrayhead )
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( $1 -$- $1 $2 )
//  ( offset length -- )
//
// String stack in:
//  $1 
//
// String stack out:
//  $1 $2
//
// Data stack in:
//  offset                        offset in $1 of substring
//  length                        length of substring
//                                                            
// Action:
//  pops offset and length from data stack
//  pushes the substring of $1 specified by offset and length to the string stack
//
// Failure cases:
//  error getting pointer to the data stack
//  data stack underflow
//  error getting number of strings on string stack
//  string stack underflow
//  error getting top string's start offset
//  error getting top string's length
//  length is longer than length of top string
//  offset + length > length of top string 
//  error growing string stack's string buffer by length
//  error pushing new end offset to string stack's offset buffer
//  error getting pointer to string stack's string buffer
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// $>$ or CATENATE$
//
// C prototype:
//  void dg_forthcatstring ( Bufferhandle* pBHarrayhead )
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the  
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( $1 $2 -$- $3 )
//
// String stack in:
//  $1 $2
//
// String stack out:
//  $3                            $1 and $2 joined into one string
//                                                            
// Action:
//  joins $1 and $2 together with the bytes in $2 following the bytes in $1
//
// Failure cases:
//  error getting pointer to the string offset stack
//  string offset stack underflow
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthlengthstring ( LENGTH$ )
//
// C prototype:
//  void dg_forthlengthstring ( Bufferhandle* pBHarrayhead )
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the  
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( $1 -$- $1 )
//  ( -- length )
//
// String stack in:
//  $1
//
// String stack out:
//  $1
//                                                           
// Data stack out:
//  length                        length of top string on string stack
// 
// Action:
//  pushes the length of the top string on the string stack onto the data stack
//
// Failure cases:
//  error getting number of strings on the string stack
//  string stack underflow
//  error getting length of the top string on the string stack
//  error pushing length to the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthshortenstring ( SHORTEN$ )
//
// C prototype:
//  void dg_forthshortenstring ( Bufferhandle* pBHarrayhead )
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( $1 -$- $1' )
//  ( n -- )
//
// String stack in:
//  $1
//
// String stack out:
//  $1'                           shorter version of string 1
//                                                           
// Data stack in:
//  n                             number of characters (bytes) to remove from the 
//                                 end of $1
// 
// Action:
//  removes n characters (bytes) from the end of the top string on the string stack
//  if n is greater than the length of the string the string is shortened to 0 
//   characters (bytes)
//
// Failure cases:
//  error popping n from the data stack
//  error getting pointer to the string offset stack
//  string offset stack underflow
//  string offset stack corrupt error - start offset > end offset
//  error shrinking string string stack buffer
//  
// //////////////////////////////////////////////////////////////////////////////////////            
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthpickstring ( PICK$ )
//
// C prototype:
//  void dg_forthpickstring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the  
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( $x .. $3 $2 $1 $0 -$- $x ... $3 $2 $1 $0 $[nidx] )
//  ( idx -- )
//
// String stack in:
//  $x ... $3 $2 $1 $0
//
// String stack out:
//  $x ... $3 $2 $1 $0 $x
//                                                           
// Data stack in:
//  x                             string to push to the top of the string stack, 
//                                 where x=0 pushes a copy of the top string on the 
//                                 string stack
// 
// Action:
//  pushes a copy of the string at x from top of the string stack onto the string 
//   stack
//
// Failure cases:
//  error popping x off of the data stack
//  error pushing a copy of string x onto the top of the string stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthdupstring ( DUP$ )
//
// C prototype:
//  void dg_forthdupstring ( Bufferhandle* pBHarrayhead )
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the  
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( $1 -$- $1 $1 )
//
// String stack in:
//  $1 
//
// String stack out:
//  $1 $1
//                                                           
// Action:
//  pushes a copy of the string at the top of the string stack to the string stack
//
// Failure cases:
//  error pushing 0 to the data stack
//  error doing pick string
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthoverstring ( OVER$ )
//
// C prototype:
//  void dg_forthoverstring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( $1 $0 -$- $1 $0 $1 )
//
// String stack in:
//  $1 $0
//
// String stack out:
//  $1 $0 $1
//                                                           
// Action:
//  pushes a copy of the string at 1 from the top of the string stack to the string 
//   stack
//
// Failure cases:
//  error pushing 1 to the data stack
//  error doing pick string
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthdropstring ( DROP$ )
//
// C prototype:
//  void dg_forthdropstring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the  
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( $0 -$- )
//
// String stack in:
//  $0 
//                                                           
// Action:
//  removes the top string from the string stack
//
// Failure cases:
//  error doing dg_droplstring
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthdeletestring ( DELETE$ )
//
// C prototype:
//  void dg_forthdeletestring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the  
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( ... $n+1 $n $n-1... $1 $0 -$- $n+1 $n-1 ... $1 $0 )
//  ( n -- )
//
// String stack in:
//  $n+1 $n $n-1 ... $1 $0
//
// String stack out:
//  $n+1 $n-1 ... $1 $0
//                                                           
// Action:
//  removes string at n from the top of the string stack from the string stack
//
// Failure cases:
//  error popping n from the data stack
//  error doing dg_deletelstring
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthswapstring ( SWAP$ )
//
// C prototype:
//  void dg_forthswapstring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( $1 $0 -$- $0 $1 )
//
// String stack in:
//  $1 $0
//
// String stack out:
//  $0 $1
//                                                           
// Action:
//  swaps the top two strings on the string stack
//
// Failure cases:
//  error getting number of strings on string stack
//  string stack underflow
//  error doing dg_forthoverstring
//  error doing dg_forthdeletestring
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthnipstring ( NIP$ )
//
// C prototype:
//  void dg_forthnipstring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( $1 $0 -$- $0 )
//
// String stack in:
//  $1 $0
//
// String stack out:
//  $0 
//                                                           
// Action:
//  removes the next to the top string from the string stack
//
// Failure cases:
//  error getting string stack depth
//  string stack underflow
//  error doing dg_deletelstring
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthrotstring ( ROT$ )
//
// C prototype:
//  void dg_forthrotstring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( $2 $1 $0 -$- $0 $1 $2 )
//
// String stack in:
//  $2 $1 $0
//
// String stack out:
//  $0 $1 $2
//                                                           
// Action:
//  moves the string two away from the top of the string stack to the top of the 
//   string stack
//
// Failure cases:
//  error getting number of strings on string stack
//  string stack underflow
//  error doing dg_picklstring
//  error doing dg_deletelstring
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthdepthstring ( DEPTH$ )
//
// C prototype:
//  void dg_forthdepthstring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the  
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( -- n )
//  ( $1 $2 $3 ... $n -$- $1 $2 $3 ... $n )
//
// String stack in:
//  n$ ... $3 $2 $1
//
// String stack out:
//  n$ ... $3 $2 $1
//
// Data stack out:
//  n
//                                                           
// Action:
//  pushes the number of strings on the string stack to the data stack
//
// Failure cases:
//  error getting number of strings on string stack
//  error pushing to data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthnewstring ( NEW$ or <#$ )
//
// C prototype:
//  void dg_forthnewstring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the  
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( -$- empty$ )
//
// String stack out:
//  empty$
//                                                           
// Action:
//  pushes an empty string onto the string stack
//
// Failure cases:
//  error doing dg_pushlstring  
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthctonewstring ( C>NEW$ )
//
// C prototype:
//  void dg_forthctonewstring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the  
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( char -- )
//  ( -$- char$ )      
//
// Data stack in:
//  char
// 
// String stack out:
//  char$
//                                                           
// Action:
//  pushes a one character string containing the character (byte) onto the string 
//   stack
//
// Failure cases:
//  error popping the character from the data stack
//  error doing dg_pushlstring  
//
// //////////////////////////////////////////////////////////////////////////////////////     
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthtonewstring ( >NEW$ )
//
// C prototype:
//  void dg_forthtonewstring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//     ( u -- )
//     ( -$- u$ )      
//
// Data stack in:
//  u
// 
// String stack out:
//  u$
//                                                           
// Action:
//  Pushes an four character string containing the bytes of the UINT64 u onto the 
//   string stack.
//  On an x86 machine these bytes are in low to high order (little endian) which 
//   means HEX 41424344 >NEW$ .$ will show 'DCBA'
//
// Failure cases:
//  error popping the UINT64 u from the data stack
//  error doing dg_pushlstring  
//
// //////////////////////////////////////////////////////////////////////////////////////   
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthturnstringinto0string ( $>0$ )
//
// C prototype:
//  void dg_forthturnstringinto0string (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( $1 -$- 0$1 )
//
// Data stack in:
//  $1
// 
// String stack out:
//  0$1
//                                                           
// Action:
//  appends a null terminator to the end of the top string on the string stack
//
// Failure cases:
//  error doing dg_pushlstring  
//  error doing dg_forthcatstring
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthinsertinstring ( INSERTIN$ )
//
// C prototype:
//  void dg_forthinsertinstring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( offset length -- )
//  ( $1 -$- $' )
//
// Data stack in:
//  offset                        offset into top string on string stack in characters 
//                                 (bytes)
//  length                        number of characters (bytes) to insert at offset 
//  
// String stack in:
//  $1
// 
// String stack out:
//  $1'
//                                                         
// Action:
//  the length of the top string on the string stack is increased by length 
//   characters (bytes)
//  then the character at the offset and the ones following it in the top string 
//   on the string stack are moved up length characters (bytes)
//  the characters in the area of the insert are left unchanged
//  note: the first character in the string is at offset 0
//
//  Example:
//   $" abcdef" 2 3 INSERTIN$ 
//   is the same as $" abcdecdef"
//
// Failure cases:
//  error getting pointer to the data stack
//  data stack underflow error
//  error getting number of strings on the string stack
//  string stack underflow error
//  error getting start offset of top string
//  error inserting in string stack's string buffer
//  error getting new buffer length of string stack's string buffer
//  error putting new end offset in string stack's offset buffer
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthdeleteinstring ( DELETEIN$ )
//
// C prototype:
//  void dg_forthdeleteinstring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the  
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( offset length -- )
//  ( $1 -$- $1' )
//
// Data stack in:
//  offset                        offset into top string on string stack in characters 
//                                 (bytes)
//  length                        number of characters (bytes) to delete at offset 
//  
// String stack in:
//  $1
// 
// String stack out:
//  $1'
//                                                         
// Action:
//  then the character (bytes) at the offset and the ones following it in the top 
//   string on the string stack are removed from the string shortening the length of 
//   the string by length bytes
//  note: the first character in the string is at offset 0
//
//  Example:
//   $" abcdef" 2 3 DELETEIN$ 
//   is the same as $" abf"
//
// Failure cases:
//  error getting pointer to the data stack
//  data stack underflow error
//  error getting the depth of the string stack
//  string stack underflow error
//  error getting the pointer to the top string on the string stack
//  length longer than top string on string stack's length
//  specified segment goes off the end of the string
//  error shortening the string
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthstringcfetch ( $C@ )
//
// C prototype:
//  void dg_forthstringcfetch (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( $1 -$- $1 )   
//  ( position -- char )
//
// Data stack in:
//  position                      offset of character in top string in bytes
//
// String stack in:
//  $1
//
// Data stack out:
//  char                          UINT64 representation of character (byte) (0 
//                                 extended to 64 bits) from position in string 
//  
// String stack out:
//  $1
//                                                         
// Action:
//  removes position from the data stack and pushes the character at the position in 
//   the top string on the string stack to the data stack
//
// Note:
//  the first character in the string is at position 0
//  
// Failure cases:
//  error getting the pointer to the data stack
//  data stack underflow
//  error getting the number of strings on the string stack
//  string stack underflow
//  error getting the pointer to the top string on the string stack
//  position is off the end of the top string on the string stack
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthstringcstore ( $C! )
//
// C prototype:
//  void dg_forthstringcstore (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the  
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( $1 -$- $1' )  
//  ( char position -- )
//
// Data stack in:
//  char                          UINT64 representation of character (byte) to put 
//                                 into string
//  position                      offset in bytes of where to put character in top 
//                                 string  
//
// String stack in:
//  $1
// 
// String stack out:
//  $1'
//                                                         
// Action:
//  removes character and position from the data stack 
//  and puts the character into the top string on the string stack at the position
//  
// Note:
//  the first character in the string is at position 0
//  
// Failure cases:
//
// ////////////////////////////////////////////////////////////////////////////////////// 
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthstringtoc ( $>C )
//
// C prototype:
//  void dg_forthstringtoc (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( $1 -$- $1' )
//  ( -- char )
//
// Data stack out:
//  char                          character (byte) popped off the end of the 
//                                 top string on the string stack 
//
// String stack in:
//  $1
// 
// String stack out:
//  $1'
//                                                         
// Action:
//  removes the last character from the top string on the string stack
//  and pushes the character to the data stack
//  
// Failure cases:
//  error getting pointer to the string stack's offset buffer
//  string stack underflow
//  string stack corrupt error because end offset < start offset for top
//   string on string stack
//  string underflow error
//  error popping character from string stack's string buffer
//  error shrinking string stack's string buffer
//  error pushing the character to the data stack
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthstringto ( $> )
//
// C prototype:
//  void dg_forthstringto (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( $1 -$- $1' )
//  ( -- u )
//
// Data stack out:
//  u                             UINT64 popped off the end of the top string on the 
//                                 string stack 
//
// String stack in:
//  $1
// 
// String stack out:
//  $1'
//                                                         
// Action:
//  Removes the last four bytes from the top string on the string stack
//   and pushes them as a UINT64 to the data stack.
//  The order of the bytes is not changed, so on an x86 machine
//    $" ZXYABCD" $> HEX U.
//   shows '41424344' and leaves 'ZXY' as the top string on the string stack.
//  
//  
// Failure cases:
//  error getting pointer to the string stack's offset buffer
//  string stack underflow
//  string stack corrupt error because end offset < start offset for top string 
//   on string stack
//  string underflow error
//  error popping a UINT64 from string stack's string buffer
//  error shrinking string stack's string buffer
//  error pushing the UINT64 to the data stack
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthctostring ( C>$ )
//
// C prototype:
//  void dg_forthctostring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( $1 -$- $1' )
//  ( char -- )
//
// Data stack in:
//  char                          UINT64 representation of character (byte) (0 
//                                 extended to 64 bits) to push onto the end of the 
//                                 top string on the string stack
//
// String stack in:
//  $1
// 
// String stack out:
//  $1'
//                                                         
// Action:
//  removes character from the data stack 
//  and pushes the character onto the end of the top string on the string stack
//  
// Failure cases:
//  error doing dg_forthchartostring
//  error doing dg_forthcatstring
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthtostring ( >$ )
//
// C prototype:
//  void dg_forthtostring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( $1 -$- $1' )
//  ( u -$- )
//
// Data stack in:
//  u                             UINT64 to push to the end of the top string on the 
//                                 string stack
//
// String stack in:
//  $1
// 
// String stack out:
//  $1'
//                                                         
// Action:
//  removes UINT64 from the data stack 
//  and pushes the UINT64's bytes onto the end of the top string on the string stack
//  
// Failure cases:
//  error doing dg_forthtonewstring
//  error doing dg_forthcatstring
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthstringquotes ( $" execute mode )
//
// C prototype:
//  void dg_forthstringquotes (Bufferhandle* pBHarrayhead )
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the  
//                                 other bufferhandles are stored.
// 
// Stack action shorthand:
//  ( "<delimeter>stuff<quotes>morestuff" -currentinputbuffer- 
//     "morestuff" )
//  ( -$- "stuff" )
//
// Current input buffer's current offset in:
//  "<delimeter>stuff<quotes>morestuff"
//
// Current input buffer's current offset out:
//  "morestuff"
//
// String stack out:
//  $1
//                                                         
// Action:
//  Everything up to the next ", the next line terminator delimiter, or end of buffer,
//   whichever comes first, in the current input buffer is pushed to a new string 
//   on top of the string stack.
//
// Note:
//  In compile mode $" does not compile a call to this routine, 
//   instead $" calls S" and then compiles a call to S>$
//   for example:
//   : t $" hi" ; 
//   t TYPE
//   is the same as $" hi" TYPE
//
// Note:
//  A line terminator delimiter is one of:
//   c shorthand      ascii code    name  
//   '\n'             0x0a          <line feed>
//   '\v'             0x0b          <vertical tab>
//   '\b'             0x08          <back space>
//   '\r'             0x0c          <carriage return>
//   '\f'             0x0f          <form feed>
//
// Failure cases:
//  error getting current input buffer id
//  error getting the pointer to the current input buffer
//  error pushing a new string onto the top of the string stack
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthholdstring ( HOLD$ ) 
//
// C prototype:
//  void dg_forthholdstring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( char -- )
//  ( $1 -$- $1' )
//
// Data stack in:
//  char                          character (byte) to insert before start of string 
//  
// String stack in:
//  $1
// 
// String stack out:
//  $1'
//                                                         
// Action:
//  inserts a character at the start of the top string on the string stack
//
//  Example:
//   $" abcd" CHAR x HOLD$
//   is the same as $" xabcd"
//  
// Failure cases:
//  error in a subroutine
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthnumbersignstring ( #$ )
//
// C prototype:
//  void dg_forthnumbersignstring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( ud -- ud' )
//  ( $1 -$- $1' )
//
// Data stack in:
//  ud                            unsigned double integer (64 bit lo 64 bit hi) for 
//                                 conversion
//  
// Data stack out:
//  ud'                           ud divided by what's in BASE
//
// String stack in:
//  $1
// 
// String stack out:
//  $1'                           
//                                                         
// Action:
//  same as # except result goes to the top string on the string stack instead of PAD
//  ud1 is divided by BASE and left on the data stack
//  the remainder of the division is converted to a character and insterted into the
//  beginning of the top string on the string stack
//  
// Failure cases:
//  error getting base
//  base too low
//  error pushing the base to the data stack
//  error doing dg_forthudmslashmod
//  error pushing the character to the data stack
//  error inserting the character at the start of the top string on the string stack
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthnumbersignsstring ( #S$ )
//
// C prototype:
//  void dg_forthnumbersignsstring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( $1 -$- $1' ) 
//  ( ud -- 0 0)
//
// Data stack in:
//  ud                            unsigned double integer for conversion 
//                                 (64 bit lo 64 bit hi)
//  
// Data stack out:
//  ud2 = 0                       double number equal to 0  (0 0)
//
// String stack in:
//  $1
// 
// String stack out:
//  $1'
//                                                         
// Action:
//  same as #S except result goes to the top string on the string stack instead of PAD
//  the number is dg_successively divided by what's in BASE until it is 0 and left on 
//   the data stack
//  the remainders of the divisions are converted to ascii characters and inserted 
//   into the beginning of the top string on the string stack
//  
// Failure cases:
//  error converting a digit
//  error getting the pointer to the data stack
//  data stack underflow
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthsignstring ( SIGN$ )
//
// C prototype:
//  void dg_forthsignstring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( n -- )
//  ( $1 -$- $1' )
//
// Data stack in:
//  n                             signed single integer (64 bit)  
//
// String stack in:
//  $1
// 
// String stack out:
//  $1'
//                                                         
// Action:
//  removes the number on top of the data stack and if it is negative inserts a '-' 
//   character into the beginning of the top string on the string stack
//  
// Failure cases:
//  error popping n from the data stack
//  error pushing '-' character to the data stack
//  error inserting '-' at the beginning of the top string on the string stack
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthsplitstring ( SPLIT$ )
//
// C prototype:
//  void dg_forthsplitstring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( nd -- )
//  ( $1 -$- $2 $3 )
//
// Data stack in:
//  nd                            number of characters to pop from top string to a new 
//                                 string on top of string stack
//
// String stack in:
//  $1                            string to split in two
// 
// String stack out:
//  $2                            beginning part of $1 containing length of $1 - n 
//                                 characters
//  $3                            end part of $1 containing n characters
//                                                         
// Action:
//  removes n from the data stack
//  splits the top string on the string stack into two strings, the new top string 
//   on the string stack contains the last n characters of the original string
//  if n > length of top string, an empty string is pushed to the top of the string 
//   stack
//  
// Failure cases:
//  error popping n from the data stack
//  error getting pointer to the string stack's offset buffer
//  string stack underflow
//  string stack's offset buffer is corrupt
//  --removed--n > length of top string
//  error pushing new end offset to string stack's offset buffer
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthputmidstring ( PUTMID$ )
//
// C prototype:
//  void dg_forthputmidstring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( destinationoffset -- )
//  ( destination$ source$ -$- destination$' )
//
// Data stack in:
//  offset                        offset in the destination string of where to  
//                                 overwrite with the top string   
//
// String stack in:
//  destination$                   
//  source$                       
// 
// String stack out:
//  destination$'                 destination string with the source string 
//                                 overwritting part of it
//                                                         
// Action:
//  removes offset from the data stack
//  copies the entire source string into the destination string at the offset in 
//   the destination string
//  
// Failure cases:
//  error popping n
//  error getting pointer to the string stack's offset buffer
//  string stack underflow
//  string stack's offset buffer is corrupt, destination's end offset < start offset
//  string stack's offset buffer is corrupt, source's end offset < start offset
//  offset is off the end of the destination string
//  source string wont fit into the destination string at the offset
//  error getting pointer to the string stack's string buffer
//  string buffer is corrupt, the string buffer's length doesn't match the last end 
//   offset in the offset buffer
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthstostring ( S>NEW$ )
//
// C prototype:
//  void dg_forthstostring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( addr length -- )
//  ( -- $1 )
//
// Data stack in:
//  addr                          start address of string 
//  length                        length of string in characters (bytes)
// 
// String stack out:
//  $1
//                                                         
// Action:
//  removes addr and length from the data stack
//  pushes a copy of the string starting at addr for length characters (bytes) to the 
//   top of the string stack as a new string. (the string is NOT appended to the top 
//   string on the string stack)
//  
// Warning:
//  Do not use this routine to push a string already in this string stack because the 
//   base address of the string stack may move when the push is done. This will 
//   invalidate the address passed in. Instead use PICK$ 
//
// Failure cases:
//  error getting pointer to the datastack
//  data stack underlow
//  error pushing to the string stack
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthgetsstringnd ( GETP$ GETS$[ND] )
//  ( GETP$ is deprecated, use GETS$[ND] instead )
//
// C prototype:
//  void dg_forthgetsstringnd (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( $n $n-1 ... $1 $0 -$- $n $n-1 ... $1 $0 )
//  ( n -- addr length )
//
// Data stack in:
//  n                             number of strings away from top of the string stack  
//
// Data stack out:
//  addr                          pointer to start of string n away from the top of 
//                                 the string stack
//  length                        length of the string in characters (bytes)
// 
// String stack in:
//  $n $n-1 ... $1 $0
// 
// String stack out:
//  $n $n-1 ... $1 $0  (unchanged)
//                                                         
// Action:
//  pushes the start address and length of the string n away from the top of the 
//   string stack to the data stack
//  
// NOTE:
//  the pointer returned is only valid until the next time something is pushed 
//   onto the string stack because the base address of the string stack's string 
//   buffer may move if it's length is increased
//
// Failure cases:
//  error popping n from the data stack
//  error getting the depth of the string stack
//  string stack underlow
//  error calling dg_getplstring
//  error pushing the pointer to the string onto the data stack
//  error pushing the length of the string onto the data stack
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthprintstring ( .$ )
//
// C prototype:
//  void dg_forthprintstring(Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead  pointer to a Bufferhandle structure which is 
//
// Stack action shorthand:
//  ( $1 -$- )
//
// String stack in:
//  $1                          string to display
//
// Action:
//  displays top string on the string stack to the current output
//  removes the top string from the string stack
//
// Failure cases:
//  error getting string stack depth
//  strings stack underflow
//  error getting pointer to the top string on the string stack
//  error sending a character to the current output
//
// Assumptions:
//  assumes dg_forthprintstring returns -1 or a character between 0 and 0xFF
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthloadfilestring ( LOADFILE$ )
//
// C prototype:
//  void dg_forthloadfilestring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.                          
//  
// Stack action shorthand:
//  ( filename$ -$- )
//  ( -- bufferid )
//
// String stack in:
//  filename$                     file's name, and can include windows path stuff
//
// Data stack out:
//  bufferid                      id of buffer where file was loaded
//                                                            
// Action:
//  removes file name from the top of the string stack
//  opens the file for reading in binary
//  creates a new buffer
//  copies the file to the buffer
//  closes the file
//  pushes the buffer id of the new buffer to the data stack
// 
// Failure cases:
//  error pushing mode to the string stack
//  error opening the file
//  error popping filehandle from the data stack
//  couldn't find file error
//  error trying to seek the end of the file
//  error using ftell to get the file length
//  file is to big to load in one chunk
//  error making a new buffer
//  error growing a new buffer
//  error getting pointer to the buffer segment
//  error reading file, entire file not read
//  error pushing new buffer id to the data stack
//  error closing the file
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthsavefilestring ( SAVEFILE$ )
//
// C prototype:
//  void dg_forthsavefilestring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.                          
//  
// Stack action shorthand:
//  ( filename$ -$- )
//  ( bufferid -- )
//
// String stack in:
//  filename$                     file's name, and can include windows path stuff
//
// Data stack int:
//  bufferid                      id of buffer to save to a file
//                                                            
// Action:
//  removes file name from the top of the string stack
//  removes the buffer id from the top of the data stack
//  opens the file for writing in binary
//  saves the buffer to the file
//  closes the file
// 
// Failure cases:
//  error popping buffer id
//  error getting pointer to the buffer
//  error pushing mode to the string stack
//  error opening the file
//  error writing the file
//  error closing the file
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthincludefilestring ( INCLUDEFILE$ )
//
// C prototype:
//  void dg_forthincludefilestring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.                          
//  
// Stack action shorthand:
//  ( filename$ -$- )
//
// String stack in:
//  filename$                     file's name, and can include windows path stuff
//                                                            
// Action:
//  loads the file to a buffer, this removes the filename from the top of the string 
//   stack
//  evaluates the buffer returned from load file
//  frees the buffer returned from load file
// 
// Failure cases:
//  error loading the file into a buffer
//  error popping the buffer id
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthqueryincludefilestring ( ?INCLUDEFILE$ )
//
// C prototype:
//  void dg_forthqueryincludefilestring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.                          
// 
// Stack action shorthand:
//  ( filename$ -$- )
//  ( flag -- )
//
// Data stack in:
//  flag                          if true, the file is included
//  
// String stack in:
//  filename$                     file's name, and can include windows path stuff
//                                                            
// Action:
//  checks to see if the flag is true if it is the following is done:
//   loads the file to a buffer, this removes the filename from the top of the 
//    string stack
//   evaluates the buffer returned from load file
//   frees the buffer returned from load file
// 
// Failure cases:
//  error popping the data stack
//  error dropping the file name string
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthfreelibrary ( FREELIBRARY )
//
// C prototype:
//  void dg_forthfreelibrary (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.                          
//  
// Stack action shorthand:
//  ( libraryhandle -- )
//
// Data stack in:
//  libraryhandle                 handle to the library
//                                                            
// Action:
//  pops the library handle from the data stack
//  frees (unloads) the library specified by the library handle
// 
// Failure cases:
//  error popping the library handle
//  error freeing the library
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthgetenvstring ( GETENV$ )
//
// C prototype:
//  void dg_forthgetenvstring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.                          
//  
// Stack action shorthand:
//  ( name$ -$- value$ )
//
// String stack in:
//  name$                         symbol name of environment variable
//
// String stack out:
//  value$                        value assigned to environment variable name$
//                                                            
// Action:
//  pops name$ of the string stack
//  pushes the value assigned to the environment variable name$ to the string stack
// 
// Failure cases:
//  error popping from the string stack
//  error getting environment variable value
//  error pushing to the string stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthgetmethodstring ( GETMETHOD$ )
//
// C prototype:
//  void dg_forthgetmethodstring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle*  pBHarrayhead      pointer to a Bufferhandle structure which is 
//                                    used as the bufferhandle for the array where the 
//                                    other bufferhandles are stored          
//
// Stack action shorthand:
//  ( -$- method$ )
//
// Action:
//  pushes the cgi or isapi method string onto the string stack
//
// Failure cases:
//  error getting script processing state
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthgetquerystring ( GETQUERY$ )
//
// C prototype:
//  void dg_forthgetquerystring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle*  pBHarrayhead      pointer to a Bufferhandle structure which is 
//                                    used as the bufferhandle for the array where the  
//                                    other bufferhandles are stored          
//
// Stack action shorthand:
//  ( -$- query$ )
//
// Action:
//  pushes the cgi or isapi query string onto the string stack
//
// Failure cases:
//  error getting script processing state
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthcscanstring ( CSCAN$ )
//
// C prototype:
//  void dg_forthcscanstring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
// 
// Stack action shorthand:
//  ( index value -- index' )
//  ( a$ -$- a$ )
//
// Data stack in:
//  index                         0 based start index in string from beginning for scan
//  value						  value of byte to scan for in string
//
// Data stack out:
//  index                         index in string in range of 0 to length of string - 1 
//                                 of first match in string or -1 if no match is found
//                                                            
// Action:
//  Searches the memory in the string starting at index from beginning and working 
//   towards the end of the string for the first occurence of the value 
//
// Failure cases:
//  error getting pointer to the data stack
//  data stack underflow
//  process doesn't own the memory in the string
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthminuscscanstring ( -CSCAN$ )
//
// C prototype:
//  void dg_forthminuscscanstring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
// 
// Stack action shorthand:
//  ( index value -- index' )
//  ( a$ -$- a$ )
//
// Data stack in:
//  index                         0 based start index in string from beginnning for  
//                                 scan, index can be off end of string
//  value						  value of byte to scan for in string
//
// Data stack out:
//  index                         index in string in range of 0 to length of string - 1 
//                                 of first match in string or -1 if no match is found
//                                                            
// Action:
//  Searches the memory backwards in the string starting at index from beginning 
//   and working towards the beginning of the string for the first occurence of 
//   the value
//  If the start offset is greater than the string length, 
//   the search starts with the last character in the string 
//
// Failure cases:
//  error getting pointer to the data stack
//  data stack underflow
//  process doesn't own the memory in the string
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthasciitounicodestring ( ASCII>UNICODE$ )
//
// C prototype:
//  void dg_forthasciitounicodestring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
// 
// Stack action shorthand:
//  ( -- )
//  ( ascii$ -$- unicode$ )
//
// String stack in:
//   Ascii encoded string
//
// Data stack out:
//   Unicode version of the ascii string
//                                                            
// Action:
//   Replaces ascii string with unicode string
//
// Failure cases:
//  buffer system corrupt
//  string stack underflow
//  not enough memory to grow string
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthunicodetoasciistring ( UNICODE>ASCII$ )
//
// C prototype:
//  void dg_forthunicodetoasciistring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
// 
// Stack action shorthand:
//  ( -- )
//  ( unicode$ -$- ascii$ )
//
// String stack in:
//   Ascii encoded string
//
// Data stack out:
//   Unicode version of the ascii string
//                                                            
// Action:
//   Replaces ascii string with unicode string
//
// Failure cases:
//  buffer system corrupt
//  string stack underflow
//  not enough memory to grow string
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthgrowstring ( GROW$ )
//
// C prototype:
//  void dg_forthgrowstring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( n -- )
//  ( $1 -$- l$' )
//
// Data stack in:
//  n                             amount to grow lstring by
//
// Action:
//  grows the top lstring on the lstring stack by n bytes
//
// Failure cases:
//  error getting pointer to the data stack
//  data stack underflow
//  error growing lstring
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthrollstring ( ROLL$ )
//
// C prototype:
//  void dg_forthrollstring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( nd -- )
//  ( $bottom ... $nd+1 $nd $nd-1 ... $1 $0 -$- $bottom ... $nd+1 $nd-1 ... $1 $0 $nd )
//
// Data stack in:
//  nd                            distance from top of string stack
//
// Action:
//  does PICK$ then deletes the string picked from the string stack
//
// Failure cases:
//   error pushing to data stack
//   error doing ROLLL$
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthminusrollstring ( -ROLL$ )
//
// C prototype:
//  void dg_forthminusrollstring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the  
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( nd -- )
//  ( $depth-1{bottom} ... $nd+1 l$nd $nd-1 ... $1 $0{top} -l$- 
//     $depth-1{bottom} ... $nd+1 $0 $nd $nd-1 ... $1 )
//
// Data stack in:
//  nd                            distance from top of string stack
//
// Action:
//  moves the top lstring on the l$stack to position nd on the l$stack
//    (nd=0 does nothing, nd=1 does SWAP$, nd=2 does -ROT$)
//
// Failure cases:
//   error pushing to data stack
//   error doing -ROLLL$
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthdeleteinstringnd ( DELETEIN$[ND] )
//
// C prototype:
//  void dg_forthdeleteinstringnd (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( offset length nd -- )
//  ( $bottom ... $nd+1 $nd $nd-1 ... $1 $0 -$- $bottom ... $nd+1 $nd' $nd-1 ... $1 $0 )
//
// Data stack in:
//  offset                        start offset of segment in string
//  length                        length of segment to delete in string
//  nd                            distance from top of string stack
//
// Action:
//  deletes segment from target string on the string stack
//
// Failure cases:
//   error pushing to data stack
//   error doing DELETEINL$
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthinsertinstringnd ( INSERTIN$[ND] )
//
// C prototype:
//  void dg_forthinsertinstringnd (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( offset length nd -- )
//  ( $bottom ... $nd+1 $nd $nd-1 ... $1 $0 -$- $bottom ... $nd+1 $nd' $nd-1 ... $1 $0 )
//
// Data stack in:
//  offset                        start offset of segment in string
//  length                        length of segment to delete in string
//  nd                            distance from top of string stack
//
// Action:
//  inserts undefined characters into a the string at distance nd from the top of 
//    the string stack
//
// Failure cases:
//   error pushing to data stack
//   error doing INSERTINL$
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthcatstringnd ( CAT$[ND] )
//
// C prototype:
//  void dg_forthcatstringnd (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//     
// Stack action shorthand:
//  ( offset length nd -- )
//  ( $bottom ... $nd+1 $nd $nd-1 ... $1 $0 -$- $bottom ... $nd+1 $nd+nd-1 ... $1 $0 )
//
// Data stack in:
//  nd                            distance from top of string stack
//
// Action:
//  concatenates target string on the string stack with the one after it
//
// Failure cases:
//   error getting pointer to data stack
//   not enough parameters on data stack
//   string stringid is not at least 1 below top of string stack
//   error concatenating strings on the string stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthurlencodestring ( URLENCODE$ )
//
// C prototype:
//  void dg_forthurlencodestring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//                                                            
// Stack action shorthand:
//  ( -- )
//  ( decodedurl$ -$- url$ )
//
// Action:
//  <space> changed to +,
//  non printable characters changed to %xx where xx is hex ascii code,
//  % changed to %25
//  non printable is 00-1F, 7F-FF
//
// Failure cases:
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthurldecodestring ( URLDECODE$ )
//
// C prototype:
//  void dg_forthurldecodestring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//                                                            
// Stack action shorthand:
//  ( -- )
//  ( url$ -$- decodedurl$ )
//
// Action:
//  + changed to <space>, %xx changed to character for xx hex ascii code
//
// Failure cases:
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthstringtobackslashstring ( $>\$ )
//
// C prototype:
//  void dg_forthstringtobackslashstring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//                                                            
// Stack action shorthand:
//  ( -- )
//  ( a$ -$- escencodeda$ )
//
// Action:
//  Replaces the top string on the string stack with an escape encoded version of the
//   string. Alpha numeric bytes are left alone.
//   Non alpha numeric characters that have the same short escape sequence in both C 
//    and Forth are encoded using this table:
//
//     byte -> escape sequence
//     0x07 -> \a
//     0x08 -> \b
//     0x0d -> \r
//     0x1b -> \e
//     0x0c -> \f
//     0x09 -> \t
//     0x0b -> \v
//     0x5C -> \\
//     0x22 -> \"
//
//   All other bytes are replaced with \xXX where XX is the hex ascii code for the
//    byte. So for example if the value of the byte was 1, then this value would be
//    encoded using four bytes which would be \x01 where '\' is 0x5C, 'x' is 0x78
//    '0' is 0x30, and '1' is 0x31.
//
//  This function generates an encoded string compatible with both the Forth and C
//   conventions.
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthbackslashstringtostring ( \$>$ )
//
// C prototype:
//  void dg_forthbackslashstringtostring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//                                                            
// Stack action shorthand:
//  ( -- )
//  ( encodeda$ -$- decodeda$ )
//
// Action:
//  Replaces the top string on the string stack with a escape decoded version of the
//   string. If a back slash is encounter in the string, the byte after it is 
//   treated as the escape code for a character. This function supports most of the
//   escape codes from both Forth and C. Most of these escape codes require no
//   additional characters and the back slash escape code sequence gets converted to
//   a single byte. The list of these are here:
//
//     Forth standard conversions
//      \z -> 0x00 
//      \a -> 0x07 
//      \b -> 0x08 
//      \t -> 0x09 
//      \l -> 0x0a 
//      \v -> 0x0b 
//      \f -> 0x0c
//      \r -> 0x0d 
//      \m -> 0x0d0a 
//      \e -> 0x1b 
//      \" -> 0x22 
//      \q -> 0x22
//      \\ -> 0x5C 
//
//     C escape conversions 
//      \0 -> 0x00
//      \n -> 0x0a 
//      \' -> 0x27
//      \? -> 0x3F
//
//   The one four character escape sequence is \xXX where XX are hex ascii digits.
//     \xXX -> 0xXX
//    So for example: \x01 gets converted to 1 and \x26 gets converted to byte 0x26.
//    
//   If the escape code is unknown, no error is given. Instead the unknown backslash 
//    escape code gets converted to a '-' character (0x2D).
//   If the backslash is at the end of the string and the escape code is missing
//    the backslash gets converted to a '-' character (0x2D).
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthstripstring( STRIP$ )
//
// C prototype:
//  void dg_forthstripstring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( a$ -$- a$' )
//
// Action:
//  Removes leading and trailing delimiters from string.
//  see dg_isdelimiter() for list of delimiters 
//
// Failure cases:
//  string stack underflow
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthdotstrings ( .$S )  
//
// C prototype:
//  void dg_forthdotstrings (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( -- )
//                                                            
// Action:
//  displays the contents of the string stack from first pushed to most recently 
//   pushed
//
// Failure cases:
//  not checked
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthstrippathfromfilenamestring ( STRIPPATHFROMFILENAME$ )  
//
// C prototype:
//  void dg_forthstrippathfromfilenamestring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( path/filename$ -$- filename$ )
//                                                            
// Action:
//  Keeps only the stuff after the last forward or back slash in a string.
//  If there are no slashes in the string, keeps the whole string.
//
// Failure cases:
//  not checked
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthvariableflstring ( VARIABLEFL$ )
//
// C prototype:
//  void dg_forthvariableflstring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( "<delimiter>word<delimiters>morestuff" -currentinputbuffer- 
//     "<delimiters>morestuff" )
//                                                            
// Action:
//  Makes a new freeable lstring in the DG_VARIABLEFLSTR_HEADER_BUFFERID freeable
//   lstring array.
//  Makes a constant word who's value is the id of the new freeable lstring and
//   who's name is the next word parsed from the current input buffer.'
//
// Failure cases:
//  not checked
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthfillnewstring ( FILL-NEW$ )
//
// C prototype:
//  void dg_forthfillnewstring(Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( char n -- )
//  ( -$- a$ )
//                                                            
// Action:
//  Creates a new string of length n in bytes filled with the character char.
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthpzerostrtonewstr ( P0$>NEW$ )
//
// C prototype:
//  void dg_forthpzerostrtonewstr(Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( p0$ -- )
//  ( -$- NEW$ )
//                                                            
// Action:
//  Given a pointer to a C style 0 string on the data stack,
//   pushes the 0 string to the string stack without the null terminator.
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthnglufilestring ( NGLUFILE$ )
//
// C prototype:
//  void dg_forthnglufilestring(Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where
//                                 the other bufferhandles are stored.
//
// Stack action shorthand:
//  ( -- )
//  ( filename$ -$- )
//                                                            
// Action:
//  Unpacks the file into an hlist, then for each child of root in the hlist,
//   this function gets the child element's name and uses the name as a UINT64
//   index into the glu function table to call the glu function.
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthglufilestring ( GLUFILE$ )
//
// C prototype:
//  void dg_forthglufilestring(Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where
//                                 the other bufferhandles are stored.
//
// Stack action shorthand:
//  ( -- )
//  ( filename$ -$- )
//                                                            
// Action:
//  Unpacks the file into an hlist, then for each child of root in the hlist,
//   this function gets the child element's name and looks up the name
//   in the glu function list, then calls the glu function associated with the
//   name.
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthwordsstringquotes ( WORDS$" )
//
// C prototype:
//  void dg_forthwordsstringquotes(Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is
//                                 used as the bufferhandle for the array where
//                                 the other bufferhandles are stored.
//
// Stack action shorthand:
//  ( -- u )
//  ( -$- word$0 word$1 ... word$u )
//  ( "<1stdelimiter&gr;<delimiters>word0<delimiters>word1
//    <delimiters>...wordu-1<delimiters>"morestuff"
//     -currentinputbuffer- "morestuff" )
//
// Action:
//  First skips the next character in the current input buffer. This is to get off the
//   delimiter after WORDS$". Then words are parsed from the current input buffer until
//   either a " or the end of the buffer is encountered. Each parsed word is pushed
//   onto the string stack as separate string in the order they were encountered.
//   Then the current input buffer's current parse offset is moved to the character
//   after the terminating " or the end of buffer depending on how the parsing
//   stopped.
//   Then the number of words parsed is pushed onto the data stack.
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthwords0stringquotes ( WORDS0$" )
//
// C prototype:
//  void dg_forthwords0stringquotes(Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is
//                                 used as the bufferhandle for the array where
//                                 the other bufferhandles are stored.
//
// Stack action shorthand:
//  ( -- u )
//  ( -$- word0$0 word0$1 ... word0$u )
//  ( "<1stdelimiter&gr;<delimiters>word0<delimiters>word1
//    <delimiters>...wordu-1<delimiters>"morestuff"
//     -currentinputbuffer- "morestuff" )
//
// Action:
//  First skips the next character in the current input buffer. This is to get off the
//   delimiter after WORDS$". Then words are parsed from the current input buffer until
//   either a " or the end of the buffer is encountered. Each parsed word is pushed
//   onto the string stack as separate null terminated string in the order they were
//   encountered. This means a byte with the value 0 is appended to the end of each
//   word before it's pushed onto the string stack.
//   Then the current input buffer's current parse offset is moved to the character
//   after the terminating " or the end of buffer depending on how the parsing
//   stopped.
//   Then the number of words parsed is pushed onto the data stack.
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthgetargsfromnstrings ( GETARGSFROMN$S )
//
// C prototype:
//  void dg_forthgetargsfromnstrings(Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is
//                                 used as the bufferhandle for the array where
//                                 the other bufferhandles are stored.
//
// Stack action shorthand:
//  ( u -- PARGS )
//  ( $0 $1 ... $u-1 -$- $0 $1 ... $u-1 ARGS$ )
//
// Action:
//  First this pops number of strings to get pointers for off the data stack.
//  Then this function creates a new string with enough room for u+1 pointers.
//  Then this function fills the new string with pointers to the top u strings from
//   before the new string was created. The last pointer in the new string gets a null
//   pointer. (A null pointer is a UINT64 with the value 0.) (A pointer is a UINT64
//   address.) Then a pointer to the new string is returned on the data stack.
//
// Note:
//  Since the string stack may move if you add stuff to it, the pointers returned from
//   this function may become invalid if you add anything else to the string stack. And
//   if you change anything on the string stack, that will also invalidate the pointers
//   because the strings will move.
//
// For example:
//  RUNFILEANDWAITNOENV" echo hello there"
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthrunfileandwaitnoenvquotes ( RUNFILEANDWAITNOENV" )
//
// C prototype:
//  void dg_forthrunfileandwaitnoenvquotes(Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is
//                                 used as the bufferhandle for the array where
//                                 the other bufferhandles are stored.
//
// Stack action shorthand:
//  ( -- )
//  ( -$- )
//  ( "<1stdelimiter&gr;<delimiters>word0<delimiters>word1
//    <delimiters>...wordu-1<delimiters>"morestuff"
//     -currentinputbuffer- "morestuff" )
//
// Action:
//  In script execute mode:
//   First this function skips the next character in the current input buffer. This is
//   to get beyond the delimiter after RUNFILEANDWAITNOENV"
//   Then this function parses words until the next " or the end of buffer is
//   reached. The first word parsed is used as the filename to run. All of the words
//   parsed are passed to the filename to run as the arguments of the program. A null
//   environment is passed to the filename to run. Then this function waits for the
//   program to completely finish running before returning.
//
//  In script compile mode:
//   First this function skips the next character in the current input buffer. This is
//   to get beyond the delimiter after RUNFILEANDWAITNOENV"
//   Then this function parses words until the next " or the end of buffer is
//   reached. The first word parsed will be used as the filename to run. All of the
//   words parsed will be passed to the filename to run as the arguments of the
//   program.
//   Then this function compiles code that does this:
//    run the program with the arguments parsed and a null environment
//    then wait for the program to completely finish running
//
// For example:
//  : doecholater RUNFILEANDWAITNOENV" echo hello there" ;
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthtostarulestring ( >*ULE$ )
//
// C prototype:
//  void dg_forthtostarulestring(Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( u -- ) ( a$ -$- a$*u )
//                                                            
// Action:
//  Pops u off the data stack.
//  Multiplies the unsigned little endian value in the top string by u.
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthtoslashulestring ( >/ULE$ )
//
// C prototype:
//  void dg_forthtoslashulestring(Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( u -- remainder ) ( a$ -$- a$/u )
//                                                            
// Action:
//  Pops u off the data stack.
//  If u is not 0:
//   Divides the unsigned little endian value in the top string by u.
//   Pushes the remainder from the division back onto the data stack.
//  If u is 0:
//   The top string is left unchanged and a remainder equal to the largest unsigned
//   integer is pushed back onto the data stack.
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthulestringtonumberstring ( ULE$>NUMBER$ )
//
// C prototype:
//  void dg_forthulestringtonumberstring(Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( ule$ -$- number$ )
//                                                            
// Action:
//  Converts the unsigned little endian value in the top string to it's ascii
//   equivalent representation. For this conversion, the value of the current BASE
//   variable is used as the base of the conversion. For example, a base of 10 is
//   decimal. a base of 16 is Hex. Trying to use a base less than 2 gives an error.
//   If the base is greater than 35, the digits are converted to exclamation marks.
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthnotstring ( NOT$ )
//
// C prototype:
//  void dg_forthnotstring(Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( a$ -$- a$' )
//                                                            
// Action:
//  Flips all the bits in the top string on the string stack. 0s become 1s and 1s
//   become 0s.
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthreversestring ( REVERSE$ )
//
// C prototype:
//  void dg_forthreversestring(Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( a$ -$- a$' )
//                                                            
// Action:
//  Reverses the order of the bytes in the string.
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthlelshiftstring ( LELSHIFT$ )
//
// C prototype:
//  void dg_forthlelshiftstring(Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( -- carryout ) ( a$ -$- a$' )
//                                                            
// Action:
//  Shifts the bits in the top string on the string stack to the left one.
//  A zero is shifted in to the lowest bit.
//  The value of the highest bit from before the shift is returned on the data stack.
//   0 = no carry out. 1 = carry out.
//  This is the same as multiplying the unsigned little endian value in the top string
//   of the string stack by 2.
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthulershiftstring ( ULERSHIFT$ )
//
// C prototype:
//  void dg_forthulershiftstring(Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( -- carryout ) ( a$ -$- a$' )
//                                                            
// Action:
//  Shifts the bits in the top string on the string stack to the right one.
//  A zero is shifted in to the highest bit.
//  The value of the lowest bit from before the shift is returned on the data stack.
//   0 = no carry out. 1 = carry out.
//  This is the same as dividing the unsigned little endian value in the top string
//   of the string stack by 2.
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthslershiftstring ( SLERSHIFT$ )
//
// C prototype:
//  void dg_forthslershiftstring(Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( -- carryout ) ( a$ -$- a$' )
//                                                            
// Action:
//  Shifts the bits in the top string on the string stack to the right one.
//  The value of the highest bit is shifted back in to the highest bit.
//  The value of the lowest bit from before the shift is returned on the data stack.
//   0 = no carry out. 1 = carry out.
//  This is the same as dividing the signed little endian value in the top string
//   of the string stack by 2.
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthlelshiftcstring ( LELSHIFTC$ )
//
// C prototype:
//  void dg_forthlelshiftcstring(Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( carryin -- carryout ) ( a$ -$- a$' )
//                                                            
// Action:
//  Shifts the bits in the top string on the string stack to the left one.
//  The carryin is shifted in to the lowest bit.
//  The value of the highest bit from before the shift is returned on the data stack.
//   0 = no carry out. 1 = carry out.
//  This is the same as multiplying the unsigned little endian value in the top string
//   of the string stack by 2 and adding carryin to the result.
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthlershiftcstring ( LERSHIFTC$ )
//
// C prototype:
//  void dg_forthlershiftcstring(Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( carryin -- carryout ) ( a$ -$- a$' )
//                                                            
// Action:
//  Shifts the bits in the top string on the string stack to the right one.
//  The carryin is shifted in to the highest bit.
//   0 = no carry in. 1 = carry in. Only the lowest bit of carryin is used.
//  The value of the lowest bit from before the shift is returned on the data stack.
//   0 = no carry out. 1 = carry out.
//  This is the same as dividing the unsigned little endian value in the top string
//   of the string stack by 2 and setting the highest bit equal to carryin.
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthuleandstring ( ULEAND$ )
//
// C prototype:
//  void dg_forthuleandstring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead     pointer to a Bufferhandle structure which is 
//                                   used as the bufferhandle for the array
//                                   where the other bufferhandles are stored.
//
// Outputs:
//   none
//
// Stack action shorthand:
//  ( -- ) ( x$ y$ -$- xANDy$ )
//
// Data stack in:
//  none
//
//
// Action:
//   If one string is shorter than the other string, it is treated as an unsigned
//    little endian integer and extended to the length of the other lstring. (This
//    means 0s are appended to the end of the shorter string to make it the same
//    length as the longer string.)
//   Then each byte in the top string is anded with the corresponding byte in the
//    string one below the top and the result is put back in the string one below
//    the top.
//   Then the top string is dropped from the string stack. 
//
// Failure cases:
//   Not enough strings on the string stack.
//   Error anding the bytes in the strings.
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthuleorstring ( ULEOR$ )
//
// C prototype:
//  void dg_forthuleorstring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead     pointer to a Bufferhandle structure which is 
//                                   used as the bufferhandle for the array
//                                   where the other bufferhandles are stored.
//
// Outputs:
//   none
//
// Stack action shorthand:
//  ( -- ) ( x$ y$ -$- xORy$ )
//
// Data stack in:
//  none
//
//
// Action:
//   If one string is shorter than the other string, it is treated as an unsigned
//    little endian integer and extended to the length of the other lstring. (This
//    means 0s are appended to the end of the shorter string to make it the same
//    length as the longer string.)
//   Then each byte in the top string is ored with the corresponding byte in the
//    string one below the top and the result is put back in the string one below
//    the top.
//   Then the top string is dropped from the string stack. 
//
// Failure cases:
//   Not enough strings on the string stack.
//   Error oring the bytes in the strings.
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthulexorstring ( ULEXOR$ )
//
// C prototype:
//  void dg_forthulexorstring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead     pointer to a Bufferhandle structure which is 
//                                   used as the bufferhandle for the array
//                                   where the other bufferhandles are stored.
//
// Outputs:
//   none
//
// Stack action shorthand:
//  ( -- ) ( x$ y$ -$- xXORy$ )
//
// Data stack in:
//  none
//
//
// Action:
//   If one string is shorter than the other string, it is treated as an unsigned
//    little endian integer and extended to the length of the other lstring. (This
//    means 0s are appended to the end of the shorter string to make it the same
//    length as the longer string.)
//   Then each byte in the top string is xored with the corresponding byte in the
//    string one below the top and the result is put back in the string one below
//    the top.
//   Then the top string is dropped from the string stack. 
//
// Failure cases:
//   Not enough strings on the string stack.
//   Error xoring the bytes in the strings.
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthulenandstring ( ULENAND$ )
//
// C prototype:
//  void dg_forthulenandstring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead     pointer to a Bufferhandle structure which is 
//                                   used as the bufferhandle for the array
//                                   where the other bufferhandles are stored.
//
// Outputs:
//   none
//
// Stack action shorthand:
//  ( -- ) ( x$ y$ -$- xNANDy$ )
//
// Data stack in:
//  none
//
//
// Action:
//   If one string is shorter than the other string, it is treated as an unsigned
//    little endian integer and extended to the length of the other lstring. (This
//    means 0s are appended to the end of the shorter string to make it the same
//    length as the longer string.)
//   Then each byte in the top string is nanded with the corresponding byte in the
//    string one below the top and the result is put back in the string one below
//    the top.
//   Then the top string is dropped from the string stack. 
//
// Failure cases:
//   Not enough strings on the string stack.
//   Error anding the bytes in the strings.
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthulenorstring ( ULENOR$ )
//
// C prototype:
//  void dg_forthulenorstring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead     pointer to a Bufferhandle structure which is 
//                                   used as the bufferhandle for the array
//                                   where the other bufferhandles are stored.
//
// Outputs:
//   none
//
// Stack action shorthand:
//  ( -- ) ( x$ y$ -$- xNORy$ )
//
// Data stack in:
//  none
//
//
// Action:
//   If one string is shorter than the other string, it is treated as an unsigned
//    little endian integer and extended to the length of the other lstring. (This
//    means 0s are appended to the end of the shorter string to make it the same
//    length as the longer string.)
//   Then each byte in the top string is nored with the corresponding byte in the
//    string one below the top and the result is put back in the string one below
//    the top.
//   Then the top string is dropped from the string stack. 
//
// Failure cases:
//   Not enough strings on the string stack.
//   Error noring the bytes in the strings.
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthulexnorstring ( ULEXNOR$ )
//
// C prototype:
//  void dg_forthulexnorstring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead     pointer to a Bufferhandle structure which is 
//                                   used as the bufferhandle for the array
//                                   where the other bufferhandles are stored.
//
// Outputs:
//   none
//
// Stack action shorthand:
//  ( -- ) ( x$ y$ -$- xXNORy$ )
//
// Data stack in:
//  none
//
//
// Action:
//   If one string is shorter than the other string, it is treated as an unsigned
//    little endian integer and extended to the length of the other lstring. (This
//    means 0s are appended to the end of the shorter string to make it the same
//    length as the longer string.)
//   Then each byte in the top string is xnored with the corresponding byte in the
//    string one below the top and the result is put back in the string one below
//    the top.
//   Then the top string is dropped from the string stack. 
//
// Failure cases:
//   Not enough strings on the string stack.
//   Error xnoring the bytes in the strings.
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthtofactorialulestring ( >FACTORIALULE$ )
//
// C prototype:
//  void dg_forthtofactorialulestring (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead     pointer to a Bufferhandle structure which is 
//                                   used as the bufferhandle for the array
//                                   where the other bufferhandles are stored.
//
// Outputs:
//   none
//
// Stack action shorthand:
//  ( u -- ) ( -$- ufactorialule$ )
//
// Data stack in:
//  u                             64 bit unsigned integer
//
//
// Action:
//  Pops u off the data stack.
//  Calculates u factorial and pushes the unsigned little endian result onto the
//   string stack. 
//
// Failure cases:
//
// //////////////////////////////////////////////////////////////////////////////////////