Struct glib::KeyFile

pub struct KeyFile(_);

The GKeyFile struct contains only private data and should not be accessed directly.

Implementations

impl KeyFile

pub fn new() -> KeyFile

Creates a new empty KeyFile object. Use load_from_file(), load_from_data(), load_from_dirs() or load_from_data_dirs() to read an existing key file.

Returns

an empty KeyFile.

pub fn comment(
    &self,
    group_name: Option<&str>,
    key: Option<&str>
) -> Result<GString, Error>

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()

pub fn double(&self, group_name: &str, key: &str) -> Result<f64, 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. 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.

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.

pub fn double_list(
    &self,
    group_name: &str,
    key: &str
) -> Result<Vec<f64>, 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. Likewise, if the values associated with key cannot be interpreted as doubles then None is returned and error is set to 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.

pub fn groups(&self) -> (Vec<GString>, usize)

Returns all groups in the key file loaded with self. The array of returned groups will be None-terminated, so length may optionally be None.

Returns

a newly-allocated None-terminated array of strings. Use g_strfreev() to free it.

length

return location for the number of returned groups, or None

pub fn int64(&self, group_name: &str, key: &str) -> Result<i64, Error>

Returns the value associated with key under group_name as a signed 64-bit integer. This is similar to 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.

pub fn integer(&self, group_name: &str, key: &str) -> Result<i32, 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. 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.

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.

pub fn integer_list(
    &self,
    group_name: &str,
    key: &str
) -> Result<Vec<i32>, 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. 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.

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.

pub fn keys(&self, group_name: &str) -> Result<(Vec<GString>, usize), Error>

Returns all keys for the group name group_name. The array of returned keys will be None-terminated, so length may optionally be None. In the event that the group_name cannot be found, None is returned and error is set to KeyFileError::GroupNotFound.

group_name

a group name

Returns

a newly-allocated None-terminated array of strings. Use g_strfreev() to free it.

length

return location for the number of keys returned, or None

pub fn locale_for_key(
    &self,
    group_name: &str,
    key: &str,
    locale: Option<&str>
) -> Option<GString>

This is supported on crate feature v2_56 only.

Returns the actual locale which the result of locale_string() or locale_string_list() came from.

If calling locale_string() or 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

pub fn start_group(&self) -> Option<GString>

Returns the name of the start group of the file.

Returns

The start group of the key file.

pub fn uint64(&self, group_name: &str, key: &str) -> Result<u64, Error>

Returns the value associated with key under group_name as an unsigned 64-bit integer. This is similar to 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.

pub fn value(&self, group_name: &str, key: &str) -> Result<GString, Error>

Returns the raw value associated with key under group_name. Use 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. In the event that the group_name cannot be found, None is returned and error is set to KeyFileError::GroupNotFound.

group_name

a group name

key

a key

Returns

a newly allocated string or None if the specified key cannot be found.

pub fn has_group(&self, group_name: &str) -> bool

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.

pub fn load_from_bytes(
    &self,
    bytes: &Bytes,
    flags: KeyFileFlags
) -> Result<(), Error>

This is supported on crate feature v2_50 only.

Loads a key file from the data in bytes into an empty KeyFile structure. If the object cannot be created then error is set to a KeyFileError.

bytes

a Bytes

flags

flags from KeyFileFlags

Returns

true if a key file could be loaded, false otherwise

pub fn load_from_data(
    &self,
    data: &str,
    flags: KeyFileFlags
) -> Result<(), Error>

Loads a key file from memory into an empty KeyFile structure. If the object cannot be created then error is set to a KeyFileError.

data

key file loaded in memory

length

the length of data in bytes (or (gsize)-1 if data is nul-terminated)

flags

flags from KeyFileFlags

Returns

true if a key file could be loaded, false otherwise

pub fn load_from_file<P: AsRef<Path>>(
    &self,
    file: P,
    flags: KeyFileFlags
) -> Result<(), Error>

Loads a key file into an empty KeyFile 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 error. If the file is not found, G_FILE_ERROR_NOENT is returned.

file

the path of a filename to load, in the GLib filename encoding

flags

flags from KeyFileFlags

Returns

true if a key file could be loaded, false otherwise

pub fn remove_comment(
    &self,
    group_name: Option<&str>,
    key: Option<&str>
) -> Result<(), 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

pub fn remove_group(&self, group_name: &str) -> Result<(), 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

pub fn remove_key(&self, group_name: &str, key: &str) -> Result<(), 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

pub fn set_boolean(&self, group_name: &str, key: &str, value: bool)

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

pub fn set_comment(
    &self,
    group_name: Option<&str>,
    key: Option<&str>,
    comment: &str
) -> Result<(), Error>

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

pub fn set_double(&self, group_name: &str, key: &str, value: f64)

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

pub fn set_int64(&self, group_name: &str, key: &str, value: i64)

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

pub fn set_integer(&self, group_name: &str, key: &str, value: i32)

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

pub fn set_list_separator(&self, separator: Char)

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

pub fn set_locale_string(
    &self,
    group_name: &str,
    key: &str,
    locale: &str,
    string: &str
)

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

pub fn set_string(&self, group_name: &str, key: &str, string: &str)

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 set_value(), this function handles characters that need escaping, such as newlines.

group_name

a group name

key

a key

string

a string

pub fn set_uint64(&self, group_name: &str, key: &str, value: u64)

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

pub fn set_value(&self, group_name: &str, key: &str, value: &str)

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 set_string().

group_name

a group name

key

a key

value

a string

impl KeyFile

pub fn save_to_file<T: AsRef<Path>>(&self, filename: T) -> Result<(), Error>

Writes the contents of self to filename using file_set_contents(). If you need stricter guarantees about durability of the written file than are provided by file_set_contents(), use file_set_contents_full() with the return value of to_data().

This function can fail for any of the reasons that file_set_contents() may fail.

filename

the name of the file to write to

Returns

true if successful, else false with error set

pub fn load_from_data_dirs<T: AsRef<Path>>(
    &self,
    file: T,
    flags: KeyFileFlags
) -> Result<PathBuf, Error>

This function looks for a key file named file in the paths returned from user_data_dir() and system_data_dirs(), loads the file into self and returns the file’s full path in full_path. If the file could not be loaded then an error is set to either a GFileError or KeyFileError.

file

a relative path to a filename to open and parse

flags

flags from KeyFileFlags

Returns

true if a key file could be loaded, false otherwise

full_path

return location for a string containing the full path of the file, or None

pub fn load_from_dirs<T: AsRef<Path>, U: AsRef<Path>>(
    &self,
    file: T,
    search_dirs: &[U],
    flags: KeyFileFlags
) -> Result<PathBuf, Error>

This function looks for a key file named file in the paths specified in search_dirs, loads the file into self and returns the file’s full path in full_path.

If the file could not be found in any of the search_dirs, KeyFileError::NotFound is returned. If the file is found but 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.

file

a relative path to a filename to open and parse

search_dirs

None-terminated array of directories to search

flags

flags from KeyFileFlags

Returns

true if a key file could be loaded, false otherwise

full_path

return location for a string containing the full path of the file, or None

pub fn to_data(&self) -> GString

This function outputs self as a string.

Note that this function never reports an error, so it is safe to pass None as error.

Returns

a newly allocated string holding the contents of the KeyFile

length

return location for the length of the returned string, or None

pub fn boolean(&self, group_name: &str, key: &str) -> Result<bool, Error>

Returns the value associated with key under group_name as a boolean.

If key cannot be found then false is returned and error is set to KeyFileError::KeyNotFound. Likewise, if the value associated with key cannot be interpreted as a boolean then false is returned and error is set to KeyFileError::InvalidValue.

group_name

a group name

key

a key

Returns

the value associated with the key as a boolean, or false if the key was not found or could not be parsed.

pub fn has_key(&self, group_name: &str, key: &str) -> Result<bool, Error>

Looks whether the key file has the key key in the group group_name.

Note that this function does not follow the rules for Error strictly; the return value both carries meaning and signals an error. To use this function, you must pass a Error pointer in error, and check whether it is not None to see if an error occurred.

Language bindings should use value() to test whether or not a key exists.

group_name

a group name

key

a key name

Returns

true if key is a part of group_name, false otherwise

pub fn boolean_list(
    &self,
    group_name: &str,
    key: &str
) -> Result<Vec<bool>, Error>

Returns the values associated with key under group_name as booleans.

If key cannot be found then None is returned and error is set to KeyFileError::KeyNotFound. Likewise, if the values associated with key cannot be interpreted as booleans then None is returned and error is set to KeyFileError::InvalidValue.

group_name

a group name

key

a key

Returns

the values associated with the key as a list of booleans, or None if the key was not found or could not be parsed. The returned list of booleans should be freed with g_free() when no longer needed.

pub fn string(&self, group_name: &str, key: &str) -> Result<GString, Error>

Returns the string value associated with key under group_name. Unlike value(), this function handles escape sequences like \s.

In the event the key cannot be found, None is returned and error is set to KeyFileError::KeyNotFound. In the event that the group_name cannot be found, None is returned and error is set to KeyFileError::GroupNotFound.

group_name

a group name

key

a key

Returns

a newly allocated string or None if the specified key cannot be found.

pub fn string_list(
    &self,
    group_name: &str,
    key: &str
) -> Result<Vec<GString>, Error>

Returns the values associated with key under group_name.

In the event the key cannot be found, None is returned and error is set to KeyFileError::KeyNotFound. In the event that the group_name cannot be found, None is returned and error is set to KeyFileError::GroupNotFound.

group_name

a group name

key

a key

Returns

a None-terminated string array or None if the specified key cannot be found. The array should be freed with g_strfreev().

pub fn locale_string(
    &self,
    group_name: &str,
    key: &str,
    locale: Option<&str>
) -> Result<GString, Error>

Returns the value associated with key under group_name translated in the given locale if available. If locale is None then the current locale is assumed.

If locale is to be non-None, or if the current locale will change over the lifetime of the KeyFile, it must be loaded with KeyFileFlags::KEEP_TRANSLATIONS in order to load strings for all locales.

If key cannot be found then None is returned and error is set to KeyFileError::KeyNotFound. If the value associated with key cannot be interpreted or no suitable translation can be found then the untranslated value is returned.

group_name

a group name

key

a key

locale

a locale identifier or None

Returns

a newly allocated string or None if the specified key cannot be found.

pub fn locale_string_list(
    &self,
    group_name: &str,
    key: &str,
    locale: Option<&str>
) -> Result<Vec<GString>, Error>

Returns the values associated with key under group_name translated in the given locale if available. If locale is None then the current locale is assumed.

If locale is to be non-None, or if the current locale will change over the lifetime of the KeyFile, it must be loaded with KeyFileFlags::KEEP_TRANSLATIONS in order to load strings for all locales.

If key cannot be found then None is returned and error is set to KeyFileError::KeyNotFound. If the values associated with key cannot be interpreted or no suitable translations can be found then the untranslated values are returned. The returned array is None-terminated, so length may optionally be None.

group_name

a group name

key

a key

locale

a locale identifier or None

Returns

a newly allocated None-terminated string array or None if the key isn’t found. The string array should be freed with g_strfreev().

Trait Implementations

impl Clone for KeyFile

fn clone(&self) -> KeyFile

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for KeyFile

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for KeyFile

fn default() -> Self

Returns the “default value” for a type.

impl Hash for KeyFile

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl Ord for KeyFile

fn cmp(&self, other: &KeyFile) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl PartialEq<KeyFile> for KeyFile

fn eq(&self, other: &KeyFile) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &KeyFile) -> bool

This method tests for !=.

impl PartialOrd<KeyFile> for KeyFile

fn partial_cmp(&self, other: &KeyFile) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl StaticType for KeyFile

fn static_type() -> Type

Returns the type identifier of Self.

impl Eq for KeyFile

impl StructuralEq for KeyFile

impl StructuralPartialEq for KeyFile