[openssl-commits] [openssl] master update

[Rich Salz]

The branch master has been updated
       via  89b06ca7b0b08d31ac48275d1376a7046dd75f55 (commit)
      from  9837496142cf3a4d32c827cb679539c0b239cec9 (commit)


- Log -----------------------------------------------------------------
commit 89b06ca7b0b08d31ac48275d1376a7046dd75f55
Author: Pauli <paul.dale at oracle.com>
Date:   Wed Mar 15 14:29:08 2017 +1000

    Rewrite the documentation for sk_TYPE_find() and sk_TYPE_find_ex() to better
    describe the vagaries in their behaviour.
    
    [skip ci]
    
    Reviewed-by: Richard Levitte <levitte at openssl.org>
    Reviewed-by: Rich Salz <rsalz at openssl.org>
    (Merged from https://github.com/openssl/openssl/pull/2958)

-----------------------------------------------------------------------

Summary of changes:
 doc/man3/DEFINE_STACK_OF.pod | 24 ++++++++++++++++--------
 1 file changed, 16 insertions(+), 8 deletions(-)

diff --git a/doc/man3/DEFINE_STACK_OF.pod b/doc/man3/DEFINE_STACK_OF.pod
index af8dd09..e6684f8 100644
--- a/doc/man3/DEFINE_STACK_OF.pod
+++ b/doc/man3/DEFINE_STACK_OF.pod
@@ -140,14 +140,22 @@ sk_TYPE_set() sets element B<idx> of B<sk> to B<ptr> replacing the current
 element. The new element value is returned or B<NULL> if an error occurred:
 this will only happen if B<sk> is B<NULL> or B<idx> is out of range.
 
-sk_TYPE_find() and sk_TYPE_find_ex() search B<sk> using the supplied
-comparison function for an element matching B<ptr>. sk_TYPE_find() returns
-the index of the first matching element or B<-1> if there is no match.
-sk_TYPE_find_ex() returns a matching element or the nearest element that
-does not match B<ptr>. Note: if a comparison function is set then  B<sk> is
-sorted before the search which may change its order. If no comparison
-function is set then a linear search is made for a pointer matching B<ptr>
-and the stack is not reordered.
+sk_TYPE_find() searches B<sk> for the element B<ptr>.  In the case
+where no comparison function has been specified, the function performs
+a linear search for a pointer equal to B<ptr>. The index of the first
+matching element is returned or B<-1> if there is no match. In the case
+where a comparison function has been specified, B<sk> is sorted then
+sk_TYPE_find() returns the index of a matching element or B<-1> if there
+is no match. Note that, in this case, the matching element returned is
+not guaranteed to be the first; the comparison function will usually
+compare the values pointed to rather than the pointers themselves and
+the order of elements in B<sk> could change.
+
+sk_TYPE_find_ex() operates like sk_TYPE_find() except when a comparison
+function has been specified and no matching element is found. Instead
+of returning B<-1>, sk_TYPE_find_ex() returns the index of the element
+either before or after the location where B<ptr> would be if it were
+present in B<sk>.
 
 sk_TYPE_sort() sorts B<sk> using the supplied comparison function.