documentation update.

added remarks about the exception safety


[SVN r23558]

include/boost/algorithm/string/case_conv.hpp

@@ -40,6 +40,10 @@ namespace boost {
             \return 
                 An output iterator pointing just after last inserted character or
                 a copy of the input
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, second variant of this function provides strong
+                exception guarantie.
         */
         template<typename OutputIteratorT, typename CollectionT>
         inline OutputIteratorT 
@@ -111,6 +115,10 @@ namespace boost {
             \return 
                 An output iterator pointing just after last inserted character or
                 a copy of the input
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, second variant of this function provides strong
+                exception guarantie.
         */
         template<typename OutputIteratorT, typename CollectionT>
         inline OutputIteratorT 

include/boost/algorithm/string/erase.hpp

@@ -37,6 +37,10 @@ namespace boost {
             \param SearchRange A range in the input to be removed
             \return An output iterator pointing just after last inserted character or
                 a modified copy of the input
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, second variant of this function provides strong
+                exception guarantie.
         */
         template<typename OutputIteratorT, typename CollectionT>
         inline OutputIteratorT erase_range_copy(
@@ -104,6 +108,11 @@ namespace boost {
             \param Search A string to be searched for 
             \return An output iterator pointing just after last inserted character or
                 a modified copy of the input
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, second variant of this function provides strong
+                exception guarantie.
+
         */
         template<
             typename OutputIteratorT,
@@ -170,6 +179,10 @@ namespace boost {
             \param Loc a locale used for case insensitive comparison
             \return An output iterator pointing just after last inserted character or
                 a modified copy of the input
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, second variant of this function provides strong
+                exception guarantie.
         */
         template<
             typename OutputIteratorT,
@@ -238,6 +251,11 @@ namespace boost {
             \param Search A string to be searched for.
             \return An output iterator pointing just after last inserted character or
                 a modified copy of the input
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, second variant of this function provides strong
+                exception guarantie.
+
         */
         template<
             typename OutputIteratorT,
@@ -304,6 +322,11 @@ namespace boost {
             \param Loc a locale used for case insensitive comparison
             \return An output iterator pointing just after last inserted character or
                 a modified copy of the input
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, second variant of this function provides strong
+                exception guarantie.
+
         */
         template<
             typename OutputIteratorT,
@@ -374,6 +397,10 @@ namespace boost {
             \param Nth An index of the match to be replaced. The index is 0-based.
             \return An output iterator pointing just after last inserted character or
                 a modified copy of the input
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, second variant of this function provides strong
+                exception guarantie.
         */
         template<
             typename OutputIteratorT,
@@ -445,6 +472,10 @@ namespace boost {
             \param Loc a locale used for case insensitive comparison
             \return An output iterator pointing just after last inserted character or
                 a modified copy of the input
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, second variant of this function provides strong
+                exception guarantie.
         */
         template<
             typename OutputIteratorT,
@@ -519,7 +550,10 @@ namespace boost {
             \param Search A string to be searched for. 
             \return An output iterator pointing just after last inserted character or
                     a modified copy of the input
-            
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, second variant of this function provides strong
+                exception guarantie.            
         */
         template<
             typename OutputIteratorT,
@@ -586,7 +620,10 @@ namespace boost {
             \param Loc a locale used for case insensitive comparison
             \return An output iterator pointing just after last inserted character or
                     a modified copy of the input
-            
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, second variant of this function provides strong
+                exception guarantie.
         */
         template<
             typename OutputIteratorT,
@@ -657,6 +694,10 @@ namespace boost {
             \param N A length of the head
             \return An output iterator pointing just after last inserted character or
                 a modified copy of the input
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, second variant of this function provides strong
+                exception guarantie.
         */
         template<
             typename OutputIteratorT,
@@ -724,6 +765,9 @@ namespace boost {
             \return An output iterator pointing just after last inserted character or
                 a modified copy of the input
             
+            \note If the input paramters satisfy the second assumption
+                about exception safety, second variant of this function provides strong
+                exception guarantie.
         */
         template<
             typename OutputIteratorT,

include/boost/algorithm/string/find.hpp

@@ -63,6 +63,10 @@ namespace boost {
                 Returned iterator is either \c CollectionT::iterator or 
                 \c CollectionT::const_iterator, depending on the constness of 
                 the input parameter.
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, this function provides strong
+                exception guarantie.
         */
         template<typename Collection1T, typename Collection2T>
         inline iterator_range< 
@@ -88,6 +92,10 @@ namespace boost {
                 Returned iterator is either \c Collection1T::iterator or 
                 \c Collection1T::const_iterator, depending on the constness of 
                 the input parameter.
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, this function provides strong
+                exception guarantie.
         */
         template<typename Collection1T, typename Collection2T>
         inline iterator_range< 
@@ -114,6 +122,10 @@ namespace boost {
                 Returned iterator is either \c Collection1T::iterator or 
                 \c Collection1T::const_iterator, depending on the constness of 
                 the input parameter.
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, this function provides strong
+                exception guarantie.
         */
         template<typename Collection1T, typename Collection2T>
         inline iterator_range< 
@@ -139,6 +151,10 @@ namespace boost {
                 Returned iterator is either \c Collection1T::iterator or 
                 \c Collection1T::const_iterator, depending on the constness of 
                 the input parameter.
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, this function provides strong
+                exception guarantie.
         */
         template<typename Collection1T, typename Collection2T>
         inline iterator_range< 
@@ -194,6 +210,11 @@ namespace boost {
                 Returned iterator is either \c Collection1T::iterator or 
                 \c Collection1T::const_iterator, depending on the constness of 
                 the input parameter.
+
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, this function provides strong
+                exception guarantie.
         */
         template<typename Collection1T, typename Collection2T>
         inline iterator_range< 
@@ -223,6 +244,10 @@ namespace boost {
                 Returned iterator is either \c Collection1T::iterator or 
                 \c Collection1T::const_iterator, depending on the constness of 
                 the input parameter.
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, this function provides strong
+                exception guarantie.
         */
         template<typename CollectionT>
         inline iterator_range< 
@@ -250,6 +275,11 @@ namespace boost {
                 Returned iterator is either \c CollectionT::iterator or 
                 \c CollectionT::const_iterator, depending on the constness of 
                 the input parameter.
+
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, this function provides strong
+                exception guarantie.
         */
         template<typename CollectionT>
         inline iterator_range< 
@@ -278,6 +308,10 @@ namespace boost {
                 Returned iterator is either \c CollectionT::iterator or 
                 \c CollectionT::const_iterator, depending on the constness of 
                 the input parameter.
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, this function provides strong
+                exception guarantie.
         */
         template<typename CollectionT, typename PredicateT>
         inline iterator_range< 

include/boost/algorithm/string/find_format.hpp

@@ -42,6 +42,10 @@ namespace boost {
             \param Formatter A Formatter object used to format a match
             \return An output iterator pointing just after last inserted character or
                 a modified copy of the input
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, second variant of this function provides strong
+                exception guarantie.
         */
         template< 
             typename OutputIteratorT,
@@ -151,6 +155,10 @@ namespace boost {
             \param Formatter A Formatter object used to format a match
             \return An output iterator pointing just after last inserted character or
                 a modified copy of the input
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, second variant of this function provides strong
+                exception guarantie.
         */
         template< 
             typename OutputIteratorT,

include/boost/algorithm/string/find_iterator.hpp

@@ -1,10 +1,9 @@
 //  Boost string_algo library find_iterator.hpp header file  ---------------------------//
 
-//  Copyright Pavol Droba 2002-2003. Use, modification and
+//  Copyright Pavol Droba 2002-2004. Use, modification and
 //  distribution is subject to the Boost Software License, Version
 //  1.0. (See accompanying file LICENSE_1_0.txt or copy at
 //  http://www.boost.org/LICENSE_1_0.txt)
-
 //  See http://www.boost.org for updates, documentation, and revision history.
 
 #ifndef BOOST_STRING_FIND_ITERATOR_HPP
@@ -18,6 +17,13 @@
 #include <boost/iterator/iterator_facade.hpp>
 #include <boost/iterator/iterator_categories.hpp>
 
+/*! \file
+    Defines find iterator classes. Find iterator repeatly applies a Finder
+    on a specified input string to search for matches. Dereferencing
+    the iterator yields the current match or a range between last and current
+    match depending on the iterator used.
+*/
+
 namespace boost {
     namespace algorithm { 
 

include/boost/algorithm/string/predicate.hpp

@@ -23,6 +23,9 @@
     substring, simply contains the substring or if both strings are equal.
     In addition the algorithm \c all() checks all elements of a container to satisfy a 
     condition.
+
+    All predicates provide strong exception guarantie if input parameters satisfy
+    second assumption about exception safety.
 */
 
 namespace boost {
@@ -41,6 +44,10 @@ namespace boost {
             \param Test A test sequence
             \param Comp An element comparison predicate
             \return A result of the test
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, this function provides strong
+                exception guarantie.
         */
         template<typename Collection1T, typename Collection2T, typename PredicateT>
             inline bool starts_with( 
@@ -91,6 +98,10 @@ namespace boost {
             \param Test A test sequence
             \param Loc a locale used for case insensitive comparison
             \return A result of the test
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, this function provides strong
+                exception guarantie.
         */
         template<typename Collection1T, typename Collection2T>
         inline bool istarts_with( 
@@ -116,6 +127,10 @@ namespace boost {
             \param Test A test sequence
             \param Comp An element comparison predicate
             \return A result of the test
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, this function provides strong
+                exception guarantie.
         */
         template<typename Collection1T, typename Collection2T, typename PredicateT>
         inline bool ends_with( 
@@ -161,6 +176,10 @@ namespace boost {
             \param Test A test sequence
             \param Loc a locale used for case insensitive comparison
             \return A result of the test
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, this function provides strong
+                exception guarantie.
         */
         template<typename Collection1T, typename Collection2T>
         inline bool iends_with( 
@@ -183,6 +202,10 @@ namespace boost {
             \param Test A test sequence
             \param Comp An element comparison predicate
             \return A result of the test
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, this function provides strong
+                exception guarantie.
         */
         template<typename Collection1T, typename Collection2T, typename PredicateT>
         inline bool contains( 
@@ -220,6 +243,10 @@ namespace boost {
             \param Test A test sequence
             \param Loc a locale used for case insensitive comparison
             \return A result of the test
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, this function provides strong
+                exception guarantie.
         */
         template<typename Collection1T, typename Collection2T>
         inline bool icontains( 
@@ -245,6 +272,10 @@ namespace boost {
             \return A result of the test
 
             \note This is two-way version of \c std::equal algorithm
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, this function provides strong
+                exception guarantie.
         */
         template<typename Collection1T, typename Collection2T, typename PredicateT>
         inline bool equals( 
@@ -297,6 +328,10 @@ namespace boost {
             \return A result of the test
 
             \note This is two-way version of \c std::equal algorithm
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, this function provides strong
+                exception guarantie.
         */
         template<typename Collection1T, typename Collection2T>
         inline bool iequals( 
@@ -317,6 +352,10 @@ namespace boost {
             \param Input An input sequence
             \param Pred A predicate
             \return A result of the test
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, this function provides strong
+                exception guarantie.
         */
         template<typename CollectionT, typename PredicateT>
         inline bool all( 

include/boost/algorithm/string/regex.hpp

@@ -40,6 +40,10 @@ namespace boost {
                 Returned iterator is either \c InputContainerT::iterator or 
                 \c InputContainerT::const_iterator, depending on the constness of 
                 the input parameter.
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, second variant of this function provides strong
+                exception guarantie.
         */
         template< 
             typename CollectionT, 
@@ -71,7 +75,11 @@ namespace boost {
             \param Format Regex format definition
             \param Flags Regex options
             \return An output iterator pointing just after last inserted character or
-                    a modified copy of the input            
+                    a modified copy of the input   
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, second variant of this function provides strong
+                exception guarantie.
         */
         template< 
             typename OutputIteratorT,
@@ -155,7 +163,11 @@ namespace boost {
             \param Format Regex format definition
             \param Flags Regex options
             \return An output iterator pointing just after last inserted character or
-                    a modified copy of the input            
+                    a modified copy of the input     
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, second variant of this function provides strong
+                exception guarantie.
         */
         template< 
             typename OutputIteratorT,
@@ -206,7 +218,7 @@ namespace boost {
             \param Input An input string
             \param Rx A regular expression
             \param Format Regex format definition
-            \param Flags Regex options
+            \param Flags Regex options            
         */
         template< 
             typename SequenceT, 
@@ -238,8 +250,12 @@ namespace boost {
             \param Rx A regular expression
             \param Flags Regex options
             \return An output iterator pointing just after last inserted character or
-                       a modified copy of the input                        
+                       a modified copy of the input    
-        */
+
+           \note If the input paramters satisfy the second assumption
+               about exception safety, second variant of this function provides strong
+               exception guarantie.
+       */
         template< 
             typename OutputIteratorT,
             typename CollectionT, 
@@ -315,7 +331,11 @@ namespace boost {
             \param Rx A regular expression
             \param Flags Regex options
             \return An output iterator pointing just after last inserted character or
-                       a modified copy of the input                        
+                    a modified copy of the input                        
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, second variant of this function provides strong
+                exception guarantie.
         */
         template< 
             typename OutputIteratorT,
@@ -383,23 +403,26 @@ namespace boost {
         //! Find all regex algorithm
         /*!
             This algorithm finds all substrings matching the give regex
-            in the input. The result is given as a 'container of containers'.
+            in the input.             
-            Each match of the search sequence is represented by one
+            
-            element in the result.
+            Each part is copied and added as a new element to the output container.
+            Thus the result container must be able to hold copies
+            of the matches (in a compatible structure like std::string) or
+            a reference to it (f.e. using the iterator range class).
+            Examples of such a container are \c std::vector<std::string>
+            or \c std::list<boost::iterator_range<std::string::iterator>>
 
-            \param Result A 'container container' to container the result of search.
+            \param Result A container that can hold copies of references to the substrings.
-                Both outer and inner container must have constructor taking a pair
-                of iterators as an argument.
-                Typical type of the result is 
-                    \c std::vector<boost::iterator_range<iterator>>.
-                (each element of such a vector will container a range delimiting 
-                a match).
             \param Input A container which will be searched.
             \param Rx A regular expression
             \param Flags Regex options
             \return A reference to the result
 
             \note Prior content of the result will be overridden.
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety and result's container swap() method have strong exception guarantie, 
+                this function provides strong exception guarantie.
         */
         template< 
             typename SequenceSequenceT, 
@@ -425,20 +448,24 @@ namespace boost {
             Tokenize expression. This function is equivalent of C strtok. Input
             sequence is split into tokens, separated  by separators. Separator
             is an every match of the given regex.
-
+            Each part is copied and added as a new element to the output container.
-            \param Result A 'container container' to container the result of search.
+            Thus the result container must be able to hold copies
-                Both outer and inner container must have constructor taking a pair
+            of the matches (in a compatible structure like std::string) or
-                of iterators as an argument.
+            a reference to it (f.e. using the iterator range class).
-                Typical type of the result is 
+            Examples of such a container are \c std::vector<std::string>
-                    'c std::vector<boost::iterator_range<iterator>>.
+            or \c std::list<boost::iterator_range<std::string::iterator>>
-                (each element of such a vector will container a range delimiting 
+    
-                a match).
+            \param Result A container that can hold copies of references to the substrings.          
             \param Input A container which will be searched.
             \param Rx A regular expression
             \param Flags Regex options
             \return A reference to the result
 
             \note Prior content of the result will be overridden.
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety and result's container swap() method have strong exception guarantie, 
+                this function provides strong exception guarantie.
         */
         template< 
             typename SequenceSequenceT, 

include/boost/algorithm/string/replace.hpp

@@ -40,6 +40,10 @@ namespace boost {
             \param Format A substitute string
             \return An output iterator pointing just after last inserted character or
                 a modified copy of the input
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, second variant of this function provides strong
+                exception guarantie.
         */
         template<
             typename OutputIteratorT,
@@ -116,6 +120,10 @@ namespace boost {
             \param Format A substitute string
             \return An output iterator pointing just after last inserted character or
                     a modified copy of the input
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, second variant of this function provides strong
+                exception guarantie.
         */
         template<
             typename OutputIteratorT,
@@ -189,6 +197,11 @@ namespace boost {
             \param Loc a locale used for case insensitive comparison
             \return An output iterator pointing just after last inserted character or
                 a modified copy of the input
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, second variant of this function provides strong
+                exception guarantie.
+
         */
         template<
             typename OutputIteratorT,
@@ -265,6 +278,10 @@ namespace boost {
             \param Format A substitute string
             \return An output iterator pointing just after last inserted character or
                     a modified copy of the input            
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, second variant of this function provides strong
+                exception guarantie.
         */
         template<
             typename OutputIteratorT,
@@ -337,7 +354,11 @@ namespace boost {
             \param Format A substitute string
             \param Loc a locale used for case insensitive comparison
             \return An output iterator pointing just after last inserted character or
-                    a modified copy of the input            
+                    a modified copy of the input  
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, second variant of this function provides strong
+                exception guarantie.
         */
         template<
             typename OutputIteratorT,
@@ -416,6 +437,10 @@ namespace boost {
             \param Format A substitute string
             \return An output iterator pointing just after last inserted character or
                 a modified copy of the input
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, second variant of this function provides strong
+                exception guarantie.
         */
         template<
             typename OutputIteratorT,
@@ -494,7 +519,11 @@ namespace boost {
             \param Loc a locale used for case insensitive comparison
             \return An output iterator pointing just after last inserted character or
                     a modified copy of the input            
-        */
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, second variant of this function provides strong
+                exception guarantie.
+       */
         template<
             typename OutputIteratorT,
             typename Collection1T, 
@@ -573,7 +602,11 @@ namespace boost {
             \param Search A string to be searched for 
             \param Format A substitute string
             \return An output iterator pointing just after last inserted character or
-                    a modified copy of the input        
+                    a modified copy of the input 
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, second variant of this function provides strong
+                exception guarantie.
         */
         template<
             typename OutputIteratorT,
@@ -647,7 +680,11 @@ namespace boost {
             \param Format A substitute string
             \param Loc a locale used for case insensitive comparison
             \return An output iterator pointing just after last inserted character or
-                    a modified copy of the input            
+                    a modified copy of the input 
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, second variant of this function provides strong
+                exception guarantie.
         */
         template<
             typename OutputIteratorT,
@@ -725,7 +762,11 @@ namespace boost {
             \param N A length of the head
             \param Format A substitute string
             \return An output iterator pointing just after last inserted character or
-                a modified copy of the input            
+                a modified copy of the input  
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, second variant of this function provides strong
+                exception guarantie.
         */
         template<
             typename OutputIteratorT,
@@ -799,7 +840,11 @@ namespace boost {
             \param N A length of the head
             \param Format A substitute string
             \return An output iterator pointing just after last inserted character or
-                    a modified copy of the input            
+                    a modified copy of the input   
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, second variant of this function provides strong
+                exception guarantie.
         */
         template<
             typename OutputIteratorT,

include/boost/algorithm/string/split.hpp

@@ -19,12 +19,16 @@
 
 /*! \file
     Defines basic split algorithms. 
-    Split algorithms can be used to divide a sequence
+    Split algorithms can be used to divide a string
     into several parts according to a given criterium.
-    Result is given as a 'container of containers' where
+    
-    elements are copies or references to extracted parts.
+    Each part is copied and added as a new element to the
-    This file contains some common specializations of generic
+    output container.
-    algorithms contained in the file split2.hpp
+    Thus the result container must be able to hold copies
+    of the matches (in a compatible structure like std::string) or
+    a reference to it (f.e. using the iterator range class).
+    Examples of such a container are \c std::vector<std::string>
+    or \c std::list<boost::iterator_range<std::string::iterator>>
 */
 
 namespace boost {
@@ -34,23 +38,27 @@ namespace boost {
 
         //! Find all algorithm
         /*!
-            This algorithm finds all occurrences of the search sequence
+            This algorithm finds all occurrences of the search string
-            in the input. A result is given as a 'container of containers'.
+            in the input.
-            Each match of the search sequence is represented by one
+            
-            element in the result.
+            Each part is copied and added as a new element to the
+            output container.
+            Thus the result container must be able to hold copies
+            of the matches (in a compatible structure like std::string) or
+            a reference to it (f.e. using the iterator range class).
+            Examples of such a container are \c std::vector<std::string>
+            or \c std::list<boost::iterator_range<std::string::iterator>>
 
-            \param Result A 'container container' to container the result of search.
+            \param Result A container that can hold copies of references to the substrings
-                Both outer and inner container must have constructor taking a pair
-                of iterators as an argument.
-                Typical type of the result is 
-                    \c std::vector<boost::iterator_range<iterator>).
-                (each element of such a vector will container a range delimiting 
-                a match).
             \param Input A container which will be searched.
             \param Search A string to be searched for.
             \return A reference the result
 
             \note Prior content of the result will be overridden.
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety and result's container swap method have strong exception guarantie, 
+                this function provides strong exception guarantie.
         */
         template< typename SequenceSequenceT, typename Collection1T, typename Collection2T >
         inline SequenceSequenceT& find_all(
@@ -67,23 +75,27 @@ namespace boost {
         //! Find all algorithm ( case insensitive ) 
         /*!
             This algorithm finds all occurrences of the search sequence
-            in the input. A result is given as a 'container of containers'.
+            in the input. 
-            Each match of the search sequence is represented by one
+            Each part is copied and added as a new element to the
-            element in the result. Searching is case insensitive.
+            output container. Thus the result container must be able to hold copies
+            of the matches (in a compatible structure like std::string) or
+            a reference to it (f.e. using the iterator range class).
+            Examples of such a container are \c std::vector<std::string>
+            or \c std::list<boost::iterator_range<std::string::iterator>>
 
-            \param Result A 'container container' to container the result of search.
+            Searching is case insensitive.
-                Both outer and inner container must have constructor taking a pair
+
-                of iterators as an argument.
+            \param Result A container that can hold copies of references to the substrings
-                Typical type of the result is 
-                    \c std::vector<boost::iterator_range<iterator>>.
-                (each element of such a vector will container a range delimiting 
-                a match).
             \param Input A container which will be searched.
             \param Search A string to be searched for.
             \param Loc a locale used for case insensitive comparison
             \return A reference the result
 
             \note Prior content of the result will be overridden.
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety and result's container swap method have strong exception guarantie, 
+                this function provides strong exception guarantie.
         */
         template< typename SequenceSequenceT, typename Collection1T, typename Collection2T >
         inline SequenceSequenceT& ifind_all(
@@ -107,14 +119,15 @@ namespace boost {
             sequence is split into tokens, separated by separators. Separators 
             are given in the mean of predicate.
 
-            \param Result A 'container container' to container the result of search.
+            Each part is copied and added as a new element to the
-                Both outer and inner container must have constructor taking a pair
+            output container.
-                of iterators as an argument.
+            Thus the result container must be able to hold copies
-                Typical type of the result is 
+            of the matches (in a compatible structure like std::string) or
-                    \c std::vector<boost::iterator_range<iterator>>.
+            a reference to it (f.e. using the iterator range class).
-                (each element of such a vector will container a range delimiting 
+            Examples of such a container are \c std::vector<std::string>
-                a match).
+            or \c std::list<boost::iterator_range<std::string::iterator>>
-
+    
+            \param Result A container that can hold copies of references to the substrings          
             \param Input A container which will be searched.
             \param Pred A predicate to identify separators. This predicate is 
                 supposed to return true if a given element is a separator.
@@ -124,6 +137,10 @@ namespace boost {
             \return A reference the result
 
             \note Prior content of the result will be overridden.
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety and result's container swap() method have strong exception guarantie, 
+                this function provides strong exception guarantie.
         */
         template< typename SequenceSequenceT, typename CollectionT, typename PredicateT >
         inline SequenceSequenceT& split(

include/boost/algorithm/string/trim.hpp

@@ -47,6 +47,10 @@ namespace boost {
             \return 
                 An output iterator pointing just after last inserted character or
                 a copy of the input
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, the second variant of this function provides strong
+                exception guarantie.
         */
         template<typename OutputIteratorT, typename CollectionT, typename PredicateT>
         inline OutputIteratorT trim_left_copy_if( 
@@ -88,6 +92,10 @@ namespace boost {
             \param Input An input sequence
             \param Loc a locale used for 'space' classification
             \return A trimmed copy of the input
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, this function provides strong
+                exception guarantie.
         */
         template<typename SequenceT>
         inline SequenceT trim_left_copy(const SequenceT& Input, const std::locale& Loc=std::locale())
@@ -149,6 +157,10 @@ namespace boost {
             \return 
                 An output iterator pointing just after last inserted character or
                 a copy of the input
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, the second variant of this function provides strong
+                exception guarantie.
         */
         template<typename OutputIteratorT, typename CollectionT, typename PredicateT>
         inline OutputIteratorT trim_right_copy_if( 
@@ -191,6 +203,10 @@ namespace boost {
             \param Input An input sequence
             \param Loc A locale used for 'space' classification
             \return A trimmed copy of the input
+
+            \note If the input paramters satisfy second assumption
+                about exception safety, this function provides strong
+                exception guarantie.
         */  
         template<typename SequenceT>
         inline SequenceT trim_right_copy(const SequenceT& Input, const std::locale& Loc=std::locale())
@@ -255,6 +271,10 @@ namespace boost {
             \return 
                 An output iterator pointing just after last inserted character or
                 a copy of the input
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, the second variant of this function provides strong
+                exception guarantie.
         */
         template<typename OutputIteratorT, typename CollectionT, typename PredicateT>
         inline OutputIteratorT trim_copy_if( 
@@ -310,6 +330,10 @@ namespace boost {
             \param Input An input sequence
             \param Loc A locale used for 'space' classification
             \return A trimmed copy of the input
+
+            \note If the input paramters satisfy the second assumption
+                about exception safety, this function provides strong
+                exception guarantie.
         */
         template<typename SequenceT>
         inline SequenceT trim_copy( const SequenceT& Input, const std::locale& Loc=std::locale() )