lparsm_c

Index Page lparsm_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 lparsm_c ( ConstSpiceChar   * list,
                       ConstSpiceChar   * delims,
                       SpiceInt           nmax,
                       SpiceInt           lenout,
                       SpiceInt         * n,
                       void             * items   )
#### Abstract
       Parse a list of items separated by multiple delimiters.
#### Required_Reading
       None.
#### Keywords
       CHARACTER,  LIST,  PARSING,  STRING
#### Brief_I/O
       VARIABLE  I/O  DESCRIPTION
       --------  ---  --------------------------------------------------
       list       I    List of items delimited by delims.
       delims     I    Single characters which 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 list of items delimited by any one of the
                   characters in the string delims. 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.  Leading
                   and trailing blanks in list are ignored.

       delims      contains the individual characters which delimit
                   the items in the list. These may be any ASCII
                   characters, including blanks.

                   However, by definition, consecutive blanks are NOT
                   considered to be consecutive delimiters. Nor are
                   a blank and any other delimiter considered to be
                   consecutive delimiters.

       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.

       items       is an array of strings containing the items in the list,
                   left justified. Any item in the list too 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:

                      SpiceChar items [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 of the input
           string pointers or the output void 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 lparsm_c.

      1) Let

            list   == "  A number of words   separated   by spaces   "
            delims == " "
            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   == " ,bob,   carol,, ted,  alice"
             delims == ","
             nmax   == 4

          Then

             items[0] == ""
             items[1] == "bob"
             items[2] == "carol"
             items[3] == ""

       3) Let

             list   == "  1986-187// 13:15:12.184 "
             delims == " ,/-:"
             nmax   == 20

          Then

             items[0] == "1986"
             items[1] == "187"
             items[2] == ""
             items[3] == "13"
             items[4] == "15"
             items[5] == "12.184"
#### Restrictions
       None.
#### Literature_References
       None.
#### Author_and_Institution
       N.J. Bachman    (JPL)
       I.M. Underwood  (JPL)
#### Version
       -CSPICE Version 1.0.0, 18-AUG-2002 (NJB) (IMU)
#### Index_Entries
       parse a list of items
#### Link to routine lparsm_c source file lparsm_c.c

    Thu Apr 16 08:58:30 2009