123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202 |
- <chapter xml:id="base64.h">
- <title><tt>__vic/base64.h</tt></title>
- <p>Base64 encoder and decoder.</p>
- <chapter xml:id="base64">
- <title><tt>base64</tt></title>
- <p>A class used as a namespace. Contains only types, constants and static
- functions. No objects of this class are supposed to be created.</p>
- </chapter>
- <chapter xml:id="base64--bad_format">
- <title><tt>base64::bad_format</tt></title>
- <code-block lang="C++">
- struct base64::bad_format : public std::exception {};
- </code-block>
- <p>Abstract base exception class.</p>
- </chapter>
- <chapter xml:id="base64--bad_digit">
- <title><tt>base64::bad_digit</tt></title>
- <code-block lang="C++">
- struct base64::bad_digit : public base64::bad_format
- {
- const char *what() const noexcept;
- };
- </code-block>
- <p>Exception class thrown by <xref to="base64--decode"/> when the input sequence
- contains character that is not a valid Base64 digit.</p>
- </chapter>
- <chapter xml:id="base64--bad_length">
- <title><tt>base64::bad_length</tt></title>
- <code-block lang="C++">
- struct base64::bad_length : public base64::bad_format
- {
- const char *what() const noexcept;
- };
- </code-block>
- <p>Exception class thrown by <xref to="base64--decode"/> when the input sequence
- length is not a multiple of 4.</p>
- </chapter>
- <chapter xml:id="base64--status">
- <title><tt>base64::status</tt></title>
- <code-block lang="C++">
- enum class base64::status
- {
- ok,
- invalid_length,
- invalid_digit
- };
- using base64::status_t = base64::status; // for C++98
- </code-block>
- <p>Input sequence parsing outcome status codes returned by
- <xref to="base64--try_decode"/>.</p>
- </chapter>
- <chapter xml:id="base64--encode">
- <title><tt>base64::encode()</tt></title>
- <code-block lang="C++"><![CDATA[
- // Bytes -> Text
- template<class ByteReader, class CharWriter>
- void base64::encode(ByteReader reader, CharWriter writer);
- ]]></code-block>
- <p>Encodes bytes from <tt>reader</tt> and writes the resulting characters to
- <tt>writer</tt>.</p>
- <p><tt>ByteReader</tt> has to model <tt>Reader<unsigned char></tt> concept.
- See <xref to="readers"/>.</p>
- <p><tt>CharWriter</tt> has to model <tt>Writer<char></tt> concept.
- See <xref to="writers"/>.</p>
- <section><title>Example</title>
- <code-block lang="C++"><![CDATA[
- #include<__vic/readers/string.h>
- #include<__vic/writers/string.h>
- using bytes = std::string;
- using bytes_reader = __vic::string_reader;
- std::string encode_base64(const bytes &s)
- {
- std::string res;
- res.reserve(__vic::base64::encoded_length(s.length()));
- __vic::base64::encode(bytes_reader(s), __vic::string_writer(res));
- return res;
- }
- ]]></code-block>
- </section>
- </chapter>
- <chapter xml:id="base64--decode">
- <title><tt>base64::decode()</tt></title>
- <code-block lang="C++"><![CDATA[
- // Text -> Bytes
- template<class CharReader, class ByteWriter>
- void base64::decode(CharReader reader, ByteWriter writer);
- ]]></code-block>
- <p>Decodes characters form <tt>reader</tt> and writes the resulting bytes to
- <tt>writer</tt>. Exception derived from <xref to="base64--bad_format"/> is
- thrown if the input sequence has invalid Base64 format.</p>
- <p><tt>CharReader</tt> has to model <tt>Reader<char></tt> concept.
- See <xref to="readers"/>.</p>
- <p><tt>ByteWriter</tt> has to model <tt>Writer<unsigned char></tt> concept.
- See <xref to="writers"/>.</p>
- <section><title>Example</title>
- <code-block lang="C++"><![CDATA[
- #include<__vic/readers/string.h>
- #include<__vic/writers/string.h>
- using bytes = std::string;
- using bytes_writer = __vic::string_writer;
- bytes decode_base64(const std::string &s)
- {
- bytes res;
- res.reserve(__vic::base64::max_decoded_length(s.length()));
- __vic::base64::decode(__vic::string_reader(s), bytes_writer(res));
- return res;
- }
- ]]></code-block>
- </section>
- </chapter>
- <chapter xml:id="base64--try_decode">
- <title><tt>base64::try_decode()</tt></title>
- <code-block lang="C++"><![CDATA[
- // Text -> Bytes
- template<class CharReader, class ByteWriter>
- base64::status_t base64::try_decode(CharReader reader, ByteWriter writer);
- ]]></code-block>
- <p>Same as <xref to="base64--decode"/> but returns <xref to="base64--status"/>
- different from <tt>base64::status::ok</tt> in case of invalid input sequence
- instead of throwing exception.</p>
- </chapter>
- <chapter xml:id="base64--encoded_length">
- <title><tt>base64::encoded_length()</tt></title>
- <code-block lang="C++">
- constexpr size_t base64::encoded_length(size_t orig_len);
- </code-block>
- <p>Calculates the length of encoded sequence of characters using the original
- length of the bytes sequence.</p>
- </chapter>
- <chapter xml:id="base64--max_decoded_length">
- <title><tt>base64::max_decoded_length()</tt></title>
- <code-block lang="C++">
- constexpr size_t base64::max_decoded_length(size_t orig_len);
- </code-block>
- <p>Estimates the maximum length of decoded sequence of bytes using the original
- length of the characters sequence. The actual value depends on trailing
- <tt>'='</tt> in the encoded value.</p>
- </chapter>
- </chapter>
|