]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 | ||
23 | Boost.StringRef is an implementation of Jeffrey Yaskin's [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3442.html N3442: | |
24 | string_ref: a non-owning reference to a string]. | |
25 | ||
26 | When 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 | ||
28 | 1) 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 | ||
30 | 2) 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 | ||
32 | 3) 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 | ||
36 | A `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 | ||
40 | 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". | |
41 | ||
42 | 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. | |
43 | ||
44 | [endsect] | |
45 | ||
46 | ||
47 | [/===============] | |
48 | [section Examples] | |
49 | [/===============] | |
50 | ||
51 | 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`. | |
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 | ||
59 | Let's figure out what happens in this (contrived) example. | |
60 | ||
61 | 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. | |
62 | ||
63 | Two `std::string`s are created, and two copy operations. That's (potentially) four memory allocations and deallocations, and the associated copying of data. | |
64 | ||
65 | Now 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 | ||
73 | 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. | |
74 | ||
75 | [endsect] | |
76 | ||
77 | ||
78 | [/=================] | |
79 | [section:reference Reference ] | |
80 | [/=================] | |
81 | ||
82 | The 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 | ||
86 | Construction 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 | ||
98 | Basic 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 | ||
115 | Access 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 | ||
123 | Modifying 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 | ||
129 | Searching: | |
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 | ||
145 | String-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.53] | |
160 | * Introduced | |
161 | ||
162 | ||
163 | [endsect] | |
164 | ||
165 | ||
166 | ||
167 |