Index of Functions: A B C D E F G H I J K L M N O P Q R S T U V W X
Index Page lxqstr_c

Table of contents

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

       lxqstr_c ( Lex quoted string )

       void lxqstr_c ( ConstSpiceChar    * string,
                       SpiceChar           qchar,
                       SpiceInt            first,
                       SpiceInt          * last,
                       SpiceInt          * nchar  )

#### Abstract

       Scan (lex) 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 0 or greater than
           strlen(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 `string' input string pointer is null, the error
           SPICE(NULLPOINTER) is 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)
       J. Diaz del Rio     (ODC Space)

#### Version

       -CSPICE Version 1.0.1, 04-AUG-2021 (JDR)

           Edited the header to comply with NAIF standard.

       -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

    Fri Dec 31 18:41:09 2021