Xport Interface: markup::insert

For a derived element object, inserts one or more markup objects or PCDATA.

virtual markup::iterator markup::insert(1st Variety
  const markup& mkup
);

virtual markup::iterator markup::insert(2nd Variety 
   const std::string& pcdat
);

virtual markup::iterator markup::insert(3rd Variety
  const markup::const_iterator& pos, 
  const markup& mkup
);

virtual markup::iterator markup::insert(4th Variety
  const markup::const_iterator& pos,
  const std::string& pcdat
);

virtual void markup::insert(5th Variety
  const markup::const_iterator& pos,
  markup::size_type num,
  const markup& mkup
);

virtual void markup::insert(6th Variety
  const markup::const_iterator& pos,
  const markup::const_iterator& beg,
  const markup::const_iterator& end
);

Parameters

mkup

A markup derived object, which can be one of the following, an element, pcdata, comment, or procinstr.

pcdat

A string argument which represents PCDATA to insert as content.

pos

An iterator which specifies the position of the markup object(s) to insert.

num

A positive integer amount which specifies the number of copies of mkup to insert.

beg

An iterator which specifies the beginning range of markup objects to insert.

end

An iterator which specifies the end of the range of markup objects to insert.

Returns

In the first four varities, returns an iterator which points to the inserted markup object.

Remarks

This operation is revelant only if it is called on an element derived object. If called on a pcdata, comment, or procinstr object, no action will take place, and the end() iterator will be returned in the first five varieties.

This family of operations are of the most used operations in the library. These operations offer a variety of ways to insert content into the document tree. The operations can be called on derived element objects, and also iterators and descendant_iterators which point to element objects. Note that for any insertions to be successful, the insertion must be valid not violate nesting rules for the particular doctype of the document.

The first variety inserts a markup object at the end of the current children. This operation is equivalent to the push_back() operation.

The second variety inserts PCDATA into the called element. The passed PCDATA is enclosed within a pcdata object before being inserted into the called element.

The third variety inserts a markup object at the child position pos. This variety allows the caller to specify where the markup object will be inserted in relation to other markup children which might already be present in the called element.

The forth variety inserts PCDATA at the child position pos. This variety allows the caller to specify where the PCDATA will be inserted in relation to other markup children which might already be present in the called element. The passed PCDATA is enclosed within a pcdata object before being inserted into the called element.

The fifth variety inserts num copies of mkup at the position pos.

The sixth variety inserts the markup objects in the range [beg, end), starting at the position pos. The markup objects in the specified range can be children of the called element, or any other element.

Complexity

Logrithmic

Examples

For examples of all varieties of this operation, see element::insert().