Function CDM_PutAttribute


Definition:#include <CDM.h>
Prototype:int CDM_PutAttribute(CDM_Collection Collection, CDM_Attribute Attr);
Arguments:

Collection: A Collection object. (CDM_Collection)
Attribute: The Attribute to be added. (CDM_Atrribute)


Prototype:int CDM_PutAttribute(CDM_Document Document, CDM_Attribute Attr);
Arguments:

Document: A Document object. (CDM_Document)
Attribute: The Attribute to be added. (CDM_Atrribute)


Prototype:CDM_Annotation CDM_PutAttribute(CDM_Annotation Ann, CDM_Attribute Attr);
Arguments:

Ann: Annotation Pointer. (CDM_Annotation)
Attribute: Attribute to be added (CDM_Atrribute)

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

Description:

int CDM_PutAttribute(CDM_Collection Collection, CDM_Attribute Attr):
This function will add a given Attribute to the specified Collection object. If an Attribute with the same name already exists in the Collection, then it will be overwritten by the new Attribute. Else, the new Attribute will be appended to the existing Attribute set of the specified Collection.

int CDM_PutAttribute(CDM_Document Document, CDM_Attribute Attr):
This function will add a given Attribute to the specified Document object. If an Attribute with the same name already exists in the Document, then it will be overwritten by the new Attribute. Else, the new Attribute will be appended to the existing Attribute set of the specified Document.

CDM_Annotation CDM_PutAttribute(CDM_Annotation Ann, CDM_Attribute Attr):
This function will add a given Attribute to the specified Annotation object. If an Attribute with the same name already exists in the Annotation, then it will be overwritten by the new Attribute. Else, the new Attribute will be appended to the existing Attribute set of the specified Annotation.

The returned value of this function may be a new Annotation object or the provided one. What the result will be depends on whether the provided Annotation is a shared object or not. If the provided Annotation is a shared object (i.e. Tcl_IsShared returns true) a new Annotation object will be created and returned, since a shared object cannot be modified. If the provided Annotation is not a shared object, then the required changes will be done in place, and the same Annotation object will be returned.

As a result, the caller should be always check the returned value, if he is the owner but does not want to keep the initial Annotation object. A typical use is shown in the following code:


      ann = CDM_CreateAnnotation("token", spanset, attrset);
      new_ann = CDM_PutAttribute(ann, Attr);
      if (new_ann != ann) {
        CDM_Free(ann);
        ann = new_ann;
      }
      CDM_AddAnnotation(Doc, ann); // Now CDM is the owner, we can forget about it...
      

Return Value:

int CDM_PutAttribute(CDM_Collection Collection, CDM_Attribute Attr):
The return value from this function will be a standart Tcl completion code (of type int) with one of the values TCL_OK and TCL_ERROR. If an error occurs, the return value will be TCL_ERROR and an error message describing the error will be left at the current Tcl interpreter (CDM_Interp). Else, TCL_OK will be returned.

int CDM_PutAttribute(CDM_Document Document, CDM_Attribute Attr):
The return value from this function will be a standart Tcl completion code (of type int) with one of the values TCL_OK and TCL_ERROR. If an error occurs, the return value will be TCL_ERROR and an error message describing the error will be left at the current Tcl interpreter (CDM_Interp). Else, TCL_OK will be returned.

CDM_Annotation CDM_PutAttribute(CDM_Annotation Ann, CDM_Attribute Attr):
This function will return an Annotation object (of type CDM_Annotation). The returned value of this function may be a new Annotation object or the provided one. What the result will be depends on whether the provided Annotation is a shared object or not. If the provided Annotation is a shared object (i.e. Tcl_IsShared returns true) a new Annotation object will be created and returned, since a shared object cannot be modified. If the provided Annotation is not a shared object, then the required changes will be done in place, and the same Annotation object will be returned.

Notes:

int CDM_PutAttribute(CDM_Collection Collection, CDM_Attribute Attr):
This function is equivelant to tip_PutAttribute (Tcl API).

int CDM_PutAttribute(CDM_Document Document, CDM_Attribute Attr):
This function is equivelant to tip_PutAttribute (Tcl API).

CDM_Annotation CDM_PutAttribute(CDM_Annotation Ann, CDM_Attribute Attr):
This function is equivelant to tip_PutAttribute (Tcl API).

See Also:

int CDM_PutAttribute(CDM_Collection Collection, CDM_Attribute Attr):
tip_PutAttribute

int CDM_PutAttribute(CDM_Document Document, CDM_Attribute Attr):
tip_PutAttribute

CDM_Annotation CDM_PutAttribute(CDM_Annotation Ann, CDM_Attribute Attr):
CDM_GetAttribute, CDM_GetAttributes, tip_PutAttribute Tcl_IsShared, Tcl_DecrRefCount


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