prg_str_decomp_with_options()
Abstract
Decomposes a source string consisting of character-separated fields into a list of strings, with optional control over how the strings are processed.
Syntax
prg_str_decomp_with_options (string, separators, options)
| Argument | Type | Description |
|---|---|---|
string |
const char * |
source string to be decomposed into fields [This string should contain a series of fields separated by any of the separator characters listed in the separators argument. The passed string is not affected by this function. |
separators |
const char * |
separator characters which delimit the source string fields [This string should contain a set of characters that serve to delimit the fields of the source string. Typical choices might include the vertical bar (“|”), comma (“,”), period (“.”), or semi-colon (“;”) characters. |
options |
int |
Decomposition options (see Details). |
Return Type
PrgT_List *
Pointer to a list of fields extracted from the source string (i.e., a list of strings). This list pointer is usually directly assigned to a variable declared as a PrgT_List*. A valid list pointer is returned even if there are no field values contained in the list. PRGC_NIL is returned if a recoverable error occurs.
Header
prg_string_funcs.h
Example
/* open and read in an address/stream translation table file */
table_list_ptr = prg_gdf_read ("addr_to_strm");
/* determine how many rows the table contains */
num_rows = prg_list_size (table_list_ptr);
/* loop through the table’s rows */
for (i = 0; i < num_rows; i++)
{
/* obtain a list of the columnar fields in each row */
/* some fields might contain single quotes */
field_list_ptr = prg_str_decomp_with_options (prg_list_access (table_list_ptr, i), ":", PRGC_STR_DECOMP_OPT_IGNORE_QUOTES);
/* extract the values of the two fields, and insert into the table matrix */
trans_tab [i].address = atoi (prg_list_access (field_list_ptr, 0));
trans_tab [i].stream = atoi (prg_list_access (field_list_ptr, 1));
/* deallocate the field list contents and list */
prg_list_free (field_list_ptr);
prg_mem_free (field_list_ptr);
}
/* deallocate the table list contents and list */
prg_list_free (table_list_ptr);
prg_mem_free (table_list_ptr);
Details
This function does the same job as prg_str_decomp(), but with the ability to make optional changes to the returned strings. These changes are specified with the options argument.
options must be either PRGC_STR_DECOMP_OPT_NONE or an OR’ed combination of the following symbolic constants:
- PRGC_STR_DECOMP_OPT_INCLUDE_EMPTY_FIELDS—include null strings for empty fields
- PRGC_STR_DECOMP_OPT_UNIQUE—include only unique strings in the returned list
- PRGC_STR_DECOMP_OPT_UNIQUE_CASE_INSENS—include only unique strings in the returned list, but do not consider case
- PRGC_STR_DECOMP_OPT_IGNORE_QUOTES—ignore single and double quotes when looking for separator characters
- PRGC_STR_DECOMP_OPT_REMOVE_ESCAPES—remove backslashes from a string before putting it in the list
- PRGC_STR_DECOMP_OPT_REMOVE_QUOTES—remove quotes from a string before putting it in the list. (This option implies _REMOVE_ESCAPES and overrides _IGNORE_QUOTES.)
- PRGC_STR_DECOMP_OPT_LEAVE_LEADING_WHITESPACE—leave leading whitespace in strings
Purpose
Provides a mechanism to extract multiple fields from a source string with optional control over how the strings are processed. This is typically useful when processing tabular information in which the source string represents a row of a table and the string’s fields represent the row-column “cells” within the table. The table can be read from a GDF into a list of strings via prg_gdf_read(), scanned in row-order loop by prg_list_access(), and each row string can be decomposed into fields using prg_str_decomp_with_options() (the Example section shows this technique).
Errors
- Recoverable Error: Allocation of memory failed.
- Program Abort: Segmentation violation. (due to an invalid string pointer, or malformed string)
Reference
- use
prg_str_decomp()to decompose a source string using the default string processing (same as the PRGC_STR_DECOMP_OPT_NONE option) - use
prg_list_free()to deallocate the contents of a list - use
prg_mem_free()to deallocate a list structure - use
prg_list_access()to obtain a pointer to an element in a list - use
prg_list_remove()to remove an element (and obtain a pointer to it) from a list - use
prg_gdf_read()to read a GDF into a list of strings