0
# Array Searching and Sorting
1

2
Functions for finding, sorting, and organizing array elements. Includes search operations, sorting algorithms, and set operations for array analysis and data organization.
3

4
## Capabilities
5

6
### Searching Functions
7

8
Find elements and their positions in arrays.
9

10
```python { .api }
11
def where(condition, x=None, y=None):
12
    """
13
    Return elements chosen from x or y depending on condition.
14
    
15
    Parameters:
16
    - condition: array_like, bool, condition to evaluate
17
    - x, y: array_like, values to choose from
18
    
19
    Returns:
20
    ndarray or tuple: Indices or selected elements
21
    """
22

23
def argwhere(a):
24
    """
25
    Find indices of non-zero elements.
26
    
27
    Parameters:
28
    - a: array_like, input array
29
    
30
    Returns:
31
    ndarray: Indices of non-zero elements
32
    """
33

34
def nonzero(a):
35
    """
36
    Return indices of non-zero elements.
37
    
38
    Parameters:
39
    - a: array_like, input array
40
    
41
    Returns:
42
    tuple of arrays: Indices of non-zero elements
43
    """
44

45
def argmax(a, axis=None, out=None, keepdims=False):
46
    """
47
    Return indices of maximum values along axis.
48
    
49
    Parameters:
50
    - a: array_like, input array
51
    - axis: int, axis along which to search
52
    - out: array, output array
53
    - keepdims: bool, keep reduced dimensions
54
    
55
    Returns:
56
    ndarray: Indices of maximum values
57
    """
58

59
def argmin(a, axis=None, out=None, keepdims=False):
60
    """
61
    Return indices of minimum values along axis.
62
    
63
    Parameters:
64
    - a: array_like, input array
65
    - axis: int, axis along which to search
66
    - out: array, output array
67
    - keepdims: bool, keep reduced dimensions
68
    
69
    Returns:
70
    ndarray: Indices of minimum values
71
    """
72

73
def searchsorted(a, v, side='left', sorter=None):
74
    """
75
    Find indices where elements should be inserted to maintain order.
76
    
77
    Parameters:
78
    - a: array_like, sorted input array
79
    - v: array_like, values to insert
80
    - side: {'left', 'right'}, insertion side
81
    - sorter: array_like, optional sorting indices
82
    
83
    Returns:
84
    ndarray: Insertion indices
85
    """
86
```
87

88
### Sorting Functions
89

90
Sort array elements using various algorithms.
91

92
```python { .api }
93
def sort(a, axis=-1, kind=None, order=None, stable=None):
94
    """
95
    Return a sorted copy of an array.
96
    
97
    Parameters:
98
    - a: array_like, array to sort
99
    - axis: int, axis to sort along
100
    - kind: {'quicksort', 'mergesort', 'heapsort', 'stable'}, sorting algorithm
101
    - order: str or list of str, field order for structured arrays
102
    - stable: bool, stable sorting
103
    
104
    Returns:
105
    ndarray: Sorted array
106
    """
107

108
def argsort(a, axis=-1, kind=None, order=None, stable=None):
109
    """
110
    Return indices that would sort an array.
111
    
112
    Parameters:
113
    - a: array_like, array to sort
114
    - axis: int, axis to sort along
115
    - kind: {'quicksort', 'mergesort', 'heapsort', 'stable'}, sorting algorithm
116
    - order: str or list of str, field order for structured arrays
117
    - stable: bool, stable sorting
118
    
119
    Returns:
120
    ndarray: Indices for sorting
121
    """
122

123
def partition(a, kth, axis=-1, kind='introselect', order=None):
124
    """
125
    Return a partitioned copy of an array.
126
    
127
    Parameters:
128
    - a: array_like, array to partition
129
    - kth: int or sequence of ints, element index to partition around
130
    - axis: int, axis to partition along
131
    - kind: {'introselect'}, selection algorithm
132
    - order: str or list of str, field order for structured arrays
133
    
134
    Returns:
135
    ndarray: Partitioned array
136
    """
137

138
def argpartition(a, kth, axis=-1, kind='introselect', order=None):
139
    """
140
    Return indices that would partition an array.
141
    
142
    Parameters:
143
    - a: array_like, array to partition
144
    - kth: int or sequence of ints, element index to partition around
145
    - axis: int, axis to partition along
146
    - kind: {'introselect'}, selection algorithm
147
    - order: str or list of str, field order for structured arrays
148
    
149
    Returns:
150
    ndarray: Indices for partitioning
151
    """
152

153
def lexsort(keys, axis=-1):
154
    """
155
    Perform indirect stable sort using sequence of keys.
156
    
157
    Parameters:
158
    - keys: sequence of array_like, sorting keys
159
    - axis: int, axis to sort along
160
    
161
    Returns:
162
    ndarray: Indices for lexicographic sorting
163
    """
164
```
165

166
### Set Operations
167

168
Set-like operations on arrays.
169

170
```python { .api }
171
def unique(ar, return_index=False, return_inverse=False, return_counts=False, axis=None, equal_nan=True):
172
    """
173
    Find unique elements of an array.
174
    
175
    Parameters:
176
    - ar: array_like, input array
177
    - return_index: bool, return indices of unique elements
178
    - return_inverse: bool, return indices to reconstruct input
179
    - return_counts: bool, return counts of unique elements
180
    - axis: int, axis to operate along
181
    - equal_nan: bool, treat NaN values as equal
182
    
183
    Returns:
184
    ndarray or tuple: Unique elements and optional extra arrays
185
    """
186

187
def in1d(ar1, ar2, assume_unique=False, invert=False, kind=None):
188
    """
189
    Test whether elements of 1-D array are in second array.
190
    
191
    Parameters:
192
    - ar1, ar2: array_like, input arrays
193
    - assume_unique: bool, assume input arrays contain unique elements
194
    - invert: bool, invert boolean result
195
    - kind: {None, 'sort', 'table'}, algorithm to use
196
    
197
    Returns:
198
    ndarray: Boolean array of same shape as ar1
199
    """
200

201
def isin(element, test_elements, assume_unique=False, invert=False, kind=None):
202
    """
203
    Calculates element in test_elements, broadcasting over element only.
204
    
205
    Parameters:
206
    - element: array_like, input array
207
    - test_elements: array_like, values against which to test
208
    - assume_unique: bool, assume test_elements contains unique elements
209
    - invert: bool, invert boolean result
210
    - kind: {None, 'sort', 'table'}, algorithm to use
211
    
212
    Returns:
213
    ndarray: Boolean array of same shape as element
214
    """
215

216
def intersect1d(ar1, ar2, assume_unique=False, return_indices=False):
217
    """
218
    Find intersection of two arrays.
219
    
220
    Parameters:
221
    - ar1, ar2: array_like, input arrays
222
    - assume_unique: bool, assume input arrays are unique
223
    - return_indices: bool, return indices of intersection
224
    
225
    Returns:
226
    ndarray or tuple: Intersection and optional indices
227
    """
228

229
def union1d(ar1, ar2):
230
    """
231
    Find union of two arrays.
232
    
233
    Parameters:
234
    - ar1, ar2: array_like, input arrays
235
    
236
    Returns:
237
    ndarray: Unique, sorted union of input arrays
238
    """
239

240
def setdiff1d(ar1, ar2, assume_unique=False):
241
    """
242
    Find set difference of two arrays.
243
    
244
    Parameters:
245
    - ar1, ar2: array_like, input arrays
246
    - assume_unique: bool, assume input arrays are unique
247
    
248
    Returns:
249
    ndarray: Unique values in ar1 not in ar2
250
    """
251

252
def setxor1d(ar1, ar2, assume_unique=False):
253
    """
254
    Find set exclusive-or of two arrays.
255
    
256
    Parameters:
257
    - ar1, ar2: array_like, input arrays
258
    - assume_unique: bool, assume input arrays are unique
259
    
260
    Returns:
261
    ndarray: Unique values in either ar1 or ar2 but not both
262
    """
263
```
264

265
## Usage Examples
266

267
### Searching Arrays
268

269
```python
270
import numpy as np
271

272
# Sample data
273
data = np.array([3, 1, 4, 1, 5, 9, 2, 6])
274

275
# Find indices of elements
276
max_idx = np.argmax(data)        # 5 (index of maximum value 9)
277
min_idx = np.argmin(data)        # 1 (index of minimum value 1)
278

279
# Find where condition is true
280
large_indices = np.where(data > 4)  # (array([4, 5, 7]),)
281
large_values = data[data > 4]       # [5, 9, 6]
282

283
# Non-zero elements
284
arr_with_zeros = np.array([0, 1, 0, 3, 0, 5])
285
nonzero_indices = np.nonzero(arr_with_zeros)  # (array([1, 3, 5]),)
286
```
287

288
### Sorting Operations
289

290
```python
291
import numpy as np
292

293
data = np.array([3, 1, 4, 1, 5, 9, 2, 6])
294

295
# Sort array
296
sorted_data = np.sort(data)       # [1, 1, 2, 3, 4, 5, 6, 9]
297

298
# Get indices for sorting
299
sort_indices = np.argsort(data)   # [1, 3, 6, 0, 2, 4, 7, 5]
300
manually_sorted = data[sort_indices]  # Same as sorted_data
301

302
# Partial sorting with partition
303
partitioned = np.partition(data, 3)  # Elements 0-3 are <= element at index 3
304
```
305

306
### Set Operations
307

308
```python
309
import numpy as np
310

311
arr1 = np.array([1, 2, 3, 4, 5])
312
arr2 = np.array([3, 4, 5, 6, 7])
313

314
# Unique elements
315
unique_vals = np.unique([1, 1, 2, 2, 3, 3])  # [1, 2, 3]
316

317
# Set operations
318
intersection = np.intersect1d(arr1, arr2)     # [3, 4, 5]
319
union = np.union1d(arr1, arr2)               # [1, 2, 3, 4, 5, 6, 7]
320
difference = np.setdiff1d(arr1, arr2)        # [1, 2]
321
symmetric_diff = np.setxor1d(arr1, arr2)     # [1, 2, 6, 7]
322

323
# Membership testing
324
is_member = np.isin(arr1, arr2)              # [False, False, True, True, True]
325
```