Strings

Cadenas de caracteres en UTF-8, reservadas dinámicamente.

Funciones

Los objetos String contienen cadenas de caracteres UTF-8 reservadas dinámicamente. A pesar de que en determinadas ocasiones podamos utilizar cadenas de texto estáticas (char_t str[128]), en otras necesitaremos que los textos sean persistentes o formen parte de estructuras u objetos. No siempre será posible predecir la cantidad de memoria que necesitará la cadena, por lo que almacenarla dinámicamente será una opción más acertada. Los cuatro primeros bytes del objeto guardan el tamaño (en bytes) del texto, incluyendo el carácter nulo final (Figura 1), por lo que deberemos utilizar la función tc() para acceder al const char_t* con el texto. El módulo strings.h de NAppGUI ofrece multitud de funciones para trabajar con cadenas de texto UTF8, tanto estáticas como dinámicas.

• Utiliza str_c para crear una copia dinámica de una cadena C estática.
• Utiliza str_printf para componer una cadena dinámica utilizando el mismo formato que el printf de C.
• Utiliza tc para obtener un puntero const char_t* al contenido de un String.
• Utiliza str_len para obtener el tamaño en bytes de la cadena.
• Utiliza str_nchars para obtener el número de caracteres.



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

No confundir los objetos String con las cadenas de texto en C const char_t *str ó char_t str[128]. Los primeros contienen un puntero al área de memoria dinámica y un entero con el número de bytes reservados.

No confundir el tamaño de la cadena len con el número de caracteres nchars. En UTF8 no tienen porqué coincidir.

En el caso que sea necesario componer textos más extensos o, a partir de bucles, la forma más eficiente es crear un Stream y, posteriormente, obtener el String asociado.

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

Devuelve la cadena C interna en formato UTF-8 contenida en el String.

const char_t*
tc(const String *str);

Retorna

Puntero a la cadena C.

tcc ()

Devuelve la cadena C (no const) interna en formato UTF-8 contenida en el String.

char_t*
tcc(String *str);

Retorna

Puntero a la cadena C.

str_c ()

Crea un String a partir de una cadena C codificada en UTF-8.

String*
str_c(const char_t *str);

Retorna

El objeto string.

str_cn ()

Crea un String copiando los primeros n bytes de una cadena C.

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

Retorna

El objeto string.

Observaciones

En cadenas UTF-8, el número de bytes no corresponde con el número de caracteres.

str_trim ()

Crea un String a partir de una cadena C recortando los espacios en blanco, tanto al principio como al final.

String*
str_trim(const char_t *str);

Retorna

El objeto string.

str_trim_n ()

Crea un String a partir a partir de los primeros n bytes de una cadena C recortando los espacios en blanco, tanto al principio como al final.

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

Retorna

El objeto string.

str_copy ()

Crea un copia exacta del String.

String*
str_copy(const String *str);

Retorna

El objeto string copiado.

Observaciones

Los Strings son un tipo especial de objeto mutable. Copiar implica crear un nuevo objeto y no incrementar un contador de referencias.

str_printf ()

Compone un String desde varios campos, utilizando el formato del printf.

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

Retorna

El objeto string.

Observaciones

El uso de esta función previene vulnerabilidades del tipo buffer overflow, asociadas a las clásicas funciones C como strcpy.

str_path ()

Igual que str_printf, pero considera que la cadena es un pathname y, por tanto, utiliza el separador conveniente según 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"

Retorna

El objeto string.

str_cpath ()

Igual que str_path, pero considerando la plataforma donde está corriendo el programa.

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

Retorna

El objeto string.

str_relpath ()

Calcula la ruta relativa a path1 para llegar a path2.

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

Retorna

El objeto string que contiene la ruta relativa.

str_crelpath ()

Calcula la ruta relativa a path1 para llegar a path2.

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

Retorna

El objeto string que contiene la ruta relativa.

Observaciones

Igual que str_relpath, pero utilizando el separador de directorios de la plataforma donde está corriendo el programa.

str_repl ()

Crea un String reemplazando un número indeterminado de sub-cadenas. El primer parámetro es la cadena original. Los siguiente pares indican la sub-cadena a buscar y la sub-cadena que debe sustituirla. El último parámetro debe ser NULL.

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

1
2

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

Retorna

El objeto string.

str_reserve ()

Crea un String con n+1 bytes, pero sin asignarle ningún contenido.

String*
str_reserve(const uint32_t n);

Retorna

El objeto string. Su contenido será indeterminado (basura). Debe escribirse posteriormente.

str_fill ()

Crea un String repitiendo n veces un mismo carácter.

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

Retorna

El objeto string.

str_read ()

Crea un String leyendo su contenido de un Stream (de-serialización). El String ha debido ser escrito previamente por str_write.

String*
str_read(Stream *stream);

Retorna

El objeto string.

Observaciones

Es una operación binaria. El tamaño del string se deserializa primero.

str_write ()

Escribe un string en un Streams (serialización).

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

Observaciones

Es una operación binaria. El tamaño del string se serializa primero. Utiliza str_writef para escribir solo el texto.

str_writef ()

Escribe en un Streams la cadena C contenida en el string.

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

Observaciones

Escribe únicamente el texto del string, sin el carácter nulo '\0' final. Es equivalente a stm_writef(stream, tc(str)); pero más eficiente, ya que no hay que calcular el tamaño de str.

str_copy_c ()

Copia la cadena C src en el búfer apuntado por dest, incluyendo el carácter nulo '\0'.

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

Observaciones

Es una operación segura. No se escribirán en dest más de size bytes y nunca se truncará un carácter. dest siempre acabará con el carácter nulo '\0'.

str_copy_cn ()

Copia en dest un máximo de n bytes de la cadena C UTF8 apuntada por src, incluyendo el carácter nulo '\0'.

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

Observaciones

Es una operación segura. No se escribirán en dest más de n bytes y nunca se truncará un carácter. dest siempre acabará con el carácter nulo '\0'.

str_cat ()

Concatena dinámicamente el contenido de src en dest.

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

Observaciones

Esta operación implica reasignar memoria dinámica. Para componer textos largos es más eficiente utilizar Stream.

str_cat_c ()

Concatena el contenido de src en dest. El carácter nulo en dest será sobrescrito por el primer carácter de src.

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

Observaciones

Es una operación segura. No se escribirán en dest más de size bytes y nunca se truncará un carácter. dest siempre acabará con el carácter nulo '\0'.

str_upd ()

Cambia el contenido de un string por otro.

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

Destruye un objeto string.

void
str_destroy(String **str);

str_destopt ()

Destruye un objeto string si su contenido no es NULL (destructor opcional).

void
str_destopt(String **str);

str_len ()

Retorna el tamaño en bytes de un string.

uint32_t
str_len(const String *str);

Retorna

El número de bytes, sin incluir el carácter nulo '\0'.

Observaciones

En cadenas UTF-8 el número de bytes no es el mismo que el caracteres. str_nchars.

str_len_c ()

Retorna el tamaño en bytes de una cadena C UTF8.

uint32_t
str_len_c(const char_t *str);

Retorna

El número de bytes, sin incluir el carácter nulo '\0'.

Observaciones

En cadenas UTF-8 el número de bytes no es el mismo que el caracteres. unicode_nchars.

str_nchars ()

Retorna el número de caracteres de un objeto string.

uint32_t
str_nchars(const String *str);

Retorna

El número de caracteres, sin incluir el carácter nulo '\0'.

Observaciones

En cadenas UTF-8 el número de bytes no es el mismo que el caracteres.

str_prefix ()

Localiza el inicio común de dos cadenas.

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

Retorna

El número de bytes que son idénticos al comienzo de ambas cadenas.

str_is_prefix ()

Comprueba si una cadena es prefijo de otra.

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

Retorna

TRUE si preffix es prefijo de str.

str_is_sufix ()

Comprueba si una cadena es sufijo de otra.

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

Retorna

TRUE si sufix es sufijo de str.

str_scmp ()

Compara alfabéticamente dos strings.

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

Retorna

Resultado de la comparación.

str_cmp ()

Compara alfabéticamente un string con una cadena C UTF8.

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

Retorna

Resultado de la comparación.

str_cmp_c ()

Compara alfabéticamente dos cadenas C UTF8 terminadas en carácter nulo '\0'.

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

Retorna

Resultado de la comparación.

str_cmp_cn ()

Compara alfabéticamente los primeros n bytes de dos cadenas C UTF8 terminadas en carácter nulo '\0'.

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

Retorna

Resultado de la comparación.

Observaciones

Es una operación segura. Si alguna de las dos cadenas llega al final antes de llegar a n bytes, la comparación termina.

str_empty ()

Comprueba si un string está vacío (str->data[0] == '\0').

bool_t
str_empty(const String *str);

Retorna

TRUE si está vacío o es NULL.

str_empty_c ()

Comprueba si una cadena C UTF8 está vacía (str[0] == '\0').

bool_t
str_empty_c(const char_t *str);

Retorna

TRUE si está vacía o es NULL.

str_equ ()

Comprueba si el contenido de un string es igual a una cadena C.

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

Retorna

TRUE si son iguales.

str_equ_c ()

Comprueba si dos cadenas C UTF8 son iguales.

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

Retorna

TRUE si son iguales.

str_equ_cn ()

Comprueba si los primeros bytes de dos cadenas C UTF8 son iguales.

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

Retorna

TRUE si son iguales.

Observaciones

Si se alcanza '\0' en alguna de las dos cadenas, se devolverá TRUE.

str_equ_nocase ()

Comprueba si dos cadenas C UTF8 son iguales, ignorando mayúsculas o minúsculas.

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

Retorna

TRUE si son iguales.

Observaciones

Solo se consideran caracteres US-ASCII (0-127).

str_equ_end ()

Comprueba la terminación de una cadena.

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

Retorna

TRUE si str acaba en end.

str_upper ()

Cambia los letras minúsculas por mayúsculas.

void
str_upper(String *str);

Observaciones

Solo se consideran caracteres US-ASCII (0-127). La cadena original cambiará, pero no los requisitos de memoria.

str_lower ()

Cambia los letras mayúsculas por minúsculas.

void
str_lower(String *str);

Observaciones

Solo se consideran caracteres US-ASCII (0-127). La cadena original cambiará, pero no los requisitos de memoria.

str_upper_c ()

Convierte una cadena a mayúsculas.

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

Observaciones

Solo se consideran caracteres US-ASCII (0-127).

str_lower_c ()

Convierte una cadena a minúsculas.

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

Observaciones

Solo se consideran caracteres US-ASCII (0-127).

str_subs ()

Cambia todas las instancias de un carácter por otro.

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"

Observaciones

Solo se consideran caracteres US-ASCII (0-127). La cadena original cambiará, pero no los requisitos de memoria.

str_repl_c ()

Cambia todas las instancias de una subcadena por otra.

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

Observaciones

Las subcadenas replace y with deben tener el mismo tamaño, de lo contrario se producirá un Asserts. Utiliza str_repl para el caso general.

str_str ()

Busca una subcadena dentro de otra de mayor tamaño.

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

Retorna

Puntero a la primera ocurrencia de substr en str o NULL si no existe ninguna.

str_split ()

Divide una cadena en dos, utilizando la primera ocurrencia de una subcadena.

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

Retorna

TRUE si substr existe en str.

Observaciones

En caso no de no ser NULL, left y right siempre devolverán una cadena válida, aunque sea vacía.

str_split_trim ()

Igual que str_split pero eliminando todos los espacios en blanco al principio y final de left y right.

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

Retorna

TRUE si substr existe en str.

Observaciones

En caso no de no ser NULL, left y right siempre devolverán una cadena válida, aunque sea vacía.

str_splits ()

Divide una cadena en varias, utilizando una subcadena como separador.

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

Retorna

Array con las subcadenas encontradas. Debe ser destruido con arrpt_destroy(&array, str_destroy, String).

Observaciones

Primero se aplica trim y después add_empty.

str_split_pathname ()

Divide un pathname en path y file Filename y 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 ()

Igual que str_split_pathname pero extrayendo también la extensión del archivo.

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

Retorna la parte final de un pathname. Filename y 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"

Retorna

El último tramo de una ruta de directorios.

str_filext ()

Retorna la extensión del archivo, a partir de un pathname. Filename y 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"

Retorna

La extensión del archivo.

str_find ()

Busca una cadena en un array.

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

Retorna

La posición de la cadena o UINT32_MAX si no existe.

str_to_i8 ()

Convierte una cadena de texto en un entero.

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

Retorna

El valor numérico.

Observaciones

Si la cadena es errónea o el valor está fuera de rango, devuelve 0 con error=TRUE.

str_to_i16 ()

Convierte una cadena de texto en un entero.

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

Retorna

El valor numérico.

Observaciones

Si la cadena es errónea o el valor está fuera de rango, devuelve 0 con error=TRUE.

str_to_i32 ()

Convierte una cadena de texto en un entero.

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

Retorna

El valor numérico.

Observaciones

Si la cadena es errónea o el valor está fuera de rango, devuelve 0 con error=TRUE.

str_to_i64 ()

Convierte una cadena de texto en un entero.

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

Retorna

El valor numérico.

Observaciones

Si la cadena es errónea o el valor está fuera de rango, devuelve 0 con error=TRUE.

str_to_u8 ()

Convierte una cadena de texto en un entero.

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

Retorna

El valor numérico.

Observaciones

Si la cadena es errónea o el valor está fuera de rango, devuelve 0 con error=TRUE.

str_to_u16 ()

Convierte una cadena de texto en un entero.

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

Retorna

El valor numérico.

Observaciones

Si la cadena es errónea o el valor está fuera de rango, devuelve 0 con error=TRUE.

str_to_u32 ()

Convierte una cadena de texto en un entero.

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

Retorna

El valor numérico.

Observaciones

Si la cadena es errónea o el valor está fuera de rango, devuelve 0 con error=TRUE.

str_to_u64 ()

Convierte una cadena de texto en un entero.

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

Retorna

El valor numérico.

Observaciones

Si la cadena es errónea o el valor está fuera de rango, devuelve 0 con error=TRUE.

str_to_r32 ()

Convierte una cadena de texto en un real.

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

Retorna

El valor numérico.

Observaciones

Si la cadena es errónea o el valor está fuera de rango, devuelve 0.0 con error=TRUE.

str_to_r64 ()

Convierte una cadena de texto en un real.

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

Retorna

El valor numérico.

Observaciones

Si la cadena es errónea o el valor está fuera de rango, devuelve 0.0 con error=TRUE.