qsort()和bsearch()

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 to by base, element size, 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 to by base reordering its elements as defined by compar.

The order of equivalent elements is undefined.

Parameters

1.base

Pointer to the first object of the array to be sorted, converted to a void*.

2.num

Number of elements in the array pointed to by base.
size_t is an unsigned integral type.

3.size

Size in bytes of each element in the array.
size_t is an unsigned integral type.

4.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 value	meaning
<0	The element pointed to by p1 goes before the element pointed to by p2
0	The element pointed to by p1 is equivalent to the element pointed to by p2
>0	The element pointed to by p1 goes after the element pointed to by p2

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

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

/* 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 to 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.

---

bsearch

void* bsearch (const void* key, const void* base,
               size_t num, size_t size,
               int (*compar)(const void*,const void*));

Binary search in array

Searches the given key in the array pointed to by base (which is formed by num elements, each of size bytes), and returns a void* pointer to a matching element, if found.

To perform the search, the function performs a series of calls to compar with key as first argument and elements of the array pointed to by base as second argument.

Because this function may be optimized to use a non-linear search algorithm (presumably a binary search), the elements that compare less than key using compar should precede those that compare equal, and these should precede those that compare greater. This requirement is fulfilled by any array ordered with the same criteria used by compar(as if sorted with qsort).

Parameters

key

Pointer to the object that serves as key for the search, type-casted to a void*.

base

Pointer to the first object of the array where the search is performed, type-casted to a void*.

num

Number of elements in the array pointed to 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 bsearch to compare key against individual elements in base. It shall follow the following prototype:

int compar (const void* pkey, const void* pelem);

Taking two pointers as arguments: the first is always key, and the second points to an element of the array (both type-casted to const void*). The function shall return (in a stable and transitive manner):

return value	meaning
<0	The element pointed to by pkey goes before the element pointed to by pelem
0	The element pointed to by pkey is equivalent to the element pointed to by pelem
>0	The element pointed to by pkey goes after the element pointed to by pelem

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

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

A pointer to an entry in the array that matches the search key. If there are more than one matching elements (i.e., elements for which compar would return 0), this may point to any of them (not necessarily the first one).

If key is not found, a null pointer is returned.

Example

/* bsearch example */
#include <stdio.h>      /* printf */
#include <stdlib.h>     /* qsort, bsearch, NULL */

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

int values[] = { 50, 20, 60, 40, 10, 30 };

int main ()
{
  int * pItem;
  int key = 40;
  qsort (values, 6, sizeof (int), compareints);
  pItem = (int*) bsearch (&key, values, 6, sizeof (int), compareints);
  if (pItem!=NULL)
    printf ("%d is in the array.\n",*pItem);
  else
    printf ("%d is not in the array.\n",key);
  return 0;
}

In the example, compareints compares the values pointed to by the two parameters as int values and returns the result of subtracting their pointed values, which gives 0 as result if they are equal, a positive result if the value pointed to by ais greater than the one pointed to by b or a negative result if the value pointed to by b is greater.

In the main function the target array is sorted with qsort before calling bsearch to search for a value.

Output:

40 is in the array.

For C strings, strcmp can directly be used as the compar argument for bsearch:

/* bsearch example with strings */
#include <stdio.h>      /* printf */
#include <stdlib.h>     /* qsort, bsearch, NULL */
#include <string.h>     /* strcmp */

char strvalues[][20] = {"some","example","strings","here"};

int main ()
{
  char * pItem;
  char key[20] = "example";

  /* sort elements in array: */
  qsort (strvalues, 4, 20, (int(*)(const void*,const void*)) strcmp);

  /* search for the key: */
  pItem = (char*) bsearch (key, strvalues, 4, 20, (int(*)(const void*,const void*)) strcmp);

  if (pItem!=NULL)
    printf ("%s is in the array.\n",pItem);
  else
    printf ("%s is not in the array.\n",key);
  return 0;
}

Output:

example is in the array.

Complexity

Unspecified, but binary searches are generally logarithmic in num, on average, calling compar approximately log2(num)+2 times.

Data races

The function accesses the object pointed to by key and any number of the num elements in the array pointed to by base, but does not modify any of them.

Exceptions (C++)

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

If key does not point to an object size bytes long, or if base does not point to an array of at least num properly arranged elements of size bytes each, or if comp does not behave as described above, it causes undefined behavior.