GNU Astronomy Utilities


Next: , Previous: , Up: Gnuastro library   [Contents][Index]


10.3.18 Qsort functions (qsort.h)

When sorting a dataset is necessary, the C programming language provides the qsort (Quick sort) function. qsort is a generic function which allows you to sort any kind of data structure (not just a single array of numbers). To define “greater” and “smaller” (for sorting), qsort needs another function, even for simple numerical types. The functions introduced in this section are to passed onto qsort.

The first class of functions below (with TYPE in their names) can be used for sorting a simple numeric array. Just replace TYPE with the dataset’s numeric datatype. The second set of functions can be used to sort indexs (leave the actual numbers untouched). To use the second set of functions, a global variable or structure are also necessary as described below.

Global variable: gal_qsort_index_single

Pointer to a floating point array (float *) to use as a reference in gal_qsort_index_single_d or gal_qsort_index_single_i, see the explanation of these functions for more. Note that if more than one array is to be sorted in a multi-threaded operation, the two functions will not work as expected. Therefore, if the operation is multi-threaded, but all the threads just sort the indexs based on a single array, this global variable can safely be used.

Type (C struct): gal_qsort_index_multi

Structure to get the sorted indexs of multiple datasets on multiple threads with gal_qsort_index_multi_d or gal_qsort_index_multi_i. Note that the values array will not be changed by these functions, it is only read. Therefore all the values elements in the (to be sorted) array of gal_qsort_index_multi must point to the same place.

struct gal_qsort_index_multi
{
  float *values;         /* Array of values (same in all).      */
  size_t  index;         /* Index of each element to be sorted. */
};
Function:
int
gal_qsort_TYPE_d (const void *a, const void *b)

When passed to qsort, this function will sort a TYPE array in decreasing order (first element will be the largest). Please replace TYPE (in the function name) with one of the Numeric data types, for example gal_qsort_int32_d, or gal_qsort_float64_d.

Function:
int
gal_qsort_TYPE_i (const void *a, const void *b)

When passed to qsort, this function will sort a TYPE array in increasing order (first element will be the smallest). Please replace TYPE (in the function name) with one of the Numeric data types, for example gal_qsort_int32_i, or gal_qsort_float64_i.

Function:
int
gal_qsort_index_single_d (const void *a, const void *b)

When passed to qsort, this function will sort a size_t array based on decreasing values in the gal_qsort_index_arr single precision floating point array. The floating point array will not be changed, it is only read. For example, if we have the following source code:

#include <stdio.h>
#include <stdlib.h>           /* qsort is defined in stdlib.h. */
#include <gnuastro/qsort.h>

int
main (void)
{
  size_t s[4]={0, 1, 2, 3};
  float f[4]={1.3,0.2,1.8,0.1};
  gal_qsort_index_arr=f;
  qsort(s, 4, sizeof(size_t), gal_qsort_index_single_d);
  printf("%zu, %zu, %zu, %zu\n", s[0], s[1], s[2], s[3]);
  return EXIT_SUCCESS;
}

The output will be: 2, 0, 1, 3.

Function:
int
gal_qsort_index_single_i (const void *a, const void *b)

Similar to gal_qsort_index_single_d, but will sort the indexes such that the values of gal_qsort_index_arr are in increasing order.

Function:
int
gal_qsort_index_multi_d (const void *a, const void *b)

When passed to qsort with an array of gal_qsort_index_multi, this function will sort the array based on the values of the given indexs. The sorting will be ordered according to the values pointer of gal_qsort_index_multi. Note that values must point to the same place in all the structures of the gal_qsort_index_multi array.

This function is only useful when the the indexs of multiple arrays on multiple threads are to be sorted. If your program is single threaded, or all the indexs belong to a single array (sorting different sub-sets of indexs in a single array on multiple threads), it is recommended to use gal_qsort_index_single_d.

Function:
int
gal_qsort_index_multi_i (const void *a, const void *b)

Similar to gal_qsort_index_multi_d, but the result will be sorted in increasing order (first element will have the smallest value).


Next: , Previous: , Up: Gnuastro library   [Contents][Index]