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

use crate::{translate::*, Bytes, Error, UriFlags, UriHideFlags};
use std::{fmt, mem, ptr};

crate::wrapper! {
    /// The [`Uri`][crate::Uri] type and related functions can be used to parse URIs into
    /// their components, and build valid URIs from individual components.
    ///
    /// Note that [`Uri`][crate::Uri] scope is to help manipulate URIs in various applications,
    /// following [RFC 3986](https://tools.ietf.org/html/rfc3986). In particular,
    /// it doesn't intend to cover web browser needs, and doesn't implement the
    /// [WHATWG URL](https://url.spec.whatwg.org/) standard. No APIs are provided to
    /// help prevent
    /// [homograph attacks](https://en.wikipedia.org/wiki/IDN_homograph_attack), so
    /// [`Uri`][crate::Uri] is not suitable for formatting URIs for display to the user for making
    /// security-sensitive decisions.
    ///
    /// ## Relative and absolute URIs # {`relative`-absolute-uris}
    ///
    /// As defined in [RFC 3986](https://tools.ietf.org/html/rfc3986`section`-4), the
    /// hierarchical nature of URIs means that they can either be ‘relative
    /// references’ (sometimes referred to as ‘relative URIs’) or ‘URIs’ (for
    /// clarity, ‘URIs’ are referred to in this documentation as
    /// ‘absolute URIs’ — although
    /// [in constrast to RFC 3986](https://tools.ietf.org/html/rfc3986`section`-4.3),
    /// fragment identifiers are always allowed).
    ///
    /// Relative references have one or more components of the URI missing. In
    /// particular, they have no scheme. Any other component, such as hostname,
    /// query, etc. may be missing, apart from a path, which has to be specified (but
    /// may be empty). The path may be relative, starting with `./` rather than `/`.
    ///
    /// For example, a valid relative reference is `./path?query`,
    /// `/?query`fragment`` or `//example.com`.
    ///
    /// Absolute URIs have a scheme specified. Any other components of the URI which
    /// are missing are specified as explicitly unset in the URI, rather than being
    /// resolved relative to a base URI using [`parse_relative()`][Self::parse_relative()].
    ///
    /// For example, a valid absolute URI is `file:///home/bob` or
    /// `https://search.com?query=string`.
    ///
    /// A [`Uri`][crate::Uri] instance is always an absolute URI. A string may be an absolute URI
    /// or a relative reference; see the documentation for individual functions as to
    /// what forms they accept.
    ///
    /// ## Parsing URIs
    ///
    /// The most minimalist APIs for parsing URIs are [`split()`][Self::split()] and
    /// [`split_with_user()`][Self::split_with_user()]. These split a URI into its component
    /// parts, and return the parts; the difference between the two is that
    /// [`split()`][Self::split()] treats the ‘userinfo’ component of the URI as a
    /// single element, while [`split_with_user()`][Self::split_with_user()] can (depending on the
    /// [`UriFlags`][crate::UriFlags] you pass) treat it as containing a username, password,
    /// and authentication parameters. Alternatively, [`split_network()`][Self::split_network()]
    /// can be used when you are only interested in the components that are
    /// needed to initiate a network connection to the service (scheme,
    /// host, and port).
    ///
    /// [`parse()`][Self::parse()] is similar to [`split()`][Self::split()], but instead of returning
    /// individual strings, it returns a [`Uri`][crate::Uri] structure (and it requires
    /// that the URI be an absolute URI).
    ///
    /// [`resolve_relative()`][Self::resolve_relative()] and [`parse_relative()`][Self::parse_relative()] allow you to
    /// resolve a relative URI relative to a base URI.
    /// [`resolve_relative()`][Self::resolve_relative()] takes two strings and returns a string,
    /// and [`parse_relative()`][Self::parse_relative()] takes a [`Uri`][crate::Uri] and a string and returns a
    /// [`Uri`][crate::Uri].
    ///
    /// All of the parsing functions take a [`UriFlags`][crate::UriFlags] argument describing
    /// exactly how to parse the URI; see the documentation for that type
    /// for more details on the specific flags that you can pass. If you
    /// need to choose different flags based on the type of URI, you can
    /// use [`peek_scheme()`][Self::peek_scheme()] on the URI string to check the scheme
    /// first, and use that to decide what flags to parse it with.
    ///
    /// For example, you might want to use [`UriParamsFlags::WWW_FORM`][crate::UriParamsFlags::WWW_FORM] when parsing the
    /// params for a web URI, so compare the result of [`peek_scheme()`][Self::peek_scheme()] against
    /// `http` and `https`.
    ///
    /// ## Building URIs
    ///
    /// [`join()`][Self::join()] and [`join_with_user()`][Self::join_with_user()] can be used to construct
    /// valid URI strings from a set of component strings. They are the
    /// inverse of [`split()`][Self::split()] and [`split_with_user()`][Self::split_with_user()].
    ///
    /// Similarly, [`build()`][Self::build()] and [`build_with_user()`][Self::build_with_user()] can be used to
    /// construct a [`Uri`][crate::Uri] from a set of component strings.
    ///
    /// As with the parsing functions, the building functions take a
    /// [`UriFlags`][crate::UriFlags] argument. In particular, it is important to keep in mind
    /// whether the URI components you are using are already `%`-encoded. If so,
    /// you must pass the [`UriFlags::ENCODED`][crate::UriFlags::ENCODED] flag.
    ///
    /// ## `file://` URIs
    ///
    /// Note that Windows and Unix both define special rules for parsing
    /// `file://` URIs (involving non-UTF-8 character sets on Unix, and the
    /// interpretation of path separators on Windows). [`Uri`][crate::Uri] does not
    /// implement these rules. Use [`filename_from_uri()`][crate::filename_from_uri()] and
    /// [`filename_to_uri()`][crate::filename_to_uri()] if you want to properly convert between
    /// `file://` URIs and local filenames.
    ///
    /// ## URI Equality
    ///
    /// Note that there is no `g_uri_equal ()` function, because comparing
    /// URIs usefully requires scheme-specific knowledge that [`Uri`][crate::Uri] does
    /// not have. [`Uri`][crate::Uri] can help with normalization if you use the various
    /// encoded [`UriFlags`][crate::UriFlags] as well as [`UriFlags::SCHEME_NORMALIZE`][crate::UriFlags::SCHEME_NORMALIZE] however
    /// it is not comprehensive.
    /// For example, `data:,foo` and `data:;base64,Zm9v` resolve to the same
    /// thing according to the `data:` URI specification which GLib does not
    /// handle.
    #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
    pub struct Uri(Shared<ffi::GUri>);

    match fn {
        ref => |ptr| ffi::g_uri_ref(ptr),
        unref => |ptr| ffi::g_uri_unref(ptr),
        type_ => || ffi::g_uri_get_type(),
    }
}

impl Uri {
    /// Gets `self`'s authentication parameters, which may contain
    /// `%`-encoding, depending on the flags with which `self` was created.
    /// (If `self` was not created with [`UriFlags::HAS_AUTH_PARAMS`][crate::UriFlags::HAS_AUTH_PARAMS] then this will
    /// be [`None`].)
    ///
    /// Depending on the URI scheme, `g_uri_parse_params()` may be useful for
    /// further parsing this information.
    ///
    /// # Returns
    ///
    /// `self`'s authentication parameters.
    #[doc(alias = "g_uri_get_auth_params")]
    #[doc(alias = "get_auth_params")]
    pub fn auth_params(&self) -> Option<crate::GString> {
        unsafe { from_glib_none(ffi::g_uri_get_auth_params(self.to_glib_none().0)) }
    }

    /// Gets `self`'s flags set upon construction.
    ///
    /// # Returns
    ///
    /// `self`'s flags.
    #[doc(alias = "g_uri_get_flags")]
    #[doc(alias = "get_flags")]
    pub fn flags(&self) -> UriFlags {
        unsafe { from_glib(ffi::g_uri_get_flags(self.to_glib_none().0)) }
    }

    /// Gets `self`'s fragment, which may contain `%`-encoding, depending on
    /// the flags with which `self` was created.
    ///
    /// # Returns
    ///
    /// `self`'s fragment.
    #[doc(alias = "g_uri_get_fragment")]
    #[doc(alias = "get_fragment")]
    pub fn fragment(&self) -> Option<crate::GString> {
        unsafe { from_glib_none(ffi::g_uri_get_fragment(self.to_glib_none().0)) }
    }

    /// Gets `self`'s host. This will never have `%`-encoded characters,
    /// unless it is non-UTF-8 (which can only be the case if `self` was
    /// created with [`UriFlags::NON_DNS`][crate::UriFlags::NON_DNS]).
    ///
    /// If `self` contained an IPv6 address literal, this value will be just
    /// that address, without the brackets around it that are necessary in
    /// the string form of the URI. Note that in this case there may also
    /// be a scope ID attached to the address. Eg, `fe80::1234%``em1` (or
    /// `fe80::1234%``25em1` if the string is still encoded).
    ///
    /// # Returns
    ///
    /// `self`'s host.
    #[doc(alias = "g_uri_get_host")]
    #[doc(alias = "get_host")]
    pub fn host(&self) -> Option<crate::GString> {
        unsafe { from_glib_none(ffi::g_uri_get_host(self.to_glib_none().0)) }
    }

    /// Gets `self`'s password, which may contain `%`-encoding, depending on
    /// the flags with which `self` was created. (If `self` was not created
    /// with [`UriFlags::HAS_PASSWORD`][crate::UriFlags::HAS_PASSWORD] then this will be [`None`].)
    ///
    /// # Returns
    ///
    /// `self`'s password.
    #[doc(alias = "g_uri_get_password")]
    #[doc(alias = "get_password")]
    pub fn password(&self) -> Option<crate::GString> {
        unsafe { from_glib_none(ffi::g_uri_get_password(self.to_glib_none().0)) }
    }

    /// Gets `self`'s path, which may contain `%`-encoding, depending on the
    /// flags with which `self` was created.
    ///
    /// # Returns
    ///
    /// `self`'s path.
    #[doc(alias = "g_uri_get_path")]
    #[doc(alias = "get_path")]
    pub fn path(&self) -> crate::GString {
        unsafe { from_glib_none(ffi::g_uri_get_path(self.to_glib_none().0)) }
    }

    /// Gets `self`'s port.
    ///
    /// # Returns
    ///
    /// `self`'s port, or `-1` if no port was specified.
    #[doc(alias = "g_uri_get_port")]
    #[doc(alias = "get_port")]
    pub fn port(&self) -> i32 {
        unsafe { ffi::g_uri_get_port(self.to_glib_none().0) }
    }

    /// Gets `self`'s query, which may contain `%`-encoding, depending on the
    /// flags with which `self` was created.
    ///
    /// For queries consisting of a series of `name=value` parameters,
    /// `GUriParamsIter` or `g_uri_parse_params()` may be useful.
    ///
    /// # Returns
    ///
    /// `self`'s query.
    #[doc(alias = "g_uri_get_query")]
    #[doc(alias = "get_query")]
    pub fn query(&self) -> Option<crate::GString> {
        unsafe { from_glib_none(ffi::g_uri_get_query(self.to_glib_none().0)) }
    }

    /// Gets `self`'s scheme. Note that this will always be all-lowercase,
    /// regardless of the string or strings that `self` was created from.
    ///
    /// # Returns
    ///
    /// `self`'s scheme.
    #[doc(alias = "g_uri_get_scheme")]
    #[doc(alias = "get_scheme")]
    pub fn scheme(&self) -> crate::GString {
        unsafe { from_glib_none(ffi::g_uri_get_scheme(self.to_glib_none().0)) }
    }

    /// Gets the ‘username’ component of `self`'s userinfo, which may contain
    /// `%`-encoding, depending on the flags with which `self` was created.
    /// If `self` was not created with [`UriFlags::HAS_PASSWORD`][crate::UriFlags::HAS_PASSWORD] or
    /// [`UriFlags::HAS_AUTH_PARAMS`][crate::UriFlags::HAS_AUTH_PARAMS], this is the same as [`userinfo()`][Self::userinfo()].
    ///
    /// # Returns
    ///
    /// `self`'s user.
    #[doc(alias = "g_uri_get_user")]
    #[doc(alias = "get_user")]
    pub fn user(&self) -> Option<crate::GString> {
        unsafe { from_glib_none(ffi::g_uri_get_user(self.to_glib_none().0)) }
    }

    /// Gets `self`'s userinfo, which may contain `%`-encoding, depending on
    /// the flags with which `self` was created.
    ///
    /// # Returns
    ///
    /// `self`'s userinfo.
    #[doc(alias = "g_uri_get_userinfo")]
    #[doc(alias = "get_userinfo")]
    pub fn userinfo(&self) -> Option<crate::GString> {
        unsafe { from_glib_none(ffi::g_uri_get_userinfo(self.to_glib_none().0)) }
    }

    /// Parses `uri_ref` according to `flags` and, if it is a
    /// [relative URI][relative-absolute-uris], resolves it relative to `self`.
    /// If the result is not a valid absolute URI, it will be discarded, and an error
    /// returned.
    /// ## `uri_ref`
    /// a string representing a relative or absolute URI
    /// ## `flags`
    /// flags describing how to parse `uri_ref`
    ///
    /// # Returns
    ///
    /// a new [`Uri`][crate::Uri], or NULL on error.
    #[doc(alias = "g_uri_parse_relative")]
    pub fn parse_relative(&self, uri_ref: &str, flags: UriFlags) -> Result<Uri, crate::Error> {
        unsafe {
            let mut error = ptr::null_mut();
            let ret = ffi::g_uri_parse_relative(
                self.to_glib_none().0,
                uri_ref.to_glib_none().0,
                flags.into_glib(),
                &mut error,
            );
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Returns a string representing `self`.
    ///
    /// This is not guaranteed to return a string which is identical to the
    /// string that `self` was parsed from. However, if the source URI was
    /// syntactically correct (according to RFC 3986), and it was parsed
    /// with [`UriFlags::ENCODED`][crate::UriFlags::ENCODED], then [`to_str()`][Self::to_str()] is guaranteed to return
    /// a string which is at least semantically equivalent to the source
    /// URI (according to RFC 3986).
    ///
    /// If `self` might contain sensitive details, such as authentication parameters,
    /// or private data in its query string, and the returned string is going to be
    /// logged, then consider using [`to_string_partial()`][Self::to_string_partial()] to redact parts.
    ///
    /// # Returns
    ///
    /// a string representing `self`,
    ///  which the caller must free.
    #[doc(alias = "g_uri_to_string")]
    #[doc(alias = "to_string")]
    pub fn to_str(&self) -> crate::GString {
        unsafe { from_glib_full(ffi::g_uri_to_string(self.to_glib_none().0)) }
    }

    /// Returns a string representing `self`, subject to the options in
    /// `flags`. See [`to_str()`][Self::to_str()] and [`UriHideFlags`][crate::UriHideFlags] for more details.
    /// ## `flags`
    /// flags describing what parts of `self` to hide
    ///
    /// # Returns
    ///
    /// a string representing
    ///  `self`, which the caller must free.
    #[doc(alias = "g_uri_to_string_partial")]
    pub fn to_string_partial(&self, flags: UriHideFlags) -> crate::GString {
        unsafe {
            from_glib_full(ffi::g_uri_to_string_partial(
                self.to_glib_none().0,
                flags.into_glib(),
            ))
        }
    }

    /// Creates a new [`Uri`][crate::Uri] from the given components according to `flags`.
    ///
    /// See also [`build_with_user()`][Self::build_with_user()], which allows specifying the
    /// components of the "userinfo" separately.
    /// ## `flags`
    /// flags describing how to build the [`Uri`][crate::Uri]
    /// ## `scheme`
    /// the URI scheme
    /// ## `userinfo`
    /// the userinfo component, or [`None`]
    /// ## `host`
    /// the host component, or [`None`]
    /// ## `port`
    /// the port, or `-1`
    /// ## `path`
    /// the path component
    /// ## `query`
    /// the query component, or [`None`]
    /// ## `fragment`
    /// the fragment, or [`None`]
    ///
    /// # Returns
    ///
    /// a new [`Uri`][crate::Uri]
    #[doc(alias = "g_uri_build")]
    pub fn build(
        flags: UriFlags,
        scheme: &str,
        userinfo: Option<&str>,
        host: Option<&str>,
        port: i32,
        path: &str,
        query: Option<&str>,
        fragment: Option<&str>,
    ) -> Uri {
        unsafe {
            from_glib_full(ffi::g_uri_build(
                flags.into_glib(),
                scheme.to_glib_none().0,
                userinfo.to_glib_none().0,
                host.to_glib_none().0,
                port,
                path.to_glib_none().0,
                query.to_glib_none().0,
                fragment.to_glib_none().0,
            ))
        }
    }

    /// Creates a new [`Uri`][crate::Uri] from the given components according to `flags`
    /// ([`UriFlags::HAS_PASSWORD`][crate::UriFlags::HAS_PASSWORD] is added unconditionally). The `flags` must be
    /// coherent with the passed values, in particular use `%`-encoded values with
    /// [`UriFlags::ENCODED`][crate::UriFlags::ENCODED].
    ///
    /// In contrast to [`build()`][Self::build()], this allows specifying the components
    /// of the ‘userinfo’ field separately. Note that `user` must be non-[`None`]
    /// if either `password` or `auth_params` is non-[`None`].
    /// ## `flags`
    /// flags describing how to build the [`Uri`][crate::Uri]
    /// ## `scheme`
    /// the URI scheme
    /// ## `user`
    /// the user component of the userinfo, or [`None`]
    /// ## `password`
    /// the password component of the userinfo, or [`None`]
    /// ## `auth_params`
    /// the auth params of the userinfo, or [`None`]
    /// ## `host`
    /// the host component, or [`None`]
    /// ## `port`
    /// the port, or `-1`
    /// ## `path`
    /// the path component
    /// ## `query`
    /// the query component, or [`None`]
    /// ## `fragment`
    /// the fragment, or [`None`]
    ///
    /// # Returns
    ///
    /// a new [`Uri`][crate::Uri]
    #[doc(alias = "g_uri_build_with_user")]
    pub fn build_with_user(
        flags: UriFlags,
        scheme: &str,
        user: Option<&str>,
        password: Option<&str>,
        auth_params: Option<&str>,
        host: Option<&str>,
        port: i32,
        path: &str,
        query: Option<&str>,
        fragment: Option<&str>,
    ) -> Uri {
        unsafe {
            from_glib_full(ffi::g_uri_build_with_user(
                flags.into_glib(),
                scheme.to_glib_none().0,
                user.to_glib_none().0,
                password.to_glib_none().0,
                auth_params.to_glib_none().0,
                host.to_glib_none().0,
                port,
                path.to_glib_none().0,
                query.to_glib_none().0,
                fragment.to_glib_none().0,
            ))
        }
    }

    /// Escapes arbitrary data for use in a URI.
    ///
    /// Normally all characters that are not ‘unreserved’ (i.e. ASCII
    /// alphanumerical characters plus dash, dot, underscore and tilde) are
    /// escaped. But if you specify characters in `reserved_chars_allowed`
    /// they are not escaped. This is useful for the ‘reserved’ characters
    /// in the URI specification, since those are allowed unescaped in some
    /// portions of a URI.
    ///
    /// Though technically incorrect, this will also allow escaping nul
    /// bytes as `%``00`.
    /// ## `unescaped`
    /// the unescaped input data.
    /// ## `reserved_chars_allowed`
    /// a string of reserved
    ///  characters that are allowed to be used, or [`None`].
    ///
    /// # Returns
    ///
    /// an escaped version of `unescaped`.
    ///  The returned string should be freed when no longer needed.
    #[doc(alias = "g_uri_escape_bytes")]
    pub fn escape_bytes(unescaped: &[u8], reserved_chars_allowed: Option<&str>) -> crate::GString {
        let length = unescaped.len() as _;
        unsafe {
            from_glib_full(ffi::g_uri_escape_bytes(
                unescaped.to_glib_none().0,
                length,
                reserved_chars_allowed.to_glib_none().0,
            ))
        }
    }

    /// Escapes a string for use in a URI.
    ///
    /// Normally all characters that are not "unreserved" (i.e. ASCII
    /// alphanumerical characters plus dash, dot, underscore and tilde) are
    /// escaped. But if you specify characters in `reserved_chars_allowed`
    /// they are not escaped. This is useful for the "reserved" characters
    /// in the URI specification, since those are allowed unescaped in some
    /// portions of a URI.
    /// ## `unescaped`
    /// the unescaped input string.
    /// ## `reserved_chars_allowed`
    /// a string of reserved
    ///  characters that are allowed to be used, or [`None`].
    /// ## `allow_utf8`
    /// [`true`] if the result can include UTF-8 characters.
    ///
    /// # Returns
    ///
    /// an escaped version of `unescaped`. The
    /// returned string should be freed when no longer needed.
    #[doc(alias = "g_uri_escape_string")]
    pub fn escape_string(
        unescaped: &str,
        reserved_chars_allowed: Option<&str>,
        allow_utf8: bool,
    ) -> crate::GString {
        unsafe {
            from_glib_full(ffi::g_uri_escape_string(
                unescaped.to_glib_none().0,
                reserved_chars_allowed.to_glib_none().0,
                allow_utf8.into_glib(),
            ))
        }
    }

    /// Parses `uri_string` according to `flags`, to determine whether it is a valid
    /// [absolute URI][relative-absolute-uris], i.e. it does not need to be resolved
    /// relative to another URI using [`parse_relative()`][Self::parse_relative()].
    ///
    /// If it’s not a valid URI, an error is returned explaining how it’s invalid.
    ///
    /// See [`split()`][Self::split()], and the definition of [`UriFlags`][crate::UriFlags], for more
    /// information on the effect of `flags`.
    /// ## `uri_string`
    /// a string containing an absolute URI
    /// ## `flags`
    /// flags for parsing `uri_string`
    ///
    /// # Returns
    ///
    /// [`true`] if `uri_string` is a valid absolute URI, [`false`] on error.
    #[doc(alias = "g_uri_is_valid")]
    pub fn is_valid(uri_string: &str, flags: UriFlags) -> Result<(), crate::Error> {
        unsafe {
            let mut error = ptr::null_mut();
            let is_ok =
                ffi::g_uri_is_valid(uri_string.to_glib_none().0, flags.into_glib(), &mut error);
            debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok(())
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Joins the given components together according to `flags` to create
    /// an absolute URI string. `path` may not be [`None`] (though it may be the empty
    /// string).
    ///
    /// When `host` is present, `path` must either be empty or begin with a slash (`/`)
    /// character. When `host` is not present, `path` cannot begin with two slash
    /// characters (`//`). See
    /// [RFC 3986, section 3](https://tools.ietf.org/html/rfc3986`section`-3).
    ///
    /// See also [`join_with_user()`][Self::join_with_user()], which allows specifying the
    /// components of the ‘userinfo’ separately.
    ///
    /// [`UriFlags::HAS_PASSWORD`][crate::UriFlags::HAS_PASSWORD] and [`UriFlags::HAS_AUTH_PARAMS`][crate::UriFlags::HAS_AUTH_PARAMS] are ignored if set
    /// in `flags`.
    /// ## `flags`
    /// flags describing how to build the URI string
    /// ## `scheme`
    /// the URI scheme, or [`None`]
    /// ## `userinfo`
    /// the userinfo component, or [`None`]
    /// ## `host`
    /// the host component, or [`None`]
    /// ## `port`
    /// the port, or `-1`
    /// ## `path`
    /// the path component
    /// ## `query`
    /// the query component, or [`None`]
    /// ## `fragment`
    /// the fragment, or [`None`]
    ///
    /// # Returns
    ///
    /// an absolute URI string
    #[doc(alias = "g_uri_join")]
    pub fn join(
        flags: UriFlags,
        scheme: Option<&str>,
        userinfo: Option<&str>,
        host: Option<&str>,
        port: i32,
        path: &str,
        query: Option<&str>,
        fragment: Option<&str>,
    ) -> crate::GString {
        unsafe {
            from_glib_full(ffi::g_uri_join(
                flags.into_glib(),
                scheme.to_glib_none().0,
                userinfo.to_glib_none().0,
                host.to_glib_none().0,
                port,
                path.to_glib_none().0,
                query.to_glib_none().0,
                fragment.to_glib_none().0,
            ))
        }
    }

    /// Joins the given components together according to `flags` to create
    /// an absolute URI string. `path` may not be [`None`] (though it may be the empty
    /// string).
    ///
    /// In contrast to [`join()`][Self::join()], this allows specifying the components
    /// of the ‘userinfo’ separately. It otherwise behaves the same.
    ///
    /// [`UriFlags::HAS_PASSWORD`][crate::UriFlags::HAS_PASSWORD] and [`UriFlags::HAS_AUTH_PARAMS`][crate::UriFlags::HAS_AUTH_PARAMS] are ignored if set
    /// in `flags`.
    /// ## `flags`
    /// flags describing how to build the URI string
    /// ## `scheme`
    /// the URI scheme, or [`None`]
    /// ## `user`
    /// the user component of the userinfo, or [`None`]
    /// ## `password`
    /// the password component of the userinfo, or
    ///  [`None`]
    /// ## `auth_params`
    /// the auth params of the userinfo, or
    ///  [`None`]
    /// ## `host`
    /// the host component, or [`None`]
    /// ## `port`
    /// the port, or `-1`
    /// ## `path`
    /// the path component
    /// ## `query`
    /// the query component, or [`None`]
    /// ## `fragment`
    /// the fragment, or [`None`]
    ///
    /// # Returns
    ///
    /// an absolute URI string
    #[doc(alias = "g_uri_join_with_user")]
    pub fn join_with_user(
        flags: UriFlags,
        scheme: Option<&str>,
        user: Option<&str>,
        password: Option<&str>,
        auth_params: Option<&str>,
        host: Option<&str>,
        port: i32,
        path: &str,
        query: Option<&str>,
        fragment: Option<&str>,
    ) -> crate::GString {
        unsafe {
            from_glib_full(ffi::g_uri_join_with_user(
                flags.into_glib(),
                scheme.to_glib_none().0,
                user.to_glib_none().0,
                password.to_glib_none().0,
                auth_params.to_glib_none().0,
                host.to_glib_none().0,
                port,
                path.to_glib_none().0,
                query.to_glib_none().0,
                fragment.to_glib_none().0,
            ))
        }
    }

    /// Splits an URI list conforming to the text/uri-list
    /// mime type defined in RFC 2483 into individual URIs,
    /// discarding any comments. The URIs are not validated.
    /// ## `uri_list`
    /// an URI list
    ///
    /// # Returns
    ///
    /// a newly allocated [`None`]-terminated list
    ///  of strings holding the individual URIs. The array should be freed
    ///  with `g_strfreev()`.
    #[doc(alias = "g_uri_list_extract_uris")]
    pub fn list_extract_uris(uri_list: &str) -> Vec<crate::GString> {
        unsafe {
            FromGlibPtrContainer::from_glib_full(ffi::g_uri_list_extract_uris(
                uri_list.to_glib_none().0,
            ))
        }
    }

    /// Parses `uri_string` according to `flags`. If the result is not a
    /// valid [absolute URI][relative-absolute-uris], it will be discarded, and an
    /// error returned.
    /// ## `uri_string`
    /// a string representing an absolute URI
    /// ## `flags`
    /// flags describing how to parse `uri_string`
    ///
    /// # Returns
    ///
    /// a new [`Uri`][crate::Uri], or NULL on error.
    #[doc(alias = "g_uri_parse")]
    pub fn parse(uri_string: &str, flags: UriFlags) -> Result<Uri, crate::Error> {
        unsafe {
            let mut error = ptr::null_mut();
            let ret = ffi::g_uri_parse(uri_string.to_glib_none().0, flags.into_glib(), &mut error);
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    //#[doc(alias = "g_uri_parse_params")]
    //pub fn parse_params(params: &str, separators: &str, flags: UriParamsFlags) -> Result</*Unknown conversion*//*Unimplemented*/HashTable TypeId { ns_id: 0, id: 28 }/TypeId { ns_id: 0, id: 28 }, crate::Error> {
    //    unsafe { TODO: call ffi:g_uri_parse_params() }
    //}

    /// Gets the scheme portion of a URI string.
    /// [RFC 3986](https://tools.ietf.org/html/rfc3986`section`-3) decodes the scheme
    /// as:
    ///
    /// ```text
    /// URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
    /// ```
    /// Common schemes include `file`, `https`, `svn+ssh`, etc.
    /// ## `uri`
    /// a valid URI.
    ///
    /// # Returns
    ///
    /// The ‘scheme’ component of the URI, or
    ///  [`None`] on error. The returned string should be freed when no longer needed.
    #[doc(alias = "g_uri_parse_scheme")]
    pub fn parse_scheme(uri: &str) -> Option<crate::GString> {
        unsafe { from_glib_full(ffi::g_uri_parse_scheme(uri.to_glib_none().0)) }
    }

    /// Gets the scheme portion of a URI string.
    /// [RFC 3986](https://tools.ietf.org/html/rfc3986`section`-3) decodes the scheme
    /// as:
    ///
    /// ```text
    /// URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
    /// ```
    /// Common schemes include `file`, `https`, `svn+ssh`, etc.
    ///
    /// Unlike [`parse_scheme()`][Self::parse_scheme()], the returned scheme is normalized to
    /// all-lowercase and does not need to be freed.
    /// ## `uri`
    /// a valid URI.
    ///
    /// # Returns
    ///
    /// The ‘scheme’ component of the URI, or
    ///  [`None`] on error. The returned string is normalized to all-lowercase, and
    ///  interned via `g_intern_string()`, so it does not need to be freed.
    #[doc(alias = "g_uri_peek_scheme")]
    pub fn peek_scheme(uri: &str) -> Option<crate::GString> {
        unsafe { from_glib_none(ffi::g_uri_peek_scheme(uri.to_glib_none().0)) }
    }

    /// Parses `uri_ref` according to `flags` and, if it is a
    /// [relative URI][relative-absolute-uris], resolves it relative to
    /// `base_uri_string`. If the result is not a valid absolute URI, it will be
    /// discarded, and an error returned.
    ///
    /// (If `base_uri_string` is [`None`], this just returns `uri_ref`, or
    /// [`None`] if `uri_ref` is invalid or not absolute.)
    /// ## `base_uri_string`
    /// a string representing a base URI
    /// ## `uri_ref`
    /// a string representing a relative or absolute URI
    /// ## `flags`
    /// flags describing how to parse `uri_ref`
    ///
    /// # Returns
    ///
    /// the resolved URI string,
    /// or NULL on error.
    #[doc(alias = "g_uri_resolve_relative")]
    pub fn resolve_relative(
        base_uri_string: Option<&str>,
        uri_ref: &str,
        flags: UriFlags,
    ) -> Result<crate::GString, crate::Error> {
        unsafe {
            let mut error = ptr::null_mut();
            let ret = ffi::g_uri_resolve_relative(
                base_uri_string.to_glib_none().0,
                uri_ref.to_glib_none().0,
                flags.into_glib(),
                &mut error,
            );
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Parses `uri_ref` (which can be an
    /// [absolute or relative URI][relative-absolute-uris]) according to `flags`, and
    /// returns the pieces. Any component that doesn't appear in `uri_ref` will be
    /// returned as [`None`] (but note that all URIs always have a path component,
    /// though it may be the empty string).
    ///
    /// If `flags` contains [`UriFlags::ENCODED`][crate::UriFlags::ENCODED], then `%`-encoded characters in
    /// `uri_ref` will remain encoded in the output strings. (If not,
    /// then all such characters will be decoded.) Note that decoding will
    /// only work if the URI components are ASCII or UTF-8, so you will
    /// need to use [`UriFlags::ENCODED`][crate::UriFlags::ENCODED] if they are not.
    ///
    /// Note that the [`UriFlags::HAS_PASSWORD`][crate::UriFlags::HAS_PASSWORD] and
    /// [`UriFlags::HAS_AUTH_PARAMS`][crate::UriFlags::HAS_AUTH_PARAMS] `flags` are ignored by [`split()`][Self::split()],
    /// since it always returns only the full userinfo; use
    /// [`split_with_user()`][Self::split_with_user()] if you want it split up.
    /// ## `uri_ref`
    /// a string containing a relative or absolute URI
    /// ## `flags`
    /// flags for parsing `uri_ref`
    ///
    /// # Returns
    ///
    /// [`true`] if `uri_ref` parsed successfully, [`false`]
    ///  on error.
    ///
    /// ## `scheme`
    /// on return, contains
    ///  the scheme (converted to lowercase), or [`None`]
    ///
    /// ## `userinfo`
    /// on return, contains
    ///  the userinfo, or [`None`]
    ///
    /// ## `host`
    /// on return, contains the
    ///  host, or [`None`]
    ///
    /// ## `port`
    /// on return, contains the
    ///  port, or `-1`
    ///
    /// ## `path`
    /// on return, contains the
    ///  path
    ///
    /// ## `query`
    /// on return, contains the
    ///  query, or [`None`]
    ///
    /// ## `fragment`
    /// on return, contains
    ///  the fragment, or [`None`]
    #[doc(alias = "g_uri_split")]
    pub fn split(
        uri_ref: &str,
        flags: UriFlags,
    ) -> Result<
        (
            Option<crate::GString>,
            Option<crate::GString>,
            Option<crate::GString>,
            i32,
            crate::GString,
            Option<crate::GString>,
            Option<crate::GString>,
        ),
        crate::Error,
    > {
        unsafe {
            let mut scheme = ptr::null_mut();
            let mut userinfo = ptr::null_mut();
            let mut host = ptr::null_mut();
            let mut port = mem::MaybeUninit::uninit();
            let mut path = ptr::null_mut();
            let mut query = ptr::null_mut();
            let mut fragment = ptr::null_mut();
            let mut error = ptr::null_mut();
            let is_ok = ffi::g_uri_split(
                uri_ref.to_glib_none().0,
                flags.into_glib(),
                &mut scheme,
                &mut userinfo,
                &mut host,
                port.as_mut_ptr(),
                &mut path,
                &mut query,
                &mut fragment,
                &mut error,
            );
            debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok((
                    from_glib_full(scheme),
                    from_glib_full(userinfo),
                    from_glib_full(host),
                    port.assume_init(),
                    from_glib_full(path),
                    from_glib_full(query),
                    from_glib_full(fragment),
                ))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Parses `uri_string` (which must be an [absolute URI][relative-absolute-uris])
    /// according to `flags`, and returns the pieces relevant to connecting to a host.
    /// See the documentation for [`split()`][Self::split()] for more details; this is
    /// mostly a wrapper around that function with simpler arguments.
    /// However, it will return an error if `uri_string` is a relative URI,
    /// or does not contain a hostname component.
    /// ## `uri_string`
    /// a string containing an absolute URI
    /// ## `flags`
    /// flags for parsing `uri_string`
    ///
    /// # Returns
    ///
    /// [`true`] if `uri_string` parsed successfully,
    ///  [`false`] on error.
    ///
    /// ## `scheme`
    /// on return, contains
    ///  the scheme (converted to lowercase), or [`None`]
    ///
    /// ## `host`
    /// on return, contains the
    ///  host, or [`None`]
    ///
    /// ## `port`
    /// on return, contains the
    ///  port, or `-1`
    #[doc(alias = "g_uri_split_network")]
    pub fn split_network(
        uri_string: &str,
        flags: UriFlags,
    ) -> Result<(Option<crate::GString>, Option<crate::GString>, i32), crate::Error> {
        unsafe {
            let mut scheme = ptr::null_mut();
            let mut host = ptr::null_mut();
            let mut port = mem::MaybeUninit::uninit();
            let mut error = ptr::null_mut();
            let is_ok = ffi::g_uri_split_network(
                uri_string.to_glib_none().0,
                flags.into_glib(),
                &mut scheme,
                &mut host,
                port.as_mut_ptr(),
                &mut error,
            );
            debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok((
                    from_glib_full(scheme),
                    from_glib_full(host),
                    port.assume_init(),
                ))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Parses `uri_ref` (which can be an
    /// [absolute or relative URI][relative-absolute-uris]) according to `flags`, and
    /// returns the pieces. Any component that doesn't appear in `uri_ref` will be
    /// returned as [`None`] (but note that all URIs always have a path component,
    /// though it may be the empty string).
    ///
    /// See [`split()`][Self::split()], and the definition of [`UriFlags`][crate::UriFlags], for more
    /// information on the effect of `flags`. Note that `password` will only
    /// be parsed out if `flags` contains [`UriFlags::HAS_PASSWORD`][crate::UriFlags::HAS_PASSWORD], and
    /// `auth_params` will only be parsed out if `flags` contains
    /// [`UriFlags::HAS_AUTH_PARAMS`][crate::UriFlags::HAS_AUTH_PARAMS].
    /// ## `uri_ref`
    /// a string containing a relative or absolute URI
    /// ## `flags`
    /// flags for parsing `uri_ref`
    ///
    /// # Returns
    ///
    /// [`true`] if `uri_ref` parsed successfully, [`false`]
    ///  on error.
    ///
    /// ## `scheme`
    /// on return, contains
    ///  the scheme (converted to lowercase), or [`None`]
    ///
    /// ## `user`
    /// on return, contains
    ///  the user, or [`None`]
    ///
    /// ## `password`
    /// on return, contains
    ///  the password, or [`None`]
    ///
    /// ## `auth_params`
    /// on return, contains
    ///  the auth_params, or [`None`]
    ///
    /// ## `host`
    /// on return, contains the
    ///  host, or [`None`]
    ///
    /// ## `port`
    /// on return, contains the
    ///  port, or `-1`
    ///
    /// ## `path`
    /// on return, contains the
    ///  path
    ///
    /// ## `query`
    /// on return, contains the
    ///  query, or [`None`]
    ///
    /// ## `fragment`
    /// on return, contains
    ///  the fragment, or [`None`]
    #[doc(alias = "g_uri_split_with_user")]
    pub fn split_with_user(
        uri_ref: &str,
        flags: UriFlags,
    ) -> Result<
        (
            Option<crate::GString>,
            Option<crate::GString>,
            Option<crate::GString>,
            Option<crate::GString>,
            Option<crate::GString>,
            i32,
            crate::GString,
            Option<crate::GString>,
            Option<crate::GString>,
        ),
        crate::Error,
    > {
        unsafe {
            let mut scheme = ptr::null_mut();
            let mut user = ptr::null_mut();
            let mut password = ptr::null_mut();
            let mut auth_params = ptr::null_mut();
            let mut host = ptr::null_mut();
            let mut port = mem::MaybeUninit::uninit();
            let mut path = ptr::null_mut();
            let mut query = ptr::null_mut();
            let mut fragment = ptr::null_mut();
            let mut error = ptr::null_mut();
            let is_ok = ffi::g_uri_split_with_user(
                uri_ref.to_glib_none().0,
                flags.into_glib(),
                &mut scheme,
                &mut user,
                &mut password,
                &mut auth_params,
                &mut host,
                port.as_mut_ptr(),
                &mut path,
                &mut query,
                &mut fragment,
                &mut error,
            );
            debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok((
                    from_glib_full(scheme),
                    from_glib_full(user),
                    from_glib_full(password),
                    from_glib_full(auth_params),
                    from_glib_full(host),
                    port.assume_init(),
                    from_glib_full(path),
                    from_glib_full(query),
                    from_glib_full(fragment),
                ))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Unescapes a segment of an escaped string as binary data.
    ///
    /// Note that in contrast to [`unescape_string()`][Self::unescape_string()], this does allow
    /// nul bytes to appear in the output.
    ///
    /// If any of the characters in `illegal_characters` appears as an escaped
    /// character in `escaped_string`, then that is an error and [`None`] will be
    /// returned. This is useful if you want to avoid for instance having a slash
    /// being expanded in an escaped path element, which might confuse pathname
    /// handling.
    /// ## `escaped_string`
    /// A URI-escaped string
    /// ## `length`
    /// the length (in bytes) of `escaped_string` to escape, or `-1` if it
    ///  is nul-terminated.
    /// ## `illegal_characters`
    /// a string of illegal characters
    ///  not to be allowed, or [`None`].
    ///
    /// # Returns
    ///
    /// an unescaped version of `escaped_string`
    ///  or [`None`] on error (if decoding failed, using [`UriError::Failed`][crate::UriError::Failed] error
    ///  code). The returned [`Bytes`][crate::Bytes] should be unreffed when no longer needed.
    #[doc(alias = "g_uri_unescape_bytes")]
    pub fn unescape_bytes(
        escaped_string: &str,
        illegal_characters: Option<&str>,
    ) -> Result<Bytes, crate::Error> {
        let length = escaped_string.len() as _;
        unsafe {
            let mut error = ptr::null_mut();
            let ret = ffi::g_uri_unescape_bytes(
                escaped_string.to_glib_none().0,
                length,
                illegal_characters.to_glib_none().0,
                &mut error,
            );
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Unescapes a segment of an escaped string.
    ///
    /// If any of the characters in `illegal_characters` or the NUL
    /// character appears as an escaped character in `escaped_string`, then
    /// that is an error and [`None`] will be returned. This is useful if you
    /// want to avoid for instance having a slash being expanded in an
    /// escaped path element, which might confuse pathname handling.
    ///
    /// Note: `NUL` byte is not accepted in the output, in contrast to
    /// [`unescape_bytes()`][Self::unescape_bytes()].
    /// ## `escaped_string`
    /// A string, may be [`None`]
    /// ## `escaped_string_end`
    /// Pointer to end of `escaped_string`,
    ///  may be [`None`]
    /// ## `illegal_characters`
    /// An optional string of illegal
    ///  characters not to be allowed, may be [`None`]
    ///
    /// # Returns
    ///
    /// an unescaped version of `escaped_string`,
    /// or [`None`] on error. The returned string should be freed when no longer
    /// needed. As a special case if [`None`] is given for `escaped_string`, this
    /// function will return [`None`].
    #[doc(alias = "g_uri_unescape_segment")]
    pub fn unescape_segment(
        escaped_string: Option<&str>,
        escaped_string_end: Option<&str>,
        illegal_characters: Option<&str>,
    ) -> Option<crate::GString> {
        unsafe {
            from_glib_full(ffi::g_uri_unescape_segment(
                escaped_string.to_glib_none().0,
                escaped_string_end.to_glib_none().0,
                illegal_characters.to_glib_none().0,
            ))
        }
    }

    /// Unescapes a whole escaped string.
    ///
    /// If any of the characters in `illegal_characters` or the NUL
    /// character appears as an escaped character in `escaped_string`, then
    /// that is an error and [`None`] will be returned. This is useful if you
    /// want to avoid for instance having a slash being expanded in an
    /// escaped path element, which might confuse pathname handling.
    /// ## `escaped_string`
    /// an escaped string to be unescaped.
    /// ## `illegal_characters`
    /// a string of illegal characters
    ///  not to be allowed, or [`None`].
    ///
    /// # Returns
    ///
    /// an unescaped version of `escaped_string`.
    /// The returned string should be freed when no longer needed.
    #[doc(alias = "g_uri_unescape_string")]
    pub fn unescape_string(
        escaped_string: &str,
        illegal_characters: Option<&str>,
    ) -> Option<crate::GString> {
        unsafe {
            from_glib_full(ffi::g_uri_unescape_string(
                escaped_string.to_glib_none().0,
                illegal_characters.to_glib_none().0,
            ))
        }
    }
}

impl fmt::Display for Uri {
    #[inline]
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        f.write_str(&self.to_str())
    }
}

unsafe impl Send for Uri {}
unsafe impl Sync for Uri {}