Find sets by traversing the subset inclusion lattice

saf_find_sets is a function defined in set.c.

Synopsis:

int saf_find_sets(SAF_ParMode pmode, SAF_FindSetMode fmode, SAF_Set *set, SAF_Cat *cat, int *num, SAF_Set **found)

Formal Arguments:

  • pmode: The parallel mode.
  • fmode: The find mode. Possible values are SAF__FSETS_TOP to find the top-level set in the subset inclusion lattice in which set is a member; SAF__FSETS_BOUNDARY to find the boundary of set set; SAF__FSETS_SUBS to find all sets which are immediate subsets of set by the specified collection category; SAF__FSETS_SUPS to find all sets which are immediate supersets of set by the specified collection category; and SAF__FSETS_LEAVES to find all leaf sets in the subset inclusion lattice rooted at set (a leaf set is a set that is a descendent of set by the specified collection category and which has no sets below it).
  • set: The set in the subset inclusion lattice at which to begin searching.
  • cat: The collection category upon which to search for subsets, supersets, or leaf sets.
  • num: For this and the succeeding argument [see Returned Handles].
  • found: For this and the preceding argument [see Returned Handles].

Description: There are two ways to search for sets. One is to simply search the whole database looking for sets that match a particular search criteria such as a name, base dimension, etc. which is handled by saf_find_matching_sets. The other is to search for sets by traversing the subset inclusion lattice which is handled by this function. This latter approach is typically faster as it involves only a portion of all sets in the database.

The possible modes to the find call are described below.

1
 FMODE==SAF_FSETS_TOP

This mode of the find will find the top-most ancestor of a given set.

1
 FMODE==SAF_FSETS_BOUNDARY

This mode of the find will find the boundary set of a given set. Note, currently this mode will return a boundary only if one exists in the file. It will not attempt to compute a boundary.

1
 FMODE==SAF_FSETS_SUBS

This mode will find all sets that are immediate subsets of the given set by the specified collection category, if any is specified. If the specified collection category is SAF__ANY_CAT, then all immediate subsets will be returned, regardless of category.

1
 FMODE=SAF_FSETS_SUPS

This mode will find all sets that are immediate supersets of the given set by the specified collection category, if any is specified. If the specified collection category is SAF__ANY_CAT, then all immediate supersets will be returned, regardless of category. Note, in typical cases, there is often only one superset of a given set by a given collection category.

1
 FMODE=SAF_FSETS_LEAVES

This mode finds all leaf sets in the subset inclusion lattice rooted at set (a leaf set is a set that is a descendent of set by the specified collection category and which has no sets below it. SAF__ANY_CAT is allowed to be the specified collection category.

Preconditions:

  • pmode must be valid. (low-cost)
  • set must be a valid set handle. (low-cost)
  • fmode must be SAF__FSETS… _TOP, _SUBS, _SUPS, _LEAVES or _BOUNDARY. (low-cost)
  • cat arg applicable only for SAF__FSETS_SUPS, SAF__FSETS_SUBS and SAF__FSETS_LEAVES modes. (low-cost)
  • num and found must be compatible for return value allocation. (low-cost)
  • num is required in a top-level SAF__FSETS_LEAVES mode call. (low-cost)

Return Value: The constant SAF__SUCCESS is returned when this function is successful. Otherwise this function either returns an error number or throws an exception, depending on the value of the library’s error handling property.

Issues: If fmode is SAF__FSETS_TOP, the memory allocation rules for SAF become irrelevant. If we confine ourselves to topological information (e.g. statements about base-space sets without respect to fields, particularly coordinate fields), then there is only ever one top (maximal ancestor) for any set. Of course, if we have two totally independent objects, say a hammer and a wall, such that the hammer has interpenetrated the wall, then the set that represents the intersection between the hammer and the wall is a subset of both. However, this intersection is a result of the fact that the hammer’s coordinate field places it inside the wall. In the purely topological setting, the sets that represent the hammer and the wall are each top sets. Thus, in theory the set that represents their intersection has two maximal ancestors. We do not worry about this case here. Thus, a query for SAF__FSETS_TOP is always a single set and so either the client asks for the single set handle to be allocated, or it does not.

If fmode is SAF__FSETS_BOUNDARY, some similar arguments apply. There is only ever one boundary of another set. Thus, if the client queries for the boundary, it is assumed the client has either allocated a single set handle or the library will and simply fill it in.

For the SAF__FSETS_TOP and SAF__FSETS_BOUNDARY cases, cat must be SAF__NOT_APPLICABLE_CAT.

This function looks for Relations only in the same scope that stores set and thus cannot traverse a subset inclusion lattice that extends outside that scope. [rpm 2004-06-21]

For a SAF__FSETS_LEAVES search with a null collection category (SAF__ANY_CAT) this function will return a list of unique sets by pruning out the duplicates. However, the pruning occurs down at the leaves and not in the internal nodes of the graph, and therefore we may end up traversing portions of the graph repeatedly. [rpm 2004-06-21]

See Also: