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. |
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.
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 |
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.
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 |
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
.
oratext* XmlDomGetCharData( xmlctx *xctx, xmlnode *node)
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
CharacterData node; Text , Comment or CDATA
|
(oratext *)
character data of node [data encoding]
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.
ub4 XmlDomGetCharDataLength( xmlctx *xctx, xmlnode *cdata)
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
CharacterData node; Text , Comment or CDATA
|
(ub4)
length in characters, not bytes, of node's data
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).
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 |
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.
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 |
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.
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 |
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
.
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 |
(oratext *)
specified substring.