stdlib/FreeBSD/tsearch.3.patch

   1 --- tsearch.3.orig      2007-03-06 15:44:54.000000000 -0800
   2 +++ tsearch.3   2007-03-06 16:04:48.000000000 -0800
   3 @@ -31,18 +31,36 @@
   4  .Dt TSEARCH 3
   5  .Os
   6  .Sh NAME
   7 -.Nm tsearch , tfind , tdelete , twalk
   8 +.Nm tdelete ,
   9 +.Nm tfind ,
  10 +.Nm tsearch ,
  11 +.Nm twalk
  12  .Nd manipulate binary search trees
  13  .Sh SYNOPSIS
  14  .In search.h
  15  .Ft void *
  16 -.Fn tdelete "const void * restrict key" "void ** restrict rootp" "int (*compar) (const void *, const void *)"
  17 +.Fo tdelete
  18 +.Fa "const void *restrict key"
  19 +.Fa "void **restrict rootp"
  20 +.Fa "int (*compar) (const void *key1, const void *key2)"
  21 +.Fc
  22  .Ft void *
  23 -.Fn tfind "const void *key" "void * const *rootp" "int (*compar) (const void *, const void *)"
  24 +.Fo tfind
  25 +.Fa "const void *key"
  26 +.Fa "void *const *rootp"
  27 +.Fa "int (*compar) (const void *key1, const void *key2)"
  28 +.Fc
  29  .Ft void *
  30 -.Fn tsearch "const void *key" "void **rootp" "int (*compar) (const void *, const void *)"
  31 +.Fo tsearch
  32 +.Fa "const void *key"
  33 +.Fa "void **rootp"
  34 +.Fa "int (*compar) (const void *key1, const void *key2)"
  35 +.Fc
  36  .Ft void
  37 -.Fn twalk "const void *root" "void (*compar) (const void *, VISIT, int)"
  38 +.Fo twalk
  39 +.Fa "const void *root"
  40 +.Fa "void (*compar) (const void *node, VISIT order, int level)"
  41 +.Fc
  42  .Sh DESCRIPTION
  43  The
  44  .Fn tdelete ,
  45 @@ -50,39 +68,46 @@
  46  .Fn tsearch ,
  47  and
  48  .Fn twalk
  49 -functions manage binary search trees based on algorithms T and D
  50 +functions manage binary search trees, based on algorithms T and D
  51  from Knuth (6.2.2).
  52  The comparison function passed in by
  53 -the user has the same style of return values as
  54 +the user takes two arguments, each of which is a key
  55 +pointer.
  56 +This function has the same style of return values as
  57  .Xr strcmp 3 .
  58  .Pp
  59  The
  60  .Fn tfind
  61  function
  62 -searches for the datum matched by the argument
  63 +searches for a node whose key matches the argument
  64  .Fa key
  65  in the binary tree rooted at
  66  .Fa rootp ,
  67 -returning a pointer to the datum if it is found and NULL
  68 +returning a pointer to the node if it is found and NULL
  69  if it is not.
  70  .Pp
  71 +Note that a node is itself a pointer to the key of the node.
  72 +Thus, you should generally cast this result to a
  73 +double pointer to the data type stored in the tree, for example
  74 +(struct myType **), and use double indirection to retrieve the
  75 +original key value.
  76 +.Pp
  77  The
  78  .Fn tsearch
  79 -function
  80 -is identical to
  81 +function is identical to
  82  .Fn tfind
  83 -except that if no match is found,
  84 +except that, if no match is found,
  85 +it inserts a new node for the
  86  .Fa key
  87 -is inserted into the tree and a pointer to it is returned.
  88 +into the tree and returns a pointer to the node.
  89  If
  90  .Fa rootp
  91 -points to a NULL value a new binary search tree is created.
  92 +points to a NULL value, a new binary search tree is created.
  93  .Pp
  94  The
  95  .Fn tdelete
  96 -function
  97 -deletes a node from the specified binary search tree and returns
  98 -a pointer to the parent of the node to be deleted.
  99 +function deletes a node from the specified binary search tree
 100 +and returns a pointer to the parent of the node that was deleted.
 101  It takes the same arguments as
 102  .Fn tfind
 103  and
 104 @@ -93,20 +118,44 @@
 105  .Pp
 106  The
 107  .Fn twalk
 108 -function
 109 -walks the binary search tree rooted in
 110 +function walks the binary search tree rooted in
 111  .Fa root
 112  and calls the function
 113  .Fa action
 114  on each node.
 115  The
 116  .Fa action
 117 -function
 118 -is called with three arguments: a pointer to the current node,
 119 +function is called with three arguments: a pointer to the current node,
 120  a value from the enum
 121  .Sy "typedef enum { preorder, postorder, endorder, leaf } VISIT;"
 122  specifying the traversal type, and a node level (where level
 123  zero is the root of the tree).
 124 +.Pp
 125 +As
 126 +.Fn twalk
 127 +traverses the tree, it calls the
 128 +.Fa action
 129 +function with the traversal type "preorder"
 130 +before visiting the left subtree of the
 131 +.Fa node ,
 132 +with the
 133 +traversal type "postorder" before visiting the right subtree
 134 +of the
 135 +.Fa node ,
 136 +and with the traversal type "endorder" after
 137 +visiting the right subtree of the
 138 +.Fa node .
 139 +.Pp.
 140 +The
 141 +.Fa action
 142 +function is called only once for a leaf-node, with the
 143 +traversal type "leaf."
 144 +.Pp
 145 +Note: the names for the traversal types differ somewhat from
 146 +common parlance.  The traversal type "postorder" corresponds
 147 +to what would typically be referred to as in-order, and the
 148 +traversal type "endorder" corresponds to what would typically
 149 +be referred to as post-order.
 150  .Sh SEE ALSO
 151  .Xr bsearch 3 ,
 152  .Xr hsearch 3 ,
 153 @@ -125,7 +174,7 @@
 154  functions
 155  return NULL if
 156  .Fa rootp
 157 -is NULL or the datum cannot be found.
 158 +is NULL or the node cannot be found.
 159  .Pp
 160  The
 161  .Fn twalk