Function CDM_ByteSequenceReplaceCharacters


Definition:#include <CDM.h>
Prototype:CDM_ByteSequence CDM_ByteSequenceReplaceCharacters(CDM_Document Document, long pos, int characters, char *string);
Arguments:

Document: A Document object. (CDM_Document)
pos: The character offset (starting from 0) where the replacement will happen. The string will be inserted at the character pointed by this value, replacing the specified number of characters. (long)
characters: An integer specifying the number of characters that will be replaced. (int)
string: The string to be inserted. (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 replacing the specified number of characters at the position specified by the "pos" parameter by the provided string. This position "pos" is the number of characters that have to be skipped before the characters are replaced by the string, where the first character of the Document text has a position equal to 0. If position is lower than zero, it is treaded as the last character of the Document text. In the case the last character is specified as position, then the last "characters" characters are replaced.

For example, if the Document contains as text the string "This is a test", the following code:

CDM_ByteSequenceReplaceCharacters(Doc, 10, 4, "simple test");

will modify the text of the Document to "This is a simple test".

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_ByteSequence) 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_ByteSequence) 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 "string" 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_ByteSequenceReplaceCharacters (Tcl API).

See Also:

CDM_RawDataReplaceCharacters, CDM_ByteSequenceInsertString, CDM_DisplaceAnnotations, CDM_GetByteSequence, CDM_SetByteSequence, tip_ByteSequenceReplaceCharacters


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