.. include:: header.rst

`home`__

__ reference.html

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

.. raw:: html

	<a name="bdecode_node"></a>

.. raw:: html

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



bdecode_node
------------

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


__ include/libtorrent/bdecode.hpp

Sometimes it's important to get a non-owning reference to the root node (
to be able to copy it as a reference for instance). For that, use the
`non_owning()`__ member function.

There are 5 different types of nodes, see `type_t`__.


__ reference-Bdecoding.html#non_owning()
__ reference-Torrent_Info.html#type_t


.. parsed-literal::
	

	struct bdecode_node
	{
	   **bdecode_node** () = default;
	   **bdecode_node** (bdecode\_node const&);
	   **bdecode_node** (bdecode\_node&&) noexcept;
	   bdecode_node& **operator=** (bdecode\_node&&) & = default;
	   bdecode_node& **operator=** (bdecode\_node const&) &;
	   type_t **type** () const noexcept;
	   explicit operator **bool** () const noexcept;
	   bdecode_node **non_owning** () const;
	   span<char const> **data_section** () const noexcept;
	   std::ptrdiff_t **data_offset** () const noexcept;
	   std::int64_t **list_int_value_at** (int i
	      , std\:\:int64\_t default\_val = 0) const;
	   bdecode_node **list_at** (int i) const;
	   string_view **list_string_value_at** (int i
	      , string\_view default\_val = string\_view()) const;
	   int **list_size** () const;
	   bdecode_node **dict_find_dict** (string\_view key) const;
	   std::pair<string_view, bdecode_node> **dict_at** (int i) const;
	   int **dict_size** () const;
	   bdecode_node **dict_find_list** (string\_view key) const;
	   bdecode_node **dict_find_int** (string\_view key) const;
	   std::pair<bdecode_node, bdecode_node> **dict_at_node** (int i) const;
	   bdecode_node **dict_find** (string\_view key) const;
	   std::int64_t **dict_find_int_value** (string\_view key
	      , std\:\:int64\_t default\_val = 0) const;
	   bdecode_node **dict_find_string** (string\_view key) const;
	   string_view **dict_find_string_value** (string\_view key
	      , string\_view default\_value = string\_view()) const;
	   std::int64_t **int_value** () const;
	   int **string_length** () const;
	   char const* **string_ptr** () const;
	   string_view **string_value** () const;
	   std::ptrdiff_t **string_offset** () const;
	   void **clear** ();
	   void **swap** (bdecode\_node& n);
	   void **reserve** (int tokens);
	   void **switch_underlying_buffer** (char const\* buf) noexcept;
	   bool **has_soft_error** (span<char> error) const;
	
	   enum type_t
	   {
	      none_t,
	      dict_t,
	      list_t,
	      string_t,
	      int_t,
	   };
	};

.. raw:: html

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

.. raw:: html

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



bdecode_node()
..............

.. parsed-literal::
	
	**bdecode_node** () = default;
	

creates a default constructed node, it will have the type ``none_t``.



.. raw:: html

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

.. raw:: html

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



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

.. parsed-literal::
	
	**bdecode_node** (bdecode\_node const&);
	**bdecode_node** (bdecode\_node&&) noexcept;
	bdecode_node& **operator=** (bdecode\_node&&) & = default;
	bdecode_node& **operator=** (bdecode\_node const&) &;
	

For owning nodes, the copy will create a copy of the tree, but the
underlying buffer remains the same.



.. raw:: html

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

.. raw:: html

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



type()
......

.. parsed-literal::
	
	type_t **type** () const noexcept;
	

the type of this node. See `type_t`__.


__ reference-Torrent_Info.html#type_t

.. raw:: html

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

.. raw:: html

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



bool()
......

.. parsed-literal::
	
	explicit operator **bool** () const noexcept;
	

returns true if `type()`__ != none_t.


__ reference-Plugins.html#type()

.. raw:: html

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

.. raw:: html

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



non_owning()
............

.. parsed-literal::
	
	bdecode_node **non_owning** () const;
	

return a non-owning reference to this node. This is useful to refer to
the root node without copying it in assignments.



.. raw:: html

	<a name="data_offset()"></a>
	<a name="data_section()"></a>

.. raw:: html

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



data_offset() data_section()
............................

.. parsed-literal::
	
	span<char const> **data_section** () const noexcept;
	std::ptrdiff_t **data_offset** () const noexcept;
	

returns the buffer and length of the section in the original bencoded
buffer where this node is defined. For a dictionary for instance, this
starts with ``d`` and ends with ``e``, and has all the content of the
dictionary in between.
the ``data_offset()`` function returns the byte-offset to this node in,
starting from the beginning of the buffer that was parsed.



.. raw:: html

	<a name="list_string_value_at()"></a>
	<a name="list_int_value_at()"></a>
	<a name="list_at()"></a>
	<a name="list_size()"></a>

.. raw:: html

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



list_string_value_at() list_int_value_at() list_at() list_size()
................................................................

.. parsed-literal::
	
	std::int64_t **list_int_value_at** (int i
	      , std\:\:int64\_t default\_val = 0) const;
	bdecode_node **list_at** (int i) const;
	string_view **list_string_value_at** (int i
	      , string\_view default\_val = string\_view()) const;
	int **list_size** () const;
	

functions with the ``list_`` prefix operate on lists. These functions are
only valid if ``type()`` == ``list_t``. ``list_at()`` returns the item
in the list at index ``i``. ``i`` may not be greater than or equal to the
size of the list. ``size()`` returns the size of the list.



.. raw:: html

	<a name="dict_size()"></a>
	<a name="dict_find_list()"></a>
	<a name="dict_find_int()"></a>
	<a name="dict_find_int_value()"></a>
	<a name="dict_find_string()"></a>
	<a name="dict_at_node()"></a>
	<a name="dict_find()"></a>
	<a name="dict_at()"></a>
	<a name="dict_find_dict()"></a>
	<a name="dict_find_string_value()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:bdecode_node%3A%3A%5Bdict_size%28%29+dict_find_list%28%29+dict_find_int%28%29+dict_find_int_value%28%29+dict_find_string%28%29+dict_at_node%28%29+dict_find%28%29+dict_at%28%29+dict_find_dict%28%29+dict_find_string_value%28%29%5D&labels=documentation&body=Documentation+under+heading+%22bdecode_node%3A%3A%5Bdict_size%28%29+dict_find_list%28%29+dict_find_int%28%29+dict_find_int_value%28%29+dict_find_string%28%29+dict_at_node%28%29+dict_find%28%29+dict_at%28%29+dict_find_dict%28%29+dict_find_string_value%28%29%5D%22+could+be+improved">report issue</a>]</span>



dict_size() dict_find_list() dict_find_int() dict_find_int_value() dict_find_string() dict_at_node() dict_find() dict_at() dict_find_dict() dict_find_string_value()
....................................................................................................................................................................

.. parsed-literal::
	
	bdecode_node **dict_find_dict** (string\_view key) const;
	std::pair<string_view, bdecode_node> **dict_at** (int i) const;
	int **dict_size** () const;
	bdecode_node **dict_find_list** (string\_view key) const;
	bdecode_node **dict_find_int** (string\_view key) const;
	std::pair<bdecode_node, bdecode_node> **dict_at_node** (int i) const;
	bdecode_node **dict_find** (string\_view key) const;
	std::int64_t **dict_find_int_value** (string\_view key
	      , std\:\:int64\_t default\_val = 0) const;
	bdecode_node **dict_find_string** (string\_view key) const;
	string_view **dict_find_string_value** (string\_view key
	      , string\_view default\_value = string\_view()) const;
	

Functions with the ``dict_`` prefix operates on dictionaries. They are
only valid if ``type()`` == ``dict_t``. In case a key you're looking up
contains a 0 byte, you cannot use the 0-terminated string overloads,
but have to use ``string_view`` instead. ``dict_find_list`` will return a
valid ``bdecode_node`` if the key is found _and_ it is a list. Otherwise
it will return a default-constructed `bdecode_node`__.

Functions with the ``_value`` suffix return the value of the node
directly, rather than the nodes. In case the node is not found, or it has
a different type, a default value is returned (which can be specified).

``dict_at()`` returns the (key, value)-pair at the specified index in a
dictionary. Keys are only allowed to be strings. ``dict_at_node()`` also
returns the (key, value)-pair, but the key is returned as a
``bdecode_node`` (and it will always be a string).


__ reference-Bdecoding.html#bdecode_node

.. raw:: html

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

.. raw:: html

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



int_value()
...........

.. parsed-literal::
	
	std::int64_t **int_value** () const;
	

this function is only valid if ``type()`` == ``int_t``. It returns the
value of the integer.



.. raw:: html

	<a name="string_ptr()"></a>
	<a name="string_offset()"></a>
	<a name="string_length()"></a>
	<a name="string_value()"></a>

.. raw:: html

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



string_ptr() string_offset() string_length() string_value()
...........................................................

.. parsed-literal::
	
	int **string_length** () const;
	char const* **string_ptr** () const;
	string_view **string_value** () const;
	std::ptrdiff_t **string_offset** () const;
	

these functions are only valid if ``type()`` == ``string_t``. They return
the string values. Note that ``string_ptr()`` is *not* 0-terminated.
``string_length()`` returns the number of bytes in the string.
``string_offset()`` returns the byte offset from the start of the parsed
bencoded buffer this string can be found.



.. raw:: html

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

.. raw:: html

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



clear()
.......

.. parsed-literal::
	
	void **clear** ();
	

resets the ``bdecoded_node`` to a default constructed state. If this is
an owning node, the tree is freed and all child nodes are invalidated.



.. raw:: html

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

.. raw:: html

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



swap()
......

.. parsed-literal::
	
	void **swap** (bdecode\_node& n);
	

Swap contents.



.. raw:: html

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

.. raw:: html

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



reserve()
.........

.. parsed-literal::
	
	void **reserve** (int tokens);
	

preallocate memory for the specified numbers of tokens. This is
useful if you know approximately how many tokens are in the file
you are about to parse. Doing so will save realloc operations
while parsing. You should only call this on the root node, before
passing it in to `bdecode()`__.


__ reference-Bdecoding.html#bdecode()

.. raw:: html

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

.. raw:: html

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



switch_underlying_buffer()
..........................

.. parsed-literal::
	
	void **switch_underlying_buffer** (char const\* buf) noexcept;
	

this buffer *MUST* be identical to the one originally parsed. This
operation is only defined on owning root nodes, i.e. the one passed in to
decode().



.. raw:: html

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

.. raw:: html

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



has_soft_error()
................

.. parsed-literal::
	
	bool **has_soft_error** (span<char> error) const;
	

returns true if there is a non-fatal error in the bencoding of this node
or its children



.. raw:: html

	<a name="type_t"></a>

.. raw:: html

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



enum type_t
...........

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


__ include/libtorrent/bdecode.hpp

+----------+-------+------------------------------------------------------------+
| name     | value | description                                                |
+==========+=======+============================================================+
| none_t   | 0     | uninitialized or default constructed. This is also used    |
|          |       | to indicate that a node was not found in some cases.       |
|          |       |                                                            |
+----------+-------+------------------------------------------------------------+
| dict_t   | 1     | a dictionary node. The ``dict_find_`` functions are valid. |
|          |       |                                                            |
+----------+-------+------------------------------------------------------------+
| list_t   | 2     | a list node. The ``list_`` functions are valid.            |
|          |       |                                                            |
+----------+-------+------------------------------------------------------------+
| string_t | 3     | a string node, the ``string_`` functions are valid.        |
|          |       |                                                            |
+----------+-------+------------------------------------------------------------+
| int_t    | 4     | an integer node. The ``int_`` functions are valid.         |
|          |       |                                                            |
+----------+-------+------------------------------------------------------------+



.. raw:: html

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

.. raw:: html

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



print_entry()
-------------

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


__ include/libtorrent/bdecode.hpp

.. parsed-literal::
	
	std::string **print_entry** (bdecode\_node const& e
	   , bool single\_line = false, int indent = 0);
	

print the bencoded structure in a human-readable format to a string
that's returned.



.. raw:: html

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

.. raw:: html

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



bdecode()
---------

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


__ include/libtorrent/bdecode.hpp

.. parsed-literal::
	
	bdecode_node **bdecode** (span<char const> buffer
	   , int depth\_limit = 100, int token\_limit = 2000000);
	int **bdecode** (char const\* start, char const\* end, bdecode\_node& ret
	   , error\_code& ec, int\* error\_pos = nullptr, int depth\_limit = 100
	   , int token\_limit = 2000000);
	bdecode_node **bdecode** (span<char const> buffer
	   , error\_code& ec, int\* error\_pos = nullptr, int depth\_limit = 100
	   , int token\_limit = 2000000);
	

This function decodes/parses bdecoded data (for example a .torrent file).
The data structure is returned in the ``ret`` argument. the buffer to parse
is specified by the ``start`` of the buffer as well as the ``end``, i.e. one
byte past the end. If the buffer fails to parse, the function returns a
non-zero value and fills in ``ec`` with the error code. The optional
argument ``error_pos``, if set to non-nullptr, will be set to the byte offset
into the buffer where the parse failure occurred.

``depth_limit`` specifies the max number of nested lists or dictionaries are
allowed in the data structure. (This affects the stack usage of the
function, be careful not to set it too high).

``token_limit`` is the max number of tokens allowed to be parsed from the
buffer. This is simply a sanity check to not have unbounded memory usage.

The resulting ``bdecode_node`` is an *owning* node. That means it will
be holding the whole parsed tree. When iterating lists and dictionaries,
those ``bdecode_node`` objects will simply have references to the root or
owning ``bdecode_node``. If the root node is destructed, all other nodes
that refer to anything in that tree become invalid.

However, the underlying buffer passed in to this function (``start``, ``end``)
must also remain valid while the bdecoded tree is used. The parsed tree
produced by this function does not copy any data out of the buffer, but
simply produces references back into it.





.. _`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
