Improved docs for replace, added unchecked variant for overload

include/boost/static_string/static_string.hpp

@@ -1609,13 +1609,34 @@ public:
     swap(
         basic_static_string<M, CharT, Traits>& s) BOOST_STATIC_STRING_COND_NOEXCEPT;
         
-    /** Replace a subset of the string.
 
-        Replaces the part of the string indicated by `[pos1, pos1 + n1)` with `s`. This replacement is done unchecked.
+   /** Replace a substring with a string.
+
+        Replaces `rcount` characters starting at index `pos1` with those
+        of `str`, where `rcount` is `std::min(n1, size() - pos1)`.
+
+        @par Exception Safety
+
+        Strong guarantee.
+
+        @note 
+        The replacement is done unchecked, as the source cannot be
+        within the destination.
+        
+        All references, pointers, or iterators
+        referring to contained elements are invalidated. Any
+        past-the-end iterators are also invalidated.
+
+        @tparam M The size of the input string.
 
-        @throw std::out_of_range if `pos1 > size()`
-        @throw std::length_error if the resulting string exceeds `max_size()`
         @return `*this`
+
+        @param pos1 The index to replace at.
+        @param n1 The number of characters to replace.
+        @param str The string to replace with.
+
+        @throw std::length_error `size() + (str.size() - rcount) > max_size()`
+        @throw std::out_of_range `pos1 > size()`
     */
     template<size_t M>
     BOOST_STATIC_STRING_CPP14_CONSTEXPR
@@ -1628,13 +1649,27 @@ public:
       return replace_unchecked(pos1, n1, str.data(), str.size());
     }
 
-    /** Replace a subset of the string.
+    /** Replace a substring with a string.
 
-        Replaces the part of the string indicated by `[pos1, pos1 + n1)` with `s`.
+        Replaces `rcount` characters starting at index `pos1` with those
+        of `str`, where `rcount` is `std::min(n1, size() - pos1)`.
+
+        @par Exception Safety
+
+        Strong guarantee.
+
+        @note All references, pointers, or iterators
+        referring to contained elements are invalidated. Any
+        past-the-end iterators are also invalidated.
 
-        @throw std::out_of_range if `pos1 > size()`
-        @throw std::length_error if the resulting string exceeds `max_size()`
         @return `*this`
+
+        @param pos1 The index to replace at.
+        @param n1 The number of characters to replace.
+        @param str The string to replace with.
+
+        @throw std::length_error `size() + (str.size() - rcount) > max_size()`
+        @throw std::out_of_range `pos1 > size()`
     */
     BOOST_STATIC_STRING_CPP14_CONSTEXPR
     basic_static_string&
@@ -1646,14 +1681,30 @@ public:
       return replace(pos1, n1, str.data(), str.size());
     }
 
-    /** Replace a subset of the string.
+    /** Replace a substring with a substring.
 
-        Replaces the part of the string indicated by `[pos1, pos1 + n1)` with substring `[pos2, pos2 + n2)` of `str`
+        Replaces `rcount` characters starting at index `pos1` with those of
-        except that if `n2` is greater than `str.size()`, `[pos2, pos2 + str.size())` is used.
+        `str.subview(pos2, n2)`, where `rcount` is `std::min(n1, size() - pos1)`.
+
+        @par Exception Safety
+
+        Strong guarantee.
+
+        @note All references, pointers, or iterators
+        referring to contained elements are invalidated. Any
+        past-the-end iterators are also invalidated.
 
-        @throw std::out_of_range if `pos1 > size()`
-        @throw std::length_error if the resulting string exceeds `max_size()`
         @return `*this`
+
+        @param pos1 The index to replace at.
+        @param n1 The number of characters to replace.
+        @param str The string to replace with.
+        @param pos2 The index to begin the substring.
+        @param n2 The length of the substring.
+        The default argument for this parameter is @ref npos.
+
+        @throw std::length_error `size() + (std::min(str.size(), n2) - rcount) > max_size()`
+        @throw std::out_of_range `pos1 > size()`
     */
     BOOST_STATIC_STRING_CPP14_CONSTEXPR
     basic_static_string&
@@ -1664,20 +1715,80 @@ public:
         size_type pos2,
         size_type n2 = npos) BOOST_STATIC_STRING_COND_NOEXCEPT
     {
-      return replace(pos1, n1, str.subview(pos2, n2));
+      return replace_unchecked(pos1, n1, str.data(), (std::min)(n2, str.size() - pos2));
     }
 
-    /** Replace a subset of the string.
+    /** Replace a substring with a substring.
 
-        Replaces the part of the string indicated by `[pos1, pos1 + n1)` with `t` after converting to `string_view_type`.
+        Replaces `rcount` characters starting at index `pos1` with those of
+        `str.subview(pos2, n2)`, where `rcount` is `std::min(n1, size() - pos1)`.
 
-        This function participates in overload resolution if
+        @par Exception Safety
-        `T` is convertible to `string_view` and `T` is not
+
-        convertible to `CharT const*`.
+        Strong guarantee.
+
+        @note 
+        The replacement is done unchecked, as the source cannot be
+        within the destination.
+        
+        All references, pointers, or iterators
+        referring to contained elements are invalidated. Any
+        past-the-end iterators are also invalidated.
 
-        @throw std::out_of_range if `pos1 > size()`
-        @throw std::length_error if the resulting string exceeds `max_size()`
         @return `*this`
+
+        @param pos1 The index to replace at.
+        @param n1 The number of characters to replace.
+        @param str The string to replace with.
+        @param pos2 The index to begin the substring.
+        @param n2 The length of the substring.
+        The default argument for this parameter is @ref npos.
+
+        @throw std::length_error `size() + (std::min(str.size(), n2) - rcount) > max_size()`
+        @throw std::out_of_range `pos1 > size()`
+    */
+    template<std::size_t M>
+    BOOST_STATIC_STRING_CPP14_CONSTEXPR
+    basic_static_string&
+    replace(
+        size_type pos1,
+        size_type n1,
+        const basic_static_string<M, CharT, Traits>& str,
+        size_type pos2,
+        size_type n2 = npos) BOOST_STATIC_STRING_COND_NOEXCEPT
+    {
+      return replace(pos1, n1, str.data(), (std::min)(n2, str.size() - pos2));
+    }
+
+    /** Replace a substring with an object convertible to `string_view`.
+
+        Constructs a temporary `string_view` object `sv` from `t`, and
+        replaces `rcount` characters starting at index `pos1` with those
+        of `sv`, where `rcount` is `std::min(n1, size() - pos1)`.
+
+        @par Exception Safety
+
+        Strong guarantee.
+
+        @note All references, pointers, or iterators
+        referring to contained elements are invalidated. Any
+        past-the-end iterators are also invalidated.
+
+        @tparam T The type of the object to convert.
+
+        @par Constraints
+
+        `std::is_convertible<T const&, string_view>::value &&
+        !std::is_convertible<T const&, char const*>::value`.
+
+        @return `*this`
+
+        @param pos1 The index to replace at.
+        @param n1 The number of characters to replace.
+        @param t The object to replace with.
+
+        @throw std::length_error `size() + (sv.size() - rcount) > max_size()`
+        @throw std::out_of_range `pos1 > size()`
     */
     template<typename T>
     BOOST_STATIC_STRING_CPP14_CONSTEXPR
@@ -1698,18 +1809,38 @@ public:
       return replace(pos1, n1, sv.data(), sv.size());
     }
 
-    /** Replace a subset of the string.
+    /** Replace a substring with a substring of an object convertible to `string_view`.
 
-        Replaces the part of the string indicated by `[pos1, pos1 + n1)` with substring `[pos2, pos2 + n2)` of `t`
+        Constructs a temporary `string_view` object `sv` from `t`, and
-        after converting to `string_view_type`, except that if `n2` is greater than `t.size()`, `[pos2, pos2 + t.size())` is used.
+        replaces `rcount` characters starting at index `pos1` with those
+        of `sv.substr(pos2, n2)`, where `rcount` is `std::min(n1, size() - pos)`.
 
-        This function participates in overload resolution if
+        @par Exception Safety
-        `T` is convertible to `string_view` and `T` is not
+
-        convertible to `CharT const*`.
+        Strong guarantee.
+
+        @note All references, pointers, or iterators
+        referring to contained elements are invalidated. Any
+        past-the-end iterators are also invalidated.
+
+        @tparam T The type of the object to convert.
+
+        @par Constraints
+
+        `std::is_convertible<T const&, string_view>::value &&
+        !std::is_convertible<T const&, char const*>::value`.
 
-        @throw std::out_of_range if `pos1 > size()`
-        @throw std::length_error if the resulting string exceeds `max_size()`
         @return `*this`
+
+        @param pos1 The index to replace at.
+        @param n1 The number of characters to replace.
+        @param t The object to replace with.
+        @param pos2 The index to begin the substring.
+        @param n2 The length of the substring.
+        The default argument for this parameter is @ref npos.
+
+        @throw std::length_error `size() + (std::min(n2, sv.size()) - rcount) > max_size()`
+        @throw std::out_of_range `pos1 > size()`
     */
     template<typename T>
     BOOST_STATIC_STRING_CPP14_CONSTEXPR
@@ -1732,13 +1863,28 @@ public:
       return replace(pos1, n1, sv.substr(pos2, n2));
     }
 
-    /** Replace a subset of the string.
+    /** Replace a substring with a string.
 
-        Replaces the part of the string indicated by `[pos1, pos1 + n1)` with the characters in the range `[s, s + n2)`.
+        Replaces `rcount` characters starting at index `pos` with those of
+        `[s, s + n2)`, where `rcount` is `std::min(n1, size() - pos)`.
+
+        @par Exception Safety
+
+        Strong guarantee.
+
+        @note All references, pointers, or iterators
+        referring to contained elements are invalidated. Any
+        past-the-end iterators are also invalidated.
 
-        @throw std::out_of_range if `pos1 > size()`
-        @throw std::length_error if the resulting string exceeds `max_size()`
         @return `*this`
+
+        @param pos The index to replace at.
+        @param n1 The number of characters to replace.
+        @param s The string to replace with.
+        @param n2 The length of the string to replace with.
+
+        @throw std::length_error `size() + (n2 - rcount) > max_size()`
+        @throw std::out_of_range `pos > size()`
     */
     BOOST_STATIC_STRING_CPP14_CONSTEXPR
     basic_static_string&
@@ -1749,13 +1895,28 @@ public:
         size_type n2) BOOST_STATIC_STRING_COND_NOEXCEPT;
 
 
-    /** Replace a subset of the string.
+    /** Replace a substring with a string.
 
-        Replaces the part of the string indicated by `[pos1, pos1 + n1)` with the characters in the range `[s, s + Traits::length(s))`.
+        Replaces `rcount` characters starting at index `pos` with those of
+        `[s, s + len)`, where the length of the string `len` is `Traits::length(s)` and `rcount`
+        is `std::min(n1, size() - pos)`.
+
+        @par Exception Safety
+
+        Strong guarantee.
+
+        @note All references, pointers, or iterators
+        referring to contained elements are invalidated. Any
+        past-the-end iterators are also invalidated.
 
-        @throw std::out_of_range if `pos1 > size()`
-        @throw std::length_error if the resulting string exceeds `max_size()`
         @return `*this`
+
+        @param pos The index to replace at.
+        @param n1 The number of characters to replace.
+        @param s The string to replace with.
+
+        @throw std::length_error `size() + (len - rcount) > max_size()`
+        @throw std::out_of_range `pos > size()`
     */
     BOOST_STATIC_STRING_CPP14_CONSTEXPR
     basic_static_string&
@@ -1767,13 +1928,28 @@ public:
       return replace(pos, n1, s, Traits::length(s));
     }
 
-    /** Replace a subset of the string.
+    /** Replace a substring with copies of a character.
 
-        Replaces the part of the string indicated by `[pos1, pos1 + n1)` with `n2` copies of `c`.
+        Replaces `rcount` characters starting at index `pos` with `n2` copies
+        of `c`, where `rcount` is `std::min(n1, size() - pos)`.
+
+        @par Exception Safety
+
+        Strong guarantee.
+
+        @note All references, pointers, or iterators
+        referring to contained elements are invalidated. Any
+        past-the-end iterators are also invalidated.
 
-        @throw std::out_of_range if `pos1 > size()`
-        @throw std::length_error if the resulting string exceeds `max_size()`
         @return `*this`
+
+        @param pos The index to replace at.
+        @param n1 The number of characters to replace.
+        @param n2 The number of characters to replace with.
+        @param c The character to replace with.
+
+        @throw std::length_error `size() + (n2 - rcount) > max_size()`
+        @throw std::out_of_range `pos > size()`
     */
     BOOST_STATIC_STRING_CPP14_CONSTEXPR
     basic_static_string&
@@ -1783,35 +1959,78 @@ public:
         size_type n2,
         CharT c) BOOST_STATIC_STRING_COND_NOEXCEPT;
 
-    /** Replace a subset of the string.
+    /** Replace a range with a string.
 
-        Replaces the part of the string indicated by `[i1, i2)` with `s`
+        Replaces the characters in the range `[i1, i2)`
+        with those of `str`.
+
+        @par Precondition
+
+        `[i1, i2)` is a valid range.
+
+        @par Exception Safety
+
+        Strong guarantee.
+
+        @note All references, pointers, or iterators
+        referring to contained elements are invalidated. Any
+        past-the-end iterators are also invalidated.
+
+        @tparam M The size of the input string.
 
-        @throw std::out_of_range if `pos1 > size()`
-        @throw std::length_error if the resulting string exceeds `max_size()`
         @return `*this`
+
+        @param i1 An iterator referring to the first character to replace.
+        @param i2 An iterator referring past the end of
+        the last character to replace.
+        @param str The string to replace with.
+
+        @throw std::length_error `size() + (str.size() - std::distance(i1, i2)) > max_size()`
     */
+    template<std::size_t M>
     BOOST_STATIC_STRING_CPP14_CONSTEXPR
     basic_static_string&
     replace(
         const_iterator i1,
         const_iterator i2,
-        const basic_static_string& str) BOOST_STATIC_STRING_COND_NOEXCEPT
+        const basic_static_string<M, CharT, Traits>& str) BOOST_STATIC_STRING_COND_NOEXCEPT
     {
       return replace(i1, i2, str.data(), str.size());
     }
 
-    /** Replace a subset of the string.
+    /** Replace a range with an object convertible to `string_view`.
 
-        Replaces the part of the string indicated by `[i1, i2)` with `t` after converting to `string_view_type`.
+        Constructs a temporary `string_view` object `sv` from `t`, and
+        replaces the characters in the range `[i1, i2)` with those
+        of `sv`.
 
-        This function participates in overload resolution if
+        @par Precondition
-        `T` is convertible to `string_view` and `T` is not
+
-        convertible to `CharT const*`.
+        `[i1, i2)` is a valid range.
+
+        @par Exception Safety
+
+        Strong guarantee.
+
+        @note All references, pointers, or iterators
+        referring to contained elements are invalidated. Any
+        past-the-end iterators are also invalidated.
+
+        @tparam T The type of the object to convert.
+
+        @par Constraints
+
+        `std::is_convertible<T const&, string_view>::value &&
+        !std::is_convertible<T const&, char const*>::value`.
 
-        @throw std::out_of_range if `i1` and `i2` do not refer to elements within the range `[0, size())`
-        @throw std::length_error if the resulting string exceeds `max_size()`
         @return `*this`
+
+        @param i1 An iterator referring to the first character to replace.
+        @param i2 An iterator referring past the end of
+        the last character to replace.
+        @param t The object to replace with.
+
+        @throw std::length_error `size() + (sv.size() - std::distance(i1, i2)) > max_size()`
     */
     template<typename T>
     BOOST_STATIC_STRING_CPP14_CONSTEXPR
@@ -1832,13 +2051,32 @@ public:
       return replace(i1 - begin(), i2 - i1, sv.data(), sv.size());
     }
 
-    /** Replace a subset of the string.
+    /** Replace a range with a string.
 
-        Replaces the part of the string indicated by `[i1, i2)` with the characters in the range `[s, s + n)`.
+        Replaces the characters in the range `[i1, i2)` with those of
+        `[s, s + n)`.
+
+        @par Precondition
+
+        `[i1, i2)` is a valid range.
+
+        @par Exception Safety
+
+        Strong guarantee.
+
+        @note All references, pointers, or iterators
+        referring to contained elements are invalidated. Any
+        past-the-end iterators are also invalidated.
 
-        @throw std::out_of_range if `i1` and `i2` do not refer to elements within the range `[0, size())`
-        @throw std::length_error if the resulting string exceeds `max_size()`
         @return `*this`
+
+        @param i1 An iterator referring to the first character to replace.
+        @param i2 An iterator referring past the end of
+        the last character to replace.
+        @param s The string to replace with.
+        @param n The length of the string to replace with.
+
+        @throw std::length_error `size() + (n - std::distance(i1, i2)) > max_size()`
     */
     BOOST_STATIC_STRING_CPP14_CONSTEXPR
     basic_static_string&
@@ -1851,13 +2089,31 @@ public:
       return replace(i1 - begin(), i2 - i1, s, n);
     }
 
-    /** Replace a subset of the string.
+    /** Replace a range with a string.
 
-        Replaces the part of the string indicated by `[i1, i2)` with the characters in the range `[s, s + Traits::length(s))`.
+        Replaces the characters in the range `[i1, i2)` with those of
+        `[s, s + len)`, where the length of the string `len` is `Traits::length(s)`.
+
+        @par Precondition
+
+        `[i1, i2)` shall be a valid range.
+
+        @par Exception Safety
+
+        Strong guarantee.
+
+        @note All references, pointers, or iterators
+        referring to contained elements are invalidated. Any
+        past-the-end iterators are also invalidated.
 
-        @throw std::out_of_range if `i1` and `i2` do not refer to elements within the range `[0, size())`
-        @throw std::length_error if the resulting string exceeds `max_size()`
         @return `*this`
+
+        @param i1 An iterator referring to the first character to replace.
+        @param i2 An iterator referring past the end of
+        the last character to replace.
+        @param s The string to replace with.
+
+        @throw std::length_error `size() + (len - std::distance(i1, i2)) > max_size()`
     */
     BOOST_STATIC_STRING_CPP14_CONSTEXPR
     basic_static_string&
@@ -1869,13 +2125,32 @@ public:
       return replace(i1, i2, s, Traits::length(s));
     }
 
-    /** Replace a subset of the string.
+    /** Replace a range with copies of a character.
 
-        Replaces the part of the string indicated by `[i1, i2)` with `n` copies of `c`.
+        Replaces the characters in the range `[i1, i2)` with
+        `n` copies of `c`.
+
+        @par Precondition
+
+        `[i1, i2)` is a valid range.
+
+        @par Exception Safety
+
+        Strong guarantee.
+
+        @note All references, pointers, or iterators
+        referring to contained elements are invalidated. Any
+        past-the-end iterators are also invalidated.
 
-        @throw std::out_of_range if `i1` and `i2` do not refer to elements within the range `[0, size())`
-        @throw std::length_error if the resulting string exceeds `max_size()`
         @return `*this`
+
+        @param i1 An iterator referring to the first character to replace.
+        @param i2 An iterator past the end of
+        the last character to replace.
+        @param n The number of characters to replace with.
+        @param c The character to replace with.
+
+        @throw std::length_error `size() + (n - std::distance(i1, i2)) > max_size()`
     */
     BOOST_STATIC_STRING_CPP14_CONSTEXPR
     basic_static_string&
@@ -1888,13 +2163,42 @@ public:
       return replace(i1 - begin(), i2 - i1, n, c);
     }
 
-    /** Replace a subset of the string.
+    /** Replace a range with a range.
 
-        Replaces the part of the string indicated by `[i1, i2)` with the characters in the range `[j1, j2)`.
+        Replaces the characters in the range `[i1, i2)`
+        with those of `[j1, j2)`.
+
+        @par Precondition
+
+        `[i1, i2)` is a valid range.
+
+        `[j1, j2)` is a valid range.
+
+        @par Exception Safety
+
+        Strong guarantee.
+
+        @note All references, pointers, or iterators
+        referring to contained elements are invalidated. Any
+        past-the-end iterators are also invalidated.
+
+        @tparam InputIt The type of the iterators.
+
+        @par Constraints
+
+        `InputIt` satisfies __InputIterator__ and does not 
+        satisfy __ForwardIterator__.
 
-        @throw std::out_of_range if `i1` and `i2` do not refer to elements within the range `[0, size())`
-        @throw std::length_error if the resulting string exceeds `max_size()`
         @return `*this`
+
+        @param i1 An iterator referring to the first character to replace.
+        @param i2 An iterator referring past the end of
+        the last character to replace.
+        @param j1 An iterator referring to the first character to replace with.
+        @param j2 An iterator referring past the end of
+        the last character to replace with.
+
+        @throw std::length_error `size() + (inserted - std::distance(i1, i2)) > max_size()`
     */
     template<typename InputIterator>
     BOOST_STATIC_STRING_CPP14_CONSTEXPR
@@ -1914,13 +2218,41 @@ public:
         InputIterator j1,
         InputIterator j2) BOOST_STATIC_STRING_COND_NOEXCEPT;
 
-    /** Replace a subset of the string.
+    /** Replace a range with a range.
 
-        Replaces the part of the string indicated by `[i1, i2)` with the characters in the range `[j1, j2)`.
+        Replaces the characters in the range `[i1, i2)`
+        with those of `[j1, j2)`.
+
+        @par Precondition
+
+        `[i1, i2)` is a valid range.
+
+        `[j1, j2)` is a valid range.
+
+        @par Exception Safety
+
+        Strong guarantee.
+
+        @note All references, pointers, or iterators
+        referring to contained elements are invalidated. Any
+        past-the-end iterators are also invalidated.
+
+        @tparam InputIt The type of the iterators.
+
+        @par Constraints
+
+        `InputIt` satisfies __ForwardIterator__.
 
-        @throw std::out_of_range if `i1` and `i2` do not refer to elements within the range `[0, size())`
-        @throw std::length_error if the resulting string exceeds `max_size()`
         @return `*this`
+
+        @param i1 An iterator referring to the first character to replace.
+        @param i2 An iterator referring past the end of
+        the last character to replace.
+        @param j1 An iterator referring to the first character to replace with.
+        @param j2 An iterator referring past the end of
+        the last character to replace with.
+
+        @throw std::length_error `size() + (std::distance(j1, j2) - std::distance(i1, i2)) > max_size()`
     */
     template<typename ForwardIterator>
     BOOST_STATIC_STRING_CPP14_CONSTEXPR
@@ -1938,13 +2270,31 @@ public:
         ForwardIterator j1,
         ForwardIterator j2) BOOST_STATIC_STRING_COND_NOEXCEPT;
 
-    /** Replace a subset of the string.
+    /** Replace a range with an initializer list.
 
-        Replaces the part of the string indicated by `[i1, i2)` with the characters in the initializer list `il`.
+        Replaces the characters in the range `[i1, i2)`
+        with those of contained in the initializer list `il`.
+
+        @par Precondition
+
+        `[i1, i2)` is a valid range.
+
+        @par Exception Safety
+
+        Strong guarantee.
+
+        @note All references, pointers, or iterators
+        referring to contained elements are invalidated. Any
+        past-the-end iterators are also invalidated.
 
-        @throw std::out_of_range if `i1` and `i2` do not refer to elements within the range `[0, size())`
-        @throw std::length_error if the resulting string exceeds `max_size()`
         @return `*this`
+
+        @param i1 An iterator referring to the first character to replace.
+        @param i2 An iterator past the end of
+        the last character to replace.
+        @param il The initializer list to replace with.
+
+        @throw std::length_error `size() + (il.size() - std::distance(i1, i2)) > max_size()`
     */
     BOOST_STATIC_STRING_CPP14_CONSTEXPR
     basic_static_string&