[MOAB-announce] MOAB API changed relating to tags

[Jason Kraftcheck]

The following is a list of upcoming changes to the subset of the MOAB API
that operates on tags.  The primary focus of this set of changes is to
provide better type safety for tag data and to transition from working with
tag sizes specified as the number of bytes to tag sizes specified as the
number of values.  However, some other minor changes have also been included.

Changes to be included in MOAB 4.1:

1. MOAB will now print a warning if a NULL handle array is passed to
   tag_get/set_handle.  It will still accept the NULL handle array as
   a means of indicating the tag value on the MOAB instance.  However,
   the preferred method is to pass an actual handle with a zero value,
   consistent with the way the MOAB instance is indicated in other calls
   such as get_entities_by_type.  That is:
     mb.tag_get_data( tag, 0, 0, &value );
   should now be:
     const EntityHandle root = 0;
     mb.tag_get_data( tag, &root, 1, &value );

2. MOAB contains a new tag_get_handle function that will replace the
   previous tag_get_handle function as well as both variations of
   tag_create and tag_create_variable_length.  All the functionality
   of all of those functions is available through the new tag_get_handle
   function.  The new function provides the added benefits of a) allowing
   an application to specify that it is fine with either creating a new tag
   or getting an existing one, such that the function either succeeds or
   fails (no checking of MB_ALREADY_ALLOCATED), b) it works with sizes as
   the number of values of the specified type rather than the number of
   bytes and c) it does some type checking for the application when
   retrieving an existing tag handle.  For example, this call:
     mb.tag_get_handle( GLOBAL_ID_TAG_NAME, tag );
   becomes this:
     mb.tag_get_handle( GLOBAL_ID_TAG_NAME, 1, MB_TYPE_INTEGER, tag );
   where an error will be returned if the tag exists but does not contain
   1 integer value for each instance of the tag on an entity.

Changes to be included in the next MOAB release (and in the current SVN trunk):

1. The change in 1. for 4.1 will be extended such that MOAB returns an error
   rather than printing a warning when tag_get/set_data are passed a NULL
   handle array.

2. All functions replaced by the new tag_get_handle in 2. above are marked
   as deprecated in the documentation and with a gcc/g++ attribute.

3. tag_get_size will be marked as deprecated and two new replacements will
   be added: tag_get_bytes() and tag_get_length().  The former will work
   the same as the deprecated tag_get_size() except in the case of bit
   tags, for which it will always return 1 (the amount of memory that must
   be allocated per entity when requesting tag data.)  The latter will
   return the number of values of the base data type (e.g. number of int
   or double).  It will behave the same as the old tag_get_size and
   tag_get_bytes for opaque tags.

4. The overloaded variants of tag_get_data and tag_set_data that work with
   an array of pointers and an optional array of sizes will be marked as
   deprecated, and replacements named tag_get_by_ptr and tag_set_by_ptr will
   be added.  The new functions will behave similar to the deprecated ones
   with the exception that the size of each tag value is interpreted as the
   number of values rather than the number of bytes.  Also, renaming the
   functions will avoid accidental matches to the non-pointer-array function
   variants when the optional size array is not passed.

5. The optional size argument to the functions: tag_clear_data and
   tag_get_default_value will be interpreted as the number of values
   of the tag data type rather than the number of bytes.  No deprecation,
   warning, or renaming will provided for these functions as it is
   unlikely that they are used anywhere outside of MOAB at this time.

All deprecated functions mentioned above will be removed in some future MOAB
release.