Package Overview

The String package supports the manipulation of strings and their memory allocations.

As described in the GDF package, there is sometimes a requirement to read and parse tabular information from files. The function prg_gdf_read() supports the process of reading an ASCII GDF and storing it in a list of strings. Typically, these file lines, which represent rows of a table, must be parsed into fields. The Str package functions prg_str_decomp() and prg_str_decomp_with_options() support the decomposition of strings into lists of fields. List items are separated by a defined character; you can use prg_string_list_separator_char_get() to discover what that character is. You can determine if a string contains the list separator with prg_string_contains_list_separator().

The function prg_string_copy() allocates memory for a copy of a string, then performs the copy. The function prg_string_const() returns a constant string. The function prg_string_free() frees the memory allocated to a string.

You can search in a string for a specified regular expression with the function prg_string_regexp_match().

You can compare two strings, with or without considering case, using prg_string_order() and prg_string_order_case_insensitive(), respectively.

You can convert string representations of double and integer values to the corresponding double or int with prg_string_to_double() and prg_string_to_integer().

Several functions provide a means of nicely formatting numerical values when represented as strings—prg_string_double_format(), prg_string_int64_format(), and prg_string_uint64_format(). When numbers are formatted, the decimal point and thousands separator characters are determined by the program’s locale setting. You can use prg_string_decimal_point_char_get() and prg_string_thousands_separator_char_get() to discover what these characters are.

You can change the decimal point and thousands separator characters in a formatted string with prg_string_double_localize() and prg_string_double_unlocalize(). Also, you can change what units a double is expressed in with prg_string_double_unit_convert().

You can determine the current locale with prg_string_locale_get(), change to a new locale with prg_string_locale_begin(), and switch back to the original locale with prg_string_locale_end(). You can switch to a known safe locale and back with prg_string_posix_locale_begin() and prg_string_posix_locale_end().

Additional formatting can be done using format states. prg_string_format_state_create() creates a format state containing format information for numbers of a particular size. prg_string_format_state_update() updates a format state to handle differently sized numbers. prg_string_format_state_format() returns a string representation of a number, formatted according to a specified format state. prg_string_format_state_destroy() destroys a format state.