void ckcov_c ( ConstSpiceChar * ck,
SpiceInt idcode,
SpiceBoolean needav,
ConstSpiceChar * level,
SpiceDouble tol,
ConstSpiceChar * timsys,
SpiceCell * cover )
/*
-Brief_I/O
Variable I/O Description
-------- --- --------------------------------------------------
ck I Name of CK file.
idcode I ID code of object.
needav I Flag indicating whether angular velocity is needed.
level I Coverage level: "SEGMENT" OR "INTERVAL".
tol I Tolerance in ticks.
timsys I Time system used to represent coverage.
cover I/O Window giving coverage for `idcode'.
-Detailed_Input
ck is the name of a C-kernel.
idcode is the integer ID code of an object, normally a
spacecraft structure or instrument, for which
pointing data are expected to exist in the specified
CK file.
needav is a logical variable indicating whether only
segments having angular velocity are to be considered
when determining coverage. When `needav' is
SPICETRUE, segments without angular velocity don't
contribute to the coverage window; when `needav' is
SPICEFALSE, all segments for `idcode' may contribute
to the coverage window.
level is the level (granularity) at which the coverage
is examined. Allowed values and corresponding
meanings are:
"SEGMENT" The output coverage window contains
intervals defined by the start and
stop times of segments for the object
designated by `idcode'.
"INTERVAL" The output coverage window contains
interpolation intervals of segments
for the object designated by
`idcode'. For type 1 segments, which
don't have interpolation intervals,
each epoch associated with a pointing
instance is treated as a singleton
interval; these intervals are added
to the coverage window.
All interpolation intervals are
considered to lie within the segment
bounds for the purpose of this
summary: if an interpolation
interval extends beyond the segment
coverage interval, only its
intersection with the segment
coverage interval is considered to
contribute to the total coverage.
tol is a tolerance value expressed in ticks of the
spacecraft clock associated with IDCODE. Before each
interval is inserted into the coverage window, the
interval is intersected with the segment coverage
interval, then if the intersection is non-empty, it
is expanded by `tol': the left endpoint of the
intersection interval is reduced by `tol' and the
right endpoint is increased by `tol'. Adjusted
interval endpoints, when expressed as encoded SCLK,
never are less than zero ticks. Any intervals that
overlap as a result of the expansion are merged.
The coverage window returned when tol > 0 indicates
the coverage provided by the file to the CK readers
ckgpav_c and ckgp_c when that value of `tol' is
passed to them as an input.
timsys is a string indicating the time system used in the
output coverage window. `timsys' may have the
values:
"SCLK" Elements of `cover' are expressed in
encoded SCLK ("ticks"), where the
clock is associated with the object
designated by `idcode'.
"TDB" Elements of `cover' are expressed as
seconds past J2000 TDB.
cover is an initialized CSPICE window data structure.
`cover' optionally may contain coverage data on
input; on output, the data already present in `cover'
will be combined with coverage found for the object
designated by `idcode' in the file `ck'.
If `cover' contains no data on input, its size and
cardinality still must be initialized.
-Detailed_Output
cover is a CSPICE window data structure which represents
the merged coverage for `idcode'. When the coverage
level is "INTERVAL", this is the set of time
intervals for which data for `idcode' are present in
the file `ck', merged with the set of time intervals
present in `cover' on input. The merged coverage is
represented as the union of one or more disjoint time
intervals. The window `cover' contains the pairs of
endpoints of these intervals.
When the coverage level is "SEGMENT", `cover' is
computed in a manner similar to that described above,
but the coverage intervals used in the computation
are those of segments rather than interpolation
intervals within segments.
When `tol' is > 0, the intervals comprising the
coverage window for `idcode' are expanded by `tol'
and any intervals overlapping as a result are merged.
The resulting window is returned in `cover'. The
expanded window in no case extends beyond the segment
bounds in either direction by more than `tol'.
The interval endpoints contained in `cover' are
encoded spacecraft clock times if `timsys' is "SCLK";
otherwise the times are converted from encoded
spacecraft clock to seconds past J2000 TDB.
See the Examples section below for a complete example
program showing how to retrieve the endpoints from
`cover'.
-Parameters
None.
-Exceptions
1) If the input file has transfer format, the error
SPICE(INVALIDFORMAT) is signaled.
2) If the input file is not a transfer file but has architecture
other than DAF, the error SPICE(BADARCHTYPE) is signaled.
3) If the input file is a binary DAF file of type other than
CK, the error SPICE(BADFILETYPE) is signaled.
4) If the CK file cannot be opened or read, the error will
be diagnosed by routines called by this routine. The output
window will not be modified.
5) If the size of the output window argument `cover' is
insufficient to contain the actual number of intervals in the
coverage window for `idcode', the error will be diagnosed by
routines called by this routine.
6) If `tol' is negative, the error SPICE(VALUEOUTOFRANGE) is
signaled.
7) If `level' is not recognized, the error SPICE(INVALIDOPTION)
is signaled.
8) If `timsys' is not recognized, the error SPICE(INVALIDOPTION)
is signaled.
9) If a time conversion error occurs, the error will be
diagnosed by a routine in the call tree of this routine.
10) If the output time system is TDB, the CK subsystem must be
able to map `idcode' to the ID code of the associated
spacecraft clock. If this mapping cannot be performed, the
error will be diagnosed by a routine in the call tree of this
routine.
11) The error SPICE(EMPTYSTRING) is signaled if any of the input
strings `ck', `level', or `timsys' do not contain at least one
character, since such an input string cannot be converted to a
Fortran-style string in this case.
12) The error SPICE(NULLPOINTER) is signaled if the if any of the input
strings `ck', `level', or `timsys' are null.
-Files
This routine reads a C-kernel.
If the output time system is "TDB", then a leapseconds kernel
and an SCLK kernel for the spacecraft clock associated with
`idcode' must be loaded before this routine is called.
If the ID code of the clock associated with `idcode' is not
equal to
idcode / 1000
then the kernel variable
CK_<idcode>_SCLK
must be present in the kernel pool to identify the clock
associated with `idcode'. This variable must contain the ID code
to be used for conversion between SCLK and TDB. Normally this
variable is provided in a text kernel loaded via furnsh_c.
-Particulars
This routine provides an API via which applications can determine
the coverage a specified CK file provides for a specified
object.
-Examples
1) Display the interval-level coverage for each object in a
specified CK file. Use tolerance of zero ticks. Do not request
angular velocity. Express the results in the TDB time system.
Find the set of objects in the file. Loop over the contents of
the ID code set: find the coverage for each item in the set and
display the coverage.
#include <stdio.h>
#include "SpiceUsr.h"
int main()
{
/.
Local parameters
./
#define FILSIZ 256
#define MAXIV 100000
#define WINSIZ ( 2 * MAXIV )
#define TIMLEN 51
#define MAXOBJ 1000
/.
Local variables
./
SPICEDOUBLE_CELL ( cover, WINSIZ );
SPICEINT_CELL ( ids, MAXOBJ );
SpiceChar ck [ FILSIZ ];
SpiceChar lsk [ FILSIZ ];
SpiceChar sclk [ FILSIZ ];
SpiceChar timstr [ TIMLEN ];
SpiceDouble b;
SpiceDouble e;
SpiceInt i;
SpiceInt j;
SpiceInt niv;
SpiceInt obj;
/.
Load a leapseconds kernel and SCLK kernel for output time
conversion. Note that we assume a single spacecraft clock is
associated with all of the objects in the CK.
./
prompt_c ( "Name of leapseconds kernel > ", FILSIZ, lsk );
furnsh_c ( lsk );
prompt_c ( "Name of SCLK kernel > ", FILSIZ, sclk );
furnsh_c ( sclk );
/.
Get name of CK file.
./
prompt_c ( "Name of CK file > ", FILSIZ, ck );
/.
Find the set of objects in the CK file.
./
ckobj_c ( ck, &ids );
/.
We want to display the coverage for each object. Loop over
the contents of the ID code set, find the coverage for
each item in the set, and display the coverage.
./
for ( i = 0; i < card_c( &ids ); i++ )
{
/.
Find the coverage window for the current object.
Empty the coverage window each time so we don't
include data for the previous object.
./
obj = SPICE_CELL_ELEM_I( &ids, i );
scard_c ( 0, &cover );
ckcov_c ( ck, obj, SPICEFALSE,
"INTERVAL", 0.0, "TDB", &cover );
/.
Get the number of intervals in the coverage window.
./
niv = wncard_c( &cover );
/.
Display a simple banner.
./
printf ( "%s\n", "========================================" );
printf ( "Coverage for object %ld\n", obj );
/.
Convert the coverage interval start and stop times to TDB
calendar strings.
./
for ( j = 0; j < niv; j++ )
{
/.
Get the endpoints of the jth interval.
./
wnfetd_c ( &cover, j, &b, &e );
/.
Convert the endpoints to TDB calendar
format time strings and display them.
./
timout_c ( b,
"YYYY MON DD HR:MN:SC.###### (TDB) ::TDB",
TIMLEN,
timstr );
printf ( "\n"
"Interval: %ld\n"
"Start: %s\n",
j,
timstr );
timout_c ( e,
"YYYY MON DD HR:MN:SC.###### (TDB) ::TDB",
TIMLEN,
timstr );
printf ( "Stop: %s\n", timstr );
}
printf ( "%s\n", "========================================" );
}
return ( 0 );
}
2) Find the segment-level coverage for the object designated by
IDCODE provided by the set of CK files loaded via a metakernel.
(The metakernel must also specify leapseconds and SCLK kernels.)
Use tolerance of zero ticks. Do not request angular velocity.
Express the results in the TDB time system.
#include <stdio.h>
#include "SpiceUsr.h"
int main()
{
/.
Local parameters
./
#define FILSIZ 256
#define LNSIZE 81
#define MAXCOV 100000
#define WINSIZ ( 2 * MAXCOV )
#define TIMLEN 51
/.
Local variables
./
SPICEDOUBLE_CELL ( cover, WINSIZ );
SpiceBoolean found;
SpiceChar file [ FILSIZ ];
SpiceChar idch [ LNSIZE ];
SpiceChar meta [ FILSIZ ];
SpiceChar source [ FILSIZ ];
SpiceChar timstr [ TIMLEN ];
SpiceChar type [ LNSIZE ];
SpiceDouble b;
SpiceDouble e;
SpiceInt count;
SpiceInt handle;
SpiceInt i;
SpiceInt idcode;
SpiceInt niv;
/.
Prompt for the metakernel name; load the metakernel.
The metakernel lists the CK files whose coverage
for `idcode' we'd like to determine. The metakernel
must also specify a leapseconds kernel and an SCLK
kernel for the clock associated with `idcode'.
./
prompt_c ( "Name of metakernel > ", FILSIZ, meta );
furnsh_c ( meta );
/.
Get the ID code of interest.
./
prompt_c ( "Enter ID code > ", LNSIZE, idch );
prsint_c ( idch, &idcode );
/.
Find out how many kernels are loaded. Loop over the
kernels: for each loaded CK file, add its coverage
for `idcode', if any, to the coverage window.
./
ktotal_c ( "CK", &count );
for ( i = 0; i < count; i++ )
{
kdata_c ( i, "CK", FILSIZ,
LNSIZE, FILSIZ, file,
type, source, &handle, &found );
ckcov_c ( file, idcode, SPICEFALSE,
"SEGMENT", 0.0, "TDB", &cover );
}
/.
Display results.
Get the number of intervals in the coverage window.
./
niv = wncard_c( &cover );
/.
Display a simple banner.
./
printf ( "\nCoverage for object %ld\n", idcode );
/.
Convert the coverage interval start and stop times to TDB
calendar strings.
./
for ( i = 0; i < niv; i++ )
{
/.
Get the endpoints of the ith interval.
./
wnfetd_c ( &cover, i, &b, &e );
/.
Convert the endpoints to TDB calendar
format time strings and display them.
./
timout_c ( b,
"YYYY MON DD HR:MN:SC.###### (TDB) ::TDB",
TIMLEN,
timstr );
printf ( "\n"
"Interval: %ld\n"
"Start: %s\n",
i,
timstr );
timout_c ( e,
"YYYY MON DD HR:MN:SC.###### (TDB) ::TDB",
TIMLEN,
timstr );
printf ( "Stop: %s\n", timstr );
}
return ( 0 );
}
-Restrictions
1) When this routine is used to accumulate coverage for `idcode'
provided by multiple CK files, the inputs `needav', `level', `tol',
and `timsys' must have the same values for all files in order
for the result to be meaningful.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
-Version
-CSPICE Version 1.0.1, 30-NOV-2007 (NJB)
Corrected bug in first example program in header:
program now empties result window prior to collecting
data for each object. Updated examples to use wncard_c
rather than card_c. Updated second example to demonstrate
segment-level summary capability.
-CSPICE Version 1.0.0, 07-JAN-2005 (NJB)
-Index_Entries
get coverage window for ck object
-&
*/
{ /* Begin ckcov_c */
/*
Local variables
*/
logical need;
/*
Participate in error tracing.
*/
if ( return_c() )
{
return;
}
chkin_c ( "ckcov_c" );
/*
Check the input string `ck' to make sure the pointer is non-null
and the string length is non-zero.
*/
CHKFSTR ( CHK_STANDARD, "ckcov_c", ck );
/*
Check the input string `level' to make sure the pointer is non-null
and the string length is non-zero.
*/
CHKFSTR ( CHK_STANDARD, "ckcov_c", level );
/*
Check the input string `timsys' to make sure the pointer is non-null
and the string length is non-zero.
*/
CHKFSTR ( CHK_STANDARD, "ckcov_c", timsys );
/*
Make sure cell data type is d.p.
*/
CELLTYPECHK ( CHK_STANDARD, "ckcov_c", SPICE_DP, cover );
/*
Initialize the cell if necessary.
*/
CELLINIT ( cover );
/*
Call the f2c'd Fortran routine.
*/
need = needav;
ckcov_ ( ( char * ) ck,
( integer * ) &idcode,
( logical * ) &need,
( char * ) level,
( doublereal * ) &tol,
( char * ) timsys,
( doublereal * ) (cover->base),
( ftnlen ) strlen(ck),
( ftnlen ) strlen(level),
( ftnlen ) strlen(timsys) );
/*
Sync the output cell.
*/
if ( !failed_c() )
{
zzsynccl_c ( F2C, cover );
}
chkout_c ( "ckcov_c" );
} /* End ckcov_c */
void pckcov_c ( ConstSpiceChar * pck,
SpiceInt idcode,
SpiceCell * cover )
/*
-Brief_I/O
Variable I/O Description
-------- --- --------------------------------------------------
pck I Name of PCK file.
idcode I Class ID code of PCK reference frame.
cover I/O Window giving coverage in `pck' for `idcode'.
-Detailed_Input
pck is the name of a binary PCK file.
idcode is the integer frame class ID code of a PCK reference
frame for which data are expected to exist in the
specified PCK file.
cover is an initialized CSPICE window data structure.
`cover' optionally may contain coverage data on
input; on output, the data already present in `cover'
will be combined with coverage found for the
reference frame designated by `idcode' in the file
`pck'.
If `cover' contains no data on input, its size and
cardinality still must be initialized.
-Detailed_Output
cover is a CSPICE window data structure which represents
the merged coverage for the reference frame having
frame class ID `idcode'. This is the set of time
intervals for which data for `idcode' are present in
the file `pck', merged with the set of time intervals
present in `cover' on input. The merged coverage is
represented as the union of one or more disjoint time
intervals. The window `cover' contains the pairs of
endpoints of these intervals.
The interval endpoints contained in `cover' are
ephemeris times, expressed as seconds past J2000
TDB.
See the Examples section below for a complete
example program showing how to retrieve the
endpoints from `cover'.
-Parameters
None.
-Exceptions
1) If the input file has transfer format, the error
SPICE(INVALIDFORMAT) is signaled.
2) If the input file is not a transfer file but has architecture
other than DAF, the error SPICE(BADARCHTYPE) is signaled.
3) If the input file is a binary DAF file of type other than
PCK, the error SPICE(BADFILETYPE) is signaled.
4) If the PCK file cannot be opened or read, the error will
be diagnosed by routines called by this routine. The output
window will not be modified.
5) If the size of the output window argument COVER is
insufficient to contain the actual number of intervals in the
coverage window for IDCODE, the error will be diagnosed by
routines called by this routine.
6) The error SPICE(EMPTYSTRING) is signaled if the input
string `pck' does not contain at least one character, since the
input string cannot be converted to a Fortran-style string in
this case.
7) The error SPICE(NULLPOINTER) is signaled if the input string
pointer `pck' is null.
-Files
This routine reads a PCK file.
-Particulars
This routine provides an API via which applications can determine
the coverage a specified PCK file provides for a specified
PCK class reference frame.
-Examples
1) This example demonstrates combined usage of pckcov_c and the
related PCK utility pckfrm_c.
Display the coverage for each object in a specified PCK file.
Find the set of objects in the file; for each object, find
and display the coverage.
#include <stdio.h>
#include "SpiceUsr.h"
int main()
{
/.
Local parameters
./
#define FILSIZ 256
#define MAXIV 1000
#define WINSIZ ( 2 * MAXIV )
#define TIMLEN 51
#define MAXOBJ 1000
/.
Local variables
./
SPICEDOUBLE_CELL ( cover, WINSIZ );
SPICEINT_CELL ( ids, MAXOBJ );
SpiceChar lsk [ FILSIZ ];
SpiceChar pck [ FILSIZ ];
SpiceChar timstr [ TIMLEN ];
SpiceDouble b;
SpiceDouble e;
SpiceInt i;
SpiceInt j;
SpiceInt niv;
SpiceInt obj;
/.
Load a leapseconds kernel for output time conversion.
PCKCOV itself does not require a leapseconds kernel.
./
prompt_c ( "Name of leapseconds kernel > ", FILSIZ, lsk );
furnsh_c ( lsk );
/.
Get name of PCK file.
./
prompt_c ( "Name of PCK file > ", FILSIZ, pck );
/.
Find the set of frames in the PCK file.
./
pckfrm_c ( pck, &ids );
/.
We want to display the coverage for each frame. Loop over
the contents of the ID code set, find the coverage for
each item in the set, and display the coverage.
./
for ( i = 0; i < card_c( &ids ); i++ )
{
/.
Find the coverage window for the current frame.
Empty the coverage window each time so we don't
include data for the previous frame.
./
obj = SPICE_CELL_ELEM_I( &ids, i );
scard_c ( 0, &cover );
pckcov_c ( pck, obj, &cover );
/.
Get the number of intervals in the coverage window.
./
niv = wncard_c ( &cover );
/.
Display a simple banner.
./
printf ( "%s\n", "========================================" );
printf ( "Coverage for frame %ld\n", obj );
/.
Convert the coverage interval start and stop times to TDB
calendar strings.
./
for ( j = 0; j < niv; j++ )
{
/.
Get the endpoints of the jth interval.
./
wnfetd_c ( &cover, j, &b, &e );
/.
Convert the endpoints to TDB calendar
format time strings and display them.
./
timout_c ( b,
"YYYY MON DD HR:MN:SC.### (TDB) ::TDB",
TIMLEN,
timstr );
printf ( "\n"
"Interval: %ld\n"
"Start: %s\n",
j,
timstr );
timout_c ( e,
"YYYY MON DD HR:MN:SC.### (TDB) ::TDB",
TIMLEN,
timstr );
printf ( "Stop: %s\n", timstr );
}
}
return ( 0 );
}
2) Find the coverage for the frame designated by `idcode'
provided by the set of PCK files loaded via a metakernel.
(The metakernel must also specify a leapseconds kernel.)
#include <stdio.h>
#include "SpiceUsr.h"
int main()
{
/.
Local parameters
./
#define FILSIZ 256
#define LNSIZE 81
#define MAXCOV 100000
#define WINSIZ ( 2 * MAXCOV )
#define TIMLEN 51
/.
Local variables
./
SPICEDOUBLE_CELL ( cover, WINSIZ );
SpiceBoolean found;
SpiceChar file [ FILSIZ ];
SpiceChar idch [ LNSIZE ];
SpiceChar meta [ FILSIZ ];
SpiceChar source [ FILSIZ ];
SpiceChar timstr [ TIMLEN ];
SpiceChar type [ LNSIZE ];
SpiceDouble b;
SpiceDouble e;
SpiceInt count;
SpiceInt handle;
SpiceInt i;
SpiceInt idcode;
SpiceInt niv;
/.
Prompt for the metakernel name; load the metakernel.
The metakernel lists the PCK files whose coverage
for `idcode' we'd like to determine. The metakernel
must also specify a leapseconds kernel.
./
prompt_c ( "Name of metakernel > ", FILSIZ, meta );
furnsh_c ( meta );
/.
Get the ID code of interest.
./
prompt_c ( "Enter ID code > ", LNSIZE, idch );
prsint_c ( idch, &idcode );
/.
Find out how many kernels are loaded. Loop over the
kernels: for each loaded PCK file, add its coverage
for `idcode', if any, to the coverage window.
./
ktotal_c ( "PCK", &count );
for ( i = 0; i < count; i++ )
{
kdata_c ( i, "PCK", FILSIZ, LNSIZE, FILSIZ,
file, type, source, &handle, &found );
pckcov_c ( file, idcode, &cover );
}
/.
Display results.
Get the number of intervals in the coverage window.
./
niv = wncard_c ( &cover );
/.
Display a simple banner.
./
printf ( "\nCoverage for frame %ld\n", idcode );
/.
Convert the coverage interval start and stop times to TDB
calendar strings.
./
for ( i = 0; i < niv; i++ )
{
/.
Get the endpoints of the ith interval.
./
wnfetd_c ( &cover, i, &b, &e );
/.
Convert the endpoints to TDB calendar
format time strings and display them.
./
timout_c ( b,
"YYYY MON DD HR:MN:SC.### (TDB) ::TDB",
TIMLEN,
timstr );
printf ( "\n"
"Interval: %ld\n"
"Start: %s\n",
i,
timstr );
timout_c ( e,
"YYYY MON DD HR:MN:SC.### (TDB) ::TDB",
TIMLEN,
timstr );
printf ( "Stop: %s\n", timstr );
}
return ( 0 );
}
-Restrictions
1) If an error occurs while this routine is updating the window
`cover', the window may be corrupted.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
-Version
-CSPICE Version 1.0.1, 01-JUL-2014 (NJB)
Updated index entries.
-CSPICE Version 1.0.0, 30-NOV-2007 (NJB)
-Index_Entries
get coverage window for binary pck reference frame
get coverage start and stop time for binary pck frame
-&
*/
{ /* Begin pckcov_c */
/*
Participate in error tracing.
*/
if ( return_c() )
{
return;
}
chkin_c ( "pckcov_c" );
/*
Check the input string `pck' to make sure the pointer is non-null
and the string length is non-zero.
*/
CHKFSTR ( CHK_STANDARD, "pckcov_c", pck );
/*
Make sure cell data type is d.p.
*/
CELLTYPECHK ( CHK_STANDARD, "pckcov_c", SPICE_DP, cover );
/*
Initialize the cell if necessary.
*/
CELLINIT ( cover );
/*
Call the f2c'd Fortran routine.
*/
pckcov_ ( ( char * ) pck,
( integer * ) &idcode,
( doublereal * ) (cover->base),
( ftnlen ) strlen(pck) );
/*
Sync the output cell.
*/
if ( !failed_c() )
{
zzsynccl_c ( F2C, cover );
}
chkout_c ( "pckcov_c" );
} /* End pckcov_c */
SpiceInt ordd_c ( SpiceDouble item,
SpiceCell * set )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
item I An item to locate within a set.
set I A set to search for a given item.
The function returns the ordinal position of item within the set.
-Detailed_Input
item is a double precision number to be located within a set.
set is a double precision CSPICE set that is to be searched
for the occurrence of item.
set must be declared as a double precision SpiceCell.
-Detailed_Output
The function returns the ordinal position of item within set.
Ordinal positions range from 0 to N-1, where N is the cardinality
of the set.
If item is not an element of set, the function returns -1.
-Parameters
None.
-Exceptions
1) If the input set argument is a SpiceCell of type other than
double precision, the error SPICE(TYPEMISMATCH) is signaled.
2) If the input set argument does not qualify as a CSPICE set,
the error SPICE(NOTASET) will be signaled. CSPICE sets have
their data elements sorted in increasing order and contain
no duplicate data elements.
-Files
None.
-Particulars
A natural ordering can be imposed upon the elements of any
CSPICE set, be it integer, character or double precision. For
character strings the ASCII collating sequence serves as the
ordering relation, for double precision and integer variables
the arithmetic ordering is used.
Given any element of a set, its location within this ordered
sequence of elements is called its ordinal position within
the set.
In common mathematical usage, ordinal positions of elements
in a set of cardinality N range from 1 to N. In C programs,
it is much more convenient to use the range 0 to N-1; this is
the convention used in CSPICE.
For illustrative purposes suppose that set represents the set
{ 8, 1, 2, 9, 7, 4, 10 }
The ordinal position of:
8 is 4
1 is 0
2 is 1
9 is 5
7 is 3
4 is 2
10 is 6
-Examples
1) Obtain the ordinal positions shown in the table of the Particulars
section above.
#include "SpiceUsr.h"
int main()
{
/.
Declare a double precision set and populate it with
the elements shown above.
./
#define MAXSIZ 7
SPICEDOUBLE_CELL ( set, MAXSIZ );
SpiceDouble inputs [MAXSIZ] =
{
8.0, 1.0, 2.0, 9.0, 7.0, 4.0, 10.0
};
SpiceDouble expected [MAXSIZ] =
{
4.0, 0.0, 1.0, 5.0, 3.0, 2.0, 6.0
};
SpiceInt i;
SpiceDouble dElt;
/.
Create the set.
./
for ( i = 0; i < MAXSIZ; i++ )
{
insrtd_c ( inputs[i], &set );
}
/.
Examine the ordinal positions of the set's elements.
Extract each element and verify that ordd_c gives the
index at which the element is located.
./
for ( i = 0; i < card_c(&set); i++ )
{
dElt = inputs[i];
if ( ordd_c(dElt, &set) != expected[i] )
{
setmsg_c ( "Position of # was expected to be # "
"but was actually #." );
errdp_c ( "#", dElt );
errdp_c ( "#", expected[i] );
errint_c ( "#", ordd_c(dElt,&set) );
sigerr_c ( "INVALID LOCATION" );
}
}
return ( 0 );
}
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
C.A. Curzon (JPL)
H.A. Neilan (JPL)
W.L. Taber (JPL)
I.M. Underwood (JPL)
-Version
-CSPICE Version 1.0.0, 07-AUG-2002 (NJB) (CAC) (HAN) (WLT) (IMU)
-Index_Entries
the ordinal position of an element in a set
-&
*/
{ /* Begin ordd_c */
/*
Use discovery check-in.
Make sure we're working with a double precision cell.
*/
CELLTYPECHK_VAL ( CHK_DISCOVER, "ordd_c", SPICE_DP, set, -1 );
/*
Initialize the set if necessary.
*/
CELLINIT ( set );
/*
Make sure the cell is really a set.
*/
CELLISSETCHK_VAL ( CHK_DISCOVER, "ordd_c", set, -1 );
/*
The routine bsrchd_c returns the index of the item in the set,
or -1 if the item is not present.
*/
return ( bsrchd_c ( item, set->card, set->data ) );
} /* End ordd_c */
void wninsd_c ( SpiceDouble left,
SpiceDouble right,
SpiceCell * window )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
left,
right I Left, right endpoints of new interval.
window I,O Input, output window.
-Detailed_Input
left,
right are the left and right endpoints of the interval
to be inserted.
window on input, is a CSPICE window containing zero or more
intervals.
window must be declared as a double precision
SpiceCell.
-Detailed_Output
window on output, is the original window following the
insertion of the interval from left to right.
-Parameters
None.
-Exceptions
1) If the input window does not have double precision type,
the error SPICE(TYPEMISMATCH) is signaled.
2) If left is greater than right, the error SPICE(BADENDPOINTS) is
signaled.
3) If the insertion of the interval causes an excess of elements,
the error SPICE(WINDOWEXCESS) is signaled.
-Files
None.
-Particulars
This routine inserts the interval from left to right into the
input window. If the new interval overlaps any of the intervals
in the window, the intervals are merged. Thus, the cardinality
of the input window can actually decrease as the result of an
insertion. However, because inserting an interval that is
disjoint from the other intervals in the window can increase the
cardinality of the window, the routine signals an error.
No other CSPICE unary window routine can increase the number of
intervals in the input window.
-Examples
Let window contain the intervals
[ 1, 3 ] [ 7, 11 ] [ 23, 27 ]
Then the following series of calls
wninsd_c ( 5.0, 5.0, &window ) (1)
wninsd_c ( 4.0, 8.0, &window ) (2)
wninsd_c ( 0.0, 30.0, &window ) (3)
produces the following series of windows
[ 1, 3 ] [ 5, 5 ] [ 7, 11 ] [ 23, 27 ] (1)
[ 1, 3 ] [ 4, 11 ] [ 23, 27 ] (2)
[ 0, 30 ] (3)
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
K.R. Gehringer (JPL)
H.A. Neilan (JPL)
W.L. Taber (JPL)
I.M. Underwood (JPL)
-Version
-CSPICE Version 1.0.0, 29-JUL-2002 (NJB) (KRG) (HAN) (WLT) (IMU)
-Index_Entries
insert an interval into a d.p. window
-&
*/
{ /* Begin wninsd_c */
/*
Standard SPICE error handling.
*/
if ( return_c() )
{
return;
}
chkin_c ( "wninsd_c" );
/*
Make sure cell data type is d.p.
*/
CELLTYPECHK ( CHK_STANDARD, "wninsd_c", SPICE_DP, window );
/*
Initialize the cell if necessary.
*/
CELLINIT ( window );
/*
Let the f2c'd routine do the work.
*/
wninsd_ ( (doublereal * ) &left,
(doublereal * ) &right,
(doublereal * ) (window->base) );
/*
Sync the output cell.
*/
if ( !failed_c() )
{
zzsynccl_c ( F2C, window );
}
chkout_c ( "wninsd_c" );
} /* End wninsd_c */
SpiceBoolean elemd_c ( SpiceDouble item,
SpiceCell * set )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
item I Item to be tested.
set I Set to be tested.
The function returns SPICETRUE if item is an element of set.
-Detailed_Input
item is an item which may or may not be an element of
the input set.
set is a CSPICE set. set must be declared as a double
precision SpiceCell.
-Detailed_Output
The function returns SPICETRUE if item is a member of the set,
and returns SPICEFALSE otherwise.
-Parameters
None.
-Exceptions
1) If the input set argument does not qualify as a CSPICE set,
the error SPICE(NOTASET) will be signaled. CSPICE sets have
their data elements sorted in increasing order and contain
no duplicate data elements.
2) If the input set does not have double precision data type,
the error SPICE(TYPEMISMATCH will be signaled.
-Files
None.
-Particulars
This routine uses a binary search to check for the presence in the set
of the specified item.
-Examples
Let set contain the elements
{ -1.0, 0.0, 1.0, 3.0, 5.0 }
The the following expressions have the value SPICETRUE
elemd_c ( -1.0, &set )
elemd_c ( 0.0, &set )
elemd_c ( 3.0, &set )
and the following expressions have the value SPICEFALSE
elemd_c ( -2.0, &set )
elemd_c ( 2.0, &set )
elemd_c ( 6.0, &set )
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
C.A. Curzon (JPL)
H.A. Neilan (JPL)
W.L. Taber (JPL)
I.M. Underwood (JPL)
-Version
-CSPICE Version 1.0.0, 07-AUG-2002 (NJB) (CAC) (HAN) (WLT) (IMU)
-Index_Entries
element of a d.p. set
-&
*/
{
/*
Use discovery check-in.
Make sure we're working with a double precision cell.
*/
CELLTYPECHK_VAL ( CHK_DISCOVER, "elemd_c", SPICE_DP, set, SPICEFALSE );
/*
Make sure the input cell is a set.
*/
CELLISSETCHK_VAL ( CHK_DISCOVER, "elemd_c", set, SPICEFALSE );
/*
Initialize the set if necessary.
*/
CELLINIT ( set );
/*
The routine bsrchd_c returns the index of the item in the set,
or -1 if the item is not present.
*/
return ( bsrchd_c ( item, set->card, set->data ) != -1 );
}
void insrtc_c ( ConstSpiceChar * item,
SpiceCell * set )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
item I Item to be inserted.
set I/O Insertion set.
-Detailed_Input
item is an item which is to be inserted into the specified
set. item may or may not already be an element of the
set. Trailing blanks in item are not significant.
set is a CSPICE set. set must be declared as a character
SpiceCell.
On input, set may or may not contain the input item
as an element.
-Detailed_Output
set on output contains the union of the input set and
the singleton set containing the input item.
-Parameters
None.
-Exceptions
1) If the input set argument is a SpiceCell of type other than
character, the error SPICE(TYPEMISMATCH) is signaled.
2) If the insertion of the element into the set causes an excess
of elements, the error SPICE(SETEXCESS) is signaled.
3) If the input set argument does not qualify as a CSPICE set,
the error SPICE(NOTASET) will be signaled. CSPICE sets have
their data elements sorted in increasing order and contain
no duplicate data elements.
4) If the input string pointer is null, the error SPICE(NULLPOINTER)
is signaled.
-Files
None.
-Particulars
None.
-Examples
1) In the following example, the element "PLUTO" is removed from
the character set planets and inserted into the character set
asteroids.
#include "SpiceUsr.h"
.
.
.
/.
Declare the sets with string length NAMLEN and with maximum
number of elements MAXSIZ.
./
SPICECHAR_CELL ( planets, MAXSIZ, NAMLEN );
SPICECHAR_CELL ( asteroids, MAXSIZ, NAMLEN );
.
.
.
removc_c ( "PLUTO", &planets );
insrtc_c ( "PLUTO", &asteroids );
If "PLUTO" is not an element of planets, then the contents of
planets are not changed. Similarly, if "PLUTO" is already an
element of asteroids, the contents of asteroids remain unchanged.
Because inserting an element into a set can increase the
cardinality of the set, an error may occur in the insertion
routines.
-Restrictions
1) String comparisons performed by this routine are Fortran-style:
trailing blanks in the input set or key value are ignored.
This gives consistent behavior with CSPICE code generated by
the f2c translator, as well as with the Fortran SPICE Toolkit.
Note that this behavior is not identical to that of the ANSI
C library functions strcmp and strncmp.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
C.A. Curzon (JPL)
W.L. Taber (JPL)
I.M. Underwood (JPL)
-Version
-CSPICE Version 2.1.0, 07-MAR-2009 (NJB)
This file now includes the header file f2cMang.h.
This header supports name mangling of f2c library
functions.
-CSPICE Version 2.0.0, 01-NOV-2005 (NJB)
Bug fix: when the item to be inserted would, after
truncation to the set's string length, match an item
already in the set, no insertion is performed. Previously
the truncated string was inserted, corrupting the set.
Long error message was updated to include size of
set into which insertion was attempted.
-CSPICE Version 1.0.0, 21-AUG-2002 (NJB) (CAC) (WLT) (IMU)
-Index_Entries
insert an item into a character set
-&
*/
{
/*
f2c library utility prototypes
*/
extern integer s_cmp (char *a, char *b, ftnlen la, ftnlen lb );
/*
Local macros
*/
#define ARRAY( i ) ( (SpiceChar *)(set->data) + (i)*(set->length) )
/*
local variables
*/
SpiceBoolean inSet;
SpiceChar * cdata;
SpiceInt i;
SpiceInt loc;
SpiceInt slen;
/*
Use discovery check-in.
Check the input string pointer to make sure it's not null.
*/
CHKPTR ( CHK_DISCOVER, "insrtc_c", item );
/*
Make sure we're working with a character cell.
*/
CELLTYPECHK ( CHK_DISCOVER, "insrtc_c", SPICE_CHR, set );
/*
Make sure the input cell is a set.
*/
CELLISSETCHK ( CHK_DISCOVER, "insrtc_c", set );
/*
Initialize the set if it's not already initialized.
*/
CELLINIT ( set );
/*
Let slen be the effective string length of the input item.
Characters beyond the string length of the set are ignored.
*/
slen = mini_c ( 2, set->length, strlen(item) );
/*
Is the item already in the set? If not, it needs to be inserted.
*/
cdata = (SpiceChar *) (set->data);
/*
The following call will give the location of the last element
less than or equal to the item to be inserted. If the item
differs from an element of the set only in characters that would
be truncated, no insertion will occur. Even in this case, the
insertion point `loc' returned by lstlec_c will be correct.
*/
loc = lstlec_c ( item, set->card, set->length, cdata );
inSet = ( loc > -1 )
&& ( s_cmp( (SpiceChar *)item, ARRAY(loc),
slen, strlen(ARRAY(loc)) ) == 0 );
if ( inSet )
{
return;
}
/*
It's an error if the set has no room left.
*/
if ( set->card == set->size )
{
chkin_c ( "insrtc_c" );
setmsg_c ( "An element could not be inserted into the set "
"due to lack of space; set size is #." );
errint_c ( "#", set->size );
sigerr_c ( "SPICE(SETEXCESS)" );
chkout_c ( "insrtc_c" );
return;
}
/*
Make room by moving the items that come after index loc in the set.
Insert the item after index loc.
*/
for ( i = (set->card); i > (loc+1); i-- )
{
SPICE_CELL_SET_C( ARRAY(i-1), i, set );
}
/*
This insertion macro will truncate the item to be inserted, if
necessary. The input item will be null-terminated.
*/
SPICE_CELL_SET_C( item, loc+1, set );
/*
Increment the set's cardinality.
*/
(set->card) ++;
}
void wnfild_c ( SpiceDouble small,
SpiceCell * window )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
small I Limiting measure of small gaps.
window I,O Window to be filled.
-Detailed_Input
small is the limiting measure of the small gaps to be
filled. Adjacent intervals separated by gaps of
measure less than or equal to small are merged.
window on input, is a window containing zero or more
intervals.
window must be declared as a double precision SpiceCell.
-Detailed_Output
window on output, is the original window, after adjacent
intervals separated by small gaps have been merged.
-Parameters
None.
-Exceptions
1) If the input window does not have double precision type,
the error SPICE(TYPEMISMATCH) is signaled.
2) If small is less than or equal to zero, this routine has
no effect on the window.
-Files
None.
-Particulars
This routine removes small gaps between adjacent intervals
by merging intervals separated by gaps of measure less than
or equal to the limiting measure small.
-Examples
Let window contain the intervals
[ 1, 3 ] [ 7, 11 ] [ 23, 27 ] [ 29, 29 ]
Then the following series of calls
wnfild_c ( 1, &window ); (1)
wnfild_c ( 2, &window ); (2)
wnfild_c ( 3, &window ); (3)
wnfild_c ( 12, &window ); (4)
produces the following series of windows
[ 1, 3 ] [ 7, 11 ] [ 23, 27 ] [ 29, 29 ] (1)
[ 1, 3 ] [ 7, 11 ] [ 23, 29 ] (2)
[ 1, 3 ] [ 7, 11 ] [ 23, 29 ] (3)
[ 1, 29 ] (4)
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
H.A. Neilan (JPL)
W.L. Taber (JPL)
I.M. Underwood (JPL)
-Version
-CSPICE Version 1.0.0, 27-JUL-2007 (EDW)
Changed gap size in Examples (4) from 10 to 12 to correct
erroneous example.
-CSPICE Version 1.0.0, 29-JUL-2002 (NJB) (HAN) (WLT) (IMU)
-Index_Entries
fill small gaps in a d.p. window
-&
*/
{ /* Begin wnfild_c */
/*
Use discovery check-in.
Make sure cell data type is d.p.
*/
CELLTYPECHK ( CHK_DISCOVER, "wnfild_c", SPICE_DP, window );
/*
Initialize the cell if necessary.
*/
CELLINIT ( window );
/*
Let the f2c'd routine do the work.
*/
wnfild_ ( (doublereal * ) &small,
(doublereal * ) (window->base) );
/*
Sync the output cell.
*/
zzsynccl_c ( F2C, window );
} /* End wnfild_c */
void insrti_c ( SpiceInt item,
SpiceCell * set )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
item I Item to be inserted.
set I/O Insertion set.
-Detailed_Input
item is an item which is to be inserted into the
specified set. item may or may not already
be an element of the set.
set is a CSPICE set. set must be declared as an integer
SpiceCell.
On input, set may or may not contain the input item
as an element.
-Detailed_Output
set on output contains the union of the input set and
the singleton set containing the input item.
-Parameters
None.
-Exceptions
1) If the input set argument is a SpiceCell of type other than
integer, the error SPICE(TYPEMISMATCH) is signaled.
2) If the insertion of the element into the set causes an excess
of elements, the error SPICE(SETEXCESS) is signaled.
3) If the input set argument does not qualify as a CSPICE set,
the error SPICE(NOTASET) will be signaled. CSPICE sets have
their data elements sorted in increasing order and contain
no duplicate data elements.
-Files
None.
-Particulars
None.
-Examples
1) In the following example, the NAIF ID code of Pluto is removed from
the integer set planets and inserted into the integer set
asteroids.
#include "SpiceUsr.h"
.
.
.
/.
Declare the sets with maximum number of elements MAXSIZ.
./
SPICEINT_CELL ( planets, MAXSIZ );
SPICEINT_CELL ( asteroids, MAXSIZ );
.
.
.
removi_c ( 999, &planets );
insrti_c ( 999, &asteroids );
If 999 is not an element of planets, then the contents of
planets are not changed. Similarly, if 999 is already an
element of asteroids, the contents of asteroids remain unchanged.
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
C.A. Curzon (JPL)
W.L. Taber (JPL)
I.M. Underwood (JPL)
-Version
-CSPICE Version 2.0.0, 01-NOV-2005 (NJB)
Long error message was updated to include size of
set into which insertion was attempted.
-CSPICE Version 1.0.0, 07-AUG-2002 (NJB) (CAC) (WLT) (IMU)
-Index_Entries
insert an item into an integer set
-&
*/
{
/*
local variables
*/
SpiceBoolean inSet;
SpiceInt i;
SpiceInt * idata;
SpiceInt loc;
/*
Use discovery check-in.
*/
/*
Make sure we're working with an integer cell.
*/
CELLTYPECHK ( CHK_DISCOVER, "insrti_c", SPICE_INT, set );
idata = (SpiceInt *) (set->data);
/*
Make sure the cell is really a set.
*/
CELLISSETCHK ( CHK_DISCOVER, "insrti_c", set );
/*
Initialize the set if necessary.
*/
CELLINIT ( set );
/*
Is the item already in the set? If not, it needs to be inserted.
*/
loc = lstlei_c ( item, set->card, idata );
inSet = ( loc > -1 ) && ( item == idata[loc] );
if ( inSet )
{
return;
}
/*
It's an error if the set has no room left.
*/
if ( set->card == set->size )
{
chkin_c ( "insrti_c" );
setmsg_c ( "An element could not be inserted into the set "
"due to lack of space; set size is #." );
errint_c ( "#", set->size );
sigerr_c ( "SPICE(SETEXCESS)" );
chkout_c ( "insrti_c" );
return;
}
/*
Make room by moving the items that come after item in the set.
Insert the item after index loc.
*/
for ( i = (set->card); i > loc+1; i-- )
{
idata[i] = idata[i-1];
}
idata[loc+1] = item;
/*
Increment the set's cardinality.
*/
(set->card) ++;
/*
Sync the set.
*/
zzsynccl_c ( C2F, set );
}
SpiceBoolean wnelmd_c ( SpiceDouble point,
SpiceCell * window )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
point I Input point.
window I Input window.
The function returns SPICETRUE if point is an element of window.
-Detailed_Input
point is a point, which may or may not be contained in
one of the intervals in window.
window is a CSPICE window containing zero or more intervals.
window must be declared as a double precision SpiceCell.
-Detailed_Output
The function returns SPICETRUE if the input point is an element of
the input window---that is, if
a(i) < point < b(i)
- -
for some interval [ a(i), b(i) ] in window---and returns SPICEFALSE
otherwise.
-Parameters
None.
-Exceptions
1) If the input window does not have double precision type,
the error SPICE(TYPEMISMATCH) is signaled.
-Files
None.
-Particulars
None.
-Examples
Let a contain the intervals
[ 1, 3 ] [ 7, 11 ] [ 23, 27 ]
Then the following expressions take the value SPICETRUE
wnelmd_c ( 1.0, &window );
wnelmd_c ( 9.0, &window );
and the following expressions take the value SPICEFALSE
wnelmd_c ( 0.0, &window );
wnelmd_c ( 13.0, &window );
wnelmd_c ( 29.0, &window );
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
H.A. Neilan (JPL)
W.L. Taber (JPL)
I.M. Underwood (JPL)
-Version
-CSPICE Version 1.0.0, 29-JUL-2002 (NJB) (HAN) (WLT) (IMU)
-Index_Entries
element of a d.p. window
-&
*/
{ /* Begin wnelmd_c */
/*
Local variables
*/
SpiceBoolean retval;
/*
Use discovery check-in.
Make sure cell data type is d.p.
*/
CELLTYPECHK_VAL ( CHK_DISCOVER,
"wnelmd_c", SPICE_DP, window, SPICEFALSE );
/*
Initialize the cell if necessary.
*/
CELLINIT ( window );
/*
Let the f2c'd routine do the work.
*/
retval = wnelmd_ ( (doublereal * ) &point,
(doublereal * ) (window->base) );
return ( retval );
} /* End wnelmd_c */
void removd_c ( SpiceDouble item,
SpiceCell * set )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
item I Item to be removed.
set I/O Removal set.
-Detailed_Input
item is an item which is to be removed from the specified
set. item may or may not already be an element of the
set.
set is a CSPICE set. set must be declared as a double
precision SpiceCell.
On input, set may or may not contain the input item
as an element.
-Detailed_Output
set on output contains the difference of the input set and
the input item. If the item is not an element of the
set, the set is not changed.
-Parameters
None.
-Exceptions
1) If the input set argument is a SpiceCell of type other than
double precision, the error SPICE(TYPEMISMATCH) is signaled.
2) If the input set argument does not qualify as a CSPICE set,
the error SPICE(NOTASET) will be signaled. CSPICE sets have
their data elements sorted in increasing order and contain
no duplicate data elements.
-Files
None.
-Particulars
None.
-Examples
1) In the following code fragment, a list of camera exposure
durations are taken from the array expList and inserted into the
set expDur.
We then update the set by removing the element 30.0 and
inserting 20.0 in its place.
#include "SpiceUsr.h"
.
.
.
/.
The number of list items is NLIST.
./
SpiceDouble expList[NLIST] =
{
0.5, 2.0, 0.5, 30.0, 0.01, 30.0
};
/.
Declare the set with maximum number of elements MAXSIZ.
./
SPICEDOUBLE_CELL ( expDur, MAXSIZ );
.
.
.
for ( i = 0; i < NLIST; i++ )
{
insrtd_c ( expList[i], &expDur );
}
/.
At this point expDur contains the set
{ 0.01, 0.5, 2.0, 30.0 }
./
.
.
.
/.
Update the exposure set by replacing 30.0 with 20.0.
./
removd_c ( 30.0, &expDur );
insrtd_c ( 20.0, &expDur );
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
C.A. Curzon (JPL)
W.L. Taber (JPL)
I.M. Underwood (JPL)
-Version
-CSPICE Version 1.0.0, 07-AUG-2002 (NJB) (CAC) (WLT) (IMU)
-Index_Entries
remove an item from a d.p. set
-&
*/
{
/*
local variables
*/
SpiceBoolean inSet;
SpiceDouble * ddata;
SpiceInt i;
SpiceInt loc;
/*
Use discovery check-in.
Make sure we're working with a double precision cell.
*/
CELLTYPECHK ( CHK_DISCOVER, "removd_c", SPICE_DP, set );
ddata = (SpiceDouble *) (set->data);
/*
Make sure the cell is really a set.
*/
CELLISSETCHK ( CHK_DISCOVER, "removd_c", set );
/*
Initialize the set if necessary.
*/
CELLINIT ( set );
/*
Is the item in the set? If not, we're done now.
*/
loc = lstled_c ( item, set->card, ddata );
inSet = ( loc > -1 ) && ( item == ddata[loc] );
if ( !inSet )
{
return;
}
/*
Shift the set's contents to overwrite the slot at index loc.
*/
for ( i = loc; i < (set->card) - 1; i++ )
{
ddata[i] = ddata[i+1];
}
/*
Decrement the set's cardinality.
*/
(set->card) --;
/*
Sync the set.
*/
zzsynccl_c ( C2F, set );
}
SpiceInt ordc_c ( ConstSpiceChar * item,
SpiceCell * set )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
item I An item to locate within a set.
set I A set to search for a given item.
The function returns the ordinal position of item within the set.
-Detailed_Input
item is a character string to be located within a set.
Trailing blanks are not significant in the comparison.
set is an integer CSPICE set that is to be searched for the
occurrence of item. Trailing blanks are not significant
in the comparison.
set must be declared as a character SpiceCell.
-Detailed_Output
The function returns the ordinal position of item within set.
Ordinal positions range from 0 to N-1, where N is the cardinality
of the set.
If item is not an element of set, the function returns -1.
-Parameters
None.
-Exceptions
1) If the input set argument is a SpiceCell of type other than
character, the error SPICE(TYPEMISMATCH) is signaled.
2) If the input set argument does not qualify as a CSPICE set,
the error SPICE(NOTASET) will be signaled. CSPICE sets have
their data elements sorted in increasing order and contain
no duplicate data elements.
3) If the input string pointer is null, the error SPICE(NULLPOINTER)
is signaled.
-Files
None.
-Particulars
A natural ordering can be imposed upon the elements of any
CSPICE set, be it integer, character or double precision. For
character strings the ASCII collating sequence serves as the
ordering relation, for double precision and integer variables
the arithmetic ordering is used.
Given any element of a set, its location within this ordered
sequence of elements is called its ordinal position within
the set.
In common mathematical usage, ordinal positions of elements
in a set of cardinality N range from 1 to N. In C programs,
it is much more convenient to use the range 0 to N-1; this is
the convention used in CSPICE.
For illustrative purposes suppose that set represents the set
{ "8", "1", "2", "9", "7", "4", "10" }
The ordinal position of:
"8" is 5
"1" is 0
"2" is 2
"9" is 6
"7" is 4
"4" is 3
"10" is 1
-Examples
1) Obtain the ordinal positions shown in the table of the Particulars
section above.
#include "SpiceUsr.h"
int main()
{
/.
Declare an integer set and populate it with the elements
shown above.
./
#define MAXSIZ 7
#define ITMLEN 10
SPICECHAR_CELL ( set, MAXSIZ, ITMLEN );
SpiceChar * cElt;
SpiceChar inputs [MAXSIZ][ITMLEN] =
{
"8", "1", "2", "9", "7", "4", "10"
};
SpiceInt expected [MAXSIZ] =
{
5, 0, 2, 6, 4, 3, 1
};
SpiceInt i;
/.
Create the set.
./
for ( i = 0; i < MAXSIZ; i++ )
{
insrtc_c ( inputs[i], &set );
}
/.
Examine the ordinal positions of the set's elements.
Extract each element and verify that ordc_c gives the
index at which the element is located.
./
for ( i = 0; i < card_c(&set); i++ )
{
cElt = inputs[i];
if ( ordc_c(cElt, &set) != expected[i] )
{
setmsg_c ( "Position of # was expected to be # "
"but was actually #." );
errch_c ( "#", cElt );
errint_c ( "#", expected[i] );
errint_c ( "#", ordc_c(cElt,&set) );
sigerr_c ( "INVALID LOCATION" );
}
}
return ( 0 );
}
-Restrictions
1) String comparisons performed by this routine are Fortran-style:
trailing blanks in the input array or key value are ignored.
This gives consistent behavior with CSPICE code generated by
the f2c translator, as well as with the Fortran SPICE Toolkit.
Note that this behavior is not identical to that of the ANSI
C library functions strcmp and strncmp.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
C.A. Curzon (JPL)
H.A. Neilan (JPL)
W.L. Taber (JPL)
I.M. Underwood (JPL)
-Version
-CSPICE Version 1.0.0, 21-AUG-2002 (NJB) (CAC) (HAN) (WLT) (IMU)
-Index_Entries
the ordinal position of an element in a set
-&
*/
{
/*
Use discovery check-in.
Check the input string pointer to make sure it's not null.
*/
CHKPTR_VAL ( CHK_DISCOVER, "ordc_c", item, -1 );
/*
Make sure we're working with a character cell.
*/
CELLTYPECHK_VAL ( CHK_DISCOVER, "ordc_c", SPICE_CHR, set, -1 );
/*
Initialize the set if necessary.
*/
CELLINIT ( set );
/*
Make sure the cell is really a set.
*/
CELLISSETCHK_VAL ( CHK_DISCOVER, "ordc_c", set, -1 );
/*
The routine bsrchc_c returns the index of the item in the set,
or -1 if the item is not present.
*/
return ( bsrchc_c ( item, set->card, set->length, set->data ) );
}
