Function CDM_RawDataReplace


Definition:#include <CDM.h>
Prototype:CDM_RawData CDM_RawDataReplace(CDM_Document Document, long first, long last, char *newstring);
Arguments:

Document: A Document object. (CDM_Document)
first: The character offset (starting from 0) of the first character that will be replaced. (long)
last: The character offset (starting from 0) of the last character that will be replaced. (long)
newstring: The string to be placed in the removed character range. (char *)

C/C++ API Sections
Tcl API Sections
Description
Return Value
Notes
See Also
Index

Description:

This function will modify the text contained in the specified Document, by removing a range of consecutive characters from the Document Text, starting with the character whose index is the value of the parameter "first" and ending with the character whose index is the value of the parameter "last". An index of 0 refers to the first character of the Document Text, while a negative value (i.e. -1) refers to the last character of the Document Text. If the value of the parameter "newstring" is not NULL, then it is placed in the removed character range. If "first" is less than zero then it is treated as if it was zero, and if "last" is greater than the length of the Document Text then it is treated as if it was equal to the length of the Document Text. It is an error if "first" is greater than "last".

The most important aspect of this function is that it will make the proper arrangements so as the Annotations contained inside the Document to be displaced by a proper amound of characters so as Annotations spanning text ranges after the replacement point to span the same text portions, after the string has replaced the desired characters.

This function will return the new Document text (as an object of type CDM_RawData) if the replacement was succesful. Note that the returned object is owned by the CDM. The caller is not supposed to free or modify the returned object.

In case of an error, NULL will be return and an error message will be left at the current active Tcl interpreter (CDM_Interp).

Return Value:

This function will return the new Document text (as an object of type CDM_RawData) if the replacement was succesful. The returned object is property of the CDM and should never be freed or modified in any way by the caller.

In case of an error, NULL will be return and an error message will be left at the current active Tcl interpreter (CDM_Interp).

Notes:

This function can be also used in order to delete characters from the text contained in the specified Document, if the value of the "newstring" parameter is NULL or an empty string (like ""). In this case, all Annotations objects contained in the specified Document are searched: if any of them has a Span object in its Span set whoose offsets span portion of the charactes to be deleted, then this Span is eliminated from the Span set of the Annotation object. Note that no Annotation objects are deleted from the Document, although character deletion can result in Annotations with an empty Span set.

This function is equivelant to tip_RawDataReplace (Tcl API).

See Also:

CDM_ByteSequenceReplace, CDM_RawDataReplaceCharacters, CDM_ByteSequenceReplaceCharacters, CDM_RawDataInsertString, CDM_ByteSequenceInsertString, CDM_DisplaceAnnotations, CDM_GetRawData, CDM_SetRawData, CDM_GetByteSequence, CDM_SetByteSequence, tip_RawDataReplace


Generated by: petasis@aias on Wed Aug 16 10:31:57 PM EEST 2006.