lparse_c

Index Page lparse_c
A B C D E F G H I J K L M N O P Q R S T U V W X
Procedure Abstract Required_Reading Keywords Brief_I/O Detailed_Input | Detailed_Output Parameters Exceptions Files Particulars Examples | Restrictions Literature_References Author_and_Institution Version Index_Entries
#### Procedure
       void lparse_c ( ConstSpiceChar   * list,
                       ConstSpiceChar   * delim,
                       SpiceInt           nmax,
                       SpiceInt           lenout,
                       SpiceInt         * n,
                       void             * items   )
#### Abstract
        Parse a list of items delimited by a single character.
#### Required_Reading
       None.
#### Keywords
        CHARACTER,  LIST,  PARSING,  STRING
#### Brief_I/O
        VARIABLE  I/O  DESCRIPTION
        --------  ---  --------------------------------------------------
        list       I    List of items delimited by delim.
        delim      I    Single character used to delimit items.
        nmax       I    Maximum number of items to return.
        lenout     I    Length of strings in item array.
        n          O    Number of items in the list.
        items      O    Items in the list, left justified.
#### Detailed_Input
        list        is a string containing a list of items delimited by the
                    single character delim. Consecutive delimiters, and
                    delimiters at the beginning and end of the list, are
                    considered to delimit empty items. A blank or empty
                    list is considered to contain a single (empty) item.

        delim       is the character delimiting the items in the list.
                    This may be any ASCII character, including a blank.
                    However, by definition, consecutive blanks are NOT
                    considered to be consecutive delimiters. In addition,
                    leading and trailing blanks are ignored.

        nmax        is the maximum number of items to be returned from
                    the list. This allows the user to guard against
                    overflow from a list containing more items than
                    expected.

        lenout      is the declared length of the strings in the string
                    array items.  This length must include room for the
                    terminating null character in each string.
#### Detailed_Output
        n           is the number of items in the list. n may be
                    any number between one and nmax. n is always the
                    number of delimiters plus one.

        items       is an array of strings containing the items in the list,
                    left justified. Any item in the list to long to fit into
                    an element of items is truncated on the right.  Empty
                    (null) or blank items in the input string are mapped to
                    empty strings on output.

                    items should be declared by the caller as:

                       SpiceCharitem [nmax][lenout]
#### Parameters
       None.
#### Exceptions
       1)  If nmax is less than one, then n will be set to zero, and no
           items will be returned.  This case is not an error.  The other
           exceptional cases can occur only if nmax > 0.

       2)  The error SPICE(NULLPOINTER) is signaled if either the input or
           output string pointer is null.

       3)  If the output string length lenout is less than one, the error
           SPICE(STRINGTOOSHORT) will be signaled.

       4)  An empty input string will result in a single, empty output
           token.  This case is not an error.
#### Files
       None.
#### Particulars
       None.
#### Examples
       The following examples illustrate the operation of lparse_c.

       1) Let
                LIST  = "  A number of words   separated   by spaces   "
                DELIM = " "
                nmax  = 20

          Then
                ITEMS[0] = "A"
                ITEMS[1] = "number"
                ITEMS[2] = "of"
                ITEMS[3] = "words"
                ITEMS[4] = "separated"
                ITEMS[5] = "by"
                ITEMS[6] = "spaces"

       2) Let
                LIST  = "//option1//option2/ //"
                DELIM = "/"
                nmax  = 20

          Then
                ITEMS[0] = ""
                ITEMS[1] = ""
                ITEMS[2] = "option1"
                ITEMS[3] = ""
                ITEMS[4] = "option2"
                ITEMS[5] = ""
                ITEMS[6] = ""
                ITEMS[7] = ""

       3) Let
                LIST  = " ,bob,   carol,, ted,  alice"
                DELIM = ","
                nmax  = 4

          Then
                ITEMS[0] = ""
                ITEMS[1] = "bob"
                ITEMS[2] = "carol"
                ITEMS[3] = ""
#### Restrictions
       None.
#### Literature_References
       None.
#### Author_and_Institution
       N.J. Bachman    (JPL)
       H.A. Neilan     (JPL)
       I.M. Underwood  (JPL)
#### Version
       -CSPICE Version 2.2.0, 18-MAY-2001 (WLT)

          Added a cast to (char *) in the call to  F2C_ConvertTrStrArr

       -CSPICE Version 2.1.0, 20-APR-2000 (NJB)

          Bug fix:  set n to zero for nmax < 1.

       -CSPICE Version 2.0.0, 25-MAR-2000 (NJB)

          Updated header to accurately describe treatment of null tokens.
          Updated code to handle the case of an empty input string or
          nmax < 1.

          Changed typedef SpiceVoid to void.

       -CSPICE Version 1.0.0, 09-FEB-1998 (NJB)
#### Index_Entries
       parse items from a list
#### Link to routine lparse_c source file lparse_c.c

    Thu Apr 16 08:58:29 2009