Function
Delete components of a Field.
Syntax
#include <dx/dx.h> Field DXChangedComponentValues(Field f, char *component) Field DXChangedComponentStructure(Field f, char *component)
Functional Details
DXChangedComponentValues deletes all the components of f that have a "der" attribute naming the specified component component. This routine is typically used when the values of the items of an Array change (e.g., the values of the "data" component) but not the number of items.
DXChangedComponentStructure deletes all the components of f that have a "dep," "der," or "ref" attribute naming the specified component component. This routine is typically used when the number of items in an Array (e.g., the number of items in the "positions" component) has been changed.
Both of these routines recursively apply DXChangedComponentStructure to the components they delete. They ensure that Fields remain internally consistent when they are altered.
By deleting components derived from a changed component, a call to DXChangedComponentValues ensures that the derived component will be recalculated when necessary and will remain up-to-date. For example, the "data statistics" component is derived from the "data" component. If the "data" component is changed, the current contents of data statistics become invalid. A call to DXChangedComponentValues(field, "data") will delete data statistics, and the values will be recomputed on the next call to DXStatistics.
Similarly, DXChangedComponentStructure ensures that components that depend on, refer to, or are derived from another component will be as up-to-date as possible. For example, the "connections" component refers to the "positions" component. If the structure of the "positions" component is changed, perhaps by deleting a position, the references in the "connections" component that are indices into the "positions" component cease to apply. Rather than leave an invalid "connections" component in the Field, it is better to remove it by calling DXChangedComponentStructure.
| Note: | Most components depend on, refer to, or are derived from others. These routines may cause important information to be discarded. It is often better to correct the component that has a "dep," "der," or "ref" attribute than to delete it. In the example just described, you can avoid deleting the "connections" component when a point is deleted from the "positions" component by deleting all connections elements that refer to the discarded position and remapping the remaining references to reflect the moved points in the "positions" component. |
Return Value
Returns f or returns NULL and sets an error code.
See Also
DXEndField, DXGetComponentValue, DXSetComponentValue