NAME

       XmStringParseText  — A function that converts a character string to a compound string "XmStringParseText"
       "compound string functions" "XmStringParseText"

SYNOPSIS

       #include <Xm/Xm.h>
       XmString XmStringParseText(
       XtPointer text,
       XtPointer *text_end,
       XmStringTag tag,
       XmTextType type,
       XmParseTable parse_table,
       Cardinal parse_count,
       XtPointer call_data);

DESCRIPTION

       XmStringParseText converts characters specified in text  to  corresponding  components  in  the  returned
       compound  string.  The resulting compound string consists of at least one locale or charset tag component
       and a series of XmString text components and other components. The conversion proceeds according  to  the
       parse  information  contained in parse_table. See the Motif Programmer's Guide for more information about
       parsing and parse tables.

          •  If type is XmCHARSET_TEXT, the associated tag is interpreted as a charset name.  If tag has a value
             of NULL, a charset component whose  value  is  the  result  of  mapping  XmFONTLIST_DEFAULT_TAG  is
             created.

          •  If  type  is  XmMULTIBYTE_TEXT  or XmWIDECHAR_TEXT, the associated tag is interpreted as a language
             environment  name.   If  tag  has  a  value  of  NULL,  a  locale  component  with   a   value   of
             _MOTIF_DEFAULT_LOCALE is created.  If type is XmMULTIBYTE_TEXT or XmWIDECHAR_TEXT, tag must be NULL
             or _MOTIF_DEFAULT_LOCALE.

       XmStringParseText  also  scans  the  string  for characters that have matches in parse_table.  Whenever a
       match is found, the text up to that point is concatenated with the mapped component.

       text      Specifies the NULL-terminated string containing characters of a type determined by type.   This
                 is updated to point to after the last character scanned.

       text_end  Specifies  a  pointer  into  text.  If  a  NULL  is  supplied  to  the text_end parameter, then
                 XmStringParseText parses text until NULL is encountered, or until it reaches a  point  in  text
                 where  it  is directed to stop (for example, by a parse_proc). Otherwise, the value supplied to
                 the text_end parameter is the pointer into text where parsing is  to  stop,  and  the  returned
                 character is the one where parsing did stop.

       tag       Specifies  the  tag to be used in creating the result.  The type of string tag created (charset
                 or locale) depends on the text type and the passed in tag value.  If the tag value is NULL  and
                 if  type  indicates  that  a charset string tag should be created, the string tag has the value
                 that is the result of mapping XmFONTLIST_DEFAULT_TAG.  If type indicates a locale  string  tag,
                 the string tag has the value _MOTIF_DEFAULT_LOCALE.

       type      Specifies  the  type  of  text and the tag type.  If a locale tag should be created, type has a
                 value of either XmMULTIBYTE_TEXT or XmWIDECHAR_TEXT.  If type has value  of  XmCHARSET_TEXT,  a
                 charset tag will be created.

       parse_table
                 Specifies  the  parse  table  to  be  used  in scanning for characters to be converted to other
                 compound string components.

       parse_count
                 Specifies the number of entries in parse_table.

       call_data Specifies data to be passed to the parse procedures.

RETURN

       Returns a new compound string.  The function allocates space to hold the returned compound string.   When
       the application no longer needs the returned compound string, the application should call XmStringFree.

RELATED

       XmString(3), XmStringFree(3), XmParseTable(3), XmParseMapping(3).

                                                                                            XmStringParseText(3)