#ifndef __STRING_H
#define __STRING_H

#ifndef __STDDEF_H
#include <stddef.h>
#endif

/* The compiler calling convention varies depending on the target
 * processor family; therefore, there often needs to be separate
 * prototypes depending on which compiler is being used.
 *
 * MPLAB-C18 provides the __18CXX environment variable which will
 * allow us to know that we're compiling for an 18c part. Future
 * versions of MPLAB-C17 will have a corresponding __17CXX environment
 * variable, but as of v2.30.03, it does not.
 *
 * Since the only two Microchip compilers currently available are
 * MPLAB-C17 and MPLAB-C18, the presence or absence of __18CXX
 * is sufficient to determine the target platform.
 */
#if __18CXX

/* Change this to near (or omit altogether) if building small memory model
 * versions of the libraries
 */
#define MEM_MODEL far

/* The ANSI specified versions */
/** @name memcpy
 * ``The {\bf memcpy} funciton copies {\bf n} characters from the object
 * pointed to by {\bf s2} into the object pointed to by {\bf s1}. If
 * copying takes place between objects that overlap, the behaviour is
 * undefined.''
 * Stack usage: 8 bytes. Re-entrant.
 * @param s1 pointer to destination
 * @param s2 pointer to source
 * @param n count of bytes to copy
 * @return ``The {\bf memcpy} function returns the value of {\bf s1}.''
 */
void *memcpy (auto void *s1, auto const void *s2, auto size_t n);

/** @name memmove
 * ``The {\bf memmove} function copies {\bf n} characters from the object
 * pointed to by {\bf s2} into the object pointed to by {\bf s1}. Copying
 * takes place as if the {\bf n} characters from the object pointed to
 * by {\bf s2} are first copied into a temporary array of {\bf n}
 * characters that does not overlap the objects pointed to by {\bf s1}
 * and {\bf s2}, and then the {\bf n} characters from the temporary array
 * are copied into the object pointed to by {\bf s1}.''
 * Stack usage: 8 bytes. Re-entrant.
 * @param s1 pointer to destination
 * @param s2 pointer to source
 * @param n count of bytes to copy
 * @return ``The {\bf memmove} function returns the value of {\bf s1}.''
 */
void *memmove (auto void *s1, auto const void *s2, auto size_t n);

/** @name strcpy
 * `` The {\bf strcpy} function copies the string pointed to by {\bf s2}
 * (including the terminating null character) into the array pointed to
 * by {\bf s1}. If copying takes place between objects that overlap,
 * the behaviour is undefined.''
 * Stack usage: 6 bytes. Re-entrant.
 * @param s1 pointer to destination
 * @param s2 pointer to source
 * @return ``The {\bf strcpy} function returns the value of {\bf s1}.''
 */
char *strcpy (auto char *s1, auto const char *s2);

/** @name strncpy
 * ``The {\bf strncpy} function copies not more than {\bf n} characters
 * (auto characters that follow a null character are not copied) from the
 * array pointed to by {\bf s2} to the array pointed to by {\bf s1}.
 * If {\bf n} characters are copies and no null character is found then
 * {\bf s1} will not be terminated.
 * If copying takes place between objects that overlap, the behaviour
 * is undefined.''
 * Stack usage: 8 bytes. Re-entrant.
 * @param s1 pointer to destination
 * @param s2 pointer to source
 * @param n count of maximum characters to copy
 * @return ``The {\bf strncpy} function returns the value of {\bf s1}.''
 */
char *strncpy (auto char *s1, auto const char *s2, auto size_t n);

/** @name strcat
 * ``The {\bf strcat} function appends a copy of the string pointed to
 * by {\bf s2} (including the terminating null character) to the end
 * of the string pointed to by {\bf s1}. The initial character of
 * {\bf s2} overwrites the null character at the end of {\bf s1}. If
 * copying takes place between objects that overlap, the behaviour is
 * undefined.''
 * Stack usage: 6 bytes. Re-entrant.
 * @param s1 pointer to destination
 * @param s2 pointer to source
 * @return ``The {\bf strcat} function returns the value of {\bf s1}.''
 */
char *strcat (auto char *s1, auto const char *s2);

/** @name strncat
 * ``The {\bf strncat} function appends not more than {\bf n} characters
 * (a null character and characters that follow it are not appended)
 * from the array pointed to by {\bf s2} to the end of the string
 * pointed to by {\bf s1}. The initial character of {\bf s2} overwrites
 * the null character at the end of {\bf s1}. A terminating null 
 * character is always appended to the result. If copying takes place
 * between objects that overlap, the behaviour is undefined.''
 * Stack usage: 8 bytes. Re-entrant.
 * @param s1 pointer to destination
 * @param s2 pointer to source
 * @param n count of maximum characters to copy
 * @return ``The {\bf strncat} function returns the value of {\bf s1}.''
 */
char *strncat (auto char *s1, auto const char *s2, auto size_t n);

/** @name memcmp
 * ``The {\bf memcmp} function compares the first {\bf n} characters of the
 * object pointed to by {\bf s1} to the first {\bf n} characters pointed
 * to by {\bf s2}.''
 * Stack usage: 6 bytes. Re-entrant.
 * @param s1 pointer to object one
 * @param s2 pointer to object two
 * @param n count of characters to compare
 * @return ``The {\bf memcmp} function returns a signed char greater than,
 * equal to, or less than zero, accordingly as the object pointed to by
 * {\bf s1} is greater than, equal to, or less than the object pointed to by
 * {\bf s2}.''
 */
signed char memcmp (auto const void *s1, auto const void *s2, auto size_t n);

/** @name strcmp
 * ``The {\bf strcmp} function compares the string pointed to by {\bf s1} to
 * the string pointed to by {\bf s2}.''
 * Stack usage: 6 bytes. Re-entrant.
 * @param s1 pointer to string one
 * @param s2 pointer to string two
 * @return ``The {\bf strcmp} function returns a signed char greater than,
 * equal to, or less than zero, accordingly as the string pointed to by
 * {\bf s1} is greater than, equal to, or less than the string pointed to
 * by {\bf s2}.''
 */
signed char strcmp (auto const char *s1, auto const char *s2);

/** @name strcoll
 * Locale-aware string comparison. As MPLAB-C18 does not currently support
 * locales, the {\bf strcoll} function is not required and is unimplemented.
 */

/** @name strncmp
 * ``The {\bf strncmp} function compares not more than {\bf n} characters
 * (auto characters that follow a null character are not compared) from the 
 * array pointed to by {\bf s1} to the array pointed to by {\bf s2}.''
 * Stack usage: 8 bytes. Re-entrant.
 * @param s1 pointer to string one
 * @param s2 pointer to string two
 * @param n count of characters to compare
 * @return ``The {\bf strncmp} function returns a signed char greater than,
 * equal to, or less than zero, accordiongly as the possibly null-terminated
 * array pointed to by {\bf s1} is greater than, equal to, or less than the
 * possibly null-terminated array pointed to by {\bf s2}.''
 */
signed char strncmp (auto const char *s1, auto const char *s2, auto size_t n);

/** @name strxfrm
 * As MPLAB-C18 does not currently support locales, the {\bf strxfrm}
 * function is not required and is unimplemented.
 */

/** @name memchr
 * ``The {\bf memchr} function locates the first occurence of {\bf c} [...]
 * in the initial {\bf n} characters [...] of the object pointed to by
 * {\bf s}.
 *
 * The MPLAB-C18 version of the {\bf memchr} function differs from the ANSI
 * specified function in that {\bf c} is defined as an {\bf unsigned char}
 * parameter rather than an {\bf int} parameter.''
 * Stack usage: 5 bytes. Re-entrant.
 * @param s pointer to object to search
 * @param c character to search for
 * @param n maximum number of chararacters to search
 * @return ``The {\bf memchr} function returns a pointer to the located character,
 * or a null pointer if the character does not occur in the object.''
 */
void *memchr (auto const void *s, auto unsigned char c, auto size_t n);

/** @name strchr
 * ``The {\bf strchr} function locates the first occurence of {\bf c} [...]
 * in the string pointed to by {\bf s}. The terminating null character is
 * considered to be part of the string.''
 *
 * The MPLAB-C18 version of the {\bf strchr} function differs from the ANSI
 * specified function in that {\bf c} is defined as an {\bf unsigned char}
 * parameter rather than an {\bf int} parameter.
 * Stack usage: 3 bytes. Re-entrant.
 * @param s pointer to string to search
 * @param c character to search for
 * @return ``The {\bf strchr} function returns a pointer to the located character,
 * or a null pointer if the character does not occur in the string.''
 */
char *strchr (auto const char *s, auto unsigned char c);

/** @name strcspn
 * ``The {\bf strcspn} function computes the length of the maximum initial
 * segment of the string pointed to by {\bf s1} which consists entirely
 * of characters {\it not} from the string pointed to by {\bf s2}.''
 * Stack usage: 6 bytes. Re-entrant.
 * @param s1 pointer to string to span
 * @param s2 pointer to set of characters
 * @return ``The {\bf strcspn} function returns the length of the segment.''
 */
size_t strcspn (auto const char *s1, auto const char *s2);

/** @name strpbrk
 * ``The {\bf strpbrk} function locates the first occurrence in the string
 * pointed to by {\bf s1} of any character from the string pointed to by
 * {\bf s2}.''
 * Stack usage: 6 bytes. Re-entrant.
 * @param s1 pointer to string to search
 * @param s2 pointer to set of characters
 * @return ``The {\bf strpbrk} function returns a pointer to the character,
 * or a null-pointer if no character from {\bf s2} occurs in {\bf s1}.''
 */
char *strpbrk (auto const char *s1, auto const char *s2);

/** @name strrchr
 * ``The {\bf strrchr} function locates the last occurrence of {\bf c} [...]
 * in the string pointed to by {\bf s}. The terminating null character is 
 * considered to be part of the string.''
 *
 * The MPLAB-C18 version of the {\bf strrchr} function differs from the ANSI
 * specified function in that {\bf c} is defined as an {\bf unsigned char}
 * parameter rather than an {\bf int} parameter.
 * Stack usage: 3 bytes. Re-entrant.
 * @param s pointer to string to search
 * @param c character to search for
 * @return ``The {\bf strrchr} function returns a pointer to the character,
 * or a null pointer if {\bf c} does not occur in the string.''
 */
char *strrchr (auto const char *s, auto unsigned char c);

/** @name strspn
 * ``The {\bf strspn} function computes the length of the maximum initial
 * segment of the string pointed to by {\bf s1} which consists entirely
 * of characters from the string pointed to by {\bf s2}.''
 * Stack usage: 6 bytes. Re-entrant.
 * @param s1 pointer to string to span
 * @param s2 pointer to set of characters
 * @return ``The {\bf strspn} function returns the length of the segment.''
 */
size_t strspn (auto const char *s1, auto const char *s2);

/** @name strstr
 * ``The {\bf strstr} function locates the first occurrence in the string 
 * pointed to by {\bf s1} of the sequence of characters (excluding the
 * null terminator) in the string pointed to by {\bf s2}.''
 * Stack usage: 8 bytes. Re-entrant.
 * @param s1 pointer to the string to search
 * @param s2 pointer to sequence to search for
 * @return ``The {\bf strstr} function returns a pointer to the located
 * string, or a null pointer if the string is not found. If {\bf s2}
 * points to a string with zero length, the function returns {\bf s1}.''
 */
char *strstr (auto const char *s1, auto const char *s2);

/** @name strtok
 * ``A sequence of calls to the {\bf strtok} function breaks the
 * string pointed to by {\bf s1} into a sequence of tokens, each of
 * which is delimited by a character from the string pointed to by
 * {\bf s2}. The first call in the sequence has {\bf s1} as its
 * first argument, and is followed by calls with a null pointer
 * as their first argument. The separator string pointed to by {\bf s2}
 * may be different from call to call.