glib/auto/

functions.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

#[cfg(feature = "v2_66")]
#[cfg_attr(docsrs, doc(cfg(feature = "v2_66")))]
use crate::FileSetContentsFlags;
use crate::{
    Bytes, ChecksumType, Error, FileTest, FormatSizeFlags, Pid, Source, SpawnFlags, UserDirectory,
    ffi, translate::*,
};
use std::boxed::Box as Box_;

/// A wrapper for the POSIX access() function. This function is used to
/// test a pathname for one or several of read, write or execute
/// permissions, or just existence.
///
/// On Windows, the file protection mechanism is not at all POSIX-like,
/// and the underlying function in the C library only checks the
/// FAT-style READONLY attribute, and does not look at the ACL of a
/// file at all. This function is this in practise almost useless on
/// Windows. Software that needs to handle file permissions on Windows
/// more exactly should use the Win32 API.
///
/// See your C library manual for more details about access().
/// ## `filename`
/// a pathname in the GLib file name encoding
///     (UTF-8 on Windows)
/// ## `mode`
/// as in access()
///
/// # Returns
///
/// zero if the pathname refers to an existing file system
///     object that has all the tested permissions, or -1 otherwise
///     or on error.
#[doc(alias = "g_access")]
pub fn access(filename: impl AsRef<std::path::Path>, mode: i32) -> i32 {
    unsafe { ffi::g_access(filename.as_ref().to_glib_none().0, mode) }
}

/// Decode a sequence of Base-64 encoded text into binary data.  Note
/// that the returned binary data is not necessarily zero-terminated,
/// so it should not be used as a character string.
/// ## `text`
/// zero-terminated string with base64 text to decode
///
/// # Returns
///
///
///               newly allocated buffer containing the binary data
///               that @text represents. The returned buffer must
///               be freed with g_free().
#[doc(alias = "g_base64_decode")]
pub fn base64_decode(text: &str) -> Vec<u8> {
    unsafe {
        let mut out_len = std::mem::MaybeUninit::uninit();
        let ret = FromGlibContainer::from_glib_full_num(
            ffi::g_base64_decode(text.to_glib_none().0, out_len.as_mut_ptr()),
            out_len.assume_init() as _,
        );
        ret
    }
}

//#[doc(alias = "g_base64_decode_inplace")]
//pub fn base64_decode_inplace(text: /*Unimplemented*/Vec<u8>) -> u8 {
//    unsafe { TODO: call ffi:g_base64_decode_inplace() }
//}

//#[doc(alias = "g_base64_decode_step")]
//pub fn base64_decode_step(in_: &[&str], out: Vec<u8>, state: &mut i32, save: &mut u32) -> usize {
//    unsafe { TODO: call ffi:g_base64_decode_step() }
//}

/// Encode a sequence of binary data into its Base-64 stringified
/// representation.
/// ## `data`
/// the binary data to encode
///
/// # Returns
///
/// a newly allocated, zero-terminated Base-64
///               encoded string representing @data. The returned string must
///               be freed with g_free().
#[doc(alias = "g_base64_encode")]
pub fn base64_encode(data: &[u8]) -> crate::GString {
    let len = data.len() as _;
    unsafe { from_glib_full(ffi::g_base64_encode(data.to_glib_none().0, len)) }
}

//#[doc(alias = "g_base64_encode_close")]
//pub fn base64_encode_close(break_lines: bool, out: Vec<u8>, state: &mut i32, save: &mut i32) -> usize {
//    unsafe { TODO: call ffi:g_base64_encode_close() }
//}

//#[doc(alias = "g_base64_encode_step")]
//pub fn base64_encode_step(in_: &[u8], break_lines: bool, out: Vec<u8>, state: &mut i32, save: &mut i32) -> usize {
//    unsafe { TODO: call ffi:g_base64_encode_step() }
//}

/// Checks that the GLib library in use is compatible with the
/// given version.
///
/// Generally you would pass in the constants `GLIB_MAJOR_VERSION`,
/// `GLIB_MINOR_VERSION`, `GLIB_MICRO_VERSION` as the three arguments
/// to this function; that produces a check that the library in use
/// is compatible with the version of GLib the application or module
/// was compiled against.
///
/// Compatibility is defined by two things: first the version
/// of the running library is newer than the version
/// `@required_major.required_minor.@required_micro`. Second
/// the running library must be binary compatible with the
/// version `@required_major.@required_minor.@required_micro`
/// (same major version.)
/// ## `required_major`
/// the required major version
/// ## `required_minor`
/// the required minor version
/// ## `required_micro`
/// the required micro version
///
/// # Returns
///
/// [`None`] if the GLib library is
///   compatible with the given version, or a string describing the
///   version mismatch. The returned string is owned by GLib and must
///   not be modified or freed.
#[doc(alias = "glib_check_version")]
pub fn check_version(
    required_major: u32,
    required_minor: u32,
    required_micro: u32,
) -> Option<crate::GString> {
    unsafe {
        from_glib_none(ffi::glib_check_version(
            required_major,
            required_minor,
            required_micro,
        ))
    }
}

/// Computes the checksum for a binary @data. This is a
/// convenience wrapper for g_checksum_new(), g_checksum_get_string()
/// and g_checksum_free().
///
/// The hexadecimal string returned will be in lower case.
/// ## `checksum_type`
/// a #GChecksumType
/// ## `data`
/// binary blob to compute the digest of
///
/// # Returns
///
/// the digest of the binary data as a
///   string in hexadecimal, or [`None`] if g_checksum_new() fails for
///   @checksum_type. The returned string should be freed with g_free() when
///   done using it.
#[doc(alias = "g_compute_checksum_for_bytes")]
pub fn compute_checksum_for_bytes(
    checksum_type: ChecksumType,
    data: &Bytes,
) -> Option<crate::GString> {
    unsafe {
        from_glib_full(ffi::g_compute_checksum_for_bytes(
            checksum_type.into_glib(),
            data.to_glib_none().0,
        ))
    }
}

/// Computes the checksum for a binary @data of @length. This is a
/// convenience wrapper for g_checksum_new(), g_checksum_get_string()
/// and g_checksum_free().
///
/// The hexadecimal string returned will be in lower case.
/// ## `checksum_type`
/// a #GChecksumType
/// ## `data`
/// binary blob to compute the digest of
///
/// # Returns
///
/// the digest of the binary data as a
///   string in hexadecimal, or [`None`] if g_checksum_new() fails for
///   @checksum_type. The returned string should be freed with g_free() when
///   done using it.
#[doc(alias = "g_compute_checksum_for_data")]
pub fn compute_checksum_for_data(
    checksum_type: ChecksumType,
    data: &[u8],
) -> Option<crate::GString> {
    let length = data.len() as _;
    unsafe {
        from_glib_full(ffi::g_compute_checksum_for_data(
            checksum_type.into_glib(),
            data.to_glib_none().0,
            length,
        ))
    }
}

/// Computes the HMAC for a binary @data. This is a
/// convenience wrapper for g_hmac_new(), g_hmac_get_string()
/// and g_hmac_unref().
///
/// The hexadecimal string returned will be in lower case.
/// ## `digest_type`
/// a #GChecksumType to use for the HMAC
/// ## `key`
/// the key to use in the HMAC
/// ## `data`
/// binary blob to compute the HMAC of
///
/// # Returns
///
/// the HMAC of the binary data as a string in hexadecimal.
///   The returned string should be freed with g_free() when done using it.
#[doc(alias = "g_compute_hmac_for_bytes")]
pub fn compute_hmac_for_bytes(
    digest_type: ChecksumType,
    key: &Bytes,
    data: &Bytes,
) -> crate::GString {
    unsafe {
        from_glib_full(ffi::g_compute_hmac_for_bytes(
            digest_type.into_glib(),
            key.to_glib_none().0,
            data.to_glib_none().0,
        ))
    }
}

/// Computes the HMAC for a binary @data of @length. This is a
/// convenience wrapper for g_hmac_new(), g_hmac_get_string()
/// and g_hmac_unref().
///
/// The hexadecimal string returned will be in lower case.
/// ## `digest_type`
/// a #GChecksumType to use for the HMAC
/// ## `key`
/// the key to use in the HMAC
/// ## `data`
/// binary blob to compute the HMAC of
///
/// # Returns
///
/// the HMAC of the binary data as a string in hexadecimal.
///   The returned string should be freed with g_free() when done using it.
#[doc(alias = "g_compute_hmac_for_data")]
pub fn compute_hmac_for_data(digest_type: ChecksumType, key: &[u8], data: &[u8]) -> crate::GString {
    let key_len = key.len() as _;
    let length = data.len() as _;
    unsafe {
        from_glib_full(ffi::g_compute_hmac_for_data(
            digest_type.into_glib(),
            key.to_glib_none().0,
            key_len,
            data.to_glib_none().0,
            length,
        ))
    }
}

/// This is a variant of g_dgettext() that allows specifying a locale
/// category instead of always using `LC_MESSAGES`. See g_dgettext() for
/// more information about how this functions differs from calling
/// dcgettext() directly.
/// ## `domain`
/// the translation domain to use, or [`None`] to use
///   the domain set with textdomain()
/// ## `msgid`
/// message to translate
/// ## `category`
/// a locale category
///
/// # Returns
///
/// the translated string for the given locale category
#[doc(alias = "g_dcgettext")]
pub fn dcgettext(domain: Option<&str>, msgid: &str, category: i32) -> crate::GString {
    unsafe {
        from_glib_none(ffi::g_dcgettext(
            domain.to_glib_none().0,
            msgid.to_glib_none().0,
            category,
        ))
    }
}

/// This function is a wrapper of dgettext() which does not translate
/// the message if the default domain as set with textdomain() has no
/// translations for the current locale.
///
/// The advantage of using this function over dgettext() proper is that
/// libraries using this function (like GTK) will not use translations
/// if the application using the library does not have translations for
/// the current locale.  This results in a consistent English-only
/// interface instead of one having partial translations.  For this
/// feature to work, the call to textdomain() and setlocale() should
/// precede any g_dgettext() invocations.  For GTK, it means calling
/// textdomain() before gtk_init or its variants.
///
/// This function disables translations if and only if upon its first
/// call all the following conditions hold:
///
/// - @domain is not [`None`]
///
/// - textdomain() has been called to set a default text domain
///
/// - there is no translations available for the default text domain
///   and the current locale
///
/// - current locale is not "C" or any English locales (those
///   starting with "en_")
///
/// Note that this behavior may not be desired for example if an application
/// has its untranslated messages in a language other than English. In those
/// cases the application should call textdomain() after initializing GTK.
///
/// Applications should normally not use this function directly,
/// but use the _() macro for translations.
/// ## `domain`
/// the translation domain to use, or [`None`] to use
///   the domain set with textdomain()
/// ## `msgid`
/// message to translate
///
/// # Returns
///
/// The translated string
#[doc(alias = "g_dgettext")]
pub fn dgettext(domain: Option<&str>, msgid: &str) -> crate::GString {
    unsafe {
        from_glib_none(ffi::g_dgettext(
            domain.to_glib_none().0,
            msgid.to_glib_none().0,
        ))
    }
}

/// This function is a wrapper of dngettext() which does not translate
/// the message if the default domain as set with textdomain() has no
/// translations for the current locale.
///
/// See g_dgettext() for details of how this differs from dngettext()
/// proper.
/// ## `domain`
/// the translation domain to use, or [`None`] to use
///   the domain set with textdomain()
/// ## `msgid`
/// message to translate
/// ## `msgid_plural`
/// plural form of the message
/// ## `n`
/// the quantity for which translation is needed
///
/// # Returns
///
/// The translated string
#[doc(alias = "g_dngettext")]
pub fn dngettext(
    domain: Option<&str>,
    msgid: &str,
    msgid_plural: &str,
    n: libc::c_ulong,
) -> crate::GString {
    unsafe {
        from_glib_none(ffi::g_dngettext(
            domain.to_glib_none().0,
            msgid.to_glib_none().0,
            msgid_plural.to_glib_none().0,
            n,
        ))
    }
}

/// This function is a variant of g_dgettext() which supports
/// a disambiguating message context. GNU gettext uses the
/// '\004' character to separate the message context and
/// message id in @msgctxtid.
/// If 0 is passed as @msgidoffset, this function will fall back to
/// trying to use the deprecated convention of using "|" as a separation
/// character.
///
/// This uses g_dgettext() internally. See that functions for differences
/// with dgettext() proper.
///
/// Applications should normally not use this function directly,
/// but use the C_() macro for translations with context.
/// ## `domain`
/// the translation domain to use, or [`None`] to use
///   the domain set with textdomain()
/// ## `msgctxtid`
/// a combined message context and message id, separated
///   by a \004 character
/// ## `msgidoffset`
/// the offset of the message id in @msgctxid
///
/// # Returns
///
/// The translated string
#[doc(alias = "g_dpgettext")]
pub fn dpgettext(domain: Option<&str>, msgctxtid: &str, msgidoffset: usize) -> crate::GString {
    unsafe {
        from_glib_none(ffi::g_dpgettext(
            domain.to_glib_none().0,
            msgctxtid.to_glib_none().0,
            msgidoffset,
        ))
    }
}

/// This function is a variant of g_dgettext() which supports
/// a disambiguating message context. GNU gettext uses the
/// '\004' character to separate the message context and
/// message id in @msgctxtid.
///
/// This uses g_dgettext() internally. See that functions for differences
/// with dgettext() proper.
///
/// This function differs from C_() in that it is not a macro and
/// thus you may use non-string-literals as context and msgid arguments.
/// ## `domain`
/// the translation domain to use, or [`None`] to use
///   the domain set with textdomain()
/// ## `context`
/// the message context
/// ## `msgid`
/// the message
///
/// # Returns
///
/// The translated string
#[doc(alias = "g_dpgettext2")]
pub fn dpgettext2(domain: Option<&str>, context: &str, msgid: &str) -> crate::GString {
    unsafe {
        from_glib_none(ffi::g_dpgettext2(
            domain.to_glib_none().0,
            context.to_glib_none().0,
            msgid.to_glib_none().0,
        ))
    }
}

/// Writes all of @contents to a file named @filename. This is a convenience
/// wrapper around calling g_file_set_contents_full() with `flags` set to
/// `G_FILE_SET_CONTENTS_CONSISTENT | G_FILE_SET_CONTENTS_ONLY_EXISTING` and
/// `mode` set to `0666`.
/// ## `filename`
/// name of a file to write @contents to, in the GLib file name
///   encoding
/// ## `contents`
/// string to write to the file
///
/// # Returns
///
/// [`true`] on success, [`false`] if an error occurred
#[doc(alias = "g_file_set_contents")]
pub fn file_set_contents(
    filename: impl AsRef<std::path::Path>,
    contents: &[u8],
) -> Result<(), crate::Error> {
    let length = contents.len() as _;
    unsafe {
        let mut error = std::ptr::null_mut();
        let is_ok = ffi::g_file_set_contents(
            filename.as_ref().to_glib_none().0,
            contents.to_glib_none().0,
            length,
            &mut error,
        );
        debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
        if error.is_null() {
            Ok(())
        } else {
            Err(from_glib_full(error))
        }
    }
}

/// Writes all of @contents to a file named @filename, with good error checking.
/// If a file called @filename already exists it will be overwritten.
///
/// @flags control the properties of the write operation: whether it’s atomic,
/// and what the tradeoff is between returning quickly or being resilient to
/// system crashes.
///
/// As this function performs file I/O, it is recommended to not call it anywhere
/// where blocking would cause problems, such as in the main loop of a graphical
/// application. In particular, if @flags has any value other than
/// [`FileSetContentsFlags::NONE`][crate::FileSetContentsFlags::NONE] then this function may call `fsync()`.
///
/// If [`FileSetContentsFlags::CONSISTENT`][crate::FileSetContentsFlags::CONSISTENT] is set in @flags, the operation is atomic
/// in the sense that it is first written to a temporary file which is then
/// renamed to the final name.
///
/// Notes:
///
/// - On UNIX, if @filename already exists hard links to @filename will break.
///   Also since the file is recreated, existing permissions, access control
///   lists, metadata etc. may be lost. If @filename is a symbolic link,
///   the link itself will be replaced, not the linked file.
///
/// - On UNIX, if @filename already exists and is non-empty, and if the system
///   supports it (via a journalling filesystem or equivalent), and if
///   [`FileSetContentsFlags::CONSISTENT`][crate::FileSetContentsFlags::CONSISTENT] is set in @flags, the `fsync()` call (or
///   equivalent) will be used to ensure atomic replacement: @filename
///   will contain either its old contents or @contents, even in the face of
///   system power loss, the disk being unsafely removed, etc.
///
/// - On UNIX, if @filename does not already exist or is empty, there is a
///   possibility that system power loss etc. after calling this function will
///   leave @filename empty or full of NUL bytes, depending on the underlying
///   filesystem, unless [`FileSetContentsFlags::DURABLE`][crate::FileSetContentsFlags::DURABLE] and
///   [`FileSetContentsFlags::CONSISTENT`][crate::FileSetContentsFlags::CONSISTENT] are set in @flags.
///
/// - On Windows renaming a file will not remove an existing file with the
///   new name, so on Windows there is a race condition between the existing
///   file being removed and the temporary file being renamed.
///
/// - On Windows there is no way to remove a file that is open to some
///   process, or mapped into memory. Thus, this function will fail if
///   @filename already exists and is open.
///
/// If the call was successful, it returns [`true`]. If the call was not successful,
/// it returns [`false`] and sets @error. The error domain is `G_FILE_ERROR`.
/// Possible error codes are those in the #GFileError enumeration.
///
/// Note that the name for the temporary file is constructed by appending up
/// to 7 characters to @filename.
///
/// If the file didn’t exist before and is created, it will be given the
/// permissions from @mode. Otherwise, the permissions of the existing file will
/// remain unchanged.
/// ## `filename`
/// name of a file to write @contents to, in the GLib file name
///   encoding
/// ## `contents`
/// string to write to the file
/// ## `flags`
/// flags controlling the safety vs speed of the operation
/// ## `mode`
/// file mode, as passed to `open()`; typically this will be `0666`
///
/// # Returns
///
/// [`true`] on success, [`false`] if an error occurred
#[cfg(feature = "v2_66")]
#[cfg_attr(docsrs, doc(cfg(feature = "v2_66")))]
#[doc(alias = "g_file_set_contents_full")]
pub fn file_set_contents_full(
    filename: impl AsRef<std::path::Path>,
    contents: &[u8],
    flags: FileSetContentsFlags,
    mode: i32,
) -> Result<(), crate::Error> {
    let length = contents.len() as _;
    unsafe {
        let mut error = std::ptr::null_mut();
        let is_ok = ffi::g_file_set_contents_full(
            filename.as_ref().to_glib_none().0,
            contents.to_glib_none().0,
            length,
            flags.into_glib(),
            mode,
            &mut error,
        );
        debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
        if error.is_null() {
            Ok(())
        } else {
            Err(from_glib_full(error))
        }
    }
}

/// Returns [`true`] if any of the tests in the bitfield @test are
/// [`true`]. For example, `(G_FILE_TEST_EXISTS | G_FILE_TEST_IS_DIR)`
/// will return [`true`] if the file exists; the check whether it's a
/// directory doesn't matter since the existence test is [`true`]. With
/// the current set of available tests, there's no point passing in
/// more than one test at a time.
///
/// Apart from [`FileTest::IS_SYMLINK`][crate::FileTest::IS_SYMLINK] all tests follow symbolic links,
/// so for a symbolic link to a regular file g_file_test() will return
/// [`true`] for both [`FileTest::IS_SYMLINK`][crate::FileTest::IS_SYMLINK] and [`FileTest::IS_REGULAR`][crate::FileTest::IS_REGULAR].
///
/// Note, that for a dangling symbolic link g_file_test() will return
/// [`true`] for [`FileTest::IS_SYMLINK`][crate::FileTest::IS_SYMLINK] and [`false`] for all other flags.
///
/// You should never use g_file_test() to test whether it is safe
/// to perform an operation, because there is always the possibility
/// of the condition changing before you actually perform the operation,
/// see [TOCTOU](https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use).
///
/// For example, you might think you could use [`FileTest::IS_SYMLINK`][crate::FileTest::IS_SYMLINK]
/// to know whether it is safe to write to a file without being
/// tricked into writing into a different location. It doesn't work!
///
///
///
/// **⚠️ The following code is in C ⚠️**
///
/// ```C
///  // DON'T DO THIS
///  if (!g_file_test (filename, G_FILE_TEST_IS_SYMLINK))
///    {
///      fd = g_open (filename, O_WRONLY);
///      // write to fd
///    }
///
///  // DO THIS INSTEAD
///  fd = g_open (filename, O_WRONLY | O_NOFOLLOW | O_CLOEXEC);
///  if (fd == -1)
///    {
///      // check error
///      if (errno == ELOOP)
///        // file is a symlink and can be ignored
///      else
///        // handle errors as before
///    }
///  else
///    {
///      // write to fd
///    }
/// ```
///
/// Another thing to note is that [`FileTest::EXISTS`][crate::FileTest::EXISTS] and
/// [`FileTest::IS_EXECUTABLE`][crate::FileTest::IS_EXECUTABLE] are implemented using the access()
/// system call. This usually doesn't matter, but if your program
/// is setuid or setgid it means that these tests will give you
/// the answer for the real user ID and group ID, rather than the
/// effective user ID and group ID.
///
/// On Windows, there are no symlinks, so testing for
/// [`FileTest::IS_SYMLINK`][crate::FileTest::IS_SYMLINK] will always return [`false`]. Testing for
/// [`FileTest::IS_EXECUTABLE`][crate::FileTest::IS_EXECUTABLE] will just check that the file exists and
/// its name indicates that it is executable, checking for well-known
/// extensions and those listed in the `PATHEXT` environment variable.
/// ## `filename`
/// a filename to test in the
///     GLib file name encoding
/// ## `test`
/// bitfield of #GFileTest flags
///
/// # Returns
///
/// whether a test was [`true`]
#[doc(alias = "g_file_test")]
#[allow(dead_code)]
pub(crate) fn file_test(filename: impl AsRef<std::path::Path>, test: FileTest) -> bool {
    unsafe {
        from_glib(ffi::g_file_test(
            filename.as_ref().to_glib_none().0,
            test.into_glib(),
        ))
    }
}

/// 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 cannot make sense of the encoding of @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 @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 g_filename_display_name() if you know the
/// whole path, as it allows translation.
/// ## `filename`
/// an absolute pathname in the
///     GLib file name encoding
///
/// # Returns
///
/// a newly allocated string containing
///   a rendition of the basename of the filename in valid UTF-8
#[doc(alias = "g_filename_display_basename")]
pub fn filename_display_basename(filename: impl AsRef<std::path::Path>) -> crate::GString {
    unsafe {
        from_glib_full(ffi::g_filename_display_basename(
            filename.as_ref().to_glib_none().0,
        ))
    }
}

/// 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 g_filename_to_utf8(), the result is guaranteed to be non-[`None`]
/// even if the filename actually isn't in the GLib file name encoding.
///
/// If GLib cannot make sense of the encoding of @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 @filename was in an invalid
/// encoding.
///
/// If you know the whole pathname of the file you should use
/// g_filename_display_basename(), since that allows location-based
/// translation of filenames.
/// ## `filename`
/// a pathname hopefully in the
///     GLib file name encoding
///
/// # Returns
///
/// a newly allocated string containing
///   a rendition of the filename in valid UTF-8
#[doc(alias = "g_filename_display_name")]
pub fn filename_display_name(filename: impl AsRef<std::path::Path>) -> crate::GString {
    unsafe {
        from_glib_full(ffi::g_filename_display_name(
            filename.as_ref().to_glib_none().0,
        ))
    }
}

/// Converts an escaped ASCII-encoded URI to a local filename in the
/// encoding used for filenames.
///
/// Since GLib 2.78, the query string and fragment can be present in the URI,
/// but are not part of the resulting filename.
/// We take inspiration from https://url.spec.whatwg.org/#file-state,
/// but we don't support the entire standard.
/// ## `uri`
/// a uri describing a filename (escaped, encoded in ASCII).
///
/// # Returns
///
/// a newly-allocated string holding
///               the resulting filename, or [`None`] on an error.
///
/// ## `hostname`
/// Location to store hostname for the URI.
///            If there is no hostname in the URI, [`None`] will be
///            stored in this location.
#[doc(alias = "g_filename_from_uri")]
pub fn filename_from_uri(
    uri: &str,
) -> Result<(std::path::PathBuf, Option<crate::GString>), crate::Error> {
    unsafe {
        let mut hostname = std::ptr::null_mut();
        let mut error = std::ptr::null_mut();
        let ret = ffi::g_filename_from_uri(uri.to_glib_none().0, &mut hostname, &mut error);
        if error.is_null() {
            Ok((from_glib_full(ret), from_glib_full(hostname)))
        } else {
            Err(from_glib_full(error))
        }
    }
}

/// Converts an absolute filename to an escaped ASCII-encoded URI, with the path
/// component following Section 3.3. of RFC 2396.
/// ## `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
/// ## `hostname`
/// A UTF-8 encoded hostname, or [`None`] for none.
///
/// # Returns
///
/// a newly-allocated string holding the resulting
///               URI, or [`None`] on an error.
#[doc(alias = "g_filename_to_uri")]
pub fn filename_to_uri(
    filename: impl AsRef<std::path::Path>,
    hostname: Option<&str>,
) -> Result<crate::GString, crate::Error> {
    unsafe {
        let mut error = std::ptr::null_mut();
        let ret = ffi::g_filename_to_uri(
            filename.as_ref().to_glib_none().0,
            hostname.to_glib_none().0,
            &mut error,
        );
        if error.is_null() {
            Ok(from_glib_full(ret))
        } else {
            Err(from_glib_full(error))
        }
    }
}

/// Locates the first executable named @program in the user's path, in the
/// same way that execvp() would locate it. Returns an allocated string
/// with the absolute path name, or [`None`] if the program is not found in
/// the path. If @program is already an absolute path, returns a copy of
/// @program if @program exists and is executable, and [`None`] otherwise.
///
/// On Windows, if @program does not have a file type suffix, tries
/// with the suffixes .exe, .cmd, .bat and .com, and the suffixes in
/// the `PATHEXT` environment variable.
///
/// On Windows, it looks for the file in the same way as CreateProcess()
/// would. This means first in the directory where the executing
/// program was loaded from, then in the current directory, then in the
/// Windows 32-bit system directory, then in the Windows directory, and
/// finally in the directories in the `PATH` environment variable. If
/// the program is found, the return value contains the full name
/// including the type suffix.
/// ## `program`
/// a program name in the GLib file name encoding
///
/// # Returns
///
/// a newly-allocated
///   string with the absolute path, or [`None`]
#[doc(alias = "g_find_program_in_path")]
pub fn find_program_in_path(program: impl AsRef<std::path::Path>) -> Option<std::path::PathBuf> {
    unsafe {
        from_glib_full(ffi::g_find_program_in_path(
            program.as_ref().to_glib_none().0,
        ))
    }
}

/// Formats a size (for example the size of a file) into a human readable
/// string.  Sizes are rounded to the nearest size prefix (kB, MB, GB)
/// and are displayed rounded to the nearest tenth. E.g. the file size
/// 3292528 bytes will be converted into the string "3.2 MB". The returned string
/// is UTF-8, and may use a non-breaking space to separate the number and units,
/// to ensure they aren’t separated when line wrapped.
///
/// The prefix units base is 1000 (i.e. 1 kB is 1000 bytes).
///
/// This string should be freed with g_free() when not needed any longer.
///
/// See g_format_size_full() for more options about how the size might be
/// formatted.
/// ## `size`
/// a size in bytes
///
/// # Returns
///
/// a newly-allocated formatted string containing
///   a human readable file size
#[doc(alias = "g_format_size")]
pub fn format_size(size: u64) -> crate::GString {
    unsafe { from_glib_full(ffi::g_format_size(size)) }
}

/// Formats a size.
///
/// This function is similar to g_format_size() but allows for flags
/// that modify the output. See #GFormatSizeFlags.
/// ## `size`
/// a size in bytes
/// ## `flags`
/// #GFormatSizeFlags to modify the output
///
/// # Returns
///
/// a newly-allocated formatted string
///   containing a human readable file size
#[doc(alias = "g_format_size_full")]
pub fn format_size_full(size: u64, flags: FormatSizeFlags) -> crate::GString {
    unsafe { from_glib_full(ffi::g_format_size_full(size, flags.into_glib())) }
}

/// Gets a human-readable name for the application, as set by
/// g_set_application_name(). This name should be localized if
/// possible, and is intended for display to the user.  Contrast with
/// g_get_prgname(), which gets a non-localized name. If
/// g_set_application_name() has not been called, returns the result of
/// g_get_prgname() (which may be [`None`] if g_set_prgname() has also not
/// been called).
///
/// # Returns
///
/// human-readable application
///   name. May return [`None`]
#[doc(alias = "g_get_application_name")]
#[doc(alias = "get_application_name")]
pub fn application_name() -> Option<crate::GString> {
    unsafe { from_glib_none(ffi::g_get_application_name()) }
}

/// Gets the character set for the current locale.
///
/// # Returns
///
/// a newly allocated string containing the name
///     of the character set. This string must be freed with g_free().
#[doc(alias = "g_get_codeset")]
#[doc(alias = "get_codeset")]
pub fn codeset() -> crate::GString {
    unsafe { from_glib_full(ffi::g_get_codeset()) }
}

/// Obtains the character set used by the console attached to the process,
/// which is suitable for printing output to the terminal.
///
/// Usually this matches the result returned by g_get_charset(), but in
/// environments where the locale's character set does not match the encoding
/// of the console this function tries to guess a more suitable value instead.
///
/// On Windows the character set returned by this function is the
/// output code page used by the console associated with the calling process.
/// If the codepage can't be determined (for example because there is no
/// console attached) UTF-8 is assumed.
///
/// The return value is [`true`] if the locale's encoding is UTF-8, in that
/// case you can perhaps avoid calling g_convert().
///
/// The string returned in @charset is not allocated, and should not be
/// freed.
///
/// # Returns
///
/// [`true`] if the returned charset is UTF-8
///
/// ## `charset`
/// return location for character set
///   name, or [`None`].
#[cfg(feature = "v2_62")]
#[cfg_attr(docsrs, doc(cfg(feature = "v2_62")))]
#[doc(alias = "g_get_console_charset")]
#[doc(alias = "get_console_charset")]
pub fn console_charset() -> Option<crate::GString> {
    unsafe {
        let mut charset = std::ptr::null();
        let ret = from_glib(ffi::g_get_console_charset(&mut charset));
        if ret {
            Some(from_glib_none(charset))
        } else {
            None
        }
    }
}

/// Gets the current directory.
///
/// The returned string should be freed when no longer needed.
/// The encoding of the returned string is system defined.
/// On Windows, it is always UTF-8.
///
/// Since GLib 2.40, this function will return the value of the "PWD"
/// environment variable if it is set and it happens to be the same as
/// the current directory.  This can make a difference in the case that
/// the current directory is the target of a symbolic link.
///
/// # Returns
///
/// the current directory
#[doc(alias = "g_get_current_dir")]
#[doc(alias = "get_current_dir")]
pub fn current_dir() -> std::path::PathBuf {
    unsafe { from_glib_full(ffi::g_get_current_dir()) }
}

/// Gets the list of environment variables for the current process.
///
/// The list is [`None`] terminated and each item in the list is of the
/// form 'NAME=VALUE'.
///
/// This is equivalent to direct access to the 'environ' global variable,
/// except portable.
///
/// The return value is freshly allocated and it should be freed with
/// g_strfreev() when it is no longer needed.
///
/// # Returns
///
///
///     the list of environment variables
#[doc(alias = "g_get_environ")]
#[doc(alias = "get_environ")]
pub fn environ() -> Vec<std::ffi::OsString> {
    unsafe { FromGlibPtrContainer::from_glib_full(ffi::g_get_environ()) }
}

/// Gets the current user's home directory.
///
/// As with most UNIX tools, this function will return the value of the
/// `HOME` environment variable if it is set to an existing absolute path
/// name, falling back to the `passwd` file in the case that it is unset.
///
/// If the path given in `HOME` is non-absolute, does not exist, or is
/// not a directory, the result is undefined.
///
/// Before version 2.36 this function would ignore the `HOME` environment
/// variable, taking the value from the `passwd` database instead. This was
/// changed to increase the compatibility of GLib with other programs (and
/// the XDG basedir specification) and to increase testability of programs
/// based on GLib (by making it easier to run them from test frameworks).
///
/// If your program has a strong requirement for either the new or the
/// old behaviour (and if you don't wish to increase your GLib
/// dependency to ensure that the new behaviour is in effect) then you
/// should either directly check the `HOME` environment variable yourself
/// or unset it before calling any functions in GLib.
///
/// # Returns
///
/// the current user's home directory
#[doc(alias = "g_get_home_dir")]
#[doc(alias = "get_home_dir")]
pub fn home_dir() -> std::path::PathBuf {
    unsafe { from_glib_none(ffi::g_get_home_dir()) }
}

/// Return a name for the machine.
///
/// The returned name is not necessarily a fully-qualified domain name,
/// or even present in DNS or some other name service at all. It need
/// not even be unique on your local network or site, but usually it
/// is. Callers should not rely on the return value having any specific
/// properties like uniqueness for security purposes. Even if the name
/// of the machine is changed while an application is running, the
/// return value from this function does not change. The returned
/// string is owned by GLib and should not be modified or freed. If no
/// name can be determined, a default fixed string "localhost" is
/// returned.
///
/// The encoding of the returned string is UTF-8.
///
/// # Returns
///
/// the host name of the machine.
#[doc(alias = "g_get_host_name")]
#[doc(alias = "get_host_name")]
pub fn host_name() -> crate::GString {
    unsafe { from_glib_none(ffi::g_get_host_name()) }
}

/// Computes a list of applicable locale names, which can be used to
/// e.g. construct locale-dependent filenames or search paths. The returned
/// list is sorted from most desirable to least desirable and always contains
/// the default locale "C".
///
/// For example, if LANGUAGE=de:en_US, then the returned list is
/// "de", "en_US", "en", "C".
///
/// This function consults the environment variables `LANGUAGE`, `LC_ALL`,
/// `LC_MESSAGES` and `LANG` to find the list of locales specified by the
/// user.
///
/// # Returns
///
/// a [`None`]-terminated array of strings owned by GLib
///    that must not be modified or freed.
#[doc(alias = "g_get_language_names")]
#[doc(alias = "get_language_names")]
pub fn language_names() -> Vec<crate::GString> {
    unsafe { FromGlibPtrContainer::from_glib_none(ffi::g_get_language_names()) }
}

/// Computes a list of applicable locale names with a locale category name,
/// which can be used to construct the fallback locale-dependent filenames
/// or search paths. The returned list is sorted from most desirable to
/// least desirable and always contains the default locale "C".
///
/// This function consults the environment variables `LANGUAGE`, `LC_ALL`,
/// @category_name, and `LANG` to find the list of locales specified by the
/// user.
///
/// g_get_language_names() returns g_get_language_names_with_category("LC_MESSAGES").
/// ## `category_name`
/// a locale category name
///
/// # Returns
///
/// a [`None`]-terminated array of strings owned by
///    the thread g_get_language_names_with_category was called from.
///    It must not be modified or freed. It must be copied if planned to be used in another thread.
#[cfg(feature = "v2_58")]
#[cfg_attr(docsrs, doc(cfg(feature = "v2_58")))]
#[doc(alias = "g_get_language_names_with_category")]
#[doc(alias = "get_language_names_with_category")]
pub fn language_names_with_category(category_name: &str) -> Vec<crate::GString> {
    unsafe {
        FromGlibPtrContainer::from_glib_none(ffi::g_get_language_names_with_category(
            category_name.to_glib_none().0,
        ))
    }
}

/// Returns a list of derived variants of @locale, which can be used to
/// e.g. construct locale-dependent filenames or search paths. The returned
/// list is sorted from most desirable to least desirable.
/// This function handles territory, charset and extra locale modifiers. See
/// [`setlocale(3)`](man:setlocale) for information about locales and their format.
///
/// @locale itself is guaranteed to be returned in the output.
///
/// For example, if @locale is `fr_BE`, then the returned list
/// is `fr_BE`, `fr`. If @locale is `en_GB.UTF-8@euro`, then the returned list
/// is `en_GB.UTF-8@euro`, `en_GB.UTF-8`, `en_GB@euro`, `en_GB`, `en.UTF-8@euro`,
/// `en.UTF-8`, `en@euro`, `en`.
///
/// If you need the list of variants for the current locale,
/// use g_get_language_names().
/// ## `locale`
/// a locale identifier
///
/// # Returns
///
/// a newly
///   allocated array of newly allocated strings with the locale variants. Free with
///   g_strfreev().
#[doc(alias = "g_get_locale_variants")]
#[doc(alias = "get_locale_variants")]
pub fn locale_variants(locale: &str) -> Vec<crate::GString> {
    unsafe {
        FromGlibPtrContainer::from_glib_full(ffi::g_get_locale_variants(locale.to_glib_none().0))
    }
}

/// Queries the system monotonic time in microseconds.
///
/// The monotonic clock will always increase and doesn’t suffer
/// discontinuities when the user (or NTP) changes the system time.  It
/// may or may not continue to tick during times where the machine is
/// suspended.
///
/// We try to use the clock that corresponds as closely as possible to
/// the passage of time as measured by system calls such as
/// [`poll()`](man:poll(2)) but it
/// may not always be possible to do this.
///
/// A more accurate version of this function exists.
/// [`monotonic_time_ns()`][crate::monotonic_time_ns()] returns the time in nanoseconds.
///
/// # Returns
///
/// the monotonic time, in microseconds
#[doc(alias = "g_get_monotonic_time")]
#[doc(alias = "get_monotonic_time")]
pub fn monotonic_time() -> i64 {
    unsafe { ffi::g_get_monotonic_time() }
}

/// Queries the system monotonic time in nanoseconds.
///
/// The monotonic clock will always increase and doesn’t suffer
/// discontinuities when the user (or NTP) changes the system time.  It
/// may or may not continue to tick during times where the machine is
/// suspended.
///
/// We try to use the clock that corresponds as closely as possible to
/// the passage of time as measured by system calls such as
/// [`poll()`](man:poll(2)) but it
/// may not always be possible to do this.
///
/// Another version of this function exists.
/// [`monotonic_time()`][crate::monotonic_time()] returns the time in microseconds.
/// If you want to support older GLib versions, it is an alternative.
///
/// # Returns
///
/// the monotonic time, in nanoseconds
#[cfg(feature = "v2_88")]
#[cfg_attr(docsrs, doc(cfg(feature = "v2_88")))]
#[doc(alias = "g_get_monotonic_time_ns")]
#[doc(alias = "get_monotonic_time_ns")]
pub fn monotonic_time_ns() -> u64 {
    unsafe { ffi::g_get_monotonic_time_ns() }
}

/// Determine the approximate number of threads that the system will
/// schedule simultaneously for this process.  This is intended to be
/// used as a parameter to g_thread_pool_new() for CPU bound tasks and
/// similar cases.
///
/// On platforms where enough information is known, this will be the number of
/// high performance cores and will not include low power ‘efficiency’ cores.
/// Use platform specific APIs to query for low power cores if needed.
///
/// # Returns
///
/// Number of schedulable threads, always greater than 0
#[doc(alias = "g_get_num_processors")]
#[doc(alias = "get_num_processors")]
pub fn num_processors() -> u32 {
    unsafe { ffi::g_get_num_processors() }
}

/// Get information about the operating system.
///
/// On Linux this comes from the `/etc/os-release` file. On other systems, it may
/// come from a variety of sources. You can either use the standard key names
/// like `G_OS_INFO_KEY_NAME` or pass any UTF-8 string key name. For example,
/// `/etc/os-release` provides a number of other less commonly used values that may
/// be useful. No key is guaranteed to be provided, so the caller should always
/// check if the result is [`None`].
/// ## `key_name`
/// a key for the OS info being requested, for example `G_OS_INFO_KEY_NAME`.
///
/// # Returns
///
/// The associated value for the requested key or [`None`] if
///   this information is not provided.
#[cfg(feature = "v2_64")]
#[cfg_attr(docsrs, doc(cfg(feature = "v2_64")))]
#[doc(alias = "g_get_os_info")]
#[doc(alias = "get_os_info")]
pub fn os_info(key_name: &str) -> Option<crate::GString> {
    unsafe { from_glib_full(ffi::g_get_os_info(key_name.to_glib_none().0)) }
}

/// Gets the real name of the user. This usually comes from the user's
/// entry in the `passwd` file. The encoding of the returned string is
/// system-defined. (On Windows, it is, however, always UTF-8.) If the
/// real user name cannot be determined, the string "Unknown" is
/// returned.
///
/// # Returns
///
/// the user's real name.
#[doc(alias = "g_get_real_name")]
#[doc(alias = "get_real_name")]
pub fn real_name() -> std::ffi::OsString {
    unsafe { from_glib_none(ffi::g_get_real_name()) }
}

/// Queries the system wall-clock time.
///
/// This is equivalent to the UNIX [`gettimeofday()`](man:gettimeofday(2))
/// function, but portable.
///
/// You should only use this call if you are actually interested in the real
/// wall-clock time. [`monotonic_time()`][crate::monotonic_time()] is probably more useful for
/// measuring intervals.
///
/// # Returns
///
/// the number of microseconds since
///   [January 1, 1970 UTC](https://en.wikipedia.org/wiki/Unix_time)
#[doc(alias = "g_get_real_time")]
#[doc(alias = "get_real_time")]
pub fn real_time() -> i64 {
    unsafe { ffi::g_get_real_time() }
}

/// Returns an ordered list of base directories in which to access
/// system-wide configuration information.
///
/// On UNIX platforms this is determined using the mechanisms described
/// in the
/// [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
/// In this case the list of directories retrieved will be `XDG_CONFIG_DIRS`.
///
/// On Windows it follows XDG Base Directory Specification if `XDG_CONFIG_DIRS` is defined.
/// If `XDG_CONFIG_DIRS` is undefined, the directory that contains application
/// data for all users is used instead. A typical path is
/// `C:\Documents and Settings\All Users\Application Data`.
/// This folder is used for application data
/// that is not user specific. For example, an application can store
/// a spell-check dictionary, a database of clip art, or a log file in the
/// FOLDERID_ProgramData folder. This information will not roam and is available
/// to anyone using the computer.
///
/// The return value is cached and modifying it at runtime is not supported, as
/// it’s not thread-safe to modify environment variables at runtime.
///
/// # Returns
///
///
///     a [`None`]-terminated array of strings owned by GLib that must not be
///     modified or freed.
#[doc(alias = "g_get_system_config_dirs")]
#[doc(alias = "get_system_config_dirs")]
pub fn system_config_dirs() -> Vec<std::path::PathBuf> {
    unsafe { FromGlibPtrContainer::from_glib_none(ffi::g_get_system_config_dirs()) }
}

/// Returns an ordered list of base directories in which to access
/// system-wide application data.
///
/// On UNIX platforms this is determined using the mechanisms described
/// in the
/// [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec)
/// In this case the list of directories retrieved will be `XDG_DATA_DIRS`.
///
/// On Windows it follows XDG Base Directory Specification if `XDG_DATA_DIRS` is defined.
/// If `XDG_DATA_DIRS` is undefined,
/// the first elements in the list are the Application Data
/// and Documents folders for All Users. (These can be determined only
/// on Windows 2000 or later and are not present in the list on other
/// Windows versions.) See documentation for FOLDERID_ProgramData and
/// FOLDERID_PublicDocuments.
///
/// Then follows the "share" subfolder in the installation folder for
/// the package containing the DLL that calls this function, if it can
/// be determined.
///
/// Finally the list contains the "share" subfolder in the installation
/// folder for GLib, and in the installation folder for the package the
/// application's .exe file belongs to.
///
/// The installation folders above are determined by looking up the
/// folder where the module (DLL or EXE) in question is located. If the
/// folder's name is "bin", its parent is used, otherwise the folder
/// itself.
///
/// Note that on Windows the returned list can vary depending on where
/// this function is called.
///
/// The return value is cached and modifying it at runtime is not supported, as
/// it’s not thread-safe to modify environment variables at runtime.
///
/// # Returns
///
///
///     a [`None`]-terminated array of strings owned by GLib that must not be
///     modified or freed.
#[doc(alias = "g_get_system_data_dirs")]
#[doc(alias = "get_system_data_dirs")]
pub fn system_data_dirs() -> Vec<std::path::PathBuf> {
    unsafe { FromGlibPtrContainer::from_glib_none(ffi::g_get_system_data_dirs()) }
}

/// Gets the directory to use for temporary files.
///
/// On UNIX, this is taken from the `TMPDIR` environment variable.
/// If the variable is not set, `P_tmpdir` is
/// used, as defined by the system C library. Failing that, a
/// hard-coded default of "/tmp" is returned.
///
/// On Windows, the `TEMP` environment variable is used, with the
/// root directory of the Windows installation (eg: "C:\") used
/// as a default.
///
/// The encoding of the returned string is system-defined. On Windows,
/// it is always UTF-8. The return value is never [`None`] or the empty
/// string.
///
/// # Returns
///
/// the directory to use for temporary files.
#[doc(alias = "g_get_tmp_dir")]
#[doc(alias = "get_tmp_dir")]
pub fn tmp_dir() -> std::path::PathBuf {
    unsafe { from_glib_none(ffi::g_get_tmp_dir()) }
}

/// Returns a base directory in which to store non-essential, cached
/// data specific to particular user.
///
/// On UNIX platforms this is determined using the mechanisms described
/// in the
/// [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
/// In this case the directory retrieved will be `XDG_CACHE_HOME`.
///
/// On Windows it follows XDG Base Directory Specification if `XDG_CACHE_HOME` is defined.
/// If `XDG_CACHE_HOME` is undefined, the directory that serves as a common
/// repository for temporary Internet files is used instead. A typical path is
/// `C:\Documents and Settings\username\Local Settings\Temporary Internet Files`.
/// See the [documentation for `FOLDERID_InternetCache`](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid).
///
/// The return value is cached and modifying it at runtime is not supported, as
/// it’s not thread-safe to modify environment variables at runtime.
///
/// # Returns
///
/// a string owned by GLib that
///   must not be modified or freed.
#[doc(alias = "g_get_user_cache_dir")]
#[doc(alias = "get_user_cache_dir")]
pub fn user_cache_dir() -> std::path::PathBuf {
    unsafe { from_glib_none(ffi::g_get_user_cache_dir()) }
}

/// Returns a base directory in which to store user-specific application
/// configuration information such as user preferences and settings.
///
/// On UNIX platforms this is determined using the mechanisms described
/// in the
/// [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
/// In this case the directory retrieved will be `XDG_CONFIG_HOME`.
///
/// On Windows it follows XDG Base Directory Specification if `XDG_CONFIG_HOME` is defined.
/// If `XDG_CONFIG_HOME` is undefined, the folder to use for local (as opposed
/// to roaming) application data is used instead. See the
/// [documentation for `FOLDERID_LocalAppData`](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid).
/// Note that in this case on Windows it will be  the same
/// as what g_get_user_data_dir() returns.
///
/// The return value is cached and modifying it at runtime is not supported, as
/// it’s not thread-safe to modify environment variables at runtime.
///
/// # Returns
///
/// a string owned by GLib that
///   must not be modified or freed.
#[doc(alias = "g_get_user_config_dir")]
#[doc(alias = "get_user_config_dir")]
pub fn user_config_dir() -> std::path::PathBuf {
    unsafe { from_glib_none(ffi::g_get_user_config_dir()) }
}

/// Returns a base directory in which to access application data such
/// as icons that is customized for a particular user.
///
/// On UNIX platforms this is determined using the mechanisms described
/// in the
/// [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
/// In this case the directory retrieved will be `XDG_DATA_HOME`.
///
/// On Windows it follows XDG Base Directory Specification if `XDG_DATA_HOME`
/// is defined. If `XDG_DATA_HOME` is undefined, the folder to use for local (as
/// opposed to roaming) application data is used instead. See the
/// [documentation for `FOLDERID_LocalAppData`](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid).
/// Note that in this case on Windows it will be the same
/// as what g_get_user_config_dir() returns.
///
/// The return value is cached and modifying it at runtime is not supported, as
/// it’s not thread-safe to modify environment variables at runtime.
///
/// # Returns
///
/// a string owned by GLib that must
///   not be modified or freed.
#[doc(alias = "g_get_user_data_dir")]
#[doc(alias = "get_user_data_dir")]
pub fn user_data_dir() -> std::path::PathBuf {
    unsafe { from_glib_none(ffi::g_get_user_data_dir()) }
}

/// Gets the user name of the current user. The encoding of the returned
/// string is system-defined. On UNIX, it might be the preferred file name
/// encoding, or something else, and there is no guarantee that it is even
/// consistent on a machine. On Windows, it is always UTF-8.
///
/// # Returns
///
/// the user name of the current user.
#[doc(alias = "g_get_user_name")]
#[doc(alias = "get_user_name")]
pub fn user_name() -> std::ffi::OsString {
    unsafe { from_glib_none(ffi::g_get_user_name()) }
}

/// Returns a directory that is unique to the current user on the local
/// system.
///
/// This is determined using the mechanisms described
/// in the
/// [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
/// This is the directory
/// specified in the `XDG_RUNTIME_DIR` environment variable.
/// In the case that this variable is not set, we return the value of
/// g_get_user_cache_dir(), after verifying that it exists.
///
/// The return value is cached and modifying it at runtime is not supported, as
/// it’s not thread-safe to modify environment variables at runtime.
///
/// # Returns
///
/// a string owned by GLib that must not be
///     modified or freed.
#[doc(alias = "g_get_user_runtime_dir")]
#[doc(alias = "get_user_runtime_dir")]
pub fn user_runtime_dir() -> std::path::PathBuf {
    unsafe { from_glib_none(ffi::g_get_user_runtime_dir()) }
}

/// Returns the full path of a special directory using its logical id.
///
/// On UNIX this is done using the XDG special user directories.
/// For compatibility with existing practise, [`UserDirectory::DirectoryDesktop`][crate::UserDirectory::DirectoryDesktop]
/// falls back to `$HOME/Desktop` when XDG special user directories have
/// not been set up.
///
/// Depending on the platform, the user might be able to change the path
/// of the special directory without requiring the session to restart; GLib
/// will not reflect any change once the special directories are loaded.
/// ## `directory`
/// the logical id of special directory
///
/// # Returns
///
/// the path to the specified special
///   directory, or [`None`] if the logical id was not found. The returned string is
///   owned by GLib and should not be modified or freed.
#[doc(alias = "g_get_user_special_dir")]
#[doc(alias = "get_user_special_dir")]
pub fn user_special_dir(directory: UserDirectory) -> Option<std::path::PathBuf> {
    unsafe { from_glib_none(ffi::g_get_user_special_dir(directory.into_glib())) }
}

/// Returns a base directory in which to store state files specific to
/// particular user.
///
/// On UNIX platforms this is determined using the mechanisms described
/// in the
/// [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
/// In this case the directory retrieved will be `XDG_STATE_HOME`.
///
/// On Windows it follows XDG Base Directory Specification if `XDG_STATE_HOME` is defined.
/// If `XDG_STATE_HOME` is undefined, the folder to use for local (as opposed
/// to roaming) application data is used instead. See the
/// [documentation for `FOLDERID_LocalAppData`](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid).
/// Note that in this case on Windows it will be the same
/// as what g_get_user_data_dir() returns.
///
/// The return value is cached and modifying it at runtime is not supported, as
/// it’s not thread-safe to modify environment variables at runtime.
///
/// # Returns
///
/// a string owned by GLib that
///   must not be modified or freed.
#[cfg(feature = "v2_72")]
#[cfg_attr(docsrs, doc(cfg(feature = "v2_72")))]
#[doc(alias = "g_get_user_state_dir")]
#[doc(alias = "get_user_state_dir")]
pub fn user_state_dir() -> std::path::PathBuf {
    unsafe { from_glib_none(ffi::g_get_user_state_dir()) }
}

/// Returns the value of an environment variable.
///
/// On UNIX, the name and value are byte strings which might or might not
/// be in some consistent character set and encoding. On Windows, they are
/// in UTF-8.
/// On Windows, in case the environment variable's value contains
/// references to other environment variables, they are expanded.
/// ## `variable`
/// the environment variable to get
///
/// # Returns
///
/// the value of the environment variable, or [`None`] if
///     the environment variable is not found. The returned string
///     may be overwritten by the next call to g_getenv(), g_setenv()
///     or g_unsetenv().
#[doc(alias = "g_getenv")]
pub fn getenv(variable: impl AsRef<std::ffi::OsStr>) -> Option<std::ffi::OsString> {
    unsafe { from_glib_none(ffi::g_getenv(variable.as_ref().to_glib_none().0)) }
}

/// Tests if @hostname contains segments with an ASCII-compatible
/// encoding of an Internationalized Domain Name. If this returns
/// [`true`], you should decode the hostname with g_hostname_to_unicode()
/// before displaying it to the user.
///
/// Note that a hostname might contain a mix of encoded and unencoded
/// segments, and so it is possible for g_hostname_is_non_ascii() and
/// g_hostname_is_ascii_encoded() to both return [`true`] for a name.
/// ## `hostname`
/// a hostname
///
/// # Returns
///
/// [`true`] if @hostname contains any ASCII-encoded
/// segments.
#[doc(alias = "g_hostname_is_ascii_encoded")]
pub fn hostname_is_ascii_encoded(hostname: &str) -> bool {
    unsafe { from_glib(ffi::g_hostname_is_ascii_encoded(hostname.to_glib_none().0)) }
}

/// Tests if @hostname is the string form of an IPv4 or IPv6 address.
/// (Eg, "192.168.0.1".)
///
/// Since 2.66, IPv6 addresses with a zone-id are accepted (RFC6874).
/// ## `hostname`
/// a hostname (or IP address in string form)
///
/// # Returns
///
/// [`true`] if @hostname is an IP address
#[doc(alias = "g_hostname_is_ip_address")]
pub fn hostname_is_ip_address(hostname: &str) -> bool {
    unsafe { from_glib(ffi::g_hostname_is_ip_address(hostname.to_glib_none().0)) }
}

/// Tests if @hostname contains Unicode characters. If this returns
/// [`true`], you need to encode the hostname with g_hostname_to_ascii()
/// before using it in non-IDN-aware contexts.
///
/// Note that a hostname might contain a mix of encoded and unencoded
/// segments, and so it is possible for g_hostname_is_non_ascii() and
/// g_hostname_is_ascii_encoded() to both return [`true`] for a name.
/// ## `hostname`
/// a hostname
///
/// # Returns
///
/// [`true`] if @hostname contains any non-ASCII characters
#[doc(alias = "g_hostname_is_non_ascii")]
pub fn hostname_is_non_ascii(hostname: &str) -> bool {
    unsafe { from_glib(ffi::g_hostname_is_non_ascii(hostname.to_glib_none().0)) }
}

/// Converts @hostname to its canonical ASCII form; an ASCII-only
/// string containing no uppercase letters and not ending with a
/// trailing dot.
/// ## `hostname`
/// a valid UTF-8 or ASCII hostname
///
/// # Returns
///
/// an ASCII hostname, which must be freed,
///    or [`None`] if @hostname is in some way invalid.
#[doc(alias = "g_hostname_to_ascii")]
pub fn hostname_to_ascii(hostname: &str) -> Option<crate::GString> {
    unsafe { from_glib_full(ffi::g_hostname_to_ascii(hostname.to_glib_none().0)) }
}

/// Converts @hostname to its canonical presentation form; a UTF-8
/// string in Unicode normalization form C, containing no uppercase
/// letters, no forbidden characters, and no ASCII-encoded segments,
/// and not ending with a trailing dot.
///
/// Of course if @hostname is not an internationalized hostname, then
/// the canonical presentation form will be entirely ASCII.
/// ## `hostname`
/// a valid UTF-8 or ASCII hostname
///
/// # Returns
///
/// a UTF-8 hostname, which must be freed,
///    or [`None`] if @hostname is in some way invalid.
#[doc(alias = "g_hostname_to_unicode")]
pub fn hostname_to_unicode(hostname: &str) -> Option<crate::GString> {
    unsafe { from_glib_full(ffi::g_hostname_to_unicode(hostname.to_glib_none().0)) }
}

/// Gets the names of all variables set in the environment.
///
/// Programs that want to be portable to Windows should typically use
/// this function and g_getenv() instead of using the environ array
/// from the C library directly. On Windows, the strings in the environ
/// array are in system codepage encoding, while in most of the typical
/// use cases for environment variables in GLib-using programs you want
/// the UTF-8 encoding that this function and g_getenv() provide.
///
/// # Returns
///
///
///     a [`None`]-terminated list of strings which must be freed with
///     g_strfreev().
#[doc(alias = "g_listenv")]
pub fn listenv() -> Vec<std::ffi::OsString> {
    unsafe { FromGlibPtrContainer::from_glib_full(ffi::g_listenv()) }
}

/// Returns the currently firing source for this thread.
///
/// # Returns
///
/// the currently firing source, or `NULL`
///   if none is firing
#[doc(alias = "g_main_current_source")]
pub fn main_current_source() -> Option<Source> {
    unsafe { from_glib_none(ffi::g_main_current_source()) }
}

/// Returns the depth of the stack of calls to
/// [`MainContext::dispatch()`][crate::MainContext::dispatch()] on any #GMainContext in the current thread.
///
/// That is, when called from the top level, it gives `0`. When
/// called from within a callback from [`MainContext::iteration()`][crate::MainContext::iteration()]
/// (or [`MainLoop::run()`][crate::MainLoop::run()], etc.) it returns `1`. When called from within
/// a callback to a recursive call to [`MainContext::iteration()`][crate::MainContext::iteration()],
/// it returns `2`. And so forth.
///
/// This function is useful in a situation like the following:
/// Imagine an extremely simple ‘garbage collected’ system.
///
/// **⚠️ The following code is in c ⚠️**
///
/// ```c
/// static GList *free_list;
///
/// gpointer
/// allocate_memory (gsize size)
/// {
///   gpointer result = g_malloc (size);
///   free_list = g_list_prepend (free_list, result);
///   return result;
/// }
///
/// void
/// free_allocated_memory (void)
/// {
///   GList *l;
///   for (l = free_list; l; l = l->next);
///     g_free (l->data);
///   g_list_free (free_list);
///   free_list = NULL;
///  }
///
/// [...]
///
/// while (TRUE);
///  {
///    g_main_context_iteration (NULL, TRUE);
///    free_allocated_memory();
///   }
/// ```
///
/// This works from an application, however, if you want to do the same
/// thing from a library, it gets more difficult, since you no longer
/// control the main loop. You might think you can simply use an idle
/// function to make the call to `free_allocated_memory()`, but that
/// doesn’t work, since the idle function could be called from a
/// recursive callback. This can be fixed by using [`main_depth()`][crate::main_depth()]
///
/// **⚠️ The following code is in c ⚠️**
///
/// ```c
/// gpointer
/// allocate_memory (gsize size)
/// {
///   FreeListBlock *block = g_new (FreeListBlock, 1);
///   block->mem = g_malloc (size);
///   block->depth = g_main_depth ();
///   free_list = g_list_prepend (free_list, block);
///   return block->mem;
/// }
///
/// void
/// free_allocated_memory (void)
/// {
///   GList *l;
///
///   int depth = g_main_depth ();
///   for (l = free_list; l; );
///     {
///       GList *next = l->next;
///       FreeListBlock *block = l->data;
///       if (block->depth > depth)
///         {
///           g_free (block->mem);
///           g_free (block);
///           free_list = g_list_delete_link (free_list, l);
///         }
///
///       l = next;
///     }
///   }
/// ```
///
/// There is a temptation to use [`main_depth()`][crate::main_depth()] to solve
/// problems with reentrancy. For instance, while waiting for data
/// to be received from the network in response to a menu item,
/// the menu item might be selected again. It might seem that
/// one could make the menu item’s callback return immediately
/// and do nothing if [`main_depth()`][crate::main_depth()] returns a value greater than 1.
/// However, this should be avoided since the user then sees selecting
/// the menu item do nothing. Furthermore, you’ll find yourself adding
/// these checks all over your code, since there are doubtless many,
/// many things that the user could do. Instead, you can use the
/// following techniques:
///
/// 1. Use `gtk_widget_set_sensitive()` or modal dialogs to prevent
///    the user from interacting with elements while the main
///    loop is recursing.
///
/// 2. Avoid main loop recursion in situations where you can’t handle
///    arbitrary  callbacks. Instead, structure your code so that you
///    simply return to the main loop and then get called again when
///    there is more work to do.
///
/// # Returns
///
/// the main loop recursion level in the current thread
#[doc(alias = "g_main_depth")]
pub fn main_depth() -> i32 {
    unsafe { ffi::g_main_depth() }
}

/// Escapes text so that the markup parser will parse it verbatim.
/// Less than, greater than, ampersand, etc. are replaced with the
/// corresponding entities. This function would typically be used
/// when writing out a file to be parsed with the markup parser.
///
/// Note that this function doesn't protect whitespace and line endings
/// from being processed according to the XML rules for normalization
/// of line endings and attribute values.
///
/// Note also that this function will produce character references in
/// the range of &#x1; ... &#x1f; for all control sequences
/// except for tabstop, newline and carriage return.  The character
/// references in this range are not valid XML 1.0, but they are
/// valid XML 1.1 and will be accepted by the GMarkup parser.
/// ## `text`
/// some valid UTF-8 text
/// ## `length`
/// length of @text in bytes, or -1 if the text is nul-terminated
///
/// # Returns
///
/// a newly allocated string with the escaped text
#[doc(alias = "g_markup_escape_text")]
pub fn markup_escape_text(text: &str) -> crate::GString {
    let length = text.len() as _;
    unsafe { from_glib_full(ffi::g_markup_escape_text(text.to_glib_none().0, length)) }
}

/// Create a directory if it doesn't already exist. Create intermediate
/// parent directories as needed, too.
/// ## `pathname`
/// a pathname in the GLib file name encoding
/// ## `mode`
/// permissions to use for newly created directories
///
/// # Returns
///
/// 0 if the directory already exists, or was successfully
/// created. Returns -1 if an error occurred, with errno set.
#[doc(alias = "g_mkdir_with_parents")]
pub fn mkdir_with_parents(pathname: impl AsRef<std::path::Path>, mode: i32) -> i32 {
    unsafe { ffi::g_mkdir_with_parents(pathname.as_ref().to_glib_none().0, mode) }
}

/// Prompts the user with
/// `[E]xit, [H]alt, show [S]tack trace or [P]roceed`.
/// This function is intended to be used for debugging use only.
/// The following example shows how it can be used together with
/// the g_log() functions.
///
///
///
/// **⚠️ The following code is in C ⚠️**
///
/// ```C
/// #include <glib.h>
///
/// static void
/// log_handler (const gchar   *log_domain,
///              GLogLevelFlags log_level,
///              const gchar   *message,
///              gpointer       user_data)
/// {
///   g_log_default_handler (log_domain, log_level, message, user_data);
///
///   g_on_error_query (MY_PROGRAM_NAME);
/// }
///
/// int
/// main (int argc, char *argv[])
/// {
///   g_log_set_handler (MY_LOG_DOMAIN,
///                      G_LOG_LEVEL_WARNING |
///                      G_LOG_LEVEL_ERROR |
///                      G_LOG_LEVEL_CRITICAL,
///                      log_handler,
///                      NULL);
///   ...
/// ```
///
/// If "[E]xit" is selected, the application terminates with a call
/// to _exit(0).
///
/// If "[S]tack" trace is selected, g_on_error_stack_trace() is called.
/// This invokes gdb, which attaches to the current process and shows
/// a stack trace. The prompt is then shown again.
///
/// If "[P]roceed" is selected, the function returns.
///
/// This function may cause different actions on non-UNIX platforms.
///
/// On Windows consider using the `G_DEBUGGER` environment
/// variable (see [Running GLib Applications](running.html)) and
/// calling g_on_error_stack_trace() instead.
/// ## `prg_name`
/// the program name, needed by gdb for the "[S]tack trace"
///     option. If @prg_name is [`None`], g_get_prgname() is called to get
///     the program name (which will work correctly if gdk_init() or
///     gtk_init() has been called)
#[doc(alias = "g_on_error_query")]
pub fn on_error_query(prg_name: &str) {
    unsafe {
        ffi::g_on_error_query(prg_name.to_glib_none().0);
    }
}

/// Invokes gdb, which attaches to the current process and shows a
/// stack trace. Called by g_on_error_query() when the "[S]tack trace"
/// option is selected. You can get the current process's program name
/// with g_get_prgname(), assuming that you have called gtk_init() or
/// gdk_init().
///
/// This function may cause different actions on non-UNIX platforms.
///
/// When running on Windows, this function is *not* called by
/// g_on_error_query(). If called directly, it will raise an
/// exception, which will crash the program. If the `G_DEBUGGER` environment
/// variable is set, a debugger will be invoked to attach and
/// handle that exception (see [Running GLib Applications](running.html)).
/// ## `prg_name`
/// the program name, needed by gdb for the
///   "[S]tack trace" option, or `NULL` to use a default string
#[doc(alias = "g_on_error_stack_trace")]
pub fn on_error_stack_trace(prg_name: Option<&str>) {
    unsafe {
        ffi::g_on_error_stack_trace(prg_name.to_glib_none().0);
    }
}

/// Gets the last component of the filename.
///
/// If @file_name ends with a directory separator it gets the component
/// before the last slash. If @file_name consists only of directory
/// separators (and on Windows, possibly a drive letter), a single
/// separator is returned. If @file_name is empty, it gets ".".
/// ## `file_name`
/// the name of the file
///
/// # Returns
///
/// a newly allocated string
///   containing the last component of the filename
#[doc(alias = "g_path_get_basename")]
#[allow(dead_code)]
pub(crate) fn path_get_basename(file_name: impl AsRef<std::path::Path>) -> std::path::PathBuf {
    unsafe {
        from_glib_full(ffi::g_path_get_basename(
            file_name.as_ref().to_glib_none().0,
        ))
    }
}

/// Gets the directory components of a file name. For example, the directory
/// component of `/usr/bin/test` is `/usr/bin`. The directory component of `/`
/// is `/`.
///
/// If the file name has no directory components "." is returned.
/// The returned string should be freed when no longer needed.
/// ## `file_name`
/// the name of the file
///
/// # Returns
///
/// the directory components of the file
#[doc(alias = "g_path_get_dirname")]
#[allow(dead_code)]
pub(crate) fn path_get_dirname(file_name: impl AsRef<std::path::Path>) -> std::path::PathBuf {
    unsafe { from_glib_full(ffi::g_path_get_dirname(file_name.as_ref().to_glib_none().0)) }
}

//#[doc(alias = "g_poll")]
//pub fn poll(fds: /*Ignored*/&mut PollFD, nfds: u32, timeout: i32) -> i32 {
//    unsafe { TODO: call ffi:g_poll() }
//}

/// Returns a random #gdouble equally distributed over the range [0..1).
///
/// # Returns
///
/// a random number
#[doc(alias = "g_random_double")]
pub fn random_double() -> f64 {
    unsafe { ffi::g_random_double() }
}

/// Returns a random #gdouble equally distributed over the range
/// [@begin..@end).
/// ## `begin`
/// lower closed bound of the interval
/// ## `end`
/// upper open bound of the interval
///
/// # Returns
///
/// a random number
#[doc(alias = "g_random_double_range")]
pub fn random_double_range(begin: f64, end: f64) -> f64 {
    unsafe { ffi::g_random_double_range(begin, end) }
}

/// Return a random #guint32 equally distributed over the range
/// [0..2^32-1].
///
/// # Returns
///
/// a random number
#[doc(alias = "g_random_int")]
pub fn random_int() -> u32 {
    unsafe { ffi::g_random_int() }
}

/// Returns a random #gint32 equally distributed over the range
/// [@begin..@end-1].
/// ## `begin`
/// lower closed bound of the interval
/// ## `end`
/// upper open bound of the interval
///
/// # Returns
///
/// a random number
#[doc(alias = "g_random_int_range")]
pub fn random_int_range(begin: i32, end: i32) -> i32 {
    unsafe { ffi::g_random_int_range(begin, end) }
}

/// Sets the seed for the global random number generator, which is used
/// by the g_random_* functions, to @seed.
/// ## `seed`
/// a value to reinitialize the global random number generator
#[doc(alias = "g_random_set_seed")]
pub fn random_set_seed(seed: u32) {
    unsafe {
        ffi::g_random_set_seed(seed);
    }
}

/// Resets the cache used for g_get_user_special_dir(), so
/// that the latest on-disk version is used. Call this only
/// if you just changed the data on disk yourself.
///
/// Due to thread safety issues this may cause leaking of strings
/// that were previously returned from g_get_user_special_dir()
/// that can't be freed. We ensure to only leak the data for
/// the directories that actually changed value though.
#[doc(alias = "g_reload_user_special_dirs_cache")]
pub fn reload_user_special_dirs_cache() {
    unsafe {
        ffi::g_reload_user_special_dirs_cache();
    }
}

/// Sets a human-readable name for the application. This name should be
/// localized if possible, and is intended for display to the user.
/// Contrast with g_set_prgname(), which sets a non-localized name.
/// g_set_prgname() will be called automatically by gtk_init(),
/// but g_set_application_name() will not.
///
/// Note that for thread safety reasons, this function can only
/// be called once.
///
/// The application name will be used in contexts such as error messages,
/// or when displaying an application's name in the task list.
/// ## `application_name`
/// localized name of the application
#[doc(alias = "g_set_application_name")]
pub fn set_application_name(application_name: &str) {
    unsafe {
        ffi::g_set_application_name(application_name.to_glib_none().0);
    }
}

/// Sets an environment variable. On UNIX, both the variable's name and
/// value can be arbitrary byte strings, except that the variable's name
/// cannot contain '='. On Windows, they should be in UTF-8.
///
/// Note that on some systems, when variables are overwritten, the memory
/// used for the previous variables and its value isn't reclaimed.
///
/// You should be mindful of the fact that environment variable handling
/// in UNIX is not thread-safe, and your program may crash if one thread
/// calls g_setenv() while another thread is calling getenv(). (And note
/// that many functions, such as gettext(), call getenv() internally.)
/// This function is only safe to use at the very start of your program,
/// before creating any other threads (or creating objects that create
/// worker threads of their own).
///
/// If you need to set up the environment for a child process, you can
/// use g_get_environ() to get an environment array, modify that with
/// g_environ_setenv() and g_environ_unsetenv(), and then pass that
/// array directly to execvpe(), g_spawn_async(), or the like.
/// ## `variable`
/// the environment variable to set, must not
///     contain '='.
/// ## `value`
/// the value for to set the variable to.
/// ## `overwrite`
/// whether to change the variable if it already exists.
///
/// # Returns
///
/// [`false`] if the environment variable couldn't be set.
#[doc(alias = "g_setenv")]
pub unsafe fn setenv(
    variable: impl AsRef<std::ffi::OsStr>,
    value: impl AsRef<std::ffi::OsStr>,
    overwrite: bool,
) -> Result<(), crate::error::BoolError> {
    unsafe {
        crate::result_from_gboolean!(
            ffi::g_setenv(
                variable.as_ref().to_glib_none().0,
                value.as_ref().to_glib_none().0,
                overwrite.into_glib()
            ),
            "Failed to set environment variable"
        )
    }
}

/// Parses a command line into an argument vector, in much the same way
/// the shell would, but without many of the expansions the shell would
/// perform (variable expansion, globs, operators, filename expansion,
/// etc. are not supported).
///
/// The results are defined to be the same as those you would get from
/// a UNIX98 `/bin/sh`, as long as the input contains none of the
/// unsupported shell expansions. If the input does contain such expansions,
/// they are passed through literally.
///
/// Possible errors are those from the `G_SHELL_ERROR` domain.
///
/// In particular, if @command_line is an empty string (or a string containing
/// only whitespace), `G_SHELL_ERROR_EMPTY_STRING` will be returned. It’s
/// guaranteed that @argvp will be a non-empty array if this function returns
/// successfully.
///
/// When constructing @command_line, quote any filenames or potentially
/// untrusted input using [`shell_quote()`][crate::shell_quote()].
///
/// Free the returned vector with g_strfreev().
/// ## `command_line`
/// command line to parse
///
/// # Returns
///
/// [`true`] on success, [`false`] if error set
///
/// ## `argvp`
///
///   return location for array of args
#[doc(alias = "g_shell_parse_argv")]
pub fn shell_parse_argv(
    command_line: impl AsRef<std::ffi::OsStr>,
) -> Result<Vec<std::ffi::OsString>, crate::Error> {
    unsafe {
        let mut argcp = std::mem::MaybeUninit::uninit();
        let mut argvp = std::ptr::null_mut();
        let mut error = std::ptr::null_mut();
        let is_ok = ffi::g_shell_parse_argv(
            command_line.as_ref().to_glib_none().0,
            argcp.as_mut_ptr(),
            &mut argvp,
            &mut error,
        );
        debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
        if error.is_null() {
            Ok(FromGlibContainer::from_glib_full_num(
                argvp,
                argcp.assume_init() as _,
            ))
        } else {
            Err(from_glib_full(error))
        }
    }
}

/// Quotes a string so that the shell (/bin/sh) will interpret the
/// quoted string to mean @unquoted_string.
///
/// If you pass a filename or other untrusted input to [`shell_parse_argv()`][crate::shell_parse_argv()],
/// you should first quote it with this function. This is sufficient to ensure
/// untrusted input cannot ‘break out’ of the quotes. Beware: this only works
/// because [`shell_parse_argv()`][crate::shell_parse_argv()] is not a real Unix shell. Quoting untrusted
/// input is not an adequate security mechanism when using a real shell.
///
/// The return value must be freed with g_free().
///
/// The quoting style used is undefined (single or double quotes may be
/// used).
/// ## `unquoted_string`
/// a literal string
///
/// # Returns
///
/// quoted string
#[doc(alias = "g_shell_quote")]
pub fn shell_quote(unquoted_string: impl AsRef<std::ffi::OsStr>) -> std::ffi::OsString {
    unsafe {
        from_glib_full(ffi::g_shell_quote(
            unquoted_string.as_ref().to_glib_none().0,
        ))
    }
}

/// Unquotes a string as the shell (/bin/sh) would.
///
/// This function only handles quotes; if a string contains file globs,
/// arithmetic operators, variables, backticks, redirections, or other
/// special-to-the-shell features, the result will be different from the
/// result a real shell would produce (the variables, backticks, etc.
/// will be passed through literally instead of being expanded).
///
/// This function is guaranteed to succeed if applied to the result of
/// g_shell_quote(). If it fails, it returns [`None`] and sets the
/// error.
///
/// The @quoted_string need not actually contain quoted or escaped text;
/// g_shell_unquote() simply goes through the string and unquotes/unescapes
/// anything that the shell would. Both single and double quotes are
/// handled, as are escapes including escaped newlines.
///
/// The return value must be freed with g_free().
///
/// Possible errors are in the `G_SHELL_ERROR` domain.
///
/// Shell quoting rules are a bit strange. Single quotes preserve the
/// literal string exactly. escape sequences are not allowed; not even
/// `\'` - if you want a `'` in the quoted text, you have to do something
/// like `'foo'\''bar'`. Double quotes allow `$`, **⚠️ The following code is in , `"`, `\`, and ⚠️**
///
/// ```, `"`, `\`, and
/// newline to be escaped with backslash. Otherwise double quotes
/// preserve things literally.
/// ## `quoted_string`
/// shell-quoted string
///
/// # Returns
///
/// an unquoted string
#[doc(alias = "g_shell_unquote")]
pub fn shell_unquote(
    quoted_string: impl AsRef<std::ffi::OsStr>,
) -> Result<std::ffi::OsString, crate::Error> {
    unsafe {
        let mut error = std::ptr::null_mut();
        let ret = ffi::g_shell_unquote(quoted_string.as_ref().to_glib_none().0, &mut error);
        if error.is_null() {
            Ok(from_glib_full(ret))
        } else {
            Err(from_glib_full(error))
        }
    }
}

//#[cfg(feature = "v2_82")]
//#[cfg_attr(docsrs, doc(cfg(feature = "v2_82")))]
//#[doc(alias = "g_sort_array")]
//pub fn sort_array(array: /*Unimplemented*/&[&Basic: Pointer], element_size: usize, compare_func: /*Unimplemented*/FnMut(/*Unimplemented*/Option<Basic: Pointer>, /*Unimplemented*/Option<Basic: Pointer>) -> i32, user_data: /*Unimplemented*/Option<Basic: Pointer>) {
//    unsafe { TODO: call ffi:g_sort_array() }
//}

/// Gets the smallest prime number from a built-in array of primes which
/// is larger than @num. This is used within GLib to calculate the optimum
/// size of a #GHashTable.
///
/// The built-in array of primes ranges from 11 to 13845163 such that
/// each prime is approximately 1.5-2 times the previous prime.
/// ## `num`
/// a #guint
///
/// # Returns
///
/// the smallest prime number from a built-in array of primes
///     which is larger than @num
#[doc(alias = "g_spaced_primes_closest")]
pub fn spaced_primes_closest(num: u32) -> u32 {
    unsafe { ffi::g_spaced_primes_closest(num) }
}

/// Executes a child program asynchronously.
///
/// See g_spawn_async_with_pipes_and_fds() for a full description; this function
/// simply calls the g_spawn_async_with_pipes() without any pipes, which in turn
/// calls g_spawn_async_with_pipes_and_fds().
///
/// You should call g_spawn_close_pid() on the returned child process
/// reference when you don't need it any more.
///
/// If you are writing a GTK application, and the program you are spawning is a
/// graphical application too, then to ensure that the spawned program opens its
/// windows on the right screen, you may want to use #GdkAppLaunchContext,
/// #GAppLaunchContext, or set the `DISPLAY` environment variable.
///
/// Note that the returned @child_pid on Windows is a handle to the child
/// process and not its identifier. Process handles and process identifiers
/// are different concepts on Windows.
/// ## `working_directory`
/// child's current working
///     directory, or [`None`] to inherit parent's
/// ## `argv`
///
///     child's argument vector
/// ## `envp`
///
///     child's environment, or [`None`] to inherit parent's
/// ## `flags`
/// flags from #GSpawnFlags
/// ## `child_setup`
/// function to run
///     in the child just before `exec()`
///
/// # Returns
///
/// [`true`] on success, [`false`] if error is set
///
/// ## `child_pid`
/// return location for child process reference, or [`None`]
#[doc(alias = "g_spawn_async")]
pub fn spawn_async(
    working_directory: Option<impl AsRef<std::path::Path>>,
    argv: &[&std::path::Path],
    envp: &[&std::path::Path],
    flags: SpawnFlags,
    child_setup: Option<Box_<dyn FnOnce() + 'static>>,
) -> Result<Pid, crate::Error> {
    let child_setup_data: Box_<Option<Box_<dyn FnOnce() + 'static>>> = Box_::new(child_setup);
    unsafe extern "C" fn child_setup_func(data: ffi::gpointer) {
        unsafe {
            let callback = Box_::from_raw(data as *mut Option<Box_<dyn FnOnce() + 'static>>);
            let callback = (*callback).expect("cannot get closure...");
            callback()
        }
    }
    let child_setup = if child_setup_data.is_some() {
        Some(child_setup_func as _)
    } else {
        None
    };
    let super_callback0: Box_<Option<Box_<dyn FnOnce() + 'static>>> = child_setup_data;
    unsafe {
        let mut child_pid = std::mem::MaybeUninit::uninit();
        let mut error = std::ptr::null_mut();
        let is_ok = ffi::g_spawn_async(
            working_directory
                .as_ref()
                .map(|p| p.as_ref())
                .to_glib_none()
                .0,
            argv.to_glib_none().0,
            envp.to_glib_none().0,
            flags.into_glib(),
            child_setup,
            Box_::into_raw(super_callback0) as *mut _,
            child_pid.as_mut_ptr(),
            &mut error,
        );
        debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
        if error.is_null() {
            Ok(from_glib(child_pid.assume_init()))
        } else {
            Err(from_glib_full(error))
        }
    }
}

//#[cfg(feature = "v2_68")]
//#[cfg_attr(docsrs, doc(cfg(feature = "v2_68")))]
//#[doc(alias = "g_spawn_async_with_pipes_and_fds")]
//pub fn spawn_async_with_pipes_and_fds(working_directory: Option<impl AsRef<std::path::Path>>, argv: &[&std::path::Path], envp: &[&std::path::Path], flags: SpawnFlags, child_setup: Option<Box_<dyn FnOnce() + 'static>>, stdin_fd: i32, stdout_fd: i32, stderr_fd: i32, source_fds: &[i32], target_fds: &[i32], n_fds: usize) -> Result<(Pid, i32, i32, i32), crate::Error> {
//    unsafe { TODO: call ffi:g_spawn_async_with_pipes_and_fds() }
//}

/// An old name for g_spawn_check_wait_status(), deprecated because its
/// name is misleading.
///
/// Despite the name of the function, @wait_status must be the wait status
/// as returned by g_spawn_sync(), g_subprocess_get_status(), `waitpid()`,
/// etc. On Unix platforms, it is incorrect for it to be the exit status
/// as passed to `exit()` or returned by g_subprocess_get_exit_status() or
/// `WEXITSTATUS()`.
///
/// # Deprecated since 2.70
///
/// Use g_spawn_check_wait_status() instead, and check whether your code is conflating wait and exit statuses.
/// ## `wait_status`
/// A status as returned from g_spawn_sync()
///
/// # Returns
///
/// [`true`] if child exited successfully, [`false`] otherwise (and
///     @error will be set)
#[cfg_attr(feature = "v2_70", deprecated = "Since 2.70")]
#[allow(deprecated)]
#[doc(alias = "g_spawn_check_exit_status")]
pub fn spawn_check_exit_status(wait_status: i32) -> Result<(), crate::Error> {
    unsafe {
        let mut error = std::ptr::null_mut();
        let is_ok = ffi::g_spawn_check_exit_status(wait_status, &mut error);
        debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
        if error.is_null() {
            Ok(())
        } else {
            Err(from_glib_full(error))
        }
    }
}

/// Set @error if @wait_status indicates the child exited abnormally
/// (e.g. with a nonzero exit code, or via a fatal signal).
///
/// The g_spawn_sync() and g_child_watch_add() family of APIs return the
/// status of subprocesses encoded in a platform-specific way.
/// On Unix, this is guaranteed to be in the same format waitpid() returns,
/// and on Windows it is guaranteed to be the result of GetExitCodeProcess().
///
/// Prior to the introduction of this function in GLib 2.34, interpreting
/// @wait_status required use of platform-specific APIs, which is problematic
/// for software using GLib as a cross-platform layer.
///
/// Additionally, many programs simply want to determine whether or not
/// the child exited successfully, and either propagate a #GError or
/// print a message to standard error. In that common case, this function
/// can be used. Note that the error message in @error will contain
/// human-readable information about the wait status.
///
/// The @domain and @code of @error have special semantics in the case
/// where the process has an "exit code", as opposed to being killed by
/// a signal. On Unix, this happens if WIFEXITED() would be true of
/// @wait_status. On Windows, it is always the case.
///
/// The special semantics are that the actual exit code will be the
/// code set in @error, and the domain will be `G_SPAWN_EXIT_ERROR`.
/// This allows you to differentiate between different exit codes.
///
/// If the process was terminated by some means other than an exit
/// status (for example if it was killed by a signal), the domain will be
/// `G_SPAWN_ERROR` and the code will be `G_SPAWN_ERROR_FAILED`.
///
/// This function just offers convenience; you can of course also check
/// the available platform via a macro such as `G_OS_UNIX`, and use
/// WIFEXITED() and WEXITSTATUS() on @wait_status directly. Do not attempt
/// to scan or parse the error message string; it may be translated and/or
/// change in future versions of GLib.
///
/// Prior to version 2.70, g_spawn_check_exit_status() provides the same
/// functionality, although under a misleading name.
/// ## `wait_status`
/// A platform-specific wait status as returned from g_spawn_sync()
///
/// # Returns
///
/// [`true`] if child exited successfully, [`false`] otherwise (and
///   @error will be set)
#[cfg(feature = "v2_70")]
#[cfg_attr(docsrs, doc(cfg(feature = "v2_70")))]
#[doc(alias = "g_spawn_check_wait_status")]
pub fn spawn_check_wait_status(wait_status: i32) -> Result<(), crate::Error> {
    unsafe {
        let mut error = std::ptr::null_mut();
        let is_ok = ffi::g_spawn_check_wait_status(wait_status, &mut error);
        debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
        if error.is_null() {
            Ok(())
        } else {
            Err(from_glib_full(error))
        }
    }
}

/// A simple version of g_spawn_async() that parses a command line with
/// g_shell_parse_argv() and passes it to g_spawn_async().
///
/// Filenames and potentially untrusted input in @command_line should be quoted
/// using [`shell_quote()`][crate::shell_quote()].
///
/// Runs a command line in the background. Unlike g_spawn_async(), the
/// [`SpawnFlags::SEARCH_PATH`][crate::SpawnFlags::SEARCH_PATH] flag is enabled, other flags are not. Note
/// that [`SpawnFlags::SEARCH_PATH`][crate::SpawnFlags::SEARCH_PATH] can have security implications, so
/// consider using g_spawn_async() directly if appropriate. Possible
/// errors are those from g_shell_parse_argv() and g_spawn_async().
///
/// The same concerns on Windows apply as for g_spawn_command_line_sync().
/// ## `command_line`
/// a command line
///
/// # Returns
///
/// [`true`] on success, [`false`] if error is set
#[cfg(unix)]
#[cfg_attr(docsrs, doc(cfg(unix)))]
#[doc(alias = "g_spawn_command_line_async")]
pub fn spawn_command_line_async(
    command_line: impl AsRef<std::ffi::OsStr>,
) -> Result<(), crate::Error> {
    unsafe {
        let mut error = std::ptr::null_mut();
        let is_ok =
            ffi::g_spawn_command_line_async(command_line.as_ref().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))
        }
    }
}

//#[doc(alias = "g_spawn_command_line_sync")]
//pub fn spawn_command_line_sync(command_line: impl AsRef<std::path::Path>, standard_output: Vec<u8>, standard_error: Vec<u8>) -> Result<i32, crate::Error> {
//    unsafe { TODO: call ffi:g_spawn_command_line_sync() }
//}

//#[doc(alias = "g_spawn_sync")]
//pub fn spawn_sync(working_directory: Option<impl AsRef<std::path::Path>>, argv: &[&std::path::Path], envp: &[&std::path::Path], flags: SpawnFlags, child_setup: Option<&mut dyn FnMut()>, standard_output: Vec<u8>, standard_error: Vec<u8>) -> Result<i32, crate::Error> {
//    unsafe { TODO: call ffi:g_spawn_sync() }
//}

//#[doc(alias = "g_stat")]
//pub fn stat(filename: impl AsRef<std::path::Path>, buf: /*Ignored*/&mut StatBuf) -> i32 {
//    unsafe { TODO: call ffi:g_stat() }
//}

/// A wrapper for the POSIX unlink() function. The unlink() function
/// deletes a name from the filesystem. If this was the last link to the
/// file and no processes have it opened, the diskspace occupied by the
/// file is freed.
///
/// See your C library manual for more details about unlink(). Note
/// that on Windows, it is in general not possible to delete files that
/// are open to some process, or mapped into memory.
/// ## `filename`
/// a pathname in the GLib file name encoding
///     (UTF-8 on Windows)
///
/// # Returns
///
/// 0 if the name was successfully deleted, -1 if an error
///    occurred
#[doc(alias = "g_unlink")]
pub fn unlink(filename: impl AsRef<std::path::Path>) -> i32 {
    unsafe { ffi::g_unlink(filename.as_ref().to_glib_none().0) }
}

/// Removes an environment variable from the environment.
///
/// Note that on some systems, when variables are overwritten, the
/// memory used for the previous variables and its value isn't reclaimed.
///
/// You should be mindful of the fact that environment variable handling
/// in UNIX is not thread-safe, and your program may crash if one thread
/// calls g_unsetenv() while another thread is calling getenv(). (And note
/// that many functions, such as gettext(), call getenv() internally.) This
/// function is only safe to use at the very start of your program, before
/// creating any other threads (or creating objects that create worker
/// threads of their own).
///
/// If you need to set up the environment for a child process, you can
/// use g_get_environ() to get an environment array, modify that with
/// g_environ_setenv() and g_environ_unsetenv(), and then pass that
/// array directly to execvpe(), g_spawn_async(), or the like.
/// ## `variable`
/// the environment variable to remove, must
///     not contain '='
#[doc(alias = "g_unsetenv")]
pub unsafe fn unsetenv(variable: impl AsRef<std::ffi::OsStr>) {
    unsafe {
        ffi::g_unsetenv(variable.as_ref().to_glib_none().0);
    }
}

/// Pauses the current thread for the given number of microseconds.
///
/// There are 1 million microseconds per second (represented by the
/// `G_USEC_PER_SEC` macro). g_usleep() may have limited precision,
/// depending on hardware and operating system; don't rely on the exact
/// length of the sleep.
/// ## `microseconds`
/// number of microseconds to pause
#[doc(alias = "g_usleep")]
pub fn usleep(microseconds: libc::c_ulong) {
    unsafe {
        ffi::g_usleep(microseconds);
    }
}

/// Parses the string @str and verify if it is a UUID.
///
/// The function accepts the following syntax:
///
/// - simple forms (e.g. `f81d4fae-7dec-11d0-a765-00a0c91e6bf6`)
///
/// Note that hyphens are required within the UUID string itself,
/// as per the aforementioned RFC.
/// ## `str`
/// a string representing a UUID
///
/// # Returns
///
/// [`true`] if @str is a valid UUID, [`false`] otherwise.
#[doc(alias = "g_uuid_string_is_valid")]
pub fn uuid_string_is_valid(str: &str) -> bool {
    unsafe { from_glib(ffi::g_uuid_string_is_valid(str.to_glib_none().0)) }
}

/// Generates a random UUID (RFC 4122 version 4) as a string. It has the same
/// randomness guarantees as #GRand, so must not be used for cryptographic
/// purposes such as key generation, nonces, salts or one-time pads.
///
/// # Returns
///
/// A string that should be freed with g_free().
#[doc(alias = "g_uuid_string_random")]
pub fn uuid_string_random() -> crate::GString {
    unsafe { from_glib_full(ffi::g_uuid_string_random()) }
}