PK_TOPOL_ask_entities_by_attdef

PK_ERROR_code_t     PK_TOPOL_ask_entities_by_attdef
(
--- received arguments ---
PK_TOPOL_t          topol,          --- topological entity
PK_CLASS_t          class,          --- class of requested entities
PK_LOGICAL_t        have_attrib,    --- whether entities have an attribute
PK_ATTDEF_t         attdef,         --- attribute definition
                                    --- ( may be PK_ENTITY_null )

--- returned arguments ---
int          *const n_entities,     --- number of entities ( >= 0 )
PK_ENTITY_t **const entities        --- entities ( optional )
)


This function returns the set of 'entities' of the given 'class' which belong
to 'topol' and either do or do not have an attribute of the given 'attdef',
depending upon 'have_attrib'.


Specific Errors:
    PK_ERROR_wrong_entity       Topological entity not supported (MILD)
    PK_ERROR_bad_class          Given class is invalid           (MILD)


At present 'topol' is restricted to be of class PK_CLASS_body.

The output array 'entities' is optional.  If it is set to NULL, the function
will only compute the number of entities.

The function selects from all the entities belonging to the given 'topol' by
applying two filters:

 - class:  all returned 'entities' will belong to the given 'class'.
           'class' may be:

           PK_CLASS_face
           PK_CLASS_edge
           PK_CLASS_vertex
           PK_CLASS_region
           PK_CLASS_lattice
           PK_CLASS_surf    and all subclasses
           PK_CLASS_curve   and all subclasses
           PK_CLASS_point
           PK_CLASS_group

 - attdef: entities are also selected by whether or not they have particular
           attributes.  'attdef' may be set to an existing attribute
           definition, in which case selection is by whether or not an entity
           has an attribute of that attribute definition, or it may be set to
           PK_ENTITY_null, meaning an attribute of any attribute definition.
           If 'have_attrib' is set to PK_LOGICAL_true then selected entities
           will have an attribute as specified by 'attdef'.  If 'have_attrib'
           is set to PK_LOGICAL_false then selected entities will not have
           an attribute as specified by 'attdef'.