X-Git-Url: https://pd.if.org/git/?p=pdclib;a=blobdiff_plain;f=includes%2Fstring.h;h=9d2a517a7cc2de434d46af6274b686d77d5c1205;hp=a5e5b21072277c344ab978f4a03a21565b3fefdf;hb=1d9d92ba957a0b8307c9a65c35867fde68e6533b;hpb=e081ed1387e0c27dc689c8e32fdda06039544107 diff --git a/includes/string.h b/includes/string.h index a5e5b21..9d2a517 100644 --- a/includes/string.h +++ b/includes/string.h @@ -1,52 +1,282 @@ -// ---------------------------------------------------------------------------- -// $Id$ -// ---------------------------------------------------------------------------- -// Public Domain C Library - http://pdclib.sourceforge.net -// This code is Public Domain. Use, modify, and redistribute at will. -// ---------------------------------------------------------------------------- -// String handling -// ---------------------------------------------------------------------------- - -#ifndef __STRING_H -#define __STRING_H __STRING_H - -// TODO: Documentation - -// ---------------------------------------------------------------------------- -// MACROS - -#define NULL 0 - -// ---------------------------------------------------------------------------- -// TYPEDEFS - -typedef size_t; // TODO - personality? - -// ---------------------------------------------------------------------------- -// FUNCTIONS - -int memcmp( const void * s1, const void * s2, size_t n ); -void * memcpy( void * restrict s1, const void * restrict s2, size_t n ); -void * memmove( void * s1, const void * s2, size_t n ); -void * memset( void * s, int c, size_t n ); -char * strcat( char * restrict s1, const char * restrict s2 ); -int strcmp( const char * s1, const char * s2 ); -int strcoll( const char * s1, const char * s2 ); -char * strcpy( char * restrict s1, const char * restrict s2 ); -size_t strcspn( const char * s1, const char * s2 ); -char * strerror( int errcode ); -size_t strlen( const char * s ); -char * strncat( char * restrict s1, const char * restrict s2, size_t n ); -int strncmp( const char * s1, const char * s2, size_t n ); -char * strncpy( char * restrict s1, const char * restrict s2, size_t n ); -size_t strspn( const char * s1, const char * s2 ); -char * strtok( char * restrict s1, const char * restrict s2 ); -size_t strxfrm( char * restrict s1, const char * restrict s2, size_t n ); - -void * memchr( const void * s, int c, size_t n ); -char * strchr( const char * s, int c ); -char * strpbrk( const char *s1, const char * s2 ); -char * strrchr( const char * s, int c ); -char * strstr( const char * s1, const char * s2 ); - -#endif // __STRING_H +/* ---------------------------------------------------------------------------- + * $Id$ + * ---------------------------------------------------------------------------- + * Public Domain C Library - http://pdclib.sourceforge.net + * This code is Public Domain. Use, modify, and redistribute at will. + * ---------------------------------------------------------------------------- + * String handling + * --------------------------------------------------------------------------*/ + +#ifndef _STRING_H +#define _STRING_H _STRING_H + +#ifndef _NULL +#include "__intern.h" +#endif /* _NULL */ + +/* ---------------------------------------------------------------------------- + * MACROS + * --------------------------------------------------------------------------*/ + +#define NULL _NULL + +/* ---------------------------------------------------------------------------- + * TYPEDEFS + * --------------------------------------------------------------------------*/ + +#ifndef _SIZE_T +#define _SIZE_T _SIZE_T +typedef __size_t size_t +#endif /* _SIZE_T */ + +/* ---------------------------------------------------------------------------- + * FUNCTIONS + * --------------------------------------------------------------------------*/ + +/** MEMory search for CHaRacter. Searches a memory area for a character. + * @param src The memory area. + * @param c The character to look for. + * @param n Number of characters to search. + * @return A pointer to the first occurrence of c in src, or NULL if no match + * found. + * @see strchr() + */ +void * memchr( const void * src, int c, size_t n ); + +/** MEMory CoMPare. Compares two memory areas until a difference is found. + * This implementation actually returns the difference of the first differing + * byte. + * This behaviour is implementation-defined and should not be relied upon to + * keep your code portable across implementations. + * @param src_1 The first memory area. + * @param src_2 The second memory area. + * @param n Number of bytes to compare. + * @return 0, if both areas are identical. If a difference is found, returns a + * value < 0 if the byte from memory area src_1 is smaller than that + * from src_2, or > 0 if otherwise. + * @see strncmp() + */ +int memcmp( const void * src_1, const void * src_2, size_t n ); + +/** MEMory CoPY. Copies a source memory area of size n into a destination + * memory area. + * Should the memory areas pointed to by dest and src overlap, behaviour is + * undefined. + * @param dest The destination memory area. + * @param src The source memory area. + * @param n The size of the source memory area. + * @return A pointer to the destination memory area. + * @see strncpy() + */ +void * memcpy( void * restrict dest, const void * restrict src, size_t n ); + +/** MEMory CoPY. Moves a source memory area of size n into a destination + * memory area. The memory areas may overlap. + * @param dest The destination memory area. + * @param src The source memory area. + * @param n The size of the source memory area. + * @return A pointer to the destination memory area. + * @see strncpy() + */ +void * memmove( void * dest, const void * src, size_t n ); + +/** MEMory SET. Fills a memory area with a given character. + * @param dest The destination memory area. + * @param c The character to be written to dest. + * @param n The number of characters to be written to dest. + * @return A pointer to the destination memory area. + */ +void * memset( void * dest, int c, size_t n ); + +/** STRing conCATenation. Appends a C string to another. If the memory area + * pointed to by 'dest' is not large enough to hold both 'dest' and 'src', + * behaviour is undefined. + * @param dest The destination string. + * @param src The source string. + * @return A pointer to the destination string. + * @see strncat() + */ +char * strcat( char * restrict dest, const char * restrict src ); + +/** STRing search for CHaRacter. Searches a C string (including terminating \0) + * for a character. If the string is not properly terminated, behaviour is + * undefined. + * @param src The source string. + * @param c The character to look for. + * @return A pointer to the first occurrence of c in src, or NULL if no match + * found. + */ +char * strchr( const char * src, int c ); + +/** STRing CoMPare. Compares two C strings until two differing characters are + * found, or both strings end. If the input strings are not correctly + * teminated with \0, behaviour is undefined. + * This implementation actually returns the difference of the two characters. + * This behaviour is implementation-defined and should not be relied upon to + * keep your code portable across implementations. + * @param src_1 The first string to be compared. + * @param src_2 The second string to be compared. + * @return 0, if both strings are identical. If two differing characters are + * found, returns a value < 0 if the character from src_1 is smaller + * than that from src_2, or > 0 if otherwise. + * @see strncmp() + */ +int strcmp( const char * src_1, const char * src_2 ); + +/** STRing COLLate. Compares two C strings until two differing characters are + * found, honoring the current locale. + * This implementation actually returns the difference of the two characters. + * This behaviour is implementation-defined and should not be relied upon to + * keep your code portable across implementations. + * @param src_1 The first string to be compared. + * @param src_2 The second string to be compared. + * @return 0, if both strings are identical. If two differing characters are + * found, returns a value < 0 if the character from src_1 is smaller + * than that from src_2, or > 0 if otherwise. + * @see locale.h + */ +int strcoll( const char * src_1, const char * src_2 ); + +/** STRing CoPY. Copies a source string (including terminating \0) into a + * destination string. If the memory area pointed to by dest is not large + * enough to hold src, behaviour is undefined. Should the memory areas pointed + * to by dest and src overlap, behavious is undefined. + * @param dest The destination string. + * @param src The source string. + * @return A pointer to the destination string. + * @see strncpy() + */ +char * strcpy( char * restrict dest, const char * restrict src ); + +/** STRing Character SPaN. Compares two C strings, determining the length of + * the substring not containing any character from the second string. + * @param src_1 The string to be searched. + * @param src_2 The string containing the characters to be searched for. + * @return The length of the src_1 substring not containing any character + * from src_2. + */ +size_t strcspn( const char * src_1, const char * src_2 ); + +/** STRing ERROR. Returns the error message corresponding to an error code. + * @param errorcode The error code. + * @return The plaintext error message corresponding to the error code. + * @see errno.h + * @see fenv.h + */ +char * strerror( int errorcode ); + +/** STRing LENgth. Returns the number of characters in a C string, not counting + * the terminating \0. + * @param src The source string. + * @return The number of characters in the string, not counting the + * terminating \0. + */ +size_t strlen( const char * src ); + +/** STRing N conCATenate. Appends a C string to another, setting a limit on the + * number of characters copied. + * @param dest The destination string. + * @param src The source string. + * @param n The maximum number of characters to be copied. + * @return A pointer to the destination string. + * @see strcat() + */ +char * strncat( char * restrict dest, const char * restrict src, size_t n ); + +/** STRing N CoMPare. Compares two C strings until two differing characters are + * found, both strings end, or a maximum number of characters has been + * compared. + * This implementation actually returns the difference of the two characters. + * This behaviour is implementation-defined and should not be relied upon to + * keep your code portable across implementations. + * @param src_1 The first string to be compared. + * @param src_2 The second string to be compared. + * @param n The maximum number of characters to be compared. + * @return 0, if both strings are identical. If two differing characters are + * found, returns a value < 0 if the character from src_1 is smaller + * than that from src_2, or > 0 if otherwise. + * @see strcmp() + */ +int strncmp( const char * src_1, const char * src_2, size_t n ); + +/** STRing CoPY. Copies a source string (including terminating \0) into a + * destination string, setting a limit on the number of characters copied. + * Should the memory areas pointed to by dest and src overlap, behaviour is + * undefined. + * @param dest The destination string. + * @param src The source string. + * @param n The maximum number of characters to be copied. + * @return A pointer to the destination string. + * @see strcpy() + */ +char * strncpy( char * restrict dest, const char * restrict src, size_t n ); + +/** STRing SPaN. Compares two C strings, determining the length of the + * substring containing only characters from the second string. + * @param src_1 The first string to be compared. + * @param src_2 The second string to be compared. + * @return The length of the identical substring. + */ +size_t strspn( const char * src_1, const char * src_2 ); + +/** STRing TOKenizer. This (complex and not thread-safe) function allows, by + * subsequent calls, to parse a string for tokens. The first parameter to the + * function is the C string to be parsed, the second parameter a C string + * containing a collection of seperating characters. On first call to the + * function, strtok() skips leading seperators, sets the first seperator after + * the token to \0, and returns a pointer to the token. Subsequent calls to + * strtok() with NULL as the first parameter return pointers to subsequent + * tokens, or NULL when all tokens have been parsed. + * Beware, this function is not thread-safe. + * @param src The string to be parsed (on first call), or NULL (to parse + * subsequent tokens). + * @param seperators The string containing the seperator(s). + * @return The next token parsed, or NULL if parse completed. + */ +char * strtok( char * restrict src, const char * restrict seperators ); + +/** STRing X FRoM. This function transforms a C string into another using a + * transformation rule depending on the current locale. + * @param dest The destination, where the transformed string should be written + * to. + * @param src The source string to be transformed. + * @param n The maximum number of characters to be written to dest. If this + * parameter is zero, 'dest' can be a NULL pointer (to determine the + * required space before doing the actual transformation). + * @return The length of the string after transformation. If return value > n, + * the transformed string has not been written, and the contents of + * 'dest' are undefined. + * @see locale.h + * @see strcoll() + */ +size_t strxfrm( char * restrict dest, const char * restrict src, size_t n ); + +/** STRing search, return Pointer to BReaK. Searches a C string (including + * terminating \0) for any character contained in a second string. If the + * first string is not properly terminated, behaviour is undefined. + * @param src_1 The string to be seached. + * @param src_2 The string containing the characters to be searched. + * @return A pointer into src_1 pointing to the first occurrence of any + * character from src_2, or NULL if no match found. + */ +char * strpbrk( const char * src_1, const char * src_2 ); + +/** STRing Reverse search for CHaRacter. Searches a C string (including + * terminating \0) for a character. If the string is not properly terminated, + * behaviour is undefined. + * @param src The source string. + * @param c The character to look for. + * @return A pointer to the last occurrence of c in src, or NULL if no match + * found. + */ +char * strrchr( const char * src, int c ); + +/** STRing search for STRing. Searches a C string for a substring. + * @param src_1 The string to be searched in. + * @param src_2 The substring to be searched for. + * @return A pointer to the first occurrence of src_2 in src_1, or NULL if no + * match found. + */ +char * strstr( const char * src_1, const char * src_2 ); + +#endif /* _STRING_H */