[Boost-commit] svn:boost r82490 - in branches/release/libs/utility/doc: . html

Subject: [Boost-commit] svn:boost r82490 - in branches/release/libs/utility/doc: . html
From: marshall_at_[hidden]
Date: 2013-01-14 11:34:17

Author: marshall
Date: 2013-01-14 11:34:16 EST (Mon, 14 Jan 2013)
New Revision: 82490
URL: http://svn.boost.org/trac/boost/changeset/82490

Log:
Merge string_ref doc changes to release
Added:
   branches/release/libs/utility/doc/html/string_ref.html
      - copied unchanged from r82489, /trunk/libs/utility/doc/html/string_ref.html
Properties modified: 
   branches/release/libs/utility/doc/   (props changed)
Text files modified: 
   branches/release/libs/utility/doc/Jamfile.v2     |     6 +-                                      
   branches/release/libs/utility/doc/string_ref.qbk |    93 ++++++++++++++++++++++++++++++++++----- 
   2 files changed, 83 insertions(+), 16 deletions(-)

Modified: branches/release/libs/utility/doc/Jamfile.v2
==============================================================================
--- branches/release/libs/utility/doc/Jamfile.v2	(original)
+++ branches/release/libs/utility/doc/Jamfile.v2	2013-01-14 11:34:16 EST (Mon, 14 Jan 2013)
@@ -43,7 +43,7 @@
 path-constant boost-images : ../../../doc/src/images ;
 
 xml declval : declval.qbk ;
-boostbook standalone
+boostbook standalone_declval
     :
         declval
     :
@@ -63,7 +63,7 @@
      ;
 
 xml string_ref : string_ref.qbk ;
-boostbook standalone
+boostbook standalone_string_ref
     :
         string_ref
     :
@@ -79,5 +79,5 @@
         <xsl:param>toc.max.depth=1
         # How far down we go with TOC's
         <xsl:param>generate.section.toc.level=1
-        
+
      ;

Modified: branches/release/libs/utility/doc/string_ref.qbk
==============================================================================
--- branches/release/libs/utility/doc/string_ref.qbk	(original)
+++ branches/release/libs/utility/doc/string_ref.qbk	2013-01-14 11:34:16 EST (Mon, 14 Jan 2013)
@@ -37,7 +37,7 @@
 
 `string_ref` acts as a container; it includes all the methods that you would expect in a container, including iteration support, `operator []`, `at` and `size`. It can be used with any of the iterator-based algorithms in the STL - as long as you don't need to change the underlying data (`sort` and `remove`, for example, will not work)
 
-Besides generic container functionality, `string_ref` provides a subset of the interface of `std::string`. This makes it easy to replace parameters of type `const std::string &` with `boost::string_ref`. 
+Besides generic container functionality, `string_ref` provides a subset of the interface of `std::string`. This makes it easy to replace parameters of type `const std::string &` with `boost::string_ref`. Like `std::string`, `string_ref` has a static member variable named `npos` to denote the result of failed searches, and to mean "the end".
 
 Because a `string_ref` does not own the data that it "points to", it introduces lifetime issues into code that uses it. The programmer must ensure that the data that a `string_ref` refers to exists as long as the `string_ref` does.
 
@@ -50,12 +50,12 @@
 
 Integrating `string_ref` into your code is fairly simple. Wherever you pass a `const std::string &` or `std::string` as a parameter, that's a candidate for passing a `boost::string_ref`.
 
-	std::string extract_part ( const std::string &bar ) {
-		return bar.substr ( 2, 3 );
-		}
-		
-	if ( extract_part ( "ABCDEFG" ).front() == "C" ) { /* do something */ }
-	
+    std::string extract_part ( const std::string &bar ) {
+        return bar.substr ( 2, 3 );
+        }
+        
+    if ( extract_part ( "ABCDEFG" ).front() == "C" ) { /* do something */ }
+    
 Let's figure out what happens in this (contrived) example.
 
 First, a temporary string is created from the string literal `"ABCDEFG"`, and it is passed (by reference) to the routine `extract_part`. Then a second string is created in the call `std::string::substr` and returned to `extract_part` (this copy may be elided by RVO). Then `extract_part` returns that string back to the caller (again this copy may be elided). The first temporary string is deallocated, and `front` is called on the second string, and then it is deallocated as well.
@@ -64,11 +64,11 @@
 
 Now let's look at the same code with `string_ref`:
 
-	boost::string_ref extract_part ( boost::string_ref bar ) {
-		return bar.substr ( 2, 3 );
-		}
-		
-	if ( extract_part ( "ABCDEFG" ).front() == "C" ) { /* do something */ }
+    boost::string_ref extract_part ( boost::string_ref bar ) {
+        return bar.substr ( 2, 3 );
+        }
+        
+    if ( extract_part ( "ABCDEFG" ).front() == "C" ) { /* do something */ }
 
 No memory allocations. No copying of character data. No changes to the code other than the types. There are two `string_ref`s created, and two `string_ref`s copied, but those are cheap operations.
 
@@ -83,6 +83,73 @@
 
 `#include <boost/utility/string_ref.hpp>`
 
+Construction and copying:
+
+    BOOST_CONSTEXPR basic_string_ref ();    // Constructs an empty string_ref
+    BOOST_CONSTEXPR basic_string_ref(const charT* str); // Constructs from a NULL-terminated string
+    BOOST_CONSTEXPR basic_string_ref(const charT* str, size_type len); // Constructs from a pointer, length pair
+    template<typename Allocator>
+    basic_string_ref(const std::basic_string<charT, traits, Allocator>& str); // Constructs from a std::string
+    basic_string_ref (const basic_string_ref &rhs);
+    basic_string_ref& operator=(const basic_string_ref &rhs);
+
+`string_ref` does not define a move constructor nor a move-assignment operator because copying a `string_ref` is just a cheap as moving one.
+
+Basic container-like functions:
+
+    BOOST_CONSTEXPR size_type size()     const ;
+    BOOST_CONSTEXPR size_type length()   const ;
+    BOOST_CONSTEXPR size_type max_size() const ;
+    BOOST_CONSTEXPR bool empty()         const ;
+    
+    // All iterators are const_iterators
+    BOOST_CONSTEXPR const_iterator  begin() const ;
+    BOOST_CONSTEXPR const_iterator cbegin() const ;
+    BOOST_CONSTEXPR const_iterator    end() const ;
+    BOOST_CONSTEXPR const_iterator   cend() const ;
+    const_reverse_iterator         rbegin() const ;
+    const_reverse_iterator        crbegin() const ;
+    const_reverse_iterator           rend() const ;
+    const_reverse_iterator          crend() const ;
+
+Access to the individual elements (all of which are const):
+
+    BOOST_CONSTEXPR const charT& operator[](size_type pos) const ;
+    const charT& at(size_t pos) const ;
+    BOOST_CONSTEXPR const charT& front() const ;
+    BOOST_CONSTEXPR const charT& back()  const ;
+    BOOST_CONSTEXPR const charT* data()  const ;
+
+Modifying the `string_ref` (but not the underlying data):
+
+    void clear();
+    void remove_prefix(size_type n);
+    void remove_suffix(size_type n);
+
+Searching:
+
+    size_type find(basic_string_ref s) const ;
+    size_type find(charT c) const ;
+    size_type rfind(basic_string_ref s) const ;
+    size_type rfind(charT c) const ;
+    size_type find_first_of(charT c) const ;
+    size_type find_last_of (charT c) const ;
+        
+    size_type find_first_of(basic_string_ref s) const ;
+    size_type find_last_of(basic_string_ref s) const ;
+    size_type find_first_not_of(basic_string_ref s) const ;
+    size_type find_first_not_of(charT c) const ;
+    size_type find_last_not_of(basic_string_ref s) const ;
+    size_type find_last_not_of(charT c) const ;
+
+String-like operations:
+
+    BOOST_CONSTEXPR basic_string_ref substr(size_type pos, size_type n=npos) const ; // Creates a new string_ref
+    bool starts_with(charT c) const ;
+    bool starts_with(basic_string_ref x) const ;
+    bool ends_with(charT c) const ;
+    bool ends_with(basic_string_ref x) const ;
+
 [endsect]
 
 [/===============]
@@ -91,7 +158,7 @@
 
 [heading boost 1.53]
 * Introduced
- 	
+    
 
 [endsect]