@spec as_prelim(t()) :: Yex.XmlFragmentPrelim.t()

Converts the XML fragment to a preliminary representation. This is useful when you need to serialize or transfer the fragment's structure.

@spec children(t()) :: Enumerable.t(Yex.XmlElement.t() | Yex.XmlText.t())

Returns a stream of all child nodes of the XML fragment.

Deletes a range of child nodes starting at the specified index. Returns :ok on success, :error on failure.

@spec fetch(t(), integer()) :: {:ok, Yex.XmlElement.t() | Yex.XmlText.t()} | :error

Retrieves the child node at the specified index. Returns {:ok, node} if found, :error if index is out of bounds.

@spec fetch!(t(), integer()) :: Yex.XmlElement.t() | Yex.XmlText.t()

Similar to fetch/2 but raises ArgumentError if the index is out of bounds.

Returns the first child node of the XML fragment. Returns nil if the fragment has no children.

@spec get(t(), integer(), default :: term()) ::
  Yex.XmlElement.t() | Yex.XmlText.t() | term()

Gets a child node by index from the XML fragment, or returns the default value if the index is out of bounds.

Parameters

• xml_fragment - The XML fragment to query
• index - The index to look up
• default - The default value to return if index is out of bounds (defaults to nil)

Examples

iex> doc = Yex.Doc.new()
iex> xml = Yex.Doc.get_xml_fragment(doc, "xml")
iex> Yex.XmlFragment.push(xml, Yex.XmlElementPrelim.empty("div"))
iex> elem = Yex.XmlFragment.get(xml, 0)
iex> match?(%Yex.XmlElement{}, elem)
true
iex> Yex.XmlFragment.get(xml, 10)
nil
iex> Yex.XmlFragment.get(xml, 10, :not_found)
:not_found

@spec get_lazy(t(), integer(), fun :: (-> term())) ::
  Yex.XmlElement.t() | Yex.XmlText.t() | term()

Gets a child node by index from the XML fragment, or lazily evaluates the given function if the index is out of bounds. This is useful when the default value is expensive to compute and should only be evaluated when needed.

Parameters

• xml_fragment - The XML fragment to query
• index - The index to look up
• fun - A function that returns the default value (only called if index is out of bounds)

Examples

iex> doc = Yex.Doc.new()
iex> xml = Yex.Doc.get_xml_fragment(doc, "xml")
iex> Yex.XmlFragment.push(xml, Yex.XmlTextPrelim.from("Hello"))
iex> Yex.XmlFragment.get_lazy(xml, 0, fn -> Yex.XmlFragment.push_and_get(xml, Yex.XmlTextPrelim.from("Computed")) end) |> to_string()
"Hello"
iex> Yex.XmlFragment.get_lazy(xml, 10, fn -> Yex.XmlFragment.push_and_get(xml, Yex.XmlTextPrelim.from("Computed")) end) |> to_string()
"Computed"

Particularly useful with *_and_get functions for get-or-create patterns:

iex> doc = Yex.Doc.new()
iex> xml = Yex.Doc.get_xml_fragment(doc, "xml")
iex> # Get existing node or create and return new one
iex> node = Yex.XmlFragment.get_lazy(xml, 0, fn ->
...>   Yex.XmlFragment.push_and_get(xml, Yex.XmlElementPrelim.empty("div"))
...> end)
iex> Yex.XmlElement.get_tag(node)
"div"

Inserts a new child node at the specified index. Returns :ok on success, :error on failure.

@spec insert_after(
  t(),
  Yex.XmlElement.t() | Yex.XmlText.t(),
  Yex.XmlElementPrelim.t() | Yex.XmlTextPrelim.t()
) :: :ok | :error

Inserts a new child node after the specified reference node. If the reference node is not found, inserts at the beginning. Returns :ok on success, :error on failure.

@spec insert_after_and_get(
  t(),
  Yex.XmlElement.t() | Yex.XmlText.t(),
  Yex.XmlElementPrelim.t() | Yex.XmlTextPrelim.t()
) :: Yex.XmlElement.t() | Yex.XmlText.t()

Inserts a new child node after the specified reference node and returns the inserted node. If the reference node is not found, inserts at the beginning. Returns the inserted node on success, raises on failure.

@spec insert_and_get(
  t(),
  integer(),
  Yex.XmlElementPrelim.t() | Yex.XmlTextPrelim.t()
) :: Yex.XmlElement.t() | Yex.XmlText.t()

Inserts a new child node at the specified index and returns the inserted node. Returns the inserted node on success, raises on failure.

Returns the number of child nodes in the XML fragment.

@spec parent(t()) :: Yex.XmlElement.t() | t() | nil

Returns the parent node of this fragment. Returns nil if this is a top-level XML fragment.

Appends a new child node at the end of the children list. Returns :ok on success, :error on failure.

@spec push_and_get(
  t(),
  Yex.XmlElementPrelim.t() | Yex.XmlTextPrelim.t()
) :: Yex.XmlElement.t() | Yex.XmlText.t()

Appends a new child node at the end of the children list and returns the inserted node. Returns the inserted node on success, raises on failure.

@spec to_string(t()) :: binary()

Returns a string representation of the XML fragment and all its child nodes.

Inserts a new child node at the beginning of the children list. Returns :ok on success, :error on failure.