Strings

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

String objects contain UTF-8 characters strings dynamically allocated. Although it is possible to insert static text strings directly into the source code or access them through the resource packages (respack_text), it is usually necessary to compose texts at runtime or dynamically store strings received by some input channel (keyboard, files, network, etc). The NAppGUI strings.h module offers a multitude of functions to work with UTF8 text strings, both static and dynamic.

• Use str_c to create a dynamic copy of a static C string.
• Use str_printf to compose a dynamic string using the same format as C printf.
• Use tc to get a const char_t* pointer to the content of a String.

1 2 3 4 5 6

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

Do not confuse String objects with C strings const char_t *str or char_t str[128]. The first ones contain a pointer to the dynamic memory area and an integer with the number of reserved bytes.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

String *str = NULL;
Stream *stm = stm_memory(2048);
uint32_t n = arrpt_size(products, Product);
stm_printf(stm, "List of %d products\n", n);
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);

// Do something with 'str'
...

str_destroy(&str);

tc ()

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

const char_t*
tc(const String *str);

Return

Pointer to the C-string.

tcc ()

Returns the inner C (non-const) string in UTF-8 format contained in String.

char_t*
tcc(String *str);

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);

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);

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);

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);

Return

The String object.

str_copy ()

Create an exact copy of the String.

String*
str_copy(const String *str);

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,
           ...);

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"

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

Return

The String object.

str_relpath ()

Calculate the relative path to path1 to get to path2.

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

Return

The string object that contains the relative path.

str_crelpath ()

Calculate the relative path to path1 to get to path2.

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

Return

The string object that contains the relative path.

Remarks

Same as str_relpath, but using the directory separator of the platform where the program is running.

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 NULL.

String*
str_repl(const char_t *str,
         ...);

1
2

String *str = str_repl("const Product **pr;", "const", "", "*", "", " ", "", NULL);
str = "Productpr;"

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);

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);

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);

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);

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);

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);

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);

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);

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);

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_destroy ()

Destroy a string object.

void
str_destroy(String **str);

str_destopt ()

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

void
str_destopt(String **str);

str_len ()

Returns the size in bytes of a string.

uint32_t
str_len(const String *str);

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);

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);

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);

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);

Return

TRUE if prefix is prefix of str.

str_is_sufix ()

Check if one string is a suffix of another.

bool_t
str_is_sufix(const char_t *str,
             const char_t *sufix);

Return

TRUE si sufix is sufix of str.

str_scmp ()

Compare two strings alphabetically.

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

Return

Comparison result.

str_cmp ()

Compare alphabetically a string with a UTF8 C string.

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

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);

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);

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);

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);

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);

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);

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);

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);

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);

Return

TRUE if str ends in end.

str_upper ()

Change lowercase letters to uppercase.

void
str_upper(String *str);

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);

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);

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);

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"

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);

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);

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

Return

TRUE if substr exists in str.

Remarks

If NULL is not used, left and right will always return a valid string, even if it is empty.

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);

Return

TRUE if substr exists in str.

Remarks

If NULL is not used, left and right will always return a valid string, even if it is empty.

str_splits ()

Splits a string into several, using a substring as a separator.

ArrPt(String)*
str_splits(const char_t *str,
           const char_t *substr,
           const bool_t trim,
           const bool_t add_empty);

1
2
3
4
5
6
7

// strs will be a 0-size array
const char_t *str = "||  ||  ||";
ArrPt(String) *strs = str_splits(str, "|", TRUE, FALSE);

// strs will be a 7-size array of empty strings
const char_t *str = "||  ||  ||";
ArrPt(String) *strs = str_splits(str, "|", TRUE, TRUE);

Return

Array with the substrings found. It must be destroyed with arrpt_destroy(&array, str_destroy, String).

Remarks

trim is applied first and then add_empty.

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"

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"

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"

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"

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);

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);

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);

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);

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);

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);

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);

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);

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);

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);

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);

Return

The numerical value.

Remarks

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