JezK

Edit File: parent.rdoc

== Class Parent

Class Parent has methods from its superclasses and included modules;
see:

- {Tasks for Child}[child_rdoc.html].
- {Tasks for Node}[node_rdoc.html].
- {Module Enumerable}[https://docs.ruby-lang.org/en/master/Enumerable.html].

:include: ../tocs/parent_toc.rdoc

=== Queries

==== Task: Get the Count of Children

Use method {Parent#size}[../../../../REXML/Parent.html#method-i-size]
(or its alias +length+) to get the count of the parent's children:

p = REXML::Parent.new
 p.size # => 0
 xml_string = '<root><a/><c/></root>'
 d = REXML::Document.new(xml_string)
 d.root.size # => 3

==== Task: Get the Child at a Given Index

Use method {Parent#[]}[../../../../REXML/Parent.html#method-i-5B-5D]
to get the child at a given index:

xml_string = '<root><a/><c/></root>'
 d = REXML::Document.new(xml_string)
 d.root[1] # => 
 d.root[-1] # => <c/>
 d.root[50] # => nil

==== Task: Get the Index of a Given Child

Use method {Parent#index}[../../../../REXML/Parent.html#method-i-index]
to get the index (0-based offset) of a child:

d = REXML::Document.new('<root></root>')
 root = d.root
 e0 = REXML::Element.new('foo')
 e1 = REXML::Element.new('bar')
 root.add(e0) # => <foo/>
 root.add(e1) # => <bar/>
 root.add(e0) # => <foo/>
 root.add(e1) # => <bar/>
 root.index(e0) # => 0
 root.index(e1) # => 1

==== Task: Get the Children

Use method {Parent#children}[../../../../REXML/Parent.html#method-i-children]
(or its alias +to_a+) to get the parent's children:

xml_string = '<root><a/><c/></root>'
 d = REXML::Document.new(xml_string)
 d.root.children # => [<a/>, , <c/>]

==== Task: Determine Whether the Node is a Parent

Use method {Parent#parent?}[../../../../REXML/Parent.html#method-i-parent-3F]
to determine whether the node is a parent;
class Text derives from Node:

d = REXML::Document.new('<root><a/>textmore<c/></root>')
 t = d.root[1] # => "text"
 t.parent? # => false

Class Parent also derives from Node, but overrides this method:

p = REXML::Parent.new
  p.parent? # => true

=== Additions

==== Task: Add a Child at the Beginning

Use method {Parent#unshift}[../../../../REXML/Parent.html#method-i-unshift]
to add a child as at the beginning of the children:

xml_string = '<root><a/><c/></root>'
 d = REXML::Document.new(xml_string)
 d.root.children # => [<a/>, , <c/>]
 d.root.unshift REXML::Element.new('d')
 d.root.children # => [<d/>, <a/>, , <c/>]

==== Task: Add a Child at the End

Use method {Parent#<<}[../../../../REXML/Parent.html#method-i-3C-3C]
(or an alias +push+ or +add+) to add a child as at the end of the children:

xml_string = '<root><a/><c/></root>'
 d = REXML::Document.new(xml_string)
 d.root.children # => [<a/>, , <c/>]
 d.root << REXML::Element.new('d')
 d.root.children # => [<a/>, , <c/>, <d/>]

==== Task: Replace a Child with Another Child

Use method {Parent#replace}[../../../../REXML/Parent.html#method-i-replace]

xml_string = '<root><a/><c/></root>'
 d = REXML::Document.new(xml_string)
 d.root.children # => [<a/>, , <c/>]
 b = d.root[1] # => 
 d.replace_child(b, REXML::Element.new('d'))
 d.root.children # => [<a/>, <c/>]

==== Task: Replace Multiple Children with Another Child

Use method {Parent#[]=}[../../../../REXML/Parent.html#method-i-parent-5B-5D-3D]
to replace multiple consecutive children with another child:

xml_string = '<root><a/><c/><d/></root>'
 d = REXML::Document.new(xml_string)
 d.root.children # => [<a/>, , <c/>, <d/>]
 d.root[1, 2] = REXML::Element.new('x')
 d.root.children # => [<a/>, <x/>, <d/>]
 d.root[1, 5] = REXML::Element.new('x')
 d.root.children # => [<a/>, <x/>] # BUG?

==== Task: Insert Child Before a Given Child

Use method {Parent#insert_before}[../../../../REXML/Parent.html#method-i-insert_before]
to insert a child immediately before a given child:

xml_string = '<root><a/><c/></root>'
 d = REXML::Document.new(xml_string)
 d.root.children # => [<a/>, , <c/>]
 b = d.root[1] # => 
 x = REXML::Element.new('x')
 d.root.insert_before(b, x)
 d.root.children # => [<a/>, <x/>, , <c/>]

==== Task: Insert Child After a Given Child

Use method {Parent#insert_after}[../../../../REXML/Parent.html#method-i-insert_after]
to insert a child immediately after a given child:

xml_string = '<root><a/><c/></root>'
 d = REXML::Document.new(xml_string)
 d.root.children # => [<a/>, , <c/>]
 b = d.root[1] # => 
 x = REXML::Element.new('x')
 d.root.insert_after(b, x)
 d.root.children # => [<a/>, , <x/>, <c/>]

=== Deletions

==== Task: Remove a Given Child

Use method {Parent#delete}[../../../../REXML/Parent.html#method-i-delete]
to remove all occurrences of a given child:

d = REXML::Document.new('<root></root>')
 a = REXML::Element.new('a')
 b = REXML::Element.new('b')
 d.root.add(a)
 d.root.add(b)
 d.root.add(a)
 d.root.add(b)
 d.root.children # => [<a/>, , <a/>, ]
 d.root.delete(b)
 d.root.children # => [<a/>, <a/>]

==== Task: Remove the Child at a Specified Offset

Use method {Parent#delete_at}[../../../../REXML/Parent.html#method-i-delete_at]
to remove the child at a specified offset:

==== Task: Remove Children That Meet Specified Criteria

Use method {Parent#delete_if}[../../../../REXML/Parent.html#method-i-delete_if]
to remove children that meet criteria specified in the given block:

d = REXML::Document.new('<root></root>')
 d.root.add(REXML::Element.new('x'))
 d.root.add(REXML::Element.new('xx'))
 d.root.add(REXML::Element.new('xxx'))
 d.root.add(REXML::Element.new('xxxx'))
 d.root.children # => [<x/>, <xx/>, <xxx/>, <xxxx/>]
 d.root.delete_if {|child| child.name.size.odd? }
 d.root.children # => [<xx/>, <xxxx/>]

=== Iterations

==== Task: Iterate Over Children

Use method {Parent#each_child}[../../../../REXML/Parent.html#method-i-each_child]
(or its alias +each+) to iterate over all children:

xml_string = '<root><a/><c/></root>'
 d = REXML::Document.new(xml_string)
 d.root.children # => [<a/>, , <c/>]
 d.root.each_child {|child| p child }

Output:

==== Task: Iterate Over Child Indexes

Use method {Parent#each_index}[../../../../REXML/Parent.html#method-i-each_index]
to iterate over all child indexes:

xml_string = '<root><a/><c/></root>'
 d = REXML::Document.new(xml_string)
 d.root.children # => [<a/>, , <c/>]
 d.root.each_index {|child| p child }

Output:

0
  1
  2

=== Clones

==== Task: Clone Deeply

Use method {Parent#deep_clone}[../../../../REXML/Parent.html#method-i-deep_clone]
to clone deeply; that is, to clone every nested node that is a Parent object:

xml_string = <<-EOT
 <?xml version="1.0" encoding="UTF-8"?>
 <bookstore>
 <book category="cooking">
 <title lang="en">Everyday Italian</title>
 <author>Giada De Laurentiis</author>
 <year>2005</year>
 <price>30.00</price>
 </book>
 <book category="children">
 <title lang="en">Harry Potter</title>
 <author>J K. Rowling</author>
 <year>2005</year>
 <price>29.99</price>
 </book>
 <book category="web">
 <title lang="en">Learning XML</title>
 <author>Erik T. Ray</author>
 <year>2003</year>
 <price>39.95</price>
 </book>
 </bookstore>
 EOT
 d = REXML::Document.new(xml_string)
 root = d.root
 shallow = root.clone
 deep = root.deep_clone
 shallow.to_s.size # => 12
 deep.to_s.size # => 590

JezK

Edit File: parent.rdoc

FAIRNETZT