1[/ 2 / Copyright (c) 2012 Marshall Clow 3 / 4 / Distributed under the Boost Software License, Version 1.0. (See accompanying 5 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 6 /] 7 8[article String_Ref 9 [quickbook 1.5] 10 [authors [Clow, Marshall]] 11 [copyright 2012 Marshall Clow] 12 [license 13 Distributed under the Boost Software License, Version 1.0. 14 (See accompanying file LICENSE_1_0.txt or copy at 15 [@http://www.boost.org/LICENSE_1_0.txt]) 16 ] 17] 18 19[/===============] 20[section Overview] 21[/===============] 22 23Boost.StringRef is an implementation of Jeffrey Yaskin's [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3442.html N3442: 24string_ref: a non-owning reference to a string]. 25 26When you are parsing/processing strings from some external source, frequently you want to pass a piece of text to a procedure for specialized processing. The canonical way to do this is as a `std::string`, but that has certain drawbacks: 27 281) If you are processing a buffer of text (say a HTTP response or the contents of a file), then you have to create the string from the text you want to pass, which involves memory allocation and copying of data. 29 302) if a routine receives a constant `std::string` and wants to pass a portion of that string to another routine, then it must create a new string of that substring. 31 323) A routine receives a constant `std::string` and wants to return a portion of the string, then it must create a new string to return. 33 34`string_ref` is designed to solve these efficiency problems. A `string_ref` is a read-only reference to a contiguous sequence of characters, and provides much of the functionality of `std::string`. A `string_ref` is cheap to create, copy and pass by value, because it does not actually own the storage that it points to. 35 36A `string_ref` is implemented as a small struct that contains a pointer to the start of the character data and a count. A `string_ref` is cheap to create and cheap to copy. 37 38`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) 39 40Besides 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". 41 42Because 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. 43 44[endsect] 45 46 47[/===============] 48[section Examples] 49[/===============] 50 51Integrating `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`. 52 53 std::string extract_part ( const std::string &bar ) { 54 return bar.substr ( 2, 3 ); 55 } 56 57 if ( extract_part ( "ABCDEFG" ).front() == 'C' ) { /* do something */ } 58 59Let's figure out what happens in this (contrived) example. 60 61First, 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. 62 63Two `std::string`s are created, and two copy operations. That's (potentially) four memory allocations and deallocations, and the associated copying of data. 64 65Now let's look at the same code with `string_ref`: 66 67 boost::string_ref extract_part ( boost::string_ref bar ) { 68 return bar.substr ( 2, 3 ); 69 } 70 71 if ( extract_part ( "ABCDEFG" ).front() == "C" ) { /* do something */ } 72 73No 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. 74 75[endsect] 76 77 78[/=================] 79[section:reference Reference ] 80[/=================] 81 82The header file "string_ref.hpp" defines a template `boost::basic_string_ref`, and four specializations - for `char` / `wchar_t` / `char16_t` / `char32_t` . 83 84`#include <boost/utility/string_ref.hpp>` 85 86Construction and copying: 87 88 BOOST_CONSTEXPR basic_string_ref (); // Constructs an empty string_ref 89 BOOST_CONSTEXPR basic_string_ref(const charT* str); // Constructs from a NULL-terminated string 90 BOOST_CONSTEXPR basic_string_ref(const charT* str, size_type len); // Constructs from a pointer, length pair 91 template<typename Allocator> 92 basic_string_ref(const std::basic_string<charT, traits, Allocator>& str); // Constructs from a std::string 93 basic_string_ref (const basic_string_ref &rhs); 94 basic_string_ref& operator=(const basic_string_ref &rhs); 95 96`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. 97 98Basic container-like functions: 99 100 BOOST_CONSTEXPR size_type size() const ; 101 BOOST_CONSTEXPR size_type length() const ; 102 BOOST_CONSTEXPR size_type max_size() const ; 103 BOOST_CONSTEXPR bool empty() const ; 104 105 // All iterators are const_iterators 106 BOOST_CONSTEXPR const_iterator begin() const ; 107 BOOST_CONSTEXPR const_iterator cbegin() const ; 108 BOOST_CONSTEXPR const_iterator end() const ; 109 BOOST_CONSTEXPR const_iterator cend() const ; 110 const_reverse_iterator rbegin() const ; 111 const_reverse_iterator crbegin() const ; 112 const_reverse_iterator rend() const ; 113 const_reverse_iterator crend() const ; 114 115Access to the individual elements (all of which are const): 116 117 BOOST_CONSTEXPR const charT& operator[](size_type pos) const ; 118 const charT& at(size_t pos) const ; 119 BOOST_CONSTEXPR const charT& front() const ; 120 BOOST_CONSTEXPR const charT& back() const ; 121 BOOST_CONSTEXPR const charT* data() const ; 122 123Modifying the `string_ref` (but not the underlying data): 124 125 void clear(); 126 void remove_prefix(size_type n); 127 void remove_suffix(size_type n); 128 129Searching: 130 131 size_type find(basic_string_ref s) const ; 132 size_type find(charT c) const ; 133 size_type rfind(basic_string_ref s) const ; 134 size_type rfind(charT c) const ; 135 size_type find_first_of(charT c) const ; 136 size_type find_last_of (charT c) const ; 137 138 size_type find_first_of(basic_string_ref s) const ; 139 size_type find_last_of(basic_string_ref s) const ; 140 size_type find_first_not_of(basic_string_ref s) const ; 141 size_type find_first_not_of(charT c) const ; 142 size_type find_last_not_of(basic_string_ref s) const ; 143 size_type find_last_not_of(charT c) const ; 144 145String-like operations: 146 147 BOOST_CONSTEXPR basic_string_ref substr(size_type pos, size_type n=npos) const ; // Creates a new string_ref 148 bool starts_with(charT c) const ; 149 bool starts_with(basic_string_ref x) const ; 150 bool ends_with(charT c) const ; 151 bool ends_with(basic_string_ref x) const ; 152 153[endsect] 154 155[/===============] 156[section History] 157[/===============] 158 159[heading boost 1.71] 160* Glen Fernandes updated the implementation of the stream insertion operator to 161write directly to the `basic_streambuf` and refactored that functionality into 162a common utility. 163 164[heading boost 1.53] 165* Introduced 166 167 168[endsect] 169 170 171 172 173