__vic/doc/en/readers.xml

<chapter xml:id="readers">
<title><tt>__vic/readers/</tt></title>


<chapter xml:id="reader-concept">
<title><tt>Reader</tt> concept</title>

<code-block lang="C++"><![CDATA[
template<class ElementT>
class ]]><nt>Reader</nt><![CDATA[
{
public:
    Reader(Reader &&o); or Reader(const Reader &o);
    bool read(ElementT &v); // throws on errors
};
]]></code-block>

<p>A concept used by the library algorithms to read logical sequence of elements
of type <tt>ElementT</tt> element by element. It is a generalization and rework
of the <tt>InputIterator</tt> concept. In particular it handles streams,
NULL-terminated strings and other sequences where <tt>end</tt>-iterator is
meaningless or expensive to obtain better. At the same time, a traditional
[<tt>begin</tt>,<tt>end</tt>) pair of iterators is just a particular case and
fully and well handled by <tt>__vic::iterator_reader</tt> adapter.</p>

<p>When the particular class meets the requirements of this concept for some
<tt>ElementT = T</tt> it is said <b>to model</b> the <tt>Reader&lt;T></tt>
concept.</p>

<p>Each instance of the class has to be move- or copy-constructible.</p>

<section><title>Class members</title>

<synopsis>
<prototype>bool read(ElementT &amp;v)</prototype>
<p>Attempts to get the next element of the sequence. Returns <tt>true</tt> and
places the value to <tt>v</tt> on success. Returns <tt>false</tt> if no element
available (EOF). Throws an exception in other cases.</p>
</synopsis>

</section>

</chapter>


<chapter xml:id="iterator_reader">
<title><tt>iterator_reader</tt></title>

<code-block lang="C++"><![CDATA[
#include<__vic/readers/iterator.h>

template<class InputIterator,
         class T = typename std::iterator_traits<InputIterator>::value_type>
class iterator_reader
{
public:
    iterator_reader(InputIterator begin, InputIterator end);
    bool read(T &v);
    InputIterator position() const;
};

template<class InputIterator> iterator_reader<InputIterator>
make_iterator_reader(InputIterator begin, InputIterator end);

template<class T, class InputIterator> iterator_reader<InputIterator,T>
make_iterator_reader_for(InputIterator begin, InputIterator end);
]]></code-block>

<p>An adapter for a traditional [<tt>begin</tt>,<tt>end</tt>) pair of iterators.
</p>

<p>Additional <tt>position()</tt> function returns the current iterator
position.</p>

<p>Can be created using constructor or one of <tt>make_...</tt> functions.</p>

</chapter>


<chapter xml:id="iterator_reader_n">
<title><tt>iterator_reader_n</tt></title>

<code-block lang="C++"><![CDATA[
#include<__vic/readers/iterator.h>

template<class InputIterator,
         class T = typename std::iterator_traits<InputIterator>::value_type>
class iterator_reader_n
{
public:
    iterator_reader_n(InputIterator begin, size_t n);
    bool read(T &v);
    InputIterator position() const;
};

template<class InputIterator> iterator_reader_n<InputIterator>
make_iterator_reader_n(InputIterator begin, size_t n);

template<class T, class InputIterator> iterator_reader_n<InputIterator,T>
make_iterator_reader_n_for(InputIterator begin, size_t n);
]]></code-block>

<p>An adapter for iterator + elements counter.</p>

<p>Additional <tt>position()</tt> function returns the current iterator
position.</p>

<p>Can be created using constructor or one of <tt>make_...</tt> functions.</p>

</chapter>


<chapter xml:id="container_reader">
<title><tt>container_reader</tt></title>

<code-block lang="C++"><![CDATA[
#include<__vic/readers/container.h>

template<class Cont, class T = typename Cont::value_type>
class container_reader
{
public:
    explicit container_reader(const Cont &c);
    bool read(T &v);
    typename Cont::const_iterator position() const;
};

template<class Cont>
container_reader<Cont> make_container_reader(const Cont &c);

template<class T, class Cont>
container_reader<Cont,T> make_container_reader_for(const Cont &c);
]]></code-block>

<p>An adapter for STL-style container classes with <tt>begin()</tt> and
<tt>end()</tt> members.</p>

<p>Additional <tt>position()</tt> function returns the current iterator
position.</p>

<p>Can be created using constructor or one of <tt>make_...</tt> functions.</p>

</chapter>


<chapter xml:id="cstring_reader">
<title><tt>cstring_reader</tt></title>

<code-block lang="C++"><![CDATA[
#include<__vic/readers/cstring.h>

template<class charT>
class basic_cstring_reader
{
public:
    explicit basic_cstring_reader(const charT *s);
    bool read(charT &ch);
    const charT *position() const;
};

template<>
class basic_cstring_reader<char>
{
public:
    explicit basic_cstring_reader(const char *s);
    bool read(char &ch);
    bool read(unsigned char &ch);
    const char *position() const;
};
using cstring_reader = basic_cstring_reader<char>;

template<class charT>
basic_cstring_reader<charT> make_cstring_reader(const charT *s);
]]></code-block>

<p>An adapter for NULL-terminated C-style strings.</p>

<p>Additional <tt>position()</tt> function returns the current pointer
position.</p>

<p><tt>char</tt> specialization models <tt>Reader&lt;unsigned char></tt> as
well as <tt>Reader&lt;char></tt>.</p>

<p>Can be created using constructor or <tt>make_...</tt> function.</p>

</chapter>


<chapter xml:id="string_reader">
<title><tt>string_reader</tt></title>

<code-block lang="C++"><![CDATA[
#include<__vic/readers/string.h>

template<
    class charT,
    class Tr = std::char_traits<charT>,
    class Al = std::allocator<charT>
>
class basic_string_reader
{
public:
    explicit basic_string_reader(const std::basic_string<charT,Tr,Al> &s);
    bool read(charT &ch);
    const charT *position() const;
};

template<class Tr, class Al>
class basic_string_reader<char,Tr,Al>
{
public:
    explicit basic_string_reader(const std::basic_string<char,Tr,Al> &s);
    bool read(char &ch);
    bool read(unsigned char &ch);
    const char *position() const;
};
using string_reader = basic_string_reader<char>;

template<class charT, class Tr, class Al>
basic_string_reader<charT,Tr,Al>
    make_string_reader(const std::basic_string<charT,Tr,Al> &s);
]]></code-block>

<p>An adapter for <tt>std::basic_string</tt>.</p>

<p>Additional <tt>position()</tt> function returns the current pointer
position.</p>

<p><tt>char</tt> specialization models <tt>Reader&lt;unsigned char></tt> as
well as <tt>Reader&lt;char></tt>.</p>

<p>Can be created using constructor or <tt>make_...</tt> function.</p>

</chapter>


<chapter xml:id="cstream_reader">
<title><tt>cstream_reader</tt></title>

<code-block lang="C++"><![CDATA[
#include<__vic/readers/cstream.h>

class cstream_reader
{
public:
    explicit cstream_reader(std::FILE *fp);
    bool read(char &ch) { return __vic::read(fp, ch); }
    bool read(unsigned char &ch) { return __vic::read(fp, ch); }
};

cstream_reader make_cstream_reader(std::FILE *fp);
]]></code-block>

<p>Models <tt>Reader&lt;char></tt> and <tt>Reader&lt;unsigned char></tt> for
<tt>std::FILE</tt>.</p>

<p>Can be created using constructor or <tt>make_...</tt> function.</p>

</chapter>


</chapter>