|  | Home | Libraries | People | FAQ | More | 
Copyright © 2012 Marshall Clow
Distributed under 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)
Boost.StringRef is an implementation of Jeffrey Yaskin's N3442: string_ref: a non-owning reference to a string.
      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:
    
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 std::string
      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 std::string
      and wants to return a portion of the string, then it must create a new string
      to return.
    
      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.
    
      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.
    
      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. 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.
    
      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 */ }
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.
    
      Two std::strings 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 string_ref:
    
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_refs
      created, and two string_refs
      copied, but those are cheap operations.
    
      The header file "string_ref.hpp" defines a template boost::basic_string_ref,
      and four specializations - for char
      / wchar_t / char16_t
      / char32_t .
    
      #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 ;
| Last revised: December 22, 2016 at 12:36:18 GMT |