Skip Headers

Oracle® XML API Reference 10g Release 1 (10.1) Part No. B10789-01 |
| Contents

## 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

See Also: XmlDomGetCharData, XmlDomInsertData, XmlDomDeleteData, XmlDomReplaceData, XmlDomSplitText

### 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

See Also: XmlDomGetCharData, XmlDomAppendData, XmlDomInsertData, XmlDomReplaceData, XmlDomSplitText

### 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]

See Also: XmlDomSetCharData, XmlDomCreateText, XmlDomCreateComment, XmlDomCreateCDATA

### 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

See Also: XmlDomGetCharData, XmlDomAppendData, XmlDomDeleteData, XmlDomReplaceData, XmlDomSplitText

### 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

See Also: XmlDomGetCharData, XmlDomAppendData, XmlDomInsertData, XmlDomDeleteData, XmlDomSplitText

### 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.

See Also: XmlDomAppendData, XmlDomInsertData, XmlDomDeleteData, XmlDomReplaceData, XmlDomSplitText, XmlDomFreeString