ULSFindAttr

Description

Searches a string for the first character that fits the specified attribute criterion.

   NOTE: The 'start' and 'max' parameters both specify a number of characters,
         not a number of bytes.  (In the case of MBCS codepages, these may not
         be the same thing).

Arguments

ULSFindAttr( string, attribute [, start] [, max] [, flag] [, codepage] [, locale] )

Parameters:

     string    The input string to be searched.

     attribute The name of the attribute to search for.  Valid attribute names
               are listed under the ULSQueryAttr function description (below).
               The name is not case sensitive.

     start     The character position within the string to start searching
               from.  Must fall between 1 and the string length (in
               characters).  Defaults to 1 (the start of the string) if not
               specified.

     max       The maximum number of characters to search.  Defaults to the
               length of the string (in characters) if not specified.

     flag      The type of search to perform.  Only the first character is
               significant, and (if specified) must be one of the following
               values:
                 T = True: find the first character that matches the specified
                     attribute.  This is the default.
                 F = False: find the first character that does not match the
                     specified attribute.

     codepage  The source codepage (a positive integer).  This is the codepage
               with which <string> is encoded (i.e. under which it would
               display correctly).  The default is the current process
               codepage.

     locale    The name of the locale whose text-attribute rules are to be
               used.  Locale names are usually of the form "xx_YY", where "xx"
               is a language and YY is a country (e.g. "en_US", "zh_TW",
               "it_IT", etc.)  The default is to use the current locale as
               defined by the LANG and LC_* environment variables.

Return Value

The character position of the first match, or 0 if no matching characters were found. If an error occurs, an empty string ("") is returned and the global ULSERR variable will be set to a non-zero value.

Example

   Example:

       /* Input string (encoded for codepage 850) */
       string = 'We had lunch at a caf‚ in Reykjav¡k.'
       SAY string

       /* Search string for the first non-ASCII character */
       c = ULSFindAttr( string, 'ascii',,,'F')
       IF ULSERR \= '0' THEN
           SAY ULSERR
       ELSE
           SAY 'The first non-ASCII character is at position:' c

Output

       We had lunch at a caf‚ in Reykjav¡k.
       The first non-ASCII character is at position: 22