base.h File Reference

Base functions for Programming I Library. More...

#include <stdio.h>
#include <stdlib.h>
#include <stddef.h>
#include <string.h>
#include <ctype.h>
#include <math.h>
#include <time.h>
#include <stdbool.h>
#include "basedefs.h"

Go to the source code of this file.

Macros
#define	assert(description, condition)
	Checks the given condition.
#define	assert_code(x)   x
	Allows writing code that is meant for use in an assertion.
#define	assert_not_null(pointer)
	Checks that the given pointer is not NULL.
#define	assert_x(description, condition, ...)
	Checks the given condition.
#define	count_if(init, has_more_steps, do_step, condition)
	Counts the number of iteration steps for which the given condition is true.
#define	ensure(description, condition)
	Checks the given postcondition.
#define	ensure_code(x)   x
	Allows writing code that is meant for use in a postcondition.
#define	ensure_not_null(pointer)
	Checks that the given pointer is not NULL.
#define	ensure_x(description, condition, ...)
	Checks the given postcondition.
#define	EPSILON   0.00000001
	A very small positive value.
#define	exists(i, length, condition)
	Checks whether the given condition is true for at least one step of an iteration.
#define	exists_x(init, has_more_steps, do_step, condition)
	Checks whether the given condition is true for at least one step of an iteration.
#define	exit   base_exit
	Exits the process and returns the given status to the operating system.
#define	exit_if(condition, ...)
	Exits the program if the failure condition is true.
#define	forall(i, length, condition)
	Checks whether the given condition is true for all steps of an iteration.
#define	forall_x(init, has_more_steps, do_step, condition)
	Checks whether the given condition is true for all steps of an iteration.
#define	free   base_free
	Frees memory blocks allocated with xmalloc or xcalloc.
#define	NO_ASSERT_DOC
	Switching assertion checking on and off.
#define	NO_ENSURE_DOC
	Switching assertion checking on and off.
#define	NO_REQUIRE_DOC
	Switching assertion checking on and off.
#define	panic(...)
	Exits the program.
#define	panic_if(condition, ...)
	Exits the program if the failure condition is true.
#define	PL   printf("%s:%d\n", __func__, __LINE__)
	Print line number.
#define	PLf(...)
	Print line number and format string.
#define	PLi(i)   printf("%s:%d: %d\n", __func__, __LINE__, i)
	Print line number and integer.
#define	require(description, condition)
	Checks the given precondition.
#define	require_not_null(argument)
	Checks that the given argument is not NULL.
#define	require_x(description, condition, ...)
	Checks the given precondition.
#define	test_equal_b(a, e)   base_test_equal_b(__FILE__, __LINE__, a, e)
	Checks whether the actual boolean (first argument) is equal to the expected boolean (second argument).
#define	test_equal_boa(a, e, ne)   base_test_equal_ba(__FILE__, __LINE__, a, e, ne)
	Checks whether the actual array (first argument) is equal to the expected array (second argument).
#define	test_equal_c(a, e)   base_test_equal_c(__FILE__, __LINE__, a, e)
	Checks whether the actual character (first argument) is equal to the expected character (second argument).
#define	test_equal_ca(a, e, ne)   base_test_equal_ca(__FILE__, __LINE__, a, e, ne)
	Checks whether the actual array (first argument) is equal to the expected array (second argument).
#define	test_equal_i(a, e)   base_test_equal_i(__FILE__, __LINE__, a, e)
	Checks whether the actual int (first argument) is equal to the expected int (second argument).
#define	test_equal_s(a, e)   base_test_equal_s(__FILE__, __LINE__, a, e)
	Checks whether the actual String (first argument) is equal to the expected String (second argument).
#define	test_equal_struct(a, e, p)   base_test_equal_struct(__FILE__, __LINE__, a, e, p)
	Checks whether the actual struct (first argument) is equal to the expected struct (second argument).
#define	test_within_d(a, e, epsilon)   base_test_within_d(__FILE__, __LINE__, a, e, epsilon)
	Checks whether the actual double (first argument) is within +/-epsilon (third argument) of the expected double (second argument).
#define	test_within_i(a, e, epsilon)   base_test_within_i(__FILE__, __LINE__, a, e, epsilon)
	Checks whether the actual int (first argument) is within +/-epsilon (third argument) of the expected int (second argument).
#define	xcalloc(num, size)   base_calloc(__FILE__, __func__, __LINE__, num, size)
	Allocates a block of (num * size) bytes with calloc.
#define	xmalloc(size)   base_malloc(__FILE__, __func__, __LINE__, size)
	Allocates a block of size bytes with xmalloc.
#define	xrealloc(ptr, size)   base_realloc(__FILE__, __func__, __LINE__, ptr, size)
	Reallocates a block of size bytes using realloc.

Functions
bool	b_rnd (void)
	Returns a random Boolean between (true or false) with 50% probability.
bool	base_test_equal_b (const char *file, int line, bool a, bool e)
	Checks whether the actual value a is equal to the expected value e.
bool	base_test_equal_c (const char *file, int line, char a, char e)
	Checks whether the actual value a is equal to the expected value e.
bool	base_test_equal_i (const char *file, int line, int a, int e)
	Checks whether the actual value a is equal to the expected value e.
bool	base_test_equal_s (const char *file, int line, String a, String e)
	Checks whether the actual value a is equal to the expected value e.
bool	base_test_equal_struct (const char *file, int line, Any a, Any e, AnyFn predicate)
	Checks whether the members of struct a are equal to the members of struct e.
bool	base_test_within_d (const char *file, int line, double a, double e, double epsilon)
	Checks whether the actual value a is within +/-epsilon of the expected value e.
bool	base_test_within_i (const char *file, int line, int a, int e, int epsilon)
	Checks whether the actual value a is within +/-epsilon of the expected value e.
double	d_input (void)
	Reads a double from standard input.
double	d_of_s (String s)
	Converts a String to a double.
double	d_rnd (double i)
	Returns a random double between in the interval [0,i).
void	get_line (char *line, int n)
	Reads at most n-1 characters into an existing buffer.
int	i_input (void)
	Reads an integer from standard input.
int	i_of_s (String s)
	Converts a String to an integer.
int	i_rnd (int i)
	Returns a random int between in the interval [0,i).
void	printb (bool b)
	Prints a boolean value.
void	printba (Byte *a, int n)
	Prints a C-array of n Bytes.
void	printbaln (Byte *a, int n)
	Prints a C-array of n Bytes followed by a line break.
void	printbln (bool b)
	Prints a boolean value followed by a line break.
void	printboa (bool *a, int n)
	Prints a C-array of n booleans.
void	printboaln (bool *a, int n)
	Prints a C-array of n booleans followed by a line break.
void	printc (char c)
	Prints a character.
void	printca (char *a, int n)
	Prints a C-array of n characters.
void	printcaln (char *a, int n)
	Prints a C-array of n characters followed by a line break.
void	printcln (char c)
	Prints a character followed by a line break.
void	printd (double d)
	Prints a double.
void	printda (double *a, int n)
	Prints a C-array of n doubles.
void	printdaln (double *a, int n)
	Prints a C-array of n doubles followed by a line break.
void	printdln (double d)
	Prints a double followed by a line break.
void	printi (int i)
	Prints an integer.
void	printia (int *a, int n)
	Prints a C-array of n integers.
void	printialn (int *a, int n)
	Prints a C-array of n integers followed by a line break.
void	printiln (int i)
	Prints an integer followed by a line break.
void	println ()
	Prints a line break.
void	prints (String s)
	Prints a String.
void	printsa (String *a, int n)
	Prints a C-array of n Strings.
void	printsaln (String *a, int n)
	Prints a C-array of n Strings followed by a line break.
void	printsln (String s)
	Prints a String followed by a line break.
void	report_memory_leaks (bool do_check)
	Switches memory checking on or off.
bool	s_contains (String s, String part)
	Returns true iff s contains part.
String	s_copy (String s)
	Creates a copy of the given string.
bool	s_equals (String s, String t)
	Returns true iff s and t are equal.
char	s_get (String s, int i)
	Returns character at index i.
String	s_input (int n)
	Reads at most n-1 characters into a newly allocated string.
int	s_length (String s)
	Returns the length of the string (number of characters).
String	s_read_file (String name)
	Reads the contents of a file into a String.
void	s_set (String s, int i, char c)
	Sets s element at index i to value v.
void	s_write_file (String name, String data)
	Writes a String to a file.
void	write_file_data (String name, Byte *data, int n)
	Writes a memory block to a file.

Detailed Description

Base functions for Programming I Library.

Here you find basic functions for output, input, files, random numbers, dynamic memory allocation, timing, assertions, and testing.

Naming Conventions

Types names are written in upper camel case, such as String, except for predefined type names such as int, double, and bool. This library does not cover type float. This library does not deal with unsigned types.

Function names are written in lower case. Parts within function names are separated with an underscore character, such as in base_init. This makes function names distinguishable from type names.

Constants, such as NULL, are written in upper case. This is independent of whether they have been defined as C constants or with preprocessor define statements.

Type Declarations

The type String is simply defined as a pointer to a character:

typedef char* String;

There are several type declarations for functions. Example:

typedef String (*IntStringToString)(int, String);

The type IntStringToString represents a pointer to a function that takes an integer and a String and returns a String.

Dynamic Memory

Memory is allocated using xmalloc or xcalloc and released with free. These functions (in fact: macros) keep track of allocated memory and report memory leaks. Make sure to always use xmalloc or xcalloc rather than malloc and calloc in your code.

Examples

Example 1: Printing an integer

printiln(123); // print an integer followed by a line break

Output:

123

Example 2: Reading a text file

Let example.txt be

line 1
line II
my line 3
last line

To read this file:

String s = s_read_file("example.txt"); // read the complete file
printsln(s);
free(s); // free the string

Output:

line 1
line II
my line 3
last line

See test functions in .c file for more examples.

Author

Michael Rohs

Date

15.10.2015, 22.09.2020, 25.09.2023

Copyright

Apache License, Version 2.0

Macro Definition Documentation

assert

#define assert	(		description,
			condition
	)

Value:

if (!(condition)) {\
    fprintf(stderr, "%s, line %d: assertion \"%s\" (%s) violated\n", __FILE__, __LINE__, description, #condition);\
    exit(EXIT_FAILURE);\
}

Checks the given condition.

If the condition is true, does nothing. If the condition is false, reports the file and line of the assertion and stops the program. Assertions are conditions that have to be valid at a particular point. If an assertion is false this indicates a bug in the program.

Example use of an assertion:

...
assert("not too large", x < 3);
...

Example output of failed assertions:

myfile.c, line 12: assertion "not too large" (x < 3) violated
myfile.c, line 12: assertion "sorted" (forall(int i = 0, i < n-1, i++, a[i] <= a[i+1])) violated

Parameters

[in]	description	String a description of the condition that has to be valid
[in]	condition	boolean the condition to check

assert_code

#define assert_code

(

x

)

x

Allows writing code that is meant for use in an assertion.

The code is removed if NO_ASSERT is defined.

Example:

assert_code(int old_x = x); // save old value for assertion
x = x + 1;
assert("incremented", x == old_x + 1); // check whether new value is as expected

assert_not_null

#define assert_not_null

(

pointer

)

Value:

if (pointer == NULL) {\
    fprintf(stderr, "%s, line %d: assertion \"not null\" (" #pointer ") violated\n", __FILE__, __LINE__);\
    exit(EXIT_FAILURE);\
}

Checks that the given pointer is not NULL.

If so, does nothing. Otherwise reports the location of the assertion and stops the program. Assertions are conditions that have to be valid at a particular point. If an assertion is false this indicates a bug in the program.

Example use of an assertion:

...
assert_not_null(s);
...

Example output of failed assertion:

myfile.c, line 12: assertion "not null" (s) violated

Parameters

[in]

pointer

a pointer that must not be null

assert_x

#define assert_x	(		description,
			condition,
			...
	)

Value:

if (!(condition)) {\
    fprintf(stderr, "%s, line %d: assertion \"%s\" violated: ", __FILE__, __LINE__, description);\
    fprintf(stderr, __VA_ARGS__);\
    fprintf(stderr, "\n");\
    exit(EXIT_FAILURE);\
}

Checks the given condition.

If the condition is true, does nothing. If the condition is false, reports the file and line of the assertion and stops the program. Assertions are conditions that have to be valid at a particular point. If an assertion is false this indicates a bug in the program.

Example use of an assertion:

...
assert_x("not too large", x < 3, "x == %d", x);
...

Example output of failed assertions:

myfile.c, line 12: assertion "not too large" violated: x == 3
myfile.c, line 12: assertion "sorted" violated: a[2] == 5 && a[3] == 4

Parameters

[in]	description	String a description of the condition that has to be valid
[in]	condition	boolean the condition to check

count_if

#define count_if	(		init,
			has_more_steps,
			do_step,
			condition
	)

Value:

   ({\
   int _count_if_result = 0;\
   for (init; has_more_steps; do_step) { if (condition) { _count_if_result++; } }\
   _count_if_result;\
})

Counts the number of iteration steps for which the given condition is true.

Primarily for use in assertions, preconditions, and postconditions.

Parameters

[in]	init	initialization expression
[in]	has_more_steps	boolean expression for continuing the iteration
[in]	do_step	advance the iteration state
[in]	condition	boolean expression

Returns

the number of iteration steps for which the condition is true

Example: Count the number of non-zero array elements:

int n_non_zero = count_if(int i = 0, i < arr_length, i++, arr[i] != 0);

ensure

#define ensure	(		description,
			condition
	)

Value:

if (!(condition)) {\
    fprintf(stderr, "%s, line %d: %s's postcondition \"%s\" (%s) violated\n", __FILE__, __LINE__, __func__, description, #condition);\
    exit(EXIT_FAILURE);\
}

Checks the given postcondition.

If the condition is true, does nothing. If the condition is false, reports the location of the postcondition and stops the program. A postcondition is a special type of assertion that has to be valid before returning from a function.

Example use of a postcondition:

int myfunction(...) {
    int result = 0;
    ...
    ensure("not negative", result >= 0);
    return result;
}

Example output of failed postconditions:

myfile.c, line 12: myfunction's postcondition "not negative" (result >= 0) violated
myfile.c, line 12: myfunction's postcondition "sorted" (forall(int i = 0, i < n-1, i++, a[i] <= a[i+1])) violated

Parameters

[in]	description	String a description of the condition that has to be valid
[in]	condition	boolean the condition to check

ensure_code

#define ensure_code

(

x

)

x

Allows writing code that is meant for use in a postcondition.

The code is removed if NO_ENSURE is defined.

Example:

int inc(int x) {
    ensure_code(int old_x = x); // save old value for postcondition
    x = x + 1;
    ensure("incremented", x == old_x + 1); // check whether new value is as expected
    return x;
}

ensure_not_null

#define ensure_not_null

(

pointer

)

Value:

if (pointer == NULL) {\
    fprintf(stderr, "%s, line %d: %s's postcondition \"not null\" (" #pointer ") violated\n", __FILE__, __LINE__, __func__);\
    exit(EXIT_FAILURE);\
}

Checks that the given pointer is not NULL.

If so, does nothing. Otherwise reports the location of the postcondition and stops the program. A postcondition is a special type of assertion that has to be valid before returning from a function.

Example use of a postcondition:

...
ensure_not_null(s);
...

Example output of failed postcondition:

myfile.c, line 12: myfunction's postcondition "not null" (s) violated

Parameters

[in]

pointer

a pointer that must not be null

ensure_x

#define ensure_x	(		description,
			condition,
			...
	)

Value:

if (!(condition)) {\
    fprintf(stderr, "%s, line %d: %s's postcondition \"%s\" violated: ", __FILE__, __LINE__, __func__, description);\
    fprintf(stderr, __VA_ARGS__);\
    fprintf(stderr, "\n");\
    exit(EXIT_FAILURE);\
}

Checks the given postcondition.

If the condition is true, does nothing. If the condition is false, reports the location of the postcondition and stops the program. A postcondition is a special type of assertion that has to be valid before returning from a function.

Example use of a postcondition:

int myfunction(...) {
    int result = 0;
    ...
    ensure_x("not negative", result >= 0, "result == %d", result);
    return result;
}

Example output of failed postconditions:

myfile.c, line 12: myfunction's postcondition "not negative" (result >= 0) violated
myfile.c, line 12: myfunction's postcondition "sorted" violated: a[2] == 5 && a[3] == 4

Parameters

[in]	description	String a description of the condition that has to be valid
[in]	condition	boolean the condition to check

EPSILON

#define EPSILON   0.00000001

A very small positive value.

exists

#define exists	(		i,
			length,
			condition
	)

Value:

   ({\
   bool _exists_result = false;\
   for (int i = 0; i < length; i++) { if (condition) { _exists_result = true; break; } }\
   _exists_result;\
})

Checks whether the given condition is true for at least one step of an iteration.

Primarily for use in assertions, preconditions, and postconditions.

Parameters

[in]	i	name of iteration variable
[in]	length	number of iteration steps, i in [0, length)
[in]	condition	boolean expression to check for each iteration step

Returns

true if the condition is true for at least one step of the iteration, false otherwise

Example: Checking whether an array contains negative elements:

bool has_negative_elements = exists(k, arr_length, arr[k] < 0);

exists_x

#define exists_x	(		init,
			has_more_steps,
			do_step,
			condition
	)

Value:

   ({\
   bool _exists_result = false;\
   for (init; has_more_steps; do_step) { if (condition) { _exists_result = true; break; } }\
   _exists_result;\
})

Checks whether the given condition is true for at least one step of an iteration.

Primarily for use in assertions, preconditions, and postconditions.

Parameters

[in]	init	initialization expression
[in]	has_more_steps	boolean expression for continuing the iteration
[in]	do_step	advance the iteration state
[in]	condition	boolean expression to check for each iteration step

Returns

true if the condition is true for at least one step of the iteration, false otherwise

Example: Checking whether an array contains negative elements:

bool has_negative_elements = exists_x(int i = 0, i < arr_length, i++, arr[i] < 0);

exit

#define exit   base_exit

Exits the process and returns the given status to the operating system.

Parameters

[in]

status

(int) exit status of the process

exit_if

#define exit_if	(		condition,
			...
	)

Value:

if (condition) {\
    flockfile(stderr);\
    fprintf(stderr, __VA_ARGS__);\
    fprintf(stderr, "\n");\
    funlockfile(stderr);\
    exit(EXIT_FAILURE);\
}

Exits the program if the failure condition is true.

The further arguments contain the reason for exiting the program, using a format string.

forall

#define forall	(		i,
			length,
			condition
	)

Value:

   ({\
   bool _forall_result = true;\
   for (int i = 0; i < length; i++) { if (!(condition)) { _forall_result = false; break; } }\
   _forall_result;\
})

Checks whether the given condition is true for all steps of an iteration.

Primarily for use in assertions, preconditions, and postconditions.

Parameters

[in]	i	name of iteration variable
[in]	length	number of iteration steps, i in [0, length)
[in]	condition	boolean expression to check for each iteration step

Returns

true if the condition is true for all steps of the iteration, false otherwise

Example: Checking whether an array is sorted:

bool is_sorted = forall(k, arr_length - 1, arr[k] <= arr[k+1]);

forall_x

#define forall_x	(		init,
			has_more_steps,
			do_step,
			condition
	)

Value:

   ({\
   bool _forall_result = true;\
   for (init; has_more_steps; do_step) { if (!(condition)) { _forall_result = false; break; } }\
   _forall_result;\
})

Checks whether the given condition is true for all steps of an iteration.

Primarily for use in assertions, preconditions, and postconditions.

Parameters

[in]	init	initialization expression
[in]	has_more_steps	boolean expression for continuing the iteration
[in]	do_step	advance the iteration state
[in]	condition	boolean expression to check for each iteration step

Returns

true if the condition is true for all steps of the iteration, false otherwise

Example: Checking whether an array is sorted:

bool is_sorted = forall_x(int i = 0, i < arr_length - 1, i++, arr[i] <= arr[i+1]);

free

#define free   base_free

Frees memory blocks allocated with xmalloc or xcalloc.

Parameters

[in]

p

pointer to memory block to free

NO_ASSERT_DOC

#define NO_ASSERT_DOC

Switching assertion checking on and off.

If NO_ASSERT is defined, then assertions will not be compiled.

NO_ENSURE_DOC

#define NO_ENSURE_DOC

Switching assertion checking on and off.

If NO_ENSURE is defined, then postconditions will not be compiled.

NO_REQUIRE_DOC

#define NO_REQUIRE_DOC

Switching assertion checking on and off.

If NO_REQUIRE is defined, then preconditions will not be compiled.

panic

#define panic

(

...

)

Value:

    {\
    flockfile(stderr);\
    fprintf(stderr, "%s:%d, %s: ", __FILE__, __LINE__, __func__);\
    fprintf(stderr, __VA_ARGS__);\
    fprintf(stderr, "\n");\
    funlockfile(stderr);\
    exit(EXIT_FAILURE);\
}

Exits the program.

The arguments contain the reason for the panic, using a format string. Reports the line number and the reason for the failure.

panic_if

#define panic_if	(		condition,
			...
	)

Value:

if (condition) {\
    flockfile(stderr);\
    fprintf(stderr, "%s:%d, %s: ", __FILE__, __LINE__, __func__);\
    fprintf(stderr, __VA_ARGS__);\
    fprintf(stderr, "\n");\
    funlockfile(stderr);\
    exit(EXIT_FAILURE);\
}

Exits the program if the failure condition is true.

The further arguments contain the reason for the panic, using a format string. Reports the line number and the reason for the failure.

PL

#define PL   printf("%s:%d\n", __func__, __LINE__)

Print line number.

Example: PL;

PLf

#define PLf

(

...

)

Value:

        {\
        fprintf(stderr, "%s:%d: ", __func__, __LINE__);\
        fprintf(stderr, __VA_ARGS__);\
        fprintf(stderr, "\n");\
    }

Print line number and format string.

Example: PLf("i = %d", 123);

PLi

#define PLi

(

i

)

printf("%s:%d: %d\n", __func__, __LINE__, i)

Print line number and integer.

Example: PL(1);

require

#define require	(		description,
			condition
	)

Value:

if (!(condition)) {\
    fprintf(stderr, "%s, line %d: %s's precondition \"%s\" (%s) violated\n", __FILE__, __LINE__, __func__, description, #condition);\
    exit(EXIT_FAILURE);\
}

Checks the given precondition.

If the condition is true, does nothing. If the condition is false, reports the location of the precondition and stops the program. A precondition is a special type of assertion that has to be valid at the beginning of a function.

Example use of a precondition:

int myfunction(int x) {
    require("not too large", x < 3);
    ...
}

Example output of failed preconditions:

myfile.c, line 12: myfunction's precondition "not too large" (x < 3) violated
myfile.c, line 12: myfunction's precondition "sorted" (forall(int i = 0, i < n-1, i++, a[i] <= a[i+1])) violated

Parameters

[in]	description	String a description of the condition that has to be valid
[in]	condition	boolean the condition to check

require_not_null

#define require_not_null

(

argument

)

Value:

if (argument == NULL) {\
    fprintf(stderr, "%s, line %d: %s's precondition \"not null\" (" #argument ") violated\n", __FILE__, __LINE__, __func__);\
    exit(EXIT_FAILURE);\
}

Checks that the given argument is not NULL.

If so, does nothing. Otherwise reports the location of the precondition and stops the program. A precondition is a special type of assertion that has to be valid at the beginning of a function.

Example use of a precondition:

int myfunction(String s) {
    require_not_null(s);
    ...
}

Example output of failed preconditions:

myfile.c, line 12: myfunction's precondition "not null" (s) violated

Parameters

[in]

argument

pointer a pointer that must not be null

require_x

#define require_x	(		description,
			condition,
			...
	)

Value:

if (!(condition)) {\
    fprintf(stderr, "%s, line %d: %s's precondition \"%s\" violated: ", __FILE__, __LINE__, __func__, description);\
    fprintf(stderr, __VA_ARGS__);\
    fprintf(stderr, "\n");\
    exit(EXIT_FAILURE);\
}

Checks the given precondition.

If the condition is true, does nothing. If the condition is false, reports the location of the precondition and stops the program. A precondition is a special type of assertion that has to be valid at the beginning of a function.

Example use of a precondition:

int myfunction(int x) {
    require_x("not too large", x < 3, "x == %d", x);
    ...
}

Example output of failed preconditions:

myfile.c, line 12: myfunction's precondition "not too large" violated: x == 3
myfile.c, line 12: myfunction's precondition "sorted" violated: a[2] == 5 && a[3] == 4

Parameters

[in]	description	String a description of the condition that has to be valid
[in]	condition	boolean the condition to check

test_equal_b

#define test_equal_b	(		a,
			e
	)		base_test_equal_b(__FILE__, __LINE__, a, e)

Checks whether the actual boolean (first argument) is equal to the expected boolean (second argument).

test_equal_boa

#define test_equal_boa	(		a,
			e,
			ne
	)		base_test_equal_ba(__FILE__, __LINE__, a, e, ne)

Checks whether the actual array (first argument) is equal to the expected array (second argument).

test_equal_c

#define test_equal_c	(		a,
			e
	)		base_test_equal_c(__FILE__, __LINE__, a, e)

Checks whether the actual character (first argument) is equal to the expected character (second argument).

test_equal_ca

#define test_equal_ca	(		a,
			e,
			ne
	)		base_test_equal_ca(__FILE__, __LINE__, a, e, ne)

Checks whether the actual array (first argument) is equal to the expected array (second argument).

test_equal_i

#define test_equal_i	(		a,
			e
	)		base_test_equal_i(__FILE__, __LINE__, a, e)

Checks whether the actual int (first argument) is equal to the expected int (second argument).

test_equal_s

#define test_equal_s	(		a,
			e
	)		base_test_equal_s(__FILE__, __LINE__, a, e)

Checks whether the actual String (first argument) is equal to the expected String (second argument).

test_equal_struct

#define test_equal_struct	(		a,
			e,
			p
	)		base_test_equal_struct(__FILE__, __LINE__, a, e, p)

Checks whether the actual struct (first argument) is equal to the expected struct (second argument).

test_within_d

#define test_within_d	(		a,
			e,
			epsilon
	)		base_test_within_d(__FILE__, __LINE__, a, e, epsilon)

Checks whether the actual double (first argument) is within +/-epsilon (third argument) of the expected double (second argument).

test_within_i

#define test_within_i	(		a,
			e,
			epsilon
	)		base_test_within_i(__FILE__, __LINE__, a, e, epsilon)

Checks whether the actual int (first argument) is within +/-epsilon (third argument) of the expected int (second argument).

xcalloc

#define xcalloc	(		num,
			size
	)		base_calloc(__FILE__, __func__, __LINE__, num, size)

Allocates a block of (num * size) bytes with calloc.

Exits with error message on failure. The allocated bytes are set to zero (the initial c in calloc stands for clear).

Parameters

[in]	num	number of elements
[in]	size	size (in bytes) of each element

Returns

pointer to the allocated memory block

See also

xrealloc, xmalloc, free

xmalloc

#define xmalloc

(

size

)

base_malloc(__FILE__, __func__, __LINE__, size)

Allocates a block of size bytes with xmalloc.

Exits with an error message on failure. The contents of the allocated memory block is not initialized (i.e., the memory block contains arbitrary values).

Parameters

[in]

size

number of bytes to allocate

Returns

pointer to the allocated memory block

See also

xrealloc, xcalloc, free

xrealloc

#define xrealloc	(		ptr,
			size
	)		base_realloc(__FILE__, __func__, __LINE__, ptr, size)

Reallocates a block of size bytes using realloc.

Exits with error message on failure. The contents of the allocated memory block is not initialized (i.e., the memory block contains arbitrary values).

Parameters

[in]	ptr	pointer to reallocate
[in]	size	number of bytes to allocate

Returns

pointer to the reallocated memory block

See also

xcalloc, xmalloc, free

Function Documentation

b_rnd()

bool b_rnd

(

void

)

Returns a random Boolean between (true or false) with 50% probability.

Returns

true or false

base_test_equal_b()

bool base_test_equal_b	(	const char *	file,
		int	line,
		bool	a,
		bool	e
	)

Checks whether the actual value a is equal to the expected value e.

base_test_equal_c()

bool base_test_equal_c	(	const char *	file,
		int	line,
		char	a,
		char	e
	)

Checks whether the actual value a is equal to the expected value e.

base_test_equal_i()

bool base_test_equal_i	(	const char *	file,
		int	line,
		int	a,
		int	e
	)

Checks whether the actual value a is equal to the expected value e.

base_test_equal_s()

bool base_test_equal_s	(	const char *	file,
		int	line,
		String	a,
		String	e
	)

Checks whether the actual value a is equal to the expected value e.

base_test_equal_struct()

bool base_test_equal_struct	(	const char *	file,
		int	line,
		Any	a,
		Any	e,
		AnyFn	predicate
	)

Checks whether the members of struct a are equal to the members of struct e.

Uses the given predicate function to perform the comparison.

base_test_within_d()

bool base_test_within_d	(	const char *	file,
		int	line,
		double	a,
		double	e,
		double	epsilon
	)

Checks whether the actual value a is within +/-epsilon of the expected value e.

base_test_within_i()

bool base_test_within_i	(	const char *	file,
		int	line,
		int	a,
		int	e,
		int	epsilon
	)

Checks whether the actual value a is within +/-epsilon of the expected value e.

d_input()

double d_input

(

void

)

Reads a double from standard input.

The input has to be terminated by a line break.

d_of_s()

double d_of_s

(

String

s

)

Converts a String to a double.

d_rnd()

double d_rnd

(

double

i

)

Returns a random double between in the interval [0,i).

0 is inclusive, i is exclusive.

Parameters

[in]

i

upper boundary (exclusive)

Returns

a double value between 0 (inclusive) and i (exclusive)

Precondition

"positive range", i > 0

get_line()

void get_line	(	char *	line,
		int	n
	)

Reads at most n-1 characters into an existing buffer.

Stops reading if newline or end-of-file have been reached. Does not return the newline character.

Parameters

[in,out]	line	buffer to write into (size of buffer at least n bytes), whill be a zero-terminated String
[in]	n	maximum number of bytes to read, has to be at least 8

Precondition

"not too small", n >= 8

See also

s_input

i_input()

int i_input

(

void

)

Reads an integer from standard input.

The input has to be terminated by a line break.

i_of_s()

int i_of_s

(

String

s

)

Converts a String to an integer.

i_rnd()

int i_rnd

(

int

i

)

Returns a random int between in the interval [0,i).

0 is inclusive, i is exclusive.

Parameters

[in]

i

upper boundary (exclusive)

Returns

an integer value between 0 (inclusive) and i (exclusive)

Precondition

"positive range", i > 0

printb()

void printb

(

bool

b

)

Prints a boolean value.

printba()

void printba	(	Byte *	a,
		int	n
	)

Prints a C-array of n Bytes.

printbaln()

void printbaln	(	Byte *	a,
		int	n
	)

Prints a C-array of n Bytes followed by a line break.

printbln()

void printbln

(

bool

b

)

Prints a boolean value followed by a line break.

printboa()

void printboa	(	bool *	a,
		int	n
	)

Prints a C-array of n booleans.

printboaln()

void printboaln	(	bool *	a,
		int	n
	)

Prints a C-array of n booleans followed by a line break.

printc()

void printc

(

char

c

)

Prints a character.

printca()

void printca	(	char *	a,
		int	n
	)

Prints a C-array of n characters.

printcaln()

void printcaln	(	char *	a,
		int	n
	)

Prints a C-array of n characters followed by a line break.

printcln()

void printcln

(

char

c

)

Prints a character followed by a line break.

printd()

void printd

(

double

d

)

Prints a double.

printda()

void printda	(	double *	a,
		int	n
	)

Prints a C-array of n doubles.

printdaln()

void printdaln	(	double *	a,
		int	n
	)

Prints a C-array of n doubles followed by a line break.

printdln()

void printdln

(

double

d

)

Prints a double followed by a line break.

printi()

void printi

(

int

i

)

Prints an integer.

printia()

void printia	(	int *	a,
		int	n
	)

Prints a C-array of n integers.

printialn()

void printialn	(	int *	a,
		int	n
	)

Prints a C-array of n integers followed by a line break.

printiln()

void printiln

(

int

i

)

Prints an integer followed by a line break.

println()

void println

(

)

Prints a line break.

prints()

void prints

(

String

s

)

Prints a String.

printsa()

void printsa	(	String *	a,
		int	n
	)

Prints a C-array of n Strings.

printsaln()

void printsaln	(	String *	a,
		int	n
	)

Prints a C-array of n Strings followed by a line break.

printsln()

void printsln

(

String

s

)

Prints a String followed by a line break.

report_memory_leaks()

void report_memory_leaks

(

bool

do_check

)

Switches memory checking on or off.

If on, checks for memory leaks when thr program terminates.

Parameters

[in]

do_check

if true, then memory is checked

s_contains()

bool s_contains	(	String	s,
		String	part
	)

Returns true iff s contains part.

Parameters

[in]	s	input string
[in]	part	input string

Returns

true iff s contains part

s_copy()

String s_copy

(

String

s

)

Creates a copy of the given string.

Memory of copy is dynamically allocated.

Parameters

[in]

s

input string

Returns

copy of input string

s_equals()

bool s_equals	(	String	s,
		String	t
	)

Returns true iff s and t are equal.

Parameters

[in]	s	input string
[in]	t	input string

Returns

true iff s and t are equal

s_get()

char s_get	(	String	s,
		int	i
	)

Returns character at index i.

Parameters

[in]	s	input string
[in]	i	index of character to return

Returns

character at index i

Precondition

"index in range", i >= 0 && i < length

s_input()

String s_input

(

int

n

)

Reads at most n-1 characters into a newly allocated string.

Stops reading if newline or end-of-file is reached. Does not return the newline character.

Parameters

[in]

n

maximum number of bytes to read, has to be at least 8

Returns

newly allocated String with bytes read

See also

get_line

s_length()

int s_length

(

String

s

)

Returns the length of the string (number of characters).

Parameters

[in]

s

input string

Returns

number of characters

s_read_file()

String s_read_file

(

String

name

)

Reads the contents of a file into a String.

The function fails if the file does not exist or cannot be read.

Parameters

[in]

name

file name (including path)

Returns

newly allocated String with data read from file

See also

s_write_file, write_file_data

s_set()

void s_set	(	String	s,
		int	i,
		char	c
	)

Sets s element at index i to value v.

Parameters

[in,out]	s	input string
[in]	i	index of character to set
[in]	c	character to set

Precondition

"index in range", i >= 0 && i < length

s_write_file()

void s_write_file	(	String	name,
		String	data
	)

Writes a String to a file.

An existing file of the same name will be overwritten.

Parameters

[in]	name	file name (including path)
[in]	data	the data to write to the file

See also

s_read_file, write_file_data

write_file_data()

void write_file_data	(	String	name,
		Byte *	data,
		int	n
	)

Writes a memory block to a file.

An existing file of the same name will be overwritten.

Parameters

[in]	name	file name (including path)
[in]	data	the data to write to the file
[in]	n	the number of bytes to write to the file

Precondition

"non-negative length", n >= 0

See also

s_read_file, s_write_file