Reference¶

Headers¶

Unless otherwise stated, all the functions in this reference section are defined in “str.h”.

#include <c-craft/str.h>

Mutability¶

String functions that modify are classed as mutating functions. In this library no function changes the original string. Instead, a new modified string is created. This class of functions takes a memory scope MEM_SCOPE as the first argument and uses that scope to allocate space for the modified string.

Non-mutating String Functions¶

int str_cmp(const char *s1, const char *s2)¶

Return the comparison of two strings.

Parameters:

s1 – The first string to compare.
s2 – The other string to compare.

Returns:

Zero if the strings match, or non-zero if they don’t.

int str_contains_c(const char *text, char c)¶

Test if one string contains another character.

Parameters:

text – The string to search.
c – The character to find.

Returns:

TRUE if the character is found, or FALSE if not.

int str_contains_r(const char *text, const char *regex)¶

Test if one string contains another string matching a regular expression.

Parameters:

text – The string to search.
regex – The regular expression to match.

Returns:

TRUE if a match is found, or FALSE if not.

int str_contains_ri(const char *text, const char *regex)¶

Test if one string contains another string matching a case-insensitive regular expression.

Parameters:

text – The string to search.
regex – The regular expression to match.

Returns:

TRUE if a match is found, or FALSE if not.

int str_contains_s(const char *text, const char *str)¶

Test if one string contains another string.

Remark

The match is case sensitive.

Parameters:

text – The string to search.
str – The string to find.

Returns:

TRUE if the string is found, or FALSE if not.

int str_contains_w(const char *text, const char *word)¶

Test if one string contains another word.

Parameters:

text – The string to search.
word – The word to find.

Returns:

TRUE if the word is found, or FALSE if not.

int str_empty(const char *str)¶

Return if the string should be considered empty.

Parameters:: str – The string to test.
Returns:: TRUE if the string is NULL or an empty string, FALSE otherwise.

const char *str_find_c(const char *text, char c)¶

Find a character within a string.

Parameters:

text – The string to search.
c – The character to search for.

Returns:

The address of the character if found, or NULL if not.

const char *str_find_r(const char *text, const char *regex)¶

Find a substring within a string by regular expression.

Parameters:

text – The string to search.
regex – The regular expression to search for.

Returns:

The address of the substring if found, or NULL if not.

const char *str_find_ri(const char *text, const char *regex)¶

Find a substring within a string by case-insensitive regular expression.

Remark

Matches are case-insensitive.

Parameters:

text – The string to search.
regex – The regular expression to search for.

Returns:

The address of the substring if found, or NULL if not.

const char *str_find_s(const char *text, const char *substr)¶

Find a substring within a string.

Parameters:

text – The string to search.
substr – The string to search for.

Returns:

The address of the substring if found, or NULL if not.

const char *str_find_w(const char *text, const char *word)¶

Find a word within a string.

Parameters:

text – The string to search.
word – The word to search for

Returns:

The address of the word if found, or NULL if not.

int str_count_c(const char *text, char c)¶

Count the occurrences of a character.

Remark

A word is delimited by any character determined by the C standard library functions ispunct() or isspace().

Parameters:

text – The string to search.
c – The character to count.

Returns:

The count of occurrences of the character.

int str_count_r(const char *text, const char *regex)¶

Count the occurrences of a regular expression match.

Parameters:

text – The string to search.
regex – The regular expression to match.

Returns:

The count of matches found.

int str_count_ri(const char *text, const char *regex)¶

Count the occurrences of a case-insensitive regular expression match.

Parameters:

text – The string to search.
regex – The regular expression to match.

Returns:

The count of matches found for the expression.

int str_count_s(const char *text, const char *str)¶

Count the occurrences of a string.

Remark

Matches are case sensitive.

Parameters:

text – The string to search.
str – The string to find.

Returns:

TRUE if the string is found, or FALSE if not.

int str_count_w(const char *text, const char *word)¶

Count the occurrences of a word.

Remark

A word is delimited by any character determined by the C standard library functions ispunct() or isspace().

Parameters:

text – The string to search.
word – The word to find.

Returns:

The count of occurrences of the word.

int str_icmp(const char *s1, const char *s2)¶

Return the case-insensitive comparison of two strings.

Remark

The comparison is case-insensitive.

A word is delimited by any character determined by the C standard library functions ispunct() or isspace().

Parameters:

s1 – The first string to compare.
s2 – The other string to compare.

Returns:

Zero if the strings match, or non-zero if they don’t.

int str_in_array(const char *item, const char **list)¶

Test if an item is included in an array.

Remark

Matches are case sensitive.

Parameters:

item – The item.
list – The null terminated array to check for inclusion in.

Returns:

TRUE if the item is in the array, or FALSE if not.

int str_in_array_i(const char *item, const char **list)¶

Test if an item is included in an array.

Remark

Matches are case-insensitive.

Parameters:

item – The item.
list – The null terminated array to check for inclusion in.

Returns:

TRUE if the item is in the array, or FALSE if not.

int str_len(const char *text)¶

Return the length of a string.

Parameters:: text – The string to find length of.
Returns:: The number of characters in the string.

int str_matches(const char *text, const char *regex)¶

Test if the string matches a regular expression.

Parameters:

text – The string to test.
regex – The regular expression to match.

Returns:

TRUE if the expression matches, or FALSE if not.

int str_matches_i(const char *text, const char *regex)¶

Test if the string matches a regular expression case-insensitively.

Parameters:

text – The string to test.
regex – The regular expression to match.

Returns:

TRUE if the expression matches, or FALSE if not.

int str_subset_of(const char **subset, const char **array)¶

Test if the first string array is a subset of the second.

Remark

The comparison is case sensitive.

Parameters:

subset – The subset array.
array – The array to test if a subset of.

Returns:

TRUE if the first NULL terminated array is a subset of the second, or FALSE if not.

int str_subset_of_i(const char **subset, const char **array)¶

Test if the first string array is a subset of the second.

Remark

The comparison is case-insensitive.

Parameters:

subset – The subset array.
array – The array to test if a subset of.

Returns:

TRUE if the first NULL terminated array is a subset of the second, or FALSE if not.

unsigned int str_hash(const void *key)¶

Generate a hash value from a string.

Remark

A hash value is always the same for a string, but different strings may hash to the same value.

Parameters:: key – The string to be hashed.
Returns:: The hash value for the given string.

Mutating String Functions¶

char *str_caps(MEM_SCOPE mem, const char *text)¶

Capitalise all words in a string.

Parameters:

mem – A memory scope to own the returned string.
text – The string to capitalise.

Returns:

A new string, with all words capitalised.

char *str_copy(MEM_SCOPE mem, const char *str)¶

Copy a string.

Parameters:

mem – A memory scope to own the returned string.
str – The string to copy.

Returns:

A copy of the string.

char *str_copyfrom_c(MEM_SCOPE mem, const char *text, char c)¶

Copy from a specific point in a string.

Parameters:

mem – A memory scope to own the returned string.
text – The string to copy.
c – The character to copy from.

Returns:

A copy of the string starting from the specified point.

char *str_copyfrom_r(MEM_SCOPE mem, const char *text, const char *regex)¶

Copy from a specific point in a string.

Parameters:

mem – A memory scope to own the returned string.
text – The string to copy.
regex – The regular expression to copy from.

Returns:

A copy of the string starting from the specified point.

char *str_copyfrom_ri(MEM_SCOPE mem, const char *text, const char *regex)¶

Copy from a specific point in a string.

Remark

The regular expression is matched case-insensitively.

Parameters:

mem – A memory scope to own the returned string.
text – The string to copy.
regex – The regular expression to copy from.

Returns:

A copy of the string starting from the specified point.

char *str_copyfrom_s(MEM_SCOPE mem, const char *text, const char *str)¶

Copy from a specific point in a string.

Parameters:

mem – A memory scope to own the returned string.
text – The string to copy.
str – The substring to copy from.

Returns:

A copy of the string starting from the specified point.

char *str_copyfrom_w(MEM_SCOPE mem, const char *text, const char *word)¶

Copy from a specific point in a string.

Remark

A word is delimited by any character determined by the C standard library functions ispunct() or isspace().

Parameters:

mem – A memory scope to own the returned string.
text – The string to copy.
word – The word to copy from.

Returns:

A copy of the string starting from the specified point..

char *str_copyto_c(MEM_SCOPE mem, const char *text, char c)¶

Copy to a specific point in a string.

Remark

The value specified to copy up to is not included in the copy.

Parameters:

mem – A memory scope to own the returned string.
text – The string to copy.
c – The character to copy to.

Returns:

A copy of the string ending at the specified point.

char *str_copyto_r(MEM_SCOPE mem, const char *text, const char *regex)¶

Copy to a specific point in a string.

Remark

The value specified to copy up to is not included in the copy.

Parameters:

mem – A memory scope to own the returned string.
text – The string to copy.
regex – The regular expression to copy to.

Returns:

A copy of the string ending at the specified point.

char *str_copyto_ri(MEM_SCOPE mem, const char *text, const char *regex)¶

Copy to a specific point in a string.

Remark

The value specified to copy up to is not included in the copy.

The regular expression is matched case-insensitively.

Parameters:

mem – A memory scope to own the returned string.
text – The string to copy.
regex – The regular expression to copy to.

Returns:

A copy of the string ending at the specified point.

char *str_copyto_s(MEM_SCOPE mem, const char *text, const char *str)¶

Copy to a specific point in a string.

Remark

The value specified to copy up to is not included in the copy.

Parameters:

mem – A memory scope to own the returned string.
text – The string to copy.
str – The substring to copy to.

Returns:

A copy of the string ending at the specified point.

char *str_copyto_w(MEM_SCOPE mem, const char *text, const char *word)¶

Copy to a specific point in a string.

Remark

The word specified to copy up to is not included in the copy.

A word is delimited by any character determined by the C standard library functions ispunct() or isspace().

Parameters:

mem – A memory scope to own the returned string.
text – The string to copy.
word – The word to copy to.

Returns:

A copy of the string ending at the specified point.

char *str_extract(MEM_SCOPE mem, const char *text, const char *regex)¶

Extract text using a chained regular expression.

Remark

A chained regular expression is an array of expressions applied to a piece of text that each operates on the result of the previous expression. The use case for this is where text may be identified contextually. For example, consider this text:

‘I want to get (this text) but not this’

‘(this text)’ may be extracted using ‘([A-Za-z ]+)’. However, the real requirement is to remove the surrounding brackets. To do that we would use ‘[A-Za-z ]+’ on the result. Thus, a chained regular expression to do the whole thing in one go would be both expressions concatenated with a newline separator (a direct example of which cannot be given here because of a Doxygen/CLion limitation, always interpreting the newline escape as a real newline!).

Often an expression is repeated in the following chain. In that case the special ‘@’ symbol can be used to avoid the repeat. EG: ‘(@)’ chained with ‘[A-Za-z ]+’.

Additionally, if an expression starts with ‘!’, not operator, then everything except the matched value is passed to the next expression in the chain.

Parameters:

mem – A memory scope to own the returned string.
text – The text to search.
regex – A chained regular expression defining the extraction.

Returns:

The extracted string, possibly empty, if nothing matches.

char *str_extract_i(MEM_SCOPE mem, const char *text, const char *regex)¶

Extract text using a case-insensitive chained regular expression.

Remark

Chained regular expressions are explained under str_extract().

See also

str_extract().

Parameters:

mem – A memory scope to own the returned string.
text – The text to search.
regex – A chained regular expression defining the extraction.

Returns:

The extracted string, possibly empty, if nothing matches.

char *str_join(MEM_SCOPE mem, const char *items[])¶

Join the NULL terminated string array and return a single joined string.

Parameters:

mem – A memory scope to own the returned string.
items – A NULL terminated array of char * values to join.

Returns:

A new string that is all the items joined.

char *str_join_s(MEM_SCOPE mem, const char *const items[], const char *delim)¶

Join the NULL terminated string array separated by delimiter returning a single joined string.

Parameters:

mem – A memory scope to own the returned string.
items – A NULL terminated array of char * values to join.
delim – The delimiter to insert between each item.

Returns:

A new string that is all the parts joined separated by the delimiter.

Example

char *items[] = { "One", "two", "three" };
char *result = str_join_s(mem, items, ARRAYLEN(items), ", ");
/* result contains "One, two, three" */

char *str_lower(MEM_SCOPE mem, const char *text)¶

Lower case all characters in a string.

Parameters:

mem – A memory scope to own the returned string.
text – The string to convert to lower case.

Returns:

A new string, with all characters converted to lower case.

char *str_replace_c(MEM_SCOPE mem, const char *text, char c, const char *rep, int occurrences)¶

Replace occurrences in a string.

Remark

If the ‘occurrences’ argument is zero all occurrences are replaced.

If the ‘occurrences’ argument is positive then the first found ‘occurrences’ are replaced.

If the ‘occurrences’ argument is negative then ‘occurrences’ are replaced working from the end of the string.

Parameters:

mem – A memory scope to own the returned string.
text – The string to replace occurrences in.
c – A character to replace.
rep – The replacement string.
occurrences – How many occurrences to replace. Zero means all, negative means from the end.

Returns:

A copy of the string with replaced occurrences.

char *str_replace_r(MEM_SCOPE mem, const char *text, const char *regex, const char *rep, int occurrences)¶

Replace occurrences in a string.

Remark

If the ‘occurrences’ argument is zero all occurrences are replaced.

If the ‘occurrences’ argument is positive then the first found ‘occurrences’ are replaced.

If the ‘occurrences’ argument is negative then ‘occurrences’ are replaced working from the end of the string.

Parameters:

mem – A memory scope to own the returned string.
text – The string to replace occurrences in.
regex – A regular expresion match to replace.
rep – The replacement string.
occurrences – How many occurrences to replace. Zero means all, negative means from the end.

Returns:

A copy of the string with replaced occurrences.

char *str_replace_ri(MEM_SCOPE mem, const char *text, const char *regex, const char *rep, int occurrences)¶

Replace occurrences in a string.

Remark

If the ‘occurrences’ argument is zero all occurrences are replaced.

If the ‘occurrences’ argument is positive then the first found ‘occurrences’ are replaced.

If the ‘occurrences’ argument is negative then ‘occurrences’ are replaced working from the end of the string.

Parameters:

mem – A memory scope to own the returned string.
text – The string to replace occurrences in.
regex – A case-insensitive regular expresion match to replace.
rep – The replacement string.
occurrences – How many occurrences to replace. Zero means all, negative means from the end.

Returns:

A copy of the string with replaced occurrences.

char *str_replace_s(MEM_SCOPE mem, const char *text, const char *str, const char *rep, int occurrences)¶

Replace occurrences in a string.

Remark

If the ‘occurrences’ argument is zero all occurrences are replaced.

If the ‘occurrences’ argument is positive then the first found ‘occurrences’ are replaced.

If the ‘occurrences’ argument is negative then ‘occurrences’ are replaced working from the end of the string.

Parameters:

mem – A memory scope to own the returned string.
text – The string to replace occurrences in.
str – A character string to replace.
rep – The replacement string.
occurrences – How many occurrences to replace. Zero means all, negative means from the end.

Returns:

A copy of the string with replaced occurrences.

char *str_replace_w(MEM_SCOPE mem, const char *text, const char *word, const char *rep, int occurrences)¶

Replace occurrences in a string.

Remark

If the ‘occurrences’ argument is zero all occurrences are replaced.

If the ‘occurrences’ argument is positive then the first found ‘occurrences’ are replaced.

If the ‘occurrences’ argument is negative then ‘occurrences’ are replaced working from the end of the string.

A word is delimited by any character determined by the C standard library functions ispunct() or isspace().

Parameters:

mem – A memory scope to own the returned string.
text – The string to replace occurrences in.
word – A word to replace.
rep – The replacement string.
occurrences – How many occurrences to replace. Zero means all, negative means from the end.

Returns:

A copy of the string with replaced occurrences.

char **str_split_c(MEM_SCOPE mem, const char *text, char c)¶

Split a string by a given delimiter.

Remark

The delimiter text is not included in the result.

Parameters:

mem – A memory scope to own the returned string.
text – The text to split
c – A character to split by.

Returns:

A NULL terminated char * array of split strings.

char **str_split_r(MEM_SCOPE mem, const char *text, const char *regex)¶

Split a string by a given delimiter.

Remark

The delimiter text is not included in the result.

Parameters:

mem – A memory scope to own the returned string.
text – The text to split
regex – A regular expression match to split by.

Returns:

A NULL terminated char * array of split strings.

char **str_split_ri(MEM_SCOPE mem, const char *text, const char *regex)¶

Split a string by a given delimiter.

Remark

The delimiter text is not included in the result.

Parameters:

mem – A memory scope to own the returned string.
text – The text to split
regex – A case-insensitive regular expression match to split by.

Returns:

A NULL terminated char * array of split strings.

char **str_split_s(MEM_SCOPE mem, const char *text, const char *str)¶

Split a string by a given delimiter.

Remark

The delimiter text is not included in the result.

Parameters:

mem – A memory scope to own the returned string.
text – The text to split
str – A character string to split by.

Returns:

A NULL terminated char * array of split strings.

char *str_substr(MEM_SCOPE mem, const char *text, int offset, int len)¶

Extract a substring from within a string.

Parameters:

mem – A memory scope to own the returned string.
text – The string to extract a substring from.
offset – The point to start from.
len – The length to extract.

Returns:

A pointer to the new string.

char *str_trim(MEM_SCOPE mem, const char *text)¶

Trim whitespace form either end of a string.

Parameters:

mem – A memory scope to own the returned string.
text – The string to trim.

Returns:

A new string, trimmed at either end.

char *str_upper(MEM_SCOPE mem, const char *text)¶

Upper case all characters in a string.

Parameters:

mem – A memory scope to own the returned string.
text – The string to convert to upper case.

Returns:

A new string, with all characters converted to upper case.

Conversion Functions¶

This class of functions convert different types to and from strings.

char *str_from_int(MEM_SCOPE mem, int value)¶

Convert an integer to string.

Parameters:

mem – A memory scope to own the returned string.
value – The value to convert.

Returns:

A pointer to a null terminated string representation of the value.

char *str_from_long(MEM_SCOPE mem, long value)¶

Convert a long integer to string.

Parameters:

mem – A memory scope to own the returned string.
value – The value to convert.

Returns:

A pointer to a null terminated string representation of the value.

char *str_from_uint(MEM_SCOPE mem, unsigned int value)¶

Convert a unsigned integer to string.

Parameters:

mem – A memory scope to own the returned string.
value – The value to convert.

Returns:

A pointer to a null terminated string representation of the value.

char *str_from_ulong(MEM_SCOPE mem, unsigned long value)¶

Convert a unsigned long integer to string.

Parameters:

mem – A memory scope to own the returned string.
value – The value to convert.

Returns:

A pointer to a null terminated string representation of the value.

char *str_from_float(MEM_SCOPE mem, float value)¶

Convert a floating point value to string.

Parameters:

mem – A memory scope to own the returned string.
value – The value to convert.

Returns:

A pointer to a null terminated string representation of the value.

char *str_from_double(MEM_SCOPE mem, double value)¶

Convert a double precision floating point value to string.

Parameters:

mem – A memory scope to own the returned string.
value – The value to convert.

Returns:

A pointer to a null terminated string representation of the value.

char *str_from_date(MEM_SCOPE mem, time_t t, int utc, const char *format)¶

Convert a date to string.

Remark

A value of SIZE_MAX for t indicates a NULL date, and will result in NULL being returned.

If the format string is NULL the format is ISO standard, IE for example ‘2012-03-11 23:13:37’. See strftime(3) for time format patterns.

a: The abbreviated weekday name according to the current locale.

A: The full weekday name according to the current locale.

b: The abbreviated month name according to the current locale.

B: The full month name according to the current locale.

c: The preferred date and time representation for the current locale.

C: The century number (year/100) as a 2-digit integer. (SU)

d: The day of the month as a decimal number (range 01 to 31).

D: Equivalent to m/d/y. (Yecch—for Americans only. Americans should note that in othercountries d/m/y is rather common. This means that in international context this format is ambiguous and should not be used.) (SU)

e: Like d, the day of the month as a decimal number, but a leading zero is replaced by a space. (SU)

E: Modifier: use alternative format, see below. (SU)

F: Equivalent to Y-m-d (the ISO 8601 date format). (C99)

G: The ISO 8601 week-based year (see NOTES) with century as a decimal number. The 4-digit year corresponding to the ISO week number (see V). This has the same format and value as Y, except that if the ISO week number belongs to the previous or next year, that year is used instead. (TZ)

g: Like G, but without century, that is, with a 2-digit year (00-99). (TZ)

h: Equivalent to b. (SU)

H: The hour as a decimal number using a 24-hour clock (range 00 to 23).

I: The hour as a decimal number using a 12-hour clock (range 01 to 12).

j: The day of the year as a decimal number (range 001 to 366).

k: The hour (24-hour clock) as a decimal number (range 0 to 23); single digits are preceded by a blank. (See also H.) (TZ)

l: The hour (12-hour clock) as a decimal number (range 1 to 12); single digits are preceded by a blank. (See also I.) (TZ)

m: The month as a decimal number (range 01 to 12).

M: The minute as a decimal number (range 00 to 59).

n: A newline character. (SU)

O: Modifier: use alternative format, see below. (SU)

p: Either “AM” or “PM” according to the given time value, or the corresponding strings for the current locale. Noon is treated as “PM” and midnight as “AM”.

P: Like p but in lowercase: “am” or “pm” or a corresponding string for the current locale. (GNU)

r: The time in a.m. or p.m. notation. In the POSIX locale this is equivalent to I:M:S p. (SU)

R: The time in 24-hour notation (H:M). (SU) For a version including the seconds, see T below.

s: The number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). (TZ)

S: The second as a decimal number (range 00 to 60). (The range is up to 60 to allow for occasional leap seconds.)

t: A tab character. (SU)

T: The time in 24-hour notation (H:M:S). (SU)

u: The day of the week as a decimal, range 1 to 7, Monday being 1. See also w. (SU)

U: The week number of the current year as a decimal number, range 00 to 53, starting with the first Sunday as the first day of week 01. See also V and W.

V: The ISO 8601 week number (see NOTES) of the current year as a decimal number, range 01 to53, where week 1 is the first week that has at least 4 days in the new year. See also # U and W. (SU)

w: The day of the week as a decimal, range 0 to 6, Sunday being 0. See also u.

W: The week number of the current year as a decimal number, range 00 to 53, starting with the first Monday as the first day of week 01.

x: The preferred date representation for the current locale without the time.

X: The preferred time representation for the current locale without the date.

y: The year as a decimal number without a century (range 00 to 99).

Y: The year as a decimal number including the century.

z: The +hhmm or -hhmm numeric timezone (that is, the hour and minute offset from UTC). (SU)

Z: The timezone name or abbreviation.

%+: The date and time in date(1) format. (TZ) (Not supported in glibc2.)

%%: A literal ‘’ character.

Parameters:

mem – A memory scope to own the returned string.
t – The date.
utc – TRUE to maintain UTC and FALSE to convert to local time.
format – An optional format pattern.

Returns:

A pointer to a null terminated string representation of the value.

Format Patterns

%a:

The abbreviated weekday name according to the current locale.

%A:

The full weekday name according to the current locale.

%b:

The abbreviated month name according to the current locale.

%B:

The full month name according to the current locale.

%c:

The preferred date and time representation for the current locale.

%C:

The century number (year/100) as a 2-digit integer. (SU)

%d:

The day of the month as a decimal number (range 01 to 31).

%D:

Equivalent to %m/%d/%y. (Yecch—for Americans only. Americans should note that in other countries %d/%m/%y is rather common. This means that in international context this format is ambiguous and should not be used.) (SU)

%e:

Like %d, the day of the month as a decimal number, but a leading zero is replaced by a space. (SU)

%E:

Modifier: use alternative format, see below. (SU)

%F:

Equivalent to %Y-%m-%d (the ISO 8601 date format). (C99)

%G:

The ISO 8601 week-based year (see NOTES) with century as a decimal number. The 4-digit year corresponding to the ISO week number (see %V). This has the same format and value as %Y, except that if the ISO week number belongs to the previous or next year, that year is used instead. (TZ)

%g:

Like %G, but without century, that is, with a 2-digit year (00-99). (TZ)

%h:

Equivalent to %b. (SU)

%H:

The hour as a decimal number using a 24-hour clock (range 00 to 23).

%I:

The hour as a decimal number using a 12-hour clock (range 01 to 12).

%j:

The day of the year as a decimal number (range 001 to 366).

%k:

The hour (24-hour clock) as a decimal number (range 0 to 23); single digits are preceded by a blank. (See also %H.) (TZ)

%l:

The hour (12-hour clock) as a decimal number (range 1 to 12); single digits are preceded by a blank. (See also %I.) (TZ)

%m:

The month as a decimal number (range 01 to 12).

%M:

The minute as a decimal number (range 00 to 59).

%n:

A newline character. (SU)

%O:

Modifier: use alternative format, see below. (SU)

%p:

Either “AM” or “PM” according to the given time value, or the corresponding strings for the current locale. Noon is treated as “PM” and midnight as “AM”.

%P:

Like %p but in lowercase: “am” or “pm” or a corresponding string for the current locale. (GNU)

%r:

The time in a.m. or p.m. notation. In the POSIX locale this is equivalent to %I:%M:%S %p. (SU)

%R:

The time in 24-hour notation (%H:%M). (SU) For a version including the seconds, see %T below.

%s:

The number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). (TZ)

%S:

The second as a decimal number (range 00 to 60). (The range is up to 60 to allow for occasional leap seconds.)

%t:

A tab character. (SU)

%T:

The time in 24-hour notation (%H:%M:%S). (SU)

%u:

The day of the week as a decimal, range 1 to 7, Monday being 1. See also %w. (SU)

%U:

The week number of the current year as a decimal number, range 00 to 53, starting with the first Sunday as the first day of week 01. See also %V and %W.

%V:

The ISO 8601 week number (see NOTES) of the current year as a decimal number, range 01 to 53, where week 1 is the first week that has at least 4 days in the new year. See also %U and %W. (SU)

%w:

The day of the week as a decimal, range 0 to 6, Sunday being 0. See also %u.

%W:

The week number of the current year as a decimal number, range 00 to 53, starting with the first Monday as the first day of week 01.

%x:

The preferred date representation for the current locale without the time.

%X:

The preferred time representation for the current locale without the date.

%y:

The year as a decimal number without a century (range 00 to 99).

%Y:

The year as a decimal number including the century.

%z:

The +hhmm or -hhmm numeric timezone (that is, the hour and minute offset from UTC). (SU)

%Z:

The timezone name or abbreviation.

%+:

The date and time in date(1) format. (TZ) (Not supported in glibc2.)

%%:

A literal ‘%’ character.

int str_to_int(const char *str, int *ok)¶

Convert a string to an integer.

Remark

The ‘ok’ argument may be NULL, if the status is of no concern. In this case if the value to convert is not valid then a zero value is returned. In the case of overflow the maximum permissible value is returned.

Parameters:

str – The string to convert.
ok – The address of a value to receive the status.

Returns:

An integer value converted from the ‘str’ value.

long str_to_long(const char *str, int *ok)¶

Convert a string to a long integer.

Remark

The ‘ok’ argument may be NULL, if the status is of no concern. In this case if the value to convert is not valid then a zero value is returned. In the case of overflow the maximum permissible value is returned.

Parameters:

str – The string to convert.
ok – The address of a value to receive the status.

Returns:

A long integer value converted from the ‘str’ value.

unsigned int str_to_uint(const char *str, int *ok)¶

Convert a string to an unsigned integer.

Remark

The ‘ok’ argument may be NULL, if the status is of no concern. In this case if the value to convert is not valid then a zero value is returned. In the case of overflow the maximum permissible value is returned.

Parameters:

str – The string to convert.
ok – The address of a value to receive the status.

Returns:

An unsigned integer value converted from the ‘str’ value.

float str_to_float(const char *str, int *ok)¶

Convert a string to a floating point number.

Remark

The ‘ok’ argument may be NULL, if the status is of no concern. In this case if the value to convert is not valid then a zero value is returned. In the case of overflow the maximum permissible value is returned.

Parameters:

str – The string to convert.
ok – The address of a value to receive the status.

Returns:

A floating point number converted from the ‘str’ value.

double str_to_double(const char *str, int *ok)¶

Convert a string to a double precision floating point number.

Remark

The ‘ok’ argument may be NULL, if the status is of no concern. In this case if the value to convert is not valid then a zero value is returned. In the case of overflow the maximum permissible value is returned.

Parameters:

str – The string to convert.
ok – The address of a value to receive the status.

Returns:

A double precision floating point number converted from the ‘str’ value.

time_t str_to_date(const char *str, int utc, int *ok)¶

Convert a string to time_t.

Remark

The ‘str’’ argument may be NULL and will result in time_t SIZE_MAX returned, indicating a NULL date/time.

The ‘ok’ argument may be NULL, if the status is of no concern. In this case if the value to convert is not valid then a zero value is returned. In the case of overflow the maximum permissible value is returned.

Time zones can be confusing. Generally dates and times from users are local, whereas databases will often store as UTC in order to maintain integrity during daylight saving periods. The utc argument is stating whether the date given by str is already utc. The result is always utc, because time_t is a count of seconds since an epoch at UTC and cares not for local conversions.

Parameters:

str – The string to convert formatted as ‘Y-M-D h:m:s’, using 24 hour clock.
utc – TRUE if str is a UTC date/time, FALSE if it is local time.
ok – The address of a value to receive the status.

Returns:

A time_t value converted from the ‘str’ value.

char *str_to_str(MEM_SCOPE mem, const char *str)¶

Copy a string safely.

Remark

If the ‘str’ argument is NULL an empty string is returned rather than NULL.

Parameters:

mem – A memory scope to own the returned string.
str – The string to copy.

Returns:

A pointer to the new copied string.

String Streams¶

String streams are useful for building up a long string from many consituent parts.

STR_STREAM str_screate(MEM_SCOPE mem)¶

Open a STR_STREAM for writing.

Remark

A STR_STREAM uses dynamically allocated memory from ‘open_memstream’. Failure to close a STR_STREAM with str_sclose will result in a memory leak.

Parameters:: mem – A memory scope used to own the resulting string.
Returns:: A STR_STREAM.

Example

#include "sstream.h"

SSTREAM sp = str_str_screate(NULL);

str_sprintf(sp, "Hello %s, you weigh %dlbs.\n", "Frederic", 152);
str_sprintf(sp, "You are %d years old.\n", 42);

char *result = str_str_sclose(sp);  /* Closes all OS resources */

sm_free(result);        /* When done with result */

void str_putc(STR_STREAM sstream, int c)¶

Write a single character to a STR_STREAM.

Parameters:

sstream – The STR_STREAM used to write, obtained from str_screate().
c – The character to write.

char *str_sclose(STR_STREAM sstream)¶

Close a STR_STREAM and recover the streamed content.

Parameters:: sstream – The STR_STREAM used to write, obtained from str_screate().
Returns:: A pointer to the streamed text.

void str_sprintf(STR_STREAM sstream, const char *format, ...)¶

Format and write arguments to a STR_STREAM.

Parameters:

sstream – A previously opened STR_STREAM to write to.
format – A format string, as used by the printf family of standard library functions.
... – Values to format and write to the STR_STREAM.

void str_vprintf(STR_STREAM sstream, const char *format, va_list argp)¶

Format and write arguments to a STR_STREAM.

Remark

This is provided to allow variadic functions that use an underlying STR_STREAM to be developed.

Parameters:

sstream – A previously opened STR_STREAM to write to.
format – A format string, as used by the printf family of standard library functions.
argp – A pointer to variadic arguments on the stack.

Reference¶

Headers¶

Mutability¶

Non-mutating String Functions¶

Mutating String Functions¶

Conversion Functions¶

String Streams¶

C Craft

Navigation

Related Topics