DOM_CharacterData

## 7. DOM_CharacterData

The `DOM_CharacterData` interface provides some basic text manipulation functions for the `DOM_Text`, `DOM_Comment`, and `DOM_CDATASection` nodes. `DOM_CharacterData` nodes cannot be instatiated directly.

Currently all of these functions set `DOM_Exception` if an error occurs however there is no return value to detect the error event. A future version of `DOMC` will likely return a value that indicates that an error has occured.

DOM specifications require that character data is UTF-16 encoded. DOMC does not support UTF-16. The locale dependant 8 bit encoding is used instead. This permits common `char *` strings to be used in place of `DOM_String *`. Many UNIX and Linux systems support the UTF-8 locale. If a DOMC program is running in a UTF-8 locale the offsets of these string operations refer to characters rather than bytes or individual multibyte sequences. Thus the behavior of these functions should be very similar or identical to that of a DOM implementation that uses UTF-16. Also note that UTF-8 support may be disabled for the sake of installation simplicity. It may be necessary to obtain the source code and rebuild DOMC if i18n support is required.

### 7.1. The DOM_CharacterData functions

These functions should be used to edit the character data content of `DOM_Text`, `DOM_Comment`, and `DOM_CDATASection` nodes.

The `DOM_CharacterData_getLength` function
Synopsis

      #include <domc.h>
      void DOM_CharacterData_deleteData(DOM_CharacterData *this);

Description
The `DOM_CharacterData_getLength` function returns the number of characters represented in this character data node.

The `DOM_CharacterData_substringData` function
Synopsis

      #include <domc.h>
      DOM_String *DOM_CharacterData_substringData(DOM_CharacterData *this,
               int offset,
               int count);

Description
The `DOM_CharacterData_substringData` function returns a pointer to a string representing the substring beginning at the character at `offset` with a length of `count`. If the sum off `offset` and `count` exceeds the length of the character data, a string representing the remainder of the string is returned. Memory for the string is allocated with `malloc`(3) and may be freed with `free`(3). If the `offset` parameter is out of range `DOM_Exception` will be set to `DOM_INDEX_SIZE_ERR`.

The `DOM_CharacterData_appendData` function
Synopsis

      #include <domc.h>
      void DOM_CharacterData_appendData(DOM_CharacterData *this, DOM_String *arg);

Description
The `DOM_CharacterData_appendData` function appends the string `arg` to this character data node.

The `DOM_CharacterData_insertData` function
Synopsis

      #include <domc.h>
      void DOM_CharacterData_insertData(DOM_CharacterData *this,
               int offset,
               DOM_String *arg);

Description
The `DOM_CharacterData_insertData` function inserts the string `arg` into this character data at `offset`. If the `offset` parameter is out of range `DOM_Exception` will be set to `DOM_INDEX_SIZE_ERR`.

The `DOM_CharacterData_deleteData` function
Synopsis

      #include <domc.h>
      void DOM_CharacterData_deleteData(DOM_CharacterData *this,
               int offset,
               int count);

Description
The `DOM_CharacterData_deleteData` function removes at most `count` characters at `offset` from the underlying string of this character data node. The resulting ends are concatonated together into one string. If the sum off `offset` and `count` exceeds the length of the character data, the resulting string will end at `offset`. If the `offset` parameter is out of range `DOM_Exception` will be set to `DOM_INDEX_SIZE_ERR`.

The `DOM_CharacterData_replaceData` function
Synopsis

      #include <domc.h>
      void DOM_CharacterData_replaceData(DOM_CharacterData *this,
               int offset,
               int count,
               DOM_String *arg);

Description
The `DOM_CharacterData_replaceData` function removes the character data at `offset` for `count` characters and inserts the string `arg` in it's place. If the sum off `offset` and `count` exceeds the length of the character data, a string representing the remainder of the string is returned. If the `offset` parameter is out of range `DOM_Exception` will be set to `DOM_INDEX_SIZE_ERR`.

Copyright 2003 Michael B. Allen <mballen@erols.com> Generated by CStyleX 0.1.1