Added some warnings to the docs about converting bad Unicode strings.

This commit is contained in:
Ryan C. Gordon 2017-08-20 02:01:50 -04:00
parent 9f8ecb91cb
commit bc2ddf0a53
1 changed files with 24 additions and 0 deletions

View File

@ -2386,6 +2386,10 @@ PHYSFS_DECL void PHYSFS_enumerateFilesCallback(const char *dir,
* \fn void PHYSFS_utf8FromUcs4(const PHYSFS_uint32 *src, char *dst, PHYSFS_uint64 len)
* \brief Convert a UCS-4 string to a UTF-8 string.
*
* \warning This function will not report an error if there are invalid UCS-4
* values in the source string. It will replace them with a '?'
* character and continue on.
*
* UCS-4 (aka UTF-32) strings are 32-bits per character: \c wchar_t on Unix.
*
* To ensure that the destination buffer is large enough for the conversion,
@ -2408,6 +2412,10 @@ PHYSFS_DECL void PHYSFS_utf8FromUcs4(const PHYSFS_uint32 *src, char *dst,
* \fn void PHYSFS_utf8ToUcs4(const char *src, PHYSFS_uint32 *dst, PHYSFS_uint64 len)
* \brief Convert a UTF-8 string to a UCS-4 string.
*
* \warning This function will not report an error if there are invalid UTF-8
* sequences in the source string. It will replace them with a '?'
* character and continue on.
*
* UCS-4 (aka UTF-32) strings are 32-bits per character: \c wchar_t on Unix.
*
* To ensure that the destination buffer is large enough for the conversion,
@ -2433,6 +2441,10 @@ PHYSFS_DECL void PHYSFS_utf8ToUcs4(const char *src, PHYSFS_uint32 *dst,
* \warning you almost certainly should use PHYSFS_utf8FromUtf16(), which
* became available in PhysicsFS 2.1, unless you know what you're doing.
*
* \warning This function will not report an error if there are invalid UCS-2
* values in the source string. It will replace them with a '?'
* character and continue on.
*
* UCS-2 strings are 16-bits per character: \c TCHAR on Windows, when building
* with Unicode support. Please note that modern versions of Windows use
* UTF-16, which is an extended form of UCS-2, and not UCS-2 itself. You
@ -2463,6 +2475,10 @@ PHYSFS_DECL void PHYSFS_utf8FromUcs2(const PHYSFS_uint16 *src, char *dst,
* \warning you almost certainly should use PHYSFS_utf8ToUtf16(), which
* became available in PhysicsFS 2.1, unless you know what you're doing.
*
* \warning This function will not report an error if there are invalid UTF-8
* sequences in the source string. It will replace them with a '?'
* character and continue on.
*
* UCS-2 strings are 16-bits per character: \c TCHAR on Windows, when building
* with Unicode support. Please note that modern versions of Windows use
* UTF-16, which is an extended form of UCS-2, and not UCS-2 itself. You
@ -2829,6 +2845,10 @@ PHYSFS_DECL int PHYSFS_stat(const char *fname, PHYSFS_Stat *stat);
* \fn void PHYSFS_utf8FromUtf16(const PHYSFS_uint16 *src, char *dst, PHYSFS_uint64 len)
* \brief Convert a UTF-16 string to a UTF-8 string.
*
* \warning This function will not report an error if there are invalid UTF-16
* sequences in the source string. It will replace them with a '?'
* character and continue on.
*
* UTF-16 strings are 16-bits per character (except some chars, which are
* 32-bits): \c TCHAR on Windows, when building with Unicode support. Modern
* Windows releases use UTF-16. Windows releases before 2000 used TCHAR, but
@ -2856,6 +2876,10 @@ PHYSFS_DECL void PHYSFS_utf8FromUtf16(const PHYSFS_uint16 *src, char *dst,
* \fn PHYSFS_utf8ToUtf16(const char *src, PHYSFS_uint16 *dst, PHYSFS_uint64 len)
* \brief Convert a UTF-8 string to a UTF-16 string.
*
* \warning This function will not report an error if there are invalid UTF-8
* sequences in the source string. It will replace them with a '?'
* character and continue on.
*
* UTF-16 strings are 16-bits per character (except some chars, which are
* 32-bits): \c TCHAR on Windows, when building with Unicode support. Modern
* Windows releases use UTF-16. Windows releases before 2000 used TCHAR, but