// Rowley C Compiler, runtime support.
//
// Copyright (c) 2010 Rowley Associates Limited.
//
// This file may be distributed under the terms of the License Agreement
// provided with this software.
//
// THIS FILE IS PROVIDED AS IS WITH NO WARRANTY OF ANY KIND, INCLUDING THE
// WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

#ifndef __wchar_H
#define __wchar_H

#include "__crossworks.h"

#ifdef __cplusplus
extern "C" {
#endif


// Some things are defined here, as required by the ISO standard, but
// we do not include <stddef.h> to get them as that would be in violation
// of the standard.


#ifndef __SIZE_T_DEFINED
#define __SIZE_T_DEFINED
typedef __SIZE_T size_t;
#endif

#ifndef NULL
#define NULL 0
#endif


/*! \brief Minimum value of a wide character
    \ingroup Character minimum and maximum values \synopsis

  \desc \b \this is the minimum value for an object of type \b wchar_t.
*/
#define WCHAR_MIN  0


/*! \brief Maximum value of a wide character 
    \ingroup Character minimum and maximum values \synopsis

  \desc \b \this is the maximum value for an object of type \b wchar_t.
  Although capable of storing larger values, the maximum value
  implemented by the conversion functions in the library is the
  value 0x10FFFF defined by ISO 10646.
*/
#define WCHAR_MAX  2147483647


/*! \brief End of file indication \ingroup Constants \synopsis

  \desc \b \this expands to a constant value that does not correspond to any
  character in the wide character set.  It is typically used to indicate an
  end of file condition.
*/
#define WEOF ((wint_t)0xFFFFFFFF)


/*! \brief Conversion state context \ingroup Types \synopsis

  \desc \b \this holds the conversion state information necessary to
  convert between sequences of multi-byte characters and wide
  characters.
*/
typedef struct __mbstate_s mbstate_t;


#ifndef __WCHAR_T_DEFINED
#define __WCHAR_T_DEFINED

/*! \brief Wide character type \ingroup Types \synopsis

  \desc \b \this holds a single wide character.
*/
typedef unsigned wchar_t;

#endif


#ifndef __WINT_DEFINED
#define __WINT_DEFINED

/*! \brief Wide integer type \ingroup Types \synopsis

  \desc \b \this is an integer type that is unchanged by default argument promotions
  that can hold any value corresponding to members of the extended character set,
  as well as at least one value that does not correspond to any member of the extended
  character set (WEOF).
*/
typedef long wint_t;

#endif

/*! \brief Copy memory \ingroup Copying functions \synopsis

  \description \b \this copies \a n wide characters from the object pointed to by \a s2
  into the object pointed to by \a s1. The behavior of \b \this is undefined 
  if copying takes place between objects that overlap.

  \b \this returns the value of \a s1.
*/
wchar_t *wmemcpy(wchar_t *s1, const wchar_t *s2, size_t n);


/*! \brief Copy memory with specified terminator (POSIX extension) \ingroup Copying functions \synopsis

  \description \b \this copies at most \a n wide characters from the object pointed to
  by \a s2 into the object pointed to by \a s1. The copying stops as soon as
  \a n wide characters are copied or the wide character \a c is copied into the
  destination object pointed to by \a s1.
  
  The behavior of \b \this is undefined if copying takes place between objects
  that overlap.

  \b \this returns a pointer to the wide character immediately following \a c in
  \a s1, or \b NULL if \a c was not found in the first \a n wide characters of \a s2.

  \note \b \this conforms to POSIX.1-2008.
*/
wchar_t *wmemccpy(wchar_t *__s1, const wchar_t *__s2, wchar_t __c, size_t __n);


/*! \brief Copy memory (GNU extension) \ingroup Copying functions \synopsis

  \description \b \this copies \a n wide characters from the object pointed to by \a s2
  into the object pointed to by \a s1. The behavior of \b \this is undefined 
  if copying takes place between objects that overlap.

  \b \this returns it returns a pointer to the wide character following the
  last written wide character.

  \note This is an extension found in GNU libc.
*/
wchar_t *wmempcpy(wchar_t *s1, const wchar_t *s2, size_t n);


/*! \brief Safely copy overlapping memory \ingroup Copying functions \synopsis

  \description \b \this copies \a n wide characters from the object pointed to by \a s2
  into the object pointed to by \a s1 ensuring that if \a s1 and \a s2
  overlap, the copy works correctly. Copying takes place as if the \a n wide characters 
  from the object pointed to by \a s2 are first copied into a temporary array 
  of \a n wide characters that does not overlap the objects pointed to by \a s1 
  and \a s2, and then the \a n wide characters from the temporary array are 
  copied into the object pointed to by \a s1.

  \b \this returns the value of \a s1.
*/
wchar_t *wmemmove(wchar_t *s1, const wchar_t *s2, size_t n);


/*! \brief Compare memory \ingroup Comparison functions \synopsis

  \description \b \this compares the first \a n wide characters of the object pointed 
  to by \a s1 to the first \a n wide characters of the object pointed to by 
  \a s2. \b \this returns an integer greater than, equal to, or less 
  than zero as the object pointed to by \a s1 is greater than, equal to, or 
  less than the object pointed to by \a s2.
*/
int wmemcmp(const wchar_t *s1, const wchar_t *s2, size_t n);


/*! \brief Search memory for a wide character \ingroup Search functions \synopsis

  \description \b \this locates the first occurrence of \a c in the initial
  \a n characters of the object pointed to by \a s.  Unlike \b wcschr, \b \this
  does \em not terminate a search when a null wide character is found in the object 
  pointed to by \a s.

  \b \this returns a pointer to the located wide character, or a null pointer 
  if \a c does not occur in the object.
*/
wchar_t *wmemchr(const wchar_t *s, wchar_t c, size_t n);


/*! \brief Set memory to wide character \ingroup Miscellaneous functions \synopsis

  \desc \b \this copies the value of \a c into each of the first \b n
  wide characters of the object pointed to by \a s. 

  \b \this returns the value of \a s.
*/
wchar_t *wmemset(wchar_t *s, wchar_t c, size_t n);


/*! \brief Copy string \ingroup Copying functions \synopsis

  \desc \b \this copies the wide string pointed to by \a s2 (including the terminating 
  null wide character) into the array pointed to by \a s1. The behavior of \b \this
  is undefined if copying takes place between objects that overlap.

  \b \this returns the value of \a s1.
*/
wchar_t *wcscpy(wchar_t *s1, const wchar_t *s2);


/*! \brief Copy string up to a maximum length \ingroup Copying functions \synopsis

  \desc \b \this copies not more than \a n wide characters from the array pointed 
  to by \a s2 to the array pointed to by \a s1. Wide characters that follow 
  a null wide character in \a s2 are not copied. The behavior of \b \this
  is undefined if copying takes place between objects that overlap. If the array 
  pointed to by \a s2 is a wide string that is shorter than \a n wide characters, 
  null wide characters are appended to the copy in the array pointed to by \a s1, 
  until \a n characters in all have been written.

  \b \this returns the value of \a s1.
*/
wchar_t *wcsncpy(wchar_t *s1, const wchar_t *s2, size_t n);


/*! \brief Concatenate strings \ingroup Copying functions \synopsis

  \desc \b \this appends a copy of the wide string pointed to by \a s2 (including 
  the terminating null wide character) to the end of the wide string pointed to by \a s1.
  The initial character of \a s2 overwrites the null wide character at the end 
  of \a s1. The behavior of \b \this is undefined if copying takes place 
  between objects that overlap.

  \b \this returns the value of \a s1.
*/
wchar_t *wcscat(wchar_t *s1, const wchar_t *s2);


/*! \brief Concatenate strings up to maximum length \ingroup Copying functions \synopsis

  \desc \b \this appends not more than \a n wude characters from the array pointed 
  to by \a s2 to the end of the wide string pointed to by \a s1. A null wide character 
  in \a s1 and wide characters that follow it are not appended. The initial wide character 
  of \a s2 overwrites the null wide character at the end of \a s1. A terminating 
  wide null character is always appended to the result. The behavior of \b \this
  is undefined if copying takes place between objects that overlap.

  \b \this returns the value of \a s1.
*/
wchar_t *wcsncat(wchar_t *s1, const wchar_t *s2, size_t n);


/*! \brief Compare strings \ingroup Comparison functions \synopsis

  \desc \b \this compares the wide string pointed to by \a s1 to the wide string pointed 
  to by \a s2. \b \this returns an integer greater than, equal to, or 
  less than zero if the wide string pointed to by \a s1 is greater than, equal 
  to, or less than the wide string pointed to by \a s2.
*/
int wcscmp(const wchar_t *s1, const wchar_t *s2);


/*! \brief Compare strings up to a maximum length \ingroup Comparison functions \synopsis

  \desc \b \this compares not more than \a n wide characters from the array pointed 
  to by \a s1 to the array pointed to by \a s2. Characters that follow 
  a null wide character are not compared.

  \b \this returns an integer greater than, equal to, or less than zero, 
  if the possibly null-terminated array pointed to by \a s1 is greater than, 
  equal to, or less than the possibly null-terminated array pointed to by \a s2.
*/
int wcsncmp(const wchar_t *s1, const wchar_t *s2, size_t n);


/*! \brief Find character within string \ingroup Search functions \synopsis

  \desc \b \this locates the first occurrence of \a c in the wide
  string pointed to by \a s. The terminating wide null character 
  is considered to be part of the string.

  \b \this returns a pointer to the located wide character, or a null pointer 
  if \a c does not occur in the string.
*/
wchar_t *wcschr(const wchar_t *s, wchar_t c);


/*! \brief Find character in a length-limited string \ingroup Search functions \synopsis

  \desc \b \this searches not more than \a n wide characters to locate the
  first occurrence of \a c in the wide string pointed to by \a s. The terminating
  wide null character is considered to be part of the wide string.

  \b \this returns a pointer to the located wide character, or a null pointer 
  if \a c does not occur in the string.
*/
wchar_t *wcsnchr(const wchar_t *str, size_t n, wchar_t ch);


/*! \brief Compute size of string not prefixed by a set of characters \ingroup Search functions \synopsis

  \desc \b \this computes the length of the maximum initial segment of the wide string
  pointed to by \a s1 which consists entirely of wide characters not from the wide string
  pointed to by \a s2.

  \b \this returns the length of the segment.
*/
size_t wcscspn(const wchar_t *s1, const wchar_t *s2);


/*! \brief Find first occurrence of characters within string \ingroup Search functions \synopsis

  \desc \b \this locates the first occurrence in the wide string pointed to by \a s1
  of any wide character from the wide string pointed to by \a s2.

  \b \this returns a pointer to the wide character, or a null pointer if no wide character 
  from \a s2 occurs in \a s1.
*/
wchar_t *wcspbrk(const wchar_t *s1, const wchar_t *s2);


/*! \brief Find last occurrence of character within string \ingroup Search functions \synopsis

  \desc \b \this locates the last occurrence of \a c in the wide string pointed to
  by \a s. The terminating wide null character is considered to be part of the string.

  \b \this returns a pointer to the wide character, or a null pointer if \a c
  does not occur in the wide string.
*/
wchar_t *wcsrchr(const wchar_t *s, wchar_t c);


/*! \brief Compute size of string prefixed by a set of characters \ingroup Search functions \synopsis

  \desc \b \this computes the length of the maximum initial segment of the wide string 
  pointed to by \a s1 which consists entirely of wide characters from the wide string
  pointed to by \a s2.

  \b \this returns the length of the segment.
*/
size_t wcsspn(const wchar_t *s1, const wchar_t *s2);


/*! \brief Find first occurrence of a string within string \ingroup Search functions \synopsis

  \desc \b \this locates the first occurrence in the wide string pointed to by \a s1
  of the sequence of wide characters (excluding the terminating null wide character) in 
  the wide string pointed to by \a s2.

  \b \this returns a pointer to the located wide string, or a null pointer if 
  the wide string is not found. If \a s2 points to a wide string with zero length, \b \this
  returns \a s1.
*/
wchar_t *wcsstr(const wchar_t *s1, const wchar_t *s2);


/*! \brief Find first occurrence of a string within length-limited string \ingroup Search functions \synopsis

  \desc \b \this searches at most \a n wide characters to locate the first occurrence
  in the wide string pointed to by \a s1 of the sequence of wide characters (excluding the
  terminating null wide character) in the wide string pointed to by \a s2.

  \b \this returns a pointer to the located string, or a null pointer if 
  the string is not found. If \a s2 points to a string with zero length, \b \this
  returns \a s1.

  \note \b \this is an extension commonly found in Linux and BSD C libraries.
*/
wchar_t *wcsnstr(const wchar_t *s1, const wchar_t *s2, size_t n);


/*! \brief Calculate length of string \ingroup Miscellaneous functions \synopsis

  \desc \b \this returns the length of the wide string pointed to by \a s, that 
  is the number of wide characters that precede the terminating null wide character.
*/
size_t wcslen(const wchar_t *s);


/*! \brief Calculate length of length-limited string \ingroup Search functions \synopsis

  \desc \b this returns the length of the wide string pointed to by \a s, up
  to a maximum of \a n wide characters.  \b \this only examines the first \a n wide characters
  of the string \a s.

  \note \b \this is an extension commonly found in Linux and BSD C libraries.
*/
size_t wcsnlen(const wchar_t *s, size_t n);


/*! \brief Break string into tokens \ingroup Search functions \synopsis

  \desc \b \this A sequence of calls to \b \this breaks the wide string pointed to by \a s1 
  into a sequence of tokens, each of which is delimited by a wide character from the 
  wide string pointed to by \a s2. The first call in the sequence has a non-null 
  first argument; subsequent calls in the sequence have a null first argument. 
  The separator wide string pointed to by \a s2 may be different from call to call. 

  The first call in the sequence searches the wide string pointed to by \a s1
  for the first wide character that is not contained in the current separator wide string
  pointed to by \a s2. If no such wide character is found, then there are no tokens 
  in the wide string pointed to by \a s1 and \b \this returns a null pointer. 
  If such a wide character is found, it is the start of the first token.

  \b \this then searches from there for a wide character that is contained in 
  the current wide separator string. If no such wide character is found, the current token 
  extends to the end of the wide string pointed to by \a s1, and subsequent searches 
  for a token will return a null pointer. If such a wude character is found, it is 
  overwritten by a wide null character, which terminates the current token. \b \this
  saves a pointer to the following wide character, from which the next search for a 
  token will start.

  Each subsequent call, with a null pointer as the value of the first argument, 
  starts searching from the saved pointer and behaves as described above.

  \note \b \this maintains static state and is therefore not reentrant and
  not thread safe.  See \ref wcstok_r for a thread-safe and reentrant
  variant.
*/
wchar_t *wcstok(wchar_t *s1, const wchar_t *s2);


/*! \brief Break string into tokens \ingroup Search functions \synopsis

  \desc \b \this locates, in the wide string referenced by \a{*stringp}, the first
  occurrence of any wide character in the wide string \a delim (or the terminating wide null
  character) and replaces it with a wide null character.  The location of the next character
  after the delimiter wide character (or NULL, if the end of the string was reached) is stored
  in \a{*stringp}.  The original value of \a{*stringp} is returned. 

  An empty field (that is, a wide character in the string \a delim occurs as the
  first wide character of \a{*stringp} can be detected by comparing the location
  referenced by the returned pointer to a wide null character. 

  If \a{*stringp} is initially null, \b \this returns null.
  
  \note \b \this is not an ISO C function, but appears in BSD4.4 and Linux.
*/
wchar_t *wstrsep(wchar_t **stringp, const wchar_t *delim);


/*! \brief Break string into tokens (reentrant version) \ingroup Search functions \synopsis

  \desc \b \this is a reentrant version of the function \b wcstok where the state is
  maintained in the object of type \b{wchar_t *} pointed to by \a s3.

  \note \b \this is an extension commonly found in Linux and BSD C libraries.

  \sa \ref wcstok.
*/
wchar_t *wcstok_r(wchar_t *s1, const wchar_t *s2, wchar_t **s3);


/*! \brief Duplicate string \ingroup Miscellaneous functions \synopsis

  \desc \b \this duplicates the wide string pointed to by \a s1 by using \b malloc to
  allocate memory for a copy of \a s and then copying \a s, including the
  terminating wide null character, to that memory. The returned pointer can be
  passed to \b free.
  
  \b \this returns a pointer to the new wide string or a null pointer if the
  new string cannot be created.

  \note \b \this is an extension commonly found in Linux and BSD C libraries.
*/
wchar_t *wcsdup(const wchar_t *s1);


#ifdef __cplusplus
}
#endif

#endif