camel-utf8: Camel Reference Manual

## camel-utf8 camel-utf8 |

## Functions

void | camel_utf8_putc ()
guint32 | camel_utf8_getc ()
guint32 | camel_utf8_getc_limit ()
gchar * | camel_utf7_utf8 ()
gchar * | camel_utf8_utf7 ()
gchar * | camel_utf8_ucs2 ()
gchar * | camel_ucs2_utf8 ()
gchar * | camel_utf8_make_valid ()
gchar * | camel_utf8_make_valid_len ()

## Description

## Functions

### camel_utf8_putc ()

    void
    camel_utf8_putc (guchar **ptr,
                     guint32 c);

Output a 32 bit unicode character as UTF-8 octets. At most 4 octets will be written to `ptr` . The `ptr` will be advanced to the next character position.

#### Parameters

ptr | pointer to write the character to. | [inout]
c | a Unicode character to write |

### camel_utf8_getc ()

    guint32
    camel_utf8_getc (const guchar **ptr);

Get a Unicode character from a UTF-8 stream. `ptr` will be advanced to the next character position. Invalid utf8 characters will be silently skipped. The `ptr` should point to a NUL terminated array.

#### Parameters

ptr | a pointer to read the character from. | [inout]

#### Returns

The next Unicode character. The `ptr` will be advanced to the next character always.

### camel_utf8_getc_limit ()

    guint32
    camel_utf8_getc_limit (const guchar **ptr,
                           const guchar *end);

Get the next UTF-8 gchar at `ptr` , and return it, advancing `ptr` to the next character. If `end` is reached before a full UTF-8 character can be read, then the invalid Unicode gchar 0xffff is returned as a sentinel (Unicode 3.1, section 2.7), and `ptr` is not advanced.

#### Parameters

ptr | a pointer to read the character from. | [inout]
end | upper limit for the read, must not be `NULL` |

#### Returns

The next UTF-8 char, or 0xffff.

### camel_utf7_utf8 ()

    gchar *
    camel_utf7_utf8 (const gchar *ptr);

Convert a modified UTF-7 string to UTF-8. If the UTF-7 string contains 8 bit characters, they are treated as iso-8859-1.

The IMAP rules [rfc2060] are used in the UTF-7 encoding.

#### Parameters

ptr | a UTF-7 string to convert |

#### Returns

The converted string. Free it with `g_free()`, when no longer needed.

[transfer full]

### camel_utf8_utf7 ()

    gchar *
    camel_utf8_utf7 (const gchar *ptr);

Convert a UTF-8 string to a modified UTF-7 format.

The IMAP rules [rfc2060] are used in the UTF-7 encoding.

#### Parameters

ptr | a UTF-8 string to convert |

#### Returns

The converted string. Free it with `g_free()`, when no longer needed.

[transfer full]

### camel_utf8_ucs2 ()

    gchar *
    camel_utf8_ucs2 (const gchar *ptr);

Convert a UTF-8 string into a ucs2 one. The ucs string will be in network byte order, and terminated with a 16-bit `NULL`.

#### Parameters

ptr | a UTF-8 string to convert |

#### Returns

The converted string. Free it with `g_free()`, when no longer needed.

[transfer full]

### camel_ucs2_utf8 ()

    gchar *
    camel_ucs2_utf8 (const gchar *ptr);

Convert a ucs2 string into a UTF-8 one. The ucs2 string is treated as network byte ordered, and terminated with a 16-bit `NULL`.

#### Parameters

ptr | a ucs2 string to convert |

#### Returns

The converted string. Free it with `g_free()`, when no longer needed.

[transfer full]

### camel_utf8_make_valid ()

    gchar *
    camel_utf8_make_valid (const gchar *text);

Ensures the returned text will be valid UTF-8 string, with incorrect letters changed to question marks.

#### Parameters

text | a text to make valid |

#### Returns

Valid UTF-8 string, with replaced incorrect letters. Free it with `g_free()`, when no longer needed.

[transfer full]

Since: 2.26

### camel_utf8_make_valid_len ()

    gchar *
    camel_utf8_make_valid_len (const gchar *text,
                               gssize text_len);

Ensures the returned text will be valid UTF-8 string, with incorrect letters changed to question marks.

#### Parameters

text | a text to make valid |
text_len | length of the `text` , or -1 if NUL-terminated |

#### Returns

Valid UTF-8 string, with replaced incorrect letters. Free it with `g_free()`, when no longer needed.

[transfer full]

Since: 3.34