xmlElementsByTagName           package:XML           R Documentation

_R_e_t_r_i_e_v_e _t_h_e _c_h_i_l_d_r_e_n _o_f _a_n _X_M_L _n_o_d_e _w_i_t_h _a _s_p_e_c_i_f_i_c _t_a_g _n_a_m_e

_D_e_s_c_r_i_p_t_i_o_n:

     This returns a list of the children or sub-elements of an XML node
     whose tag name matches the one specified by the user.

_U_s_a_g_e:

     xmlElementsByTagName(el, name, recursive = FALSE)

_A_r_g_u_m_e_n_t_s:

      el: the node whose matching children are to be retrieved.

    name: a string giving the name of the tag to match in each of 
          'el''s children.

recursive: a logical value. If this is 'FALSE', the default, only the
          direct child nodes are searched. Alternatively, if this is
          'TRUE',  all sub-nodes at all levels  are searched. In other
          words, we find all descendants of the node 'el' and return a
          list with the nodes having the given name. The relationship
          between the nodes in the resulting list cannot be determined.
          This is a set of nodes. See the note.  

_D_e_t_a_i_l_s:

     This does a simple matching of names and subsets the XML node's
     children list. If 'recursive' is 'TRUE', then the function is
     applied recursively to the children of the given node and so on.

_V_a_l_u_e:

     A list containing those child nodes of 'el' whose tag name matches
     that specified by the user.

_N_o_t_e:

     The addition of the 'recursive' argument makes this function
     behave like the 'getElementsByTagName' in other language APIs such
     as Java, C#. However, one should be careful to understand that in
     those languages, one would get back a set of node objects. These
     nodes have references to their parents and children. Therefore one
     can navigate the tree from each node, find its relations, etc. In
     the current version of this package (and for the forseeable
     future),  the node set is a "copy" of the nodes in the original
     tree. And these have no facilities for finding their siblings or
     parent. Additionally, one can consume a large amount of memory by
     taking a copy of numerous large nodes using this facility. If one
     does not modify the nodes, the extra memory may be small. But
     modifying them means that the contents will be copied.

     Alternative implementations of the tree, e.g. using unique
     identifiers for nodes or via internal data structures from libxml
     can allow us to implement this function with different semantics,
     more similar to the other APIs.

_A_u_t_h_o_r(_s):

     Duncan Temple Lang

_R_e_f_e_r_e_n_c_e_s:

     <URL: http://www.w3.org/XML>, <URL:
     http://www.omegahat.org/RSXML>,

_S_e_e _A_l_s_o:

     'xmlChildren' 'xmlTreeParse'

_E_x_a_m_p_l_e_s:

     ## Not run: 
      doc <- xmlTreeParse("http://www.omegahat.org/Scripts/Data/mtcars.xml")
      xmlElementsByTagName(doc$children[[1]], "variable")
     ## End(Not run)

      doc <- xmlTreeParse(system.file("exampleData", "mtcars.xml", package="XML"))
      xmlElementsByTagName(xmlRoot(doc)[[1]], "variable")

