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 
 
Wed Apr  5 17:54:38 2017