/*
 * $Id$
 */

/*
 * The following parts are Copyright of the individual authors.
 * www - http://www.harbour-project.org
 *
 * Copyright 1999 Andy M Leighton
 *    Documentation
 *
 * See doc/license.txt for licensing terms.
 *
 */

/*
 *  $DOC$
 *  $FUNCNAME$
 *      GT_ASCPOS()
 *  $CATEGORY$
 *      String
 *  $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 substr(<cStr>, <nPos>, 1)
 *  $DESCRIPTION$
 *      Return the ascii value of a specified character in a string
 *      Equivalent (but much faster) to
 *          asc(substr(cStr, nPos, 1)
 *
 *      NOTE:
 *         invalid parameters will return -1
 *         nPos > len(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
 *  $FILES$
 *      Library is Tools.lib
 *  $END$
 */

/*
 *  $DOC$
 *  $FUNCNAME$
 *      GT_ASCIISUM()
 *  $CATEGORY$
 *      String
 *  $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$
 *  $FILES$
 *      Library is Tools.lib
 *  $END$
 */

/*
 *  $DOC$
 *  $FUNCNAME$
 *      GT_ATDIFF()
 *  $CATEGORY$
 *      String
 *  $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
 *  $FILES$
 *      Library is Tools.lib
 *  $END$
 */

/*
 *  $DOC$
 *  $FUNCNAME$
 *      GT_CHAREVEN()
 *  $CATEGORY$
 *      String
 *  $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"
 *  $FILES$
 *      Library is Tools.lib
 *  $END$
 */

/*
 *  $DOC$
 *  $FUNCNAME$
 *      GT_CHARMIX()
 *  $CATEGORY$
 *      String
 *  $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"
 *  $FILES$
 *      Library is Tools.lib
 *  $END$
 */

/*
 *  $DOC$
 *  $FUNCNAME$
 *      GT_CHARODD()
 *  $CATEGORY$
 *      String
 *  $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"
 *  $FILES$
 *      Library is Tools.lib
 *  $END$
 */

/*
 *  $DOC$
 *  $FUNCNAME$
 *      GT_CHRCOUNT()
 *  $CATEGORY$
 *      String
 *  $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
 *  $FILES$
 *      Library is Tools.lib
 *  $END$
 */

/*
 *  $DOC$
 *  $FUNCNAME$
 *      GT_CHRFIRST()
 *  $CATEGORY$
 *      String
 *  $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$
 *
 *      ? chr(GT_ChrFirst("sa ", "This is a test"))  // prints "s"
 *      ? chr(GT_ChrFirst("et",  "This is a test"))   // prints "t"
 *  $FILES$
 *      Library is Tools.lib
 *  $END$
 */

/*
 *  $DOC$
 *  $FUNCNAME$
 *      GT_CHRTOTAL()
 *  $CATEGORY$
 *      String
 *  $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
 *  $FILES$
 *      Library is Tools.lib
 *  $END$
 */

/*
 *  $DOC$
 *  $FUNCNAME$
 *      GT_STRCOUNT()
 *  $CATEGORY$
 *      String
 *  $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
 *  $FILES$
 *      Library is Tools.lib
 *  $END$
 */

/*
 *  $DOC$
 *  $FUNCNAME$
 *      GT_STRCSPN()
 *  $CATEGORY$
 *      String
 *  $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
 *  $FILES$
 *      Library is Tools.lib
 *  $END$
 */

/*
 *  $DOC$
 *  $FUNCNAME$
 *      GT_STRDIFF()
 *  $CATEGORY$
 *      String
 *  $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 ""
 *  $FILES$
 *      Library is Tools.lib
 *  $END$
 */

/*
 *  $DOC$
 *  $FUNCNAME$
 *      GT_STREXPAND()
 *  $CATEGORY$
 *      String
 *  $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 "abc"
 *  $FILES$
 *      Library is Tools.lib
 *  $END$
 */

/*
 *  $DOC$
 *  $FUNCNAME$
 *      GT_STRLEFT()
 *  $CATEGORY$
 *      String
 *  $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
 *  $FILES$
 *      Library is Tools.lib
 *  $END$
 */

/*
 *  $DOC$
 *  $FUNCNAME$
 *      GT_STRPBRK()
 *  $CATEGORY$
 *      String
 *  $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"
 *  $FILES$
 *      Library is Tools.lib
 *  $END$
 */

/*
 *  $DOC$
 *  $FUNCNAME$
 *      GT_STRRIGHT()
 *  $CATEGORY$
 *      String
 *  $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
 *  $FILES$
 *      Library is Tools.lib
 *  $END$
 */

