Reuse library
user manual

Alexander Chernov

This manual documents Reuse library used by Rasta development team. The description corresponds to version 1.0.3 of January, 30.

Function prorotypes that are defined in this documentation differs from these you actually find in header files. In fact these prototypes are much like C++ prototypes when actually Reuse library is written in ANSI C. Anyway, these prototypes indicate usage of function rather that their definition in the sources.

CONTENTS

• General definitions
• Character strings (flexible strings)

General definitions

Reuse library provides a way of portable definition of such widely used types as unsigned types, types with fixed size, boolean types, etc. Certain operating systems provide definitions of some of them but other provide definitions for other part. During the installation of reuse library these system dependencies are checked automatically.

Interface file name: Defs.h

This file automatically includes <sys/types.h> (if such exists on your system) to include some system definitions.

Defined types:

Character strings

Reuse library introduce a facility to handle character strings which maximal size is unknown at compilation time. Storage for such strings (called flexible strings) is allocated in heap area and automatically extended when necessary.

Interface file name: FlexString.h

Module usage:

Before using any functions from this module function fsInitModule must be called. Prior to program exit function fsCloseModule might be called to release memory allocated for internal structures. Call to this function is not mandatory, though.

Defined types:

Type literals:

Manipulations:

The following functions are defined for manipulations over flexible strings:

void fsInitModule(void);
Initializes the flexible string module in the whole. Sets up internal variables, allocates heap space for internal tables, etc. This function must be called prior any use of functions from the module. Put call of the function in your program startup code. The module is protected against double initialization, so all calls to the function after the first will do nothing. Note, that certain reuse modules requests initialization of this module on their behalf if they use functions of this module.

void fsCloseModule(void);
Finalizes the flexible string module. Deallocates allocated space, etc. Puts the module to uninitialized state, so in order to use it the module must be initialized again.

void fsStatistics(FILE *out);
Reports some statistics about module usage. Current version of the function does nothing, though.

void fsInit(tFString &s);
Initializes the string s. Initialization must be performed before use of a string variable unless it's a static or a global variable, which is initialized by default or might be initialized explicitly with fsNULL value. If this function is applied to the string with definite value, the value becames of empty string, but it causes memory leak, so do not initialize flexible string twice. Unlike the following function the function does not assign any heap memory for a string, it just initializes pointer to the actual location of string to NULL. So calls to fsString will return NULL pointer until the value of string is changed. Such behavous (that fsString might return NULL pointer) is a feature. To avoid it use the following function.

void fsInitEmpty(tFString &s);
Initializes the string s. Like the previous function assigns to s value of empty string, but unlike the previous function allocates space for a string terminator character. After such initialization calls to fsString (until value of the string is changed) will return empty string rather then NULL pointer. This function has no equivalent literal (like fsInit has literal fsNULL which can be used for initialization of static and global flexible strings), so the function must be applied to all required flexible string variables explicity.

void fsDestroy(tFString &s);
Finalizes the string s. Releases heap memory allocated for the string and sets it's value to empty string. Note, however, that the string remains in definite state as being empty string, so the subsequent action are possible without reinitializing of the string. Result of destroying of uninialized string is undefined (could well be a system crash immediately or later due to call to free with an invalid address), destroying of already destroyed string is safe and does nothing. If an automatic flexible string variable is initialized but is not finalized, a memory leak occurs.

void fsClear(tFString &s);
Clears string s, but does not deallocate memory used by that string. Since heap memory allocation is fairly expensive operation which might involve system calls, it's desirable (from the point of view of efficiency) to hold the storage allocated to speed up the following manipulations. If however, the storage needs to be deallocated, use function fsDestroy.

void fsAlloc(tFString &s, size_t size);
Allocates enough memory in flexible string s for storing a string of length size. size argument must count space for storing string terminator '\0'. The functions only extends allocated space, but do not alter string's value. If current string size is larger that the requested, string is not truncated and no other action is performed.

void fsAdd(tFString &s, char c);
Adds character c to the string s. Character must not be a null character '\0'.

void fsAppend(tFString &s, char const *str);
Adds null-terminated character string str to the flexible string s. str might be NULL, in this case it's considered as a pointer to an empty string "".

void fsConcat(tFString &s, tFString const &s2);
Concatenates two flexible strings. String s is updated and string s2 left intact.

void fsAddMem(tFString &s, char const *str, int len);
Adds len characters pointed by str to the flexible string s. Added characters must not contain '\0' characters. str might be NULL or len might be 0, in both cases no action is performed. If len is less than zero program aborted on failed assertion.

void fsInsChar(tFString &s, char c, int pos);
Inserts a character c into the flexible string s at position pos. The character must not be a null character '\0'. Position 0 is the first position in the string, and position fsLength(s) is the position after the last character of the string. Valid positions lies beetween these values, if the position is less than 0, or greater than string length, range error reported and the program aborts.
Note, that fsAdd(s,c) is equivalent to fsInsChar(s,c,fsLength(s)).

void fsInsStr(tFString &s, char const *str, int pos);
Inserts a null-terminated character string str into a flexible string s at position pos. str might be a NULL pointer, then no actions is performed. Position numeration is explained in the description of the function description. If the position is invalid, range check error is reported and program aborts. Note, that fsAppend(s,str) is equivalent to fsInsStr(s,str,fsLength(s)).

void fsInsMem(tFString &s, char const *mem, int len, int pos);
Inserts len characters pointer by mem to flexible string s at position pos. The character array must not contain character '\0'. If mem is NULL or len is 0, no action is performed. If len is less that zero, assertion is failed and the program aborts. If the insert position is invalid, range check error is reported and program aborts.

void fsInsFS(tFString &s, tFString const &s2, int pos);
Inserts flexible string s2 into flexible string s at position pos. If the insert position is out of string bounds, range check error is reported and program aborts.

void fsCut(tFString &s, int pos, int len);
Cuts substring from the flexible string s. The substring starts at position pos and has length of len characters. Valid ranges for starting position and substring length are extended as described below:

• if position is >= 0, the position is counted from the beginning of the string, i. e 0 means the first position and fsLength(s)-1 is the last position.
• if position is less than 0, the position is counted from the tail of the string, i. e -1 stands for the last position and -fsLength(s) is the first position in the string.
• if position is greater than fsLength(s)-1 or is less than -fsLength(s), such position is considered invalid, range check error is reported and program aborts.
• if substring length is >= 0, character at position pos is considered as the first character of the substring to be deleted. The last character in the substring is at position (provided pos is positive) pos + len -1.
• if substring length is less than 0, character at position pos is considered as the last character of the substring to be deleted. The first character of the substring has position
  (provided pos is positive) pos + len.

int fsLength(tFString const &s);
Returns the length of the flexible string. If the flexible string is empty, zero is returned. Terminating '\0' character is not counted. So the behavour is alike to the behaviour of strlen.

char *fsString(tFString const &s);
Returns the pointer to the internal array of characters that constitute the string s. This character array is terminated with '\0' character, so it can be considered as an ordinary C string and can be manipulated either manually or passed as argument to functions that acceps character strings. But you must obey the following don'ts:

You are not recommended to do the following:

1. Extend the string by appending other strings (e. g. via strcat) or characters, for example by overriding the terminator null character with another character.
2. Effectively truncate the string by insertion of '\0' character into the string.
3. Completely overwrite the string giving it as a parameter for functions like strcpy or sprintf.

If these limitations are not obeyed program can easily crash. The last limitation looks most restrictive and it could be raised someday. However, you should feel free for doing the following:

1. Overwriting any non-terminating characters of the string with other non-null characters.
2. Pass the string as a constant parameter to functions that require a string argument, for example, strcmp or printf.

If the string is empty the function returns either "" (pointer to null character) or NULL pointer. NULL is only returned when the flexible string s was initialized with fsInit, but no characters were put to it. When the string has non-empty value and cleared using fsClear, empty string is returned rather than NULL pointer. This feature might be annoying, in order for the function to return empty string the string should be initialized using fsInitEmpty function.

char *fsDup(tFString const &s);
Allocates memory block at the heap and copies value of flexible string s into that block. Returns pointer to the allocated block, or NULL if memory allocation failed (not enough memory). If the function succeeded address returned by the function poins to array of characters, terminated with '\0' character, this array can be handled as a C string. User should take care of deallocating of the memory block (using free) when it is no longer used, or memory leaks may occur.

char *fsDup2(tFString const &s, void *(*alloc_func)(size_t));
Allocates memory block using user provided memory allocation routine alloc_func and copies value of flexible string s to the allocated block. User allocation function should return pointer to an allocated memory block, or NULL if no free memory available and accepts a single parameter which contains required size of memory block. Function fsDup2 returns pointer to an array of characters, terminated with '\0' character, or NULL, if user provided allocation function returns NULL.

void fsAssign(tFString &d, tFString const &s);

void fsCopy(tFString &d, tFString const &s);

void fsPut(tFString const &s, FILE *f);

void fsGet(tFString &s, FILE *f);

void fsWrite(tFString const &s, FILE *f);

void fsRead(tFString &s, FILE *f);

Bool fsInt(tFString const &s, int *i);

Bool fsDouble(tFstring const &s, FILE *f);

void fsUpperCase(tFString &s);

void fsLowerCase(tFString &s);

Example:

Alexander Chernov