// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *  
// A collection of useful words for dealing wth Forth strings
// a forth string is a series of consecutive bytes terminated 
// with a 0
// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *  

// HISTORY:
// Dec 2008 Added strcopy$

// REQUIRES:
// does not depend on any other files.

// CONSTANTS:
// none defined but words in the file use local variables.

// mid string function, given a string address str
// and an offset into it, it will produce another string form
// it, e.g.
// str="Hello fred"
// str 2 3 mid$, will produce
// "llo"
// Limitations: the local variable used is only transitory and so
// the address must be used imediately afer this call. It is limited
// to 80 characters
: mid$ { str offset len --- address } 
v$: b 81
// error checking if required
//    num 80 > abort" Max 80 Chars on mid$"
    offset len +  str length > abort" Mid$ outside limits"
    str offset + %@ b len // addr1, addr2, number -- for move
    move                  // move form str to b  
    0 %@ b len + c!       // add terminating 0  
    %@ b                // return eith address
;

// copies one string to another and terminates when the
// first string has 0 or the max is reached.
: strcopy$ { str1 str2 max-len -- }
    max-len for        
        i str1 + c@ 
        dup 0= if drop unloop escape then
        i str2 + c!
    next
;        

// add two strings together and returns the address of the 
// concatenated string
// limitations: uses local address so this must be used imediately
// sting length limited to 80 charatcres
: add$ { str1 str2 ---- addr }
v$: buff 162     // buffer space for both strings
int: len
    str1 length => len  // lenggth of sting1 less terminationg 0
    str1 %@ buff len move // buf=str1 less terminator
    str2 %@ buff len + str2 length 1+ // include 0 terminator 
    move
    %@ buff       
;

// Gets a number from an ASCII string where str is the address of the string
// offset is the diatnce into the string strating at 0
// len is the number of characters 2=byte 4=16bit word etc.
: hl-number { str offset len --- number|abort }  
   str offset len mid$    // get substring
   s" &" swap add$        // add & to front of string
   ?number  -1 <> abort" number expected"
;

// returns the postion along the string of the delimiting char
// string is the string address
// start start along string
// ch = delimiting character
// returns 0 if char not found otherwise postion char found
// EXAMPLE string = fred bob" andy, start = 0 ch = "
// this will return 8
: instr$   { string start ch --- count }
int: count

    begin
        start string + count +
        c@  dup ch <> swap 0 <> and // ch or terminator
    while
        1 +> count
    repeat
    start string + count + c@
    0= if 0 else count then
;

// extracts a string from an address delimited by char
// NOTE max set at 80
// ch = delimiting character
// address input is string to extarct from
// address output points to a local containing extracted string
// count size of extratced string - for calculating nect address
//       returns 0 when no more characters
// returns pointing to a local address
: tab   { ch address --- address count }
v$: buf 80
int: count

    80 address + address
    do
        i c@ dup ch = swap 0 = or // ch or 0 termina
        if
            0 %@ buf count + c! // add sting teminator
            %@ buf  count     // leave with address & count
            leave
        else
            i c@
            %@ buf count + c! // store
            1 +> count
        then
    loop
;