Index of Functions: A B C D E F G H I J K L M N O P Q R S T U V W X
Index Page bschoi_c

Table of contents

Procedure Abstract Required_Reading Keywords Brief_I/O Detailed_Input | Detailed_Output Parameters Exceptions Files Particulars Examples | Restrictions Literature_References Author_and_Institution Version Index_Entries

#### Procedure

       bschoi_c ( Binary search with order vector, integer )

       SpiceInt bschoi_c ( SpiceInt          value,
                           SpiceInt          ndim,
                           ConstSpiceInt   * array,
                           ConstSpiceInt   * order  )

#### Abstract

       Do a binary search for a given value within an integer array,
       accompanied by an order vector. Return the index of the
       matching array entry, or -1 if the key value is not found.

#### Required_Reading

       None.

#### Keywords

       ARRAY
       SEARCH

#### Brief_I/O

       VARIABLE  I/O  DESCRIPTION
       --------  ---  --------------------------------------------------
       value      I   Value to find in `array'.
       ndim       I   Dimension of `array'.
       array      I   Array to be searched.
       order      I   Order vector.

       The function returns the index of the first matching array element
       or -1 if the value is not found.

#### Detailed_Input

       value       is the value to be found in the input array.

       ndim        is the number of elements in the input array.

       array       is the array to be searched.

       order       is an order vector which can be used to access the
                   elements of `array' in order. The contents of order are a
                   permutation of the sequence of integers ranging from 0 to
                   ndim-1.

#### Detailed_Output

       The function returns the index of the specified value in the input
       array. Indices range from 0 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 value of the function is -1.

       2)  If memory cannot be allocated to create the temporary variable
           required for the execution of the underlying Fortran routine,
           the error SPICE(MALLOCFAILED) is signaled. The function
           returns the value -1.

#### Files

       None.

#### Particulars

       A binary search is performed on the input array, whose order is
       given by an associated order vector. 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' and `order' contain the following elements:

          array         order
          -----------   -----
            100             1
              1             2
             10             0
          10000             4
           1000             3

       Then

          bschoi_c (  1000, 5, array, order )  ==   4
          bschoi_c (     1, 5, array, order )  ==   1
          bschoi_c ( 10000, 5, array, order )  ==   3
          bschoi_c (    -1, 5, array, order )  ==  -1
          bschoi_c (    17, 5, array, order )  ==  -1

       That is,

          array[4] ==  1000
          array[1] ==     1
          array[3] == 10000

#### Restrictions

       1)  `order' is assumed to give the order of the elements of `array'
           in increasing order. If this condition is not met, the results
           of bschoi_c are unpredictable.

#### Literature_References

       None.

#### Author_and_Institution

       N.J. Bachman        (JPL)
       J. Diaz del Rio     (ODC Space)
       W.L. Taber          (JPL)
       I.M. Underwood      (JPL)

#### Version

       -CSPICE Version 1.0.1, 08-JUL-2021 (JDR)

           Edited the header to comply with NAIF standard. Updated
           -Index_Entries to better explain the objective of this function.

       -CSPICE Version 1.0.0, 10-JUL-2002 (NJB) (WLT) (IMU)

#### Index_Entries

       binary search for an integer using an order vector

#### Link to routine bschoi_c source file bschoi_c.c

    Fri Dec 31 18:41:02 2021