source: appstream-generator/build/girepo/glib/CharacterSet.d @ 4841

Last change on this file since 4841 was 4841, checked in by Juanma, 2 years ago

Initial release

File size: 20.6 KB
Line 
1/*
2 * Licensed under the GNU Lesser General Public License Version 3
3 *
4 * This library is free software: you can redistribute it and/or modify
5 * it under the terms of the GNU Lesser General Public License as published by
6 * the Free Software Foundation, either version 3 of the license, or
7 * (at your option) any later version.
8 *
9 * This software is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 * GNU Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public License
15 * along with this library.  If not, see <http://www.gnu.org/licenses/>.
16 */
17
18// generated automatically - do not change
19
20
21module glib.CharacterSet;
22
23private import gi.glib;
24public  import gi.glibtypes;
25private import glib.ErrorG;
26private import glib.GException;
27private import glib.Str;
28
29
30/** */
31public struct CharacterSet
32{
33
34        /**
35         * Converts a string from one character set to another.
36         *
37         * Note that you should use g_iconv() for streaming conversions.
38         * Despite the fact that @byes_read can return information about partial
39         * characters, the g_convert_... functions are not generally suitable
40         * for streaming. If the underlying converter maintains internal state,
41         * then this won't be preserved across successive calls to g_convert(),
42         * g_convert_with_iconv() or g_convert_with_fallback(). (An example of
43         * this is the GNU C converter for CP1255 which does not emit a base
44         * character until it knows that the next character is not a mark that
45         * could combine with the base character.)
46         *
47         * Using extensions such as "//TRANSLIT" may not work (or may not work
48         * well) on many platforms.  Consider using g_str_to_ascii() instead.
49         *
50         * Params:
51         *     str = the string to convert
52         *     len = the length of the string in bytes, or -1 if the string is
53         *         nul-terminated (Note that some encodings may allow nul
54         *         bytes to occur inside strings. In that case, using -1
55         *         for the @len parameter is unsafe)
56         *     toCodeset = name of character set into which to convert @str
57         *     fromCodeset = character set of @str.
58         *     bytesRead = location to store the number of bytes in the
59         *         input string that were successfully converted, or %NULL.
60         *         Even if the conversion was successful, this may be
61         *         less than @len if there were partial characters
62         *         at the end of the input. If the error
63         *         #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
64         *         stored will the byte offset after the last valid
65         *         input sequence.
66         *     bytesWritten = the number of bytes stored in the output buffer (not
67         *         including the terminating nul).
68         *
69         * Returns: If the conversion was successful, a newly allocated
70         *     nul-terminated string, which must be freed with
71         *     g_free(). Otherwise %NULL and @error will be set.
72         *
73         * Throws: GException on failure.
74         */
75        public static string convert(string str, ptrdiff_t len, string toCodeset, string fromCodeset, out size_t bytesRead, out size_t bytesWritten)
76        {
77                GError* err = null;
78               
79                auto retStr = g_convert(Str.toStringz(str), len, Str.toStringz(toCodeset), Str.toStringz(fromCodeset), &bytesRead, &bytesWritten, &err);
80               
81                if (err !is null)
82                {
83                        throw new GException( new ErrorG(err) );
84                }
85               
86                scope(exit) Str.freeString(retStr);
87                return Str.toString(retStr);
88        }
89
90        /** */
91        public static GQuark convertErrorQuark()
92        {
93                return g_convert_error_quark();
94        }
95
96        /**
97         * Converts a string from one character set to another, possibly
98         * including fallback sequences for characters not representable
99         * in the output. Note that it is not guaranteed that the specification
100         * for the fallback sequences in @fallback will be honored. Some
101         * systems may do an approximate conversion from @from_codeset
102         * to @to_codeset in their iconv() functions,
103         * in which case GLib will simply return that approximate conversion.
104         *
105         * Note that you should use g_iconv() for streaming conversions.
106         * Despite the fact that @byes_read can return information about partial
107         * characters, the g_convert_... functions are not generally suitable
108         * for streaming. If the underlying converter maintains internal state,
109         * then this won't be preserved across successive calls to g_convert(),
110         * g_convert_with_iconv() or g_convert_with_fallback(). (An example of
111         * this is the GNU C converter for CP1255 which does not emit a base
112         * character until it knows that the next character is not a mark that
113         * could combine with the base character.)
114         *
115         * Params:
116         *     str = the string to convert
117         *     len = the length of the string in bytes, or -1 if the string is
118         *         nul-terminated (Note that some encodings may allow nul
119         *         bytes to occur inside strings. In that case, using -1
120         *         for the @len parameter is unsafe)
121         *     toCodeset = name of character set into which to convert @str
122         *     fromCodeset = character set of @str.
123         *     fallback = UTF-8 string to use in place of character not
124         *         present in the target encoding. (The string must be
125         *         representable in the target encoding).
126         *         If %NULL, characters not in the target encoding will
127         *         be represented as Unicode escapes \uxxxx or \Uxxxxyyyy.
128         *     bytesRead = location to store the number of bytes in the
129         *         input string that were successfully converted, or %NULL.
130         *         Even if the conversion was successful, this may be
131         *         less than @len if there were partial characters
132         *         at the end of the input.
133         *     bytesWritten = the number of bytes stored in the output buffer (not
134         *         including the terminating nul).
135         *
136         * Returns: If the conversion was successful, a newly allocated
137         *     nul-terminated string, which must be freed with
138         *     g_free(). Otherwise %NULL and @error will be set.
139         *
140         * Throws: GException on failure.
141         */
142        public static string convertWithFallback(string str, ptrdiff_t len, string toCodeset, string fromCodeset, string fallback, size_t* bytesRead, size_t* bytesWritten)
143        {
144                GError* err = null;
145               
146                auto retStr = g_convert_with_fallback(Str.toStringz(str), len, Str.toStringz(toCodeset), Str.toStringz(fromCodeset), Str.toStringz(fallback), bytesRead, bytesWritten, &err);
147               
148                if (err !is null)
149                {
150                        throw new GException( new ErrorG(err) );
151                }
152               
153                scope(exit) Str.freeString(retStr);
154                return Str.toString(retStr);
155        }
156
157        /**
158         * Converts a string from one character set to another.
159         *
160         * Note that you should use g_iconv() for streaming conversions.
161         * Despite the fact that @byes_read can return information about partial
162         * characters, the g_convert_... functions are not generally suitable
163         * for streaming. If the underlying converter maintains internal state,
164         * then this won't be preserved across successive calls to g_convert(),
165         * g_convert_with_iconv() or g_convert_with_fallback(). (An example of
166         * this is the GNU C converter for CP1255 which does not emit a base
167         * character until it knows that the next character is not a mark that
168         * could combine with the base character.)
169         *
170         * Params:
171         *     str = the string to convert
172         *     len = the length of the string in bytes, or -1 if the string is
173         *         nul-terminated (Note that some encodings may allow nul
174         *         bytes to occur inside strings. In that case, using -1
175         *         for the @len parameter is unsafe)
176         *     converter = conversion descriptor from g_iconv_open()
177         *     bytesRead = location to store the number of bytes in the
178         *         input string that were successfully converted, or %NULL.
179         *         Even if the conversion was successful, this may be
180         *         less than @len if there were partial characters
181         *         at the end of the input. If the error
182         *         #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
183         *         stored will the byte offset after the last valid
184         *         input sequence.
185         *     bytesWritten = the number of bytes stored in the output buffer (not
186         *         including the terminating nul).
187         *
188         * Returns: If the conversion was successful, a newly allocated
189         *     nul-terminated string, which must be freed with
190         *     g_free(). Otherwise %NULL and @error will be set.
191         *
192         * Throws: GException on failure.
193         */
194        public static string convertWithIconv(string str, ptrdiff_t len, GIConv converter, size_t* bytesRead, size_t* bytesWritten)
195        {
196                GError* err = null;
197               
198                auto retStr = g_convert_with_iconv(Str.toStringz(str), len, converter, bytesRead, bytesWritten, &err);
199               
200                if (err !is null)
201                {
202                        throw new GException( new ErrorG(err) );
203                }
204               
205                scope(exit) Str.freeString(retStr);
206                return Str.toString(retStr);
207        }
208
209        /**
210         * Returns the display basename for the particular filename, guaranteed
211         * to be valid UTF-8. The display name might not be identical to the filename,
212         * for instance there might be problems converting it to UTF-8, and some files
213         * can be translated in the display.
214         *
215         * If GLib cannot make sense of the encoding of @filename, as a last resort it
216         * replaces unknown characters with U+FFFD, the Unicode replacement character.
217         * You can search the result for the UTF-8 encoding of this character (which is
218         * "\357\277\275" in octal notation) to find out if @filename was in an invalid
219         * encoding.
220         *
221         * You must pass the whole absolute pathname to this functions so that
222         * translation of well known locations can be done.
223         *
224         * This function is preferred over g_filename_display_name() if you know the
225         * whole path, as it allows translation.
226         *
227         * Params:
228         *     filename = an absolute pathname in the GLib file name encoding
229         *
230         * Returns: a newly allocated string containing
231         *     a rendition of the basename of the filename in valid UTF-8
232         *
233         * Since: 2.6
234         */
235        public static string filenameDisplayBasename(string filename)
236        {
237                auto retStr = g_filename_display_basename(Str.toStringz(filename));
238               
239                scope(exit) Str.freeString(retStr);
240                return Str.toString(retStr);
241        }
242
243        /**
244         * Converts a filename into a valid UTF-8 string. The conversion is
245         * not necessarily reversible, so you should keep the original around
246         * and use the return value of this function only for display purposes.
247         * Unlike g_filename_to_utf8(), the result is guaranteed to be non-%NULL
248         * even if the filename actually isn't in the GLib file name encoding.
249         *
250         * If GLib cannot make sense of the encoding of @filename, as a last resort it
251         * replaces unknown characters with U+FFFD, the Unicode replacement character.
252         * You can search the result for the UTF-8 encoding of this character (which is
253         * "\357\277\275" in octal notation) to find out if @filename was in an invalid
254         * encoding.
255         *
256         * If you know the whole pathname of the file you should use
257         * g_filename_display_basename(), since that allows location-based
258         * translation of filenames.
259         *
260         * Params:
261         *     filename = a pathname hopefully in the GLib file name encoding
262         *
263         * Returns: a newly allocated string containing
264         *     a rendition of the filename in valid UTF-8
265         *
266         * Since: 2.6
267         */
268        public static string filenameDisplayName(string filename)
269        {
270                auto retStr = g_filename_display_name(Str.toStringz(filename));
271               
272                scope(exit) Str.freeString(retStr);
273                return Str.toString(retStr);
274        }
275
276        /**
277         * Converts a string from UTF-8 to the encoding GLib uses for
278         * filenames. Note that on Windows GLib uses UTF-8 for filenames;
279         * on other platforms, this function indirectly depends on the
280         * [current locale][setlocale].
281         *
282         * Params:
283         *     utf8string = a UTF-8 encoded string.
284         *     len = the length of the string, or -1 if the string is
285         *         nul-terminated.
286         *     bytesRead = location to store the number of bytes in
287         *         the input string that were successfully converted, or %NULL.
288         *         Even if the conversion was successful, this may be
289         *         less than @len if there were partial characters
290         *         at the end of the input. If the error
291         *         #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
292         *         stored will the byte offset after the last valid
293         *         input sequence.
294         *
295         * Returns: The converted string, or %NULL on an error.
296         *
297         * Throws: GException on failure.
298         */
299        public static string filenameFromUtf8(string utf8string, ptrdiff_t len, out size_t bytesRead)
300        {
301                size_t bytesWritten;
302                GError* err = null;
303               
304                auto retStr = g_filename_from_utf8(Str.toStringz(utf8string), len, &bytesRead, &bytesWritten, &err);
305               
306                if (err !is null)
307                {
308                        throw new GException( new ErrorG(err) );
309                }
310               
311                scope(exit) Str.freeString(retStr);
312                return Str.toString(retStr, bytesWritten);
313        }
314
315        /**
316         * Converts a string which is in the encoding used by GLib for
317         * filenames into a UTF-8 string. Note that on Windows GLib uses UTF-8
318         * for filenames; on other platforms, this function indirectly depends on
319         * the [current locale][setlocale].
320         *
321         * Params:
322         *     opsysstring = a string in the encoding for filenames
323         *     len = the length of the string, or -1 if the string is
324         *         nul-terminated (Note that some encodings may allow nul
325         *         bytes to occur inside strings. In that case, using -1
326         *         for the @len parameter is unsafe)
327         *     bytesRead = location to store the number of bytes in the
328         *         input string that were successfully converted, or %NULL.
329         *         Even if the conversion was successful, this may be
330         *         less than @len if there were partial characters
331         *         at the end of the input. If the error
332         *         #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
333         *         stored will the byte offset after the last valid
334         *         input sequence.
335         *     bytesWritten = the number of bytes stored in the output buffer (not
336         *         including the terminating nul).
337         *
338         * Returns: The converted string, or %NULL on an error.
339         *
340         * Throws: GException on failure.
341         */
342        public static string filenameToUtf8(string opsysstring, ptrdiff_t len, size_t* bytesRead, size_t* bytesWritten)
343        {
344                GError* err = null;
345               
346                auto retStr = g_filename_to_utf8(Str.toStringz(opsysstring), len, bytesRead, bytesWritten, &err);
347               
348                if (err !is null)
349                {
350                        throw new GException( new ErrorG(err) );
351                }
352               
353                scope(exit) Str.freeString(retStr);
354                return Str.toString(retStr);
355        }
356
357        /**
358         * Obtains the character set for the [current locale][setlocale]; you
359         * might use this character set as an argument to g_convert(), to convert
360         * from the current locale's encoding to some other encoding. (Frequently
361         * g_locale_to_utf8() and g_locale_from_utf8() are nice shortcuts, though.)
362         *
363         * On Windows the character set returned by this function is the
364         * so-called system default ANSI code-page. That is the character set
365         * used by the "narrow" versions of C library and Win32 functions that
366         * handle file names. It might be different from the character set
367         * used by the C library's current locale.
368         *
369         * The return value is %TRUE if the locale's encoding is UTF-8, in that
370         * case you can perhaps avoid calling g_convert().
371         *
372         * The string returned in @charset is not allocated, and should not be
373         * freed.
374         *
375         * Params:
376         *     charset = return location for character set
377         *         name, or %NULL.
378         *
379         * Returns: %TRUE if the returned charset is UTF-8
380         */
381        public static bool getCharset(out string charset)
382        {
383                char* outcharset = null;
384               
385                auto p = g_get_charset(&outcharset) != 0;
386               
387                charset = Str.toString(outcharset);
388               
389                return p;
390        }
391
392        /**
393         * Gets the character set for the current locale.
394         *
395         * Returns: a newly allocated string containing the name
396         *     of the character set. This string must be freed with g_free().
397         */
398        public static string getCodeset()
399        {
400                auto retStr = g_get_codeset();
401               
402                scope(exit) Str.freeString(retStr);
403                return Str.toString(retStr);
404        }
405
406        /**
407         * Determines the preferred character sets used for filenames.
408         * The first character set from the @charsets is the filename encoding, the
409         * subsequent character sets are used when trying to generate a displayable
410         * representation of a filename, see g_filename_display_name().
411         *
412         * On Unix, the character sets are determined by consulting the
413         * environment variables `G_FILENAME_ENCODING` and `G_BROKEN_FILENAMES`.
414         * On Windows, the character set used in the GLib API is always UTF-8
415         * and said environment variables have no effect.
416         *
417         * `G_FILENAME_ENCODING` may be set to a comma-separated list of
418         * character set names. The special token "&commat;locale" is taken
419         * to  mean the character set for the [current locale][setlocale].
420         * If `G_FILENAME_ENCODING` is not set, but `G_BROKEN_FILENAMES` is,
421         * the character set of the current locale is taken as the filename
422         * encoding. If neither environment variable  is set, UTF-8 is taken
423         * as the filename encoding, but the character set of the current locale
424         * is also put in the list of encodings.
425         *
426         * The returned @charsets belong to GLib and must not be freed.
427         *
428         * Note that on Unix, regardless of the locale character set or
429         * `G_FILENAME_ENCODING` value, the actual file names present
430         * on a system might be in any random encoding or just gibberish.
431         *
432         * Params:
433         *     charsets = return location for the %NULL-terminated list of encoding names
434         *
435         * Returns: %TRUE if the filename encoding is UTF-8.
436         *
437         * Since: 2.6
438         */
439        public static bool getFilenameCharsets(string[][] charsets)
440        {
441                return g_get_filename_charsets(Str.toStringzArray(charsets)) != 0;
442        }
443
444        /**
445         * Converts a string from UTF-8 to the encoding used for strings by
446         * the C runtime (usually the same as that used by the operating
447         * system) in the [current locale][setlocale]. On Windows this means
448         * the system codepage.
449         *
450         * Params:
451         *     utf8string = a UTF-8 encoded string
452         *     len = the length of the string, or -1 if the string is
453         *         nul-terminated (Note that some encodings may allow nul
454         *         bytes to occur inside strings. In that case, using -1
455         *         for the @len parameter is unsafe)
456         *     bytesRead = location to store the number of bytes in the
457         *         input string that were successfully converted, or %NULL.
458         *         Even if the conversion was successful, this may be
459         *         less than @len if there were partial characters
460         *         at the end of the input. If the error
461         *         #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
462         *         stored will the byte offset after the last valid
463         *         input sequence.
464         *     bytesWritten = the number of bytes stored in the output buffer (not
465         *         including the terminating nul).
466         *
467         * Returns: A newly-allocated buffer containing the converted string,
468         *     or %NULL on an error, and error will be set.
469         *
470         * Throws: GException on failure.
471         */
472        public static string localeFromUtf8(string utf8string, ptrdiff_t len, size_t* bytesRead, size_t* bytesWritten)
473        {
474                GError* err = null;
475               
476                auto retStr = g_locale_from_utf8(Str.toStringz(utf8string), len, bytesRead, bytesWritten, &err);
477               
478                if (err !is null)
479                {
480                        throw new GException( new ErrorG(err) );
481                }
482               
483                scope(exit) Str.freeString(retStr);
484                return Str.toString(retStr);
485        }
486
487        /**
488         * Converts a string which is in the encoding used for strings by
489         * the C runtime (usually the same as that used by the operating
490         * system) in the [current locale][setlocale] into a UTF-8 string.
491         *
492         * Params:
493         *     opsysstring = a string in the encoding of the current locale. On Windows
494         *         this means the system codepage.
495         *     len = the length of the string, or -1 if the string is
496         *         nul-terminated (Note that some encodings may allow nul
497         *         bytes to occur inside strings. In that case, using -1
498         *         for the @len parameter is unsafe)
499         *     bytesRead = location to store the number of bytes in the
500         *         input string that were successfully converted, or %NULL.
501         *         Even if the conversion was successful, this may be
502         *         less than @len if there were partial characters
503         *         at the end of the input. If the error
504         *         #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
505         *         stored will the byte offset after the last valid
506         *         input sequence.
507         *     bytesWritten = the number of bytes stored in the output buffer (not
508         *         including the terminating nul).
509         *
510         * Returns: A newly-allocated buffer containing the converted string,
511         *     or %NULL on an error, and error will be set.
512         *
513         * Throws: GException on failure.
514         */
515        public static string localeToUtf8(string opsysstring, ptrdiff_t len, size_t* bytesRead, size_t* bytesWritten)
516        {
517                GError* err = null;
518               
519                auto retStr = g_locale_to_utf8(Str.toStringz(opsysstring), len, bytesRead, bytesWritten, &err);
520               
521                if (err !is null)
522                {
523                        throw new GException( new ErrorG(err) );
524                }
525               
526                scope(exit) Str.freeString(retStr);
527                return Str.toString(retStr);
528        }
529}
Note: See TracBrowser for help on using the repository browser.