| libtorrent

Author: | Arvid Norberg, arvid@libtorrent.org
Version: | 1.2.16

home

# Utility

Table of contents

- Utility
  - hasher
  - bitfield
  - operator<<()
  - operator>>()

[report issue]

## hasher

Declared in "libtorrent/hasher.hpp"

this is a SHA-1 hash class.

You use it by first instantiating it, then call `update()` to feed it with data. i.e. you don't have to keep the entire buffer of which you want to create the hash in memory. You can feed the hasher parts of it at a time. When You have fed the hasher with all the data, you call `final()` and it will return the sha1-hash of the data.

The constructor that takes a `char const*` and an integer will construct the sha1 context and feed it the data passed in.

If you want to reuse the hasher object once you have created a hash, you have to call `reset()` to reinitialize it.

The built-in software version of sha1-algorithm was implemented by Steve Reid and released as public domain. For more info, see `src/sha1.cpp`.

    class hasher
    {
       hasher ();
       explicit hasher (span<char const> data);
       hasher& operator= (hasher const&) &;
       hasher (hasher const&);
       hasher (char const* data, int len);
       hasher& update (char const* data, int len);
       hasher& update (span<char const> data);
       sha1_hash final ();
       void reset ();
    };

[report issue]

### hasher() operator=()

    explicit hasher (span<char const> data);
    hasher& operator= (hasher const&) &;
    hasher (hasher const&);
    hasher (char const* data, int len);

this is the same as default constructing followed by a call to `update(data, len)`.

[report issue]

### update()

    hasher& update (char const* data, int len);
    hasher& update (span<char const> data);

append the following bytes to what is being hashed

[report issue]

### final()

    sha1_hash final ();

returns the SHA-1 digest of the buffers previously passed to update() and the hasher constructor.

[report issue]

### reset()

    void reset ();

restore the hasher state to be as if the hasher has just been default constructed.

[report issue]

## bitfield

Declared in "libtorrent/bitfield.hpp"

The bitfield type stores any number of bits as a bitfield in a heap allocated array.

    struct bitfield
    {
       explicit bitfield (int bits);
       bitfield (int bits, bool val);
       bitfield (bitfield&& rhs) noexcept = default;
       bitfield (char const* b, int bits);
       bitfield () noexcept = default;
       bitfield (bitfield const& rhs);
       void assign (char const* b, int const bits);
       bool operator[] (int index) const noexcept;
       bool get_bit (int index) const noexcept;
       void clear_bit (int index) noexcept;
       void set_bit (int index) noexcept;
       bool all_set () const noexcept;
       bool none_set () const noexcept;
       int size () const noexcept;
       int num_words () const noexcept;
       bool empty () const noexcept;
       char* data () noexcept;
       char const* data () const noexcept;
       void swap (bitfield& rhs) noexcept;
       int count () const noexcept;
       int find_first_set () const noexcept;
       int find_last_clear () const noexcept;
    };

[report issue]

### bitfield()

    explicit bitfield (int bits);
    bitfield (int bits, bool val);
    bitfield (bitfield&& rhs) noexcept = default;
    bitfield (char const* b, int bits);
    bitfield () noexcept = default;
    bitfield (bitfield const& rhs);

constructs a new bitfield. The default constructor creates an empty bitfield. `bits` is the size of the bitfield (specified in bits). `val` is the value to initialize the bits to. If not specified all bits are initialized to 0.

The constructor taking a pointer `b` and `bits` copies a bitfield from the specified buffer, and `bits` number of bits (rounded up to the nearest byte boundary).

[report issue]

### assign()

    void assign (char const* b, int const bits);

copy bitfield from buffer `b` of `bits` number of bits, rounded up to the nearest byte boundary.

[report issue]

### get_bit() operator[]()

    bool operator[] (int index) const noexcept;
    bool get_bit (int index) const noexcept;

query bit at `index`. Returns true if bit is 1, otherwise false.

[report issue]

### set_bit() clear_bit()

    void clear_bit (int index) noexcept;
    void set_bit (int index) noexcept;

set bit at `index` to 0 (clear_bit) or 1 (set_bit).

[report issue]

### all_set()

    bool all_set () const noexcept;

returns true if all bits in the bitfield are set

[report issue]

### none_set()

    bool none_set () const noexcept;

returns true if no bit in the bitfield is set

[report issue]

### size()

    int size () const noexcept;

returns the size of the bitfield in bits.

[report issue]

### num_words()

    int num_words () const noexcept;

returns the number of 32 bit words are needed to represent all bits in this bitfield.

[report issue]

### empty()

    bool empty () const noexcept;

returns true if the bitfield has zero size.

[report issue]

### data()

    char* data () noexcept;
    char const* data () const noexcept;

returns a pointer to the internal buffer of the bitfield, or `nullptr` if it's empty.

[report issue]

### swap()

    void swap (bitfield& rhs) noexcept;

swaps the bit-fields two variables refer to

[report issue]

### count()

    int count () const noexcept;

count the number of bits in the bitfield that are set to 1.

[report issue]

### find_first_set()

    int find_first_set () const noexcept;

returns the index of the first set bit in the bitfield, i.e. 1 bit.

[report issue]

### find_last_clear()

    int find_last_clear () const noexcept;

returns the index to the last cleared bit in the bitfield, i.e. 0 bit.

[report issue]

## operator<<()

Declared in "libtorrent/sha1_hash.hpp"

    std::ostream& operator<< (std::ostream& os, sha1_hash const& peer);

print a sha1_hash object to an ostream as 40 hexadecimal digits

[report issue]

## operator>>()

Declared in "libtorrent/sha1_hash.hpp"

    std::istream& operator>> (std::istream& is, sha1_hash& peer);

read 40 hexadecimal digits from an istream into a sha1_hash