glib/auto/

key_file.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT

use crate::{ffi, translate::*, Bytes, Error, KeyFileFlags};

crate::wrapper! {
    /// `GKeyFile` parses .ini-like config files.
    ///
    /// `GKeyFile` lets you parse, edit or create files containing groups of
    /// key-value pairs, which we call "key files" for lack of a better name.
    /// Several freedesktop.org specifications use key files now, e.g the
    /// [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec)
    /// and the [Icon Theme Specification](http://freedesktop.org/Standards/icon-theme-spec).
    ///
    /// The syntax of key files is described in detail in the
    /// [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec),
    /// here is a quick summary: Key files consists of groups of key-value pairs, interspersed
    /// with comments.
    ///
    /// **⚠️ The following code is in txt ⚠️**
    ///
    /// ```txt
    /// # this is just an example
    /// # there can be comments before the first group
    ///
    /// [First Group]
    ///
    /// Name=Key File Example\tthis value shows\nescaping
    ///
    /// # localized strings are stored in multiple key-value pairs
    /// Welcome=Hello
    /// Welcome[de]=Hallo
    /// Welcome[fr_FR]=Bonjour
    /// Welcome[it]=Ciao
    ///
    /// [Another Group]
    ///
    /// Numbers=2;20;-200;0
    ///
    /// Booleans=true;false;true;true
    /// ```
    ///
    /// Lines beginning with a '#' and blank lines are considered comments.
    ///
    /// Groups are started by a header line containing the group name enclosed
    /// in '[' and ']', and ended implicitly by the start of the next group or
    /// the end of the file. Each key-value pair must be contained in a group.
    ///
    /// Key-value pairs generally have the form `key=value`, with the exception
    /// of localized strings, which have the form `key[locale]=value`, with a
    /// locale identifier of the form `lang_COUNTRY@MODIFIER` where `COUNTRY`
    /// and `MODIFIER` are optional. Space before and after the '=' character
    /// are ignored. Newline, tab, carriage return and backslash characters in
    /// value are escaped as `\n`, `\t`, `\r`, and `\\\\`, respectively. To preserve
    /// leading spaces in values, these can also be escaped as `\s`.
    ///
    /// Key files can store strings (possibly with localized variants), integers,
    /// booleans and lists of these. Lists are separated by a separator character,
    /// typically ';' or ','. To use the list separator character in a value in
    /// a list, it has to be escaped by prefixing it with a backslash.
    ///
    /// This syntax is obviously inspired by the .ini files commonly met
    /// on Windows, but there are some important differences:
    ///
    /// - .ini files use the ';' character to begin comments,
    ///   key files use the '#' character.
    ///
    /// - Key files do not allow for ungrouped keys meaning only
    ///   comments can precede the first group.
    ///
    /// - Key files are always encoded in UTF-8.
    ///
    /// - Key and Group names are case-sensitive. For example, a group called
    ///   [GROUP] is a different from [group].
    ///
    /// - .ini files don't have a strongly typed boolean entry type,
    ///    they only have GetProfileInt(). In key files, only
    ///    true and false (in lower case) are allowed.
    ///
    /// Note that in contrast to the
    /// [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec),
    /// groups in key files may contain the same key multiple times; the last entry wins.
    /// Key files may also contain multiple groups with the same name; they are merged
    /// together. Another difference is that keys and group names in key files are not
    /// restricted to ASCII characters.
    ///
    /// Here is an example of loading a key file and reading a value:
    ///
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    /// g_autoptr(GError) error = NULL;
    /// g_autoptr(GKeyFile) key_file = g_key_file_new ();
    ///
    /// if (!g_key_file_load_from_file (key_file, "key-file.ini", flags, &error))
    ///   {
    ///     if (!g_error_matches (error, G_FILE_ERROR, G_FILE_ERROR_NOENT))
    ///       g_warning ("Error loading key file: %s", error->message);
    ///     return;
    ///   }
    ///
    /// g_autofree gchar *val = g_key_file_get_string (key_file, "Group Name", "SomeKey", &error);
    /// if (val == NULL &&
    ///     !g_error_matches (error, G_KEY_FILE_ERROR, G_KEY_FILE_ERROR_KEY_NOT_FOUND))
    ///   {
    ///     g_warning ("Error finding key in key file: %s", error->message);
    ///     return;
    ///   }
    /// else if (val == NULL)
    ///   {
    ///     // Fall back to a default value.
    ///     val = g_strdup ("default-value");
    ///   }
    /// ```
    ///
    /// Here is an example of creating and saving a key file:
    ///
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    /// g_autoptr(GKeyFile) key_file = g_key_file_new ();
    /// const gchar *val = …;
    /// g_autoptr(GError) error = NULL;
    ///
    /// g_key_file_set_string (key_file, "Group Name", "SomeKey", val);
    ///
    /// // Save as a file.
    /// if (!g_key_file_save_to_file (key_file, "key-file.ini", &error))
    ///   {
    ///     g_warning ("Error saving key file: %s", error->message);
    ///     return;
    ///   }
    ///
    /// // Or store to a GBytes for use elsewhere.
    /// gsize data_len;
    /// g_autofree guint8 *data = (guint8 *) g_key_file_to_data (key_file, &data_len, &error);
    /// if (data == NULL)
    ///   {
    ///     g_warning ("Error saving key file: %s", error->message);
    ///     return;
    ///   }
    /// g_autoptr(GBytes) bytes = g_bytes_new_take (g_steal_pointer (&data), data_len);
    /// ```
    #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
    pub struct KeyFile(Shared<ffi::GKeyFile>);

    match fn {
        ref => |ptr| ffi::g_key_file_ref(ptr),
        unref => |ptr| ffi::g_key_file_unref(ptr),
        type_ => || ffi::g_key_file_get_type(),
    }
}

impl KeyFile {
    /// Creates a new empty #GKeyFile object. Use
    /// g_key_file_load_from_file(), g_key_file_load_from_data(),
    /// g_key_file_load_from_dirs() or g_key_file_load_from_data_dirs() to
    /// read an existing key file.
    ///
    /// # Returns
    ///
    /// an empty #GKeyFile.
    #[doc(alias = "g_key_file_new")]
    pub fn new() -> KeyFile {
        unsafe { from_glib_full(ffi::g_key_file_new()) }
    }

    /// Retrieves a comment above @key from @group_name.
    /// If @key is [`None`] then @comment will be read from above
    /// @group_name. If both @key and @group_name are [`None`], then
    /// @comment will be read from above the first group in the file.
    ///
    /// Note that the returned string does not include the '#' comment markers,
    /// but does include any whitespace after them (on each line). It includes
    /// the line breaks between lines, but does not include the final line break.
    /// ## `group_name`
    /// a group name, or [`None`]
    /// ## `key`
    /// a key
    ///
    /// # Returns
    ///
    /// a comment that should be freed with g_free()
    #[doc(alias = "g_key_file_get_comment")]
    #[doc(alias = "get_comment")]
    pub fn comment(
        &self,
        group_name: Option<&str>,
        key: Option<&str>,
    ) -> Result<crate::GString, crate::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::g_key_file_get_comment(
                self.to_glib_none().0,
                group_name.to_glib_none().0,
                key.to_glib_none().0,
                &mut error,
            );
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Returns the value associated with @key under @group_name as a
    /// double. If @group_name is [`None`], the start_group is used.
    ///
    /// If @key cannot be found then 0.0 is returned and @error is set to
    /// [`KeyFileError::KeyNotFound`][crate::KeyFileError::KeyNotFound]. Likewise, if the value associated
    /// with @key cannot be interpreted as a double then 0.0 is returned
    /// and @error is set to [`KeyFileError::InvalidValue`][crate::KeyFileError::InvalidValue].
    /// ## `group_name`
    /// a group name
    /// ## `key`
    /// a key
    ///
    /// # Returns
    ///
    /// the value associated with the key as a double, or
    ///     0.0 if the key was not found or could not be parsed.
    #[doc(alias = "g_key_file_get_double")]
    #[doc(alias = "get_double")]
    pub fn double(&self, group_name: &str, key: &str) -> Result<f64, crate::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::g_key_file_get_double(
                self.to_glib_none().0,
                group_name.to_glib_none().0,
                key.to_glib_none().0,
                &mut error,
            );
            if error.is_null() {
                Ok(ret)
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Returns the values associated with @key under @group_name as
    /// doubles.
    ///
    /// If @key cannot be found then [`None`] is returned and @error is set to
    /// [`KeyFileError::KeyNotFound`][crate::KeyFileError::KeyNotFound]. Likewise, if the values associated
    /// with @key cannot be interpreted as doubles then [`None`] is returned
    /// and @error is set to [`KeyFileError::InvalidValue`][crate::KeyFileError::InvalidValue].
    /// ## `group_name`
    /// a group name
    /// ## `key`
    /// a key
    ///
    /// # Returns
    ///
    ///
    ///     the values associated with the key as a list of doubles, or [`None`] if the
    ///     key was not found or could not be parsed. The returned list of doubles
    ///     should be freed with g_free() when no longer needed.
    #[doc(alias = "g_key_file_get_double_list")]
    #[doc(alias = "get_double_list")]
    pub fn double_list(&self, group_name: &str, key: &str) -> Result<Vec<f64>, crate::Error> {
        unsafe {
            let mut length = std::mem::MaybeUninit::uninit();
            let mut error = std::ptr::null_mut();
            let ret = ffi::g_key_file_get_double_list(
                self.to_glib_none().0,
                group_name.to_glib_none().0,
                key.to_glib_none().0,
                length.as_mut_ptr(),
                &mut error,
            );
            if error.is_null() {
                Ok(FromGlibContainer::from_glib_container_num(
                    ret,
                    length.assume_init() as _,
                ))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Returns the value associated with @key under @group_name as a signed
    /// 64-bit integer. This is similar to g_key_file_get_integer() but can return
    /// 64-bit results without truncation.
    /// ## `group_name`
    /// a non-[`None`] group name
    /// ## `key`
    /// a non-[`None`] key
    ///
    /// # Returns
    ///
    /// the value associated with the key as a signed 64-bit integer, or
    /// 0 if the key was not found or could not be parsed.
    #[doc(alias = "g_key_file_get_int64")]
    #[doc(alias = "get_int64")]
    pub fn int64(&self, group_name: &str, key: &str) -> Result<i64, crate::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::g_key_file_get_int64(
                self.to_glib_none().0,
                group_name.to_glib_none().0,
                key.to_glib_none().0,
                &mut error,
            );
            if error.is_null() {
                Ok(ret)
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Returns the value associated with @key under @group_name as an
    /// integer.
    ///
    /// If @key cannot be found then 0 is returned and @error is set to
    /// [`KeyFileError::KeyNotFound`][crate::KeyFileError::KeyNotFound]. Likewise, if the value associated
    /// with @key cannot be interpreted as an integer, or is out of range
    /// for a #gint, then 0 is returned
    /// and @error is set to [`KeyFileError::InvalidValue`][crate::KeyFileError::InvalidValue].
    /// ## `group_name`
    /// a group name
    /// ## `key`
    /// a key
    ///
    /// # Returns
    ///
    /// the value associated with the key as an integer, or
    ///     0 if the key was not found or could not be parsed.
    #[doc(alias = "g_key_file_get_integer")]
    #[doc(alias = "get_integer")]
    pub fn integer(&self, group_name: &str, key: &str) -> Result<i32, crate::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::g_key_file_get_integer(
                self.to_glib_none().0,
                group_name.to_glib_none().0,
                key.to_glib_none().0,
                &mut error,
            );
            if error.is_null() {
                Ok(ret)
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Returns the values associated with @key under @group_name as
    /// integers.
    ///
    /// If @key cannot be found then [`None`] is returned and @error is set to
    /// [`KeyFileError::KeyNotFound`][crate::KeyFileError::KeyNotFound]. Likewise, if the values associated
    /// with @key cannot be interpreted as integers, or are out of range for
    /// #gint, then [`None`] is returned
    /// and @error is set to [`KeyFileError::InvalidValue`][crate::KeyFileError::InvalidValue].
    /// ## `group_name`
    /// a group name
    /// ## `key`
    /// a key
    ///
    /// # Returns
    ///
    ///
    ///     the values associated with the key as a list of integers, or [`None`] if
    ///     the key was not found or could not be parsed. The returned list of
    ///     integers should be freed with g_free() when no longer needed.
    #[doc(alias = "g_key_file_get_integer_list")]
    #[doc(alias = "get_integer_list")]
    pub fn integer_list(&self, group_name: &str, key: &str) -> Result<Vec<i32>, crate::Error> {
        unsafe {
            let mut length = std::mem::MaybeUninit::uninit();
            let mut error = std::ptr::null_mut();
            let ret = ffi::g_key_file_get_integer_list(
                self.to_glib_none().0,
                group_name.to_glib_none().0,
                key.to_glib_none().0,
                length.as_mut_ptr(),
                &mut error,
            );
            if error.is_null() {
                Ok(FromGlibContainer::from_glib_container_num(
                    ret,
                    length.assume_init() as _,
                ))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Returns the actual locale which the result of
    /// g_key_file_get_locale_string() or g_key_file_get_locale_string_list()
    /// came from.
    ///
    /// If calling g_key_file_get_locale_string() or
    /// g_key_file_get_locale_string_list() with exactly the same @self,
    /// @group_name, @key and @locale, the result of those functions will
    /// have originally been tagged with the locale that is the result of
    /// this function.
    /// ## `group_name`
    /// a group name
    /// ## `key`
    /// a key
    /// ## `locale`
    /// a locale identifier or [`None`]
    ///
    /// # Returns
    ///
    /// the locale from the file, or [`None`] if the key was not
    ///   found or the entry in the file was was untranslated
    #[doc(alias = "g_key_file_get_locale_for_key")]
    #[doc(alias = "get_locale_for_key")]
    pub fn locale_for_key(
        &self,
        group_name: &str,
        key: &str,
        locale: Option<&str>,
    ) -> Option<crate::GString> {
        unsafe {
            from_glib_full(ffi::g_key_file_get_locale_for_key(
                self.to_glib_none().0,
                group_name.to_glib_none().0,
                key.to_glib_none().0,
                locale.to_glib_none().0,
            ))
        }
    }

    /// Returns the name of the start group of the file.
    ///
    /// # Returns
    ///
    /// The start group of the key file.
    #[doc(alias = "g_key_file_get_start_group")]
    #[doc(alias = "get_start_group")]
    pub fn start_group(&self) -> Option<crate::GString> {
        unsafe { from_glib_full(ffi::g_key_file_get_start_group(self.to_glib_none().0)) }
    }

    /// Returns the value associated with @key under @group_name as an unsigned
    /// 64-bit integer. This is similar to g_key_file_get_integer() but can return
    /// large positive results without truncation.
    /// ## `group_name`
    /// a non-[`None`] group name
    /// ## `key`
    /// a non-[`None`] key
    ///
    /// # Returns
    ///
    /// the value associated with the key as an unsigned 64-bit integer,
    /// or 0 if the key was not found or could not be parsed.
    #[doc(alias = "g_key_file_get_uint64")]
    #[doc(alias = "get_uint64")]
    pub fn uint64(&self, group_name: &str, key: &str) -> Result<u64, crate::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::g_key_file_get_uint64(
                self.to_glib_none().0,
                group_name.to_glib_none().0,
                key.to_glib_none().0,
                &mut error,
            );
            if error.is_null() {
                Ok(ret)
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Returns the raw value associated with @key under @group_name.
    /// Use g_key_file_get_string() to retrieve an unescaped UTF-8 string.
    ///
    /// In the event the key cannot be found, [`None`] is returned and
    /// @error is set to [`KeyFileError::KeyNotFound`][crate::KeyFileError::KeyNotFound].  In the
    /// event that the @group_name cannot be found, [`None`] is returned
    /// and @error is set to [`KeyFileError::GroupNotFound`][crate::KeyFileError::GroupNotFound].
    /// ## `group_name`
    /// a group name
    /// ## `key`
    /// a key
    ///
    /// # Returns
    ///
    /// a newly allocated string or [`None`] if the specified
    ///  key cannot be found.
    #[doc(alias = "g_key_file_get_value")]
    #[doc(alias = "get_value")]
    pub fn value(&self, group_name: &str, key: &str) -> Result<crate::GString, crate::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::g_key_file_get_value(
                self.to_glib_none().0,
                group_name.to_glib_none().0,
                key.to_glib_none().0,
                &mut error,
            );
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Looks whether the key file has the group @group_name.
    /// ## `group_name`
    /// a group name
    ///
    /// # Returns
    ///
    /// [`true`] if @group_name is a part of @self, [`false`]
    /// otherwise.
    #[doc(alias = "g_key_file_has_group")]
    pub fn has_group(&self, group_name: &str) -> bool {
        unsafe {
            from_glib(ffi::g_key_file_has_group(
                self.to_glib_none().0,
                group_name.to_glib_none().0,
            ))
        }
    }

    /// Loads a key file from the data in @bytes into an empty #GKeyFile structure.
    /// If the object cannot be created then `error` is set to a #GKeyFileError.
    /// ## `bytes`
    /// a #GBytes
    /// ## `flags`
    /// flags from #GKeyFileFlags
    ///
    /// # Returns
    ///
    /// [`true`] if a key file could be loaded, [`false`] otherwise
    #[doc(alias = "g_key_file_load_from_bytes")]
    pub fn load_from_bytes(&self, bytes: &Bytes, flags: KeyFileFlags) -> Result<(), crate::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::g_key_file_load_from_bytes(
                self.to_glib_none().0,
                bytes.to_glib_none().0,
                flags.into_glib(),
                &mut error,
            );
            debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok(())
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Loads a key file from memory into an empty #GKeyFile structure.
    /// If the object cannot be created then `error` is set to a #GKeyFileError.
    /// ## `data`
    /// key file loaded in memory
    /// ## `length`
    /// the length of @data in bytes (or (gsize)-1 if data is nul-terminated)
    /// ## `flags`
    /// flags from #GKeyFileFlags
    ///
    /// # Returns
    ///
    /// [`true`] if a key file could be loaded, [`false`] otherwise
    #[doc(alias = "g_key_file_load_from_data")]
    pub fn load_from_data(&self, data: &str, flags: KeyFileFlags) -> Result<(), crate::Error> {
        let length = data.len() as _;
        unsafe {
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::g_key_file_load_from_data(
                self.to_glib_none().0,
                data.to_glib_none().0,
                length,
                flags.into_glib(),
                &mut error,
            );
            debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok(())
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Loads a key file into an empty #GKeyFile structure.
    ///
    /// If the OS returns an error when opening or reading the file, a
    /// `G_FILE_ERROR` is returned. If there is a problem parsing the file, a
    /// `G_KEY_FILE_ERROR` is returned.
    ///
    /// This function will never return a [`KeyFileError::NotFound`][crate::KeyFileError::NotFound] error. If the
    /// @file is not found, [`FileError::Noent`][crate::FileError::Noent] is returned.
    /// ## `file`
    /// the path of a filename to load, in the GLib filename encoding
    /// ## `flags`
    /// flags from #GKeyFileFlags
    ///
    /// # Returns
    ///
    /// [`true`] if a key file could be loaded, [`false`] otherwise
    #[doc(alias = "g_key_file_load_from_file")]
    pub fn load_from_file(
        &self,
        file: impl AsRef<std::path::Path>,
        flags: KeyFileFlags,
    ) -> Result<(), crate::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::g_key_file_load_from_file(
                self.to_glib_none().0,
                file.as_ref().to_glib_none().0,
                flags.into_glib(),
                &mut error,
            );
            debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok(())
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Removes a comment above @key from @group_name.
    /// If @key is [`None`] then @comment will be removed above @group_name.
    /// If both @key and @group_name are [`None`], then @comment will
    /// be removed above the first group in the file.
    /// ## `group_name`
    /// a group name, or [`None`]
    /// ## `key`
    /// a key
    ///
    /// # Returns
    ///
    /// [`true`] if the comment was removed, [`false`] otherwise
    #[doc(alias = "g_key_file_remove_comment")]
    pub fn remove_comment(
        &self,
        group_name: Option<&str>,
        key: Option<&str>,
    ) -> Result<(), crate::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::g_key_file_remove_comment(
                self.to_glib_none().0,
                group_name.to_glib_none().0,
                key.to_glib_none().0,
                &mut error,
            );
            debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok(())
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Removes the specified group, @group_name,
    /// from the key file.
    /// ## `group_name`
    /// a group name
    ///
    /// # Returns
    ///
    /// [`true`] if the group was removed, [`false`] otherwise
    #[doc(alias = "g_key_file_remove_group")]
    pub fn remove_group(&self, group_name: &str) -> Result<(), crate::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::g_key_file_remove_group(
                self.to_glib_none().0,
                group_name.to_glib_none().0,
                &mut error,
            );
            debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok(())
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Removes @key in @group_name from the key file.
    /// ## `group_name`
    /// a group name
    /// ## `key`
    /// a key name to remove
    ///
    /// # Returns
    ///
    /// [`true`] if the key was removed, [`false`] otherwise
    #[doc(alias = "g_key_file_remove_key")]
    pub fn remove_key(&self, group_name: &str, key: &str) -> Result<(), crate::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::g_key_file_remove_key(
                self.to_glib_none().0,
                group_name.to_glib_none().0,
                key.to_glib_none().0,
                &mut error,
            );
            debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok(())
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Associates a new boolean value with @key under @group_name.
    /// If @key cannot be found then it is created.
    /// ## `group_name`
    /// a group name
    /// ## `key`
    /// a key
    /// ## `value`
    /// [`true`] or [`false`]
    #[doc(alias = "g_key_file_set_boolean")]
    pub fn set_boolean(&self, group_name: &str, key: &str, value: bool) {
        unsafe {
            ffi::g_key_file_set_boolean(
                self.to_glib_none().0,
                group_name.to_glib_none().0,
                key.to_glib_none().0,
                value.into_glib(),
            );
        }
    }

    //#[doc(alias = "g_key_file_set_boolean_list")]
    //pub fn set_boolean_list(&self, group_name: &str, key: &str, list: /*Unimplemented*/&CArray TypeId { ns_id: 0, id: 1 }) {
    //    unsafe { TODO: call ffi:g_key_file_set_boolean_list() }
    //}

    /// Places a comment above @key from @group_name.
    ///
    /// If @key is [`None`] then @comment will be written above @group_name.
    /// If both @key and @group_name  are [`None`], then @comment will be
    /// written above the first group in the file.
    ///
    /// Note that this function prepends a '#' comment marker to
    /// each line of @comment.
    /// ## `group_name`
    /// a group name, or [`None`]
    /// ## `key`
    /// a key
    /// ## `comment`
    /// a comment
    ///
    /// # Returns
    ///
    /// [`true`] if the comment was written, [`false`] otherwise
    #[doc(alias = "g_key_file_set_comment")]
    pub fn set_comment(
        &self,
        group_name: Option<&str>,
        key: Option<&str>,
        comment: &str,
    ) -> Result<(), crate::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::g_key_file_set_comment(
                self.to_glib_none().0,
                group_name.to_glib_none().0,
                key.to_glib_none().0,
                comment.to_glib_none().0,
                &mut error,
            );
            debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok(())
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Associates a new double value with @key under @group_name.
    /// If @key cannot be found then it is created.
    /// ## `group_name`
    /// a group name
    /// ## `key`
    /// a key
    /// ## `value`
    /// a double value
    #[doc(alias = "g_key_file_set_double")]
    pub fn set_double(&self, group_name: &str, key: &str, value: f64) {
        unsafe {
            ffi::g_key_file_set_double(
                self.to_glib_none().0,
                group_name.to_glib_none().0,
                key.to_glib_none().0,
                value,
            );
        }
    }

    /// Associates a new integer value with @key under @group_name.
    /// If @key cannot be found then it is created.
    /// ## `group_name`
    /// a group name
    /// ## `key`
    /// a key
    /// ## `value`
    /// an integer value
    #[doc(alias = "g_key_file_set_int64")]
    pub fn set_int64(&self, group_name: &str, key: &str, value: i64) {
        unsafe {
            ffi::g_key_file_set_int64(
                self.to_glib_none().0,
                group_name.to_glib_none().0,
                key.to_glib_none().0,
                value,
            );
        }
    }

    /// Associates a new integer value with @key under @group_name.
    /// If @key cannot be found then it is created.
    /// ## `group_name`
    /// a group name
    /// ## `key`
    /// a key
    /// ## `value`
    /// an integer value
    #[doc(alias = "g_key_file_set_integer")]
    pub fn set_integer(&self, group_name: &str, key: &str, value: i32) {
        unsafe {
            ffi::g_key_file_set_integer(
                self.to_glib_none().0,
                group_name.to_glib_none().0,
                key.to_glib_none().0,
                value,
            );
        }
    }

    /// Sets the character which is used to separate
    /// values in lists. Typically ';' or ',' are used
    /// as separators. The default list separator is ';'.
    /// ## `separator`
    /// the separator
    #[doc(alias = "g_key_file_set_list_separator")]
    pub fn set_list_separator(&self, separator: crate::Char) {
        unsafe {
            ffi::g_key_file_set_list_separator(self.to_glib_none().0, separator.into_glib());
        }
    }

    /// Associates a string value for @key and @locale under @group_name.
    /// If the translation for @key cannot be found then it is created.
    /// ## `group_name`
    /// a group name
    /// ## `key`
    /// a key
    /// ## `locale`
    /// a locale identifier
    /// ## `string`
    /// a string
    #[doc(alias = "g_key_file_set_locale_string")]
    pub fn set_locale_string(&self, group_name: &str, key: &str, locale: &str, string: &str) {
        unsafe {
            ffi::g_key_file_set_locale_string(
                self.to_glib_none().0,
                group_name.to_glib_none().0,
                key.to_glib_none().0,
                locale.to_glib_none().0,
                string.to_glib_none().0,
            );
        }
    }

    /// Associates a new string value with @key under @group_name.
    /// If @key cannot be found then it is created.
    /// If @group_name cannot be found then it is created.
    /// Unlike g_key_file_set_value(), this function handles characters
    /// that need escaping, such as newlines.
    /// ## `group_name`
    /// a group name
    /// ## `key`
    /// a key
    /// ## `string`
    /// a string
    #[doc(alias = "g_key_file_set_string")]
    pub fn set_string(&self, group_name: &str, key: &str, string: &str) {
        unsafe {
            ffi::g_key_file_set_string(
                self.to_glib_none().0,
                group_name.to_glib_none().0,
                key.to_glib_none().0,
                string.to_glib_none().0,
            );
        }
    }

    /// Associates a new integer value with @key under @group_name.
    /// If @key cannot be found then it is created.
    /// ## `group_name`
    /// a group name
    /// ## `key`
    /// a key
    /// ## `value`
    /// an integer value
    #[doc(alias = "g_key_file_set_uint64")]
    pub fn set_uint64(&self, group_name: &str, key: &str, value: u64) {
        unsafe {
            ffi::g_key_file_set_uint64(
                self.to_glib_none().0,
                group_name.to_glib_none().0,
                key.to_glib_none().0,
                value,
            );
        }
    }

    /// Associates a new value with @key under @group_name.
    ///
    /// If @key cannot be found then it is created. If @group_name cannot
    /// be found then it is created. To set an UTF-8 string which may contain
    /// characters that need escaping (such as newlines or spaces), use
    /// g_key_file_set_string().
    /// ## `group_name`
    /// a group name
    /// ## `key`
    /// a key
    /// ## `value`
    /// a string
    #[doc(alias = "g_key_file_set_value")]
    pub fn set_value(&self, group_name: &str, key: &str, value: &str) {
        unsafe {
            ffi::g_key_file_set_value(
                self.to_glib_none().0,
                group_name.to_glib_none().0,
                key.to_glib_none().0,
                value.to_glib_none().0,
            );
        }
    }
}

impl Default for KeyFile {
    fn default() -> Self {
        Self::new()
    }
}