Index: uspace/lib/c/generic/str.c =================================================================== --- uspace/lib/c/generic/str.c (revision 08e103d46af516da7dcb378db322a88e2c4aca0b) +++ uspace/lib/c/generic/str.c (revision 1d2f85e056d4e6e3a0f3c692edee43e8b87c64b8) @@ -41,5 +41,5 @@ * Strings and characters use the Universal Character Set (UCS). The standard * strings, called just strings are encoded in UTF-8. Wide strings (encoded - * in UTF-32) are supported to a limited degree. A single character is + * in UTF-32) are supported to a limited degree. A single code point is * represented as wchar_t.@n * @@ -50,5 +50,5 @@ * byte 8 bits stored in uint8_t (unsigned 8 bit integer) * - * character UTF-32 encoded Unicode character, stored in wchar_t + * character UTF-32 encoded Unicode code point, stored in wchar_t * (signed 32 bit integer), code points 0 .. 1114111 * are valid @@ -66,5 +66,5 @@ * the NULL-terminator), size_t * - * [wide] string length number of CHARACTERS in a [wide] string (excluding + * [wide] string length number of CODE POINTS in a [wide] string (excluding * the NULL-terminator), size_t * @@ -80,5 +80,5 @@ * NULL-terminator) * - * length l size_t number of CHARACTERS in a string (excluding the + * length l size_t number of CODE POINTS in a string (excluding the * null terminator) * @@ -89,5 +89,5 @@ * Function naming prefixes:@n * - * chr_ operate on characters + * chr_ operate on code points * ascii_ operate on ASCII characters * str_ operate on strings @@ -102,5 +102,5 @@ * pointer (char *, wchar_t *) * byte offset (size_t) - * character index (size_t) + * code point index (size_t) * */ @@ -138,9 +138,9 @@ #define CONT_BITS 6 -/** Decode a single character from a string. - * - * Decode a single character from a string of size @a size. Decoding starts +/** Decode a single code point from an UTF-8 encoded string. + * + * Decode a single code point from a string of size @a size. Decoding starts * at @a offset and this offset is moved to the beginning of the next - * character. In case of decoding error, offset generally advances at least + * code point. In case of decoding error, offset generally advances at least * by one. However, offset is never moved beyond size. * @@ -149,5 +149,5 @@ * @param size Size of the string (in bytes). * - * @return Value of decoded character, U_SPECIAL on decoding error or + * @return Value of decoded code point, U_SPECIAL on decoding error or * NULL if attempt to decode beyond @a size. * @@ -208,9 +208,9 @@ } -/** Decode a single character from a string to the left. - * - * Decode a single character from a string of size @a size. Decoding starts +/** Decode a single code point from an UTF-8 encoded string to the left. + * + * Decode a single code point from a string of size @a size. Decoding starts * at @a offset and this offset is moved to the beginning of the previous - * character. In case of decoding error, offset generally decreases at least + * code point. In case of decoding error, offset generally decreases at least * by one. However, offset is never moved before 0. * @@ -219,5 +219,5 @@ * @param size Size of the string (in bytes). * - * @return Value of decoded character, U_SPECIAL on decoding error or + * @return Value of decoded code point, U_SPECIAL on decoding error or * NULL if attempt to decode beyond @a start of str. * @@ -251,17 +251,17 @@ } -/** Encode a single character to string representation. - * - * Encode a single character to string representation (i.e. UTF-8) and store +/** Encode a single code point to a UTF-8 string representation. + * + * Encode a single code point to a UTF-8 string representation and store * it into a buffer at @a offset. Encoding starts at @a offset and this offset - * is moved to the position where the next character can be written to. - * - * @param ch Input character. + * is moved to the position where the next code point can be written to. + * + * @param ch Input code point. * @param str Output buffer. * @param offset Byte offset where to start writing. * @param size Size of the output buffer (in bytes). * - * @return EOK if the character was encoded successfully, EOVERFLOW if there - * was not enough space in the output buffer or EINVAL if the character + * @return EOK if the code point was encoded successfully, EOVERFLOW if there + * was not enough space in the output buffer or EINVAL if the code point * code was invalid. */ @@ -357,15 +357,15 @@ } -/** Get size of string with length limit. +/** Get size of string with code point count limit. * * Get the number of bytes which are used by up to @a max_len first - * characters in the string @a str. If @a max_len is greater than - * the length of @a str, the entire string is measured (excluding the - * NULL-terminator). + * code points in the string @a str. If @a max_len is greater than + * the number of code points in @a str, the entire string is measured + * (excluding the NULL-terminator). * * @param str String to consider. - * @param max_len Maximum number of characters to measure. - * - * @return Number of bytes used by the characters. + * @param max_len Maximum number of code points to measure. + * + * @return Number of bytes used by the code points. * */ @@ -425,12 +425,12 @@ * * Get the number of bytes which are used by up to @a max_len first - * wide characters in the wide string @a str. If @a max_len is greater than + * code points in the wide string @a str. If @a max_len is greater than * the length of @a str, the entire wide string is measured (excluding the * NULL-terminator). * * @param str Wide string to consider. - * @param max_len Maximum number of wide characters to measure. - * - * @return Number of bytes used by the wide characters. + * @param max_len Maximum number of code points to measure. + * + * @return Number of bytes used by the code points. * */ @@ -440,9 +440,9 @@ } -/** Get number of characters in a string. - * - * @param str NULL-terminated string. - * - * @return Number of characters in string. +/** Get number of unicode code points in a UTF-8 encoded string. + * + * @param str NULL-terminated UTF-8 string. + * + * @return Number of code points in the string. * */ @@ -458,9 +458,9 @@ } -/** Get number of characters in a wide string. +/** Get number of code points in a wide string. * * @param str NULL-terminated wide string. * - * @return Number of characters in @a str. + * @return Number of code points in @a str. * */ @@ -475,10 +475,10 @@ } -/** Get number of characters in a string with size limit. +/** Get number of code points in a string with size limit. * * @param str NULL-terminated string. * @param size Maximum number of bytes to consider. * - * @return Number of characters in string. + * @return Number of code points in string. * */ @@ -494,10 +494,10 @@ } -/** Get number of characters in a string with size limit. +/** Get number of code points in a string with size limit. * * @param str NULL-terminated string. * @param size Maximum number of bytes to consider. * - * @return Number of characters in string. + * @return Number of code points in string. * */ @@ -516,8 +516,8 @@ } -/** Get character display width on a character cell display. - * - * @param ch Character - * @return Width of character in cells. +/** Get display width of a code point on a character cell display. + * + * @param ch Code point + * @return Display width in cells. */ size_t chr_width(wchar_t ch) @@ -543,7 +543,7 @@ } -/** Check whether character is plain ASCII. - * - * @return True if character is plain ASCII. +/** Check whether code point is plain ASCII. + * + * @return True if code point is plain ASCII. * */ @@ -556,7 +556,7 @@ } -/** Check whether character is valid - * - * @return True if character is a valid Unicode code point. +/** Check whether code point is valid + * + * @return True if code point is a valid Unicode code point. * */ @@ -573,10 +573,10 @@ * Do a char-by-char comparison of two NULL-terminated strings. * The strings are considered equal iff their length is equal - * and both strings consist of the same sequence of characters. - * - * A string S1 is less than another string S2 if it has a character with - * lower value at the first character position where the strings differ. + * and both strings consist of the same sequence of code points. + * + * A string S1 is less than another string S2 if it has a code point with + * lower value at the first code point position where the strings differ. * If the strings differ in length, the shorter one is treated as if - * padded by characters with a value of zero. + * padded by code points with a value of zero. * * @param s1 First string to compare. @@ -617,16 +617,16 @@ * The strings are considered equal iff * min(str_code_points(s1), max_len) == min(str_code_points(s2), max_len) - * and both strings consist of the same sequence of characters, - * up to max_len characters. - * - * A string S1 is less than another string S2 if it has a character with - * lower value at the first character position where the strings differ. + * and both strings consist of the same sequence of code points, + * up to max_len code points. + * + * A string S1 is less than another string S2 if it has a code point with + * lower value at the first code point position where the strings differ. * If the strings differ in length, the shorter one is treated as if - * padded by characters with a value of zero. Only the first max_len - * characters are considered. + * padded by code points with a value of zero. Only the first max_len + * code points are considered. * * @param s1 First string to compare. * @param s2 Second string to compare. - * @param max_len Maximum number of characters to consider. + * @param max_len Maximum number of code points to consider. * * @return 0 if the strings are equal, -1 if the first is less than the second, @@ -671,11 +671,11 @@ * Do a char-by-char comparison of two NULL-terminated strings. * The strings are considered equal iff their length is equal - * and both strings consist of the same sequence of characters + * and both strings consist of the same sequence of code points * when converted to lower case. * - * A string S1 is less than another string S2 if it has a character with - * lower value at the first character position where the strings differ. + * A string S1 is less than another string S2 if it has a code point with + * lower value at the first code point position where the strings differ. * If the strings differ in length, the shorter one is treated as if - * padded by characters with a value of zero. + * padded by code points with a value of zero. * * @param s1 First string to compare. @@ -717,16 +717,16 @@ * The strings are considered equal iff * min(str_code_points(s1), max_len) == min(str_code_points(s2), max_len) - * and both strings consist of the same sequence of characters, - * up to max_len characters. - * - * A string S1 is less than another string S2 if it has a character with - * lower value at the first character position where the strings differ. + * and both strings consist of the same sequence of code points, + * up to max_len code points. + * + * A string S1 is less than another string S2 if it has a code point with + * lower value at the first code point position where the strings differ. * If the strings differ in length, the shorter one is treated as if - * padded by characters with a value of zero. Only the first max_len - * characters are considered. + * padded by code points with a value of zero. Only the first max_len + * code points are considered. * * @param s1 First string to compare. * @param s2 Second string to compare. - * @param max_len Maximum number of characters to consider. + * @param max_len Maximum number of code points to consider. * * @return 0 if the strings are equal, -1 if the first is less than the second, @@ -808,5 +808,5 @@ * No more than @a size bytes are written. If the size of the output buffer * is at least one byte, the output string will always be well-formed, i.e. - * null-terminated and containing only complete characters. + * null-terminated and containing only complete code points. * * @param dest Destination buffer. @@ -838,5 +838,5 @@ * @a dest. No more than @a size bytes are written. The output string will * always be well-formed, i.e. null-terminated and containing only complete - * characters. + * code points. * * No more than @a n bytes are read from the input string, so it does not @@ -871,5 +871,5 @@ * Size of the destination buffer is @a dest. If the size of the output buffer * is at least one byte, the output string will always be well-formed, i.e. - * null-terminated and containing only complete characters. + * null-terminated and containing only complete code points. * * @param dest Destination buffer. @@ -1030,5 +1030,5 @@ * * @param dest Destination buffer. - * @param dlen Number of utf16 characters that fit in the destination buffer. + * @param dlen Number of utf16 code points that fit in the destination buffer. * @param src Source string. * @@ -1188,10 +1188,10 @@ } -/** Find first occurence of character in string. +/** Find first occurence of code point in string. * * @param str String to search. - * @param ch Character to look for. - * - * @return Pointer to character in @a str or NULL if not found. + * @param ch code point to look for. + * + * @return Pointer to code point in @a str or NULL if not found. */ char *str_chr(const char *str, wchar_t ch) @@ -1215,5 +1215,5 @@ * @param n Needle (substring to look for) * - * @return Pointer to character in @a hs or @c NULL if not found. + * @return Pointer to substring in @a hs or @c NULL if not found. */ char *str_str(const char *hs, const char *n) @@ -1232,8 +1232,8 @@ } -/** Removes specified trailing characters from a string. +/** Removes specified trailing code points from a string. * * @param str String to remove from. - * @param ch Character to remove. + * @param ch Code point to remove. */ void str_rtrim(char *str, wchar_t ch) @@ -1260,8 +1260,8 @@ } -/** Removes specified leading characters from a string. +/** Removes specified leading code points from a string. * * @param str String to remove from. - * @param ch Character to remove. + * @param ch code point to remove. */ void str_ltrim(char *str, wchar_t ch) @@ -1286,10 +1286,10 @@ } -/** Find last occurence of character in string. +/** Find last occurence of code point in string. * * @param str String to search. - * @param ch Character to look for. - * - * @return Pointer to character in @a str or NULL if not found. + * @param ch code point to look for. + * + * @return Pointer to code point in @a str or NULL if not found. */ char *str_rchr(const char *str, wchar_t ch) @@ -1309,13 +1309,13 @@ } -/** Insert a wide character into a wide string. - * - * Insert a wide character into a wide string at position - * @a pos. The characters after the position are shifted. +/** Insert a code point into a wide string. + * + * Insert a code point into a wide string at position + * @a pos. The code points after the position are shifted. * * @param str String to insert to. - * @param ch Character to insert to. - * @param pos Character index where to insert. - * @param max_pos Characters in the buffer. + * @param ch Code point to insert. + * @param pos Code point index where to insert. + * @param max_pos Number of code points that fit in the buffer. * * @return True if the insertion was sucessful, false if the position @@ -1339,11 +1339,11 @@ } -/** Remove a wide character from a wide string. - * - * Remove a wide character from a wide string at position - * @a pos. The characters after the position are shifted. +/** Remove a code point from a wide string. + * + * Remove a code point from a wide string at position + * @a pos. The code points after the position are shifted. * * @param str String to remove from. - * @param pos Character index to remove. + * @param pos Code point index to remove. * * @return True if the removal was sucessful, false if the position @@ -1367,10 +1367,8 @@ /** Duplicate string. * - * Allocate a new string and copy characters from the source - * string into it. The duplicate string is allocated via sleeping - * malloc(), thus this function can sleep in no memory conditions. - * - * The allocation cannot fail and the return value is always - * a valid pointer. The duplicate string is always a well-formed + * Allocate a new string and copy the contents of the source string into it. + * The duplicate string is allocated as if by malloc(). + * + * If successful, the duplicate string is always a well-formed * null-terminated UTF-8 string, but it can differ from the source * string on the byte level. @@ -1378,5 +1376,5 @@ * @param src Source string. * - * @return Duplicate string. + * @return Duplicate string, or NULL if allocation failed. * */ @@ -1395,12 +1393,10 @@ * * Allocate a new string and copy up to @max_size bytes from the source - * string into it. The duplicate string is allocated via sleeping - * malloc(), thus this function can sleep in no memory conditions. + * string into it. The duplicate string is allocated as if by malloc(). * No more than @max_size + 1 bytes is allocated, but if the size * occupied by the source string is smaller than @max_size + 1, * less is allocated. * - * The allocation cannot fail and the return value is always - * a valid pointer. The duplicate string is always a well-formed + * If successful, the duplicate string is always a well-formed * null-terminated UTF-8 string, but it can differ from the source * string on the byte level.