WordToChar()

WordToChar()

Replace double with single characters

Syntax

       WordToChar( <cDoubleCharacterSearchString>, <cString>,
                   <cSingleCharacterReplaceString> ) -> cString

Arguments

<cDoubleCharacterSearchString> Designates multiple 2-byte sequences which are exchanged for corresponding individual characters from the <cSingleCharacter ReplaceString>.

<cString> Designates the character string within which 2-byte sequences are exchanged for individual characters.

<cSingleCharacterReplaceString> Designates a sequence of individual characters which correspond to 2-byte sequences in <cDoubleCharacterSearchString> for replacement within <cString>.

Returns

WordToChar() returns the modified character string.

Description

When you use SOUNDEX algorithms, sequences of two characters must often be exchanged for a single other character. WordToChar() makes this process extremely simple and quick. The function processes the <cString> in 1-byte steps. The behavior after exchanging a sequence for a character is determined by CSetAtMuPa(). If CSetAtMuPa is .F., the search for more sequences continues after the exchanged characters. If CSetAtMuPa is .T., the search for more sequences continues and includes the exchanged characters.

Notes

. The term “word” is not used here in the textual sense, but rather as it is used in assembler programming. A “word” consists of units of 16 bits, or more precisely, 2 bytes. . <cCharacterlist> can be shorter than <cDoubleCharacterList>. When this occurs, the function exchanges the sequences in <cDoubleCharacterList> that do not have corresponding sequences in <cCharacterlist> for the last sequence in <cDoubleCharacterList>.

Examples

       .  This example shows a simple replacement:
              ? WordToChar("aa", "Xaaaa", "a")      // "Xaa"
       .  This example shows WORDTOCHAR() in conjunction with
          CSetAtMuPa():
          CSetAtMuPa(.F.)                       // Multi pass off
          ? WordToChar("aa", "Xaaaa", "a")      // "Xaa"
          CSetAtMuPa(.T.)                       // Multi pass on
          ? WordToChar("aa", "Xaaaa", "a")      // "Xa"

Compliance

WordToChar() is compatible with CT3’s WordToChar().

Platforms

All

Files

Source is wordtoch.c, library is libct.

Seealso

CSetAtMuPa(), CharRepl(), WordRepl()

NUMAT()

NUMAT()

Number of occurrences of a sequence in a string

Syntax

       NUMAT( <cStringToMatch>, <cString>, [<nIgnore>] ) --> nCount

Arguments

<cStringToMatch> The search string. <cString> The string to search.

<nIgnore> The number of characters that are excluded from the search. The default value ignores none.

Returns

The function returns a value that specifies how frequently the <cStringToMatch> sequence was found in the <cString>.

Description

NUMAT() determines how often a particular <cStringToMatch> appears within <cString>. When you use <nIgnore> you can lock out a number of characters at the beginning of the <cString> and keep them out of the search. The setting for CSETATMUPA() impacts your results. The character string is searched from the left for each occurrence of the <cStringToMatch> string. If CSETATMUPA() is .F., then the search continues after the last character of the found sequence. If CSETATMUPA() is .T., then the search continues after the first character of the found sequence.

Note

. By implementing SETATLIKE(), wildcard characters can be used within the search expression.

Examples

       .  Count from the first position:
              ? NUMAT("ab", "abcdeabc")            // Result: 2
           .  Count from the second position.  <nIgnore> specifies that one
              space is to be skipped:
              ? NUMAT("ab", "abcdeabc", 1)         // Result: 1
           .  This example shows the impact of CSETATMUPA() when counting
              the string "aa" within the <cString> string:
              CSETATMUPA(.F.)                      // Off
              ? NUMAT("aa", "aaaab")               // Result: 2
              CSETATMUPA(.T.)                      // On
              ? NUMAT("aa", "aaaab")               // Result: 3
           .  Examples for the use of SETATLIKE() can be found under the
              corresponding function description.

Compliance

NUMAT() is compatible with CT3’s NUMAT().

Platforms

All

Files

Source is numat.c, library is libct.

Seealso

CSETATMUPA(), SETATLIKE()

WordRepl()

WordRepl()

Replacement of double characters

Syntax

      WordRepl( <cDoubleCharacterSearchString>, <[@]cString>,
                <cDoubleCharacterReplaceString>, [<lMode>] ) -> <cString>

Arguments

<cDoubleCharacterSearchString> is a string of double characters that should be replaced

<[@]cString>is the processed string

<cDoubleCharacterReplaceString> is a string of double characters that replace the one of <cSearchString>

[<lMode>] sets the replacement method (see description) Default: .F.

Returns

<cString> the processed string

Description

The WordRepl() takes the double characters of <cDoubleCharacterSearchString> one after the other and searches for them in <cString>. For <lMode> set to .F., this search is successful, if the double character sequence in <cString> starts at an odd position or at any position, if <lMode> is set to .T.

If this happens, the double character sequence will be replaced with the corresponding double character sequence of <cDoubleCharacter ReplaceString>. If <cDoubleCharacter ReplaceString> is shorter than <cDoubleCharacter SearchString> the last double sequence of <cDoubleCharacter ReplaceString> is used for the “rest” of <cDoubleCharacter SearchString>. Note that the last double character sequence in “AABBC” is “BB” in this context !!

After the replacement the function restarts the search in <cString> BEHIND the replacement if the CSETATMUPA() switch is turned off, or BEHIND the first character of the replacement if the switch is turned on. (see examples for this !) One can omit the return value of this function by setting the CSETREF() to .T., but one must then pass <cString> by reference to get a result.

Examples

      ? WordRepl( "CC", "AABBCCDDEE", "XX" ) // "AABBXXDDEE"
      ? WordRepl( "aa", "1aaaa", "ba" )      // "1abaa"
      ? WordRepl( "aa", "1aaaa", "ba", .T. ) // "1baba"
      csetatmupa( .T. )
      ? WordRepl( "aa", "1aaaa", "ba" )      // "1abaa"
      ? WordRepl( "aa", "1aaaa", "ba", .T. ) // "1bbba"

Tests

      WordRepl( "CC", "AABBCCDDEE", "XX" ) == "AABBXXDDEE"
      WordRepl( "aa", "1aaaa", "ba" )      == "1abaa"
      WordRepl( "aa", "1aaaa", "ba", .T. ) == "1baba"
      Eval( {|| csetatmupa( .T. ), WordRepl( "aa", "1aaaa", "ba" ) } ) == "1abaa"
      Eval( {|| csetatmupa( .T. ), WordRepl( "aa", "1aaaa", "ba", .T. ) } ) == "1bbba"

Compliance

WordRepl() is compatible with CT3’s WordRepl().

Platforms

All

Files

Source is wordrepl.c, library is ct3.

Seealso

CHARREPL(), RANGEREPL(), POSREPL(), CSETREF(), CSETATMUPA()

AtNum()

AtNum()

Returns the start position of the nth occurence of a substring in a string

Syntax

      AtNum (<cStringToMatch>, <cString>, [<nCounter>],
             [<nIgnore>] ) --> nPosition

Arguments

<cStringToMatch> is the substring scanned for <cString> is the scanned string

[<nCounter>] determines how many occurences are of <cStringToMatch> in <cString> are searched Default: search last occurence

[<nIgnore>] determines how many character from the start should be ignored in the search Default: 0

Returns

<nPosition> the position of the <nCounter>th occurence of <cStringToMatch> in <cString>. If such an occurence does not exist, 0 is returned.

Description

This function scans <cString> for <cStringToMatch>. After the <nCounter>th match (or the last one, depending on the value of <nCounter>) has been found, the position of that match will be returned. If there aren’t enough matches or there is no last match, 0 will be returned. After a match has been found, the function continues to scan after that match if the CSETATMUPA() switch is turned off, with the second character of the matched substring otherwise. The function will also consider the settings of SETATLIKE().

Examples

      ? AtNum( "!", "What is the answer ? 4 ! 5 !" ) // -> 28
      ? AtNum( "!", "What is the answer ? 4 ! 5 ?" ) // -> 24

Tests

      AtNum( "..", "..This..is..a..test!" ) == 14
      AtNum( "..", "..This..is..a..test!", 2 ) == 7
      AtNum( "..", "..This..is..a..test!", 2, 2 ) == 11

Compliance

AtNum() is compatible with CT3’s AtNum().

Platforms

All

Files

Source is AtNum.c, library is libct.

Seealso

AtNum(), AfterAtNum(), CSETATMUPA(), SETATLIKE()

AtAdjust()

AtAdjust()

Adjusts a sequence within a string to a specified position

Syntax

      AtAdjust( <cStringToMatch>, <cString>, <nAdjustPosition>,
                [<nCounter>], [<nIgnore>],
                [<nFillChar|cFillChar>] ) -> cString

Arguments

<cStringToMatch> is the sequence to be adjusted within <cString>

<cString> is the string that contains <cStringToMatch>

<nAdjustPosition> specifies the position to that <cStringToMatch> will be adjusted

[<nCounter>] specifies which occurence of <cStringToMatch> in <cString> is to be adjusted. Default: last occurence

[<nIgnore>] specifies how many characters should be omitted in the scan

[<nFillChar|cFillChar>] specifies the character that is used for the adjustment

Returns

<cString> the changed string

Description

The function first looks for the <cSearchFor> parameter within the character string. From this point, the rest of the <cString> is moved (adjusted) by either inserting or removing blanks until the <nTargetPosition> is reached. In lieu of blanks, <nCharacter> | <cCharacter> can be used as a fill character.

Additionally you can specify that the nth occurrence of be used and whether or not a specific number of characters at the beginning of the search string is eliminated.

Note

Using CSETATMUPA() can influence how the search is performed.

Using SETATLIKE() permits the use of wild cards within the search sequence.

Examples

     .  Align comments at column 60.  The search is for the first
        occurrence of "//".  Since there is usually at least one space before
        each "//", search for " //":

        ? AtAdjust(" //", Line, 60, 1)

     .  Move the extensions for the following list of file names to
        position 10 and eliminate the ".":

        WINDOW.DBF
        PLZ.DBF
        BACK.DBF
        HELP.DBF
        LOG.DBF

        CHARREM(".", AtAdjust(".", File, 10))

        WINDOW      DBF

        PLZ         DBF
        BACK        DBF
        HELP        DBF
        LOG         DBF

Use AtAdjust() with CSETATMUPA(). There is always a problem determining whether “AA” occurs twice or three times in “AAA”. Depending on CSETATMUPA(), the function searches behind the last character, or starts from the last character of a located sequence:

        CSETATMUPA(.F.)
        ? AtAdjust("AA", "123AAABBB", 7, 2)       // Sequence not found

        CSETATMUPA(.T.)
        ? AtAdjust("AA", "123AAABBB", 7, 2)       // "123A  AABBB"

Compliance

AtAdjust() works like CT3’s AtAdjust()

Platforms

All

Files

Source is AtAdjust.c, library is ct3.

Seealso

SETATLIKE(), CSETATMUPA()

AfterAtNum()

AfterAtNum()

Returns string portion after nth occurence of substring

Syntax

      AfterAtNum( <cStringToMatch>, <cString>, [<nCounter>],
                  [<nIgnore>] ) --> cRestString

Arguments

<cStringToMatch> is the substring scanned for <cString> is the scanned string

[<nCounter>] determines how many occurences are of <cStringToMatch> in <cString> are searched Default: search last occurence

[<nIgnore>] determines how many character from the start should be ignored in the search Default: 0

Returns

<cRestString> the portion of <cString> after the <nCounter>th occurence of <cStringToMatch> in <cString> If such a rest does not exist, an empty string is returned.

Description

This function scans <cString> for <cStringToMatch>. After the <nCounter>th match (or the last one, depending on the value of <nCounter>) has been found, the portion of <cString> after that match will be returned. If there aren’t enough matches or the last match is identical to the end of <cString>, an empty string will be returned. After a match has been found, the function continues to scan after that match if the CSETATMUPA() switch is turned off, with the second character of the matched substring otherwise. The function will also consider the settings of SETATLIKE().

Examples

      ? AfterAtNum( "!", "What is the answer ? 4 ! 5 !" ) // -> ""
      ? AfterAtNum( "!", "What is the answer ? 4 ! 5 ?" ) // -> " 5 ?"
      <TODO: add some examples here with csetatmupa() and setatlike()>

Tests

      AfterAtNum( "..", "..This..is..a..test!" ) == "test!"
      AfterAtNum( "..", "..This..is..a..test!", 2 ) == "is..a..test!"
      AfterAtNum( "..", "..This..is..a..test!", 2, 2 ) == "a..test!"

Compliance

AfterAtNum() is compatible with CT3’s AfterAtNum().

Platforms

All

Files

Source is atnum.c, library is libct.

Seealso

ATNUM(), BEFORATNUM(), CSETATMUPA(), SETATLIKE()