String and memory manipulations
[C library]

This group contains functions that manipulate memory and C zero-terminated strings. More...

Functions
void *	memccpy (void d, const void s, int c, size_t n)
	Copy a memory area with a sentinel.
void *	memchr (const void *p, int c, size_t n)
	Locate the first occurance of a given byte in a memory region.
int	memcmp (const void p1, const void p2, size_t n)
	Compare two memory regions.
void *	memcpy (void dst, const void src, size_t len)
	Copies a memory range to an other.
void *	memmove (void dst, void src, size_t len)
	Copies a memory range to an other.
void *	memrchr (const void *p, int c, size_t n)
	Locate the last occurance of a given byte in a memory region.
void *	memrcpy (void dst, const void src, size_t len)
	Copies a memory range to an other.
void *	memset (void *s, int c, size_t n)
	Set all bytes in a memory range to a given value.
char *	strcat (char dst, const char src)
	Concatenate two NUL terminated strings.
char *	strcat_fast (char dst, const char src)
	Concatenate two NUL terminated strings.
char *	strchr (const char *s, int c)
	Locate the first occurance of a charater in a string.
int	strcmp (const char s1, const char s2)
	Compare two NUL terminated strings.
char *	strcpy (char dst, const char src)
	Copy a NUL terminated string to an other.
size_t	strcspn (const char str, const char set)
	Length of the initial segment of a string containing a set of characters.
size_t	strlcat (char dst, const char src, size_t len)
	Concatenates a string with an other in a fixed size buffer.
size_t	strlcpy (char dst, const char src, size_t len)
	Copies at most len-1 bytes from a string to an other.
size_t	strlen (const char *s)
	Return the length of a NUL terminated string.
char *	strncat (char dst, const char src, size_t len)
	Concatenate two NUL terminated strings, with a size limit.
int	strncmp (const char s1, const char s2, size_t ml)
	Compare two NUL terminated strings with a length limit.
char *	strncpy (char dst, const char src, size_t len)
	Copy a NUL terminated string to an other with a length limit.
size_t	strnlen (const char *s, size_t m)
	Return the length of a NUL terminated string, with a limit.
char *	strpbrk (const char str, const char set)
	Locate the first occurance of a charater from a set in a string.
char *	strrchr (const char *s, int c)
	Locate the last occurance of a charater in a string.
char *	strsep (char *string, const char delim)
	Extracts a token from a string.
size_t	strspn (const char str, const char set)
	Length of the initial segment of a string containing a set of characters.
char *	strstr (const char haystack, const char needle)
	Find a substring in a string.

Detailed Description

This group contains functions that manipulate memory and C zero-terminated strings.

To use these functions you have to include string.h.

Inlined functions

A lot of these functions provide very simple functionality, their "classic" implementation is only a few lines of C code. Therefore, they are prospective candidates for inlining and the library supplies inlined versions of the most basic functions. The following functions have inlined versions:

memcpy(), memrcpy(), memcmp(), memset(), memmove(), memchr(), memrchr()
strlen(), strnlen(), strcpy(), strncpy(), strcat(), strncat(), strcmp(), strncmp(), strchr(), strrchr()

To access the inlined versions, you have to define the symbol

#define BLC_STRING_INLINE

before you include string.h in your code.

Fast functions

Some selected functions are also provided in assembly form, where size is traded for speed. These functions have a _fast suffix in their name, therefore you can distinguish between the "classic" implementation and the fast one. The prototype and behaviour of the fast function is the same as the corresponding "classic" function, with the following considerations:

The fast functions work only on a little endian target.
The string manipulation fast functions can read beyond the '\0' that marks the end of a string. In particular, these functions fetch a word at a time and will stop when they fetched the word that contains the closing '\0'. That means that they may read beyond the end of the string by up to 3 bytes. It is only for read, the functions never write after the closing 0. The memXXX() family functions never read or write beyond the specified length of the memory area.

You can use the fast functions regardless of whether you use the inlined or not inlined "classic" versions; however, the fast versions are never inlined.

If you define the symbol

#define BLC_STRING_FAST

before you include the string.h header, then macros will be used to map the functions to the fast functions where available. You can still use the explicite fast functions, but even the "normal" functions will actually call the fast versions. If you define both BLC_STRING_FAST and BLC_STRING_INLINE then functions that have fast version will be mapped to the fast version and not inlined while functions that have inline format but no fast version will be inlined.
The following functions are provided in fast version:

memcmp(), memset(), memcpy(), memrcpy(), memmove()
strcpy(), strncpy(), strlen(), strnlen(), strcat()

Code size and speed comparison

The following table gives you a rough idea of the speed and size trade-off when using the memXXX_fast() functions. The data was obtained on an LPC23xx running at 60MHz from its internal FLASH. The code increase is just a rough measure, the slow version code size is rather dependent on whether you compile for ARM or THUMB, the compiler version, the flags and so on. Since the slow functions treat memory as bytes, data alignment for those does not matter. On the other hand, alignment, in particular the relative alignment of source and destination, has a significant effect on the fast versions, therefore timing data for both aligned and misaligned cases are given.

Function Code size Data Execution time [µs] name increase [bytes] slow alig. misal.

memset()       ~ 4            5     1.57    1.38    1.90
                             40     8.57    1.62    2.10
                            320    64.57    3.65    4.13
                           2560   512.57   19.66   20.14

memcmp()       ~ 7            5     2.32    1.92    2.05
                             40    13.10    3.77    6.35
                            320    99.43   22.43   29.69
                           2560   790.10  171.77  216.35

memcpy()       ~ 7            5     1.62    1.32    2.24
memrcpy()                    40     9.65    3.38    6.48
                            320    69.01   11.84   28.21
                           2560   539.05   71.65  189.95

memmove()      ~ 15           5     1.84    1.42    2.39
                             40    10.08    3.97    6.61
                            320    69.67    9.13   16.67
                           2560   539.92   38.80   71.48

The strXXX_fast() functions are only about 3-4 times as fast as their normal counterparts and about 7 times larger. These functions are not detailed in a table form.

Function Documentation

void* memccpy	(	void *	d,
		const void *	s,
		int	c,
		size_t	n
	)

Copy a memory area with a sentinel.

The function copies the source memory area to the destination memory area. The copying stops if either the given number of bytes were copied, or if the last copied byte is identical to the character given. If the copy was stopped because the given character was found (and copied), then a pointer to the byte in the destination area just after the last copied byte is returned. If the copy stopped because the given number of bytes were copied and the given character was not found, then NULL is returned.

Parameters:

	d	Pointer to the destination area
	s	Pointer to the source area
	c	The character to look for
	n	The maximum number of bytes to copy

Returns:: NULL if c was not found while copying n bytes or a pointer in d to the location just after the copied c byte.

void* memchr	(	const void *	p,
		int	c,
		size_t	n
	)

Locate the first occurance of a given byte in a memory region.

The function returns a pointer to the first occurance of the byte c in the n bytes long memory area pointed by p. If the memory area does not contain the character, then NULL is returned. Note that the parameter c is int, not char. Only the lower 8 bits of the int value will be used, all the higher bits are simply ignored.

Parameters:

	p	Pointer to the memory area
	c	The character to look for
	n	The size of the memory area

Returns:: Pointer to the first occurance of the character in the string or NULL if the string does not contain the character

int memcmp	(	const void *	p1,
		const void *	p2,
		size_t	n
	)

Compare two memory regions.

The function compares the two memory areas byte after byte, treating the bytes as unsigned chars. The comparison stops at the first byte that is different or when n bytes have been compared.

Parameters:

	p1	Pointer to the first memory aread
	p2	Pointer to the second memory area
	n	Length of the comparison.

Returns:: An integer value that is 0 if p1 and p2 are identical in their first n bytes, a negative number if s1 is smaller that s2 and a positive number if s1 is greater than s2. The actual numeric value of the return value is undeterminate, only its signum is significant.

void* memcpy	(	void *	dst,
		const void *	src,
		size_t	len
	)

Copies a memory range to an other.

The function copies len bytes from the memory area pointed by src to the memory are pointed by dst and returns dst. The memory ranges must not overlap.

Parameters:

	dst	Pointer to the destination memory range
	src	Pointer to the source memory range
	len	The number of bytes to copy

Returns:: The value of dst

Note:: Although the standard states that the memory areas can not overlap, this function always copies starting at the beginning of the areas. Therefore, if your destination address is smaller than the source address, the function will work even if the areas do actually overlap. The non-standard memrcpy() function copies starting from the end, so that function can be used for overlapping areas where the destination address is larger than the source.

void* memmove	(	void *	dst,
		void *	src,
		size_t	len
	)

Copies a memory range to an other.

The function copies len bytes from the memory area pointed by src to the memory are pointed by dst and returns dst. The copying is done in such way that is equivalent of first copying the source range to a temporary buffer, distinct from both src and dst, then copying the temporary to the dst area. That is, the memory ranges src and dst may overlap.

Parameters:

	dst	Pointer to the destination memory range
	src	Pointer to the source memory range
	len	The number of bytes to copy

Returns:: The value of dst

Attention:: The C99 standard specifies the prototype of this function as
void *memmove( void *dst, const void *src, size_t len )
but then it explicitely states that src and dst can overlap, that is, the function has every right to overwrite the src area. It is different from using memcpy() to fill a memory with a repetitive pattern knowing that it performs a forward, byte-by-byte copy. That is abuse and is against the standard that clearly specifies that the source and destination areas of memcpy() must not overlap. In case of memmove(), such a usage is actually allowed and in fact the only reason to have memmove() on top of memcpy() is the overlap safe copying. Therefore this library omits the const qualifier from the second argument's type in the prototype. Therefore, this function is not strictly standard compliant.

void* memrchr	(	const void *	p,
		int	c,
		size_t	n
	)

Locate the last occurance of a given byte in a memory region.

The function returns a pointer to the last occurance of the byte c in the n bytes long memory area pointed by p. If the memory area does not contain the character, then NULL is returned. Note that the parameter c is int, not char. Only the lower 8 bits of the int value will be used, all the higher bits are simply ignored.

Parameters:

	p	Pointer to the memory area
	c	The character to look for
	n	The size of the memory area

Returns:: Pointer to the last occurance of the character in the string or NULL if the string does not contain the character

void* memrcpy	(	void *	dst,
		const void *	src,
		size_t	len
	)

Copies a memory range to an other.

The function copies len bytes from the memory area pointed by src to the memory are pointed by dst and returns dst. The copy will be performed starting with the end of the memory areas, therefore the areas can overlap if the destination address is larger than the source address.

Parameters:

	dst	Pointer to the destination memory range
	src	Pointer to the source memory range
	len	The number of bytes to copy

Returns:: The value of dst

Note:: This is a non-standard function.

void* memset	(	void *	s,
		int	c,
		size_t	n
	)

Set all bytes in a memory range to a given value.

Parameters:

	s	Pointer to the memory range
	c	The value to set the bytes to
	n	The number of bytes to set

Returns:: The value of s

char* strcat	(	char *	dst,
		const char *	src
	)

Concatenate two NUL terminated strings.

The function appends the src string to the dst string. The result is a longer sting at dst. The result is NUL terminated. The memory areas for src and dst should not overlap.

Parameters:

	dst	Pointer to the destination string
	src	Pointer to the source string

Returns:: Pointer to the destination string

char* strcat_fast	(	char *	dst,
		const char *	src
	)

Concatenate two NUL terminated strings.

The function appends the src string to the dst string. The result is a longer sting at dst. The result is NUL terminated. The memory areas for src and dst should not overlap.

Parameters:

	dst	Pointer to the destination string
	src	Pointer to the source string

Returns:: Pointer to the destination string

Attention:: This function only works on little-endian targets. In addition it can read up to 7 bytes more from the source than would be necessary; however, the excess read is never more than the 32 bit word following the word that contains the terminating 0. The destination is never written after the terminating 0 byte.

char* strchr	(	const char *	s,
		int	c
	)

Locate the first occurance of a charater in a string.

The function returns a pointer to the first occurance of the character c in the string s. If the string does not contain the character, then NULL is returned. Note that the parameter c is int, not char. Only the lower 8 bits of the int value will be used, all the higher bits are simply ignored. Also note that the terminating NUL character is not considered part of the string, if you search for 0, the function will return NULL.

Parameters:

	s	Pointer to the string
	c	The character to look for

Returns:: Pointer to the first occurance of the character in the string or NULL if the string does not contain the character

int strcmp	(	const char *	s1,
		const char *	s2
	)

Compare two NUL terminated strings.

The function compares the strings byte after byte, as unsigned chars. The comparison stops at the first byte that is different or when a NUL in either string is reached. A string is considered smaller than an other if the first differing character is a smaller unsigned number is less than the character at the same position in the other string.

Parameters:

	s1	Pointer to the first string
	s2	Pointer to the second string

Returns:: An integer value that is 0 if s1 and s2 are identical, a negative number if s1 is smaller that s2 and a positive number if s1 is greater than s2. The actual numeric value of the return value is undeterminate, only its signum is significant.

char* strcpy	(	char *	dst,
		const char *	src
	)

Copy a NUL terminated string to an other.

The memory areas for src and dst should not overlap.

Parameters:

	dst	Pointer to the destination string
	src	Pointer to the source string

Returns:: Pointer to the destination string

size_t strcspn	(	const char *	str,
		const char *	set
	)

Length of the initial segment of a string containing a set of characters.

The function returns the length of the initial segment of the string str containing only characters that are not in set. If the set is empty, then the length of the string str is is returned.

Parameters:

	str	Pointer to the string
	set	The set of characters that can not be in `str`

Returns:: The length of the initials segment of str that contains only characters not in the set.

size_t strlcat	(	char *	dst,
		const char *	src,
		size_t	len
	)

Concatenates a string with an other in a fixed size buffer.

Parameters:

	dst	Pointer to the destination buffer
	src	Pointer to the string to append to `dst`
	len	Size of the buffer (including dst!)

Returns:: The length of the final string or len if the result would overflow the buffer.

Attention:: This is not a standard C library function. This function was suggested first by Todd C. Miller and Theo de Raadt and it is included in OpenBSD.

size_t strlcpy	(	char *	dst,
		const char *	src,
		size_t	len
	)

Copies at most len-1 bytes from a string to an other.

Works like strncpy() with the following differences:

The result string is guaranteed to be NUL terminated
The remaining buffer space after the terminating NUL will not be zeroed. The zeroing of the remaining space is a performance hit, especially if you have a reasonably sized buffer and short source strings. In addition, strncpy() does not guarantee that the result is actually terminated. This function avoids the performance penalty and guarantees the termination. If you want to know if the copy truncated the string, then you just have to see if the return value was greater than l-1.

Parameters:

	dst	Pointer to the destiantion area
	src	Pointer to the source string
	len	Maximum number of non-zero characters to copy

Returns:: Length of the source string, but no more than len.

Attention:: This is not a standard C library function. This function was suggested first by Todd C. Miller and Theo de Raadt and it is included in OpenBSD.

size_t strlen ( const char * s )

Return the length of a NUL terminated string.

Parameters:

s

Pointer to the string.

Returns:: The number of characters in the string before the terminating NUL. The NUL itself is not included in the length.

char* strncat	(	char *	dst,
		const char *	src,
		size_t	len
	)

Concatenate two NUL terminated strings, with a size limit.

The function appends the src string to the dst string. The result is a longer sting at dst. The result is NUL terminated. At most len characters of src are copied, not including the NUL character. Therefore, at most len + 1 bytes are written. The memory areas for src and dst should not overlap.

Parameters:

	dst	Pointer to the destination string
	src	Pointer to the source string
	len	The maximum number of characters to be used from src

Returns:: Pointer to the destination string

int strncmp	(	const char *	s1,
		const char *	s2,
		size_t	ml
	)

Compare two NUL terminated strings with a length limit.

The function compares the strings byte after byte, as unsigned chars. The comparison stops at the first byte that is different or when a NUL in either string is reached. A string is considered smaller than an other if the first differing character is a smaller unsigned number is less than the character at the same position in the other string. At most ml characters are compared, if the first ml characters are identical, then the two strings are considered equal.

Parameters:

	s1	Pointer to the first string
	s2	Pointer to the second string
	ml	Maximum length of the comparison

Returns:: An integer value that is 0 if s1 and s2 are identical, a negative number if s1 is smaller that s2 and a positive number if s1 is greater than s2. The actual numeric value of the return value is undeterminate, only its signum is significant.

char* strncpy	(	char *	dst,
		const char *	src,
		size_t	len
	)

Copy a NUL terminated string to an other with a length limit.

The function behaves like strcpy() except that no more than len characters are copied to the destination. Note that if the source string is at least len characters long, then the destination will not have a terminating NUL stored in it. If the source is shorter than the given memory area, the rest of the memory area will be filled with NULs. That's the standard behaviour; if you want a safer and more efficient variant, see strlcpy().

Parameters:

	dst	Pointer to the destination string
	src	Pointer to the source string
	len	The maximum number of characters to copy

Returns:: Pointer to the destination string

size_t strnlen	(	const char *	s,
		size_t	m
	)

Return the length of a NUL terminated string, with a limit.

The function calculates the length of a string but it does not test more than a given number characters. If the limit is reached, the function stops, even if no NUL character was seen. The function does not read beyond the given number of characters.

Parameters:

	s	Pointer to the string.
	m	The maximum length of the string

Returns:: The number of characters in the string before the terminating NUL or m, if the first m characters of the string did not contain a NUL character.

char* strpbrk	(	const char *	str,
		const char *	set
	)

Locate the first occurance of a charater from a set in a string.

The function returns a pointer to the first occurance of a character from the set set in the string str. If the string does not contain any of the characters of set, then NULL is returned.

Parameters:

	str	Pointer to the string
	set	Pointer to the set of characters to look for

Returns:: Pointer to the first occurance of a set member in the string or NULL if the string does not contain any members.

char* strrchr	(	const char *	s,
		int	c
	)

Locate the last occurance of a charater in a string.

The function returns a pointer to the last occurance of the character c in the string s. If the string does not contain the character, then NULL is returned. Note that the parameter c is int, not char. Only the lower 8 bits of the int value will be used, all the higher bits are simply ignored. Also note that the terminating NUL character is not considered part of the string, if you search for 0, the function will return NULL.

Parameters:

	s	Pointer to the string
	c	The character to look for

Returns:: Pointer to the lastt occurance of the character in the string or NULL if the string does not contain the character

char* strsep	(	char **	string,
		const char *	delim
	)

Extracts a token from a string.

If the string pointer is NULL, then the function does nothing. Otherwise, the function looks for the first occurence of any character from the set delim in *string. If no occurence is found, then *string is set to NULL. Otherwise, the occurence in *string is replaced with a NUL and *string is set to the character just after the occurence. That is, if *string points to the string "First Second" and delim contains the string " ", then this function will set string to the address of the letter 'S' in the string and will replace the space between First and Second with a NUL. If the delimiter character set is empty, then it is treated as if it was not found in the string.

Warning:: This function is dangerous because it changes the original string. Be very cautious when you are using it.

Parameters:

	string	Pointer to a pointer to a string
	delim	Pointer to a string of delimiter characters

Returns:: The original value of *string

size_t strspn	(	const char *	str,
		const char *	set
	)

Length of the initial segment of a string containing a set of characters.

The function returns the length of the initial segment of the string str containing only characters that are in set. If the set is empty, then 0 is returned.

Parameters:

	str	Pointer to the string
	set	The set of characters to look for

Returns:: The length of the initials segment of str that contains only characters in the set.

char* strstr	(	const char *	haystack,
		const char *	needle
	)

Find a substring in a string.

The function looks for the first occurance of the string needle in the string haystack. If needle is an empty string, then it is considered to be immediately found, that is, a pointer to the first character of haystack is returned, even if that haystack was itself empty (i.e. you can find an empty string in an empty string).

Parameters:

	haystack	Pointer to the string in which to search
	needle	Pointer to the string you want to find

Returns:: Pointer to the first occurance of needle in haystack or NULL if needle is not found.

String and memory manipulations [C library]

Functions

Detailed Description

Inlined functions

Fast functions

Code size and speed comparison

Function Documentation

String and memory manipulations
[C library]