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.

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

本站文档由 北京智网畅联科技有限公司 整理、翻译并提供 · Documentation compiled and provided by Beijing ZNetLink Technology Co., Ltd.

交流群 · QQ Group:OPNET/智网妙算网络仿真交流群(群号 486383494)

原文档 © 2017 Riverbed Technology · 本站为公益翻译,由 AI 辅助完成,请仔细甄别

Original documentation © 2017 Riverbed Technology. Community translation, AI-assisted. Contact: jiazequn@znetlink.com