Sets |
Table of ContentsSets Abstract Revisions Introduction Naming Conventions Initialization Cell functions Unary Functions Binary Functions Comparison Functions Summary Initialization Utilities Unary Binary Comparison Set Relationships Sets
Abstract
Revisions
Introduction
A ``set'' is a character, integer, or double precision cell in which the following restrictions are observed:
"AB", "Ab", "aB", "ab".
[SPICE_CELL_CRTLSZ + 1] : [SPICE_CELL_CTRLSZ + n]
[SPICE_CELL_CRTLSZ + i]
SPICE_CELL_CTRLSZ
[SPICE_CELL_CRTLSZ + i]
[SPICE_CELL_CRTLSZ+i][0] : [SPICE_CELL_CRTLSZ+i][length-1]
Naming Conventions
Thus, insrtc_c inserts an element into a character set, insrtd_c inserts an element into a double precision set, and insrti_c inserts an element into an integer set. We will refer to a class of type-dependent set routines by taking the name of any routine in the class and substituting an x for the last letter. Thus, the function elemx_c may refer to elemc_c, elemd_c, or elemi_c. In specific contexts, we will use the specific names of routines. A number of the CSPICE set functions are truly generic; these functions operate on a CSPICE set of any data type. The names of generic set functions have no final character designating data type. For example, the generic function union_c computes the union of two CSPICE sets of any data type. Initialization
insrtc_c insrtd_c insrti_cHowever, when working with large sets, it may be more efficient to construct the set by populating the set's data array and then sorting the array and removing duplicate items. After the set's data array has been populated, the function valid_c may be used to sort and prune the array:
valid_c ( size, n, &set );Here size is the maximum allowed size of the set (normally the declared size of the data array) and n is the initial number of elements in the data array. Efficient population of the set's data array may be done using the CSPICE cell ``append'' routines, the CSPICE cell element assignment macros, or the element reference macros. See the Cells Required Reading, cells.req, for further information. An even faster, but lower level, approach would be to use memmove, supplying the set's void pointer member ``data'' as a target address. Cell functions
The CSPICE cell assignment, fetch, and element reference macros may be used to access data members of any CSPICE set. Note however that direct assignment of set elements may cause the set to become unordered or to contain duplicate items, in which case it cannot be used with the CSPICE set functions until it is validated. An example of using the CSPICE cardinality function to define a loop bound (where we also use the character cell element reference macro to point to the cell's data members):
printf ( "Winners of the Nobel Prize for Physics:\n" ); for ( i = 0; i < card_c(nobel); i++ ) { printf ( "%s\n", SPICE_CELL_ELEM_C( nobel, i ) ); }The integer function size_c returns the size (maximum cardinality) of a set. This is useful primarily for predicting situations in which overflow can occur. Unary Functions
"PLUTO"is removed from the character set `planets' and inserted into the character set `asteroids'.
removc_c ( "PLUTO", &planets ); insrtc_c ( "PLUTO", &asteroids );If
"PLUTO"is not an element of the set `planets', then the contents of `planets' are not changed. Similarly, if
"PLUTO"is already an element of `asteroids', the contents of `asteroids' remain unchanged. If a set is not large enough to accommodate the insertion of an element, the CSPICE error handling mechanism reports the excess. Binary Functions
The UNION of two sets contains every element which is in the first set, or in the second set, or in both sets.
{a,b} U {c,d} = {a,b,c,d} {a,b,c} U {b,c,d} = {a,b,c,d} {a,b,c,d} U {} = {a,b,c,d} {} U {a,b,c,d} = {a,b,c,d} {} U {} = {}The INTERSECTION of two sets contains every element which is in both the first set AND in the second set.
{a,b} * {c,d} = {} {a,b,c} * {b,c,d} = {b,c} {a,b,c,d} * {} = {} {} * {a,b,c,d} = {} {} * {} = {}The DIFFERENCE of two sets contains every element which is in the first set, but NOT in the second.
{a,b} - {c,d} = {a,b} {a,b,c} - {b,c,d} = {a} {a,b,c,d} - {} = {a,b,c,d} {} - {a,b,c,d} = {} {} - {} = {}The SYMMETRIC DIFFERENCE of two sets contains every element which is in the first set OR in the second set, but NOT in both sets.
{a,b} ^ {c,d} = {a,b,c,d} {a,b,c} ^ {b,c,d} = {a,d} {a,b,c,d} ^ {} = {a,b,c,d} {} ^ {a,b,c,d} = {a,b,c,d} {} ^ {} = {}Each of the functions takes two input sets and returns an output set. In CSPICE, the functions carrying out these operations are type-independent. The following calls
union_c ( &planets, &asteroids, &result ); inter_c ( &planets, &asteroids, &result ); diff_c ( &planets, &asteroids, &result ); sdiff_c ( &planets, &asteroids, &result );respectively place the union, intersection, difference, and symmetric difference of the character sets `planets' and `asteroids' into the character set `result'. In each case, if the output set `result' is not large enough to hold the result of the operation, as many elements as will fit are inserted into the set, and the CSPICE error handling mechanism reports the excess. In each of the binary functions, the output set must be distinct from both of the input sets. (All four of the binary operations can be performed in place, but not efficiently. Consequently, for the sake of consistency, none of the functions work in place.) For example, the following calls are invalid.
union_c ( ¤t, &new, ¤t ); inter_c ( &new, ¤t, ¤t );In each of the examples above, the function may or may not return an error. However, the results will almost certainly be wrong. Comparison Functions
PLANETS ASTEROIDS -------- ---------- "Earth" "Apollo" "Mars" "Ceres" "Pluto" "Venus"Then all of the following expressions are true.
elemc_c ( "Earth", &planets ) elemc_c ( "Pluto", &planets ) elemc_c ( "Ceres", &asteroids )And all of the following expressions are false.
elemc_c ( "Saturn", &planets ) elemc_c ( "Pluto", &asteroids ) elemc_c ( "CERES", &asteroids )The SpiceBoolean function set_c is true whenever the specified relationship between two sets exists, and is false otherwise. In the following example, set_c is used to repeat an operation for as long as the integer set `finished' remains a proper subset of the integer set `planned'.
while ( set_c( &finished, "<", &planned ) ) { . . . }The full list of valid operators is given below.
Operator is read -------- --------------------------------------------- "=" "is equal to (contains the same elements as)" "<>" "is not equal to" "<=" "is a subset of" "<" "is a proper subset of" ">=" "is a superset of" ">" "is a proper superset of"Let the integer sets `a', `b', and `c' contain the following elements. Let `e' be an empty integer set.
a b c --- --- --- 1 1 1 2 3 3 3 4Then all of the following expressions are true.
set_c ( &b, "=", &c ) "b is equal to c" set_c ( &a, "<>", &c ) "a is not equal to c" set_c ( &a, ">", &b ) "a is a proper superset of b" set_c ( &b, "<=", &c ) "b is a subset of c" set_c ( &c, "<=", &b ) "c is a subset of b" set_c ( &a, "<=", &a ) "a is a subset of a" set_c ( &e, "<=", &b ) "e is a subset of b" set_c ( &e, "<", &b ) "e is a proper subset of b" set_c ( &e, "<=", &e ) "e is a subset of e"And all of the following are false.
set_c ( &b, "<>", &c ) "b is not equal to c" set_c ( &a, "=", &c ) "a is equal to c" set_c ( &a, "<", &b ) "a is a proper subset of b" set_c ( &b, "<", &c ) "b is a proper subset of c" set_c ( &b, ">=", &a ) "b is a superset of a" set_c ( &a, ">", &a ) "a is a proper superset of a" set_c ( &e, ">=", &a ) "e is a superset of a" set_c ( &e, "<", &e ) "e is a proper subset of e" Summary
Initialization
Utilities
Unary
Binary
Comparison
Set Relationships
= is equal to (contains the same elements as) <> is not equal to <= is a subset of < is a proper subset of >= is a superset of > is a proper superset of |