Useful common functions and macros. More...

Files
file	utils.h
	Useful common functions and macros.

Macros
#define	int2str(num)
	Converts an `int` value to a stack allocated string. More...

#define	int2nstr(num, len)
	Converts an `int` value to a stack allocated string. More...

#define	perc2str(percentage)
	Converts an `int` percentage to a stack allocated string. More...

#define	length_vargs_string_list(first)
	Determines the length of all strings passed as a NULL terminated variable list of arguments (vargs). More...

#define	not_null(pnt)
	Checks if address is not `NULL`, before its application. More...

Functions
void *	mem_alloc (int size)
	A replacement for `malloc` function. More...

void	mem_free (void *pnt)
	A replacement for `free` function. More...

char *	string_clone (char *str)
	Replicates a string. More...

int	string_num_lines (char *text)
	Number of lines of a string. More...

int	string_num_columns (char *text)
	Maximum number of columns of a string (not counting character `'\n'`). More...

int	string_count_char (char text, char ch)
	Counts the number of occurrences of an UTF8 character in a text. More...

int	string_starts_with (char text, char prefix)
	Tests if a string starts with a prefix. More...

int	string_ends_with (char text, char suffix)
	Tests if a string ends with a suffix. More...

char *	string_concat (char res, int max_length, char text,...)
	Concatenates a `NULL` terminated list of string arguments. More...

int	random_boolean (int trueProb)
	Generates a random boolean value. More...

int	random_int (int min, int max)
	Generates a random integer value within a given interval. More...

char *	random_string (char *list, int used, int length)
	Returns a random string from a given string list. More...

void	clear_console ()
	Clears the terminal.

void	move_cursor (int line, int column)
	Moves the cursor to a position in terminal. More...

void	hide_cursor ()
	Hides the terminal cursor.

void	show_cursor ()
	Shows the terminal cursor.

int	string_list_length (char **list)
	Number of elements of a `NULL` terminated list of strings. More...

char **	string_list_clone (char **list)
	Replicates a `NULL` terminated list of strings. More...

char **	string_list_free (char **list)
	Frees the memory allocated to a `NULL` terminated list of strings. More...

char *	int2nstring (char *res, int num, int len)
	Converts an `int` value to a string. More...

char *	percentage2string (char *res, int percentage)
	Converts an `int` percentage to a string. More...

String concatenation in stack memory

#define	concat_2str(str1, str2)
	Concatenates two strings in the stack memory (thus it cannot be implemented in a function). More...

#define	concat_3str(str1, str2, str3)
	Concatenates three strings in the stack memory (thus it cannot be implemented in a function). More...

#define	concat_4str(str1, str2, str3, str4)
	Concatenates four strings in the stack memory (thus it cannot be implemented in a function). More...

#define	concat_5str(str1, str2, str3, str4, str5)
	Concatenates five strings in the stack memory (thus it cannot be implemented in a function). More...

#define	concat_6str(str1, str2, str3, str4, str5, str6)
	Concatenates six strings in the stack memory (thus it cannot be implemented in a function). More...

#define	concat_7str(str1, str2, str3, str4, str5, str6, str7)
	Concatenates seven strings in the stack memory (thus it cannot be implemented in a function). More...

Detailed Description

Useful common functions and macros.

Author: Miguel Oliveira e Silva, 2017-2018

Macro Definition Documentation

◆ concat_2str

#define concat_2str	(	str1,
		str2
	)

Value:

({ \
           char* s1 = (str1) == NULL ? (char*)"" : (char*)(str1); \
           char* s2 = (str2) == NULL ? (char*)"" : (char*)(str2); \
           char* __res__ = (char*)alloca(strlen(s1)+strlen(s2)+1); \
           strcpy(__res__, s1); \
           strcat(__res__, s2); \
           __res__; \
        })

Concatenates two strings in the stack memory (thus it cannot be implemented in a function).

A NULL reference is treated as an empty string.

Parameters

[in]	str1	string 1
[in]	str2	string 2

Returns: the concatenated string

◆ concat_3str

#define concat_3str	(	str1,
		str2,
		str3
	)

Value:

({ \
           char* s1 = (str1) == NULL ? (char*)"" : (char*)(str1); \
           char* s2 = (str2) == NULL ? (char*)"" : (char*)(str2); \
           char* s3 = (str3) == NULL ? (char*)"" : (char*)(str3); \
           char* __res__ = (char*)alloca(strlen(s1)+strlen(s2)+strlen(s3)+1); \
           strcpy(__res__, s1); \
           strcat(__res__, s2); \
           strcat(__res__, s3); \
           __res__; \
        })

Concatenates three strings in the stack memory (thus it cannot be implemented in a function).

A NULL reference is treated as an empty string.

Parameters

[in]	str1	string 1
[in]	str2	string 2
[in]	str3	string 3

Returns: the concatenated string

◆ concat_4str

#define concat_4str	(	str1,
		str2,
		str3,
		str4
	)

Value:

({ \
           char* s1 = (str1) == NULL ? (char*)"" : (char*)(str1); \
           char* s2 = (str2) == NULL ? (char*)"" : (char*)(str2); \
           char* s3 = (str3) == NULL ? (char*)"" : (char*)(str3); \
           char* s4 = (str4) == NULL ? (char*)"" : (char*)(str4); \
           char* __res__ = (char*)alloca(strlen(s1)+strlen(s2)+strlen(s3)+strlen(s4)+1); \
           strcpy(__res__, s1); \
           strcat(__res__, s2); \
           strcat(__res__, s3); \
           strcat(__res__, s4); \
           __res__; \
        })

Concatenates four strings in the stack memory (thus it cannot be implemented in a function).

A NULL reference is treated as an empty string.

Parameters

[in]	str1	string 1
[in]	str2	string 2
[in]	str3	string 3
[in]	str4	string 4

Returns: the concatenated string

◆ concat_5str

#define concat_5str	(	str1,
		str2,
		str3,
		str4,
		str5
	)

Value:

({ \
           char* s1 = (str1) == NULL ? (char*)"" : (char*)(str1); \
           char* s2 = (str2) == NULL ? (char*)"" : (char*)(str2); \
           char* s3 = (str3) == NULL ? (char*)"" : (char*)(str3); \
           char* s4 = (str4) == NULL ? (char*)"" : (char*)(str4); \
           char* s5 = (str5) == NULL ? (char*)"" : (char*)(str5); \
           char* __res__ = (char*)alloca(strlen(s1)+strlen(s2)+strlen(s3)+strlen(s4)+strlen(s5)+1); \
           strcpy(__res__, s1); \
           strcat(__res__, s2); \
           strcat(__res__, s3); \
           strcat(__res__, s4); \
           strcat(__res__, s5); \
           __res__; \
        })

Concatenates five strings in the stack memory (thus it cannot be implemented in a function).

A NULL reference is treated as an empty string.

Parameters

[in]	str1	string 1
[in]	str2	string 2
[in]	str3	string 3
[in]	str4	string 4
[in]	str5	string 5

Returns: the concatenated string

◆ concat_6str

#define concat_6str	(	str1,
		str2,
		str3,
		str4,
		str5,
		str6
	)

Value:

({ \
           char* s1 = (str1) == NULL ? (char*)"" : (char*)(str1); \
           char* s2 = (str2) == NULL ? (char*)"" : (char*)(str2); \
           char* s3 = (str3) == NULL ? (char*)"" : (char*)(str3); \
           char* s4 = (str4) == NULL ? (char*)"" : (char*)(str4); \
           char* s5 = (str5) == NULL ? (char*)"" : (char*)(str5); \
           char* s6 = (str6) == NULL ? (char*)"" : (char*)(str6); \
           char* __res__ = (char*)alloca(strlen(s1)+strlen(s2)+strlen(s3)+strlen(s4)+strlen(s5)+strlen(s6)+1); \
           strcpy(__res__, s1); \
           strcat(__res__, s2); \
           strcat(__res__, s3); \
           strcat(__res__, s4); \
           strcat(__res__, s5); \
           strcat(__res__, s6); \
           __res__; \
        })

Concatenates six strings in the stack memory (thus it cannot be implemented in a function).

A NULL reference is treated as an empty string.

Parameters

[in]	str1	string 1
[in]	str2	string 2
[in]	str3	string 3
[in]	str4	string 4
[in]	str5	string 5
[in]	str6	string 6

Returns: the concatenated string

◆ concat_7str

#define concat_7str	(	str1,
		str2,
		str3,
		str4,
		str5,
		str6,
		str7
	)

Value:

({ \
           char* s1 = (str1) == NULL ? (char*)"" : (char*)(str1); \
           char* s2 = (str2) == NULL ? (char*)"" : (char*)(str2); \
           char* s3 = (str3) == NULL ? (char*)"" : (char*)(str3); \
           char* s4 = (str4) == NULL ? (char*)"" : (char*)(str4); \
           char* s5 = (str5) == NULL ? (char*)"" : (char*)(str5); \
           char* s6 = (str6) == NULL ? (char*)"" : (char*)(str6); \
           char* s7 = (str7) == NULL ? (char*)"" : (char*)(str7); \
           char* __res__ = (char*)alloca(strlen(s1)+strlen(s2)+strlen(s3)+strlen(s4)+strlen(s5)+strlen(s6)+strlen(s7)+1); \
           strcpy(__res__, s1); \
           strcat(__res__, s2); \
           strcat(__res__, s3); \
           strcat(__res__, s4); \
           strcat(__res__, s5); \
           strcat(__res__, s6); \
           strcat(__res__, s7); \
           __res__; \
        })

Concatenates seven strings in the stack memory (thus it cannot be implemented in a function).

A NULL reference is treated as an empty string.

Parameters

[in]	str1	string 1
[in]	str2	string 2
[in]	str3	string 3
[in]	str4	string 4
[in]	str5	string 5
[in]	str6	string 6
[in]	str7	string 7

Returns: the concatenated string

◆ int2str

#define int2str ( num )

Value:

({ \
           char* __res__ = (char*)alloca(numDigits((int)num)+1); \
           sprintf(__res__, "%d", (int)num); \
           __res__; \
        })

Converts an int value to a stack allocated string.

Parameters

[in] num integer number

Returns: the converted string

◆ int2nstr

#define int2nstr	(	num,
		len
	)

Value:

({ \
           require (len > 0, concat_3str("invalid length value (", int2str(len), ")")); \
           int d = numDigits((int)num); \
           if (len > d) \
              d = len; \
           char* __res__ = (char*)alloca(d+1); \
           sprintf(__res__, "%0*d", d, (int)num); \
           __res__; \
        })

Converts an int value to a stack allocated string.

If necessary, fills the result string with left zeros.

Parameters

[in]	num	integer number
[in]	len	minimum length of result string

Precondition:: len > 0

Returns: the converted string

◆ perc2str

#define perc2str ( percentage )

Value:

({ \
           require (percentage >= 0 && percentage <= 100, concat_3str("invalid percentage value (", int2str(percentage), ")")); \
           char* __res__ = (char*)alloca(4+1); \
           sprintf(__res__, "%3d%%", (int)percentage); \
           __res__; \
        })

Converts an int percentage to a stack allocated string.

Parameters

[in] percentage an integer number with a percentage value

Precondition:: percentage >= 0 && percentage <= 100

Returns: the converted string

◆ length_vargs_string_list

#define length_vargs_string_list ( first )

Value:

({ \
           int __res__ = 0; \
           va_list ap; \
           va_start(ap, first); \
           char* t = first; \
           while (t != NULL) \
           { \
              __res__ += strlen(t); \
              t = va_arg(ap, char*); \
           } \
           va_end(ap); \
           __res__; \
        })

Determines the length of all strings passed as a NULL terminated variable list of arguments (vargs).

Parameters

[in] first the argument that precedes the vargs argument list.

Returns: the sum of the length of all strings (not counting terminator `'\0'`)

◆ not_null

#define not_null ( pnt )

Value:

({ \
           if ((pnt) == NULL) \
           { \
                 fprintf (stderr, "Null pointer error, pointer: \"%s\", function: \"%s\":%d, file: \"%s\"\n", \
                          #pnt, __FUNCTION__, __LINE__ , __FILE__); \
                 *((int*)0) = 0; \
                 abort (); \
           } \
           pnt; \
        })

Checks if address is not NULL, before its application.

This macro is a non-defensive implementation of a null pointer verification. It implements two error handling policies:

EXIT_POLICY (default): describes the error in stderr (with the identification and the precise location of the failure), generates a segmentation fault (enabling a stack trace within a debugger like gdb), and exits program execution;
EXCEPTION_POLICY: throws a char* exception with the description of the failure.

Example: not_null(pnt)->something();

Parameters

[in] pnt memory address

Function Documentation

◆ mem_alloc()

void* mem_alloc ( int size )

A replacement for malloc function.

This function is a non-defensive implementation of malloc error verification. It implements two error handling policies:

EXIT_POLICY (default): describes the error in stderr (with the identification and the precise location of the failure), generates a segmentation fault (enabling a stack trace within a debugger like gdb), and exits program execution;
EXCEPTION_POLICY: throws a char* exception with the description of the failure.

Parameters

[in] size number of bytes to be allocated

Precondition:: size >= 0

Returns: address of the allocated memory

◆ mem_free()

void mem_free ( void * pnt )

A replacement for free function.

Parameters

[in] pnt memory address to be freed

Precondition:: pnt != NULL

◆ string_clone()

char* string_clone ( char * str )

Replicates a string.

The memory is allocated in the heap (using mem_alloc()).

Parameters

[in] str string to be replicated

Precondition:: str != NULL

Returns: pointer to the replicated string

◆ string_num_lines()

int string_num_lines ( char * text )

Number of lines of a string.

Parameters

[in] text string text to process

Precondition:: text != NULL

Returns: number of counted lines

◆ string_num_columns()

int string_num_columns ( char * text )

Maximum number of columns of a string (not counting character `'\n'`).

Parameters

[in] text string text to process

Precondition:: text != NULL

Returns: maximum number of counted columns

◆ string_count_char()

int string_count_char	(	char *	text,
		char *	ch
	)

Counts the number of occurrences of an UTF8 character in a text.

Parameters

[in]	text	string text to process
[in]	ch	string containing the sequence of bytes (one or more) of an UTF8 single character

Precondition:: text != NULL
ch != NULL && num_chars_utf8(ch) == 1

Returns: number of counted occurrences

◆ string_starts_with()

int string_starts_with	(	char *	text,
		char *	prefix
	)

Tests if a string starts with a prefix.

Parameters

[in]	text	string text to process
[in]	prefix	string to test if is a prefix

Precondition:: text != NULL
prefix != NULL

Returns: true (!=0) if prefix starts text, false (0) otherwise

◆ string_ends_with()

int string_ends_with	(	char *	text,
		char *	suffix
	)

Tests if a string ends with a suffix.

Parameters

[in]	text	string text to process
[in]	prefix	string to test if is a suffix

Precondition:: text != NULL
suffix != NULL

Returns: true (!=0) if suffix ends text, false (0) otherwise

◆ string_concat()

char* string_concat	(	char *	res,
		int	max_length,
		char *	text,
			...
	)

Concatenates a NULL terminated list of string arguments.

This function treats all vargs arguments as strings (char*), and requires that the list is terminated with a NULL argument.

It allocates memory in heap (using mem_alloc()) if NULL is passed in the res argument.

Parameters

[in,out]	res	address of result string (if not `NULL`)
[in]	max_length	`res` input argument maximum length (not counting terminator `'\0'`), only applies if`(res != NULL)`
[in]	text	the first string to be used in concatenation

Precondition:: text != NULL
res == NULL || (max_length > 0 && length_vargs_string_list(text) <= max_length)

Returns: the concatenated string

◆ random_boolean()

int random_boolean ( int trueProb )

Generates a random boolean value.

This function generates boolean values with defined probabilities for true (!=0) and false (0) values.

Parameters

[in] trueProb probability (in interval [0;100]).

Precondition:: trueProb >= 0 && trueProb <= 100

Returns: the random boolean value

◆ random_int()

int random_int	(	int	min,
		int	max
	)

Generates a random integer value within a given interval.

This function generates integer values in the interval [min;max]with an uniform distribution for all values.

Parameters

[in]	min	lower value of interval
[in]	max	higher value of interval

Precondition:: max >= min

Returns: the random integer value

◆ random_string()

char* random_string	(	char **	list,
		int *	used,
		int	length
	)

Returns a random string from a given string list.

This function stores the previous randomly selected string's (using the integer indexes of the string list) to disallow its repeated generation.

Parameters

[in]	list	list of strings to be selected (`NULL` terminated)
[in,out]	used	indexes of strings already selected
[in]	length	number of elements of lists `list` (not counting `NULL` entry) and `used`

Precondition:: list != NULL
used != NULL

Returns: the random string

◆ move_cursor()

void move_cursor	(	int	line,
		int	column
	)

Moves the cursor to a position in terminal.

Parameters

[in]	line	position in the terminal
[in]	column	position in the terminal

Precondition:: line >= 0 && column >= 0

◆ string_list_length()

int string_list_length ( char ** list )

Number of elements of a NULL terminated list of strings.

Parameters

[in] list NULL terminated array of strings

Precondition:: list != NULL

Returns: number of elements of list (not counting NULL)

◆ string_list_clone()

char** string_list_clone ( char ** list )

Replicates a NULL terminated list of strings.

The memory is allocated in the heap (using mem_alloc()).

Parameters

[in] list NULL terminated array of strings

Precondition:: list != NULL

Returns: pointer to the replicated list

◆ string_list_free()

char** string_list_free ( char ** list )

Frees the memory allocated to a NULL terminated list of strings.

This function is totally compatible with string_list_clone(), and always returns NULL.

Parameters

[in] list NULL terminated array of strings

Precondition:: list != NULL

Returns: NULL

◆ int2nstring()

char* int2nstring	(	char *	res,
		int	num,
		int	len
	)

Converts an int value to a string.

If necessary, fills the result string with left zeros. It allocates memory in heap (using mem_alloc()) if NULL is passed in the res argument.

Parameters

[in,out]	res	address of result string (if not `NULL`)
[in]	num	integer number
[in]	len	minimum length of result string (not counting terminator `'\0'`)

Precondition:: len >= numDigits(num)

Returns: the converted string

◆ percentage2string()

char* percentage2string	(	char *	res,
		int	percentage
	)

Converts an int percentage to a string.

It allocates memory in heap (using mem_alloc()) if NULL is passed in the res argument.

Parameters

[in,out]	res	address of result string (if not `NULL`)
[in]	percentage	an integer number with a percentage value

Precondition:: percentage >= 0 && percentage <= 100

Returns: the converted string (if not NULL, it returns res)

Files

Macros

Functions

String concatenation in stack memory

Detailed Description

Macro Definition Documentation

◆ concat_2str

◆ concat_3str

◆ concat_4str

◆ concat_5str

◆ concat_6str

◆ concat_7str

◆ int2str

◆ int2nstr

◆ perc2str

◆ length_vargs_string_list

◆ not_null

Function Documentation

◆ mem_alloc()

◆ mem_free()

◆ string_clone()

◆ string_num_lines()

◆ string_num_columns()

◆ string_count_char()

◆ string_starts_with()

◆ string_ends_with()

◆ string_concat()

◆ random_boolean()

◆ random_int()

◆ random_string()

◆ move_cursor()

◆ string_list_length()

◆ string_list_clone()

◆ string_list_free()

◆ int2nstring()

◆ percentage2string()