123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297 |
- <chapter xml:id="string_buffer.h">
- <title><tt>__vic/string_buffer.h</tt></title>
- <chapter xml:id="string_buffer">
- <title><tt>string_buffer</tt></title>
- <code-block lang="C++"><![CDATA[
- class string_buffer : public std::string
- {
- public:
- string_buffer();
- explicit string_buffer(size_type n);
- string_buffer(const char *str);
- string_buffer(std::string str);
- string_buffer(string_ref sr);
- string_buffer(const std::string &str, size_type off, size_type n = npos);
- string_buffer(const char *char_buf, size_type n);
- string_buffer(const char *begin, const char *end);
- template<class InputIterator>
- string_buffer(InputIterator begin, InputIterator end);
- string_buffer &operator<<(const char *str);
- string_buffer &operator<<(const std::string &str);
- string_buffer &operator<<(string_ref sr);
- string_buffer &operator<<(char ch);
- string_buffer &operator<<(long long n);
- string_buffer &operator<<(long n);
- string_buffer &operator<<(int n);
- string_buffer &operator<<(short n);
- string_buffer &operator<<(signed char ch);
- string_buffer &operator<<(unsigned long long n);
- string_buffer &operator<<(unsigned long n);
- string_buffer &operator<<(unsigned n);
- string_buffer &operator<<(unsigned short n);
- string_buffer &operator<<(unsigned char ch);
- string_buffer &operator<<(long double n);
- string_buffer &operator<<(double n);
- string_buffer &operator<<(float n);
- string_buffer &operator<<(bool flag);
- string_buffer &operator<<(const void *p);
- string_buffer &operator=(string_ref sr);
- string_buffer &operator+=(string_ref sr);
- string_buffer &assign(string_ref sr);
- string_buffer &append(string_ref sr);
- // improved std::string calls
- string_buffer &assign(const std::string &str,
- size_type off, size_type n = npos);
- string_buffer &append(const std::string &str,
- size_type off, size_type n = npos);
- string_buffer &insert(size_type pos, const std::string &str,
- size_type off, size_type n = npos);
- string_buffer &reserve(size_type n);
- string_buffer &clear();
- // missing container interface of std::string
- reference front();
- reference back();
- const_reference front() const;
- const_reference back() const;
- void pop_back();
- operator const char *() const;
- };
- string_buffer operator+(const string_buffer &s1, const string_buffer &s2);
- string_buffer operator+(const string_buffer &s1, const std::string &s2);
- string_buffer operator+(const std::string &s1, const string_buffer &s2);
- string_buffer operator+(const string_buffer &s1, const char *s2);
- string_buffer operator+(const char *s1, const string_buffer &s2);
- string_buffer operator+(const string_buffer &s, char ch);
- string_buffer operator+(char ch, const string_buffer &s);
- template<class T>
- string_buffer &operator<<(string_buffer &&s, const T &v); // C++11
- using msg = string_buffer;
- ]]></code-block>
- <p>Class is an extended and improved <tt>std::string</tt>. It has following
- advantages:</p>
- <list style="numbered">
- <item>Left-associative append operator (<tt><<</tt>) that allows
- constructions like this:
- <code-block lang="C++"><![CDATA[
- str << "Error message: " << err_msg << "\n";
- ]]></code-block></item>
- <item>Specific amount of bytes can be reserved using constructor as well as
- <tt>reserve()</tt> call. Reserving required amount of space in advance can
- improve performance significantly.
- <code-block lang="C++">
- __vic::string_buffer st(4096);
- // is same as
- std::string st;
- st.reserve(4096);
- </code-block></item>
- <item>Operator <tt><<</tt> accepts all fundamental types: numbers, chars,
- pointers, <tt>bool</tt>:
- <code-block lang="C++"><![CDATA[
- for(int i=0; i<10; i++)
- str << "i = " << i << '\n';
- ]]></code-block></item>
- <item>All input <tt>nullptr</tt> values of <tt>const char *</tt> are treated as
- an empty string. Such values usually cause crash with <tt>std::string</tt>.
- <code-block lang="C++">
- std::string s1("Str");
- const char *p = nullptr;
- s1.append(p); // Oops.... Null pointer access!
- __vic::string_buffer s2("Str");
- s2.append(p); // Ok. s2 == "Str" still
- s2 = p; // Ok. s2.empty() == true
- </code-block></item>
- <item>Automatic conversion to <tt>const char *</tt> that allows usage of the
- object in context requires C-string, without explicit <tt>c_str()</tt> call.
- <code-block lang="C++">
- std::string fname(...);
- FILE *fp = fopen(fname.c_str(), "r");
- __vic::string_buffer fname(...);
- FILE *fp = fopen(fname, "r");)
- </code-block></item>
- <item>Some design irregularities of <tt>std::string</tt> are corrected. For
- instance <tt>std::string</tt> is a complete container but operations
- <tt>front()</tt> and <tt>back()</tt> are missed in C++98. There is
- <tt>push_back()</tt> but no <tt>pop_back()</tt>.</item>
- </list>
- <p>In spite of all these improvements, the interface of this class is completely
- backward compatible with <tt>std::string</tt>. Objects can be passed in contexts
- that require <tt>std::string</tt>. Class has no additional data-members.</p>
- <p>Using of inserter (operator <tt><<</tt>) provides the easiest way to
- convert numbers to decimal string representation. Using of
- <tt>std::ostringstream</tt> for this purposes is more functional (you can
- specify radix, formatting, etc) but too tedious and not efficient in most
- cases.</p>
- <p>Additionally this type has a short synonym <tt>msg</tt>. It is very
- convenient for usage when one needs to construct a complex message with a
- single expression, without introducing unnecessary variables:</p>
- <code-block lang="C++"><![CDATA[
- oresult res = db_open(db_name);
- if(res != 0) throw __vic::exception(
- __vic::msg(64) << "Cannot open DB " << db_name << ". res = " << res
- );
- ]]></code-block>
- <p>As you can see, the maximum size of the message expected is specified in the
- constructor for optimization purposes.</p>
- <section><title>Class members</title>
- <synopsis>
- <prototype>string_buffer()</prototype>
- <p>Create an empty string.</p>
- <postcondition><tt>empty() == true</tt></postcondition>
- </synopsis>
- <synopsis>
- <prototype>explicit string_buffer(size_type n)</prototype>
- <p>Calls <tt>reserve(n)</tt>.</p>
- <postcondition><tt>capacity() >= n</tt></postcondition>
- </synopsis>
- <synopsis>
- <prototype>string_buffer(const char *str)</prototype>
- <prototype>string_buffer(std::string str)</prototype>
- <p>Creates the copy of <tt>str</tt>.</p>
- </synopsis>
- <synopsis>
- <prototype>string_buffer(const std::string &str, size_type off, size_type n = npos)</prototype>
- <p>Creates the copy of <tt>str</tt> substring.</p>
- </synopsis>
- <synopsis>
- <prototype>string_buffer(const char *char_buf, size_type n)</prototype>
- <p>Creates string using buffer and its length.</p>
- </synopsis>
- <synopsis>
- <prototype>string_buffer(string_ref sr)</prototype>
- <prototype>string_buffer(const char *begin, const char *end)</prototype>
- <prototype>template<class InputIterator>
- string_buffer(InputIterator begin, InputIterator end)</prototype>
- <p>Creates string from the chars range.</p>
- </synopsis>
- <synopsis>
- <prototype>string_buffer &operator<<(const char *str)</prototype>
- <prototype>string_buffer &operator<<(const std::string &str)</prototype>
- <prototype>string_buffer &operator<<(string_ref sr)</prototype>
- <prototype>string_buffer &operator<<(char ch)</prototype>
- <p>Calls <tt>std::string::append()</tt>.</p>
- </synopsis>
- <synopsis>
- <prototype>string_buffer &operator<<(long long n)</prototype>
- <prototype>string_buffer &operator<<(long n)</prototype>
- <prototype>string_buffer &operator<<(int n)</prototype>
- <prototype>string_buffer &operator<<(short n)</prototype>
- <prototype>string_buffer &operator<<(signed char ch)</prototype>
- <prototype>string_buffer &operator<<(unsigned long long n)</prototype>
- <prototype>string_buffer &operator<<(unsigned long n)</prototype>
- <prototype>string_buffer &operator<<(unsigned n)</prototype>
- <prototype>string_buffer &operator<<(unsigned short n)</prototype>
- <prototype>string_buffer &operator<<(unsigned char ch)</prototype>
- <prototype>string_buffer &operator<<(long double n)</prototype>
- <prototype>string_buffer &operator<<(double n)</prototype>
- <prototype>string_buffer &operator<<(float n)</prototype>
- <p>Appends decimal representaion of <tt>n</tt> to the string.</p>
- </synopsis>
- <synopsis>
- <prototype>string_buffer &operator<<(const void *p)</prototype>
- <p>Appends pointers value in <tt>%p</tt> format of <tt>std::printf</tt>.</p>
- </synopsis>
- <synopsis>
- <prototype>string_buffer &operator<<(bool flag)</prototype>
- <p>Appends <tt>1</tt> (for <tt>true</tt>) or <tt>0</tt> (for <tt>false</tt>)
- to the string.</p>
- </synopsis>
- <synopsis>
- <prototype>string_buffer &operator=(string_ref sr)</prototype>
- <prototype>string_buffer &operator+=(string_ref sr)</prototype>
- <prototype>string_buffer &assign(string_ref sr)</prototype>
- <prototype>string_buffer &append(string_ref sr)</prototype>
- <p>Operations for <tt>string_ref</tt>.</p>
- </synopsis>
- <synopsis>
- <prototype>string_buffer &reserve(size_type n)</prototype>
- <prototype>string_buffer &clear()</prototype>
- <p>Calls the corresponding <tt>std::string</tt> operation and additionally
- returns the reference to itself, so the call can be used in complex
- expressions.</p>
- </synopsis>
- <synopsis>
- <prototype>reference front()</prototype>
- <prototype>reference back()</prototype>
- <prototype>const_reference front() const</prototype>
- <prototype>const_reference back() const</prototype>
- <prototype>void pop_back()</prototype>
- <p>Missed container operations in the <tt>std::string</tt> interface in
- C++98.</p>
- </synopsis>
- <synopsis>
- <prototype>operator const char *() const</prototype>
- <p>Calls <tt>std::string::c_str()</tt>.</p>
- </synopsis>
- <synopsis>
- <prototype>string_buffer operator+(const string_buffer &s1, const string_buffer &s2)</prototype>
- <prototype>string_buffer operator+(const string_buffer &s1, const std::string &s2)</prototype>
- <prototype>string_buffer operator+(const std::string &s1, const string_buffer &s2)</prototype>
- <prototype>string_buffer operator+(const string_buffer &s1, const char *s2)</prototype>
- <prototype>string_buffer operator+(const char *s1, const string_buffer &s2)</prototype>
- <prototype>string_buffer operator+(const string_buffer &s, char ch)</prototype>
- <prototype>string_buffer operator+(char ch, const string_buffer &s)</prototype>
- <p>Concatenation of strings and characters.</p>
- </synopsis>
- <synopsis>
- <prototype><![CDATA[template<class T>
- string_buffer &operator<<(string_buffer &&s, const T &v)]]> <sign>C++11</sign></prototype>
- <p>Calls <tt>operator<<(string_buffer &s, const T &v)</tt>.</p>
- </synopsis>
- </section>
- </chapter>
- </chapter>
|