/* $DOC$
   $NAME$
      gt_AscPos()
   $CATEGORY$
      String Tools
   $ONELINER$
      Return the ASCII value of a specified character in a string
   $SYNTAX$
      gt_AscPos( <cStr>, <nPos> ) --> nAscVal
   $ARGUMENTS$
      <cStr>  - The string
      <nPos>  - The position in <cStr>
   $RETURNS$
      <nAscVal> - The ASCII value of hb_BSubStr( <cStr>, <nPos>, 1 )
   $DESCRIPTION$
      Return the ASCII value of a specified character in a string
      Equivalent (but much faster) to
          hb_BCode( hb_BSubStr( cStr, nPos, 1 ) )

      NOTE:
         invalid parameters will return -1
         nPos > hb_BLen( cStr ) will return -2

      This last behaviour is different to the Funcky function of the
      same name.  I changed the behaviour because some of the strings
      I process contain embedded NULs.
   $EXAMPLES$
      ? gt_AscPos( "the cat sat on the mat", 3 ) // prints e
   $STATUS$
      R
   $COMPLIANCE$

   $PLATFORMS$

   $FILES$
      Library is hbgt
   $END$
 */

/* $DOC$
   $NAME$
      gt_AsciiSum()
   $CATEGORY$
      String Tools
   $ONELINER$
      Sum the ASCII values in a string.
   $SYNTAX$
      gt_AsciiSum( <cStr> ) --> nSum
   $ARGUMENTS$
      <cStr>  - The string to sum
   $RETURNS$
      <nSum>    - The sum of all ASCII values in <cStr>.
   $DESCRIPTION$
      Sum the ASCII value of every character in the passed string
      and return the result.
   $EXAMPLES$

   $STATUS$
      R
   $COMPLIANCE$

   $PLATFORMS$

   $FILES$
      Library is hbgt
   $END$
 */

/* $DOC$
   $NAME$
      gt_AtDiff()
   $CATEGORY$
      String Tools
   $ONELINER$
      Return the position where two strings begin to differ
   $SYNTAX$
      gt_AtDiff( <cStr1>, <cStr2> ) --> nPos
   $ARGUMENTS$
      <cStr1>  - A character string to compare
      <cStr2>  - The string to compare with
   $RETURNS$
      <nPos>     - The position in <cStr2> where <cStr1> begins to differ
   $DESCRIPTION$
      Return the position in <cStr2> where <cStr1> begins to differ.
      If the strings differ in the first character gt_AtDiff() will
      return 1.  If the two strings are identical (or identical upto
      the last character in <cStr2>) the function will return 0.

      NOTE:
         invalid parameters will return -1
   $EXAMPLES$
      ? gt_AtDiff( "the cat", "the rat" )          // prints 5
      ? gt_AtDiff( "the cat", "the " )             // prints 0
   $STATUS$
      R
   $COMPLIANCE$

   $PLATFORMS$

   $FILES$
      Library is hbgt
   $END$
 */

/* $DOC$
   $NAME$
      gt_CharEven()
   $CATEGORY$
      String Tools
   $ONELINER$
      Return a string of all the characters in even positions
   $SYNTAX$
      gt_CharEven( <cStr> ) --> cRet
   $ARGUMENTS$
      <cStr>   - A character string to extract chars from
   $RETURNS$
      <cRet>     - A string of all the chars in even positions
   $DESCRIPTION$
      Return a string consisting of all the characters in even
      positions in <cStr1>.

      NOTE:
         invalid parameters will return ""
   $EXAMPLES$
      ? gt_CharEven( "abcdefghijklm" )             // prints "bdfhjl"
   $STATUS$
      R
   $COMPLIANCE$

   $PLATFORMS$

   $FILES$
      Library is hbgt
   $END$
 */

/* $DOC$
   $NAME$
      gt_CharMix()
   $CATEGORY$
      String Tools
   $ONELINER$
      Amalgamate two strings to form the return value
   $SYNTAX$
      gt_CharMix( <cStr1>, <cStr2> ) --> cRet
   $ARGUMENTS$
      <cStr1>  - A character string to mix
      <cStr2>  - A character string to mix with
   $RETURNS$
      <cRet>     - A string consisting of all the characters in <cStr1>
                 mixed with all the characters in <cStr2>
   $DESCRIPTION$
      Return a string consisting of all the characters in <cStr1>
      mixed with the characters from <cStr2>.

      NOTE:
         invalid parameters will return ""
   $EXAMPLES$
      ? gt_CharMix( "abc", "123" )               // prints "a1b2c3"
      ? gt_CharMix( "abcde", "123" )             // prints "a1b2c3de"
      ? gt_CharMix( "abc", "12345" )             // prints "a1b2c345"
   $STATUS$
      R
   $COMPLIANCE$

   $PLATFORMS$

   $FILES$
      Library is hbgt
   $END$
 */

/* $DOC$
   $NAME$
      gt_CharOdd()
   $CATEGORY$
      String Tools
   $ONELINER$
      Return a string of all the characters in odd positions
   $SYNTAX$
      gt_CharOdd( <cStr> ) --> cRet
   $ARGUMENTS$
      <cStr>   - A character string to extract chars from
   $RETURNS$
      <cRet>     - A string of all the chars in odd positions
   $DESCRIPTION$
      Return a string consisting of all the characters in odd
      positions in <cStr1>.

      NOTE:
         invalid parameters will return ""
   $EXAMPLES$
      ? gt_CharOdd( "abcdefghijklm" )             // prints "acegikm"
   $STATUS$
      R
   $COMPLIANCE$

   $PLATFORMS$

   $FILES$
      Library is hbgt
   $END$
 */

/* $DOC$
   $NAME$
      gt_ChrCount()
   $CATEGORY$
      String Tools
   $ONELINER$
      Count the number of times a character appears in a string
   $SYNTAX$
      gt_ChrCount( <cChr>, <cStr> ) --> nFreq
   $ARGUMENTS$
      <cChr>  - The character to find the frequence of
      <cStr>  - The string in which to find the character
   $RETURNS$
      nFreq   - The number of times <cChr> occurs in <cStr>
   $DESCRIPTION$
      gt_ChrCount() counts how many times a specified character
      appears in a string.

      NOTE:
         invalid parameters will return -1
   $EXAMPLES$
      ? gt_ChrCount( "t", "the cat sat on the mat" )      // prints 4
   $STATUS$
      R
   $COMPLIANCE$

   $PLATFORMS$

   $FILES$
      Library is hbgt
   $END$
 */

/* $DOC$
   $NAME$
      gt_ChrFirst()
   $CATEGORY$
      String Tools
   $ONELINER$
      Find which character occurs first in a string
   $SYNTAX$
      gt_ChrFirst( <cChars>, <cStr> ) --> nAsc
   $ARGUMENTS$
      <cChars> - The set of characters to find
      <cStr>   - The input string
   $RETURNS$
      <nAsc>     - The ASCII value of the first character in <cChars>
                 which appears first in <cStr>
   $DESCRIPTION$
      Return the ASCII value of a character in <cChars>
      which appears first in <cStr>.
   $EXAMPLES$
      ? hb_BChar( gt_ChrFirst( "sa ", "This is a test" ) )  // prints "s"
      ? hb_BChar( gt_ChrFirst( "et" , "This is a test" ) )  // prints "t"
   $STATUS$
      R
   $COMPLIANCE$

   $PLATFORMS$

   $FILES$
      Library is hbgt
   $END$
 */

/* $DOC$
   $NAME$
      gt_ChrTotal()
   $CATEGORY$
      String Tools
   $ONELINER$
      Find number of times a set of characters appears in a string
   $SYNTAX$
      gt_ChrTotal( <cChrs>, <cStr> ) --> nTotOcc
   $ARGUMENTS$
      <cChrs> - The set of characters
      <cStr>  - The string to search
   $RETURNS$
      <nTotOcc> - The number of times the characters specified in
                <cChrs> appears in <cStr>
   $DESCRIPTION$
      Returns the numnber of occurrences of characters belonging
      to the set <cChrs> in the string <cStr>.  If no characters
      in <cChrs> appears in <cStr> gt_ChrTotal() will return 0.

      NOTE:
         invalid parameters will return -1
   $EXAMPLES$
      LOCAL cStr1 := "the cat sat on the mat"

         ? gt_ChrTotal( "tae", cStr1 )            // prints 10
         ? gt_ChrTotal( "zqw", cStr1 )            // prints  0
   $STATUS$
      R
   $COMPLIANCE$

   $PLATFORMS$

   $FILES$
      Library is hbgt
   $END$
 */

/* $DOC$
   $NAME$
      gt_StrCount()
   $CATEGORY$
      String Tools
   $ONELINER$
      Count the number of times a substring appears in a string
   $SYNTAX$
      gt_StrCount( <cChrs>, <cStr> ) --> nFreq
   $ARGUMENTS$
      <cChrs> - The substring to find the frequence of
      <cStr>  - The string in which to find the character
   $RETURNS$
      <nFreq>   - The number of times <cChrs> occurs in <cStr>
   $DESCRIPTION$
      gt_StrCount() counts how many times a specified substring
      appears in a string.
      If the substring does NOT appear in <cStr> this function
      will return 0.
      If the substring is a single character use gt_ChrCount() as
      it will be faster.

      NOTE:
         invalid parameters will return -1
   $EXAMPLES$
      ? gt_StrCount( "the", "the cat sat on the mat" )      // prints 2
   $STATUS$
      R
   $COMPLIANCE$

   $PLATFORMS$

   $FILES$
      Library is hbgt
   $END$
 */

/* $DOC$
   $NAME$
      gt_StrCSPN()
   $CATEGORY$
      String Tools
   $ONELINER$
      Return length of prefix in string of chars NOT in set.
   $SYNTAX$
      gt_StrCSPN( <cString>, <cSet> ) --> nLength
   $ARGUMENTS$
      <cString> - The string to find the prefix in
      <cSet>    - The set of characters
   $RETURNS$
      <nLength>   - The length of a string upto a character in the set
   $DESCRIPTION$
      Return the number of characters in the leading segment of a
      string that consists solely of characters NOT in the set.
   $EXAMPLES$
      ? gt_StrCSPN( "this is a test", "as " )      // prints 3
      ? gt_StrCSPN( "this is a test", "elnjpq" )   // prints 11
   $STATUS$
      R
   $COMPLIANCE$

   $PLATFORMS$

   $FILES$
      Library is hbgt
   $END$
 */

/* $DOC$
   $NAME$
      gt_StrDiff()
   $CATEGORY$
      String Tools
   $ONELINER$
      Return a string where it begins to differ from another
   $SYNTAX$
      gt_StrDiff( <cStr1>, <cStr2> ) --> cRet
   $ARGUMENTS$
      <cStr1>  - A character string to compare
      <cStr2>  - The string to compare with
   $RETURNS$
      <cRet>     - A string beginning at the position in <cStr2> where
                 <cStr1> begins to differ from <cStr1>
   $DESCRIPTION$
      Return a string beginning at the position in <cStr2> where
      <cStr1> begins to differ from <cStr1>. If the two strings are
      identical (or identical upto the last character in <cStr2>)
      the function will return "".

      NOTE:
         invalid parameters will return ""
   $EXAMPLES$
      ? gt_StrDiff( "the cat", "the rat" )          // prints "rat"
      ? gt_StrDiff( "the cat", "the " )             // prints ""
   $STATUS$
      R
   $COMPLIANCE$

   $PLATFORMS$

   $FILES$
      Library is hbgt
   $END$
 */

/* $DOC$
   $NAME$
      gt_StrExpand()
   $CATEGORY$
      String Tools
   $ONELINER$
      Insert fillers between characters in a passed string
   $SYNTAX$
      gt_StrExpand( <cStr>, [<nNum>], [<cChar>] ) --> cRet
   $ARGUMENTS$
      <cStr1>  - A character string to insert chars into
      <nNum>   - The number of fill characters to insert (default 1)
      <cChar>  - The fill chararacter (default space)
   $RETURNS$
      <cRet>     - The input string with fill characters inserted between
                 every character in the original.
   $DESCRIPTION$
      Inserts fill characters into a string.

      NOTE:
         invalid parameters will return ""
   $EXAMPLES$
      ? gt_StrExpand( "abc" )                    // prints "a b c"
      ? gt_StrExpand( "abc", 2 )                 // prints "a  b  c"
      ? gt_StrExpand( "abc", 2, '|' )            // prints "a||b||c"
   $STATUS$
      R
   $COMPLIANCE$

   $PLATFORMS$

   $FILES$
      Library is hbgt
   $END$
 */

/* $DOC$
   $NAME$
      gt_StrLeft()
   $CATEGORY$
      String Tools
   $ONELINER$
      Find length of prefix of a string
   $SYNTAX$
      gt_StrLeft( <cStr>, <cChars> ) --> nLen
   $ARGUMENTS$
      <cStr>   - The input string
      <cChars> - The set of characters to find
   $RETURNS$
      nLen     - The length of the prefix found.
   $DESCRIPTION$
      Return the length of the leading segment in the passed string
      <cStr> that consists solely of the characters in the character
      set <cChars>.

      If no characters in the the search set are found, the function
      shall return 0
   $EXAMPLES$
      ? gt_StrLeft( "this is a test", "hsit " )       // prints 8
      ? gt_StrLeft( "this is a test", "hit a" )       // prints 3
      ? gt_StrLeft( "this is a test", "zxy" )         // prints 0
   $STATUS$
      R
   $COMPLIANCE$

   $PLATFORMS$

   $FILES$
      Library is hbgt
   $END$
 */

/* $DOC$
   $NAME$
      gt_StrPBRK()
   $CATEGORY$
      String Tools
   $ONELINER$
      Return string after 1st char from a set
   $SYNTAX$
      gt_StrPBRK( <cStr>, <cSet> ) --> cString
   $ARGUMENTS$
      <cStr>   - The input string
      <cSet>   - The set of characters to find
   $RETURNS$
      <cString>  - The input string after the first occurance of any
                 character from <cSet>
   $DESCRIPTION$
      Return a string after the first occurance of any character from
      the input set <cSet>.
   $EXAMPLES$
      ? gt_StrPBRK( "This is a test", "sa " )  // prints "s is a test"
      ? gt_StrPBRK( "This is a test", "et" )   // prints "test"
   $STATUS$
      R
   $COMPLIANCE$

   $PLATFORMS$

   $FILES$
      Library is hbgt
   $END$
 */

/* $DOC$
   $NAME$
      gt_StrRight()
   $CATEGORY$
      String Tools
   $ONELINER$
      Find length of a suffix of a string
   $SYNTAX$
      gt_StrRight( <cStr>, <cChars> ) --> nLen
   $ARGUMENTS$
      <cStr>   - The input string
      <cChars> - The set of characters to find
   $RETURNS$
      <nLen>     - The length of the prefix found.
   $DESCRIPTION$
      Return the length of the trailing segment in the passed string
      <cStr> that consists solely of the characters in the character
      set <cChars>.

      If no characters in the the search set are found, the function
      shall return 0
   $EXAMPLES$
      ? gt_StrRight( "this is a test", "teas " )       // prints 8
      ? gt_StrRight( "this is a test", "tes h" )       // prints 5
      ? gt_StrRight( "this is a test", "zxy" )         // prints 0
   $STATUS$
      R
   $COMPLIANCE$

   $PLATFORMS$

   $FILES$
      Library is hbgt
   $END$
 */

/* $DOC$
   $NAME$
      gt_NewFlag()
   $CATEGORY$
      General
   $ONELINER$
      Create a new bit flag string.
   $SYNTAX$
      gt_NewFlag( <nFlagCount> ) --> cFlagString
   $ARGUMENTS$
      <nFlagCount> is the number of flags you wish to store.
   $RETURNS$
      A string to hold the bit flags. All flags are set to FALSE.
   $DESCRIPTION$
      gt_NewFlag() is used to construct a bit flag string. The bit flag
      functions can be used for storing a large number of logical values
      in a small space.

      To create a bit flag string you need to pass gt_NewFlag() a value
      that is equal to or greater than the number of flags required (you
      may want to allow for future expansion). Each character in the
      string returned from gt_NewFlag() will hold 8 logical values.
   $EXAMPLES$
      cFlags := gt_NewFlag( 20 )   // Create a bit flag string for 20 logical values.
   $SEEALSO$
      gt_SetFlag(), gt_ClrFlag(), gt_IsFlag()
   $END$
 */

/* $DOC$
   $NAME$
      gt_SetFlag()
   $CATEGORY$
      General
   $ONELINER$
      Set a number of flags to TRUE in a bit flag string.
   $SYNTAX$
      gt_SetFlag( <cFlagString>, [<nStart>], [<nEnd>] ) --> cFlagString
   $ARGUMENTS$
      <cFlagString> is a bit flag string created with gt_NewFlag()

      <nStart> is the starting flag. This is an optional numeric value.
      If not supplied it defaults to 1.

      <nEnd> is the ending flag. This is an optional numeric value. If
      not supplied it defaults to <nStart>.
   $RETURNS$
      The bit map string with the new flag settings.
   $DESCRIPTION$
      gt_SetFlag() is used to turn flags within the flag string on.
   $EXAMPLES$
      cFlags := gt_NewFlag( 20 )   // Create a bit flag string for 20
      // logical values.

      // Now set flags 10 to 15 to true.

      cFlags := gt_SetFlag( cFlags, 10, 15 )

      // And set flag 18 to true.

      cFlags := gt_SetFlag( cFlags, 18 )

      // And set flag 1 to true.

      cFlags := gt_SetFlag( cFlags )
   $SEEALSO$
      gt_NewFlag(), gt_ClrFlag(), gt_IsFlag()
   $END$
 */

/* $DOC$
   $NAME$
      gt_ClrFlag()
   $CATEGORY$
      General
   $ONELINER$
      Set a number of flags to FALSE in a bit flag string.
   $SYNTAX$
      gt_ClrFlag( <cFlagString>, [<nStart>], [<nEnd>] ) --> cFlagString
   $ARGUMENTS$
      <cFlagString> is a bit flag string created with gt_NewFlag()

      <nStart> is the starting flag. This is an optional numeric value.
      If not supplied it defaults to 1.

      <nEnd> is the ending flag. This is an optional numeric value. If
      not supplied it defaults to <nStart>.
   $RETURNS$
      The bit map string with the new flag settings.
   $DESCRIPTION$
      gt_ClrFlag() is used to turn flags within the flag string off.
   $EXAMPLES$
      cFlags := gt_NewFlag( 20 )   // Create a bit flag string for 20
      // logical values.

      // Now, turn them all on.

      cFlags := gt_SetFlag( cFlags, 1, 20 )

      // Now set flags 10 to 15 to false.

      cFlags := gt_ClrFlag( cFlags, 10, 15 )

      // And set flag 18 to false.

      cFlags := gt_ClrFlag( cFlags, 18 )

      // And set flag 1 to false.

      cFlags := gt_ClrFlag( cFlags )
   $SEEALSO$
      gt_NewFlag(), gt_SetFlag(), gt_IsFlag()
   $END$
 */

/* $DOC$
   $NAME$
      gt_IsFlag()
   $CATEGORY$
      General
   $ONELINER$
      Test the setting of a flag in a bit flag string.
   $SYNTAX$
      gt_IsFlag( <cFlagString>, [<nFlag>] ) --> lSetting
   $ARGUMENTS$
      <cFlagString> is a bit flag string created with gt_NewFlag()

      <nFlag> is the flag to be tested.
   $RETURNS$
      A boolean value, TRUE if the flag is on, FALSE if it's off.
   $DESCRIPTION$
      gt_IsFlag() is used to test the state of a flag with a bit flag
      string.
   $EXAMPLES$
      // Print the setting of the flags in a flag string called ``cDave''

      FOR nFlag := 1 TO hb_BLen( cDave ) * 8
         ? "Flag number", nFlag, "==", gt_IsFlag( cDave, nFlag )
      NEXT
   $SEEALSO$
      gt_NewFlag(), gt_SetFlag(), gt_ClrFlag()
   $END$
 */