glib/auto/

markup_parse_context.rs

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

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

crate::wrapper! {
    /// A parse context is used to parse a stream of bytes that
    /// you expect to contain marked-up text.
    ///
    /// See g_markup_parse_context_new(), #GMarkupParser, and so
    /// on for more details.
    // rustdoc-stripper-ignore-next-stop
    /// A parse context is used to parse a stream of bytes that
    /// you expect to contain marked-up text.
    ///
    /// See g_markup_parse_context_new(), #GMarkupParser, and so
    /// on for more details.
    #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
    pub struct MarkupParseContext(Shared<ffi::GMarkupParseContext>);

    match fn {
        ref => |ptr| ffi::g_markup_parse_context_ref(ptr),
        unref => |ptr| ffi::g_markup_parse_context_unref(ptr),
        type_ => || ffi::g_markup_parse_context_get_type(),
    }
}

impl MarkupParseContext {
    //#[doc(alias = "g_markup_parse_context_new")]
    //pub fn new(parser: /*Ignored*/&MarkupParser, flags: /*Ignored*/MarkupParseFlags, user_data: /*Unimplemented*/Option<Basic: Pointer>) -> MarkupParseContext {
    //    unsafe { TODO: call ffi:g_markup_parse_context_new() }
    //}

    /// Signals to the #GMarkupParseContext that all data has been
    /// fed into the parse context with g_markup_parse_context_parse().
    ///
    /// This function reports an error if the document isn't complete,
    /// for example if elements are still open.
    ///
    /// # Returns
    ///
    /// [`true`] on success, [`false`] if an error was set
    // rustdoc-stripper-ignore-next-stop
    /// Signals to the #GMarkupParseContext that all data has been
    /// fed into the parse context with g_markup_parse_context_parse().
    ///
    /// This function reports an error if the document isn't complete,
    /// for example if elements are still open.
    ///
    /// # Returns
    ///
    /// [`true`] on success, [`false`] if an error was set
    #[doc(alias = "g_markup_parse_context_end_parse")]
    pub fn end_parse(&self) -> Result<(), crate::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::g_markup_parse_context_end_parse(self.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))
            }
        }
    }

    /// Retrieves the name of the currently open element.
    ///
    /// If called from the start_element or end_element handlers this will
    /// give the element_name as passed to those functions. For the parent
    /// elements, see g_markup_parse_context_get_element_stack().
    ///
    /// # Returns
    ///
    /// the name of the currently open element, or [`None`]
    // rustdoc-stripper-ignore-next-stop
    /// Retrieves the name of the currently open element.
    ///
    /// If called from the start_element or end_element handlers this will
    /// give the element_name as passed to those functions. For the parent
    /// elements, see g_markup_parse_context_get_element_stack().
    ///
    /// # Returns
    ///
    /// the name of the currently open element, or [`None`]
    #[doc(alias = "g_markup_parse_context_get_element")]
    #[doc(alias = "get_element")]
    pub fn element(&self) -> crate::GString {
        unsafe {
            from_glib_none(ffi::g_markup_parse_context_get_element(
                self.to_glib_none().0,
            ))
        }
    }

    /// Retrieves the element stack from the internal state of the parser.
    ///
    /// The returned #GSList is a list of strings where the first item is
    /// the currently open tag (as would be returned by
    /// g_markup_parse_context_get_element()) and the next item is its
    /// immediate parent.
    ///
    /// This function is intended to be used in the start_element and
    /// end_element handlers where g_markup_parse_context_get_element()
    /// would merely return the name of the element that is being
    /// processed.
    ///
    /// # Returns
    ///
    /// the element stack, which must not be modified
    // rustdoc-stripper-ignore-next-stop
    /// Retrieves the element stack from the internal state of the parser.
    ///
    /// The returned #GSList is a list of strings where the first item is
    /// the currently open tag (as would be returned by
    /// g_markup_parse_context_get_element()) and the next item is its
    /// immediate parent.
    ///
    /// This function is intended to be used in the start_element and
    /// end_element handlers where g_markup_parse_context_get_element()
    /// would merely return the name of the element that is being
    /// processed.
    ///
    /// # Returns
    ///
    /// the element stack, which must not be modified
    #[doc(alias = "g_markup_parse_context_get_element_stack")]
    #[doc(alias = "get_element_stack")]
    pub fn element_stack(&self) -> Vec<crate::GString> {
        unsafe {
            FromGlibPtrContainer::from_glib_none(ffi::g_markup_parse_context_get_element_stack(
                self.to_glib_none().0,
            ))
        }
    }

    /// Retrieves the current offset from the beginning of the document,
    /// in bytes.
    ///
    /// The information is meant to accompany the values returned by
    /// [`position()`][Self::position()], and comes with the
    /// same accuracy guarantees.
    ///
    /// # Returns
    ///
    /// the offset
    // rustdoc-stripper-ignore-next-stop
    /// Retrieves the current offset from the beginning of the document,
    /// in bytes.
    ///
    /// The information is meant to accompany the values returned by
    /// [`position()`][Self::position()], and comes with the
    /// same accuracy guarantees.
    ///
    /// # Returns
    ///
    /// the offset
    #[cfg(feature = "v2_88")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v2_88")))]
    #[doc(alias = "g_markup_parse_context_get_offset")]
    #[doc(alias = "get_offset")]
    pub fn offset(&self) -> usize {
        unsafe { ffi::g_markup_parse_context_get_offset(self.to_glib_none().0) }
    }

    /// Retrieves the current line number and the number of the character on
    /// that line. Intended for use in error messages; there are no strict
    /// semantics for what constitutes the "current" line number other than
    /// "the best number we could come up with for error messages."
    ///
    /// # Returns
    ///
    ///
    /// ## `line_number`
    /// return location for a line number, or [`None`]
    ///
    /// ## `char_number`
    /// return location for a char-on-line number, or [`None`]
    // rustdoc-stripper-ignore-next-stop
    /// Retrieves the current line number and the number of the character on
    /// that line. Intended for use in error messages; there are no strict
    /// semantics for what constitutes the "current" line number other than
    /// "the best number we could come up with for error messages."
    ///
    /// # Returns
    ///
    ///
    /// ## `line_number`
    /// return location for a line number, or [`None`]
    ///
    /// ## `char_number`
    /// return location for a char-on-line number, or [`None`]
    #[doc(alias = "g_markup_parse_context_get_position")]
    #[doc(alias = "get_position")]
    pub fn position(&self) -> (i32, i32) {
        unsafe {
            let mut line_number = std::mem::MaybeUninit::uninit();
            let mut char_number = std::mem::MaybeUninit::uninit();
            ffi::g_markup_parse_context_get_position(
                self.to_glib_none().0,
                line_number.as_mut_ptr(),
                char_number.as_mut_ptr(),
            );
            (line_number.assume_init(), char_number.assume_init())
        }
    }

    /// Retrieves the start position of the current start or end tag.
    ///
    /// This function can be used in the `start_element` or `end_element`
    /// callbacks to obtain location information for error reporting.
    ///
    /// Note that @line_number and @char_number are intended for human
    /// readable error messages and are therefore 1-based and in Unicode
    /// characters. @offset on the other hand is meant for programmatic
    /// use, and thus is 0-based and in bytes.
    ///
    /// The information is meant to accompany the values returned by
    /// [`position()`][Self::position()], and comes with the
    /// same accuracy guarantees.
    ///
    /// # Returns
    ///
    ///
    /// ## `line_number`
    /// return location for the line number
    ///
    /// ## `char_number`
    /// return location for the character number
    ///
    /// ## `offset`
    /// return location for offset from the beginning of the document
    // rustdoc-stripper-ignore-next-stop
    /// Retrieves the start position of the current start or end tag.
    ///
    /// This function can be used in the `start_element` or `end_element`
    /// callbacks to obtain location information for error reporting.
    ///
    /// Note that @line_number and @char_number are intended for human
    /// readable error messages and are therefore 1-based and in Unicode
    /// characters. @offset on the other hand is meant for programmatic
    /// use, and thus is 0-based and in bytes.
    ///
    /// The information is meant to accompany the values returned by
    /// [`position()`][Self::position()], and comes with the
    /// same accuracy guarantees.
    ///
    /// # Returns
    ///
    ///
    /// ## `line_number`
    /// return location for the line number
    ///
    /// ## `char_number`
    /// return location for the character number
    ///
    /// ## `offset`
    /// return location for offset from the beginning of the document
    #[cfg(feature = "v2_88")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v2_88")))]
    #[doc(alias = "g_markup_parse_context_get_tag_start")]
    #[doc(alias = "get_tag_start")]
    pub fn tag_start(&self) -> (usize, usize, usize) {
        unsafe {
            let mut line_number = std::mem::MaybeUninit::uninit();
            let mut char_number = std::mem::MaybeUninit::uninit();
            let mut offset = std::mem::MaybeUninit::uninit();
            ffi::g_markup_parse_context_get_tag_start(
                self.to_glib_none().0,
                line_number.as_mut_ptr(),
                char_number.as_mut_ptr(),
                offset.as_mut_ptr(),
            );
            (
                line_number.assume_init(),
                char_number.assume_init(),
                offset.assume_init(),
            )
        }
    }

    /// Feed some data to the #GMarkupParseContext.
    ///
    /// The data need not be valid UTF-8; an error will be signaled if
    /// it's invalid. The data need not be an entire document; you can
    /// feed a document into the parser incrementally, via multiple calls
    /// to this function. Typically, as you receive data from a network
    /// connection or file, you feed each received chunk of data into this
    /// function, aborting the process if an error occurs. Once an error
    /// is reported, no further data may be fed to the #GMarkupParseContext;
    /// all errors are fatal.
    /// ## `text`
    /// chunk of text to parse
    /// ## `text_len`
    /// length of @text in bytes
    ///
    /// # Returns
    ///
    /// [`false`] if an error occurred, [`true`] on success
    // rustdoc-stripper-ignore-next-stop
    /// Feed some data to the #GMarkupParseContext.
    ///
    /// The data need not be valid UTF-8; an error will be signaled if
    /// it's invalid. The data need not be an entire document; you can
    /// feed a document into the parser incrementally, via multiple calls
    /// to this function. Typically, as you receive data from a network
    /// connection or file, you feed each received chunk of data into this
    /// function, aborting the process if an error occurs. Once an error
    /// is reported, no further data may be fed to the #GMarkupParseContext;
    /// all errors are fatal.
    /// ## `text`
    /// chunk of text to parse
    /// ## `text_len`
    /// length of @text in bytes
    ///
    /// # Returns
    ///
    /// [`false`] if an error occurred, [`true`] on success
    #[doc(alias = "g_markup_parse_context_parse")]
    pub fn parse(&self, text: &str) -> Result<(), crate::Error> {
        let text_len = text.len() as _;
        unsafe {
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::g_markup_parse_context_parse(
                self.to_glib_none().0,
                text.to_glib_none().0,
                text_len,
                &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_markup_parse_context_pop")]
    //pub fn pop(&self) -> /*Unimplemented*/Option<Basic: Pointer> {
    //    unsafe { TODO: call ffi:g_markup_parse_context_pop() }
    //}

    //#[doc(alias = "g_markup_parse_context_push")]
    //pub fn push(&self, parser: /*Ignored*/&MarkupParser, user_data: /*Unimplemented*/Option<Basic: Pointer>) {
    //    unsafe { TODO: call ffi:g_markup_parse_context_push() }
    //}
}