stdlib/FreeBSD/qsort.3.patch

   1 --- qsort.3.orig        2009-05-12 11:21:33.000000000 -0700
   2 +++ qsort.3     2009-05-20 15:00:21.000000000 -0700
   3 @@ -40,41 +40,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 nmemb"
  68 -.Fa "size_t size"
  69 +.Fa "size_t nel"
  70 +.Fa "size_t width"
  71 +.Fa "int \*[lp]^compar\*[rp]\*[lp]const void *, const void *\*[rp]"
  72 +.Fc
  73 +#endif
  74 +.Ft void
  75 +.Fo qsort
  76 +.Fa "void *base"
  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 @@ -84,7 +121,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 @@ -92,19 +129,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 @@ -139,7 +176,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 @@ -183,8 +220,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 @@ -195,42 +232,83 @@
 155  Normally,
 156  .Fn qsort
 157  is faster than
 158 -.Fn mergesort
 159 -is faster than
 160 +.Fn mergesort ,
 161 +which is faster than
 162  .Fn heapsort .
 163  Memory availability and pre-existing order in the data can make this
 164  untrue.
 165 +#ifdef UNIFDEF_BLOCKS
 166 +.Pp
 167 +The
 168 +.Fn heapsort_b ,
 169 +.Fn mergesort_b ,
 170 +and
 171 +.Fn qsort_b
 172 +routines are like the corresponding routines without the _b suffix, expect
 173 +that the
 174 +.Fa compar
 175 +callback is a block pointer instead of a function pointer.
 176 +#endif
 177  .Sh RETURN VALUES
 178  The
 179 +#ifdef UNIFDEF_BLOCKS
 180 +.Fn qsort ,
 181 +.Fn qsort_b
 182 +#else
 183  .Fn qsort
 184 +#endif
 185  and
 186  .Fn qsort_r
 187  functions
 188  return no value.
 189  .Pp
 190 -.Rv -std heapsort mergesort
 191 +#ifdef UNIFDEF_BLOCKS
 192 +.ds HEAPSORT_B heapsort_b
 193 +.ds MERGESORT_B mergesort_b
 194 +#endif
 195 +.Rv -std heapsort \*[HEAPSORT_B] mergesort \*[MERGESORT_B]
 196  .Sh ERRORS
 197  The
 198 +#ifdef UNIFDEF_BLOCKS
 199 +.Fn heapsort ,
 200 +.Fn heapsort_b ,
 201 +.Fn mergesort
 202 +and
 203 +.Fn mergesort_b
 204 +#else
 205  .Fn heapsort
 206  and
 207  .Fn mergesort
 208 +#endif
 209  functions succeed unless:
 210  .Bl -tag -width Er
 211  .It Bq Er EINVAL
 212  The
 213 -.Fa size
 214 +.Fa width
 215  argument is zero, or,
 216  the
 217 -.Fa size
 218 +.Fa width
 219  argument to
 220  .Fn mergesort
 221 +#ifdef UNIFDEF_BLOCKS
 222 +or
 223 +.Fn mergesort_b
 224 +#endif
 225  is less than
 226  .Dq "sizeof(void *) / 2" .
 227  .It Bq Er ENOMEM
 228  The
 229 +#ifdef UNIFDEF_BLOCKS
 230 +.Fn heapsort ,
 231 +.Fn heapsort_b ,
 232 +.Fn mergesort
 233 +and
 234 +.Fn mergesort_b
 235 +#else
 236  .Fn heapsort
 237 -or
 238 +and
 239  .Fn mergesort
 240 +#endif
 241  functions
 242  were unable to allocate memory.
 243  .El