X-Git-Url: https://pd.if.org/git/?p=pdclib.old;a=blobdiff_plain;f=includes%2Fstring.h;h=27441df467bdec14c24b58465c2b99bef2ce33a0;hp=e7e69216de1b6ca3fe021ed8d40a3eab98ddd735;hb=1088cf7324e77983cbfbd8cab9783408d547882a;hpb=df52df19b4116c77db72f8d45fab95fdf765fe97 diff --git a/includes/string.h b/includes/string.h index e7e6921..27441df 100644 --- a/includes/string.h +++ b/includes/string.h @@ -1,272 +1,212 @@ -// ---------------------------------------------------------------------------- -// $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 - -// ---------------------------------------------------------------------------- -// MACROS - -#include "__NULL.h" - -// ---------------------------------------------------------------------------- -// TYPEDEFS - -#include "__size_t.h" - -// ---------------------------------------------------------------------------- -// 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 +/* $Id$ */ + +/* 7.21 String handling + + This file is part of the Public Domain C Library (PDCLib). + Permission is granted to use, modify, and / or redistribute at will. +*/ + +#ifndef _PDCLIB_STRING_H +#define _PDCLIB_STRING_H _PDCLIB_STRING_H +#include <_PDCLIB_int.h> +_PDCLIB_BEGIN_EXTERN_C + +#ifndef _PDCLIB_SIZE_T_DEFINED +#define _PDCLIB_SIZE_T_DEFINED _PDCLIB_SIZE_T_DEFINED +typedef _PDCLIB_size_t size_t; +#endif + +#ifndef _PDCLIB_NULL_DEFINED +#define _PDCLIB_NULL_DEFINED _PDCLIB_NULL_DEFINED +#define NULL _PDCLIB_NULL +#endif + +/* String function conventions */ + +/* + In any of the following functions taking a size_t n to specify the length of + an array or size of a memory region, n may be 0, but the pointer arguments to + the call shall still be valid unless otherwise stated. +*/ + +/* Copying functions */ + +/* Copy a number of n characters from the memory area pointed to by s2 to the + area pointed to by s1. If the two areas overlap, behaviour is undefined. + Returns the value of s1. +*/ +void * memcpy( void * _PDCLIB_restrict s1, const void * _PDCLIB_restrict s2, size_t n ) _PDCLIB_nothrow; + +/* Copy a number of n characters from the memory area pointed to by s2 to the + area pointed to by s1. The two areas may overlap. + Returns the value of s1. +*/ +void * memmove( void * s1, const void * , size_t n ) _PDCLIB_nothrow; + +/* Copy the character array s2 (including terminating '\0' byte) into the + character array s1. + Returns the value of s1. +*/ +char * strcpy( char * _PDCLIB_restrict s1, const char * _PDCLIB_restrict s2 ) _PDCLIB_nothrow; + +/* Copy a maximum of n characters from the character array s2 into the character + array s1. If s2 is shorter than n characters, '\0' bytes will be appended to + the copy in s1 until n characters have been written. If s2 is longer than n + characters, NO terminating '\0' will be written to s1. If the arrays overlap, + behaviour is undefined. + Returns the value of s1. +*/ +char * strncpy( char * _PDCLIB_restrict s1, const char * _PDCLIB_restrict s2, size_t n ) _PDCLIB_nothrow; + +/* Concatenation functions */ + +/* Append the contents of the character array s2 (including terminating '\0') to + the character array s1 (first character of s2 overwriting the '\0' of s1). If + the arrays overlap, behaviour is undefined. + Returns the value of s1. +*/ +char * strcat( char * _PDCLIB_restrict s1, const char * _PDCLIB_restrict s2 ) _PDCLIB_nothrow; + +/* Append a maximum of n characters from the character array s1 to the character + array s1 (first character of s2 overwriting the '\0' of s1). A terminating + '\0' is ALWAYS appended, even if the full n characters have already been + written. If the arrays overlap, behaviour is undefined. + Returns the value of s1. +*/ +char * strncat( char * _PDCLIB_restrict s1, const char * _PDCLIB_restrict s2, size_t n ) _PDCLIB_nothrow; + +/* Comparison functions */ + +/* Compare the first n characters of the memory areas pointed to by s1 and s2. + Returns 0 if s1 == s2, a negative number if s1 < s2, and a positive number if + s1 > s2. +*/ +int memcmp( const void * s1, const void * s2, size_t n ) _PDCLIB_nothrow; + +/* Compare the character arrays s1 and s2. + Returns 0 if s1 == s2, a negative number if s1 < s2, and a positive number if + s1 > s2. +*/ +int strcmp( const char * s1, const char * s2 ) _PDCLIB_nothrow; + +/* Compare the character arrays s1 and s2, interpreted as specified by the + LC_COLLATE category of the current locale. + Returns 0 if s1 == s2, a negative number if s1 < s2, and a positive number if + s1 > s2. + TODO: Currently a dummy wrapper for strcmp() as PDCLib does not yet support + locales. +*/ +int strcoll( const char * s1, const char * s2 ) _PDCLIB_nothrow; + +/* Compare no more than the first n characters of the character arrays s1 and + s2. + Returns 0 if s1 == s2, a negative number if s1 < s2, and a positive number if + s1 > s2. +*/ +int strncmp( const char * s1, const char * s2, size_t n ) _PDCLIB_nothrow; + +/* Transform the character array s2 as appropriate for the LC_COLLATE setting of + the current locale. If length of resulting string is less than n, store it in + the character array pointed to by s1. Return the length of the resulting + string. +*/ +size_t strxfrm( char * _PDCLIB_restrict s1, const char * _PDCLIB_restrict s2, size_t n ) _PDCLIB_nothrow; + +/* Search functions */ + +/* Search the first n characters in the memory area pointed to by s for the + character c (interpreted as unsigned char). + Returns a pointer to the first instance found, or NULL. +*/ +void * memchr( const void * s, int c, size_t n ) _PDCLIB_nothrow; + +/* Search the character array s (including terminating '\0') for the character c + (interpreted as char). + Returns a pointer to the first instance found, or NULL. +*/ +char * strchr( const char * s, int c ) _PDCLIB_nothrow; + +/* Determine the length of the initial substring of character array s1 which + consists only of characters not from the character array s2. + Returns the length of that substring. +*/ +size_t strcspn( const char * s1, const char * s2 ) _PDCLIB_nothrow; + +/* Search the character array s1 for any character from the character array s2. + Returns a pointer to the first occurrence, or NULL. +*/ +char * strpbrk( const char * s1, const char * s2 ) _PDCLIB_nothrow; + +/* Search the character array s (including terminating '\0') for the character c + (interpreted as char). + Returns a pointer to the last instance found, or NULL. +*/ +char * strrchr( const char * s, int c ) _PDCLIB_nothrow; + +/* Determine the length of the initial substring of character array s1 which + consists only of characters from the character array s2. + Returns the length of that substring. +*/ +size_t strspn( const char * s1, const char * s2 ) _PDCLIB_nothrow; + +/* Search the character array s1 for the substring in character array s2. + Returns a pointer to that sbstring, or NULL. If s2 is of length zero, + returns s1. +*/ +char * strstr( const char * s1, const char * s2 ) _PDCLIB_nothrow; + +/* In a series of subsequent calls, parse a C string into tokens. + On the first call to strtok(), the first argument is a pointer to the to-be- + parsed C string. On subsequent calls, the first argument is NULL unless you + want to start parsing a new string. s2 holds an array of seperator characters + which can differ from call to call. Leading seperators are skipped, the first + trailing seperator overwritten with '\0'. + Returns a pointer to the next token. + WARNING: This function uses static storage, and as such is not reentrant. +*/ +char * strtok( char * _PDCLIB_restrict s1, const char * _PDCLIB_restrict s2 ) _PDCLIB_nothrow; + +/* Miscellaneous functions */ + +/* Write the character c (interpreted as unsigned char) to the first n + characters of the memory area pointed to by s. + Returns s. +*/ +void * memset( void * s, int c, size_t n ) _PDCLIB_nothrow; + +/* Map an error number to a (locale-specific) error message string. Error + numbers are typically errno values, but any number is mapped to a message. + TODO: PDCLib does not yet support locales. +*/ +char * strerror( int errnum ) _PDCLIB_nothrow; + +/* Returns the length of the string s (excluding terminating '\0'). +*/ +size_t strlen( const char * s ) _PDCLIB_nothrow; + +#if _PDCLIB_POSIX_MIN(2008098L) +/* Returns the length of the string s (excluding terminating '\0') or maxlen if + * no terminating '\0' is found in the first maxlen characters. + */ +size_t strnlen( const char * s, size_t maxlen ) _PDCLIB_nothrow; +#endif + +#if _PDCLIB_POSIX_MIN(2008098L) || _PDCLIB_XOPEN_MIN(0) +char * strdup( const char* src ) _PDCLIB_nothrow; +char * strndup( const char* src, size_t n ) _PDCLIB_nothrow; +#endif + +#if _PDCLIB_BSD_SOURCE +size_t strlcpy( + char *_PDCLIB_restrict _Dst, + const char *_PDCLIB_restrict _Src, + size_t _DstSize) _PDCLIB_nothrow; + +size_t strlcat( + char *_PDCLIB_restrict _Dst, + const char *_PDCLIB_restrict _Src, + size_t _DstSize) _PDCLIB_nothrow; +#endif + +_PDCLIB_END_EXTERN_C +#endif