Function CDM_DeleteAnnotations


Definition:#include <CDM.h>
Prototype:int CDM_DeleteAnnotations(CDM_Document Document, char *Type);
Arguments:

Document: A Document object. (CDM_Document)
Type: The type of the Annotations to be deleted. (char *)


Prototype:int CDM_DeleteAnnotations(CDM_Document Document, char *Type, char *Constraints);
Arguments:

Document: A Document object. (CDM_Document)
Type: The type of the Annotations to be deleted. (char *)
Constraints: A boolean expression. (char *)

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

Description:

int CDM_DeleteAnnotations(CDM_Document Document, char *Type):
This function accepts two arguments: a Document object and a UTF-8 string that defines the Annotations to be deleted. According to the value specified by the "Type" parameter, this function will delete Annotations or Annotation Attributes from the specified Document.

If the value of the "Type" parameter is an empty string or NULL, then ALL the Annotations that the specified Document currently has will be deleted from this Document object. The used Annotation Ids will be also reseted. This means that the first Annotation that will be added to this Document will take the value "0" as Annotation Id, if it does not already have an Id. If the deletion is done successfully, the total number of the deleted Annotations will be returned.

If Annotations having as type the value of the "Type" parameter exist, then all these Annotations will be deleted from the Document. If the deletion is done successfully, the total number of the deleted Annotations will be returned.

If all Annotations have been searched and no Annotation having as type the value of the "Type" parameter was found, the value of the "Type" parameter is examined whether it can be splitted in two words. If this is the case (the value of the "Type" parameter contains at least one space character), then the value is splitted in two parts on the first space character that is found. The first word will be used as an Annotation type and the rest of the value (second word) will be used as an Attribute name. All Annotations will be seached. If Annotations having as type the first word are found, they are examined whether they contain an Attribute named as the second word. If such an Attribute is found in an Annotation, it will be deleted from the Annotation. The total number of deleted Attributes will be returned as the return value of this function.

If this function fails to delete any Annotation or any Annotation Attribute, then the value "0" will be deleted. In case of an error, the value "-1" will be returned, and an error message describing the error will be left at the current Tcl interpreter (CDM_Interp).

int CDM_DeleteAnnotations(CDM_Document Document, char *Type, char *Constraints):
This function accepts three arguments: a Document object, a UTF-8 string that defines the Annotations to be deleted and a boolean expression that must be true in order for an Annotation to be deleted. According to the value specified by the "Type" parameter, this function will delete Annotations or Annotation Attributes from the specified Document.

If all Annotations have been searched and no Annotation having as type the value of the "Type" parameter was found, the value of the "Type" parameter is examined whether it can be splitted in two words. If this is the case (the value of the "Type" parameter contains at least one space character), then the value is splitted in two parts on the first space character that is found. The first word will be used as an Annotation type and the rest of the value (second word) will be used as an Attribute name. All Annotations will be seached. If Annotations having as type the first word are found, they are examined whether they contain an Attribute named as the second word. If such an Attribute is found in an Annotation and the boolean expression is true for this Annotation, it will be deleted from the Annotation. The total number of deleted Attributes will be returned as the return value of this function.

The boolean expression that can be specified through the "Constraints" parameter will be evaluated before an Annotation or an Annotation Attribute is deleted. If the expression is true, then the deletion will be done. Else, this Annotation or Annotation Attribute will not be deleted. This expression can be any valid Tcl boolean expression (i.e. a boolean expression that will be accepted by the "expr" Tcl command), with the following excepion:

  • The boolean expression can contain references to the values of Atttributes of the Annotation, by utilising the notation "ann::<Attribute Name>". The only limitation is that "<Attribute Name>" cannot exceed 120 characters. For example, the following code will delete all Annotations from the specified Document that their type is token, they have a "type" Attribute which has as value "EFW" and also have a "pos" Attribute that has a value other than "NN":

  • CDM_DeleteAnnotations(Doc, "token", "ann::type == \"EFW\" && ann::pos != \"NN\"");

    If the value of the "Type" parameter is an empty string or NULL, then all Annotations will be searched for deletion, regardless their type. If the value of the "Constraints" parameter is an empty string or NULL, then the expression is ignored and the deletions will be based only on the value of the "Type" parameter. Note that if all Annotations are deleted from the specified Document, then the set of utilised Ids will also be reseted. As a result, the first Annotation that will be added to this Document after the deletion will take the value "0" as Annotation Id, if it does not already have an Id.

    If any deletion are done successfully, the total number of the deleted (or modified) Annotations will be returned.

    If this function fails to delete any Annotation or any Annotation Attribute, then the value "0" will be deleted. In case of an error, the value "-1" will be returned, and an error message describing the error will be left at the current Tcl interpreter (CDM_Interp).

    Return Value:

    int CDM_DeleteAnnotations(CDM_Document Document, char *Type):
    This function will return the number of the deleted Annotations or Annotation Attributes. If nothing was deleted, this function will return "0". In case of an error, he value "-1" will be returned, and an error message describing the error will be left at the current Tcl interpreter (CDM_Interp).

    int CDM_DeleteAnnotations(CDM_Document Document, char *Type, char *Constraints):
    This function will return the number of the deleted Annotations or Annotation Attributes. If nothing was deleted, this function will return "0". In case of an error, he value "-1" will be returned, and an error message describing the error will be left at the current Tcl interpreter (CDM_Interp).

    Notes:

    int CDM_DeleteAnnotations(CDM_Document Document, char *Type):
    This function is equivelant to tip_DeleteAnnotations (Tcl API).

    int CDM_DeleteAnnotations(CDM_Document Document, char *Type, char *Constraints):
    This function is equivelant to tip_DeleteAnnotations (Tcl API).

    See Also:

    int CDM_DeleteAnnotations(CDM_Document Document, char *Type):
    CDM_FindMaxUsedAnnotationId, tip_DeleteAnnotations

    int CDM_DeleteAnnotations(CDM_Document Document, char *Type, char *Constraints):
    CDM_FindMaxUsedAnnotationId, tip_DeleteAnnotations, The Tcl "expr" manual.


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