Find set by matching criteria

saf_find_matching_sets is a function defined in set.c.

Synopsis:

int saf_find_matching_sets(SAF_ParMode pmode, SAF_Db *db, const char *name_grep, SAF_SilRole srole, int tdim, SAF_ExtendMode extmode, SAF_TopMode topmode, int *num, SAF_Set **found)

Formal Arguments:

  • pmode: The parallel mode.
  • db: The database in which to search
  • name_grep: The name of the desired set(s) or a limited regular expression that the set names must match. If this argument begins with a leading “at sign”, ‘@’, character, the remaining characters will be treated as a limited form of a regular expression akin to that supported by ‘ed.’ The constant SAF__ANY_NAME can be passed if the client does not want to limit the search by name.
  • srole: The subset inclusion lattice role of the desired set(s). The SAF__ANY_SILROLE constant can be passed if the client is not interested in restricting the search on this criteria.
  • tdim: The topological dimension of the desired set(s). The SAF__ANY_TOPODIM constant can be passed if the client is not interested in restricting the search on this criteria.
  • extmode: User to specify if the set is extendible or not (whether it can grow or not). Pass SAF__EXTENDIBLE_TRUE, SAF__EXTENDIBLE_FALSE, or SAF__EXTENDIBLE_TORF
  • topmode: whether the matching sets should be top sets. Pass SAF__TOP_TRUE, SAF__TOP_FALSE, or SAF__TOP_TORF
  • num: For this and the succeeding argument [see Returned Handles].
  • found: For this and the preceding argument [see Returned Handles].

Description: This function will find sets by searching the entire database and matching certain criteria. Because it finds sets by matching criteria, this function does not exploit the subset inclusion lattice to improve performance.

If the name_grep argument begins with a leading “at sign” character, ‘@’, the remaining characters will be treated as a limited form of a regular expression akin to that supported in ‘ed’. Otherwise, it will be treated as a specific name for a set. If the name does not matter, pass SAF__ANY_NAME.

If the library was not compiled with -lgen support library, then if regular expressions are used, the library will behave as though SAF__ANY_NAME was specified.

Preconditions:

  • pmode must be valid. (low-cost)
  • DATABASE must be a database handle. (low-cost)
  • The srole must be one of SAF__TIME, SAF__SPACE, SAF__PARAM, or SAF__ANY_SILROLE. (low-cost)
  • If srole is TIME then tdim must be 1. (low-cost)
  • tdim must be SAF__ANY_TOPODIM or positive. (low-cost)
  • extmode cannot be arbitrarily non-zero for truth. (low-cost)
  • topmode cannot be arbitrarily non-zero for truth. (low-cost)
  • num and found must be compatible for return value allocation. (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.

See Also:

  • Sets: Introduction for current chapter