SpiceInt lstltc_c ( ConstSpiceChar * string,
SpiceInt n,
SpiceInt lenvals,
const void * array )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
string I Upper bound value to search against.
n I Number elements in array.
lenvals I String length.
array I Array of possible lower bounds.
The function returns the index of the last element of array that
is lexically less than string.
-Detailed_Input
string is a string acting as an upper bound: the array element
that is lexically the greatest element less than string
is to be found. Trailing blanks in this bound value are
not significant.
n is the dimension of the array.
lenvals is the declared length of the strings in the input
string array, including null terminators. The input
array should be declared with dimension
[n][lenvals]
array is the array of character strings to be searched.
Trailing blanks in the strings in this array are not
significant. The strings must be sorted in
non-decreasing order. The elements of array need not be
distinct.
-Detailed_Output
The function returns the index of the highest-indexed element in the
input array that is lexically less than string. The routine assumes
the array elements are sorted in non-decreasing order.
If all elements of the input array are greater than or equal to the
specified upper bound string, the function returns -1.
-Parameters
None.
-Exceptions
1) If ndim < 1 the function value is -1. This is not considered
an error.
2) If input key value pointer is null, the error SPICE(NULLPOINTER) will
be signaled. The function returns -1.
3) The input key value may have length zero. This case is not
considered an error.
4) If the input array pointer is null, the error SPICE(NULLPOINTER) will
be signaled. The function returns -1.
5) If the input array string's length is less than 2, the error
SPICE(STRINGTOOSHORT) will be signaled. The function returns -1.
-Files
None.
-Particulars
Note: If you need to find the first element of the array that
is greater than or equal to string, simply add 1 to the
result returned by this function and check to see if the
result is within the array bounds given by n.
-Examples
Let array be a character array of dimension
[5][lenvals]
which contains the following elements:
"BOHR"
"EINSTEIN"
"FEYNMAN"
"GALILEO"
"NEWTON"
Then
lstltc_c ( "NEWTON", 5, lenvals, array ) == 3
lstltc_c ( "EINSTEIN", 5, lenvals, array ) == 0
lstltc_c ( "GALILEO", 5, lenvals, array ) == 2
lstltc_c ( "Galileo", 5, lenvals, array ) == 3
lstltc_c ( "BETHE", 5, lenvals, array ) == -1
-Restrictions
1) The input array is assumed to be sorted in increasing order. If
this condition is not met, the results of bsrchc_c are unpredictable.
2) 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)
H.A. Neilan (JPL)
W.L. Taber (JPL)
-Version
-CSPICE Version 1.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 1.0.0, 22-JUL-2002 (NJB) (HAN) (WLT)
-Index_Entries
last character element less_than
-&
*/
{ /* Begin lstltc_c */
/*
f2c library utility prototypes
*/
logical l_gt (char *a, char *b, ftnlen la, ftnlen lb );
logical l_le (char *a, char *b, ftnlen la, ftnlen lb );
logical l_lt (char *a, char *b, ftnlen la, ftnlen lb );
/*
Local macros
*/
#define ARRAY( i ) ( ( (SpiceChar *)array ) + (i)*lenvals )
/*
Local variables
*/
SpiceInt begin;
SpiceInt end;
SpiceInt items;
SpiceInt j;
SpiceInt keylen;
SpiceInt middle;
/*
Use discovery check-in.
Return immediately if the array dimension is non-positive.
*/
if ( n < 1 )
{
return ( -1 );
}
/*
Make sure the pointer for the key value is non-null
and that the length is adequate.
*/
CHKPTR_VAL ( CHK_DISCOVER, "lstltc_c", string, -1 );
/*
Make sure the pointer for the string array is non-null
and that the length lenvals is sufficient.
*/
CHKOSTR_VAL ( CHK_DISCOVER, "lstltc_c", array, lenvals, -1 );
/*
Return if none of the array's elements are less than the key value.
*/
keylen = strlen(string);
begin = 0;
end = n - 1;
if ( l_le( ( char * )string,
( char * )ARRAY(begin),
( ftnlen )keylen,
( ftnlen )strlen(ARRAY(begin)) ) )
{
return ( -1 );
}
/*
Return if the key string is greater than all of the array's elements.
*/
if ( l_gt( ( char * )string,
( char * )ARRAY(end),
( ftnlen )keylen,
( ftnlen )strlen(ARRAY(end)) ) )
{
return ( end );
}
/*
Do a binary search for the specified key value.
At this point, string is greater than the first element of array and
less than or equal to the last element of array.
*/
items = n;
while ( items > 2 )
{
/*
Check the middle element.
*/
j = items / 2;
middle = begin + j;
/*
Narrow the search area.
*/
if ( l_lt ( (char * ) ARRAY(middle),
(char * ) string,
(ftnlen ) strlen( ARRAY(middle) ),
(ftnlen ) keylen ) )
{
/*
The middle element is less than string.
*/
begin = middle;
}
else
{
end = middle;
}
items = end - begin + 1;
/*
At this point, string is greater than the array element at index
begin and is less than or equal to the element at index end.
*/
}
/*
The element at index begin is the winner.
*/
return ( begin );
} /* End lstltc_c */
SpiceBoolean eqstr_c ( ConstSpiceChar * a, ConstSpiceChar * b )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
a,
b I Arbitrary character strings.
The function returns SPICETRUE if A and B are equivalent.
-Detailed_Input
a,
b are arbitrary character strings.
-Detailed_Output
The function returns TRUE if A and B are equivalent: that is,
if A and B contain the same characters in the same order,
when white space characters are ignored and uppercase and lowercase
characters are considered equal.
White space characters are those in the set
{ ' ', '\f', '\n', '\r', '\t', '\v' }
Note that this specification differs from that of the Fortran version
of this routine, which considers the blank ( ' ' ) to be the only
white space character.
-Parameters
None.
-Files
None.
-Exceptions
1) If either input string pointer is null, the error
SPICE(NULLPOINTER) will be signaled.
-Particulars
This routine is provided for those cases in which two strings
must be compared, and in which allowances are to be made for
extra (leading, trailing, and embedded) blanks and differences
in case. For the most part,
if ( eqstr_c ( A, B ) )
.
.
is true whenever
cmprss_c ( ' ', 0, a, MAXLEN, tempa );
ucase_c ( tempa, MAXLEN, tempa );
cmprss_c ( ' ', 0, b, MAXLEN, tempb );
ucase_c ( tempb, MAXLEN, tempb );
if ( !strcmp ( tempa, tempb ) )
.
.
is true. There are two important differences, however.
1) The single reference to eqstr_c is much simpler to
write, and simpler to understand.
2) The reference to eqstr_c does not require any temporary
storage, nor does it require that the strings a and b
be changed. This feature is especially useful when
comparing strings recieved as subprogram arguments
against strings stored internally within the subprogram.
-Examples
Usage
--------------------------------------------
All of the following are TRUE.
eqstr_c ( "A short string ",
"ashortstring" );
eqstr_c ( "Embedded blanks",
"Em be dd ed bl an ks" );
eqstr_c ( "Embedded blanks",
" Embeddedblanks" );
eqstr_c ( " ",
" " );
All of the following are FALSE.
eqstr_c ( "One word left out",
"WORD LEFT OUT" );
eqstr_c ( "Extra [] delimiters",
"extradelimiters" );
eqstr_c ( "Testing 1, 2, 3",
"TESTING123" );
Use
--------------------------------------------
The following illustrates a typical use for eqstr_c.
#include "SpiceUsr.h"
.
.
.
SpiceChar * greeting ( SpiceChar *who )
{
if ( eqstr_c ( who, "Steve" ) )
{
return ( "Yes, sir?" );
}
else if ( eqstr_c ( who, "Chuck" ) )
{
return ( "What can I do for you?" );
}
else
{
return ( "Whaddya want?" );
}
}
Note that all of the following calls will elicit the
greeting "Yes, sir?":
greeting ( "STEVE" );
greeting ( "steve" );
greeting ( "Steve" );
greeting ( "sTEVE" );
greeting ( " S T E V E " );
-Restrictions
None.
-Literature_References
1) "American National Standard for Programming Languages -- C,"
Published by the American National Standards Institute, 1990.
Section 7.3.1.9., p. 104.
-Author_and_Institution
N.J. Bachman (JPL)
I.M. Underwood (JPL)
-Version
-CSPICE Version 1.3.0, 27-AUG-1999 (NJB)
Added check for null input strings. Added logic to handle the
case where at least one input string is empty.
-CSPICE Version 1.2.0, 24-FEB-1999 (NJB)
Arguments passed to isspace are now cast to unsigned char to
suppress compilation warnings on some systems.
-CSPICE Version 1.1.0, 08-FEB-1998 (NJB)
Initial assignment of return value added to suppress compilation
warnings on some systems.
-CSPICE Version 1.0.0, 25-OCT-1997 (NJB)
Based on SPICELIB Version 1.2.0, 03-AUG-1994 (NJB)
-Index_Entries
equivalent strings
-&
*/
{ /* Begin eqstr_c */
/*
Local constants
*/
#define LBOUND ( (SpiceInt) 'a' )
#define UBOUND ( (SpiceInt) 'z' )
#define DELTA ( ( (SpiceInt) 'A' ) - LBOUND )
/*
Local variables
*/
SpiceBoolean done;
SpiceBoolean retval;
ConstSpiceChar * pa;
ConstSpiceChar * pb;
SpiceInt ca;
SpiceInt cb;
SpiceInt lenA;
SpiceInt lenB;
/*
Initialize the return value retval in order to make certain
compilers happy. This initial value is not used later; retval
is set explicitly in each case below.
*/
retval = SPICEFALSE;
/*
Check the input string pointers to make sure they're non-null.
*/
CHKPTR_VAL ( CHK_DISCOVER, "eqstr_c", a, retval );
CHKPTR_VAL ( CHK_DISCOVER, "eqstr_c", b, retval );
/*
The general plan is to move a pair of pointers (PA, PB)
through strings A and B, skipping blank characters and
comparing others one-for-one.
Repeat:
If (A is blank) then
Increment A
Else if (B is blank) then
Increment B
Else
If (A and B are equivalent) then
Increment A and B
Else
Return FALSE
If (A and B are past end) then
Return TRUE
Else if (A or B is past end and other is non-blank) then
Return FALSE
Else if (A or B is past end and other is blank) then
Return TRUE
Note that no pointer gets incremented more than once on each
pass through the loop.
On the other hand, in many cases the strings will be exactly
equal. If so, why knock ourselves out?
*/
if ( !strcmp( a, b ) )
{
return ( SPICETRUE );
}
pa = a;
pb = b;
lenA = strlen(a);
lenB = strlen(b);
/*
The possibility of an input string being empty does not occur in
Fortran, but it does here. Handle these cases (the case where both
are empty was handled by the strcmp test above).
*/
if ( ( lenA == 0 ) && ( lenB > 0 ) )
{
return ( SPICEFALSE );
}
if ( ( lenB == 0 ) && ( lenA > 0 ) )
{
return ( SPICEFALSE );
}
/*
On with the normal path.
*/
done = SPICEFALSE;
while ( !done )
{
/*
At this point, we're guaranteed that strings a and b have more
characters to examine, that is:
( pa <= a+lenA-1 ) and ( pb <= b+lenB-1 )
*/
if ( isspace( (unsigned char) *pa ) )
{
pa++;
}
else if ( isspace( (unsigned char) *pb) )
{
pb++;
}
else
{
ca = (SpiceInt)(*pa);
cb = (SpiceInt)(*pb);
if ( ( ca >= LBOUND ) && ( ca <= UBOUND ) )
{
ca = ca + DELTA;
}
if ( ( cb >= LBOUND ) && ( cb <= UBOUND ) )
{
cb = cb + DELTA;
}
if ( ca == cb )
{
pa++;
pb++;
}
else
{
/*
We now know the strings don't match.
*/
retval = SPICEFALSE;
done = SPICETRUE;
}
}
if ( !done )
{
/*
At this point, the strings still match and we've advanced
at least one of the pointers.
*/
if ( ( (SpiceInt)(pa-a) ) == lenA )
{
/*
There are no more characters in string a to examine. The
rest of string b had better be white space, or else we had
better be at the end of string b.
*/
if ( ( (SpiceInt)(pb-b) ) == lenB )
{
/*
We've seen all of string b.
*/
retval = SPICETRUE;
done = SPICETRUE;
}
else if ( iswhsp_c(pb) )
{
retval = SPICETRUE;
done = SPICETRUE;
}
else
{
retval = SPICEFALSE;
done = SPICETRUE;
}
}
/*
End of "no more characters in string a" case.
*/
else if ( ( (SpiceInt)(pb-b) ) == lenB )
{
/*
There are no more characters in string b to examine. The
rest of string a had better be white space.
*/
if ( iswhsp_c(pa) )
{
retval = SPICETRUE;
done = SPICETRUE;
}
else
{
retval = SPICEFALSE;
done = SPICETRUE;
}
}
/*
End of "no more characters in string b" case.
*/
}
/*
At this point, we've handled the cases where at least one
string is out of characters. If such a case occurred, done
has been set to SPICETRUE.
*/
}
/*
End of while loop. retval has been set.
*/
return (retval);
} /* End eqstr_c */
SpiceInt isrchc_c ( ConstSpiceChar * value,
SpiceInt ndim,
SpiceInt lenvals,
const void * array )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
value I Key value to be found in array.
ndim I Dimension of array.
lenvals I String length.
array I Character string array to search.
The function returns the index of the first matching array
element or -1 if the value is not found.
-Detailed_Input
value is the key value to be found in the array. Trailing
blanks in this key are not significant: string matches
found by this routine do not require trailing blanks in
value to match those in the corresponding element of
array.
ndim is the dimension of the array.
lenvals is the declared length of the strings in the input
string array, including null terminators. The input
array should be declared with dimension
[ndim][lenvals]
array is the array of character srings to be searched. Trailing
blanks in the strings in this array are not significant.
-Detailed_Output
The function returns the index of the first matching array
element in array. If value is not found, isrchc_c returns -1.
-Parameters
None.
-Exceptions
1) If ndim < 1 the function value is -1. This is not considered
an error.
2) If input key value pointer is null, the error SPICE(NULLPOINTER) will
be signaled. The function returns -1.
3) The input key value may have length zero. This case is not
considered an error.
4) If the input array pointer is null, the error SPICE(NULLPOINTER) will
be signaled. The function returns -1.
5) If the input array string's length is less than 2, the error
SPICE(STRINGTOOSHORT) will be signaled. The function returns -1.
-Files
None.
-Particulars
None.
-Examples
The following table shows the value of isrchc_c given the contents
of array and value:
array value isrchc_c
----------------- ----- --------
"1", "0", "4", "2" "4" 2
"1", "0", "4", "2" "2" 3
"1", "0", "4", "2" "3" -1
-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.
None.
-Literature_References
None
-Author_and_Institution
N.J. Bachman (JPL)
W.M. Owen (JPL)
-Version
-CSPICE Version 1.1.0, 07-MAR-2009 (NJB)
This file now includes the header file f2cMang.h.
This header supports name mangling of f2c library
functions.
Header sections were re-ordered.
-CSPICE Version 1.0.0, 22-JUL-2002 (NJB) (WMO)
-Index_Entries
search in a character array
-&
*/
{ /* Begin isrchc_c */
/*
f2c library utility prototypes
*/
extern integer s_cmp (char *a, char *b, ftnlen la, ftnlen lb );
/*
Local macros
*/
#define ARRAY( i ) ( ( (SpiceChar *)array ) + i*lenvals )
/*
Local variables
*/
SpiceInt i;
/*
Use discovery check-in.
Return immediately if the array dimension is non-positive.
*/
if ( ndim < 1 )
{
return ( -1 );
}
/*
Make sure the input pointer for the key value is non-null
and that the length is adequate.
*/
CHKPTR_VAL ( CHK_DISCOVER, "isrchc_c", value, -1 );
/*
Make sure the input pointer for the string array is non-null
and that the length lenvals is sufficient.
*/
CHKOSTR_VAL ( CHK_DISCOVER, "isrchc_c", array, lenvals, -1 );
for ( i = 0; i < ndim; i++ )
{
if ( s_cmp ( (char *) value,
(char *) ARRAY(i),
(ftnlen ) strlen(value),
(ftnlen ) strlen(ARRAY(i)) ) == 0 )
{
return ( i );
}
}
/*
Indicate no match was found.
*/
return ( -1 );
} /* End isrchc_c */
SpiceBoolean iswhsp_c ( ConstSpiceChar * string )
/*
-Brief_I/O
Variable I/O Description
-------- --- --------------------------------------------------
string I String to be tested.
The function returns the boolean value SPICETRUE if the string is
empty or contains only white space characters; otherwise it returns
the value SPICEFALSE.
-Detailed_Input
string is a character pointer designating a string to be
searched for non-white-space characters.
-Detailed_Output
The function returns the boolean value SPICETRUE if the string
contains only white space characters; otherwise it returns the
value SPICEFALSE.
White space characters are those in the set
{ ' ', '\f', '\n', '\r', '\t', '\v' }
-Parameters
None.
-Exceptions
1) If the input string pointer is null, the error SPICE(NULLPOINTER)
is signaled.
2) An empty string, that is a string with a null character
at index 0, is considered to be blank.
-Files
None.
-Particulars
This routine provides a short cut for testing lines for the presence
of non-blank characters; this is a test which is performed frequently
in CSPICE.
-Examples
1) Read a text file; print the non-blank lines.
#include <stdio.h>
#include "SpiceUsr.h"
void main()
{
#define MAXLEN 82
FILE *fptr;
SpiceBoolean eof;
SpiceChar line [MAXLEN];
txtopr_c ( "myfile", &fptr );
readln_c ( fptr, MAXLEN, line, &eof );
while ( !eof )
{
if ( !iswhsp_c(line) )
{
printf ( "%s\n", line );
}
readln_c ( fptr, MAXLEN, line, &eof );
}
}
-Restrictions
None.
-Literature_References
1) "American National Standard for Programming Languages -- C,"
Published by the American National Standards Institute, 1990.
Section 7.3.1.9., p. 104.
-Author_and_Institution
N.J. Bachman (JPL)
-Version
-CSPICE Version 1.1.0, 27-AUG-1999 (NJB)
Now checks for null input string.
-CSPICE Version 1.0.0, 24-FEB-1999 (NJB)
Arguments passed to isspace are now cast to unsigned char to
suppress compilation warnings on some systems.
-CSPICE Version 1.0.0, 08-FEB-1998 (NJB)
-Index_Entries
read a non-blank line from a text file
-&
*/
{ /* Begin iswhsp_c */
/*
Local variables
*/
SpiceBoolean blank;
ConstSpiceChar * sptr;
/*
Check the input string pointer to make sure it's non-null.
*/
CHKPTR_VAL ( CHK_DISCOVER, "iswhsp_c", string, SPICEFALSE );
/*
Start out assuming the string is blank. If the string is empty,
we've got the right return value already.
*/
blank = SPICETRUE;
sptr = string;
while ( blank && ( (SpiceBoolean) *sptr ) )
{
if ( !isspace( (unsigned char) *sptr ) )
{
blank = SPICEFALSE;
}
sptr++;
}
return ( blank );
} /* End iswhsp_c */
SpiceInt posr_c ( ConstSpiceChar * str,
ConstSpiceChar * substr,
SpiceInt start )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
str I Any character string.
substr I Substring to locate in the character string.
start I Position to begin looking for substr in str.
The function returns the index of the last occurrence of substr in
str at or preceding index start.
-Detailed_Input
str is any character string.
substr is a substring to look for in str. Spaces in substr are
significant, including trailing blanks.
start is the position in str to begin looking for substr. start
may range from 0 to n-1, where n is the number of
characters in str.
-Detailed_Output
The function returns the index of the beginning of the last
substring of str that begins at or before index start and is equal
to substr. If the substring cannot be found after start, the
function is returns -1.
-Parameters
None.
-Exceptions
1) The error SPICE(NULLPOINTER) is signaled if either of
the input string pointers is null.
2) If start is less than 0, the search begins at the first
character of the string.
3) If start is greater than or equal to the length of the string,
posr_c returns -1.
4) The function returns -1 if either of the input strings is empty.
-Files
None.
-Particulars
posr_c is case sensitive.
An entire family of related CSPICE routines
cpos_c
cposr_c
ncpos_c
ncposr_c
pos_c
posr_c
is described in the Required Reading.
-Examples
Let string == "AN ANT AND AN ELEPHANT "
012345678901234567890123456789
Normal (Sequential) Searching:
------------------------------
posr_c ( STRING, "AN", 29 ) == 19
posr_c ( STRING, "AN", 18 ) == 11
posr_c ( STRING, "AN", 10 ) == 7
posr_c ( STRING, "AN", 6 ) == 3
posr_c ( STRING, "AN", 2 ) == 0
start out of bounds:
--------------------
posr_c ( STRING, "AN", -6 ) == -1
posr_c ( STRING, "AN", -1 ) == -1
posr_c ( STRING, "AN", 30 ) == 19
posr_c ( STRING, "AN", 43 ) == 19
Significance of Spaces:
-----------------------
posr_c ( STRING, "AN", 29 ) == 19
posr_c ( STRING, " AN", 29 ) == 10
posr_c ( STRING, " AN ", 29 ) == 10
posr_c ( STRING, " AN ", 9 ) == -1
posr_c ( STRING, " AN ", 29 ) == -1
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
W.L. Taber (JPL)
-Version
-CSPICE Version 1.0.0, 15-AUG-2002 (NJB) (WLT)
-Index_Entries
position of substring reverse search
-&
*/
{ /* Begin posr_c */
/*
Local variables
*/
SpiceInt fstart;
SpiceInt retval;
/*
Use discovery check-in.
Check for null pointers.
*/
CHKPTR_VAL ( CHK_DISCOVER, "posr_c", str, -1 );
CHKPTR_VAL ( CHK_DISCOVER, "posr_c", substr, -1 );
/*
Check for empty strings.
*/
if ( ( strlen(str) == 0 ) || ( strlen(substr) == 0 ) )
{
return ( -1 );
}
/*
The rest can be handled by the f2c'd SPICELIB routine. Adjust
the start index to account for Fortran indexing.
*/
fstart = start + 1;
retval = posr_ ( (char *) str,
(char *) substr,
(integer *) &fstart,
(ftnlen ) strlen(str),
(ftnlen ) strlen(substr) );
/*
Adjust the return value to account for C indexing.
*/
return ( retval-1 );
} /* End posr_c */
SpiceInt esrchc_c ( ConstSpiceChar * value,
SpiceInt ndim,
SpiceInt lenvals,
const void * array )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
value I Key value to be found in array.
ndim I Dimension of array.
lenvals I String length.
array I Character string array to search.
The function returns the index of the first array entry
equivalent to value, or -1 if none is found.
-Detailed_Input
value is the key value to be found in the array. Trailing
blanks in this key are not significant: string matches
found by this routine do not require trailing blanks in
value to match those in the corresponding element of
array.
ndim is the dimension of the array.
lenvals is the declared length of the strings in the input
string array, including null terminators. The input
array should be declared with dimension
[ndim][lenvals]
array is the array of character srings to be searched. Trailing
blanks in the strings in this array are not significant.
-Detailed_Output
The function returns the index of the first element of the
input array equivalent to the input value, or -1 if the
array contains no such elements.
Two strings are equivalent if they contain the same characters
in the same order, when blanks are ignored and uppercase and
lowercase characters are considered equal.
-Parameters
None.
-Exceptions
1) If ndim < 1 the function value is -1. This is not considered
an error.
2) If input key value pointer is null, the error SPICE(NULLPOINTER) will
be signaled. The function returns -1.
3) The input key value may have length zero. This case is not
considered an error.
4) If the input array pointer is null, the error SPICE(NULLPOINTER) will
be signaled. The function returns -1.
5) If the input array string's length is less than 2, the error
SPICE(STRINGTOOSHORT) will be signaled. The function returns -1.
-Files
None.
-Particulars
esrchc_c is identical to isrchc_c, except that it looks for
the first equivalent string (as defined by eqstr_c) instead
of the first identical one.
-Examples
Let array be declared with dimension
[NDIM][STRLEN]
and contain the following elements:
array[0] == "This"
array[1] == "little"
array[2] == "piggy"
array[3] == "went"
array[4] == "to"
array[5] == "market"
Then
esrchc_c ( "PIGGY", NDIM, STRLEN, array ) == 2
esrchc_c ( " LiTtLe ", NDIM, STRLEN, array ) == 1
esrchc_c ( "W e n t", NDIM, STRLEN, array ) == 3
esrchc_c ( "mall", NDIM, STRLEN, array ) == -1
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
I.M. Underwood (JPL)
-Version
-CSPICE Version 1.0.0, 22-JUL-2002 (NJB) (IMU)
-Index_Entries
search array for equivalent character_string
-&
*/
{ /* Begin esrchc_c */
/*
Local macros
*/
#define ARRAY( i ) ( ( (SpiceChar *)array ) + (i)*lenvals )
/*
Local variables
*/
SpiceInt i;
/*
Use discovery check-in.
Return immediately if the array dimension is non-positive.
*/
if ( ndim < 1 )
{
return ( -1 );
}
/*
Make sure the input pointer for the key value is non-null
and that the length is adequate.
*/
CHKPTR_VAL ( CHK_DISCOVER, "esrchc_c", value, -1 );
/*
Make sure the input pointer for the string array is non-null
and that the length lenvals is sufficient.
*/
CHKOSTR_VAL ( CHK_DISCOVER, "esrchc_c", array, lenvals, -1 );
for ( i = 0; i < ndim; i++ )
{
if ( eqstr_c( value, ARRAY(i) ) )
{
return ( i );
}
}
/*
Indicate no match was found.
*/
return ( -1 );
} /* End esrchc_c */
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 ) );
}
SpiceInt bsrchc_c ( ConstSpiceChar * value,
SpiceInt ndim,
SpiceInt lenvals,
const void * array )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
value I Key value to be found in array.
ndim I Dimension of array.
lenvals I String length.
array I Character string array to search.
The function returns the index of the first matching array
element or -1 if the value is not found.
-Detailed_Input
value is the key value to be found in the array. Trailing blanks
in this key are not significant: string matches found
by this routine do not require trailing blanks in
value to match that in the corresponding element of array.
ndim is the dimension of the array.
lenvals is the declared length of the strings in the input
string array, including null terminators. The input
array should be declared with dimension
[ndim][lenvals]
array is the array of character srings to be searched. Trailing
blanks in the strings in this array are not significant.
-Detailed_Output
The function returns the index of the specified value in the input array.
Array indices range from zero to ndim-1.
If the input array does not contain the specified value, the function
returns -1.
If the input array contains more than one occurrence of the specified
value, the returned index may point to any of the occurrences.
-Parameters
None.
-Exceptions
1) If ndim < 1 the function value is -1. This is not considered
an error.
2) If input key value pointer is null, the error SPICE(NULLPOINTER) will
be signaled. The function returns -1.
3) The input key value may have length zero. This case is not
considered an error.
4) If the input array pointer is null, the error SPICE(NULLPOINTER) will
be signaled. The function returns -1.
5) If the input array string's length is less than 2, the error
SPICE(STRINGTOOSHORT) will be signaled. The function returns -1.
-Files
None
-Particulars
A binary search is performed on the input array. If an
element of the array is found to match the input value, the
index of that element is returned. If no matching element
is found, -1 is returned.
-Examples
Let array be a character array of dimension
[5][lenvals]
which contains the following elements:
"BOHR"
"EINSTEIN"
"FEYNMAN"
"GALILEO"
"NEWTON"
Then
bsrchc_c ( "NEWTON", 5, lenvals, array ) == 4
bsrchc_c ( "EINSTEIN", 5, lenvals, array ) == 1
bsrchc_c ( "GALILEO", 5, lenvals, array ) == 3
bsrchc_c ( "Galileo", 5, lenvals, array ) == -1
bsrchc_c ( "BETHE", 5, lenvals, array ) == -1
-Restrictions
1) The input array is assumed to be sorted in increasing order. If
this condition is not met, the results of bsrchc_c are unpredictable.
2) 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)
W.M. Owen (JPL)
-Version
-CSPICE Version 1.1.0, 07-MAR-2009 (NJB)
This file now includes the header file f2cMang.h.
This header supports name mangling of f2c library
functions.
Header sections were re-ordered.
-CSPICE Version 1.0.0, 26-AUG-2002 (NJB) (WMO)
-Index_Entries
search in a character array
-&
*/
{ /* Begin bsrchc_c */
/*
f2c library utility prototypes
*/
logical l_lt (char *a, char *b, ftnlen la, ftnlen lb );
extern integer s_cmp (char *a, char *b, ftnlen la, ftnlen lb );
/*
Local macros
*/
#define ARRAY( i ) ( ( (SpiceChar *)array ) + (i)*lenvals )
/*
Local variables
*/
SpiceInt i;
SpiceInt keylen;
SpiceInt left;
SpiceInt order;
SpiceInt right;
/*
Use discovery check-in.
Return immediately if the array dimension is non-positive.
*/
if ( ndim < 1 )
{
return ( -1 );
}
/*
Make sure the pointer for the key value is non-null
and that the length is adequate.
*/
CHKPTR_VAL ( CHK_DISCOVER, "bsrchc_c", value, -1 );
/*
Make sure the pointer for the string array is non-null
and that the length lenvals is sufficient.
*/
CHKOSTR_VAL ( CHK_DISCOVER, "bsrchc_c", array, lenvals, -1 );
/*
Do a binary search for the specified key value.
*/
keylen = strlen(value);
left = 0;
right = ndim - 1;
while ( left <= right )
{
/*
Check the middle element.
*/
i = ( left + right ) / 2;
/*
The f2c library function s_cmp performs a Fortran-style
lexical order comparison. A negative return value indicates
the first argument is less than the second, a return value
of zero indicates equality, and a positive value indicates
the second argument is greater.
*/
order = (SpiceInt) s_cmp ( (char * ) value,
(char * ) ARRAY(i),
(ftnlen ) keylen,
(ftnlen ) strlen(ARRAY(i)) );
/*
If the middle element matches, return its location.
*/
if ( order == 0 )
{
return ( i );
}
/*
Otherwise, narrow the search area.
*/
else if ( order < 0 )
{
/*
value is less than the middle element.
*/
right = i - 1;
}
else
{
left = i + 1;
}
}
/*
If the search area is empty, indicate the value was not found.
*/
return ( -1 );
} /* End bsrchc_c */
SpiceInt cposr_c ( ConstSpiceChar * str,
ConstSpiceChar * chars,
SpiceInt start )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
str I Any character string.
chars I A collection of characters.
start I Position to begin looking for one of chars.
The function returns the index of the last character of str
at or before index start that is in the collection chars.
-Detailed_Input
str is any character string.
chars is a character string containing a collection
of characters. Spaces in chars are significant,
including trailing blanks. The order in which
characters are listed is not significant.
start is the position in str to begin looking for one of
the characters in chars. start may range from 0
to n-1, where n is the number of characters in str.
-Detailed_Output
The function returns the index of the last character of str (at or
before index start) that is one of the characters in the string
chars. The returned value normally ranges from 0 to n-1, where n is
the number of characters in str. If none of the characters is found,
the function returns -1.
-Parameters
None.
-Exceptions
1) The error SPICE(NULLPOINTER) is signaled if either of
the input string pointers is null.
2) If start is less than 0, cposr_c returns -1.
3) If start is greater than or equal to the length of the string,
the search begins at the last character of the string.
4) The function returns -1 if either of the input strings is empty.
-Files
None.
-Particulars
cposr_c is case sensitive.
An entire family of related CSPICE routines
cpos_c
cposr_c
ncpos_c
ncposr_c
pos_c
posr_c
is described in the Required Reading.
-Examples
Let string == "BOB, JOHN, TED, AND MARTIN...."
012345678901234567890123456789
Normal (sequential) searching:
------------------------------
cposr_c( string, ' ,', 29 ) = 29
cposr_c( string, ' ,', 28 ) = 28
cposr_c( string, ' ,', 27 ) = 27
cposr_c( string, ' ,', 26 ) = 26
cposr_c( string, ' ,', 25 ) = 19
cposr_c( string, ' ,', 18 ) = 15
cposr_c( string, ' ,', 14 ) = 14
cposr_c( string, ' ,', 13 ) = 10
cposr_c( string, ' ,', 9 ) = 9
cposr_c( string, ' ,', 8 ) = 4
cposr_c( string, ' ,', 3 ) = 3
cposr_c( string, ' ,', 2 ) = -1
start out of bounds:
--------------------
cposr_c( string, ' ,', 230 ) = 29
cposr_c( string, ' ,', 30 ) = 29
cposr_c( string, ' ,', -1 ) = -1
cposr_c( string, ' ,', -10 ) = -1
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
W.L. Taber (JPL)
-Version
-CSPICE Version 1.0.0, 27-AUG-2002 (NJB) (WLT)
-Index_Entries
backward search for position of character
-&
*/
{ /* Begin cposr_c */
/*
Local variables
*/
SpiceInt fstart;
SpiceInt retval;
/*
Use discovery check-in.
Check for null pointers.
*/
CHKPTR_VAL ( CHK_DISCOVER, "cposr_c", str, -1 );
CHKPTR_VAL ( CHK_DISCOVER, "cposr_c", chars, -1 );
/*
Check for empty strings.
*/
if ( ( strlen(str) == 0 ) || ( strlen(chars) == 0 ) )
{
return ( -1 );
}
/*
The rest can be handled by the f2c'd SPICELIB routine. Adjust
the start index to account for Fortran indexing.
*/
fstart = start + 1;
retval = cposr_ ( (char *) str,
(char *) chars,
(integer *) &fstart,
(ftnlen ) strlen(str),
(ftnlen ) strlen(chars) );
/*
Adjust the return value to account for C indexing.
*/
return ( retval-1 );
} /* End cposr_c */