Module mstr [Version: v01]

[Documentation]

[Details]

[Wiki]

[Tests]

This documentation describes the Prokee module interface.

Templates

Show templates with parameter T set to: (T), (char), (char16_t), (char32_t), (wchar_t )

About

This module provides basic functionality for strings (like copying, concatenation and comparison) with automated reallocation of larger memory blocks, if required.

Static Template Methods:

create
template< class T > mstrs< T > *mstr::create(mstrs< T > **mstring,unsigned int length)

create_from_str (version 1)
template< class T > mstrs< T > *mstr::create_from_str(mstrs< T > **mstring,const T *c_str)

create_from_str (version 2)
template< class T > mstrs< T > *mstr::create_from_str(mstrs< T > **mstring,const T *c_str,unsigned int length)

destroy
template< class T > void mstr::destroy(mstrs< T > *mstring)

length
template< class T > unsigned int mstr::length(mstrs< T > *mstring)

buffer_length
template< class T > unsigned int mstr::buffer_length(mstrs< T > *mstring)

buffer_bytes
template< class T > unsigned int mstr::buffer_bytes(mstrs< T > *mstring)

used_memory
template< class T > unsigned int mstr::used_memory(mstrs< T > *mstring)

cpy
template< class T > mstrs< T > *mstr::cpy(mstrs< T > *mstring_a,mstrs< T > *mstring_b)

cat
template< class T > mstrs< T > *mstr::cat(mstrs< T > *mstring_a,mstrs< T > *mstring_b)

cmp
template< class T > int mstr::cmp(mstrs< T > *mstring_a,mstrs< T > *mstring_b)

fit
template< class T > mstrs< T > *mstr::fit(mstrs< T > *mstring)

reset
template< class T > mstrs< T > *mstr::reset(mstrs< T > *mstring)

c_str
template< class T > T *mstr::c_str(mstrs< T > *mstring)

copy_str
template< class T > mstrs< T > *mstr::copy_str(mstrs< T > *mstring,const T *c_str)

append_str
template< class T > mstrs< T > *mstr::append_str(mstrs< T > *mstring,const T *c_str)

compare_str
template< class T > int mstr::compare_str(mstrs< T > *mstring,const T *c_str)

is_prefix (version 1)
template< class T > bool mstr::is_prefix(mstrs< T > *str,mstrs< T > *prefix)

is_prefix (version 2)
template< class T > bool mstr::is_prefix(const T *c_str,mstrs< T > *prefix)

is_prefix (version 3)
template< class T > int mstr::is_prefix(const T *c_str,mstrs< T > **prefix)

Static Template Methods

create

Returns a new empty string.

Signature:

template< class T > mstrs< T > *mstr::create(mstrs< T > **mstring,unsigned int length)

Parameters:

Type	Name	Direction	Description
mstrs< T > **	mstring	[OUT]	Address of a Pointer of type (mstrs< T > *).
unsigned int	length		The initial length (in number of characters) of the memory block to store the string.

Return value:
A pointer to the new allocated mstrs structure.

create_from_str (version 1)

Constructs a new mstrs structure.

Signature:

template< class T > mstrs< T > *mstr::create_from_str(mstrs< T > **mstring,const T *c_str)

Parameters:

Type	Name	Direction	Description
mstrs< T > **	mstring	[OUT]	Address of a Pointer of type (mstrs< T > *).
const T *	c_str	[IN]	Pointer to a null-terminated string.

Return value:
A pointer to the new allocated mstrs structure.

create_from_str (version 2)

Constructs a new mstrs structure.

Signature:

template< class T > mstrs< T > *mstr::create_from_str(mstrs< T > **mstring,const T *c_str,unsigned int length)

Parameters:

Type	Name	Direction	Description
mstrs< T > **	mstring	[OUT]	Address of a Pointer of type (mstrs< T > *).
const T *	c_str	[IN]	Pointer to a null-terminated string.
unsigned int	length		The initial length (in number of characters) of the memory block to store the string.

Return value:
A pointer to the new allocated mstrs structure.

destroy

Frees all memory allocated for mstring.

Signature:

template< class T > void mstr::destroy(mstrs< T > *mstring)

Parameters:

Type	Name	Direction	Description
mstrs< T > *	mstring	[IN]	Pointer to a mstrs structure.

length

Returnes the length (in number of characters) of the string stored in mstring.

Signature:

template< class T > unsigned int mstr::length(mstrs< T > *mstring)

Parameters:

Type	Name	Direction	Description
mstrs< T > *	mstring	[IN]	Pointer to a mstrs structure.

Return value:
The length of the string.

buffer_length

Returnes the length (in number of characters) of the memory block used to store the string in mstring.

The actual size of the memory block is one character larger than the returened value to account for the null-termination character.

Signature:

template< class T > unsigned int mstr::buffer_length(mstrs< T > *mstring)

Parameters:

Type	Name	Direction	Description
mstrs< T > *	mstring	[IN]	Pointer to a mstrs structure.

Return value:
The length of the memory block.

buffer_bytes

Returnes the size in bytes of the memory block used to store the string in mstring.

Signature:

template< class T > unsigned int mstr::buffer_bytes(mstrs< T > *mstring)

Parameters:

Type	Name	Direction	Description
mstrs< T > *	mstring	[IN]	Pointer to a mstrs structure.

Return value:
The size of the memory block.

used_memory

Returnes the total memory in bytes used by mstring.

Signature:

template< class T > unsigned int mstr::used_memory(mstrs< T > *mstring)

Parameters:

Type	Name	Direction	Description
mstrs< T > *	mstring	[IN]	Pointer to a mstrs structure.

Return value:
The size of the used memory.

cpy

Copies the string from mstring_b to mstring_a.

Signature:

template< class T > mstrs< T > *mstr::cpy(mstrs< T > *mstring_a,mstrs< T > *mstring_b)

Parameters:

Type	Name	Direction	Description
mstrs< T > *	mstring_a	[IN/OUT]	Pointer to a mstrs structure.
mstrs< T > *	mstring_b	[IN]	Pointer to a mstrs structure.

Return value:
A pointer to mstring_a.

cat

Appends the string from mstring_b to mstring_a.

Signature:

template< class T > mstrs< T > *mstr::cat(mstrs< T > *mstring_a,mstrs< T > *mstring_b)

Parameters:

Type	Name	Direction	Description
mstrs< T > *	mstring_a	[IN/OUT]	Pointer to a mstrs structure.
mstrs< T > *	mstring_b	[IN]	Pointer to a mstrs structure.

Return value:
A pointer to mstring_a.

cmp

Compares mstring_b with mstring_a.

Signature:

template< class T > int mstr::cmp(mstrs< T > *mstring_a,mstrs< T > *mstring_b)

Parameters:

Type	Name	Direction	Description
mstrs< T > *	mstring_a	[IN]	Pointer to a mstrs structure.
mstrs< T > *	mstring_b	[IN]	Pointer to a mstrs structure.

Return value:
Returnes 0 if both strings are equal and a value other than 0 otherwise.

fit

Reduces the size of the allocated memory to fit the string stored in mstring.

Signature:

template< class T > mstrs< T > *mstr::fit(mstrs< T > *mstring)

Parameters:

Type	Name	Direction	Description
mstrs< T > *	mstring	[IN]	Pointer to a mstrs structure.

Return value:
A pointer to mstring.

reset

Resets the string stored in mstring to the empty string.

Signature:

template< class T > mstrs< T > *mstr::reset(mstrs< T > *mstring)

Parameters:

Type	Name	Direction	Description
mstrs< T > *	mstring	[IN]	Pointer to a mstrs structure.

Return value:
A pointer to mstring.

c_str

Returns a pointer to the null-terminated string stored in mstring.

Signature:

template< class T > T *mstr::c_str(mstrs< T > *mstring)

Parameters:

Type	Name	Direction	Description
mstrs< T > *	mstring	[IN]	Pointer to a mstrs structure.

Return value:
A Pointer to the null-rerminated string.

copy_str

Copies the null-terminated string c_str to mstring.

Signature:

template< class T > mstrs< T > *mstr::copy_str(mstrs< T > *mstring,const T *c_str)

Parameters:

Type	Name	Direction	Description
mstrs< T > *	mstring	[IN]	Pointer to a mstrs structure.
const T *	c_str	[IN]	Pointer to a null-terminated string.

Return value:
A pointer to mstring.

append_str

Appends the null-terminated string c_str to mstring.

Signature:

template< class T > mstrs< T > *mstr::append_str(mstrs< T > *mstring,const T *c_str)

Parameters:

Type	Name	Direction	Description
mstrs< T > *	mstring	[IN]	Pointer to a mstrs structure.
const T *	c_str	[IN]	Pointer to a null-terminated string.

Return value:
A pointer to mstring.

compare_str

Compares mstring with the null-terminated string c_str.

Signature:

template< class T > int mstr::compare_str(mstrs< T > *mstring,const T *c_str)

Parameters:

Type	Name	Direction	Description
mstrs< T > *	mstring	[IN]	Pointer to a mstrs structure.
const T *	c_str	[IN]	Pointer to a null-terminated string.

Return value:
Returnes 0 if both strings are equal and a value other than 0 otherwise.

is_prefix (version 1)

Tests if prefix is prefix of str.

Signature:

template< class T > bool mstr::is_prefix(mstrs< T > *str,mstrs< T > *prefix)

Parameters:

Type	Name	Direction	Description
mstrs< T > *	str	[IN]	Pointer to a mstrs structure.
mstrs< T > *	prefix	[IN]	Pointer to a mstrs structure.

Return value:
Returns true if the strings matches and false otherwise.

is_prefix (version 2)

Tests if prefix is prefix of str.

Signature:

template< class T > bool mstr::is_prefix(const T *c_str,mstrs< T > *prefix)

Parameters:

Type	Name	Direction	Description
const T *	c_str	[IN]	Pointer to a null-terminated string.
mstrs< T > *	prefix	[IN]	Pointer to a mstrs structure.

Return value:
Returns true if the strings matches and false otherwise.

is_prefix (version 3)

Tests if one of the strings in prefix is prefix of str.

Signature:

template< class T > int mstr::is_prefix(const T *c_str,mstrs< T > **prefix)

Parameters:

Type	Name	Direction	Description
const T *	c_str	[IN]	Pointer to a null-terminated string.
mstrs< T > **	prefix	[IN]	Pointer to a null-terminated series of pointers to mstrs structures.

Return value:
Returns the index of the first string that matches. If no string in prefix is prefix of c_str, the function returns -1.