Harbour Reference Guide

gt_ClrFlag()Source code ⌃ | ☰ | Improve this doc

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
LOCAL cFlags := gt_NewFlag( 20 )  // Create a bit flag string for 20
// logical values.

// Now, turn them all on.
? hb_StrToHex( cFlags := gt_SetFlag( cFlags, 1, 20 ) )

// Now set flags 10 to 15 to false.
? hb_StrToHex( cFlags := gt_ClrFlag( cFlags, 10, 15 ) )

// And set flag 18 to false.
? hb_StrToHex( cFlags := gt_ClrFlag( cFlags, 18 ) )

// And set flag 1 to false.
? hb_StrToHex( cFlags := gt_ClrFlag( cFlags ) )
Platforms
Available on all platforms
Tag
General
See also
gt_IsFlag(), gt_NewFlag(), gt_SetFlag()

gt_IsFlag()Source code ⌃ | ☰ | Improve this doc

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>
LOCAL nFlag
FOR nFlag := 1 TO hb_BLen( cDave ) * 8
   ? "Flag number", nFlag, "==", gt_IsFlag( cDave, nFlag )
NEXT
Platforms
Available on all platforms
Tag
General
See also
gt_ClrFlag(), gt_NewFlag(), gt_SetFlag()

gt_NewFlag()Source code ⌃ | ☰ | Improve this doc

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
? hb_StrToHex( gt_NewFlag( 20 ) )  // Create a bit flag string for 20 logical values.
Platforms
Available on all platforms
Tag
General
See also
gt_ClrFlag(), gt_IsFlag(), gt_SetFlag()

gt_SetFlag()Source code ⌃ | ☰ | Improve this doc

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
LOCAL cFlags := gt_NewFlag( 20 )  // Create a bit flag string for 20
// logical values.

// Now set flags 10 to 15 to true.
? hb_StrToHex( cFlags := gt_SetFlag( cFlags, 10, 15 ) )

// And set flag 18 to true.
? hb_StrToHex( cFlags := gt_SetFlag( cFlags, 18 ) )

// And set flag 1 to true.
? hb_StrToHex( cFlags := gt_SetFlag( cFlags ) )
Platforms
Available on all platforms
Tag
General
See also
gt_ClrFlag(), gt_IsFlag(), gt_NewFlag()

gt_AsciiSum()Source code ⌃ | ☰ | Improve this doc

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.
Status
Ready
Compliance
Not applicable
Platforms
Available on all platforms
File
Library is hbgt
Tag
String Tools

gt_AscPos()Source code ⌃ | ☰ | Improve this doc

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
? hb_BChar( gt_AscPos( "the cat sat on the mat", 3 ) )  // --> "e"
Status
Ready
Compliance
Not applicable
Platforms
Available on all platforms
File
Library is hbgt
Tag
String Tools

gt_AtDiff()Source code ⌃ | ☰ | Improve this doc

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 up to the last character in cStr2) the function will return 0.

NOTE:

invalid parameters will return -1

Examples
? gt_AtDiff( "the cat", "the rat" )  // --> 5
? gt_AtDiff( "the cat", "the " )     // --> 0
Status
Ready
Compliance
Not applicable
Platforms
Available on all platforms
File
Library is hbgt
Tag
String Tools

gt_CharEven()Source code ⌃ | ☰ | Improve this doc

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" )  // --> "bdfhjl"
Status
Ready
Compliance
Not applicable
Platforms
Available on all platforms
File
Library is hbgt
Tag
String Tools

gt_CharMix()Source code ⌃ | ☰ | Improve this doc

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" )    // --> "a1b2c3"
? gt_CharMix( "abcde", "123" )  // --> "a1b2c3de"
? gt_CharMix( "abc", "12345" )  // --> "a1b2c345"
Status
Ready
Compliance
Not applicable
Platforms
Available on all platforms
File
Library is hbgt
Tag
String Tools

gt_CharOdd()Source code ⌃ | ☰ | Improve this doc

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" )  // --> "acegikm"
Status
Ready
Compliance
Not applicable
Platforms
Available on all platforms
File
Library is hbgt
Tag
String Tools

gt_ChrCount()Source code ⌃ | ☰ | Improve this doc

Count the number of times a character appears in a string
Syntax
gt_ChrCount( <cChr>, <cStr> ) → nFreq
Arguments
cChr - The character to find the frequency 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" )  // --> 4
Status
Ready
Compliance
Not applicable
Platforms
Available on all platforms
File
Library is hbgt
Tag
String Tools

gt_ChrFirst()Source code ⌃ | ☰ | Improve this doc

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" ) )  // --> "s"
? hb_BChar( gt_ChrFirst( "et" , "This is a test" ) )  // --> "t"
Status
Ready
Compliance
Not applicable
Platforms
Available on all platforms
File
Library is hbgt
Tag
String Tools

gt_ChrTotal()Source code ⌃ | ☰ | Improve this doc

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 number 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 cString := "the cat sat on the mat"

? gt_ChrTotal( "tae", cString )  // --> 10
? gt_ChrTotal( "zqw", cString )  // --> 0
Status
Ready
Compliance
Not applicable
Platforms
Available on all platforms
File
Library is hbgt
Tag
String Tools

gt_StrCount()Source code ⌃ | ☰ | Improve this doc

Count the number of times a substring appears in a string
Syntax
gt_StrCount( <cChrs>, <cStr> ) → nFreq
Arguments
cChrs - The substring to find the frequency 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" )  // --> 2
Status
Ready
Compliance
Not applicable
Platforms
Available on all platforms
File
Library is hbgt
Tag
String Tools

gt_StrCSPN()Source code ⌃ | ☰ | Improve this doc

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 up to 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 " )     // --> 3
? gt_StrCSPN( "this is a test", "elnjpq" )  // --> 11
Status
Ready
Compliance
Not applicable
Platforms
Available on all platforms
File
Library is hbgt
Tag
String Tools

gt_StrDiff()Source code ⌃ | ☰ | Improve this doc

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 up to the last character in cStr2) the function will return "".

NOTE:

invalid parameters will return ""

Examples
? gt_StrDiff( "the cat", "the rat" )  // --> "rat"
? gt_StrDiff( "the cat", "the " )     // --> ""
Status
Ready
Compliance
Not applicable
Platforms
Available on all platforms
File
Library is hbgt
Tag
String Tools

gt_StrExpand()Source code ⌃ | ☰ | Improve this doc

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 character (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" )          // --> "a b c"
? gt_StrExpand( "abc", 2 )       // --> "a  b  c"
? gt_StrExpand( "abc", 2, '|' )  // --> "a||b||c"
Status
Ready
Compliance
Not applicable
Platforms
Available on all platforms
File
Library is hbgt
Tag
String Tools

gt_StrLeft()Source code ⌃ | ☰ | Improve this doc

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 " )  // --> 8
? gt_StrLeft( "this is a test", "hit a" )  // --> 3
? gt_StrLeft( "this is a test", "zxy" )    // --> 0
Status
Ready
Compliance
Not applicable
Platforms
Available on all platforms
File
Library is hbgt
Tag
String Tools

gt_StrPBRK()Source code ⌃ | ☰ | Improve this doc

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 occurrence of any
character from cSet
Description
Return a string after the first occurrence of any character from the input set cSet.
Examples
? gt_StrPBRK( "This is a test", "sa " )  // --> "s is a test"
? gt_StrPBRK( "This is a test", "et" )   // --> "test"
Status
Ready
Compliance
Not applicable
Platforms
Available on all platforms
File
Library is hbgt
Tag
String Tools

gt_StrRight()Source code ⌃ | ☰ | Improve this doc

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 " )  // --> 8
? gt_StrRight( "this is a test", "tes h" )  // --> 5
? gt_StrRight( "this is a test", "zxy" )    // --> 0
Status
Ready
Compliance
Not applicable
Platforms
Available on all platforms
File
Library is hbgt
Tag
String Tools