.. include:: header.rst

`home`__

__ reference.html

.. contents:: Table of contents
  :depth: 2
  :backlinks: none


Bencoding is a common representation in bittorrent used for dictionary,
list, `int`__ and string hierarchies. It's used to encode .torrent files and
some messages in the network protocol. libtorrent also uses it to store
settings, resume data and other `session`__ state.

Strings in bencoded structures do not necessarily represent text.
Strings are raw byte buffers of a certain length. If a string is meant to be
interpreted as text, it is required to be UTF-8 encoded. See `BEP 3`_.

The function for decoding bencoded data `bdecode()`__, returning a `bdecode_node`__.
This function builds a tree that points back into the original buffer. The
returned `bdecode_node`__ will not be valid once the buffer it was parsed out of
is discarded.

It's possible to construct an `entry`__ from a `bdecode_node`__, if a structure needs
to be altered and re-encoded.

.. raw:: html

	<a name="entry"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+entry&labels=documentation&body=Documentation+under+heading+%22class+entry%22+could+be+improved">report issue</a>]</span>



entry
-----

Declared in "`libtorrent/entry.hpp`__"


__ reference-Alerts.html#int
__ reference-Session.html#session
__ reference-Bdecoding.html#bdecode()
__ reference-Bdecoding.html#bdecode_node
__ reference-Bdecoding.html#bdecode_node
__ reference-Bencoding.html#entry
__ reference-Bdecoding.html#bdecode_node
__ include/libtorrent/entry.hpp

The ``entry`` class represents one node in a bencoded hierarchy. It works as a
variant type, it can be either a list, a dictionary (``std::map``), an integer
or a string.




.. parsed-literal::
	

	class entry
	{
	   data_type **type** () const;
	   **entry** (span<char const>);
	   **entry** (dictionary\_type);
	   **entry** (integer\_type);
	   **entry** (preformatted\_type);
	   **entry** (list\_type);
	   **entry** (U v);
	   **entry** (data\_type t);
	   **entry** (bdecode\_node const& n);
	   entry& **operator=** (dictionary\_type) &;
	   entry& **operator=** (entry const&) &;
	   entry& **operator=** (span<char const>) &;
	   entry& **operator=** (integer\_type) &;
	   entry& **operator=** (bdecode\_node const&) &;
	   entry& **operator=** (preformatted\_type) &;
	   entry& **operator=** (entry&&) & noexcept;
	   entry& **operator=** (list\_type) &;
	   entry& **operator=** (U v) &;
	   list_type& **list** ();
	   integer_type& **integer** ();
	   list_type const& **list** () const;
	   dictionary_type const& **dict** () const;
	   integer_type const& **integer** () const;
	   preformatted_type const& **preformatted** () const;
	   string_type const& **string** () const;
	   dictionary_type& **dict** ();
	   preformatted_type& **preformatted** ();
	   string_type& **string** ();
	   void **swap** (entry& e);
	   entry& **operator[]** (string\_view key);
	   entry const& **operator[]** (string\_view key) const;
	   entry const* **find_key** (string\_view key) const;
	   entry\* **find_key** (string\_view key);
	   std::string **to_string** (bool single\_line = false) const;
	
	   enum data_type
	   {
	      int_t,
	      string_t,
	      list_t,
	      dictionary_t,
	      undefined_t,
	      preformatted_t,
	   };
	};

.. raw:: html

	<a name="type()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:entry%3A%3A%5Btype%28%29%5D&labels=documentation&body=Documentation+under+heading+%22entry%3A%3A%5Btype%28%29%5D%22+could+be+improved">report issue</a>]</span>



type()
......

.. parsed-literal::
	
	data_type **type** () const;
	

returns the concrete type of the `entry`__


__ reference-Bencoding.html#entry

.. raw:: html

	<a name="entry()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:entry%3A%3A%5Bentry%28%29%5D&labels=documentation&body=Documentation+under+heading+%22entry%3A%3A%5Bentry%28%29%5D%22+could+be+improved">report issue</a>]</span>



entry()
.......

.. parsed-literal::
	
	**entry** (span<char const>);
	**entry** (dictionary\_type);
	**entry** (integer\_type);
	**entry** (preformatted\_type);
	**entry** (list\_type);
	

constructors directly from a specific type.
The content of the argument is copied into the
newly constructed `entry`__


__ reference-Bencoding.html#entry

.. raw:: html

	<a name="entry()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:entry%3A%3A%5Bentry%28%29%5D&labels=documentation&body=Documentation+under+heading+%22entry%3A%3A%5Bentry%28%29%5D%22+could+be+improved">report issue</a>]</span>



entry()
.......

.. parsed-literal::
	
	**entry** (data\_type t);
	

construct an empty `entry`__ of the specified type.
see `data_type`__ enum.


__ reference-Bencoding.html#entry
__ reference-Bencoding.html#data_type

.. raw:: html

	<a name="entry()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:entry%3A%3A%5Bentry%28%29%5D&labels=documentation&body=Documentation+under+heading+%22entry%3A%3A%5Bentry%28%29%5D%22+could+be+improved">report issue</a>]</span>



entry()
.......

.. parsed-literal::
	
	**entry** (bdecode\_node const& n);
	

construct from `bdecode_node`__ parsed form (see `bdecode()`__)


__ reference-Bdecoding.html#bdecode_node
__ reference-Bdecoding.html#bdecode()

.. raw:: html

	<a name="operator=()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:entry%3A%3A%5Boperator%3D%28%29%5D&labels=documentation&body=Documentation+under+heading+%22entry%3A%3A%5Boperator%3D%28%29%5D%22+could+be+improved">report issue</a>]</span>



operator=()
...........

.. parsed-literal::
	
	entry& **operator=** (dictionary\_type) &;
	entry& **operator=** (entry const&) &;
	entry& **operator=** (span<char const>) &;
	entry& **operator=** (integer\_type) &;
	entry& **operator=** (bdecode\_node const&) &;
	entry& **operator=** (preformatted\_type) &;
	entry& **operator=** (entry&&) & noexcept;
	entry& **operator=** (list\_type) &;
	

copies the structure of the right hand side into this
`entry`__.


__ reference-Bencoding.html#entry

.. raw:: html

	<a name="integer()"></a>
	<a name="preformatted()"></a>
	<a name="list()"></a>
	<a name="dict()"></a>
	<a name="string()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:entry%3A%3A%5Binteger%28%29+preformatted%28%29+list%28%29+dict%28%29+string%28%29%5D&labels=documentation&body=Documentation+under+heading+%22entry%3A%3A%5Binteger%28%29+preformatted%28%29+list%28%29+dict%28%29+string%28%29%5D%22+could+be+improved">report issue</a>]</span>



integer() preformatted() list() dict() string()
...............................................

.. parsed-literal::
	
	list_type& **list** ();
	integer_type& **integer** ();
	list_type const& **list** () const;
	dictionary_type const& **dict** () const;
	integer_type const& **integer** () const;
	preformatted_type const& **preformatted** () const;
	string_type const& **string** () const;
	dictionary_type& **dict** ();
	preformatted_type& **preformatted** ();
	string_type& **string** ();
	

The ``integer()``, ``string()``, ``list()`` and ``dict()`` functions
are accessors that return the respective type. If the ``entry`` object
isn't of the type you request, the accessor will throw
system_error. You can ask an ``entry`` for its type through the
``type()`` function.

If you want to create an ``entry`` you give it the type you want it to
have in its constructor, and then use one of the non-const accessors
to get a reference which you then can assign the value you want it to
have.

The typical code to get info from a torrent file will then look like
this:

.. code:: c++

	entry torrent_file;
	// ...

	// throws if this is not a dictionary
	entry::dictionary_type const& dict = torrent_file.dict();
	entry::dictionary_type::const_iterator i;
	i = dict.find("announce");
	if (i != dict.end())
	{
		std::string tracker_url = i->second.string();
		std::cout << tracker_url << "\n";
	}


The following code is equivalent, but a little bit shorter:

.. code:: c++

	entry torrent_file;
	// ...

	// throws if this is not a dictionary
	if (entry* i = torrent_file.find_key("announce"))
	{
		std::string tracker_url = i->string();
		std::cout << tracker_url << "\n";
	}


To make it easier to extract information from a torrent file, the
class `torrent_info`__ exists.


__ reference-Torrent_Info.html#torrent_info

.. raw:: html

	<a name="swap()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:entry%3A%3A%5Bswap%28%29%5D&labels=documentation&body=Documentation+under+heading+%22entry%3A%3A%5Bswap%28%29%5D%22+could+be+improved">report issue</a>]</span>



swap()
......

.. parsed-literal::
	
	void **swap** (entry& e);
	

swaps the content of *this* with ``e``.



.. raw:: html

	<a name="operator[]()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:entry%3A%3A%5Boperator%5B%5D%28%29%5D&labels=documentation&body=Documentation+under+heading+%22entry%3A%3A%5Boperator%5B%5D%28%29%5D%22+could+be+improved">report issue</a>]</span>



operator[]()
............

.. parsed-literal::
	
	entry& **operator[]** (string\_view key);
	entry const& **operator[]** (string\_view key) const;
	

All of these functions requires the `entry`__ to be a dictionary, if it
isn't they will throw ``system_error``.

The non-const versions of the ``operator[]`` will return a reference
to either the existing element at the given key or, if there is no
element with the given key, a reference to a newly inserted element at
that key.

The const version of ``operator[]`` will only return a reference to an
existing element at the given key. If the key is not found, it will
throw ``system_error``.


__ reference-Bencoding.html#entry

.. raw:: html

	<a name="find_key()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:entry%3A%3A%5Bfind_key%28%29%5D&labels=documentation&body=Documentation+under+heading+%22entry%3A%3A%5Bfind_key%28%29%5D%22+could+be+improved">report issue</a>]</span>



find_key()
..........

.. parsed-literal::
	
	entry const* **find_key** (string\_view key) const;
	entry\* **find_key** (string\_view key);
	

These functions requires the `entry`__ to be a dictionary, if it isn't
they will throw ``system_error``.

They will look for an element at the given key in the dictionary, if
the element cannot be found, they will return nullptr. If an element
with the given key is found, the return a pointer to it.


__ reference-Bencoding.html#entry

.. raw:: html

	<a name="to_string()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:entry%3A%3A%5Bto_string%28%29%5D&labels=documentation&body=Documentation+under+heading+%22entry%3A%3A%5Bto_string%28%29%5D%22+could+be+improved">report issue</a>]</span>



to_string()
...........

.. parsed-literal::
	
	std::string **to_string** (bool single\_line = false) const;
	

returns a pretty-printed string representation
of the bencoded structure, with JSON-style syntax



.. raw:: html

	<a name="data_type"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+data_type&labels=documentation&body=Documentation+under+heading+%22enum+data_type%22+could+be+improved">report issue</a>]</span>



enum data_type
..............

Declared in "`libtorrent/entry.hpp`__"


__ include/libtorrent/entry.hpp

+----------------+-------+-------------+
| name           | value | description |
+================+=======+=============+
| int_t          | 0     |             |
+----------------+-------+-------------+
| string_t       | 1     |             |
+----------------+-------+-------------+
| list_t         | 2     |             |
+----------------+-------+-------------+
| dictionary_t   | 3     |             |
+----------------+-------+-------------+
| undefined_t    | 4     |             |
+----------------+-------+-------------+
| preformatted_t | 5     |             |
+----------------+-------+-------------+



.. raw:: html

	<a name="bencode()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:bencode%28%29&labels=documentation&body=Documentation+under+heading+%22bencode%28%29%22+could+be+improved">report issue</a>]</span>



bencode()
---------

Declared in "`libtorrent/bencode.hpp`__"


__ include/libtorrent/bencode.hpp

.. parsed-literal::
	
	template<class OutIt> int **bencode** (OutIt out, const entry& e);
	

This function will encode data to bencoded form.

The entry_ class is the internal representation of the bencoded data
and it can be used to retrieve information, an entry_ can also be build by
the program and given to ``bencode()`` to encode it into the ``OutIt``
iterator.

``OutIt`` is an OutputIterator_. It's a template and usually
instantiated as ostream_iterator_ or back_insert_iterator_. This
function assumes the value_type of the iterator is a ``char``.
In order to encode `entry`__ ``e`` into a buffer, do::

	std::vector<char> buffer;
	bencode(std::back_inserter(buf), e);

.. _OutputIterator:  https://en.cppreference.com/w/cpp/named_req/OutputIterator
.. _ostream_iterator: https://en.cppreference.com/w/cpp/iterator/ostream_iterator
.. _back_insert_iterator: https://en.cppreference.com/w/cpp/iterator/back_insert_iterator


__ reference-Bencoding.html#entry

.. raw:: html

	<a name="operator<<()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:operator%3C%3C%28%29&labels=documentation&body=Documentation+under+heading+%22operator%3C%3C%28%29%22+could+be+improved">report issue</a>]</span>



operator<<()
------------

Declared in "`libtorrent/entry.hpp`__"


__ include/libtorrent/entry.hpp

.. parsed-literal::
	
	inline std::ostream& **operator<<** (std\:\:ostream& os, const entry& e);
	

prints the bencoded structure to the ostream as a JSON-style structure.





.. _`BEP 3`: https://www.bittorrent.org/beps/bep_0003.html
.. _`BEP 17`: https://www.bittorrent.org/beps/bep_0017.html
.. _extensions: manual-ref.html#extensions
.. _`BEP 52`: https://www.bittorrent.org/beps/bep_0052.html
.. _`BEP 19`: https://www.bittorrent.org/beps/bep_0019.html
.. _`BEP 38`: https://www.bittorrent.org/beps/bep_0038.html
.. _`rate based choking`: manual-ref.html#rate-based-choking
.. _`BEP 42`: https://www.bittorrent.org/beps/bep_0042.html
