boost-react-native-bundle

<html> <head> <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> <title>String_Ref</title> <link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css"> <meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> <link rel="home" href="string_ref.html" title="String_Ref"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> <table cellpadding="2" width="100%"><tr> <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td> <td align="center"><a href="../../../../index.html">Home</a></td> <td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td> <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> <td align="center"><a href="../../../../more/index.htm">More</a></td> </tr></table> <hr> <div class="spirit-nav"></div> <div class="article"> <div class="titlepage"> <div> <div><h2 class="title"> <a name="string_ref"></a>String_Ref</h2></div> <div><div class="authorgroup"><div class="author"><h3 class="author"> Marshall Clow </h3></div></div></div> <div>Copyright © 2012 Marshall Clow</div> <div><div class="legalnotice"> <a name="string_ref.legal"></a> Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) </div></div> </div> <hr> </div> <div class="toc"> Table of Contents <dl class="toc"> <dt><a href="string_ref.html#string_ref.overview">Overview</a></dt> <dt><a href="string_ref.html#string_ref.examples">Examples</a></dt> <dt><a href="string_ref.html#string_ref.reference">Reference </a></dt> <dt><a href="string_ref.html#string_ref.history">History</a></dt> </dl> </div> <div class="section"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="string_ref.overview"></a><a class="link" href="string_ref.html#string_ref.overview" title="Overview">Overview</a> </h2></div></div></div> Boost.StringRef is an implementation of Jeffrey Yaskin's <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3442.html" target="_top">N3442: string_ref: a non-owning reference to a string</a>. 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 <code class="computeroutput">std::string</code>, but that has certain drawbacks: 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. 2) if a routine receives a constant <code class="computeroutput">std::string</code> and wants to pass a portion of that string to another routine, then it must create a new string of that substring. 3) A routine receives a constant <code class="computeroutput">std::string</code> and wants to return a portion of the string, then it must create a new string to return. <code class="computeroutput">string_ref</code> is designed to solve these efficiency problems. A <code class="computeroutput">string_ref</code> is a read-only reference to a contiguous sequence of characters, and provides much of the functionality of <code class="computeroutput">std::string</code>. A <code class="computeroutput">string_ref</code> is cheap to create, copy and pass by value, because it does not actually own the storage that it points to. A <code class="computeroutput">string_ref</code> is implemented as a small struct that contains a pointer to the start of the character data and a count. A <code class="computeroutput">string_ref</code> is cheap to create and cheap to copy. <code class="computeroutput">string_ref</code> acts as a container; it includes all the methods that you would expect in a container, including iteration support, <code class="computeroutput">operator []</code>, <code class="computeroutput">at</code> and <code class="computeroutput">size</code>. 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 (<code class="computeroutput">sort</code> and <code class="computeroutput">remove</code>, for example, will not work) Besides generic container functionality, <code class="computeroutput">string_ref</code> provides a subset of the interface of <code class="computeroutput">std::string</code>. This makes it easy to replace parameters of type <code class="computeroutput">const std::string &</code> with <code class="computeroutput">boost::string_ref</code>. Like <code class="computeroutput">std::string</code>, <code class="computeroutput">string_ref</code> has a static member variable named <code class="computeroutput">npos</code> to denote the result of failed searches, and to mean "the end". Because a <code class="computeroutput">string_ref</code> 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 <code class="computeroutput">string_ref</code> refers to exists as long as the <code class="computeroutput">string_ref</code> does. </div> <div class="section"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="string_ref.examples"></a><a class="link" href="string_ref.html#string_ref.examples" title="Examples">Examples</a> </h2></div></div></div> Integrating <code class="computeroutput">string_ref</code> into your code is fairly simple. Wherever you pass a <code class="computeroutput">const std::string &</code> or <code class="computeroutput">std::string</code> as a parameter, that's a candidate for passing a <code class="computeroutput">boost::string_ref</code>. <pre class="programlisting">std::string extract_part ( const std::string &bar ) { return bar.substr ( 2, 3 ); } if ( extract_part ( "ABCDEFG" ).front() == 'C' ) { /* do something */ } </pre> Let's figure out what happens in this (contrived) example. First, a temporary string is created from the string literal <code class="computeroutput">"ABCDEFG"</code>, and it is passed (by reference) to the routine <code class="computeroutput">extract_part</code>. Then a second string is created in the call <code class="computeroutput">std::string::substr</code> and returned to <code class="computeroutput">extract_part</code> (this copy may be elided by RVO). Then <code class="computeroutput">extract_part</code> returns that string back to the caller (again this copy may be elided). The first temporary string is deallocated, and <code class="computeroutput">front</code> is called on the second string, and then it is deallocated as well. Two <code class="computeroutput">std::string</code>s are created, and two copy operations. That's (potentially) four memory allocations and deallocations, and the associated copying of data. Now let's look at the same code with <code class="computeroutput">string_ref</code>: <pre class="programlisting">boost::string_ref extract_part ( boost::string_ref bar ) { return bar.substr ( 2, 3 ); } if ( extract_part ( "ABCDEFG" ).front() == "C" ) { /* do something */ } </pre> No memory allocations. No copying of character data. No changes to the code other than the types. There are two <code class="computeroutput">string_ref</code>s created, and two <code class="computeroutput">string_ref</code>s copied, but those are cheap operations. </div> <div class="section"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="string_ref.reference"></a><a class="link" href="string_ref.html#string_ref.reference" title="Reference">Reference </a> </h2></div></div></div> The header file "string_ref.hpp" defines a template <code class="computeroutput">boost::basic_string_ref</code>, and four specializations - for <code class="computeroutput">char</code> / <code class="computeroutput">wchar_t</code> / <code class="computeroutput">char16_t</code> / <code class="computeroutput">char32_t</code> . <code class="computeroutput">#include <boost/utility/string_ref.hpp></code> Construction and copying: <pre class="programlisting">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); </pre> <code class="computeroutput">string_ref</code> does not define a move constructor nor a move-assignment operator because copying a <code class="computeroutput">string_ref</code> is just a cheap as moving one. Basic container-like functions: <pre class="programlisting">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 ; </pre> Access to the individual elements (all of which are const): <pre class="programlisting">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 ; </pre> Modifying the <code class="computeroutput">string_ref</code> (but not the underlying data): <pre class="programlisting">void clear(); void remove_prefix(size_type n); void remove_suffix(size_type n); </pre> Searching: <pre class="programlisting">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 ; </pre> String-like operations: <pre class="programlisting">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 ; </pre> </div> <div class="section"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="string_ref.history"></a><a class="link" href="string_ref.html#string_ref.history" title="History">History</a> </h2></div></div></div> <h4> <a name="string_ref.history.h0"></a> <a name="string_ref.history.boost_1_53"></a><a class="link" href="string_ref.html#string_ref.history.boost_1_53">boost 1.53</a> </h4> <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> Introduced </li></ul></div> </div> </div> <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> <td align="left">Last revised: October 30, 2014 at 10:17:16 GMT</td> <td align="right"><div class="copyright-footer"></div></td> </tr></table> <hr> <div class="spirit-nav"></div> </body> </html>