Functions

# 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 * | 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* 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.