op_prg_str_decomp()
Abstract
Decomposes a source string consisting of character-separated fields into a list of strings, each of which is a single field extracted from the source string.
Note: This KP is a macro call included for backward compatibility only. Use prg_str_decomp() in new code.
Syntax
op_prg_str_decomp (src_string, separators)
| Argument | Type | Description |
|---|---|---|
src_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 KP.] |
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
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 List*, as shown in the Example section. A valid list pointer is returned even if there are no field values contained in the list. OPC_NIL is returned if a recoverable error occurs.]
Example
/* open and read in an address/stream translation table file */
table_list_ptr = op_prg_gdf_read ("addr_to_strm");
/* determine how many rows the table contains */
num_rows = op_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 = op_prg_str_decomp (op_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 (op_prg_list_access (field_list_ptr, 0));
trans_tab [i].stream = atoi (op_prg_list_access (field_list_ptr, 1));
/* deallocate the field list contents and list */
op_prg_list_free (field_list_ptr); op_prg_mem_free (field_list_ptr);
}
/* deallocate the table list contents and list */
op_prg_list_free (table_list_ptr); op_prg_mem_free (table_list_ptr);
Details
This KP 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 the KP op_prg_list_free(), and the list should be deallocated via the KP op_prg_mem_free(), so that its memory can be recycled for other uses.
Fields contained within the source string can contain whitespace characters (i.e., spaces or tabs), and any other characters, except for the separator characters, which delimit fields. However, leading whitespace 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.
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 the KP op_prg_gdf_read(), scanned in row-order loop by the KP op_prg_list_access(), and each row string can be decomposed into fields using op_prg_str_decomp() (this technique is illustrated in the Example section to the left).
Errors
- Recoverable Error: Allocation of memory failed.
- Program Abort: Segmentation violation (due to an invalid string pointer, or malformed string).
Reference
- Use the KP op_prg_list_free() to deallocate the contents of a list
- Use the KP op_prg_mem_free() to deallocate a list structure
- Use the KP op_prg_list_access() to obtain a pointer to an element in a list
- Use the KP op_prg_list_remove() to remove an element (and obtain a pointer to it) from a list
- Use the KP op_prg_gdf_read() to read a GDF into a list of strings.