CT_PADRIGHT

 PADRIGHT()
 Pads a string on the right to a particular length
------------------------------------------------------------------------------
 Syntax

     PADRIGHT(<cString>,<nLength>,[<cCharacter|
        nCharacter>]) --> cString

 Arguments

     <cString>  Designates the string that is processed.

     <nLength>  Designates the selected new length for <cString>.

     <cCharacter|nCharacter>  Designates the character with which the
     beginning of the <cString> string is filled.  The default value is a
     space, CHR(32).

 Returns

     The processed <cString> is returned.

 Description

     PADRIGHT() allows you to pad the end of a character string with
     characters, in accordance with a length specification.  Spaces or any
     other characters that you choose can be used.

 Notes

     .  The function works like the Clipper LEFT() function when
        <nLength> is shorter than the length of <cString>.  If <nLength> is
        negative, PADRIGHT() returns a null string.

     .  When the <cCharacter|nCharacter> parameter is not specified,
        spaces are automatically used for padding.

 Examples

     .  The function works like LEFT():

        ? PADRIGHT("123456", 4)              // "1234"

     .  Pad the right with spaces:

        ? PADRIGHT("123456", 8)              // "123456  "

     .  Pad the right with the "." character:

        ? PADRIGHT("123456", 8, ".")         // "123456.."

See Also: PADLEFT()



CT_PADLEFT

 PADLEFT()
 Pads a string on the left to a particular length
------------------------------------------------------------------------------
 Syntax

     PADLEFT(<cString>,<nLength>,[<cCharacter|
        <nCharacter>]) --> cString

 Arguments

     <cString>  Designates the string that is processed.

     <nLength>  Designates the new length for <cString>.

     <cCharacter|nCharacter>  Designates the character with which the
     beginning of the <cString> string is filled.  The default value is a
     space, CHR(32).

 Returns

     The processed <cString> is returned.

 Description

     PADLEFT() allows you to pad the beginning of character strings with
     characters, in accordance with a length specification.  Spaces or any
     other characters you choose can be used.

 Notes

     .  The function works like the Clipper RIGHT() function when
        <nLength> is shorter than the length of <cString>.  If <nLength> is
        negative, PADLEFT() returns a null string.

     .  When the <cCharacter|nCharacter> parameter is not specified,
        spaces are automatically used for padding.

 Examples

     .  The function works like RIGHT():

        ? PADLEFT("123456", 4)              // "3456"

     .  Pad the left with spaces:

        ? PADLEFT("123456", 8)              // "  123456"

     .  Pad the left with the "." character:

        ? PADLEFT("123456", 8, ".")         // "..123456"

See Also: PADRIGHT()

CT_NUMTOKEN

 NUMTOKEN()
 Determines the number of tokens in a string
------------------------------------------------------------------------------
 Syntax

     NUMTOKEN(<cString>,[<cDelimiter>],[<nSkipWidth>])
        --> nNumber

 Arguments

     <cString>  Designates the string that is passed.

     <cDelimiter>  Designates the delimiter list used by the passer.

     <nSkipWidth>  Designates after what number of delimiter characters
     or sequences to count a token.  This is helpful for counting empty
     tokens.  The default value indicates that empty tokens are not taken
     into account.

 Returns

     The number of tokens contained in the <cString> is returned.

 Description

     Use NUMTOKEN() to determine how many words (or tokens) are contained in
     the character string.  The function uses the following list of
     delimiters as a standard:

     CHR 32, 0, 9, 10, 13, 26, 32, 138, 141

     and the characters ,.;:!?/\<<>>()^#&%+-*

     The list can be replaced by your own list of delimiters, <cDelimiter>.
     Here are some examples of useful delimiters:

     Table 4-3: Recommended Delimiter Sequences
     ------------------------------------------------------------------------
     Description         <cDelimiter>
     ------------------------------------------------------------------------
     Pages               CHR(12)(Form Feed)
     Sentences           ".!?"
     File Names          ":\."
     Numerical strings   ",."
     Date strings        "/."
     Time strings        ":."
     ------------------------------------------------------------------------

     The skip value designates the number of characters after which a token
     is counted again.  This also allows empty tokens, like blanks within a
     string, to be counted.

 Examples

     .  A character string is searched using the standard delimiter
        list:

        ? NUMTOKEN("Good Morning!")      // Result: 2

     .  Your own list of delimiters can be specified for particular
        reasons.  Since the delimiter list for the following example only
        contains the characters ".!?", the result is 3.

        ? NUMTOKEN("Yes!  That's it. Maybe not?", ".!?")

     .  This example shows how to count empty tokens.  Parameters
        separated by commas are counted, but some of the parameters are
        skipped.  A token is counted after at least one delimiter (comma):

        String  :=  "one,two,,four"
        ? NUMTOKEN(String, ", ", 1)      // Result: 4

See Also: TOKEN() ATTOKEN() TOKENUPPER() TOKENLOWER()

 

CT_NUMLINE

 NUMLINE()
 Determines the number of lines required for string output
------------------------------------------------------------------------------
 Syntax

     NUMLINE(<cString>,[<nLineLength>]) --> nNumber

 Arguments

     <cString>  Designates the character string that is processed.

     <nLineLength>  Designates the length of an output line.  The default
     value is 80 characters.

 Returns

     NUMLINE() returns the number of lines required for text output.

 Description

     NUMLINE() can determine the number of lines that are required to output
     a MEMO field.  The return value relates to a line length that is
     determined by <nLineLength>.

 Note

     .  With the exception of the carriage return and the line feed,
        this function treats all characters as printable with a width of 1.
        If the <cString> text contains tabs, then you must first use the
        TABEXPAND() function to expand the tabs to spaces.

 Examples

     .  A null string occupies one line:

        ? NUMLINE("")                                       // 1

     .  A string one character longer also occupies one line:

        ? NUMLINE("-")                                      // 1

     .  80 characters, at a line width of 80 characters (default
        value), occupy two lines:

        ? NUMLINE(REPLICATE("-", 80))                       // 2

     .  100 characters, at a line width of 30 characters, occupy 4
        lines:

        ? NUMLINE(REPLICATE("-", 100), 30)                  // 4

     .  A line feed is also handled correctly -- an extra line is
        required:

        ? NUMLINE("-", +crlf)                               // 2
        ? NUMLINE(REPLICATE("-", 100) +crlf, 30)            // 5

See Also: TABEXPAND() MAXLINE()

 

CT_NUMAT

 NUMAT()
 Counts the number of occurrences of a sequence within a string
------------------------------------------------------------------------------
 Syntax

     NUMAT(<cSearchFor>,<cString>,[<nIgnore>]) --> nNumber

 Arguments

     <cSearchFor>  Designates the search string.

     <cString>  Designates the string to search.

     <nIgnore>  Designates 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
     <cSearchFor> sequence was found in the <cString>.

 Description

     NUMAT() determines how often a particular <cSearchFor> 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 <cSearchFor>
     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.

See Also: CSETATMUPA() SETATLIKE()

CT_MAXLINE

 MAXLINE()
 Finds the longest line within a string
------------------------------------------------------------------------------
 Syntax

     MAXLINE(<cString>) --> nLength

 Argument

     <cString>  Designates the string that is processed.

 Returns

     The function returns the maximum line length necessary to display the
     <cString> text without automatic line breaks.

 Description

     MAXLINE() looks for the longest line within a character string.  This
     allows you to determine the required width for a window to display text
     (MEMO fields).  In this way the text can be displayed without additional
     line breaks.

 Note

     .  With the exception of the carriage return and the line feed,
        this function treats all characters as printable with a width of 1.
        If the <cString> text contains tabs, then you must first use the
        TABEXPAND() function to expand the tabs to spaces.

 Example

     A function, based on the maximum line length, automatically performs a
     suitable call of MEMOEDIT():

     FUNCTION SHOWMEMO(cMemo)

     LOCAL cMessage, nHeight, nWidth

        nHeight   :=  MIN(NUMLINE(cMemo), MAXROW() -1)
        nWidth    :=  MIN(MAXLINE(cMemo), MAXCOL() -1)

        IF nWidth = 0
           cMessage  :=  "The memo field is empty"
        ELSE
           cMessage  :=  ""
           @ 0, 0 TO nHeight +1, nWidth +1 DOUBLE
           MEMOEDIT(cMemo, 1, 1, nHeight, nWidth, .F.)
        ENDIF
        RETURN(cMessage)

See Also: TABEXPAND() NUMLINE()



CT_LTOC

 LTOC()
 Converts a logical value into a character
------------------------------------------------------------------------------
 Syntax

     LTOC([<lValue>]) --> cCharacter

 Argument

     <lValue>  Designates the logical value that is converted. The
     default value is .F..

 Returns

     The character returned corresponds to the logical value specified in the
     parameter.

 Description

     In contrast to the LTON() function, which converts a logical value into
     a number, LTOC() returns a value for the type character string.  This
     can be particularly helpful with combined index keys.

 Examples

     .  Without parameters, .F. is assumed:

        ? LTOC()               // "F"

     .  Return a letter that corresponds to the specified logical
        value:

        ? LTOC(.F.)            // "F"

        ? LTOC(.T.)            // "T"

     .  Other functions can return the logical value:

        ? LTOC(DELETED())      // "T" or "F"

See Also: LTON()



CT_LIKE

 LIKE()
 Compares character strings using wildcard characters
------------------------------------------------------------------------------
 Syntax

     LIKE(<cString1>,<cString2>) --> lEqual

 Arguments

     <cString1>  Designates the wildcard string for comparison.  All
     wildcards must be in this character string.

     <cString2>  Designates the string to compare to <cString1>.

 Returns

     LIKE() returns .T. when, after taking wildcards into account, both
     character strings are equal.

 Description

     This function allows you to compare two character strings with one
     another, where the first can contain wildcard characters.  This is
     similar to the way wildcard characters are used in conjunction with DOS
     commands but not identical.  Any single character matches a "?" in the
     first string (see examples).  The "*" within <cString1> can be placed
     anywhere and matches multiple characters.  You can also use multiple
     "*".

 Note

     .  You can also use wildcard characters in conjunction with an
        array of other string functions by using the SETATLIKE() switch, but
        only for the "?".

 Examples

     .  This example shows differences from DOS:

        Dir XYZ?.DBF                     // shows XYZ.DBF and XYZ1.DBF

        ? LIKE("XYZ?", "XYZ")            // .F.
        ? LIKE("XYZ?", "XYZ1")           // .T.

     .  This example shows other combinations:

        ? LIKE("*OG.*", "PROG.PRG")      // .T.
        ? LIKE("*OG.*", "LOG.PRG")       // .T.
        ? LIKE("*R*T*", "PROTO")         // .T.
        ? LIKE("*R*T*?", "PROTO")        // .F.
        ? LIKE("*R*T*?", "PROTO2")       // .T.

     .  Use wildcards in the first parameter only:

        ? LIKE("*PER", "CLIPPER")        // .T.
        ? LIKE("CLIPPER", "*PER")        // .F.

See Also: SETATLIKE()

 

CT_JUSTRIGHT

 JUSTRIGHT()
 Moves characters from the end of a string to the beginning
------------------------------------------------------------------------------
 Syntax

     JUSTRIGHT(<cString>,[<cCharacter|nCharacter>])
        --> cString

 Arguments

     <cString>  [@] Designates the string that is processed.

     <cCharacter|nCharacter>  Designates the character that is moved from
     the end of the <cString> to the beginning.  The default value is a
     space, CHR(32).

 Returns

     The processed <cString> is returned.

 Description

     JUSTRIGHT() moves the characters specified in <cCharacter| nCharacter>
     from the end of a character string to the beginning.  Then the remaining
     text in the character string is right justified, without affecting the
     length.

 Notes

     .  If the <cCharacter|nCharacter> parameter is not specified,
        spaces are automatically moved.

     .  The return value for this function can be suppressed by
        implementing CSETREF() to save room in working memory.

 Examples

     .  Move the blanks:

        ? JUSTRIGHT("123   ")           // "   123"

     .  Move the "." character:

        ? JUSTRIGHT("123..", ".")       // "..123 "

See Also: JUSTLEFT() CSETREF() Introduction



CT_JUSTLEFT

 JUSTLEFT()
 Moves characters from the beginning to the end of a string
------------------------------------------------------------------------------
 Syntax

     JUSTLEFT(<cString>,[<cCharacter|nCharacter>])
        --> cString

 Arguments

     <cString>  [@]  Designates the string that is processed.

     <cCharacter|nCharacter>  Designates the character that is moved from
     the beginning of the <cString> to the end.  The default value is a
     space, CHR(32).

 Returns

     The processed <cString> is returned.

 Description

     JUSTLEFT() moves the characters specified in <cCharacter|nCharacter>
     from the beginning of a character string to the end.  Then the remaining
     text in the character string is left justified, without affecting the
     length.

 Notes

     .  If the <cCharacter|nCharacter> parameter is not specified,
        spaces are automatically moved.

     .  The return value for this function can be suppressed by
        implementing CSETREF() to save room in working memory.

 Examples

     .  Move the blanks:

        ? JUSTLEFT("   123")              // "123   "

     .  Move the "." character:

        ? JUSTLEFT("..123"," ".)          // "123.."

See Also: JUSTRIGHT() CSETREF() Introduction