API

group str

Public function definitions and types for Yc’s non-dynamic strings.

Defines

y_STR(p)

A define that takes a constant string and returns an array struct string.

Parameters:
  • p – The string to initialize the array struct string with.

Returns:

A fully initialized array struct initializer that can be directly assigned to string.

Pre:

p must be constant at compile time.

y_STR_INIT(s, p)

A define that takes an array struct string and a string and initializes the array struct with the string and its length.

s must not be a pointer. For pointers, see y_STR_INITP.

Parameters:
  • s – The array struct string to initialize.

  • p – The string to initialize the array struct string with.

Pre:

s must not be a pointer.

Pre:

p must be constant at compile time.

y_STR_INITP(s, p)

A define that takes an array struct string and a string and initializes the array struct with the string and its length.

s must be a pointer. For non-pointers, see y_STR_INIT.

Parameters:
  • s – The array struct string to initialize.

  • p – The string to initialize the array struct string with.

Pre:

s must be a pointer.

Pre:

p must be constant at compile time.

Functions

y_Status y_str_init(y_str *s, const char *str)

Initializes a new y_str from a C string.

Parameters:
  • s – The y_str to initialize.

  • str – The C string to initialize from.

Returns:

y_STATUS_MALLOC_FAIL on allocation failure, y_STATUS_SUCCESS otherwise.

Pre:

s must not be NULL.

Pre:

s must not be initialized.

Pre:

str must not be NULL.

y_Status y_str_sinit(y_str *s, const char *str)

Initializes a new y_str from a C string from the thread stackpool.

Parameters:
  • s – The y_str to initialize.

  • str – The C string to initialize from.

Returns:

y_STATUS_MALLOC_FAIL on allocation failure, y_STATUS_SUCCESS otherwise.

Pre:

s must not be NULL.

Pre:

s must not be initialized.

Pre:

str must not be NULL.

y_Status y_str_dup(y_str *s, const y_str *str)

Creates a new y_str from another y_str.

Parameters:
  • s – The y_str to initialize.

  • str – The y_str to initialize from.

Returns:

y_STATUS_MALLOC_FAIL on allocation failure, y_STATUS_SUCCESS otherwise.

Pre:

s must not be NULL.

Pre:

s must not be initialized.

Pre:

str must not be NULL.

Pre:

str must be initialized.

y_Status y_str_copy(void *dest, const void *src)

Frees and reinitializes a y_str from another y_str.

This is a y_Copier function.

Parameters:
  • dest – The y_str to free and reinitialize.

  • src – The y_str to initialize from.

Returns:

y_STATUS_MALLOC_FAIL on allocation failure, y_STATUS_SUCCESS otherwise.

Pre:

dest must not be NULL.

Pre:

dest must be initialized.

Pre:

src must not be NULL.

Pre:

src must be initialized.

bool y_str_eq(const void *str1, const void *str2)

Compares two y_strs and returns true if they are equal, false otherwise.

This is a y_Equal function.

Parameters:
  • str1 – The first y_str.

  • str2 – The second y_str.

Returns:

True if the y_strs are equal, false otherwise.

Pre:

str1 must not be NULL.

Pre:

str1 must be initialized.

Pre:

str2 must not be NULL.

Pre:

str2 must be initialized.

ssize_t y_str_cmp(const void *str1, const void *str2)

Compares two y_strs and returns less than 0 if str1 is less than str2, 0 if they are equal, and greater than 0 otherwise.

This is a y_Comparator.

Parameters:
  • str1 – The first y_str.

  • str2 – The second y_str.

Returns:

0 if the elements are equal, greater than 0 if ptr2 is less than ptr1, less than 0 otherwise.

Pre:

str1 must not be NULL.

Pre:

str1 must be initialized.

Pre:

str2 must not be NULL.

Pre:

str2 must be initialized.

uint64_t y_str_hash(const void *str)

Returns a 64-bit hash of a y_str.

This is a y_Hasher function.

Parameters:

str – The string to hash.

Returns:

The 64-bit hash of the str.

Pre:

s must not be NULL.

Pre:

s must be initialized.

size_t y_str_len(const y_str *s)

Returns the length of the string without the nul byte.

Parameters:

s – The string.

Returns:

The length of the string.

Pre:

s must not be NULL.

const char *y_str_str(const y_str *s)

Returns a const pointer to the C string in a y_str.

Parameters:

s – The y_str to query.

Returns:

The underlying C string in s.

Pre:

s must not be NULL.

Pre:

s must be initialized.

y_Status y_str_pchar2str(y_str *s, y_pchar *str)

Returns a newly-allocated string that is a conversion of the given y_pchar string to a normal string.

Parameters:
  • s – The string to initialize, It must be freed with y_str_free().

  • str – The string to convert.

Pre:

s must not be NULL.

Pre:

str must not be NULL.

void y_str_free(void *str)

Frees a y_str.

This is a y_Destructor function.

Parameters:

str – The y_str to free.

Pre:

s must not be NULL.

Pre:

s must be initialized.

y_Status y_strv_split(y_strv *s, y_str str, y_uchar c)

Splits a string on a specific character and returns the resulting list of strings.

Parameters:
  • s – The string list to initialize.

  • str – The string to split.

  • c – The character to split on.

Returns:

An error code, if any.

Pre:

s must not be NULL.

Pre:

str must be initialized.

y_Status y_strv_pcharv2strv(y_strv *s, size_t len, y_pchar **v)

Returns a newly-allocated string array where all strings are a conversion of the given y_pchar strings.

Parameters:
  • s – The string array to allocate and initialize.

  • len – The length of the y_pchar string list.

  • v – The y_pchar string list.

Returns:

An error code, if any.

Pre:

s must not be NULL.

Pre:

v must not be NULL.

void y_strv_free(void *strv)

Frees an array of strings.

Parameters:

strv – The array to free.

Pre:

strv must not be NULL.

y_Status y_env_linit(y_env *e, y_strv env)

Creates an environment block out of a string list.

Parameters:
  • e – The environment block to create and initialize.

  • env – The list of strings to put into the environment.

Returns:

An error code, if any.

Pre:

e must not be NULL.

y_Status y_env_init(y_env *e, size_t nargs, ...)

Creates an environment block out of a list of string argumest.

All var args must be strings.

Parameters:
  • e – The environment block to create and initialize.

  • nargs – The number of var args strings passed in.

  • ... – String arguments to create an environment out of.

Returns:

An error code, if any.

Pre:

e must not be NULL.

void y_env_destroy(void *env)

Destroys an environment block.

Parameters:

env – The environment block to destroy.

Pre:

env must not be NULL.

struct y_str
#include <str.h>

Yc’s string type.

struct y_str_const
#include <str.h>

Yc’s const string type.

This is used for keys for maps and things like that.

struct y_strv
#include <str.h>

A type for an array of strings.

group string

Definitions and types for Yc’s dynamic string.

Typedefs

typedef struct y_vec *y_String

Public definition of Yc’s string, which is hidden.

Functions

y_String y_string_create(const char *str)

Creates a y_String from an existing char array.

Parameters:

str – The char array to copy into the new y_String.

Returns:

NULL on malloc error, a valid y_String otherwise.

Pre:

str must not be NULL.

y_String y_string_createCopy(y_String str)

Creates a y_String and copies contents from str.

Parameters:

str – The y_String to copy into the new y_String.

Returns:

NULL on malloc error, a valid y_String otherwise.

Pre:

str must not be NULL.

size_t y_string_len(const y_String s)

Returns the length of the y_str, not including the terminating zero byte.

Parameters:

s – The y_str whose length will be returned.

Returns:

The length of the given y_String.

Pre:

s must not be NULL.

y_str y_string_str(const y_String s)

Returns the underlying string in the y_String.

Parameters:

s – The y_String whose string will be returned.

Returns:

A y_str of the y_String.

Pre:

s must not be NULL.

char *y_string_cstr(const y_String s)

Returns the underlying string in the y_String.

Parameters:

s – The y_String whose char array will be returned.

Returns:

The underlying char array of the y_String.

Pre:

s must not be NULL.

y_Status y_string_set(y_String s, const char *str)

Sets the y_String to contain the provided string.

It copies the data into the y_String.

Parameters:
  • s – The y_String to set.

  • str – The string to set the y_String to.

Returns:

Either y_STATUS_SUCCESS or a status describing the error.

Pre:

s must not be NULL.

Pre:

str must not be NULL.

y_Status y_string_nset(y_String s, const char *str, size_t n)

Sets the y_String to contain n characters of the provided string.

It copies the data into the y_String. If n is greater than the length of str, n is changed to the length of str.

Parameters:
  • s – The y_String to set.

  • str – The string to set the y_String to.

  • n – The number of characters to copy. If n is greater than the length of str, then it is decreased to the length of str.

Returns:

Either y_STATUS_SUCCESS or a status describing the error.

Pre:

s must not be NULL.

Pre:

str must not be NULL.

y_Status y_string_copy(y_String d, const y_String s)

Copies one string into another.

This is a y_Copier.

Parameters:
  • d – The copy destination.

  • s – The copy source.

Returns:

y_STATUS_SUCCESS on success, an error code otherwise.

Pre:

d must not be NULL.

Pre:

s must not be NULL.

Pre:

d and s must not be the same vector.

y_Status y_string_cat(y_String d, const y_String s)

Concatenates s to the end of d.

If necessary, d will be reallocated to handle the new size of the string.

Parameters:
  • d – The y_String that will appended to.

  • s – The y_String that will be copied onto the back of d.

Returns:

Either y_STATUS_SUCCESS or a status describing the error.

Pre:

d must not be NULL.

Pre:

s must not be NULL.

y_Status y_string_ccat(y_String d, const char *s)

Concatenates s to the end of d.

If necessary, d will be reallocated to handle the new size of the string.

Parameters:
  • d – The y_String that will appended to.

  • s – The y_String that will be copied onto the back of d.

Returns:

Either y_STATUS_SUCCESS or a status describing the error.

Pre:

d must not be NULL.

Pre:

s must not be NULL.

y_Status y_string_ncat(y_String d, const y_String s, size_t n)

Concatenates n bytes of s to the end of d.

If necessary, d will be reallocated to handle the new size of the string.

Parameters:
  • d – The y_String that will appended to.

  • s – The y_String that will be copied onto the back of d.

  • n – The number of bytes to be copied.

Returns:

Either y_STATUS_SUCCESS or a status describing the error.

Pre:

d must not be NULL.

Pre:

s must not be NULL.

Pre:

n must be greater than 0.

y_Status y_string_push(y_String s, y_uchar c)

Pushes c onto s.

Parameters:
  • s – The string to push onto.

  • c – The character to push.

Returns:

Either y_STATUS_SUCCESS or a status describing the error.

Pre:

s must not be NULL.

Pre:

c must not be the NUL character.

y_Status y_string_substr(y_String d, y_String s, size_t idx, size_t n)

Copies a substring of s into d, starting at start and going for n characters.

Parameters:
  • d – The string that will be copied to.

  • s – The string that will be copied from.

  • idx – The start index to copy.

  • n – The amount of characters to copy.

Returns:

Either y_STATUS_SUCCESS or a status describing the error.

Pre:

d must not be NULL.

Pre:

s must not be NULL.

Pre:

n must be greater than 0.

y_Status y_string_setCapacity(y_String s, size_t ncap)

Sets the string’s capacity to ncap (new capacity).

If ncap is less than the current length of the length, those existing elements will be erased.

Parameters:
  • s – The string to resize.

  • ncap – The new capacity for the string.

Returns:

y_STATUS_SUCCESS if the string was successfully expanded, or a status describing the error.

Pre:

s must not be NULL.

Pre:

ncap must not be 0.

void y_string_free(y_String s)

Free all of the data from a string.

Parameters:

s – The string whose data will be freed.

Pre:

s must not be NULL.