pango/auto/
language.rs

1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4
5use crate::{ffi, Script};
6use glib::translate::*;
7
8glib::wrapper! {
9    /// The [`Language`][crate::Language] structure is used to
10    /// represent a language.
11    ///
12    /// [`Language`][crate::Language] pointers can be efficiently
13    /// copied and compared with each other.
14    #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
15    pub struct Language(Boxed<ffi::PangoLanguage>);
16
17    match fn {
18        copy => |ptr| glib::gobject_ffi::g_boxed_copy(ffi::pango_language_get_type(), ptr as *mut _) as *mut ffi::PangoLanguage,
19        free => |ptr| glib::gobject_ffi::g_boxed_free(ffi::pango_language_get_type(), ptr as *mut _),
20        type_ => || ffi::pango_language_get_type(),
21    }
22}
23
24impl Language {
25    /// Get a string that is representative of the characters needed to
26    /// render a particular language.
27    ///
28    /// The sample text may be a pangram, but is not necessarily. It is chosen
29    /// to be demonstrative of normal text in the language, as well as exposing
30    /// font feature requirements unique to the language. It is suitable for use
31    /// as sample text in a font selection dialog.
32    ///
33    /// If @self is [`None`], the default language as found by
34    /// [`default()`][Self::default()] is used.
35    ///
36    /// If Pango does not have a sample string for @self, the classic
37    /// "The quick brown fox..." is returned.  This can be detected by
38    /// comparing the returned pointer value to that returned for (non-existent)
39    /// language code "xx".  That is, compare to:
40    ///
41    /// ```text
42    /// pango_language_get_sample_string (pango_language_from_string ("xx"))
43    /// ```
44    ///
45    /// # Returns
46    ///
47    /// the sample string
48    #[doc(alias = "pango_language_get_sample_string")]
49    #[doc(alias = "get_sample_string")]
50    pub fn sample_string(&self) -> glib::GString {
51        unsafe {
52            from_glib_none(ffi::pango_language_get_sample_string(mut_override(
53                self.to_glib_none().0,
54            )))
55        }
56    }
57
58    /// Determines if @script is one of the scripts used to
59    /// write @self.
60    ///
61    /// The returned value is conservative; if nothing is known about
62    /// the language tag @self, [`true`] will be returned, since, as
63    /// far as Pango knows, @script might be used to write @self.
64    ///
65    /// This routine is used in Pango's itemization process when
66    /// determining if a supplied language tag is relevant to
67    /// a particular section of text. It probably is not useful
68    /// for applications in most circumstances.
69    ///
70    /// This function uses [`scripts()`][Self::scripts()] internally.
71    /// ## `script`
72    /// a [`Script`][crate::Script]
73    ///
74    /// # Returns
75    ///
76    /// [`true`] if @script is one of the scripts used
77    ///   to write @self or if nothing is known about @self
78    ///   (including the case that @self is [`None`]), [`false`] otherwise.
79    #[doc(alias = "pango_language_includes_script")]
80    pub fn includes_script(&self, script: Script) -> bool {
81        unsafe {
82            from_glib(ffi::pango_language_includes_script(
83                mut_override(self.to_glib_none().0),
84                script.into_glib(),
85            ))
86        }
87    }
88
89    /// Checks if a language tag matches one of the elements in a list of
90    /// language ranges.
91    ///
92    /// A language tag is considered to match a range in the list if the
93    /// range is '*', the range is exactly the tag, or the range is a prefix
94    /// of the tag, and the character after it in the tag is '-'.
95    /// ## `range_list`
96    /// a list of language ranges, separated by ';', ':',
97    ///   ',', or space characters.
98    ///   Each element must either be '*', or a RFC 3066 language range
99    ///   canonicalized as by [`from_string()`][Self::from_string()]
100    ///
101    /// # Returns
102    ///
103    /// [`true`] if a match was found
104    #[doc(alias = "pango_language_matches")]
105    pub fn matches(&self, range_list: &str) -> bool {
106        unsafe {
107            from_glib(ffi::pango_language_matches(
108                mut_override(self.to_glib_none().0),
109                range_list.to_glib_none().0,
110            ))
111        }
112    }
113
114    /// Gets the RFC-3066 format string representing the given language tag.
115    ///
116    /// Returns (transfer none): a string representing the language tag
117    #[doc(alias = "pango_language_to_string")]
118    #[doc(alias = "to_string")]
119    pub fn to_str(&self) -> glib::GString {
120        unsafe {
121            from_glib_none(ffi::pango_language_to_string(mut_override(
122                self.to_glib_none().0,
123            )))
124        }
125    }
126
127    /// Convert a language tag to a [`Language`][crate::Language].
128    ///
129    /// The language tag must be in a RFC-3066 format. [`Language`][crate::Language] pointers
130    /// can be efficiently copied (copy the pointer) and compared with other
131    /// language tags (compare the pointer.)
132    ///
133    /// This function first canonicalizes the string by converting it to
134    /// lowercase, mapping '_' to '-', and stripping all characters other
135    /// than letters and '-'.
136    ///
137    /// Use [`default()`][Self::default()] if you want to get the
138    /// [`Language`][crate::Language] for the current locale of the process.
139    /// ## `language`
140    /// a string representing a language tag
141    ///
142    /// # Returns
143    ///
144    /// a [`Language`][crate::Language]
145    #[doc(alias = "pango_language_from_string")]
146    pub fn from_string(language: &str) -> Language {
147        unsafe { from_glib_none(ffi::pango_language_from_string(language.to_glib_none().0)) }
148    }
149
150    /// Returns the [`Language`][crate::Language] for the current locale of the process.
151    ///
152    /// On Unix systems, this is the return value is derived from
153    /// `setlocale (LC_CTYPE, NULL)`, and the user can
154    /// affect this through the environment variables LC_ALL, LC_CTYPE or
155    /// LANG (checked in that order). The locale string typically is in
156    /// the form lang_COUNTRY, where lang is an ISO-639 language code, and
157    /// COUNTRY is an ISO-3166 country code. For instance, sv_FI for
158    /// Swedish as written in Finland or pt_BR for Portuguese as written in
159    /// Brazil.
160    ///
161    /// On Windows, the C library does not use any such environment
162    /// variables, and setting them won't affect the behavior of functions
163    /// like ctime(). The user sets the locale through the Regional Options
164    /// in the Control Panel. The C library (in the setlocale() function)
165    /// does not use country and language codes, but country and language
166    /// names spelled out in English.
167    /// However, this function does check the above environment
168    /// variables, and does return a Unix-style locale string based on
169    /// either said environment variables or the thread's current locale.
170    ///
171    /// Your application should call `setlocale(LC_ALL, "")` for the user
172    /// settings to take effect. GTK does this in its initialization
173    /// functions automatically (by calling gtk_set_locale()).
174    /// See the setlocale() manpage for more details.
175    ///
176    /// Note that the default language can change over the life of an application.
177    ///
178    /// Also note that this function will not do the right thing if you
179    /// use per-thread locales with uselocale(). In that case, you should
180    /// just call pango_language_from_string() yourself.
181    ///
182    /// # Returns
183    ///
184    /// the default language as a [`Language`][crate::Language]
185    #[doc(alias = "pango_language_get_default")]
186    #[doc(alias = "get_default")]
187    #[allow(clippy::should_implement_trait)]
188    pub fn default() -> Language {
189        unsafe { from_glib_none(ffi::pango_language_get_default()) }
190    }
191
192    /// Returns the list of languages that the user prefers.
193    ///
194    /// The list is specified by the `PANGO_LANGUAGE` or `LANGUAGE`
195    /// environment variables, in order of preference. Note that this
196    /// list does not necessarily include the language returned by
197    /// [`default()`][Self::default()].
198    ///
199    /// When choosing language-specific resources, such as the sample
200    /// text returned by [`sample_string()`][Self::sample_string()],
201    /// you should first try the default language, followed by the
202    /// languages returned by this function.
203    ///
204    /// # Returns
205    ///
206    /// a [`None`]-terminated array
207    ///   of [`Language`][crate::Language]*
208    #[cfg(feature = "v1_48")]
209    #[cfg_attr(docsrs, doc(cfg(feature = "v1_48")))]
210    #[doc(alias = "pango_language_get_preferred")]
211    #[doc(alias = "get_preferred")]
212    pub fn preferred() -> Vec<Language> {
213        unsafe { FromGlibPtrContainer::from_glib_none(ffi::pango_language_get_preferred()) }
214    }
215}
216
217impl std::fmt::Display for Language {
218    #[inline]
219    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
220        f.write_str(&self.to_str())
221    }
222}