Skip Headers

Oracle® XML API Reference
10g Release 1 (10.1)
Part No. B10789-01
  Go To Table Of Contents
Contents

Previous Next  

CharacterData Interface

Table 4-2 summarizes the methods of available through the CharacterData interface.

Table 4-2 Summary of CharacterData Method; DOM Package

Function Summary
XmlDomAppendData
Append data to end of node's current data.
XmlDomDeleteData
Remove part of node's data.
XmlDomGetCharData
Return data for node.
XmlDomGetCharDataLength
Return length of data for node.
XmlDomInsertData
Insert string into node's current data.
XmlDomReplaceData
Replace part of node's data.
XmlDomSetCharData
Set data for node.
XmlDomSubstringData
Return substring of node's data.


XmlDomAppendData

Append a string to the end of a CharacterData node's data. If the node is not Text, Comment or CDATA, or if the string to append is NULL, does nothing. The appended data should be in the data encoding. It will not be verified, converted, or checked.

The new node data will be allocated and managed by DOM, but if the previous node value was allocated and manager by the user, they are responsible for freeing it, which is why it is returned.


Syntax
void XmlDomAppendData(
   xmlctx *xctx,
   xmlnode *node,
   oratext *data, 
   oratext **old)

Parameter In/Out Description
xctx
IN
XML context
node
IN
CharacterData node
data
IN
data to append; data encoding
old
OUT
previous data for node; data encoding


XmlDomDeleteData

Remove a range of characters from a CharacterData node's data. If the node is not text, comment or CDATA, or if the offset is outside of the original data, does nothing. The offset is zero-based, so offset zero refers to the start of the data. Both offset and count are in characters, not bytes. If the sum of offset and count exceeds the data length then all characters from offset to the end of the data are deleted.

The new node data will be allocated and managed by DOM, but if the previous node value was allocated and managed by the user, they are responsible for freeing it, which is why it is returned.


Syntax
void XmlDomDeleteData(
   xmlctx *xctx,
   xmlnode *node,
   ub4 offset, 
   ub4 count,
   oratext **old)

Parameter In/Out Description
xctx
IN
XML context
node
IN
CharacterData node
offset
IN
character offset where to start removing
count
IN
number of characters to delete
old
OUT
previous data for node; data encoding


XmlDomGetCharData

Returns the data for a CharacterData node (type text, comment or CDATA) in the data encoding. For other node types, or if there is no data, returns NULL.


Syntax
oratext* XmlDomGetCharData(
   xmlctx *xctx,
   xmlnode *node)

Parameter In/Out Description
xctx
IN
XML context
node
IN
CharacterData node; Text, Comment or CDATA


Returns

(oratext *) character data of node [data encoding]


XmlDomGetCharDataLength

Returns the length of the data for a CharacterData node, type Text, Comment or CDATA) in characters, not bytes. For other node types, returns 0.


Syntax
ub4 XmlDomGetCharDataLength(
   xmlctx *xctx,
   xmlnode *cdata)

Parameter In/Out Description
xctx
IN
XML context
node
IN
CharacterData node; Text, Comment or CDATA


Returns

(ub4) length in characters, not bytes, of node's data


See Also:

XmlDomGetCharData


XmlDomInsertData

Insert a string into a CharacterData node's data at the specified position. If the node is not Text, Comment or CDATA, or if the data to be inserted is NULL, or the offset is outside the original data, does nothing. The inserted data must be in the data encoding. It will not be verified, converted, or checked. The offset is specified as characters, not bytes. The offset is zero-based, so inserting at offset zero prepends the data.

The new node data will be allocated and managed by DOM, but if the previous node value was allocated and managed by the user, they are responsible for freeing it (which is why it's returned).


Syntax
void XmlDomInsertData(
   xmlctx *xctx,
   xmlnode *node,
   ub4 offset, 
   oratext *arg,
   oratext **old)

Parameter In/Out Description
xctx
IN
XML context
node
IN
CharacterData node; Text, Comment, or CDATA
offset
IN
character offset where to start inserting
arg
IN
data to insert
old
OUT
previous data for node; data encoding


XmlDomReplaceData

Replaces a range of characters in a CharacterData node's data with a new string. If the node is not text, comment or CDATA, or if the offset is outside of the original data, or if the replacement string is NULL, does nothing. If the count is zero, acts just as XmlDomInsertData. The offset is zero-based, so offset zero refers to the start of the data. The replacement data must be in the data encoding. It will not be verified, converted, or checked. The offset and count are both in characters, not bytes. If the sum of offset and count exceeds length, then all characters to the end of the data are replaced.

The new node data will be allocated and managed by DOM, but if the previous node value was allocated and managed by the user, they are responsible for freeing it, which is why it is returned.


Syntax
void XmlDomReplaceData(
   xmlctx *xctx,
   xmlnode *node,
   ub4 offset, 
   ub4 count,
   oratext *arg,
   oratext **old)

Parameter In/Out Description
xctx
IN
XML context
node
IN
CharacterData node; Text, Comment, or CDATA
offset
IN
character offset where to start replacing
count
IN
number of characters to replace
arg
IN
replacement substring; data encoding
old
OUT
previous data for node; data encoding


XmlDomSetCharData

Sets data for a CharacterData node (type text, comment or CDATA), replacing the old data. For other node types, does nothing. The new data is not verified, converted, or checked; it should be in the data encoding.


Syntax
void XmlDomSetCharData(
   xmlctx *xctx,
   xmlnode *node,
   oratext *data)

Parameter In/Out Description
xctx
IN
XML context
node
IN
CharacterData node; Text, Comment, or CDATA
data
IN
new data for node


See Also:

XmlDomGetCharData


XmlDomSubstringData

Returns a range of character data from a CharacterData node, type Text, Comment or CDATA. For other node types, or if count is zero, returns NULL. Since the data is in the data encoding, offset and count are in characters, not bytes. The beginning of the string is offset 0. If the sum of offset and count exceeds the length, then all characters to the end of the data are returned.

The substring is permanently allocated in the node's document's memory pool. To free the substring, use XmlDomFreeString.


Syntax
oratext* XmlDomSubstringData(
   xmlctx *xctx,
   xmlnode *node,
   ub4 offset,
   ub4 count)

Parameter In/Out Description
xctx
IN
XML context
node
IN
CharacterData node; Text, Comment, or CDATA
offset
IN
character offset where to start extraction of substring
count
IN
number of characters to extract


Returns

(oratext *) specified substring.