issue #4660: Updates comments and doc for deprecated ccutf8 api

This commit is contained in:
James Chen 2014-05-10 21:51:42 +08:00
parent 448c1ad352
commit 602fa28577
2 changed files with 49 additions and 32 deletions

View File

@ -177,6 +177,8 @@ long getCharacterCountInUTF8String(const std::string& utf8)
int cc_wcslen(const unsigned short* str)
{
if (str == nullptr)
return -1;
int i=0;
while(*str++) i++;
return i;
@ -184,6 +186,8 @@ int cc_wcslen(const unsigned short* str)
void cc_utf8_trim_ws(std::vector<unsigned short>* str)
{
if (str == nullptr)
return;
// unsigned short and char16_t are both 2 bytes
std::vector<char16_t>* ret = reinterpret_cast<std::vector<char16_t>*>(str);
StringUtils::trimUTF16Vector(*ret);
@ -204,6 +208,8 @@ bool iscjk_unicode(unsigned short ch)
long cc_utf8_strlen (const char * p, int max)
{
CC_UNUSED_PARAM(max);
if (p == nullptr)
return -1;
return StringUtils::getCharacterCountInUTF8String(p);
}
@ -220,9 +226,13 @@ unsigned int cc_utf8_find_last_not_char(const std::vector<unsigned short>& str,
std::vector<unsigned short> cc_utf16_vec_from_utf16_str(const unsigned short* str)
{
int len = cc_wcslen(str);
std::vector<unsigned short> str_new;
if (str == nullptr)
return str_new;
int len = cc_wcslen(str);
for (int i = 0; i < len; ++i)
{
str_new.push_back(str[i]);

View File

@ -122,8 +122,16 @@ CC_DLL std::vector<char16_t> getChar16VectorFromUTF16String(const std::u16string
} // namespace StringUtils {
/**
* Returns the character count in UTF16 string
* @param str pointer to the start of a UTF-16 encoded string. It must be an NULL terminal UTF8 string.
* @deprecated Please use c++11 `std::u16string::length` instead, don't use `unsigned short*` directly
*/
CC_DEPRECATED_ATTRIBUTE CC_DLL int cc_wcslen(const unsigned short* str);
CC_DLL int cc_wcslen(const unsigned short* str);
/** Trims the space characters at the end of UTF8 string
* @deprecated Please use `StringUtils::trimUTF16Vector` instead
*/
CC_DEPRECATED_ATTRIBUTE void cc_utf8_trim_ws(std::vector<unsigned short>* str);
@ -132,6 +140,7 @@ CC_DEPRECATED_ATTRIBUTE void cc_utf8_trim_ws(std::vector<unsigned short>* str);
*
* @param ch the unicode character
* @returns whether the character is a white space character.
* @deprecated Please use `StringUtils::isUnicodeSpace` instead
*
* @see http://en.wikipedia.org/wiki/Whitespace_character#Unicode
* */
@ -142,6 +151,7 @@ CC_DEPRECATED_ATTRIBUTE bool isspace_unicode(unsigned short ch);
*
* @param ch the unicode character
* @returns whether the character is a Chinese character.
* @deprecated Please use `StringUtils::isCJKUnicode` instead
*
* @see http://www.searchtb.com/2012/04/chinese_encode.html
* @see http://tieba.baidu.com/p/748765987
@ -151,59 +161,56 @@ CC_DEPRECATED_ATTRIBUTE bool iscjk_unicode(unsigned short ch);
/**
* Returns the length of the string in characters.
*
* @param p pointer to the start of a UTF-8 encoded string.
* @param max the maximum number of bytes to examine. If \p max is less than
* 0, then the string is assumed to be null-terminated. If \p max
* is 0, \p p will not be examined and my be %nullptr.
*
* @param p pointer to the start of a UTF-8 encoded string. It must be an NULL terminal UTF8 string.
* @param max Not used from 3.1, just keep it for backward compatibility
* @deprecated Please use `StringUtils::getCharacterCountInUTF8String` instead
* @returns the length of the string in characters
**/
CC_DEPRECATED_ATTRIBUTE long
cc_utf8_strlen (const char * p, int max);
CC_DEPRECATED_ATTRIBUTE long cc_utf8_strlen (const char * p, int max = -1);
/**
* Find the last character that is not equal to the character given.
*
* @param str the string to be searched.
* @param c the character to be searched for.
*
* @deprecated Please use `StringUtils::getIndexOfLastNotChar16` instead
* @returns the index of the last character that is not \p c.
* */
CC_DEPRECATED_ATTRIBUTE unsigned int cc_utf8_find_last_not_char(const std::vector<unsigned short>& str, unsigned short c);
/**
* @brief Gets `unsigned short` vector from a given utf16 string
* @deprecated Please use `StringUtils::getChar16VectorFromUTF16String` instead
*/
CC_DEPRECATED_ATTRIBUTE std::vector<unsigned short> cc_utf16_vec_from_utf16_str(const unsigned short* str);
/**
* Creates a utf8 string from a cstring.
* Creates an utf8 string from a c string. The result will be null terminated.
*
* @param str_old pointer to the start of a C string.
*
* @returns the newly created utf8 string.
* @param str_old pointer to the start of a C string. It must be an NULL terminal UTF8 string.
* @param length not used from 3.1, keep it just for backward compatibility
* @param rUtf16Size The character count in the return UTF16 string.
* @deprecated Please use `StringUtils::UTF8ToUTF16` instead
* @returns the newly created utf16 string, it must be released with `delete[]`,
* If an error occurs, %NULL will be returned.
* */
CC_DEPRECATED_ATTRIBUTE unsigned short* cc_utf8_to_utf16(const char* str_old, int length = -1, int* rUtf16Size = nullptr);
/**
* Convert a string from UTF-16 to UTF-8. The result will be null terminated.
*
* @param str a UTF-16 encoded string
* @param len the maximum length of \p str to use. If \p len < 0, then the
* string is null terminated.
* @param items_read location to store number of words read, or %nullptr.
* If %nullptr, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
* returned in case \p str contains a trailing partial
* character. If an error occurs then the index of the
* invalid input is stored here.
* @param items_written location to store number of bytes written, or %nullptr.
* The value stored here does not include the trailing null.
* Converts a string from UTF-16 to UTF-8. The result will be null terminated.
*
* @param utf16 an UTF-16 encoded string, It must be an NULL terminal UTF16 string.
* @param len not used from 3.1, keep it just for backward compatibility
* @param items_read not used from 3.1, keep it just for backward compatibility
* @param items_written not used from 3.1, keep it just for backward compatibility
* @deprecated Please use `StringUtils::UTF16ToUTF8` instead
* @returns a pointer to a newly allocated UTF-8 string. This value must be
* freed with free(). If an error occurs, %nullptr will be returned.
* released with `delete[]`. If an error occurs, %NULL will be returned.
**/
CC_DEPRECATED_ATTRIBUTE char *
cc_utf16_to_utf8 (const unsigned short *str,
int len,
long *items_read,
long *items_written);
CC_DEPRECATED_ATTRIBUTE char * cc_utf16_to_utf8 (const unsigned short *str,
int len = -1,
long *items_read = nullptr,
long *items_written = nullptr);
NS_CC_END