diff --git a/doc/Jamfile.v2 b/doc/Jamfile.v2 index eb9c35d..4146135 100644 --- a/doc/Jamfile.v2 +++ b/doc/Jamfile.v2 @@ -117,3 +117,22 @@ boostbook standalone_string_ref # How far down we go with TOC's generate.section.toc.level=1 ; + +xml string_view : string_view.qbk ; +boostbook standalone_string_view + : + string_view + : + # File name of HTML output: + root.filename=string_view + # How far down we chunk nested sections, basically all of them: + chunk.section.depth=0 + # Don't put the first section on the same page as the TOC: + chunk.first.sections=0 + # How far down sections get TOC's + toc.section.depth=1 + # Max depth in each TOC: + toc.max.depth=1 + # How far down we go with TOC's + generate.section.toc.level=1 + ; diff --git a/doc/string_view.qbk b/doc/string_view.qbk index 4434660..7d9dc0b 100644 --- a/doc/string_view.qbk +++ b/doc/string_view.qbk @@ -1,5 +1,6 @@ [/ / Copyright (c) 2012 Marshall Clow + / Copyright (c) 2015 Beman Dawes / / 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) @@ -7,12 +8,11 @@ [article String_View [quickbook 1.5] - [authors [Clow, Marshall]] - [copyright 2012 Marshall Clow] + [authors [Clow, Marshall] [Dawes, Beman]] + [copyright 2012 Marshall Clow, 2015 Beman Dawes] [license 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]) + [@http://www.boost.org/LICENSE_1_0.txt] ] ] @@ -20,9 +20,10 @@ [section Overview] [/===============] -Boost.StringView is an implementation of Jeffrey Yaskin's [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3442.html N3442: -string_view: a non-owning reference to a string]. - +Boost.StringView is an implementation of `string_view` as specified in [@ +http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/n4480.html#string.view N4480: +ISO/IEC DTS 19568, Technical Specification - C++ Extensions for Library Fundamentals]. + 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. @@ -41,6 +42,18 @@ Besides generic container functionality, `string_view` provides a subset of the Because a `string_view` 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_view` refers to exists as long as the `string_view` does. +Note: The header actually contains a class template, `basic_string_view` and four typedefs: + + template> + class basic_string_view; + + typedef basic_string_view string_view; + typedef basic_string_view u16string_view; + typedef basic_string_view u32string_view; + typedef basic_string_view wstring_view; + +So you can have views of strings of any of the four built-in character types as well as strings of user-defined character-like type strings. For the sake of simple exposition, we concentrate on `string_view` (i.e. `char` strings) in this documentation. + [endsect] @@ -79,76 +92,123 @@ No memory allocations. No copying of character data. No changes to the code othe [section:reference Reference ] [/=================] -The header file "string_view.hpp" defines a template `boost::basic_string_view`, and four specializations - for `char` / `wchar_t` / `char16_t` / `char32_t` . +The header file "string_view.hpp" defines a class template `boost::basic_string_view`, and four specializations - for `char` / `wchar_t` / `char16_t` / `char32_t` . `#include ` +Types: + + typedef traits traits_type; + typedef charT value_type; + typedef charT* pointer; + typedef const charT* const_pointer; + typedef charT& reference; + typedef const charT& const_reference; + typedef const_pointer const_iterator; // implementation defined + typedef const_iterator iterator; + typedef std::reverse_iterator const_reverse_iterator; + typedef const_reverse_iterator reverse_iterator; + typedef std::size_t size_type; + typedef std::ptrdiff_t difference_type; + static BOOST_CONSTEXPR_OR_CONST size_type npos = size_type(-1); + Construction and copying: - BOOST_CONSTEXPR basic_string_view (); // Constructs an empty string_view - BOOST_CONSTEXPR basic_string_view(const charT* str); // Constructs from a NULL-terminated string - BOOST_CONSTEXPR basic_string_view(const charT* str, size_type len); // Constructs from a pointer, length pair + BOOST_CONSTEXPR basic_string_view () BOOST_NOEXCEPT; // Constructs empty string_view + BOOST_CONSTEXPR basic_string_view (const basic_string_view &rhs) BOOST_NOEXCEPT; + basic_string_view& operator=(const basic_string_view &rhs) BOOST_NOEXCEPT; template - basic_string_view(const std::basic_string& str); // Constructs from a std::string - basic_string_view (const basic_string_view &rhs); - basic_string_view& operator=(const basic_string_view &rhs); + basic_string_view(const std::basic_string& str) BOOST_NOEXCEPT; // Ctor from std::string + BOOST_CONSTEXPR basic_string_view(const charT* str); // Ctor from NULL-terminated string + BOOST_CONSTEXPR basic_string_view(const charT* str, size_type len); // Ctor from pointer, length pair -`string_view` does not define a move constructor nor a move-assignment operator because copying a `string_view` is just a cheap as moving one. +`string_view` does not define a move constructor or a move-assignment operator because copying a `string_view` is just as cheap as moving one would be. 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 ; + BOOST_CONSTEXPR size_type size() const BOOST_NOEXCEPT ; + BOOST_CONSTEXPR size_type length() const BOOST_NOEXCEPT ; + BOOST_CONSTEXPR size_type max_size() const BOOST_NOEXCEPT ; + BOOST_CONSTEXPR bool empty() const BOOST_NOEXCEPT ; // 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 ; + BOOST_CONSTEXPR const_iterator begin() const BOOST_NOEXCEPT ; + BOOST_CONSTEXPR const_iterator cbegin() const BOOST_NOEXCEPT ; + BOOST_CONSTEXPR const_iterator end() const BOOST_NOEXCEPT ; + BOOST_CONSTEXPR const_iterator cend() const BOOST_NOEXCEPT ; + const_reverse_iterator rbegin() const BOOST_NOEXCEPT ; + const_reverse_iterator crbegin() const BOOST_NOEXCEPT ; + const_reverse_iterator rend() const BOOST_NOEXCEPT ; + const_reverse_iterator crend() const BOOST_NOEXCEPT ; 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& at(size_t pos) const ; BOOST_CONSTEXPR const charT& front() const ; BOOST_CONSTEXPR const charT& back() const ; - BOOST_CONSTEXPR const charT* data() const ; + BOOST_CONSTEXPR const charT* data() const BOOST_NOEXCEPT ; Modifying the `string_view` (but not the underlying data): - void clear(); - void remove_prefix(size_type n); - void remove_suffix(size_type n); - + BOOST_CONSTEXPR void clear(); // boost extension + BOOST_CONSTEXPR void remove_prefix(size_type n); + BOOST_CONSTEXPR void remove_suffix(size_type n); + BOOST_CONSTEXPR void swap(basic_string_view& s) BOOST_NOEXCEPT; + Searching: - size_type find(basic_string_view s) const ; - size_type find(charT c) const ; - size_type rfind(basic_string_view 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_view s) const ; - size_type find_last_of(basic_string_view s) const ; - size_type find_first_not_of(basic_string_view s) const ; - size_type find_first_not_of(charT c) const ; - size_type find_last_not_of(basic_string_view s) const ; - size_type find_last_not_of(charT c) const ; + BOOST_CONSTEXPR size_type find(basic_string_view s, size_type pos = 0) const BOOST_NOEXCEPT; + BOOST_CONSTEXPR size_type find(charT c, size_type pos = 0) const BOOST_NOEXCEPT; + BOOST_CONSTEXPR size_type find(const charT* s, size_type pos, size_type n) const; + BOOST_CONSTEXPR size_type find(const charT* s, size_type pos = 0) const; + + BOOST_CONSTEXPR size_type rfind(basic_string_view s, size_type pos = npos) const BOOST_NOEXCEPT; + BOOST_CONSTEXPR size_type rfind(charT c, size_type pos = npos) const BOOST_NOEXCEPT; + BOOST_CONSTEXPR size_type rfind(const charT* s, size_type pos, size_type n) const; + BOOST_CONSTEXPR size_type rfind(const charT* s, size_type pos = npos) const; + + BOOST_CONSTEXPR size_type find_first_of(basic_string_view s, size_type pos = 0) const BOOST_NOEXCEPT; + BOOST_CONSTEXPR size_type find_first_of(charT c, size_type pos = 0) const BOOST_NOEXCEPT; + BOOST_CONSTEXPR size_type find_first_of(const charT* s, size_type pos, size_type n) const; + BOOST_CONSTEXPR size_type find_first_of(const charT* s, size_type pos = 0) const; + + BOOST_CONSTEXPR size_type find_last_of(basic_string_view s, size_type pos = npos) const BOOST_NOEXCEPT; + BOOST_CONSTEXPR size_type find_last_of(charT c, size_type pos = npos) const BOOST_NOEXCEPT; + BOOST_CONSTEXPR size_type find_last_of(const charT* s, size_type pos, size_type n) const; + BOOST_CONSTEXPR size_type find_last_of(const charT* s, size_type pos = npos) const; + + BOOST_CONSTEXPR size_type find_first_not_of(basic_string_view s, size_type pos = 0) const BOOST_NOEXCEPT; + BOOST_CONSTEXPR size_type find_first_not_of(charT c, size_type pos = 0) const BOOST_NOEXCEPT; + BOOST_CONSTEXPR size_type find_first_not_of(const charT* s, size_type pos, size_type n) const; + BOOST_CONSTEXPR size_type find_first_not_of(const charT* s, size_type pos = 0) const; + + BOOST_CONSTEXPR size_type find_last_not_of(basic_string_view s, size_type pos = npos) const BOOST_NOEXCEPT; + BOOST_CONSTEXPR size_type find_last_not_of(charT c, size_type pos = npos) const BOOST_NOEXCEPT; + BOOST_CONSTEXPR size_type find_last_not_of(const charT* s, size_type pos, size_type n) const; + BOOST_CONSTEXPR size_type find_last_not_of(const charT* s, size_type pos = npos) const; + + BOOST_CONSTEXPR bool starts_with(charT c) const ; // boost extension + BOOST_CONSTEXPR bool starts_with(basic_string_view x) const ; // boost extension + BOOST_CONSTEXPR bool ends_with(charT c) const ; // boost extension + BOOST_CONSTEXPR bool ends_with(basic_string_view x) const ; // boost extension String-like operations: - BOOST_CONSTEXPR basic_string_view substr(size_type pos, size_type n=npos) const ; // Creates a new string_view - bool starts_with(charT c) const ; - bool starts_with(basic_string_view x) const ; - bool ends_with(charT c) const ; - bool ends_with(basic_string_view x) const ; + template // Only present if compiler supports C++11 explicit conversion + explicit operator basic_string() const; + + template > // Default only for C++11 compilers + basic_string + to_string(const Allocator& a = Allocator()) const; + + size_type copy(charT* s, size_type n, size_type pos = 0) const; + + BOOST_CONSTEXPR basic_string_view substr(size_type pos, size_type n=npos) const ; // Creates new string_view + +Comparison: + + To be supplied [endsect] @@ -157,8 +217,13 @@ String-like operations: [/===============] [heading boost 1.53] -* Introduced - +* Introduced, based on Jeffrey Yaskin's [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3442.html N3442: +string_ref: a non-owning reference to a string] + +[heading boost 1.60] +* Updated to reflect [@ +http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/n4480.html#string.view N4480: +ISO/IEC DTS 19568, Technical Specification - C++ Extensions for Library Fundamentals] [endsect] diff --git a/include/boost/utility/string_view.hpp b/include/boost/utility/string_view.hpp index cd22b32..63f7a8f 100644 --- a/include/boost/utility/string_view.hpp +++ b/include/boost/utility/string_view.hpp @@ -73,14 +73,14 @@ namespace boost { return *this; } + template + basic_string_view(const std::basic_string& str) BOOST_NOEXCEPT + : ptr_(str.data()), len_(str.length()) {} + BOOST_CONSTEXPR basic_string_view(const charT* str) : ptr_(str), len_(traits::length(str)) {} - template - basic_string_view(const std::basic_string& str) BOOST_NOEXCEPT - : ptr_(str.data()), len_(str.length()) {} - BOOST_CONSTEXPR basic_string_view(const charT* str, size_type len) : ptr_(str), len_(len) {} @@ -114,7 +114,7 @@ namespace boost { BOOST_CONSTEXPR const_pointer data() const BOOST_NOEXCEPT { return ptr_; } // modifiers - void clear() { len_ = 0; } // Boost extension + void clear() BOOST_NOEXCEPT { len_ = 0; } // Boost extension BOOST_CONSTEXPR void remove_prefix(size_type n) { if ( n > len_ )