Functions¶

	`encoding_convert` (input_bytes, to_codeset, from_codeset, allow_invalid_characters)
	`encoding_try_convert` (input_bytes, to_codeset, from_codeset)
	`finalize` ()
	`init` ()
	`loader_basic_load_async` (file, max_size, max_n_bytes_per_line, io_priority, cancellable, callback, *user_data)
	`loader_basic_load_finish` (file, result)
	`loader_error_quark` ()
	`utf8_find_very_long_line` (str, max_n_bytes_per_line)

Details¶

Gfls.encoding_convert(input_bytes, to_codeset, from_codeset, allow_invalid_characters)¶

Parameters:

input_bytes (GLib.Bytes) – the input GLib.Bytes to convert.
to_codeset (str) – destination codeset.
from_codeset (str) – source codeset.
allow_invalid_characters (bool) – whether invalid characters are allowed.

Raises:

GLib.Error

Returns:

True on success, False otherwise.

output_bytes:: the output GLib.Bytes. It must initially point to a None GLib.Bytes value.
output_bytes_valid_region:: the output Gfls.BytesRegion that represents the valid characters. It must initially point to a None Gfls.BytesRegion value.

Return type:

(bool, output_bytes: GLib.Bytes, output_bytes_valid_region: Gfls.BytesRegion)

This function converts input_bytes from a codeset to another.

from_codeset and to_codeset must be compatible with iconv, see gfls_iconv_open().

Note that from_codeset and to_codeset can be equal. It is useful to identify the valid characters from the invalid ones.

The output is the combination of output_bytes and output_bytes_valid_region. Output bytes that are part of output_bytes_valid_region are the valid characters (successfully converted). The other output bytes are invalid characters (copied as is from input_bytes).

If allow_invalid_characters is False:

As soon as an invalid character is encountered, False is returned by this function and output_bytes and output_bytes_valid_region will return None.
Otherwise, if everything goes well, True is returned alongside the output_bytes and output_bytes_valid_region (the latter contains in this case only one, valid sub-region).

New in version 0.4.

Gfls.encoding_try_convert(input_bytes, to_codeset, from_codeset)¶

Parameters:

input_bytes (GLib.Bytes) – a GLib.Bytes.
to_codeset (str) – destination codeset.
from_codeset (str) – source codeset.

Returns:

True if and only if input_bytes can be converted without errors, without invalid characters and without fallback characters.

Return type:

bool

Tries a conversion on input_bytes, discarding the output.

from_codeset and to_codeset must be compatible with iconv, see gfls_iconv_open().

If input_bytes ends with an incomplete multi-byte character, that part is ignored. So input_bytes can be for example the first chunk of a file when loading it.

New in version 0.4.

Gfls.finalize()¶

Free the resources allocated by Gfls. For example it unrefs the singleton objects.

It is not mandatory to call this function, it’s just to be friendlier to memory debugging tools. This function is meant to be called at the end of main(). It can be called several times.

New in version 0.1.

Gfls.init()¶

Initializes the Gfls library (e.g. for the internationalization).

This function can be called several times, but is meant to be called at the beginning of main(), before any other Gfls function call.

New in version 0.1.

Gfls.loader_basic_load_async(file, max_size, max_n_bytes_per_line, io_priority, cancellable, callback, *user_data)¶

Parameters:

file (Gio.File) – a Gio.File.
max_size (int) – the maximum allowed number of bytes in total.
max_n_bytes_per_line (int) – the maximum allowed number of bytes per line, as per Gfls.utf8_find_very_long_line().
io_priority (int) – the I/O priority of the request. E.g. GLib.PRIORITY_LOW, GLib.PRIORITY_DEFAULT or GLib.PRIORITY_HIGH.
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore.
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when the operation is finished.
user_data (object or None) – user data to pass to callback.

Starts a basic file loading operation.

If the file content is not a valid UTF-8 string, or if the max_size or max_n_bytes_per_line conditions are not satisfied, an error will be returned without the file content.

See the Gio.AsyncResult documentation to know how to use this function.

New in version 0.1.

Gfls.loader_basic_load_finish(file, result)¶

Parameters:

file (Gio.File) – a Gio.File.
result (Gio.AsyncResult) – a Gio.AsyncResult.

Raises:

GLib.Error

Returns:

a GLib.Bytes, or None on error.

Return type:

GLib.Bytes

Finishes an operation started with Gfls.loader_basic_load_async().

If everything went well, a GLib.Bytes with the Gio.File content (unmodified) is returned. It is guaranteed to be a valid UTF-8 string.

Otherwise an error is returned. The %GFLS_LOADER_ERROR domain is used, among others.

The data contained in the resulting GLib.Bytes is always zero-terminated, but this is not included in the GLib.Bytes length. The resulting GLib.Bytes should be freed with GLib.Bytes.unref() when no longer in use.

New in version 0.1.

Gfls.loader_error_quark()¶

Return type:: int

Gfls.utf8_find_very_long_line(str, max_n_bytes_per_line)¶

Parameters:

str (str) – a UTF-8 nul-terminated string.
max_n_bytes_per_line (int) – the maximum number of bytes per line, without counting the newline character(s).

Returns:

a pointer to the beginning of the first very long line found, or None if not found.

Return type:

str

Finds if a line in str exceeds max_n_bytes_per_line.

For performance reasons, str is not checked whether it is a valid UTF-8 string. So you must call for example GLib.utf8_validate() beforehand.

New in version 0.3.