Cross-platform C SDK logo

Cross-platform C SDK

Strings

❮ Back
Next ❯
This page has been automatically translated using the Google Translate API services. We are working on improving texts. Thank you for your understanding and patience.

Character strings in UTF-8, dynamically allocated.


Functions

const char_t*tc (...)
String*str_c (...)
String*str_cn (...)
String*str_trim (...)
String*str_trim_n (...)
String*str_copy (...)
String*str_printf (...)
String*str_path (...)
String*str_cpath (...)
String*str_relpath (...)
String*str_repl (...)
String*str_reserve (...)
String*str_fill (...)
String*str_read (...)
voidstr_write (...)
voidstr_writef (...)
voidstr_copy_c (...)
voidstr_copy_cn (...)
voidstr_cat (...)
voidstr_cat_c (...)
voidstr_upd (...)
voidstr_destroy (...)
voidstr_destopt (...)
uint32_tstr_len (...)
uint32_tstr_len_c (...)
uint32_tstr_nchars (...)
uint32_tstr_prefix (...)
bool_tstr_is_prefix (...)
intstr_scmp (...)
intstr_cmp (...)
intstr_cmp_c (...)
intstr_cmp_cn (...)
bool_tstr_empty (...)
bool_tstr_empty_c (...)
bool_tstr_equ (...)
bool_tstr_equ_c (...)
bool_tstr_equ_cn (...)
bool_tstr_equ_nocase (...)
bool_tstr_equ_end (...)
voidstr_upper (...)
voidstr_lower (...)
voidstr_upper_c (...)
voidstr_lower_c (...)
voidstr_subs (...)
voidstr_repl_c (...)
const char_t*str_str (...)
bool_tstr_split (...)
bool_tstr_split_trim (...)
voidstr_split_pathname (...)
voidstr_split_pathext (...)
const char_t*str_filename (...)
const char_t*str_filext (...)
uint32_tstr_find (...)
int8_tstr_to_i8 (...)
int16_tstr_to_i16 (...)
int32_tstr_to_i32 (...)
int64_tstr_to_i64 (...)
uint8_tstr_to_u8 (...)
uint16_tstr_to_u16 (...)
uint32_tstr_to_u32 (...)
uint64_tstr_to_u64 (...)
real32_tstr_to_r32 (...)
real64_tstr_to_r64 (...)

String objects contain UTF-8 characters strings dynamically allocated. Although it is possible to insert text strings directly into the source code or access them through the resource packages (respack_text), it is usual compose texts at runtime or store volatile data received through some input channel (keyboard, files, network, etc). The module strings.h offers support to work with this type of objects, as well as generic functions for the text manipulation.

There are different ways of composing UTF8 strings, but the two most used constructors are str_c to create a copy of a C string and str_printf to compose a string from several fields, with the well-known format of the printf() function.

1
2
3
4
String *str1 = str_c("This a static char array.");
String *str2 = str_printf("Code: %s, Price %8.2f.", tc(product->code), product->price);
str1 = "This a static char array."
str2 = "Code: 456-34GH-JKL, Price   439.67."

In the case that it is necessary to create more extensive texts from loops or other conditional, the most efficient way is to create a Stream and, later, obtain the String.

1
2
3
4
5
6
7
8
String *str;
Stream *stm = stm_memory(2048);
stm_printf(stm, "List of %d products\n", arrpt_size(products, Product));
arrpt_foreach(product, products, Product);
    stm_printf(stm, "Code: %s, Price %8.2f.\n", tc(product->code), product->price);
arrpt_end();
str = stm_str(stm);
stm_close(&stm);

tc ()

Returns the inner C string in format UTF-8 contained in the String.

const char_t*
tc(const String *str);
str

String object.

Return

Pointer to the C-string.


str_c ()

Create a String from a UTF-8-encoded C string.

String*
str_c(const char_t *str);
str

C UTF8 string ending in null character '\0'.

Return

The String object.


str_cn ()

Create a String by copying the first n bytes of a C string.

String*
str_cn(const char_t *str,
       const uint32_t n);
str

UTF8 C String.

n

The number of bytes to copy.

Return

The String object.

Remarks

In UTF-8 strings, the number of bytes does not correspond to the number of characters.


str_trim ()

Create a String from a C string by cutting the blanks, both at the beginning and at the end.

String*
str_trim(const char_t *str);
str

C UTF8 string ending in null character '\0'.

Return

The String object.


str_trim_n ()

Create a String from the first n bytes of a C string cutting the blanks, both at the beginning and at the end.

String*
str_trim_n(const char_t *str,
           const uint32_t n);
str

UTF8 C string.

n

The number of bytes to consider from the original string. The copy can contain 'n' or fewer bytes, depending on the number of blanks.

Return

The String object.


str_copy ()

Create an exact copy of the String.

String*
str_copy(const String *str);
str

The original String object.

Return

The copy of String object.

Remarks

Strings are a special type of mutable object. Copy involves creating a new object and not increasing a reference counter.


str_printf ()

Compose a String from several fields, using the the printf format.

String*
str_printf(const char_t *format,
           ...);
format

String with the printf-like format with a variable number of parameters.

...

Arguments or variables of the printf.

Return

The String object.

Remarks

The use of this function prevents buffer overflow vulnerabilities, associated with the classic C functions such as strcpy.


str_path ()

Like str_printf, but consider the string to be a pathname and therefore use the convenient separator according platform.

String*
str_path(const platform_t platform,
         const char_t *format,
         ...);
1
2
String *path = str_path(ekWINDOWS, "/%s/img/%s.png", tc(product->category), tc(product->name));
path = "\\camera\\img\\sony_a5000.png"
platform

Platform for which the pathname is created.

format

String with the printf-like format with a variable number of parameters.

...

Arguments or variables of the printf.

Return

The String object.


str_cpath ()

Like str_path, but considering the platform where the program is running.

String*
str_cpath(const char_t *format,
          ...);
1
2
3
String *path = str_cpath("/%s/img/%s.png", tc(product->category), tc(product->name));
path = "\\camera\\img\\sony_a5000.png"  // In Windows
path = "/camera/img/sony_a5000.png"     // In Unix-like
format

String with the printf-like format with a variable number of parameters.

...

Arguments or variables of the printf.

Return

The String object.


str_relpath ()

Calculate the relative path to path1 to get to path2.

String*
str_relpath(const char_t *path1,
            const char_t *path2);
path1

The origin path.

path2

The destination path.

Return

The string object that contains the relative path.


str_repl ()

Create a String by replacing an undetermined number of sub-strings. The first parameter is the original string. The following pairs indicate the sub-string to be searched and the sub-string that should replace it. The last parameter must be 0.

String*
str_repl(const char_t *str,
         ...);
1
2
String *str = str_repl("const Product **pr;", "const", "", "*", "", " ", "", 0);
str = "Productpr;"
str

Original C UTF8 string terminated in null character '\0'.

...

Variable number of parameters, in pairs. The first element of the pair indicates the sub-string to look for in str. The second element replaces it.

Return

The String object.


str_reserve ()

Create a String with n+1 bytes, but without assigning any content.

String*
str_reserve(const uint32_t n);
n

Number of bytes. Reserve space for one more (the '\n').

Return

The String object. Its content will be indeterminate (garbage). It must be written later.


str_fill ()

Create a String by repeating n times the same character.

String*
str_fill(const uint32_t n,
         const char_t c);
n

Number of characters.

c

Pattern character.

Return

The String object.


str_read ()

Create a String by reading its contents from a Stream (de-serialization). String must have been previously written by str_write.

String*
str_read(Stream *stream);
stream

A read stream.

Return

The String object.

Remarks

It is a binary operation. String size is deserialized first.


str_write ()

Write a string in a Streams (serialization).

void
str_write(Stream *stream,
          String *str);
stream

A write stream.

str

The String object.

Remarks

It is a binary operation. The string size is serialized first. Use str_writef to write only the text.


str_writef ()

Write in a Streams the C string contained in the string.

void
str_writef(Stream *stream,
           String *str);
stream

A write stream.

str

The String object.

Remarks

Write only the string text, without the null final character '\0'. It is equivalent to stm_writef(stream, tc(str)); but more efficient, since you don't have to calculate the size of str.


str_copy_c ()

Copy the C string src in the buffer pointed by dest, including the null character '\0'.

void
str_copy_c(char_t *dest,
           const uint32_t size,
           const char_t *str);
dest

Destination Buffer.

size

Size in bytes of dest.

str

UTF8 C string terminated in null character '\0'.

Remarks

It is a safe operation. They will not be written in dest more of size bytes and a character will never be truncated. dest it will always end the null character '\0'.


str_copy_cn ()

Copy in dest a maximum of n bytes of the C UTF8 string pointed by src, including the null character '\0'.

void
str_copy_cn(char_t *dest,
            const uint32_t size,
            const char_t *str,
            const uint32_t n);
dest

Destination Buffer.

size

Size in bytes of dest.

str

UTF8 C string.

n

Maximum number of bytes to copy in dest.

Remarks

It is a safe operation. They will not be written in dest more of n bytes and a character will never be truncated. dest it will always end the null character '\0'.


str_cat ()

Dynamically concatenates the content of src in dest.

void
str_cat(String **dest,
        const char_t *src);
**dest

String object of origin and destination.

src

UTF8 C string to concatenate.

Remarks

This operation involves reallocating dynamic memory. To compose long texts it is more efficient to use Stream.


str_cat_c ()

Concatenate the content of src in dest. The null character in dest will be overwritten by the first character of src.

void
str_cat_c(char_t *dest,
          const uint32_t size,
          const char_t *src);
dest

UTF8 C string origin and destination.

size

Size in bytes of dest.

src

UTF8 C string to concatenate.

Remarks

It is a safe operation. They will not be written in dest more of size bytes and a character will never be truncated. dest it will always end the null character '\0'.


str_upd ()

Change the content of a string to another.

void
str_upd(String **str,
        const char_t *new_str);
1
2
3
4
5
6
// Equivalent code
String *str = ..original content..
String *temp = str_c(new_str);
str_destroy(&str);
str = temp;
temp = NULL;
str

Destination string object. The original content will be deleted.

new_str

UTF8 C string that will replace the original.


str_destroy ()

Destroy a string object.

void
str_destroy(String **str);
str

The string object. Will be set to NULL after destruction.


str_destopt ()

Destroy a string object if its content is not NULL (optional destroyer).

void
str_destopt(String **str);
str

The string object. Will be set to NULL after destruction.


str_len ()

Returns the size in bytes of a string.

uint32_t
str_len(const String *str);
str

The String object.

Return

The number of bytes, not including the null character '\0'.

Remarks

In UTF-8 strings the number of bytes is not the same as the characters. str_nchars.


str_len_c ()

Returns the size in bytes of a UTF8 C string.

uint32_t
str_len_c(const char_t *str);
str

UTF8 C string terminated in null character '\0'.

Return

The number of bytes, not including the null character '\0'.

Remarks

In UTF-8 strings the number of bytes is not the same as the characters. str_nchars.


str_nchars ()

Returns the number of characters of a string object.

uint32_t
str_nchars(const String *str);
str

The String object.

Return

The number of characters, not including the null character '\0'.

Remarks

In UTF-8 strings the number of bytes is not the same as the characters.


str_prefix ()

Locate the common begin of two strings.

uint32_t
str_prefix(const char_t *str1,
           const char_t *str2);
str1

First UTF8 C string terminated in null character '\0'.

str2

Second UTF8 C string terminated in null character '\0'.

Return

The number of bytes that are identical at the beginning of both strings.


str_is_prefix ()

Check if one string is prefix of another.

bool_t
str_is_prefix(const char_t *str,
              const char_t *prefix);
str

UTF8 C string terminated in null character '\0'.

prefix

Prefix of str terminated in null character '\0'.

Return

TRUE if prefix is prefix of str.


str_scmp ()

Compare two strings alphabetically.

int
str_scmp(const String *str1,
         const String *str2);
str1

First string.

str2

Second string.

Return

Comparison result.


str_cmp ()

Compare alphabetically a string with a UTF8 C string.

int
str_cmp(const String *str1,
        const char_t *str2);
str1

String object.

str2

C UTF8 string terminated in null character '\0'.

Return

Comparison result.


str_cmp_c ()

Compare alphabetically two UTF8 C strings terminated in a null character '\0'.

int
str_cmp_c(const char_t *str1,
          const char_t *str2);
str1

First UTF8 C string.

str2

Second UTF8 C string.

Return

Comparison result.


str_cmp_cn ()

Compare alphabetically the first n bytes of two UTF8 C strings terminated in a null character '\0'.

int
str_cmp_cn(const char_t *str1,
           const char_t *str2,
           const uint32_t n);
str1

First UTF8 C string.

str2

Second UTF8 C string.

n

Maximum number of bytes to compare.

Return

Comparison result.

Remarks

It is a safe operation. If either of the two chains reaches the end before reaching n bytes, the comparison ends.


str_empty ()

Check if a string is empty (str->data[0] == '\0').

bool_t
str_empty(const String *str);
str

The String object.

Return

TRUE if it is empty or is NULL.


str_empty_c ()

Check if a UTF8 C string is empty (str[0] == '\0').

bool_t
str_empty_c(const char_t *str);
str

UTF8 C string.

Return

TRUE if it is empty or is NULL.


str_equ ()

Check if the content of a string is equal to a C string.

bool_t
str_equ(const String *str1,
        const char_t *str2);
str1

String object.

str2

UTF8 C string terminated in null character '\0'.

Return

TRUE if they are equals.


str_equ_c ()

Check if two UTF8 C strings are equal.

bool_t
str_equ_c(const char_t *str1,
          const char_t *str2);
str1

First UTF8 C string terminated in null character '\0'.

str2

Second UTF8 C string terminated in null character '\0'.

Return

TRUE if they are equals.


str_equ_cn ()

Check if the first bytes of two UTF8 C strings are equal.

bool_t
str_equ_cn(const char_t *str1,
           const char_t *str2,
           const uint32_t n);
str1

First UTF8 C string terminated in null character '\0'.

str2

Second UTF8 C string terminated in null character '\0'.

n

First 'n' bytes to compare.

Return

TRUE if they are equals.

Remarks

If '\0' is reached in either of the two strings, TRUE will be returned.


str_equ_nocase ()

Check if two UTF8 C strings are equal, ignoring upper or lower case.

bool_t
str_equ_nocase(const char_t *str1,
               const char_t *str2);
str1

First UTF8 C string terminated in null character '\0'.

str2

Second UTF8 C string terminated in null character '\0'.

Return

TRUE if they are equals.

Remarks

Only US-ASCII characters are considered (0-127).


str_equ_end ()

Check the termination of a string.

bool_t
str_equ_end(const char_t *str,
            const char_t *end);
str

UTF8 C string terminated in null character '\0'.

end

UTF8 C string with termination.

Return

TRUE if str ends in end.


str_upper ()

Change lowercase letters to uppercase.

void
str_upper(String *str);
str

The String object.

Remarks

Only US-ASCII characters (0-127) are considered. The original string will change, but not the memory requirements.


str_lower ()

Change uppercase letters to lowercase letters.

void
str_lower(String *str);
str

The String object.

Remarks

Only US-ASCII characters (0-127) are considered. The original string will change, but not the memory requirements.


str_upper_c ()

Convert a string to uppercase.

void
str_upper_c(char_t *dest,
            const uint32_t size,
            const char_t *str);
dest

Destination buffer.

size

Size in bytes of the destination buffer.

str

String C UTF8 terminated in null character '\0'.

Remarks

Only US-ASCII characters are considered (0-127).


str_lower_c ()

Convert a string to lowercase.

void
str_lower_c(char_t *dest,
            const uint32_t size,
            const char_t *str);
dest

Destination buffer.

size

Size in bytes of the destination buffer.

str

String C UTF8 terminated in null character '\0'.

Remarks

Only US-ASCII characters are considered (0-127).


str_subs ()

Change all instances of one character to another.

void
str_subs(String *str,
         const char_t replace,
         const char_t with);
1
2
3
4
String *str = str_c("customer.service.company.com");
str_subs(str, '.', '_');
str_uppercase(str);
str="CUSTOMER_SERVICE_COMPANY_COM"
str

The String object.

replace

Character to replace.

with

Replacement character.

Remarks

Only US-ASCII characters (0-127) are considered. The original string will change, but not the memory requirements.


str_repl_c ()

Change all instances of one substring to another.

void
str_repl_c(String *str,
           const char_t *replace,
           const char_t *with);
str

The String object.

replace

Substring to replace.

with

Replacement substring.

Remarks

The substrings replace and with they must be the same size, otherwise a Asserts will be triggered. Use str_repl for the general case.


str_str ()

Search for a substring within a larger one.

const char_t*
str_str(const char_t *str,
        const char_t *substr);
str

UTF8 C strings terminated in null character '\0'.

substr

Substring to search terminated in null character '\0'.

Return

Pointer to the first occurrence of substr in str or NULL if there is none.


str_split ()

Divide a string into two, using the first occurrence of a substring.

bool_t
str_split(const char_t *str,
          const char_t *substr,
          String **left,
          String **right);
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
const char_t *str = "one::two";
String *str1, *str2, *str3;
bool_t ok1, ok2;
ok1 = str_split(str, "::", &str1, &str2);
ok2 = str_split(tc(str1), "::", NULL, &str3);
str1 = "one"
str2 = "two"
str3 = ""
ok1 = TRUE
ok2 = FALSE
str

UTF8 C string terminated in null character '\0'.

substr

Substring to search.

left

Left substring. It will be equal to str if substr does not exist. The parameter can be NULL if not necessary.

right

Right substring. It will be equal to "" if substr does not exist. The parameter can be NULL if not necessary.

Return

TRUE if substr exists in str.


str_split_trim ()

Like str_split but removing all the blanks at the beginning and end of left and right.

bool_t
str_split_trim(const char_t *str,
               const char_t *substr,
               String **left,
               String **right);
str

UTF8 C string terminated in null character '\0'.

substr

Substring to search.

left

Left substring.

right

Right substring.

Return

TRUE if substr exists in str.


str_split_pathname ()

Divide a pathname into path and file Filename and pathname.

void
str_split_pathname(const char_t *pathname,
                   String **path,
                   String **file);
1
2
3
4
5
6
String *path, *name, *name2;
str_split_pathname("C:\\Users\\john\\Desktop\\image.png", &path, &name);
str_split_pathname(tc(path), NULL, name2);
path = "C:\\Users\\john\\Desktop"
name = "image.png"
name2 = "Desktop"
pathname

Input pathname.

path

Directory path. The parameter can be NULL if not necessary.

file

File name or final directory. The parameter can be NULL if not necessary.


str_split_pathext ()

Like str_split_pathname but also extracting the file extension.

void
str_split_pathext(const char_t *pathname,
                  String **path,
                  String **file,
                  String **ext);
1
2
3
4
5
String *path, *name, *ext;
str_split_pathext("C:\\Users\\john\\Desktop\\image.png", &path, &name, &ext);
path = "C:\\Users\\john\\Desktop"
name = "image"
ext = "png"
pathname

Input pathname.

path

Path part.

file

File part.

ext

File extension.


str_filename ()

Returns the final part of a pathname. Filename and pathname.

const char_t*
str_filename(const char_t *pathname);
1
2
const char_t *name = str_filename("C:\\Users\\john\\Desktop\\image.png");
name = "image.png"
pathname

Input pathname.

Return

The last part of a directory path.


str_filext ()

Returns the file extension, from a pathname. Filename and pathname.

const char_t*
str_filext(const char_t *pathname);
1
2
const char_t *ext = str_fileext("C:\\Users\\john\\Desktop\\image.png");
ext = "png"
pathname

Input pathname.

Return

The file extension.


str_find ()

Search for a string in an array.

uint32_t
str_find(const ArrPt(String) *array,
         const char_t *str);
array

Array.

str

The string to find.

Return

The position of the string or UINT32_MAX if it does not exist.


str_to_i8 ()

Converts a text string into an integer.

int8_t
str_to_i8(const char_t *str,
          const uint32_t base,
          bool_t *error);
str

Text string, ending in null character '\0'.

base

Numeric base: 8 (octal), 10 (decimal), 16 (hexadecimal).

error

Gets TRUE if there is an error in the conversion. Can be NULL.

Return

The numerical value.

Remarks

If the string is wrong or the value is out of range, return 0 with error=TRUE.


str_to_i16 ()

Converts a text string into an integer.

int16_t
str_to_i16(const char_t *str,
           const uint32_t base,
           bool_t *error);
str

Text string, ending in null character '\0'.

base

Numeric base: 8 (octal), 10 (decimal), 16 (hexadecimal).

error

Gets TRUE if there is an error in the conversion. Can be NULL.

Return

The numerical value.

Remarks

If the string is wrong or the value is out of range, return 0 with error=TRUE.


str_to_i32 ()

Converts a text string into an integer.

int32_t
str_to_i32(const char_t *str,
           const uint32_t base,
           bool_t *error);
str

Text string, ending in null character '\0'.

base

Numeric base: 8 (octal), 10 (decimal), 16 (hexadecimal).

error

Gets TRUE if there is an error in the conversion. Can be NULL.

Return

The numerical value.

Remarks

If the string is wrong or the value is out of range, return 0 with error=TRUE.


str_to_i64 ()

Converts a text string into an integer.

int64_t
str_to_i64(const char_t *str,
           const uint32_t base,
           bool_t *error);
str

Text string, ending in null character '\0'.

base

Numeric base: 8 (octal), 10 (decimal), 16 (hexadecimal).

error

Gets TRUE if there is an error in the conversion. Can be NULL.

Return

The numerical value.

Remarks

If the string is wrong or the value is out of range, return 0 with error=TRUE.


str_to_u8 ()

Converts a text string into an integer.

uint8_t
str_to_u8(const char_t *str,
          const uint32_t base,
          bool_t *error);
str

Text string, ending in null character '\0'.

base

Numeric base: 8 (octal), 10 (decimal), 16 (hexadecimal).

error

Gets TRUE if there is an error in the conversion. Can be NULL.

Return

The numerical value.

Remarks

If the string is wrong or the value is out of range, return 0 with error=TRUE.


str_to_u16 ()

Converts a text string into an integer.

uint16_t
str_to_u16(const char_t *str,
           const uint32_t base,
           bool_t *error);
str

Text string, ending in null character '\0'.

base

Numeric base: 8 (octal), 10 (decimal), 16 (hexadecimal).

error

Gets TRUE if there is an error in the conversion. Can be NULL.

Return

The numerical value.

Remarks

If the string is wrong or the value is out of range, return 0 with error=TRUE.


str_to_u32 ()

Converts a text string into an integer.

uint32_t
str_to_u32(const char_t *str,
           const uint32_t base,
           bool_t *error);
str

Text string, ending in null character '\0'.

base

Numeric base: 8 (octal), 10 (decimal), 16 (hexadecimal).

error

Gets TRUE if there is an error in the conversion. Can be NULL.

Return

The numerical value.

Remarks

If the string is wrong or the value is out of range, return 0 with error=TRUE.


str_to_u64 ()

Converts a text string into an integer.

uint64_t
str_to_u64(const char_t *str,
           const uint32_t base,
           bool_t *error);
str

Text string, ending in null character '\0'.

base

Numeric base: 8 (octal), 10 (decimal), 16 (hexadecimal).

error

Gets TRUE if there is an error in the conversion. Can be NULL.

Return

The numerical value.

Remarks

If the string is wrong or the value is out of range, return 0 with error=TRUE.


str_to_r32 ()

Convert a string of text into a real.

real32_t
str_to_r32(const char_t *str,
           bool_t *error);
str

Text string, ending in null character '\0'.

error

Gets TRUE if there is an error in the conversion. Can be NULL.

Return

The numerical value.

Remarks

If the string is wrong or the value is out of range, return 0.0 with error=TRUE.


str_to_r64 ()

Convert a string of text into a real.

real64_t
str_to_r64(const char_t *str,
           bool_t *error);
str

Text string, ending in null character '\0'.

error

Gets TRUE if there is an error in the conversion. Can be NULL.

Return

The numerical value.

Remarks

If the string is wrong or the value is out of range, return 0.0 with error=TRUE.

❮ Back
Next ❯