Functions | |
HC_BOOLEAN | Parse_String (const char *string, const char *delimiter, int offset, char *token) |
HC_BOOLEAN Parse_String | ( | const char * | string, |
const char * | delimiter, | ||
int | offset, | ||
char * | token | ||
) |
A utility routine for extracting delimited strings from longer strings.
string | - delimiters. |
delimiter | - A single character that separates the tokens within string. Note that this parameter is passed as a string which happens to be one character long. |
offset | - The position of the token to be returned within string. A positive count is the position from the beginning of string, 0 being the left most. A negative count is the position from the end, -1 being the right most. |
token | - The token taken from string in the position specified by offset. Leading and trailing blanks are trimmed. Returned to user. Passed by reference always. |
Parse_String() takes a text string that is to be divided into tokens (regions) by delimiter. It extracts the token found in the region indicated by offset.
Parse_String() can be used to break up pathnames, object type lists (returned by Show routines) or any analogous list of items. To parse the return value of Show_Driver_Options() , for example, you might use Parse_String() with a comma (",") delimiter to find each item, then within each item you could use a "=" delimiter to separate the type from the value (if there is a value). Once you know the type and the value, you can use a language dependent routine such as "sscanf" in C to convert the string value to an integer or a float.
Other examples include
Parse_String ("markers = red", "=", 1, token)
which sets token to "red" and returns true,
Parse_String ("?picture/bolt/head/notch", "/", -1, token)
which sets token to "notch" and also returns true, and
Parse_String ("lines, no windows, no edges", ",", 4, token)
which returns false.
An empty string counts as a token, for example:
Parse_String ("", "/", 0, token)
sets token to "" and returns true, and
Parse_String (",,hello", ",", 2, token)
sets token to "hello" and returns true.
Parse_String() is intended to facilitate the parsing of HOOPS segment and attribute specifications. This means that a delimiter that occurs inside of parentheses or any type of quote (",', or `) is not counted as a delimiter. For example, each of the following strings consist of one token only:
(segment a/segment b/segment c)
"input/output"
even when the delimiter is set to "/". If you do want to pursue parsing once you've arrived at such a string, just nibble off the quotes or parentheses, then call Parse_String() again.