Index Page lxqstr_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 lxqstr_c ( ConstSpiceChar    * string,
                       SpiceChar           qchar,
                       SpiceInt            first,
                       SpiceInt          * last,
                       SpiceInt          * nchar  )
#### Abstract
       Lex (scan) a quoted string.
#### Required_Reading
       None.
#### Keywords
       CHARACTER
       PARSING
       SCANNING
       STRING
       UTILITY
#### Brief_I/O
       Variable  I/O  Description
       --------  ---  --------------------------------------------------
       string     I   String to be scanned.
       qchar      I   Quote delimiter character.
       first      I   Character position at which to start scanning.
       last       O   Character position of end of token.
       nchar      O   Number of characters in token.
#### Detailed_Input
       string         is a character string that may contain a "string
                      token" starting at the character position
                      indicated by the input argument first (see below).
                      String tokens are sequences of characters that
                      represent literal strings.  Syntactically, a string
                      token is a sequence of characters that begins and
                      ends with a designated "quote character".  Within
                      the token, any occurrence of the quote character
                      is indicated by an adjacent pair of quote
                      characters:  for example, if the quote character is

                         "

                      then the token representing one instance of this
                      character is

                         """"

                      Here the first quote indicates the beginning of the
                      token, the next two quotes together indicate a
                      single quote character that constitutes the
                      "contents" of the token, and the final quote
                      indicates the end of the token.

       qchar          is the quote character.  This is always a single
                      character.  The characters

                         "  and '

                      are common choices, but any non-blank character is
                      accepted.  Case *is* significant in qchar.

       first          is the character position at which the routine
                      is to start scanning a quoted string token.  Note
                      that the character string[first] must equal
                      qchar if a string token is to be found; this
                      routine does *not* attempt to locate the first
                      quoted string following the position first.
#### Detailed_Output
       last           is the last character position such that the subtring
                      ranging from string[first] to string[last] is a
                      quoted string token, if such a substring exists.
                      Otherwise, the returned value of last is first-1.

       nchar          is the length of the string token found by this
                      routine, if such a token exists.  This length
                      includes the starting and ending bracketing quotes.
                      If a string token is not found, the returned value
                      of nchar is zero.
#### Parameters
       None.
#### Exceptions
       1) If the input argument first is less than 1 or greater than
          len(string)-1, the returned value of last is first-1, and the
          returned value of nchar is zero.

       2) It is not an error for a quoted string token to consist of
          two consecutive quote characters with no intervening
          characters.  Calling routines that require special treatment
          of null tokens must handle this case.

       3) If the input argument qchar is blank, the returned value of
          last is first-1, and the returned value of nchar is zero.

       4) If the input string pointer is null, the error SPICE(NULLPOINTER)
          will be signaled.

       5) If the input string has length zero, last will be set to first-1
          and nchar will be set to zero.  This case is not considered an
          error.
#### Files
       None.
#### Particulars
       Quote characters may be ANY non-blank character.  For example, the
       ampersand

          &

       is a perfectly valid quote character.  If we were using the
       ampersand as the quote character, then the term "doubled quote"
       in the following discussion would refer to the sequence

          &&

       not the character

          "

       The string tokens identified by this routine are Fortran-style
       quoted strings:  they start and end with quote characters.  In the
       interior of any such token, any quote characters are represented
       by doubled quote characters.  These rules imply that the number of
       quote characters in a quoted string token is always even.  The end
       of a quoted string token is located at the first even-numbered
       quote character, counting from the initial quote character, that
       is  not the first member of a pair of quotes indicating an
       embedded quote character.

       To map the token to the string of characters it represents, use
       the CSPICE subroutine parsqs_c (String parse, quoted).  parsqs_c
       removes the bracketing quotes from a quoted string token and
       converts each doubled quote between the bracketing quotes to a
       single quote.  For example, the token

          """"

       identified by this routine would be mapped by parsqs_c to a string
       variable containing the single character

          "
#### Examples
       1)  The table below illustrates the action of this routine.

           STRING CONTENTS               qchar   first   last   nchar
           ==========================================================
           The "SPICE" system            "       4       10      7
           The "SPICE" system            "       0       -1      0
           The "SPICE" system            '       4        3      0
           The """SPICE"" system"        "       4       12      9
           The """SPICE"""" system       "       4       14     11
           The &&&SPICE system           &       4        5      2
           ' '                           '       0        2      3
           ''                            '       0        1      2
           ==========================================================
           01234567890123456789012
#### Restrictions
       None.
#### Literature_References
       None.
#### Author_and_Institution
       N.J. Bachman       (JPL)
#### Version
       -CSPICE Version 1.0.0, 19-AUG-2002 (NJB)
#### Index_Entries
       scan quoted string token
       lex quoted string token
       recognize quoted string token
#### Link to routine lxqstr_c source file lxqstr_c.c

    Wed Jun  9 13:05:26 2010