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.