From 98fe149e34b48d0c4d69105315cc7c61be8276ec Mon Sep 17 00:00:00 2001 From: Anders Kaseorg Date: Thu, 11 Dec 2014 05:33:22 -0500 Subject: [PATCH] manual: Correct guarantee about pointers compared by qsort() C99, C11, POSIX, and the glibc implementation do guarantee that the pointers passed to the qsort comparison function lie within the array. Signed-off-by: Anders Kaseorg --- ChangeLog | 5 +++++ manual/search.texi | 14 ++++++++------ 2 files changed, 13 insertions(+), 6 deletions(-) diff --git a/ChangeLog b/ChangeLog index 642f84d..eaaff71 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2014-12-21 Anders Kaseorg + + * manual/search.texi: (Array Sort Function): Clarify stable sorting + guarantees. + 2014-12-20 Chris Metcalf * sysdeps/unix/sysv/linux/tile/localplt.data: New file. diff --git a/manual/search.texi b/manual/search.texi index 8aff574..662527f 100644 --- a/manual/search.texi +++ b/manual/search.texi @@ -164,8 +164,8 @@ To sort an array using an arbitrary comparison function, use the @comment ISO @deftypefun void qsort (void *@var{array}, size_t @var{count}, size_t @var{size}, comparison_fn_t @var{compare}) @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}} -The @var{qsort} function sorts the array @var{array}. The array contains -@var{count} elements, each of which is of size @var{size}. +The @code{qsort} function sorts the array @var{array}. The array +contains @var{count} elements, each of which is of size @var{size}. The @var{compare} function is used to perform the comparison on the array elements. This function is called with two pointer arguments and @@ -180,10 +180,12 @@ This can make a difference when the comparison considers only part of the elements. Two elements with the same sort key may differ in other respects. -The addresses passed to the comparison function need not correspond with -the original location of the objects, and need not even lie within the -original array. The only way to perform a stable sort with @var{qsort} -is to first augment the objects with a monotonic counter of some kind. +Although the object addresses passed to the comparison function lie +within the array, they need not correspond with the original locations +of those objects because the sorting algorithm may swap around objects +in the array before making some comparisons. The only way to perform +a stable sort with @code{qsort} is to first augment the objects with a +monotonic counter of some kind. Here is a simple example of sorting an array of doubles in numerical order, using the comparison function defined above (@pxref{Comparison -- 2.7.4