function
<cstdlib>

qsort

void qsort (void* base, size_t num, size_t size,
            int (*compar)(const void*,const void*));
Sort elements of array
Sorts the num elements of the array pointed by base, each element size bytes long, using the compar function to determine the order.

The sorting algorithm used by this function compares pairs of elements by calling the specified compar function with pointers to them as argument.

The function does not return any value, but modifies the content of the array pointed by base reordering its elements as defined by compar.

The order of equivalent elements is undefined.

Parameters

base
Pointer to the first object of the array to be sorted, converted to a void*.
num
Number of elements in the array pointed by base.
size_t is an unsigned integral type.
size
Size in bytes of each element in the array.
size_t is an unsigned integral type.
compar
Pointer to a function that compares two elements.
This function is called repeatedly by qsort to compare two elements. It shall follow the following prototype:
 
int compar (const void* p1, const void* p2);

Taking two pointers as arguments (both converted to const void*). The function defines the order of the elements by returning (in a stable and transitive manner):
return valuemeaning
<0The element pointed by p1 goes before the element pointed by p2
0The element pointed by p1 is equivalent to the element pointed by p2
>0The element pointed by p1 goes after the element pointed by p2

For types that can be compared using regular relational operators, a general compar function may look like:

1
2
3
4
5
6
int compareMyType (const void * a, const void * b)
{
  if ( *(MyType*)a <  *(MyType*)b ) return -1;
  if ( *(MyType*)a == *(MyType*)b ) return 0;
  if ( *(MyType*)a >  *(MyType*)b ) return 1;
}


Return Value

none

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
/* qsort example */
#include <stdio.h>      /* printf */
#include <stdlib.h>     /* qsort */

int values[] = { 40, 10, 100, 90, 20, 25 };

int compare (const void * a, const void * b)
{
  return ( *(int*)a - *(int*)b );
}

int main ()
{
  int n;
  qsort (values, 6, sizeof(int), compare);
  for (n=0; n<6; n++)
     printf ("%d ",values[n]);
  return 0;
}


Output:

10 20 25 40 90 100

Complexity

Unspecified, but quicksorts are generally linearithmic in num, on average, calling compar approximately num*log2(num) times.

Data races

The function accesses and/or modifies the num elements in the array pointed by base.

Exceptions (C++)

If comp does not throw exceptions, this function throws no exceptions (no-throw guarantee).

If base does not point to an array of at least num*size bytes, or if comp does not behave as described above, it causes undefined behavior.

See also