
@c %start of fragment

@deffn Function g-convert  (str@tie{}@code{mchars}) (len@tie{}@code{ssize_t}) (to_codeset@tie{}@code{mchars}) (from_codeset@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{mchars}) (bytes_read@tie{}@code{size_t}) (bytes_written@tie{}@code{size_t})
Converts a string from one character set to another.

@table @var
@item str
the string to convert

@item to-codeset
name of character set into which to convert @var{str}

@item from-codeset
character set of @var{str}.

@item ret
If the conversion was successful, a string. Otherwise an exception will be
thrown.

@end table

Note that some encodings may allow nul bytes to occur inside strings. In that
case, the Guile wrapper for this function is unsafe.

@end deffn

@deffn Function g-convert-with-fallback  (str@tie{}@code{mchars}) (len@tie{}@code{ssize_t}) (to_codeset@tie{}@code{mchars}) (from_codeset@tie{}@code{mchars}) (fallback@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{mchars}) (bytes_read@tie{}@code{size_t}) (bytes_written@tie{}@code{size_t})
Converts a string from one character set to another, possibly including fallback
sequences for characters not representable in the output. Note that it is not
guaranteed that the specification for the fallback sequences in @var{fallback}
will be honored. Some systems may do a approximate conversion from
@var{from-codeset} to @var{to-codeset} in their @code{iconv} functions, in which
case GLib will simply return that approximate conversion.

@table @var
@item str
the string to convert

@item to-codeset
name of character set into which to convert @var{str}

@item from-codeset
character set of @var{str}.

@item fallback
UTF-8 string to use in place of character not present in the target encoding.
(The string must be representable in the target encoding). If @samp{@code{#f}},
characters not in the target encoding will be represented as Unicode escapes
\uxxxx or \Uxxxxyyyy.

@item ret
If the conversion was successful, a string. Otherwise an exception will be
thrown.

@end table

@end deffn

@deffn Function g-locale-to-utf8  (opsysstring@tie{}@code{mchars}) (len@tie{}@code{ssize_t}) @result{}@tie{} (ret@tie{}@code{mchars}) (bytes_read@tie{}@code{size_t}) (bytes_written@tie{}@code{size_t})
Converts a string which is in the encoding used for strings by the C runtime
(usually the same as that used by the operating system) in the current locale
into a UTF-8 string.

@table @var
@item opsysstring
a string in the encoding of the current locale. On Windows this means the system
codepage.

@item ret
The converted string. If the conversion fails, an exception will be raised.

@end table

@end deffn

@deffn Function g-filename-to-utf8  (opsysstring@tie{}@code{mchars}) (len@tie{}@code{ssize_t}) @result{}@tie{} (ret@tie{}@code{mchars}) (bytes_read@tie{}@code{size_t}) (bytes_written@tie{}@code{size_t})
Converts a string which is in the encoding used by GLib for filenames into a
UTF-8 string. Note that on Windows GLib uses UTF-8 for filenames.

@table @var
@item opsysstring
a string in the encoding for filenames

@item ret
The converted string. If the conversion fails, an exception will be raised.

@end table

@end deffn

@deffn Function g-filename-from-utf8  (utf8string@tie{}@code{mchars}) (len@tie{}@code{ssize_t}) @result{}@tie{} (ret@tie{}@code{mchars}) (bytes_read@tie{}@code{size_t}) (bytes_written@tie{}@code{size_t})
Converts a string from UTF-8 to the encoding GLib uses for filenames. Note that
on Windows GLib uses UTF-8 for filenames.

@table @var
@item utf8string
a UTF-8 encoded string.

@item len
the length of the string, or -1 if the string is nul-terminated.

@item bytes-read
location to store the number of bytes in the input string that were successfully
converted, or @samp{@code{#f}}. Even if the conversion was successful, this may
be less than @var{len} if there were partial characters at the end of the input.
If the error @code{<g-convert-error-illegal-sequence>} occurs, the value stored
will the byte offset after the last valid input sequence.

@item bytes-written
the number of bytes stored in the output buffer (not including the terminating
nul).

@item error
location to store the error occuring, or @samp{@code{#f}} to ignore errors. Any
of the errors in @code{<g-convert-error>} may occur.

@item ret
The converted string, or @samp{@code{#f}} on an error.

@end table

@end deffn

@deffn Function g-filename-from-uri  (uri@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{mchars}) (hostname@tie{}@code{mchars})
Converts an escaped ASCII-encoded URI to a local filename in the encoding used
for filenames.

@table @var
@item uri
a uri describing a filename (escaped, encoded in ASCII).

@item hostname
Location to store hostname for the URI, or @samp{@code{#f}}. If there is no
hostname in the URI, @samp{@code{#f}} will be stored in this location.

@item error
location to store the error occuring, or @samp{@code{#f}} to ignore errors. Any
of the errors in @code{<g-convert-error>} may occur.

@item ret
a newly-allocated string holding the resulting filename, or @samp{@code{#f}} on
an error.

@end table

@end deffn

@deffn Function g-filename-to-uri  (filename@tie{}@code{mchars}) (hostname@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{mchars})
Converts an absolute filename to an escaped ASCII-encoded URI, with the path
component following Section 3.3. of RFC 2396.

@table @var
@item filename
an absolute filename specified in the GLib file name encoding, which is the
on-disk file name bytes on Unix, and UTF-8 on Windows

@item hostname
A UTF-8 encoded hostname, or @samp{@code{#f}} for none.

@item error
location to store the error occuring, or @samp{@code{#f}} to ignore errors. Any
of the errors in @code{<g-convert-error>} may occur.

@item ret
a newly-allocated string holding the resulting URI, or @samp{@code{#f}} on an
error.

@end table

@end deffn

@deffn Function g-filename-display-name  (filename@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{mchars})
Converts a filename into a valid UTF-8 string. The conversion is not necessarily
reversible, so you should keep the original around and use the return value of
this function only for display purposes. Unlike @code{g-filename-to-utf8}, the
result is guaranteed to be non-@samp{@code{#f}} even if the filename actually
isn't in the GLib file name encoding.

If GLib can not make sense of the encoding of @var{filename}, as a last resort
it replaces unknown characters with U+FFFD, the Unicode replacement character.
You can search the result for the UTF-8 encoding of this character (which is
"\357\277\275" in octal notation) to find out if @var{filename} was in an
invalid encoding.

If you know the whole pathname of the file you should use
@code{g-filename-display-basename}, since that allows location-based translation
of filenames.

@table @var
@item filename
a pathname hopefully in the GLib file name encoding

@item ret
a newly allocated string containing a rendition of the filename in valid UTF-8

@end table

Since 2.6

@end deffn

@deffn Function g-filename-display-basename  (filename@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{mchars})
Returns the display basename for the particular filename, guaranteed to be valid
UTF-8. The display name might not be identical to the filename, for instance
there might be problems converting it to UTF-8, and some files can be translated
in the display.

If GLib can not make sense of the encoding of @var{filename}, as a last resort
it replaces unknown characters with U+FFFD, the Unicode replacement character.
You can search the result for the UTF-8 encoding of this character (which is
"\357\277\275" in octal notation) to find out if @var{filename} was in an
invalid encoding.

You must pass the whole absolute pathname to this functions so that translation
of well known locations can be done.

This function is preferred over @code{g-filename-display-name} if you know the
whole path, as it allows translation.

@table @var
@item filename
an absolute pathname in the GLib file name encoding

@item ret
a newly allocated string containing a rendition of the basename of the filename
in valid UTF-8

@end table

Since 2.6

@end deffn

@deffn Function g-locale-from-utf8  (utf8string@tie{}@code{mchars}) (len@tie{}@code{ssize_t}) @result{}@tie{} (ret@tie{}@code{mchars}) (bytes_read@tie{}@code{size_t}) (bytes_written@tie{}@code{size_t})
Converts a string from UTF-8 to the encoding used for strings by the C runtime
(usually the same as that used by the operating system) in the current locale.

@table @var
@item utf8string
a UTF-8 encoded string

@item ret
The converted string. If the conversion fails, an exception will be raised.

@end table

@end deffn


@c %end of fragment
