pd.if.org Git - pdclib/blob - string.h

   1 /* $Id$ */
   2
   3 /* Release $Name$ */
   4
   5 /* String handling <string.h>
   6
   7    This file is part of the Public Domain C Library (PDCLib).
   8    Permission is granted to use, modify, and / or redistribute at will.
   9 */
  10
  11 #ifndef _PDCLIB_AUX_H
  12 #define _PDCLIB_AUX_H _PDCLIB_AUX_H
  13 #include <_PDCLIB_aux.h>
  14 #endif
  15
  16 #ifndef _PDCLIB_INT_H
  17 #define _PDCLIB_INT_H _PDCLIB_INT_H
  18 #include <_PDCLIB_int.h>
  19 #endif
  20
  21 #if _PDCLIB_HOSTED == 1
  22 #warning As of the current release, PDCLib is not a conforming hosted environment.
  23 #warning <string.h> might be incomplete.
  24 #endif
  25
  26 typedef _PDCLIB_size_t size_t;
  27
  28 /* String function conventions */
  29
  30 /*
  31    In any of the following functions taking a size_t n to specify the length of
  32    an array or size of a memory region, n may be 0, but the pointer arguments to
  33    the call shall still be valid unless otherwise stated.
  34 */
  35
  36 /* Copying functions */
  37
  38 /* Copy a number of n characters from the memory area pointed to by s2 to the
  39    area pointed to by s1. If the two areas overlap, behaviour is undefined.
  40    Returns the value of s1.
  41 */
  42 void * memcpy( void * _PDCLIB_restrict s1, const void * _PDCLIB_restrict s2, size_t n );
  43
  44 /* Copy a number of n characters from the memory area pointed to by s2 to the
  45    area pointed to by s1. The two areas may overlap.
  46    Returns the value of s1.
  47 */
  48 void * memmove( void * _PDCLIB_restrict s1, const void * _PDCLIB_restrict s2, size_t n );
  49
  50 /* Copy the character array s2 (including terminating '\0' byte) into the
  51    character array s1.
  52    Returns the value of s1.
  53 */
  54 char * strcpy( char * _PDCLIB_restrict s1, const char * _PDCLIB_restrict s2 );
  55
  56 /* Copy a maximum of n characters from the character array s2 into the character
  57    array s1. If s2 is shorter than n characters, '\0' bytes will be appended to
  58    the copy in s1 until n characters have been written. If s2 is longer than n
  59    characters, NO terminating '\0' will be written to s1. If the arrays overlap,
  60    behaviour is undefined.
  61    Returns the value of s1.
  62 */
  63 char * strncpy( char * _PDCLIB_restrict s1, const char * _PDCLIB_restrict s2, size_t n );
  64
  65 /* Concatenation functions */
  66
  67 /* Append the contents of the character array s2 (including terminating '\0') to
  68    the character array s1 (first character of s2 overwriting the '\0' of s1). If
  69    the arrays overlap, behaviour is undefined.
  70    Returns the value of s1.
  71 */
  72 char * strcat( char * _PDCLIB_restrict s1, const char * _PDCLIB_restrict s2 );
  73
  74 /* Append a maximum of n characters from the character array s1 to the character
  75    array s1 (first character of s2 overwriting the '\0' of s1). A terminating
  76    '\0' is ALWAYS appended, even if the full n characters have already been
  77    written. If the arrays overlap, behaviour is undefined.
  78    Returns the value of s1.
  79 */
  80 char * strncat( char * _PDCLIB_restrict s1, const char * _PDCLIB_restrict s2, size_t n );
  81
  82 /* Comparison functions */
  83
  84 /* Compare the first n characters of the memory areas pointed to by s1 and s2.
  85    Returns 0 if s1 == s2, a negative number if s1 < s2, and a positive number if
  86    s1 > s2.
  87 */
  88 int memcmp( const void * s1, const void * s2, size_t n );
  89
  90 /* Compare the character arrays s1 and s2.
  91    Returns 0 if s1 == s2, a negative number if s1 < s2, and a positive number if
  92    s1 > s2.
  93 */
  94 int strcmp( const char * s1, const char * s2 );
  95
  96 /* Compare the character arrays s1 and s2, interpreted as specified by the
  97    LC_COLLATE category of the current locale.
  98    Returns 0 if s1 == s2, a negative number if s1 < s2, and a positive number if
  99    s1 > s2.
 100    TODO: Currently a dummy wrapper for strcmp() as PDCLib does not yet support
 101    locales.
 102 */
 103 int strcoll( const char * s1, const char * s2 );
 104
 105 /* Compare no more than the first n characters of the character arrays s1 and
 106    s2.
 107    Returns 0 if s1 == s2, a negative number if s1 < s2, and a positive number if
 108    s1 > s2.
 109 */
 110 int strncmp( const char * s1, const char * s2, size_t n );
 111
 112 /* Transform the character array s2 as appropriate for the LC_COLLATE setting of
 113    the current locale. If length of resulting string is less than n, store it in
 114    the character array pointed to by s1. Return the length of the resulting
 115    string.
 116 */
 117 size_t strxfrm( char * _PDCLIB_restrict s1, const char * _PDCLIB_restrict s2, size_t n );
 118
 119 /* Search functions */
 120
 121 /* Search the first n characters in the memory area pointed to by s for the
 122    character c (interpreted as unsigned char).
 123    Returns a pointer to the first instance found, or NULL.
 124 */
 125 void * memchr( const void * s, int c, size_t n );
 126
 127 /* Search the character array s (including terminating '\0') for the character c
 128    (interpreted as char).
 129    Returns a pointer to the first instance found, or NULL.
 130 */
 131 char * strchr( const char * s, int c );
 132