prg_str_decomp()
Abstract
Decomposes a source string consisting of character-separated fields into a list of strings.
Syntax
prg_str_decomp (string, separators)
| 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. |
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*, as shown in the Example section. 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 */
field_list_ptr = prg_str_decomp (prg_list_access (table_list_ptr, i), ":");
/* 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 dynamically allocates the returned field list and its contents, without affecting the passed arguments. Thus the field list can be manipulated as required by the needs of the invoking process. After the list has served its purpose, its contents should be deallocated via prg_list_free(), and the list should be deallocated via prg_mem_free(), so that its memory can be recycled for other uses.
Fields contained within the source string can contain white space characters (i.e., spaces or tabs), and any other characters, except for the separator characters, which delimit fields. However, leading white space in the first field is removed, allowing the whole cluster of fields to be horizontally offset in the source string, without affecting the field contents. As the field list is being prepared, any fields which consist exclusively of whitespace characters are not included. Thus, if the source string consists of ten fields (#0 – #9), and if field #4 is all whitespace, the returned list will consist of nine strings: fields #0 through #3, and fields #5 through #9.
Any characters inside a set of single- or double-quotes are kept in the same field, even if a delimiter is inside the set of quotes. In the delimited string, if an unmatched single quote (') or double quote(") is encountered, the rest of the string is inserted into the field-list as one field.
To change the way strings are handled during extraction (for example, to keep leading whitespace or allow unmatched quotes), use prg_str_decomp_with_options().
Purpose
Provides a mechanism to extract multiple fields from a source string. 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() (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_with_options()to decompose a source string with additional control over string extraction - 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