Lex (scan) a quoted string.
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.
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.
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.
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 "
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
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.
N.J. Bachman (JPL)
-CSPICE Version 1.0.0, 19-AUG-2002 (NJB)
scan quoted string token lex quoted string token recognize quoted string token