stdlib/FreeBSD/qsort.3.patch

   1 --- qsort.3.orig        2010-10-07 21:23:04.000000000 -0700
   2 +++ qsort.3     2010-10-07 21:24:45.000000000 -0700
   3 @@ -36,41 +36,78 @@
   4  .Dt QSORT 3
   5  .Os
   6  .Sh NAME
   7 -.Nm qsort , qsort_r , heapsort , mergesort
   8 +.Nm heapsort ,
   9 +#ifdef UNIFDEF_BLOCKS
  10 +.Nm heapsort_b ,
  11 +#endif
  12 +.Nm mergesort ,
  13 +#ifdef UNIFDEF_BLOCKS
  14 +.Nm mergesort_b ,
  15 +#endif
  16 +.Nm qsort ,
  17 +#ifdef UNIFDEF_BLOCKS
  18 +.Nm qsort_b ,
  19 +#endif
  20 +.Nm qsort_r
  21  .Nd sort functions
  22 -.Sh LIBRARY
  23 -.Lb libc
  24  .Sh SYNOPSIS
  25  .In stdlib.h
  26 -.Ft void
  27 -.Fo qsort
  28 +.Ft int
  29 +.Fo heapsort
  30  .Fa "void *base"
  31 -.Fa "size_t nmemb"
  32 -.Fa "size_t size"
  33 +.Fa "size_t nel"
  34 +.Fa "size_t width"
  35  .Fa "int \*[lp]*compar\*[rp]\*[lp]const void *, const void *\*[rp]"
  36  .Fc
  37 -.Ft void
  38 -.Fo qsort_r
  39 +#ifdef UNIFDEF_BLOCKS
  40 +.Ft int
  41 +.Fo heapsort_b
  42  .Fa "void *base"
  43 -.Fa "size_t nmemb"
  44 -.Fa "size_t size"
  45 -.Fa "void *thunk"
  46 -.Fa "int \*[lp]*compar\*[rp]\*[lp]void *, const void *, const void *\*[rp]"
  47 +.Fa "size_t nel"
  48 +.Fa "size_t width"
  49 +.Fa "int \*[lp]^compar\*[rp]\*[lp]const void *, const void *\*[rp]"
  50  .Fc
  51 +#endif
  52  .Ft int
  53 -.Fo heapsort
  54 +.Fo mergesort
  55  .Fa "void *base"
  56 -.Fa "size_t nmemb"
  57 -.Fa "size_t size"
  58 +.Fa "size_t nel"
  59 +.Fa "size_t width"
  60  .Fa "int \*[lp]*compar\*[rp]\*[lp]const void *, const void *\*[rp]"
  61  .Fc
  62 +#ifdef UNIFDEF_BLOCKS
  63  .Ft int
  64 -.Fo mergesort
  65 +.Fo mergesort_b
  66 +.Fa "void *base"
  67 +.Fa "size_t nel"
  68 +.Fa "size_t width"
  69 +.Fa "int \*[lp]^compar\*[rp]\*[lp]const void *, const void *\*[rp]"
  70 +.Fc
  71 +#endif
  72 +.Ft void
  73 +.Fo qsort
  74  .Fa "void *base"
  75 -.Fa "size_t nmemb"
  76 -.Fa "size_t size"
  77 +.Fa "size_t nel"
  78 +.Fa "size_t width"
  79  .Fa "int \*[lp]*compar\*[rp]\*[lp]const void *, const void *\*[rp]"
  80  .Fc
  81 +#ifdef UNIFDEF_BLOCKS
  82 +.Ft void
  83 +.Fo qsort_b
  84 +.Fa "void *base"
  85 +.Fa "size_t nel"
  86 +.Fa "size_t width"
  87 +.Fa "int \*[lp]^compar\*[rp]\*[lp]const void *, const void *\*[rp]"
  88 +.Fc
  89 +#endif
  90 +.Ft void
  91 +.Fo qsort_r
  92 +.Fa "void *base"
  93 +.Fa "size_t nel"
  94 +.Fa "size_t width"
  95 +.Fa "void *thunk"
  96 +.Fa "int \*[lp]*compar\*[rp]\*[lp]void *, const void *, const void *\*[rp]"
  97 +.Fc
  98  .Sh DESCRIPTION
  99  The
 100  .Fn qsort
 101 @@ -80,7 +117,7 @@
 102  function is a modified selection sort.
 103  The
 104  .Fn mergesort
 105 -function is a modified merge sort with exponential search
 106 +function is a modified merge sort with exponential search,
 107  intended for sorting data with pre-existing order.
 108  .Pp
 109  The
 110 @@ -88,19 +125,19 @@
 111  and
 112  .Fn heapsort
 113  functions sort an array of
 114 -.Fa nmemb
 115 +.Fa nel
 116  objects, the initial member of which is pointed to by
 117  .Fa base .
 118  The size of each object is specified by
 119 -.Fa size .
 120 +.Fa width .
 121  The
 122  .Fn mergesort
 123  function
 124  behaves similarly, but
 125  .Em requires
 126  that
 127 -.Fa size
 128 -be greater than
 129 +.Fa width
 130 +be greater than or equal to
 131  .Dq "sizeof(void *) / 2" .
 132  .Pp
 133  The contents of the array
 134 @@ -135,7 +172,7 @@
 135  .Fn heapsort
 136  are
 137  .Em not
 138 -stable, that is, if two members compare as equal, their order in
 139 +stable; that is, if two members compare as equal, their order in
 140  the sorted array is undefined.
 141  The
 142  .Fn mergesort
 143 @@ -179,8 +216,8 @@
 144  The function
 145  .Fn mergesort
 146  requires additional memory of size
 147 -.Fa nmemb *
 148 -.Fa size
 149 +.Fa nel *
 150 +.Fa width
 151  bytes; it should be used only when space is not at a premium.
 152  The
 153  .Fn mergesort
 154 @@ -192,19 +229,40 @@
 155  .Fn qsort
 156  is faster than
 157  .Fn mergesort
 158 -is faster than
 159 +which is faster than
 160  .Fn heapsort .
 161  Memory availability and pre-existing order in the data can make this
 162  untrue.
 163 +#ifdef UNIFDEF_BLOCKS
 164 +.Pp
 165 +The
 166 +.Fn heapsort_b ,
 167 +.Fn mergesort_b ,
 168 +and
 169 +.Fn qsort_b
 170 +routines are like the corresponding routines without the _b suffix, expect
 171 +that the
 172 +.Fa compar
 173 +callback is a block pointer instead of a function pointer.
 174 +#endif
 175  .Sh RETURN VALUES
 176  The
 177 +#ifdef UNIFDEF_BLOCKS
 178 +.Fn qsort ,
 179 +.Fn qsort_b
 180 +#else
 181  .Fn qsort
 182 +#endif
 183  and
 184  .Fn qsort_r
 185  functions
 186  return no value.
 187  .Pp
 188 -.Rv -std heapsort mergesort
 189 +#ifdef UNIFDEF_BLOCKS
 190 +.ds HEAPSORT_B heapsort_b
 191 +.ds MERGESORT_B mergesort_b
 192 +#endif
 193 +.Rv -std heapsort \*[HEAPSORT_B] mergesort \*[MERGESORT_B]
 194  .Sh COMPATIBILITY
 195  Previous versions of
 196  .Fn qsort
 197 @@ -213,26 +271,46 @@
 198  This is no longer true.
 199  .Sh ERRORS
 200  The
 201 +#ifdef UNIFDEF_BLOCKS
 202 +.Fn heapsort ,
 203 +.Fn heapsort_b ,
 204 +.Fn mergesort ,
 205 +and
 206 +.Fn mergesort_b
 207 +#else
 208  .Fn heapsort
 209  and
 210  .Fn mergesort
 211 +#endif
 212  functions succeed unless:
 213  .Bl -tag -width Er
 214  .It Bq Er EINVAL
 215  The
 216 -.Fa size
 217 +.Fa width
 218  argument is zero, or,
 219  the
 220 -.Fa size
 221 +.Fa width
 222  argument to
 223  .Fn mergesort
 224 +#ifdef UNIFDEF_BLOCKS
 225 +or
 226 +.Fn mergesort_b
 227 +#endif
 228  is less than
 229  .Dq "sizeof(void *) / 2" .
 230  .It Bq Er ENOMEM
 231  The
 232 +#ifdef UNIFDEF_BLOCKS
 233 +.Fn heapsort ,
 234 +.Fn heapsort_b ,
 235 +.Fn mergesort ,
 236 +or
 237 +.Fn mergesort_b
 238 +#else
 239  .Fn heapsort
 240  or
 241  .Fn mergesort
 242 +#endif
 243  functions
 244  were unable to allocate memory.
 245  .El