-// ----------------------------------------------------------------------------
-// $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 * s, 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 * s1, const void * s2, 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 s1, const void * restrict s2, 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 * s1, const void * s2, 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 * s, 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 s1, const char * restrict s2, size_t n );
-
-/** STRing SPaN. Compares two C strings, determining the length of the
- * substring where both strings are equal.
- * @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 * s1, const char * s2 );
-
-/** 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 s1, const char * restrict s2, 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 * s, 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 <string.h>
+
+ 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
projects / pdclib.old / blobdiff