=head1 NAME

XML::LibXML::Text - The DOM Text Node Class

=head1 synopsis

 use XML::LibXML

 $text = XML::LibXML::Text->new( $content ); 
 $nodedata = $text->data;
 $text->setData( $text_content );
 $text->substringData($offset, $length);
 $text->appendData( $somedata );
 $text->insertData($offset, $string);
 $text->deleteData($offset, $length);
 $text->deleteDataString($remstring, $all);
 $text->replaceData($offset, $length, $string);
 $text->replaceDataString($old, $new, $flag);
 $text->replaceDataRegEx( $search_cond, $replace_cond, $reflags );


=head1 DESCRIPTION




Different to the DOM specification XML::LibXML
implements the text node as the base class of all
character data node. Therefor there exists no
CharacterData class. This allow one to use all methods
that are available for textnodes as well for Comments
or CDATA-sections.




=head2 Methods

=over 4

=item B<new>




The constuctor of the class. It creates an unbound text node.




=item B<data>




Although there exists the I<nodeValue>
attribute in the Node class, the DOM specification
defines data as a separate
attribute. I<XML::LibXML> implements these
two attributes not as different attributes, but as
aliases, such as I<libxml2> does. Therefore 


 $text->data
                

and


 $text->nodeValue
                


will have the same result and are not different
entities.




=item B<setData($string)>




This function sets or replaces text content to a
node. The node has to be of the type "text",
"cdata" or "comment".




=item B<substringData($offset,$length)>




Extracts a range of data from the node. (DOM Spec)
This function takes the two parameters $offset and
$length and returns the substring if available.





If the node contains no data or $offset referes to
an nonexisting string index, this function will
return B<undef>. If $length is out of range
I<substringData> will return the data
starting at $offset instead of causing an error.




=item B<appendData($string)>




Appends a string to the end of the existing
data. If the current text node contains no data,
this function has the same effect as
I<setData>.




=item B<insertData($offset,$string)>




Inserts the parameter $string at the given $offset
of the existing data of the node. This operation
will not remove existing data, but change the
order of the existing data.





The $offset has to be a positive value. If $offset
is out of range, I<insertData> will have the
same behaviour as I<appendData>.




=item B<deleteData($offset, $length)>




This method removes a chunk from the existing node
data at the given offset. The $length parameter
tells, how many characters should be removed from
the string.




=item B<deleteDataString($string, [$all])>




This method removes a chunk from the existing node
data. Since the DOM spec is quite unhandy if you
already know I<which> string to remove from
a text node, this method allows more perlish code :)





The functions takes two parameters:
B<$string> and optional the B<$all>
flag. If $all is not set, B<undef> or
B<0>, I<deleteDataString> will remove
only the first occourance of $string. If $all is
B<TRUE> I<deleteDataString> will
remove all occourences of B<$string> from
the node data.




=item B<replaceData($offset, $length, $string)>




The DOM style version to replace node data.




=item B<replaceDataString($oldstring, $newstring, [$all])>




The more programmer friendly version of replaceData() :)





Instead of giving offsets and length one can
specify the exact string (B<$oldstring>) to
be replaced. Additionally the B<$all> flag
allows to replace all occourences of
B<$oldstring>.




=item B<replaceDataRegEx( $search_cond, $replace_cond, $reflags )>




This method replaces the node's data by a
I<simple> regular expression. Optional, this
function allows to pass some flags that will be
added as flag to the replace statement.





B<NOTE:> This is a shortcut for



 my $datastr = $node->getData();
 $datastr =~ s/somecond/replacement/g; # 'g' is just an example for any flag
 $node->setData( $datastr );
                    


This function can make things easier to read for
simple replacements. For more complex variants it
is recommented to use the code snippet above.






=back

=head1 AUTHOR

Matt Sergeant, Christian Glahn

=head1 SEE ALSO

XML::LibXML, XML::LibXML::Node, XML::LibXML::Element, XML::LibXML::Document, XML::LibXML::Comment, XML::LibXML::DocumentFragment

=head1 VERSION

1.53