Generate and return bin
, the index of the element of the input ascendingordered array
, such that array(bin) <= value < array(bin+1)
holds for the input value
.
The following conditions hold.

If
value < array(1)
, then bin = 0_IK
.

If
array(size(array)) <= value
, then bin = size(array, kind = IK)
.

The lessthan
<
comparison operator can be also customized by a userdefined comparison supplied as the external function isLess
input argument for arrays that are not ascendingordered.
In such a case, the output bin
satisfies both .not.(value < array(bin))
and value < array(bin+1)
where the <
binary operator is defined by the isLess()
usersupplied function.
 Parameters

[in]  array  : The input contiguous array of shape (:) of either

type
character of kind any supported by the processor (e.g., SK, SKA, SKD , or SKU) of arbitrary length type parameter, or

type
integer of kind any supported by the processor (e.g., IK, IK8, IK16, IK32, or IK64), or

type
complex of kind any supported by the processor (e.g., CK, CK32, CK64, or CK128), or

type
real of kind any supported by the processor (e.g., RK, RK32, RK64, or RK128),
or,

a scalar assumedlength
character of kind any supported by the processor (e.g., SK, SKA, SKD , or SKU),
whose elements will have to be searched for the largest value smaller than the input value .
The input array must be sorted in ascendingorder unless an appropriate isLess external comparison function is supplied according to which the array effectively behaves as if it is ascendingordered.
If the array is of type complex , then only its real component will be compared unless the comparison is defined by the external userspecified input comparison function isLess . 
[in]  value  : The input scalar of the same type and kind as the input array whose value is to be searched in array . 
 isLess  : The external userspecified function that takes two input scalar arguments of the same type and kind as the input array .
It returns a scalar logical of default kind LK that is .true. if the two input arguments meet the userdefined comparison criterion.
Otherwise, it is .false. . If array is a scalar character , the two input arguments to isLess() will be scalar character values of the same length as the input value (which could be larger than 1).
The following illustrates the generic interface of isLess() , function isLess(value, segment) result(isLess)
TYPE(KIND) , intent(in) :: value, segment
logical(LK) :: isLess
end function
This module defines the relevant Fortran kind typeparameters frequently used in the ParaMonte librar...
integer, parameter LK The default logical kind in the ParaMonte library: kind(.true.) in Fortran, kind(....
where TYPE(KIND) represents the type and kind of the input argument array , which can be one of the following, integer(IK) , intent(in) :: value, segment
complex(CK) , intent(in) :: value, segment
real(RK) , intent(in) :: value, segment
character(len(value),SK), intent(in) :: value, segment
This external function is extremely useful where a userdefined comparison check other than < is desired, for example, when the array segments should match the input value only within a given threshold or, when the casesensitivity in character comparisons do not matter, or when the input array can be considered as an ascendingordered sequence under certain conditions, for example, when only the magnitudes of the array elements are considered or when the array elements are multiplied by 1 or inverted (that is, when the array is in descendingorder). See below for example use cases.
(optional, the default comparison operator is < .) 
 Returns
bin
: The output scalar integer
of default kind IK representing the index of the element of array
for which array(bin) <= value < array(bin+1)
holds or if isLess()
is specified, the following conditions hold,
isLess(value, array(bin+1)) .and. .not. isLess(value, array(bin)) ! evaluates to .true._LK
Possible calling interfaces ⛓
bin
= getBin(array, value, isLess)
Generate and return bin, the index of the element of the input ascendingordered array,...
This module contains procedures and generic interfaces for finding the specific array index whose ele...
 Warning
 The procedures under this generic interface are
impure
when the userspecified external
procedure isLess
is specified as input argument.

Note that in Fortran, trailing blanks are ignored in character comparison, that is,
"Fortran" == "Fortran "
yields .true.
.

The input
array
must be a nonempty sequence of values that is sorted according to the criterion specified by the external
function isLess()
or if it is missing, then the values are sorted in ascending order.
These conditions are verified only if the library is built with the preprocessor macro CHECK_ENABLED=1
.

Be mindful of scenario where there are duplicate values in the input
array
.
In such cases, the returned bin
is not necessarily the index of the first or the last occurrence of such value.
See below for illustrative examples.

The
pure
procedure(s) documented herein become impure
when the ParaMonte library is compiled with preprocessor macro CHECK_ENABLED=1
.
By default, these procedures are pure
in release
build and impure
in debug
and testing
builds.
 See also
 getLoc
setLoc
setReplaced
getReplaced
setInserted
setSplit
Example usage ⛓
11 character(:, SK),
allocatable :: string_SK, strval_SK
12 character(
2, SK),
allocatable :: Array_SK(:)
13 integer(IK) ,
allocatable :: Array_IK(:)
14 real(RK) ,
allocatable :: Array_RK(:)
16 character(
2,SK) :: value_SK
17 integer(IK) :: value_IK
22 type(display_type) :: disp
27 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
28 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
29 call disp%show(
"! Find the index of the largest element in the ascendingordered `array` that is smaller than or equal to `value` via Binary Search.")
30 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
31 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
34 string_SK
= "abcdefghi"
35 Array_SK
= [
"aa",
"bb",
"dd",
"ee",
"ff",
"gg",
"hh",
"ii",
"jj"]
36 Array_RK
= [
0._RK,
1._RK,
2._RK,
4._RK,
5._RK,
6._RK]
37 Array_IK
= [
0_IK,
1_IK,
2_IK,
4_IK,
5_IK,
6_IK]
45 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
46 call disp%show(
"! Find the index of character scalar.")
47 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
52 call disp%show( string_SK, deliml
= SK_
"""" )
54 call disp%show( strval_SK, deliml
= SK_
"""" )
55 call disp%show(
"bin = getBin(string_SK, strval_SK) ! index of the largest value in `array` that is smaller than or equal to the input `value`.")
56 bin
= getBin(string_SK, strval_SK)
64 call disp%show( string_SK, deliml
= SK_
"""" )
66 call disp%show( strval_SK, deliml
= SK_
"""" )
67 call disp%show(
"bin = getBin(string_SK, strval_SK) ! index of the largest value in `array` that is smaller than or equal to the input `value`.")
68 bin
= getBin(string_SK, strval_SK)
76 call disp%show( string_SK, deliml
= SK_
"""" )
78 call disp%show( strval_SK, deliml
= SK_
"""" )
79 call disp%show(
"bin = getBin(string_SK, strval_SK) ! index of the largest value in `array` that is smaller than or equal to the input `value`.")
80 bin
= getBin(string_SK, strval_SK)
86 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
87 call disp%show(
"! Find the index of character array.")
88 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
93 call disp%show( Array_SK, deliml
= SK_
"""" )
95 call disp%show( value_SK, deliml
= SK_
"""" )
96 call disp%show(
"bin = getBin(Array_SK, value_SK) ! index of the largest value in `array` that is smaller than or equal to the input `value`.")
97 bin
= getBin(Array_SK, value_SK)
103 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
104 call disp%show(
"! Find the index of integer array.")
105 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
113 call disp%show(
"bin = getBin(Array_IK, value_IK) ! index of the largest value in `array` that is smaller than or equal to the input `value`.")
114 bin
= getBin(Array_IK, value_IK)
120 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
121 call disp%show(
"! Find the index of real array.")
122 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
130 call disp%show(
"bin = getBin(Array_RK, value_RK) ! index of the largest value in `array` that is smaller than or equal to the input `value`.")
131 bin
= getBin(Array_RK, value_RK)
137 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
138 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
139 call disp%show(
"! The index of a `value` that is out of range.")
140 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
141 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
144 value_IK
= Array_IK(
1)
 1_IK
150 call disp%show(
"bin = getBin(Array_IK, value_IK) ! index of the largest value in `array` that is smaller than or equal to the input `value`.")
151 bin
= getBin(Array_IK, value_IK)
156 value_IK
= Array_IK(
size(Array_IK))
+ 1_IK
162 call disp%show(
"bin = getBin(Array_IK, value_IK) ! index of the largest value in `array` that is smaller than or equal to the input `value`.")
163 bin
= getBin(Array_IK, value_IK)
169 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
170 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
171 call disp%show(
"! Find the index of the smallest element in the descendingordered `array` that is")
172 call disp%show(
"! larger than or equal to `value` via Binary Search with a custom comparison function.")
173 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
174 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
178 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
179 call disp%show(
"! Find the index of a `value` in a descendingordered input `Array`.")
180 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
184 Array_IK
= Array_IK(
size(Array_IK):
1:
1)
190 call disp%show(
"bin = getBin(Array_IK, value_IK, isLess_IK) ! index of the smallest value in `array` that is larger than or equal to the input `value`.")
191 bin
= getBin(Array_IK, value_IK, isLess_IK)
197 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
198 call disp%show(
"! Find the index of a `value` in an input `array` whose absolute value is ascendingordered.")
199 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
202 Array_RK
= [( Array_RK(bin)
*(
1)
**bin, bin
= 1,
size(Array_RK,
kind = IK) )]
208 call disp%show(
"bin = getBin(Array_RK, value_RK, isLess_RK) ! index of the largest absolute value in `array` that is smaller than or equal to the input `value`.")
209 bin
= getBin(Array_RK, value_RK, isLess_RK)
215 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
216 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
217 call disp%show(
"! Be mindful of duplicate values in the input `Array`.")
218 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
219 call disp%show(
"!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
223 Array_IK
= int([
0,
0,
3,
3,
3],
kind = IK)
229 call disp%show(
"bin = getBin(Array_IK, value_IK) ! index of the largest value in `array` that is smaller than or equal to the input `value`.")
230 bin
= getBin(Array_IK, value_IK)
236 Array_IK
= int([
0,
0,
3,
3,
3],
kind = IK)
242 call disp%show(
"bin = getBin(Array_IK, value_IK) ! index of the largest value in `array` that is smaller than or equal to the input `value`.")
243 bin
= getBin(Array_IK, value_IK)
252 pure function isLess_IK(value, segment)
result(less)
254 integer(IK) ,
intent(in) ::
value, segment
256 less
= value
> segment
261 pure function isLess_RK(value, segment)
result(less)
263 real(RK) ,
intent(in) ::
value, segment
265 less
= value
< abs(segment)
This is a generic method of the derived type display_type with pass attribute.
This is a generic method of the derived type display_type with pass attribute.
This module contains classes and procedures for input/output (IO) or generic display operations on st...
type(display_type) disp
This is a scalar module variable an object of type display_type for general display.
integer, parameter RK
The default real kind in the ParaMonte library: real64 in Fortran, c_double in CFortran Interoperati...
integer, parameter IK
The default integer kind in the ParaMonte library: int32 in Fortran, c_int32_t in CFortran Interoper...
integer, parameter SK
The default character kind in the ParaMonte library: kind("a") in Fortran, c_char in CFortran Intero...
Generate and return an object of type display_type.
Example Unix compile command via Intel ifort
compiler ⛓
3ifort fpp standardsemantics O3 Wl,rpath,../../../lib I../../../inc main.F90 ../../../lib/libparamonte* o main.exe
Example Windows Batch compile command via Intel ifort
compiler ⛓
2set PATH=..\..\..\lib;%PATH%
3ifort /fpp /standardsemantics /O3 /I:..\..\..\include main.F90 ..\..\..\lib\libparamonte*.lib /exe:main.exe
Example Unix / MinGW compile command via GNU gfortran
compiler ⛓
3gfortran cpp ffreelinelengthnone O3 Wl,rpath,../../../lib I../../../inc main.F90 ../../../lib/libparamonte* o main.exe
Example output ⛓
18bin
= getBin(string_SK, strval_SK)
27bin
= getBin(string_SK, strval_SK)
36bin
= getBin(string_SK, strval_SK)
47"aa",
"bb",
"dd",
"ee",
"ff",
"gg",
"hh",
"ii",
"jj"
50bin
= getBin(Array_SK, value_SK)
64bin
= getBin(Array_IK, value_IK)
75+0.0000000000000000,
+1.0000000000000000,
+2.0000000000000000,
+4.0000000000000000,
+5.0000000000000000,
+6.0000000000000000
78bin
= getBin(Array_RK, value_RK)
94bin
= getBin(Array_IK, value_IK)
100+0,
+1,
+2,
+4,
+5,
+6
103bin
= getBin(Array_IK, value_IK)
122+6,
+5,
+4,
+2,
+1,
+0
125bin
= getBin(Array_IK, value_IK, isLess_IK)
1360.0000000000000000,
+1.0000000000000000,
2.0000000000000000,
+4.0000000000000000,
5.0000000000000000,
+6.0000000000000000
139bin
= getBin(Array_RK, value_RK, isLess_RK)
155bin
= getBin(Array_IK, value_IK)
164bin
= getBin(Array_IK, value_IK)
 Test:
 test_pm_arraySearch
Final Remarks ⛓
If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.

If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.
This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.
 Copyright
 Computational Data Science Lab
 Author:
 Amir Shahmoradi, September 1, 2017, 12:00 AM, Institute for Computational Engineering and Sciences (ICES), The University of Texas Austin
Definition at line 174 of file pm_arraySearch.F90.