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()

Harbour All Functions – C

CD / CHDIR / DirChange

CDoW

Chr

CharAdd
CharAnd
CharEven
CharHist
CharList
CharMirr
CharMix
CharNoList
CharNot
CharOdd
CharOne
CharOnly
CharOr
CharPix
CharRela
CharRelRep
CharRem
CharRepl
CharRLL
CharRLR
CharSHL
CharSHR
CharSList
CharSort
CharSub
CharSwap
CharWin
CharXOR

CLIPINIT
CMonth

Col

Cos

CosH

CountLeft
CountRight

CToBit

CToD

CToDoW
CToF
CToMonth
CToN

CurDir

CSetArgErr
CSetAtMuPa
CSetRef
CTCExit
CTCInit
CTExit
CTInit

CT_CSETATMUPA

 CSETATMUPA()
 Determines the setting of the multi-pass mode for ATXXX() functions
------------------------------------------------------------------------------
 Syntax

     CSETATMUPA(<lNewMode>) --> lOldMode

 Argument

     <lNewMode>  Designates the setting for the multi-pass switch for all
     AT functions.  The default value (.F.) sets the multi-pass switch to off

 Returns

     If <lNewMode> is not specified, the current setting is returned.  If
     <lNewMode> is specified, CSETATMUPA() returns the previous setting.

 Description

     CSETATMUPA() sets a switch, internal to Clipper Tools, that affects
     the operation of several other Clipper Tools functions.  These
     functions permit targeted, extremely flexible substring manipulation.
     The affected functions are:

           ATNUM()      AFTERATNUM()    BEFORATNUM()

           ATREPL()     NUMAT()         ATADJUST()

           WORDTOCHAR() WORDREPL()

     The CSETATMUPA() function sets the multi-pass mode on or off for these
     functions.

 Note

     .  The default setting for CSETATMUPA() is .F., indicating that
        the multi-pass mode is off.

 Example

     Switch the multi-pass mode on and save the previous setting:

     lOldMupa  :=  CSETATMUPA(.T.)

See Also: ATNUM() AFTERATNUM() BEFORATNUM() ATREPL()

 

Tools – String Manipulations

Introduction 
ADDASCII()   Adds a value to each ASCII code in a string
AFTERATNUM() Returns remainder of a string after nth appearance of sequence
ASCIISUM()   Finds sum of the ASCII values of all the characters of a string
ASCPOS()     Determines ASCII value of a character at a position in a string
ATADJUST()   Adjusts the beginning position of a sequence within a string
ATNUM()      Determines the starting position of a sequence within a string
ATREPL()     Searches for a sequence within a string and replaces it
ATTOKEN()    Finds the position of a token within a string
BEFORATNUM() Returns string segment before the nth occurrence of a sequence
CENTER()     Centers a string using pad characters
CHARADD()    Adds the corresponding ASCII codes of two strings
CHARAND()    Links corresponding ASCII codes of paired strings with AND
CHAREVEN()   Returns characters in the even positions of a string
CHARLIST()   Lists each character in a string
CHARMIRR()   Mirrors characters within a string
CHARMIX()    Mixes two strings together
CHARNOLIST() Lists the characters that do not appear in a string
CHARNOT()    Complements each character in a string
CHARODD()    Returns characters in the odd positions of a string
CHARONE()    Reduces adjoining duplicate characters in string to 1 character
CHARONLY()   Determines the common denominator between two strings
CHAROR()     Joins the corresponding ASCII code of paired strings with OR
CHARPACK()   Compresses (packs) a string
CHARRELA()   Correlates the character positions in paired strings
CHARRELREP() Replaces characters in a string depending on their correlation
CHARREM()    Removes particular characters from a string
CHARREPL()   Replaces certain characters with others
CHARSORT()   Sorts sequences within a string
CHARSPREAD() Expands a string at the tokens
CHARSWAP()   Exchanges all adjoining characters in a string
CHARUNPACK() Decompresses (unpacks) a string
CHARXOR()    Joins ASCII codes of paired strings with exclusive OR operation
CHECKSUM()   Calculates the checksum for a character string (algorithm)
COUNTLEFT()  Counts a particular character at the beginning of a string
COUNTRIGHT() Counts a particular character at the end of a string
CRYPT()      Encrypts and decrypts a string
CSETATMUPA() Determines setting of the multi-pass mode for ATXXX() functions
CSETREF()    Determines whether reference sensitive functions return a value
EXPAND()     Expands a string by inserting characters
JUSTLEFT()   Moves characters from the beginning to the end of a string
JUSTRIGHT()  Moves characters from the end of a string to the beginning
LIKE()       Compares character strings using wildcard characters
LTOC()       Converts a logical value into a character
MAXLINE()    Finds the longest line within a string
NUMAT()      Counts the number of occurrences of a sequence within a string
NUMLINE()    Determines the number of lines required for string output
NUMTOKEN()   Determines the number of tokens in a string
PADLEFT()    Pads a string on the left to a particular length
PADRIGHT()   Pads a string on the right to a particular length
POSALPHA()   Determines position of first alphabetic character in a string
POSCHAR()    Replaces individual character at particular position in string
POSDEL()     Deletes characters at a particular position in a string
POSDIFF()    Finds the first position from which two strings differ
POSEQUAL()   Finds the first position at which two strings are the same
POSINS()     Inserts characters at a particular position within a string
POSLOWER()   Finds the position of the first lower case alphabetic character
POSRANGE()   Determines position of first character in an ASCII code range
POSREPL()    Replaces one or more characters from a certain position
POSUPPER()   Finds the position of the first uppercase, alphabetic character
RANGEREM()   Deletes characters that are within a specified ASCII code range
RANGEREPL()  Replaces characters within a specified ASCII code range
REMALL()     Removes characters from the beginning and end of a string
REMLEFT()    Removes particular characters from the beginning of a string
REMRIGHT()   Removes particular characters at the end of a string
REPLALL()    Exchanges characters at the beginning and end of a string
REPLLEFT()   Exchanges particular characters at the beginning of a string
REPLRIGHT()  Exchanges particular characters at the end of a string
RESTTOKEN()  Recreates an incremental tokenizer environment
SAVETOKEN()  Saves the incremental tokenizer environment to a variable
SETATLIKE()  Provides an additional search mode for all AT functions
STRDIFF()    Finds similarity between two strings (Levenshtein Distance)
STRSWAP()    Interchanges two strings
TABEXPAND()  Converts tabs to spaces
TABPACK()    Converts spaces in tabs
TOKEN()      Selects the nth token from a string
TOKENAT()    Determines the most recent TOKENNEXT() position within a string
TOKENEND()   Determines if more tokens are available in TOKENNEXT()
TOKENINIT()  Initializes a string for TOKENNEXT()
TOKENLOWER() Converts initial alphabetic character of a token into lowercase
TOKENNEXT()  Provides an incremental tokenizer
TOKENSEP()   Provides separator before/after most recently retrieved TOKEN()
TOKENUPPER() Converts the initial letter of a token into upper case
VALPOS()     Determines numerical value of character at particular position
WORDONE()    Reduces multiple appearances of double characters to one
WORDONLY()   Finds common denominator of 2 strings on double character basis
WORDREPL()   Replaces particular double characters with others
WORDSWAP()   Exchanges double characters lying beside each other in a string
WORDTOCHAR() Exchanges double characters for individual ones