Difference between revisions of "cpp/iterator/istreambuf iterator"

Latest revision as of 05:19, 12 July 2024

Defined in header `<iterator>`
template< class CharT, class Traits = std::char_traits<CharT> > class istreambuf_iterator : public std::iterator<std::input_iterator_tag, CharT, typename Traits::off_type, /* unspecified */, CharT>		(until C++17)
template< class CharT, class Traits = std::char_traits<CharT> > class istreambuf_iterator;		(since C++17)

std::istreambuf_iterator is a single-pass input iterator that reads successive characters from the std::basic_streambuf object for which it was constructed.

The default-constructed std::istreambuf_iterator is known as the end-of-stream iterator. When a valid std::istreambuf_iterator reaches the end of the underlying stream, it becomes equal to the end-of-stream iterator. Dereferencing or incrementing it further invokes undefined behavior.

std::istreambuf_iterator has a trivial copy constructor, a constexpr default constructor, and a trivial destructor.

(since C++11)

Member type	Definition
`iterator_category`	std::input_iterator_tag
`value_type`	CharT
`difference_type`	typename Traits::off_type
`pointer`	/* unspecified */
`reference`	CharT
`char_type`	`CharT`
`traits_type`	`Traits`
`int_type`	typename Traits::int_type
`streambuf_type`	std::basic_streambuf<CharT, Traits>
`istream_type`	std::basic_istream<CharT, Traits>
`/* proxy */`	Implementation-defined class type. A `proxy` object holds a `char_type` character and a `streambuf_type` pointer. Dereferencing a `proxy` object with `operator` yields the stored character. (exposition-only member type*)

Member types iterator_category, value_type, difference_type, pointer and reference are required to be obtained by inheriting from std::iterator<std::input_iterator_tag, CharT, typename Traits::off_type, /* unspecified */, CharT>.

(until C++17)

The member type pointer is usually CharT* (see below).

[edit] Member functions

(constructor)	constructs a new `istreambuf_iterator` (public member function) [edit]
(destructor) (implicitly declared)	destructs an `istreambuf_iterator` (public member function) [edit]
operator*	obtains a copy of the current character (public member function) [edit]
operator++operator++(int)	advances the iterator (public member function) [edit]
equal	tests if both `istreambuf_iterator`s are end-of-stream or if both are valid (public member function) [edit]

[edit] Non-member functions

operator==operator!=

(removed in C++20)

compares two istreambuf_iterators
(function template) [edit]

[edit] Notes

The resolution of LWG issue 659 introduced operator->. It is expected that given an std::istreambuf_iterator i, the expressions (*i).m and i->m have the same effect.

However, the resolution does not provide a formal specification of its behavior. Thus it is implemented differently, including returning nullptr, returning the address of a temporary, or does even provide the member at all. Its intended behavior can hardly be achieved, and it is removed by the resolution of LWG issue 2790.

The resolution of LWG issue 659 also made the member type pointer unspecified in order to allow operator-> to return a proxy. This is to allow operator-> to compile when CharT is not a class type.

[edit] Example

Run this code

#include <iostream>
#include <iterator>
#include <sstream>
#include <string>
 
int main()
{
    // typical use case: an input stream represented as a pair of iterators
    std::istringstream in{"Hello, world"};
    std::istreambuf_iterator<char> it{in}, end;
    std::string ss{it, end};
    std::cout << "ss has " << ss.size() << " bytes; "
                 "it holds \"" << ss << "\"\n";
 
    // demonstration of the single-pass nature
    std::istringstream s{"abc"};
    std::istreambuf_iterator<char> i1{s}, i2{s};
    std::cout << "i1 returns '" << *i1 << "'\n"
                 "i2 returns '" << *i2 << "'\n";
 
    ++i1;
    std::cout << "after incrementing i1, but not i2:\n"
                 "i1 returns '" << *i1 << "'\n"
                 "i2 returns '" << *i2 << "'\n";
 
    ++i2;
    std::cout << "after incrementing i2, but not i1:\n"
                 "i1 returns '" << *i1 << "'\n"
                 "i2 returns '" << *i2 << "'\n";
}

Output:

ss has 12 bytes; it holds "Hello, world"
i1 returns 'a'
i2 returns 'a'
after incrementing i1, but not i2:
i1 returns 'b'
i2 returns 'b'
after incrementing i2, but not i1:
i1 returns 'c'
i2 returns 'c'

[edit] Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR	Applied to	Behavior as published	Correct behavior
LWG 659	C++98	1. `std::istreambuf_iterator` did not have operator-> 2. the member type `pointer` was specified as `CharT*`	1. added 2. made unspecified
LWG 2790	C++98	the operator-> added by LWG issue 659 was not useful	removed

[edit] See also

ostreambuf_iterator	output iterator that writes to std::basic_streambuf (class template) [edit]
istream_iterator	input iterator that reads from std::basic_istream (class template) [edit]

@@ Line 1: / Line 1: @@
 {{cpp/title|istreambuf_iterator}}
-{{cpp/iterator/istreambuf_iterator/sidebar}}
+{{cpp/iterator/istreambuf_iterator/navbar}}
-{{ddcl list begin}}
+{{dcl begin}}
-{{ddcl list header | iterator}}
+{{dcl header|iterator}}
-{{ddcl list item | 1=
+{{dcl rev begin}}
+{{dcl|until=c++17|1=
 template< class CharT, class Traits = std::char_traits<CharT> >
-class istreambuf_iterator : public std::iterator< std::input_iterator_tag,
+class istreambuf_iterator
-                                                  CharT,
+    : public std::iterator<std::input_iterator_tag,
-                                                  typename Traits::off_type,
+                           CharT, typename Traits::off_type,
-                                                  /*unspecified*/,
+                           /* unspecified */, CharT>
-                                                  CharT >
 }}
-{{ddcl list end}}
+{{dcl|since=c++17|1=
+template< class CharT, class Traits = std::char_traits<CharT> >
+class istreambuf_iterator;
+}}
+{{dcl rev end}}
+{{dcl end}}
-{{tt|std::istreambuf_iterator}} is a single-pass input iterator that reads successive characters from the {{cpp|std::basic_streambuf}} object for which it was constructed. The actual read operation is performed when the iterator is incremented, not when it is dereferenced. The first character may be read when the iterator is constructed or when the first dereferencing is done. Otherwise, dereferencing only returns a copy of the most recently read character.
+{{tt|std::istreambuf_iterator}} is a single-pass input iterator that reads successive characters from the {{lc|std::basic_streambuf}} object for which it was constructed.
 The default-constructed {{tt|std::istreambuf_iterator}} is known as the ''end-of-stream'' iterator. When a valid {{tt|std::istreambuf_iterator}} reaches the end of the underlying stream, it becomes equal to the end-of-stream iterator. Dereferencing or incrementing it further invokes undefined behavior.
+{{rrev|since=c++11|
 {{tt|std::istreambuf_iterator}} has a trivial copy constructor, a constexpr default constructor, and a trivial destructor.
+}}
-===Member types===
+{{cpp/iterator/iterator/inherit|std::input_iterator_tag|CharT|typename Traits::off_type|/* unspecified */|CharT|ext=
-{{tdcl list begin}}
+{{dsc|{{tt|char_type}}|{{tt|CharT}}}}
-{{tdcl list hitem | Member type | Definition}}
+{{dsc|{{tt|traits_type}}|{{tt|Traits}}}}
-{{tdcl list item | {{tt|char_type}} | {{tt|CharT}}}}
+{{dsc|{{tt|int_type}}|{{c/core|typename Traits::int_type}}}}
-{{tdcl list item | {{tt|traits_type}} | {{tt|Traits}}}}
+{{dsc|{{tt|streambuf_type}}|{{c/core|std::basic_streambuf<CharT, Traits>}}}}
-{{tdcl list item | {{tt|int_type}} | {{cpp|typename traits::int_type}}}}
+{{dsc|{{tt|istream_type}}|{{c/core|std::basic_istream<CharT, Traits>}}}}
-{{tdcl list item | {{tt|streambuf_type}} | {{cpp|std::basic_streambuf<CharT, Traits>}}
+{{dsc expos mem type|{{c/core|/* proxy */}}|Implementation-defined class type.<br>A {{tt|''proxy''}} object holds a {{tt|char_type}} character and a {{tt|streambuf_type*}} pointer.<br>Dereferencing a {{tt|''proxy''}} object with {{tt|operator*}} yields the stored character.}}
-{{tdcl list item | {{tt|istream_type}} | {{cpp|std::basic_istream<CharT, Traits>}}
+}}
-{{tdcl list end}}
+The member type {{tt|pointer}} is usually {{tt|CharT*}} (see [[#Notes|below]]).
 ===Member functions===
-{{dcl list begin}}
+{{dsc begin}}
-{{dcl list mem ctor | cpp/iterator/istreambuf_iterator/istreambuf_iterator | constructs a new istreambuf_iterator }}
+{{dsc inc|cpp/iterator/istreambuf_iterator/dsc constructor}}
-{{dcl list mem dtor | nolink=true| destructs an istreambuf_iterator | notes={{mark implicit}} }}
+{{dsc inc|cpp/iterator/istreambuf_iterator/dsc destructor}}
-{{dcl list mem fun | cpp/iterator/istreamubuf_iterator/operator* | obtains a copy of the current character, if {{tt|CharT}} has members }}
+{{dsc inc|cpp/iterator/istreambuf_iterator/dsc operator*}}
-{{dcl list mem fun | cpp/iterator/istreamubuf_iterator/operator_to | title=operator-> | accesses a member of the current character | notes={{mark c++11}}}}
+{{dsc inc|cpp/iterator/istreambuf_iterator/dsc operator_arith}}
-{{dcl list mem fun | cpp/iterator/istreamubuf_iterator/operator++ | title=operator++<br>operator++(int) | advances the istreambuf_iterator }}
+{{dsc inc|cpp/iterator/istreambuf_iterator/dsc equal}}
-{{dcl list mem fun | cpp/iterator/istreamubuf_iterator/equal | tests if both istreambuf_iterators are end-of-stream or if both are valid}}
+{{dsc end}}
-{{dcl list end}}
 ===Non-member functions===
-{{dcl list begin}}
+{{dsc begin}}
-{{dcl list tfun | cpp/iterator/istreambuf_iterator/operator_eq | title=operator==<br>operator!= | compares two istreambuf_iterators }}
+{{dsc inc|cpp/iterator/istreambuf_iterator/dsc operator_cmp}}
-{{dcl list end}}
+{{dsc end}}
+===Notes===
+The resolution of {{lwg|659}} introduced {{c/core|operator->}}. It is expected that given an {{tt|std::istreambuf_iterator}} {{c|i}}, the expressions {{c|(*i).m}} and {{c|i->m}} have the same effect.
+However, the resolution does not provide a formal specification of its behavior. Thus it is implemented differently, including returning {{c|nullptr}}, returning the address of a temporary, or does even provide the member at all. Its intended behavior can hardly be achieved, and it is removed by the resolution of {{lwg|2790}}.
+The resolution of {{lwg|659}} also made the member type {{tt|pointer}} unspecified in order to allow {{tt|operator->}} to return a proxy. This is to allow {{tt|operator->}} to compile when {{tt|CharT}} is not a class type.
 ===Example===
-{{example cpp
+{{example
- |
+|code=
- | code=
-#include <vector>
-#include <sstream>
 #include <iostream>
 #include <iterator>
+#include <sstream>
+#include <string>
 int main()
 {
      // typical use case: an input stream represented as a pair of iterators
-     std::istringstream in("Hello, world");
+     std::istringstream in{"Hello, world"};
-     std::vector<char> v( (std::istreambuf_iterator<char>(in)),
+     std::istreambuf_iterator<char> it{in}, end;
-                          std::istreambuf_iterator<char>() );
+    std::string ss{it, end};
-     std::cout << "v has " << v.size() << " bytes. ";
+     std::cout << "ss has " << ss.size() << " bytes; "
-    v.push_back('\0');
+                 "it holds \"" << ss << "\"\n";
-    std::cout << "it holds \"" << &v[0] << "\"\n";
      // demonstration of the single-pass nature
-     std::istringstream s("abc");
+     std::istringstream s{"abc"};
-     std::istreambuf_iterator<char> i1(s), i2(s);
+     std::istreambuf_iterator<char> i1{s}, i2{s};
-     std::cout << "i1 returns " << *i1 << '\n'
+     std::cout << "i1 returns '" << *i1 << "'\n"
-              << "i2 returns " << *i2 << '\n';
+                 "i2 returns '" << *i2 << "'\n";
      ++i1;
-     std::cout << "after incrementing i1, but not i2\n"
+     std::cout << "after incrementing i1, but not i2:\n"
-              << "i1 returns " << *i1 << '\n'
+                 "i1 returns '" << *i1 << "'\n"
-              << "i2 returns " << *i2 << '\n';
+                 "i2 returns '" << *i2 << "'\n";
-     ++i2; // this makes the apparent value of *i2 to jump from 'a' to 'c'
-     std::cout << "after incrementing i2, but not i1\n"
+     ++i2;
-              << "i1 returns " << *i1 << '\n'
+     std::cout << "after incrementing i2, but not i1:\n"
-              << "i2 returns " << *i2 << '\n';
+                 "i1 returns '" << *i1 << "'\n"
+                 "i2 returns '" << *i2 << "'\n";
 }
- | output=
+|output=
-v has 12 bytes. it holds "Hello, world"
+ss has 12 bytes; it holds "Hello, world"
-i1 returns a
+i1 returns 'a'
-i2 returns a
+i2 returns 'a'
-after incrementing i1, but not i2
+after incrementing i1, but not i2:
-i1 returns b
+i1 returns 'b'
-i2 returns a
+i2 returns 'b'
-after incrementing i2, but not i1
+after incrementing i2, but not i1:
-i1 returns b
+i1 returns 'c'
-i2 returns c
+i2 returns 'c'
 }}
+===Defect reports===
+{{dr list begin}}
+{{dr list item|wg=lwg|dr=659|std=C++98|before=1. {{tt|std::istreambuf_iterator}} did not have {{c/core|operator->}}<br>2. the member type {{tt|pointer}} was specified as {{tt|CharT*}}|after=1. added<br>2. made unspecified}}
+{{dr list item|wg=lwg|dr=2790|std=C++98|before=the {{c/core|operator->}} added by {{lwg|659}} was not useful|after=removed}}
+{{dr list end}}
 ===See also===
-{{dcl list begin}}
+{{dsc begin}}
-{{dcl list template | cpp/iterator/dcl list ostreambuf_iterator}}
+{{dsc inc|cpp/iterator/dsc ostreambuf_iterator}}
-{{dcl list template | cpp/iterator/dcl list istream_iterator}}
+{{dsc inc|cpp/iterator/dsc istream_iterator}}
-{{dcl list end}}
+{{dsc end}}
+{{langlinks|de|es|fr|it|ja|pt|ru|zh}}

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Metaprogramming library (C++11)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (C++17)
Regular expressions library (C++11)
Concurrency support library (C++11)
Execution support library (C++26)
Technical specifications
Symbols index
External libraries

Member functions
istreambuf_iterator::istreambuf_iterator
istreambuf_iterator::operator*
istreambuf_iterator::operator++istreambuf_iterator::operator++(int)
istreambuf_iterator::equal
Non-member functions
operator==operator!= (until C++20)

cppreference.com

Namespaces

Variants

Views

Actions

Difference between revisions of "cpp/iterator/istreambuf iterator"

Latest revision as of 05:19, 12 July 2024

Contents

[edit] Member types