/**
* g_unichar_isupper:
- * @c: a unicode character
+ * @c: a Unicode character
*
* Determines if a character is uppercase.
*
- * Return value: %TRUE if @c is an uppercase character.
+ * Return value: %TRUE if @c is an uppercase character
**/
gboolean
g_unichar_isupper (gunichar c)
/**
* g_unichar_istitle:
- * @c: a unicode character
+ * @c: a Unicode character
*
* Determines if a character is titlecase. Some characters in
* Unicode which are composites, such as the DZ digraph
* have three case variants instead of just two. The titlecase
* form is used at the beginning of a word where only the
* first letter is capitalized. The titlecase form of the DZ
- * digraph is U+01F2 LATIN CAPITAL LETTTER D WITH SMALL LETTER Z
+ * digraph is U+01F2 LATIN CAPITAL LETTTER D WITH SMALL LETTER Z.
*
- * Return value: %TRUE if the character is titlecase.
+ * Return value: %TRUE if the character is titlecase
**/
gboolean
g_unichar_istitle (gunichar c)
/**
* g_unichar_isxdigit:
- * @c: a unicode character.
+ * @c: a Unicode character.
*
- * Determines if a characters is a hexidecimal digit
+ * Determines if a character is a hexidecimal digit.
*
- * Return value: %TRUE if the character is a hexadecimal digit.
+ * Return value: %TRUE if the character is a hexadecimal digit
**/
gboolean
g_unichar_isxdigit (gunichar c)
/**
* g_unichar_isdefined:
- * @c: a unicode character
+ * @c: a Unicode character
*
* Determines if a given character is assigned in the Unicode
* standard.
*
- * Return value: %TRUE if the character has an assigned value.
+ * Return value: %TRUE if the character has an assigned value
**/
gboolean
g_unichar_isdefined (gunichar c)
/**
* g_unichar_iswide:
- * @c: a unicode character
+ * @c: a Unicode character
*
* Determines if a character is typically rendered in a double-width
* cell.
*
- * Return value: %TRUE if the character is wide.
+ * Return value: %TRUE if the character is wide
**/
/* This function stolen from Markus Kuhn <Markus.Kuhn@cl.cam.ac.uk>. */
gboolean
/**
* g_unichar_toupper:
- * @c: a unicode character
+ * @c: a Unicode character
*
- * Convert a character to uppercase.
+ * Converts a character to uppercase.
*
* Return value: the result of converting @c to uppercase.
* If @c is not an lowercase or titlecase character,
/**
* g_unichar_tolower:
- * @c: a unicode character.
+ * @c: a Unicode character.
*
- * Convert a character to lower case
+ * Converts a character to lower case.
*
* Return value: the result of converting @c to lower case.
* If @c is not an upperlower or titlecase character,
/**
* g_unichar_totitle:
- * @c: a unicode character
+ * @c: a Unicode character
*
- * Convert a character to the titlecase
+ * Converts a character to the titlecase.
*
* Return value: the result of converting @c to titlecase.
* If @c is not an uppercase or lowercase character,
/**
* g_unichar_digit_value:
- * @c: a unicode character
+ * @c: a Unicode character
*
* Determines the numeric value of a character as a decimal
* digit.
*
* Return value: If @c is a decimal digit (according to
- * `g_unichar_isdigit'), its numeric value. Otherwise, -1.
+ * g_unichar_isdigit()), its numeric value. Otherwise, -1.
**/
int
g_unichar_digit_value (gunichar c)
/**
* g_unichar_xdigit_value:
- * @c: a unicode character
+ * @c: a Unicode character
*
* Determines the numeric value of a character as a hexidecimal
* digit.
*
* Return value: If @c is a hex digit (according to
- * `g_unichar_isxdigit'), its numeric value. Otherwise, -1.
+ * g_unichar_isxdigit()), its numeric value. Otherwise, -1.
**/
int
g_unichar_xdigit_value (gunichar c)
/**
* g_unichar_type:
- * @c: a unicode character
+ * @c: a Unicode character
*
- * Classifies a unicode character by type.
+ * Classifies a Unicode character by type.
*
* Return value: the type of the character.
**/
/**
* g_utf8_find_prev_char:
- * @str: pointer to the beginning of a UTF-8 string
+ * @str: pointer to the beginning of a UTF-8 encoded string
* @p: pointer to some position within @str
*
* Given a position @p with a UTF-8 encoded string @str, find the start
* of the previous UTF-8 character starting before @p. Returns %NULL if no
* UTF-8 characters are present in @p before @str.
*
- * @p does not have to be at the beginning of a UTF-8 chracter. No check
+ * @p does not have to be at the beginning of a UTF-8 character. No check
* is made to see if the character found is actually valid other than
* it starts with an appropriate byte.
*
* g_utf8_find_next_char:
* @p: a pointer to a position within a UTF-8 encoded string
* @end: a pointer to the end of the string, or %NULL to indicate
- * that the string is NULL terminated, in which case
+ * that the string is nul-terminated, in which case
* the returned value will be
*
- * Find the start of the next utf-8 character in the string after @p
+ * Finds the start of the next UTF-8 character in the string after @p.
*
- * @p does not have to be at the beginning of a UTF-8 chracter. No check
+ * @p does not have to be at the beginning of a UTF-8 character. No check
* is made to see if the character found is actually valid other than
* it starts with an appropriate byte.
*
* g_utf8_prev_char:
* @p: a pointer to a position within a UTF-8 encoded string
*
- * Find the previous UTF-8 character in the string before @p.
+ * Finds the previous UTF-8 character in the string before @p.
*
* @p does not have to be at the beginning of a UTF-8 character. No check
* is made to see if the character found is actually valid other than
* it starts with an appropriate byte. If @p might be the first
- * character of the string, you must use g_utf8_find_prev_char instead.
+ * character of the string, you must use g_utf8_find_prev_char() instead.
*
* Return value: a pointer to the found character.
**/
/**
* g_utf8_strlen:
- * @p: pointer to the start of a UTF-8 string.
+ * @p: pointer to the start of a UTF-8 encoded string.
* @max: the maximum number of bytes to examine. If @max
* is less than 0, then the string is assumed to be
* nul-terminated.
*
+ * Returns the length of the string in characters.
+ *
* Return value: the length of the string in characters
**/
glong
/**
* g_utf8_get_char:
- * @p: a pointer to unicode character encoded as UTF-8
+ * @p: a pointer to Unicode character encoded as UTF-8
*
- * Convert a sequence of bytes encoded as UTF-8 to a unicode character.
+ * Converts a sequence of bytes encoded as UTF-8 to a Unicode character.
* If @p does not point to a valid UTF-8 encoded character, results are
* undefined. If you are not sure that the bytes are complete
- * valid unicode characters, you should use g_utf8_get_char_validated()
+ * valid Unicode characters, you should use g_utf8_get_char_validated()
* instead.
*
* Return value: the resulting character
/**
* g_utf8_offset_to_pointer:
* @str: a UTF-8 encoded string
- * @offset: a character offset within the string.
+ * @offset: a character offset within @str
*
* Converts from an integer character offset to a pointer to a position
* within the string.
* @pos: a pointer to a position within @str
*
* Converts from a pointer to position within a string to a integer
- * character offset
+ * character offset.
*
* Return value: the resulting character offset
**/
/**
* g_utf8_strncpy:
* @dest: buffer to fill with characters from @src
- * @src: UTF-8 string
+ * @src: UTF-8 encoded string
* @n: character count
*
- * Like the standard C strncpy() function, but copies a given number
- * of characters instead of a given number of bytes. The @src string
- * must be valid UTF-8 encoded text. (Use g_utf8_validate() on all
- * text before trying to use UTF-8 utility functions with it.)
+ * Like the standard C <function>strncpy()</function> function, but
+ * copies a given number of characters instead of a given number of
+ * bytes. The @src string must be valid UTF-8 encoded text.
+ * (Use g_utf8_validate() on all text before trying to use UTF-8
+ * utility functions with it.)
*
* Return value: @dest
**/
* @c: a ISO10646 character code
* @outbuf: output buffer, must have at least 6 bytes of space.
* If %NULL, the length will be computed and returned
- * and nothing will be written to @out.
+ * and nothing will be written to @outbuf.
*
- * Convert a single character to utf8
+ * Converts a single character to UTF-8.
*
* Return value: number of bytes written
**/
/**
* g_utf8_strchr:
- * @p: a nul-terminated utf-8 string
- * @len: the maximum length of p
- * @c: a iso-10646 character
+ * @p: a nul-terminated UTF-8 encoded string
+ * @len: the maximum length of @p
+ * @c: a ISO10646 character
*
- * Find the leftmost occurence of the given iso-10646 character
- * in a UTF-8 string, while limiting the search to p_len bytes.
- * If len is -1, allow unbounded search.
+ * Finds the leftmost occurrence of the given ISO10646 character
+ * in a UTF-8 encoded string, while limiting the search to @len bytes.
+ * If @len is -1, allow unbounded search.
*
- * Return value: NULL if the string does not contain the character, otherwise, a
- * a pointer to the start of the leftmost of the character in the string.
+ * Return value: %NULL if the string does not contain the character,
+ * otherwise, a pointer to the start of the leftmost occurrence of
+ * the character in the string.
**/
gchar *
g_utf8_strchr (const char *p,
/**
* g_utf8_strrchr:
- * @p: a nul-terminated utf-8 string
- * @len: the maximum length of p
- * @c: a iso-10646 character/
+ * @p: a nul-terminated UTF-8 encoded string
+ * @len: the maximum length of @p
+ * @c: a ISO10646 character
*
- * Find the rightmost occurence of the given iso-10646 character
- * in a UTF-8 string, while limiting the search to p_len bytes.
- * If len is -1, allow unbounded search.
+ * Find the rightmost occurrence of the given ISO10646 character
+ * in a UTF-8 encoded string, while limiting the search to @len bytes.
+ * If @len is -1, allow unbounded search.
*
- * Return value: NULL if the string does not contain the character, otherwise, a
- * a pointer to the start of the rightmost of the character in the string.
+ * Return value: %NULL if the string does not contain the character,
+ * otherwise, a pointer to the start of the rightmost occurrence of the
+ * character in the string.
**/
gchar *
g_utf8_strrchr (const char *p,
/**
* g_utf8_get_char_validated:
- * @p: a pointer to unicode character encoded as UTF-8
+ * @p: a pointer to Unicode character encoded as UTF-8
* @max_len: the maximum number of bytes to read, or -1, for no maximum.
*
- * Convert a sequence of bytes encoded as UTF-8 to a unicode character.
+ * Convert a sequence of bytes encoded as UTF-8 to a Unicode character.
* This function checks for incomplete characters, for invalid characters
* such as characters that are out of the range of Unicode, and for
* overlong encodings of valid characters.
* Return value: the resulting character. If @p points to a partial
* sequence at the end of a string that could begin a valid character,
* returns (gunichar)-2; otherwise, if @p does not point to a valid
- * UTF-8 encoded unicode character, returns (gunichar)-1.
+ * UTF-8 encoded Unicode character, returns (gunichar)-1.
**/
gunichar
g_utf8_get_char_validated (const gchar *p,
/**
* g_utf8_to_ucs4_fast:
* @str: a UTF-8 encoded string
- * @len: the maximum length of @str to use. If < 0, then
- * the string is %NULL terminated.
+ * @len: the maximum length of @str to use. If @len < 0, then
+ * the string is nul-terminated.
* @items_written: location to store the number of characters in the
* result, or %NULL.
*
* but does no error checking on the input.
*
* Return value: a pointer to a newly allocated UCS-4 string.
- * This value must be freed with g_free()
+ * This value must be freed with g_free().
**/
gunichar *
g_utf8_to_ucs4_fast (const gchar *str,
/**
* g_utf8_to_ucs4:
* @str: a UTF-8 encoded string
- * @len: the maximum length of @str to use. If < 0, then
- * the string is %NULL terminated.
+ * @len: the maximum length of @str to use. If @len < 0, then
+ * the string is nul-terminated.
* @items_read: location to store number of bytes read, or %NULL.
* If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
* returned in case @str contains a trailing partial
/**
* g_ucs4_to_utf8:
* @str: a UCS-4 encoded string
- * @len: the maximum length of @str to use. If < 0, then
- * the string is %NULL terminated.
+ * @len: the maximum length of @str to use. If @len < 0, then
+ * the string is terminated with a 0 character.
* @items_read: location to store number of characters read read, or %NULL.
* @items_written: location to store number of bytes written or %NULL.
* The value here stored does not include the trailing 0
/**
* g_utf16_to_utf8:
* @str: a UTF-16 encoded string
- * @len: the maximum length of @str to use. If < 0, then
+ * @len: the maximum length of @str to use. If @len < 0, then
* the string is terminated with a 0 character.
* @items_read: location to store number of words read, or %NULL.
* If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
/**
* g_utf16_to_ucs4:
* @str: a UTF-16 encoded string
- * @len: the maximum length of @str to use. If < 0, then
+ * @len: the maximum length of @str to use. If @len < 0, then
* the string is terminated with a 0 character.
* @items_read: location to store number of words read, or %NULL.
* If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
/**
* g_utf8_to_utf16:
* @str: a UTF-8 encoded string
- * @len: the maximum length of @str to use. If < 0, then
- * the string is %NULL terminated.
+ * @len: the maximum length of @str to use. If @len < 0, then
+ * the string is nul-terminated.
* @items_read: location to store number of bytes read, or %NULL.
* If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
/**
* g_ucs4_to_utf16:
* @str: a UCS-4 encoded string
- * @len: the maximum length of @str to use. If < 0, then
- * the string is terminated with a zero character.
+ * @len: the maximum length of @str to use. If @len < 0, then
+ * the string is terminated with a 0 character.
* @items_read: location to store number of bytes read, or %NULL.
* If an error occurs then the index of the invalid input
* is stored here.
* if some bytes were invalid, or the end of the text being validated
* otherwise).
*
- * Returns TRUE if all of @str was valid. Many GLib and GTK+
- * routines <emphasis>require</emphasis> valid UTF8 as input;
+ * Returns %TRUE if all of @str was valid. Many GLib and GTK+
+ * routines <emphasis>require</emphasis> valid UTF-8 as input;
* so data read from a file or the network should be checked
* with g_utf8_validate() before doing anything else with it.
*
- * Return value: TRUE if the text was valid UTF-8.
+ * Return value: %TRUE if the text was valid UTF-8
**/
gboolean
g_utf8_validate (const gchar *str,