Standard functions

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.

Functions

uint32_t	blib_strlen (...)
const char_t*	blib_strstr (...)
void	blib_strcpy (...)
void	blib_strncpy (...)
void	blib_strcat (...)
int	blib_strcmp (...)
int	blib_strncmp (...)
uint32_t	blib_strftime (...)
int64_t	blib_strtol (...)
uint64_t	blib_strtoul (...)
real32_t	blib_strtof (...)
real64_t	blib_strtod (...)
void	blib_qsort (...)
void	blib_qsort_ex (...)
bool_t	blib_bsearch (...)
bool_t	blib_bsearch_ex (...)
const char_t*	blib_getenv (...)
int32_t	blib_setenv (...)
void	blib_atexit (...)
void	blib_abort (void)
void	blib_exit (...)
void	blib_debug_break (void)

1. Date conversion

BLib includes useful functions from the C standard library that don't fit in other modules like BMath or BMem. As in <stdlib.h> we find text conversion functions, algorithms or interaction with the environment.

Use blib_strcmp to compare two text strings.
Use blib_qsort to sort a vector of elements.
Use blib_bsearch to perform a dichotomous search on an ordered vector.
Use blib_abort to end program execution.

1. Date conversion

Use blib_strftime to convert a date to text.

Table 1: Date format modifiers.

Specifier	Replaced By	Example
%a	Abbreviated weekday name	Sun
%A	Full weekday name	Sunday
%b	Abbreviated month name	Mar
%B	Full month name	March
%c	Date and time representation	Sun Aug 19 02:56:02 2012
%d	Day of the month (01-31)	19
%H	Hour in 24h format (00-23)	14
%I	Hour in 12h format (01-12)	05
%j	Day of the year (001-366)	231
%m	Month as a decimal number (01-12)	08
%M	Minute (00-59)	55
%p	AM or PM designation	PM
%S	Second (00-59)	02
%U	Week number with the first Sunday as the first day of week one (00-53)	33
%w	Weekday as a decimal number with Sunday as 0 (0-6)	4
%W	Week number with the first Monday as the first day of week one (00-53)	34
%x	Date representation	08/19/12
%X	Time representation	02:50:06
%y	Year, last two digits (00-99)	01
%Y	Year	2012
%Z	Timezone name or abbreviation	CDT
%%	A % sign	%

blib_strlen ()

Returns the length in bytes of a text string.

uint32_t
blib_strlen(const char_t *str);

str	String terminated with null character '\0'.

Return

String length not including the null character.

Remarks

See Unicode, the number of bytes is not equivalent to the number of characters.

blib_strstr ()

Find a substring within a longer string.

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

str	String terminated with null character '\0'.
substr	Substring to search ending in null character '\0'.

Return

Pointer to the start of the first substring found or NULL if none exists.

blib_strcpy ()

Copy the content of one string to another.

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

dest	Destiny buffer.
size	Destination buffer size in bytes.
src	String to copy ending in null character '\0'.

Remarks

Only the first size-1 bytes will be copied, in case src is longer than the capacity of dest.

blib_strncpy ()

Copy the first n bytes of one string to another.

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

dest	Destiny buffer.
size	Destination buffer size in bytes.
src	String to copy ending in null character '\0'.
n	Number of bytes to copy.

Remarks

Only the first size-1 bytes will be copied, in case n is greater than size.

blib_strcat ()

Concatenation of strings.

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

dest	Source and destination buffer.
size	Destination buffer size in bytes.
src	String to add to `dest`, terminated with null character '\0'.

Remarks

The size-1 bytes in dest will not be exceeded, so the concatenation will be truncated if necessary.

blib_strcmp ()

Compare two strings.

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

str1	First string to compare, terminated with null character '\0'.
str2	Second string to compare, terminated with null character '\0'.

Return

Comparison Result.

blib_strncmp ()

Compare the first n bytes of two strings.

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

str1	First string to compare, terminated with null character '\0'.
str2	Second string to compare, terminated with null character '\0'.
n	Maximum number of bytes to compare.

Return

Comparison Result.

blib_strftime ()

Transforms a date into a text string, using the strftime format.

uint32_t
blib_strftime(char_t *dest,
              const uint32_t size,
              const char_t *format,
              const int16_t year,
              const uint8_t month,
              const uint8_t mday,
              const uint8_t wday,
              const uint8_t hour,
              const uint8_t minute,
              const uint8_t second);

dest	Pointer to the buffer where the result will be written. Will terminate in null character `'\0'`.
size	Size of `dest` in bytes.
format	Format the string with the date.
year	Year.
month	Month number (1,12).
mday	Day of the month (1,31).
wday	Weekday (0,6). 0=Sunday.
hour	Hour (0,23).
minute	Minute (0,59).
second	Second (0,59).

Return

The number of bytes written to dest, not including the character '\0'. If the string does not fit in dest it returns 0.

Remarks

See Date conversion.

blib_strtol ()

Convert a text string to an integer.

int64_t
blib_strtol(const char_t *str,
            char_t **endptr,
            uint32_t base,
            bool_t *err);

str	String starting with an integer.
endptr	Pointer whose value will be the first character after the number. Can be `NULL`.
base	Number base: 2, 8, 10, 16.
err	Value `TRUE` is assigned if there is an error in the parsing of the string. Can be `NULL`.

Return

String parsing result number.

blib_strtoul ()

Convert a text string to an unsigned integer.

uint64_t
blib_strtoul(const char_t *str,
             char_t **endptr,
             uint32_t base,
             bool_t *err);

str	String starting with an integer.
endptr	Pointer whose value will be the first character after the number. Can be `NULL`.
base	Number base: 2, 8, 10, 16.
err	Value `TRUE` is assigned if there is an error in the parsing of the string. Can be `NULL`.

Return

String parsing result number.

blib_strtof ()

Convert a text string to a 32-bit real number.

real32_t
blib_strtof(const char_t *str,
            char_t **endptr,
            bool_t *err);

str	String starting with an real number.
endptr	Pointer whose value will be the first character after the number. Can be `NULL`.
err	Value `TRUE` is assigned if there is an error in the parsing of the string. Can be `NULL`.

Return

String parsing result number.

blib_strtod ()

Convert a text string to a 32-bit real number.

real64_t
blib_strtod(const char_t *str,
            char_t **endptr,
            bool_t *err);

str	String starting with an real number.
endptr	Pointer whose value will be the first character after the number. Can be `NULL`.
err	Value `TRUE` is assigned if there is an error in the parsing of the string. Can be `NULL`.

Return

String parsing result number.

blib_qsort ()

Sorts a vector of elements using the QuickSort algorithm.

void
blib_qsort(byte_t *array,
           const uint32_t nelems,
           const uint32_t size,
           FPtr_compare func_compare);

array	Vector of elements.
nelems	Number of elements.
size	Size of each element.
func_compare	Comparison function.

blib_qsort_ex ()

Sorts a vector of elements using the QuickSort algorithm.

void
blib_qsort_ex(byte_t *array,
              const uint32_t nelems,
              const uint32_t size,
              FPtr_compare_ex func_compare,
              const byte_t *data);

array	Vector of elements.
nelems	Number of elements.
size	Size of each element.
func_compare	Compare function that accepts extra data.
data	Extra data that will be passed in each comparison.

blib_bsearch ()

Search for an element in an ordered vector.

bool_t
blib_bsearch(const byte_t *array,
             const byte_t *key,
             const uint32_t nelems,
             const uint32_t size,
             FPtr_compare func_compare,
             uint32_t *pos);

array	Vector of elements.
key	Search key.
nelems	Number of elements.
size	Size of each element.
func_compare	Comparison function.
pos	Position of the found element. It can be `NULL`.

Return

TRUE if the element was found.

blib_bsearch_ex ()

Search for an element in an ordered vector.

bool_t
blib_bsearch_ex(const byte_t *array,
                const byte_t *key,
                const uint32_t nelems,
                const uint32_t size,
                FPtr_compare_ex func_compare,
                const byte_t *data,
                uint32_t *pos);

array	Vector of elements.
key	Search key.
nelems	Number of elements.
size	Size of each element.
func_compare	Compare function that accepts extra data.
data	Extra data that will be passed in each comparison.
pos	Position of the found element. It can be `NULL`.

Return

TRUE if the element was found.

blib_getenv ()

Gets the value of an environment variable.

const char_t*
blib_getenv(const char_t *name);

name	The name of the variable.

Return

The value of the variable. NULL if said variable does not exist.

blib_setenv ()

Sets the value of an environment variable.

int32_t
blib_setenv(const char_t *name,
            const char_t *value);

name	The name of the variable.
value	The value of the variable.

Return

0 if set correctly. Otherwise, an error code.

Remarks

If the variable already exists, its value will be overwritten.

blib_atexit ()

Add a function that will be called when the program ends.

void
blib_atexit(void()(void) *func);

func

Function.

blib_abort ()

The execution of the program ends abruptly.

void
blib_abort(void);

Remarks

No resources are released or a controlled shutdown is performed. The only case where its use is justified is to exit the program after detecting an unrecoverable error (eg NULL pointer).

blib_exit ()

Terminates a process.

void
blib_exit(int code);

code	Return code.

blib_debug_break ()

Stops program execution at the point where the function is located and returns debugger control so we can inspect the stack, variables, etc.

void
blib_debug_break(void);