re PR libstdc++/21035 (Documentation for std::basic_string::compare() incorrect)

2005-04-25  Paolo Carlini  <pcarlini@suse.de>

	PR libstdc++/21035
	* include/bits/basic_string.h (compare): Adjust the documentation
	to match the implementation and the standard.

From-SVN: r98708

libstdc++-v3/ChangeLog

+2005-04-25  Paolo Carlini  <pcarlini@suse.de>
+
+	PR libstdc++/21035
+	* include/bits/basic_string.h (compare): Adjust the documentation
+	to match the implementation and the standard.
+
 2005-04-24  Paolo Carlini  <pcarlini@suse.de>
 
 	* docs/html/ext/lwg-active.html, lwg-defects.html: Import Revision 35.

libstdc++-v3/include/bits/basic_string.h

@@ -1905,9 +1905,11 @@ namespace std
        *
        *  Returns an integer < 0 if this string is ordered before @a str, 0 if
        *  their values are equivalent, or > 0 if this string is ordered after
-       *  @a str.  If the lengths of @a str and this string are different, the
-       *  shorter one is ordered first.  If they are the same, returns the
-       *  result of traits::compare(data(),str.data(),size());
+       *  @a str.  Determines the effective length rlen of the strings to
+       *  compare as the smallest of size() and str.size().  The function
+       *  then compares the two strings by calling traits::compare(data(),
+       *  str.data(),rlen).  If the result of the comparison is nonzero returns
+       *  it, otherwise the shorter one is ordered first.
       */
       int
       compare(const basic_string& __str) const
@@ -1932,10 +1934,12 @@ namespace std
        *  Form the substring of this string from the @a n characters starting
        *  at @a pos.  Returns an integer < 0 if the substring is ordered
        *  before @a str, 0 if their values are equivalent, or > 0 if the
-       *  substring is ordered after @a str.  If the lengths @a of str and the
-       *  substring are different, the shorter one is ordered first.  If they
-       *  are the same, returns the result of
-       *  traits::compare(substring.data(),str.data(),size());
+       *  substring is ordered after @a str.  Determines the effective length
+       *  rlen of the strings to compare as the smallest of the length of the
+       *  substring and @a str.size().  The function then compares the two
+       *  strings by calling traits::compare(substring.data(),str.data(),rlen).
+       *  If the result of the comparison is nonzero returns it, otherwise the
+       *  shorter one is ordered first.
       */
       int
       compare(size_type __pos, size_type __n, const basic_string& __str) const;
@@ -1954,10 +1958,12 @@ namespace std
        *  starting at @a pos2.  Returns an integer < 0 if this substring is
        *  ordered before the substring of @a str, 0 if their values are
        *  equivalent, or > 0 if this substring is ordered after the substring
-       *  of @a str.  If the lengths of the substring of @a str and this
-       *  substring are different, the shorter one is ordered first.  If they
-       *  are the same, returns the result of
-       *  traits::compare(substring.data(),str.substr(pos2,n2).data(),size());
+       *  of @a str.  Determines the effective length rlen of the strings
+       *  to compare as the smallest of the lengths of the substrings.  The
+       *  function then compares the two strings by calling
+       *  traits::compare(substring.data(),str.substr(pos2,n2).data(),rlen).
+       *  If the result of the comparison is nonzero returns it, otherwise the
+       *  shorter one is ordered first.
       */
       int
       compare(size_type __pos1, size_type __n1, const basic_string& __str,
@@ -1970,9 +1976,12 @@ namespace std
        *
        *  Returns an integer < 0 if this string is ordered before @a s, 0 if
        *  their values are equivalent, or > 0 if this string is ordered after
-       *  @a s.  If the lengths of @a s and this string are different, the
-       *  shorter one is ordered first.  If they are the same, returns the
-       *  result of traits::compare(data(),s,size());
+       *  @a s.  Determines the effective length rlen of the strings to
+       *  compare as the smallest of size() and the length of a string
+       *  constructed from @a s.  The function then compares the two strings
+       *  by calling traits::compare(data(),s,rlen).  If the result of the
+       *  comparison is nonzero returns it, otherwise the shorter one is
+       *  ordered first.
       */
       int
       compare(const _CharT* __s) const;
@@ -1989,10 +1998,13 @@ namespace std
        *  Form the substring of this string from the @a n1 characters starting
        *  at @a pos.  Returns an integer < 0 if the substring is ordered
        *  before @a s, 0 if their values are equivalent, or > 0 if the
-       *  substring is ordered after @a s.  If the lengths of @a s and the
-       *  substring are different, the shorter one is ordered first.  If they
-       *  are the same, returns the result of
-       *  traits::compare(substring.data(),s,size());
+       *  substring is ordered after @a s.  Determines the effective length
+       *  rlen of the strings to compare as the smallest of the length of the 
+       *  substring and the length of a string constructed from @a s.  The
+       *  function then compares the two string by calling
+       *  traits::compare(substring.data(),s,rlen).  If the result of the
+       *  comparison is nonzero returns it, otherwise the shorter one is
+       *  ordered first.
       */
       int
       compare(size_type __pos, size_type __n1, const _CharT* __s) const;
@@ -2009,10 +2021,12 @@ namespace std
        *  at @a pos1.  Form a string from the first @a n2 characters of @a s.
        *  Returns an integer < 0 if this substring is ordered before the string
        *  from @a s, 0 if their values are equivalent, or > 0 if this substring
-       *  is ordered after the string from @a s. If the lengths of this
-       *  substring and @a n2 are different, the shorter one is ordered first.
-       *  If they are the same, returns the result of
-       *  traits::compare(substring.data(),s,size());
+       *  is ordered after the string from @a s.   Determines the effective
+       *  length rlen of the strings to compare as the smallest of the length
+       *  of the substring and @a n2.  The function then compares the two
+       *  strings by calling traits::compare(substring.data(),s,rlen).  If the
+       *  result of the comparison is nonzero returns it, otherwise the shorter
+       *  one is ordered first.
        *
        *  NB: s must have at least n2 characters, '\0' has no special
        *  meaning.