From: solar <unknown>
Date: Sun, 18 Jan 2004 14:17:58 +0000 (+0000)
Subject: Completed documentation.
X-Git-Tag: OLD~20
X-Git-Url: https://pd.if.org/git/?p=pdclib;a=commitdiff_plain;h=f72e1f3e6441674c8ad2ab620102e50b3bf53768

Completed documentation.
---

diff --git a/includes/string.h b/includes/string.h
index 827f979..ed46905 100644
--- a/includes/string.h
+++ b/includes/string.h
@@ -10,8 +10,6 @@
 #ifndef __STRING_H
 #define __STRING_H __STRING_H
 
-// TODO: Documentation
-
 // ----------------------------------------------------------------------------
 // MACROS
 
@@ -25,9 +23,59 @@
 // ----------------------------------------------------------------------------
 // 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
@@ -125,7 +173,7 @@ size_t strlen( const char * src );
  */
 char * strncat( char * restrict dest, const char * restrict src, size_t n );
 
-/** STRing CoMPare. Compares two C strings until two differing characters are
+/** 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.
@@ -177,11 +225,48 @@ size_t strspn( const char * s1, const char * s2 );
  */
 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 );
 
-void * memchr( const void * s, int c, size_t n );
-char * strpbrk( const char *s1, const char * s2 );
+/** 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 );
-char * strstr( const char * s1, const char * s2 );
+
+/** 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