GtkSourceIconv: libgedit-gtksourceview 300 Reference Manual

GtkSourceIconv

GtkSourceIconv — To use iconv more comfortably

Functions

GtkSourceIconv *	gtk_source_iconv_new ()
gboolean	gtk_source_iconv_open ()
GtkSourceIconvResult	gtk_source_iconv_feed ()
GtkSourceIconvResult	gtk_source_iconv_feed_discard_output ()
gboolean	gtk_source_iconv_close ()
void	gtk_source_iconv_free ()

Types and Values

	GtkSourceIconv
enum	GtkSourceIconvResult

Includes

#include <gtksourceview/gtksource.h>

Description

GtkSourceIconv is a small wrapper for the g_iconv() family of functions, to use iconv more comfortably. GtkSourceIconv returns GError's and enum values for the different situations.

Call the functions in this order:

gtk_source_iconv_new()
gtk_source_iconv_open()
gtk_source_iconv_feed() in a loop.
gtk_source_iconv_feed() with inbuf and inbytes_left set to NULL (in a loop too if the output buffer is full).
gtk_source_iconv_close()
gtk_source_iconv_free()

Note that GLib provides the g_convert() family of functions. As the g_convert() documentation explains, it is necessary to use g_iconv() (or GtkSourceIconv) for streaming conversions. One other use-case is to have more control over invalid characters: in the case of the GtkSourceView library, it is desirable to apply a GtkTextTag to them.

Avoid iconv if possible

However, if you have the choice, don't use iconv! It's a crappy API and has several design flaws:

When iconv() returns (size_t)-1 (e.g., when the output buffer is full), we don't know if it has performed lossy conversions. In a normal situation, the number of lossy conversions performed is returned by iconv() as its return value.

To fix this flaw, an iconv2() function could return the number of lossy conversions performed as an output parameter. And also an iconv_open2 () function could take a flags parameter to configure whether lossy conversions are allowed.
The EILSEQ error returned by iconv() can mean two different things: there is either an invalid character in the input buffer (so invalid wrt. the *origin* codeset), or there is a valid character in the input buffer that cannot be represented in the *target* codeset.

To fix this flaw, an iconv2() function could simply return two different error codes.
When the EILSEQ error is returned by iconv(), “*inbuf is left pointing to the beginning of the invalid multibyte sequence”, however we don't know the length of the multibyte sequence! So in practice we assume only one invalid byte, and call iconv() again with inbuf pointing to the next byte, which may fail again, and so on.

An iconv2() function would need a more elaborate API to return this kind of information. For example by returning/filling a struct as an optional output parameter.

Additionally, iconv() has different implementations (so working code on Linux can behave differently on a BSD or Solaris).

Functions

gtk_source_iconv_new ()

GtkSourceIconv *
gtk_source_iconv_new (void);

[skip]

Returns

a new GtkSourceIconv.

[transfer full]

Since: 299.6

gtk_source_iconv_open ()

gboolean
gtk_source_iconv_open (GtkSourceIconv *conv,
                       const gchar *to_codeset,
                       const gchar *from_codeset,
                       GError **error);

Similar to g_iconv_open(). The difference is that it returns a GError instead of errno.

[skip]

Parameters

conv	a GtkSourceIconv.
to_codeset	destination codeset.
from_codeset	source codeset.
error	location to a GError, or `NULL` to ignore errors.

Returns

TRUE on success, FALSE on error.

Since: 299.6

gtk_source_iconv_feed ()

GtkSourceIconvResult
gtk_source_iconv_feed (GtkSourceIconv *conv,
                       gchar **inbuf,
                       gsize *inbytes_left,
                       gchar **outbuf,
                       gsize *outbytes_left,
                       GError **error);

Similar to g_iconv(). This function reads the errno value and converts it either to a GError, or to a GtkSourceIconvResult enumeration value.

error is set only when GTK_SOURCE_ICONV_RESULT_ERROR is returned.

[skip]

Parameters

conv	a GtkSourceIconv.
inbuf	bytes to convert.	[nullable]
inbytes_left	bytes remaining to convert in `inbuf` .	[nullable][inout]
outbuf	converted output bytes.	[not nullable]
outbytes_left	bytes available to fill in `outbuf` .	[not nullable][inout]
error	location to a GError, or `NULL` to ignore errors.

Returns

a GtkSourceIconvResult enumeration value.

Since: 299.6

gtk_source_iconv_feed_discard_output ()

GtkSourceIconvResult
gtk_source_iconv_feed_discard_output (GtkSourceIconv *conv,
                                      gchar **inbuf,
                                      gsize *inbytes_left,
                                      GError **error);

Similar to gtk_source_iconv_feed() but without the output buffer parameters.

[skip]

Parameters

conv	a GtkSourceIconv.
inbuf	bytes to convert.	[nullable]
inbytes_left	bytes remaining to convert in `inbuf` .	[nullable][inout]
error	location to a GError, or `NULL` to ignore errors.

Returns

a GtkSourceIconvResult enumeration value. GTK_SOURCE_ICONV_RESULT_OUTPUT_BUFFER_FULL is never returned by this function.

Since: 299.6

gtk_source_iconv_close ()

gboolean
gtk_source_iconv_close (GtkSourceIconv *conv,
                        GError **error);

Similar to g_iconv_close(). The difference is that it returns a GError instead of errno.

[skip]

Parameters

conv	a GtkSourceIconv.
error	location to a GError, or `NULL` to ignore errors.

Returns

TRUE on success, FALSE on error.

Since: 299.6

gtk_source_iconv_free ()

void
gtk_source_iconv_free (GtkSourceIconv *conv);

Frees conv .

[skip]

Parameters

conv

a GtkSourceIconv, or NULL.

[nullable]

Since: 299.6

Types and Values

GtkSourceIconv

typedef struct _GtkSourceIconv GtkSourceIconv;

enum GtkSourceIconvResult

Used as the result value of gtk_source_iconv_feed().

Members

GTK_SOURCE_ICONV_RESULT_OK	Everything OK.
GTK_SOURCE_ICONV_RESULT_ERROR	An error occurred.
GTK_SOURCE_ICONV_RESULT_ILLEGAL_SEQUENCE	Stopped at an invalid character in the `inbuf` ; or the character could not be represented in the target character set. `*inbuf` is left pointing to the beginning of the invalid or unconvertible sequence.
GTK_SOURCE_ICONV_RESULT_INCOMPLETE_INPUT	The input byte sequence ends with an incomplete multi-byte character. `*inbuf` is left pointing to the beginning of the incomplete multi-byte character.
GTK_SOURCE_ICONV_RESULT_OUTPUT_BUFFER_FULL	The output buffer has no more room for the next converted character.
GTK_SOURCE_ICONV_RESULT_LOSSY_CONVERSION	A number of nonreversible conversions have been performed.

Since: 299.6