| libtorrent

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

home

# Utility

Table of contents

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

## bitfield

Declared in "libtorrent/bitfield.hpp"

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

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

### bitfield()

    bitfield (int bits);
    bitfield (bitfield const& rhs);
    bitfield (bitfield&& rhs);
    bitfield (int bits, bool val);
    bitfield ();
    bitfield (char const* b, int bits);

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).

### assign()

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

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

### operator[]()

    bool operator[] (int index) const;

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

### set_bit() clear_bit()

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

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

### all_set()

    bool all_set () const;

returns true if all bits in the bitfield are set

### size()

    int size () const;

returns the size of the bitfield in bits.

### empty()

    bool empty () const;

returns true if the bitfield has zero size.

### data()

    char const* data () const;

returns a pointer to the internal buffer of the bitfield.

### operator=()

    bitfield& operator= (bitfield const& rhs);

copy operator

### count()

    int count () const;

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

## 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 sha1-algorithm used was implemented by Steve Reid and released as public domain. For more info, see `src/sha1.cpp`.

    class hasher
    {
       hasher ();
       hasher (const char* data, int len);
       hasher& operator= (hasher const& h);
       hasher (hasher const& h);
       hasher& update (std::string const& data);
       hasher& update (const char* data, int len);
       sha1_hash final ();
       void reset ();
       ~hasher ();
    };

### hasher()

    hasher (const char* data, int len);

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

### update()

    hasher& update (std::string const& data);
    hasher& update (const char* data, int len);

append the following bytes to what is being hashed

### final()

    sha1_hash final ();

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

### reset()

    void reset ();

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

## sha1_hash

Declared in "libtorrent/sha1_hash.hpp"

This type holds a SHA-1 digest or any other kind of 20 byte sequence. It implements a number of convenience functions, such as bit operations, comparison operators etc.

In libtorrent it is primarily used to hold info-hashes, piece-hashes, peer IDs, node IDs etc.

    class sha1_hash
    {
       sha1_hash ();
       static sha1_hash max ();
       static sha1_hash min ();
       explicit sha1_hash (char const* s);
       void assign (char const* str);
       explicit sha1_hash (std::string const& s);
       void assign (std::string const& s);
       char* data ();
       char const* data () const;
       void clear ();
       bool is_all_zeros () const;
       sha1_hash& operator<<= (int n);
       sha1_hash& operator>>= (int n);
       bool operator!= (sha1_hash const& n) const;
       bool operator< (sha1_hash const& n) const;
       bool operator== (sha1_hash const& n) const;
       sha1_hash operator~ () const;
       sha1_hash operator^ (sha1_hash const& n) const;
       sha1_hash& operator^= (sha1_hash const& n);
       sha1_hash operator& (sha1_hash const& n) const;
       sha1_hash& operator&= (sha1_hash const& n);
       sha1_hash& operator|= (sha1_hash const& n);
       boost::uint8_t& operator[] (int i);
       boost::uint8_t const& operator[] (int i) const;
       const_iterator begin () const;
       iterator begin ();
       iterator end ();
       const_iterator end () const;
       std::string to_string () const;
    };

### sha1_hash()

    sha1_hash ();

constructs an all-zero sha1-hash

### max()

    static sha1_hash max ();

returns an all-F sha1-hash. i.e. the maximum value representable by a 160 bit number (20 bytes). This is a static member function.

### min()

    static sha1_hash min ();

returns an all-zero sha1-hash. i.e. the minimum value representable by a 160 bit number (20 bytes). This is a static member function.

### assign() sha1_hash()

    explicit sha1_hash (char const* s);
    void assign (char const* str);
    explicit sha1_hash (std::string const& s);
    void assign (std::string const& s);

copies 20 bytes from the pointer provided, into the sha1-hash. The passed in string MUST be at least 20 bytes. NULL terminators are ignored, `s` is treated like a raw memory buffer.

### clear()

    void clear ();

set the sha1-hash to all zeros.

### is_all_zeros()

    bool is_all_zeros () const;

return true if the sha1-hash is all zero.

### operator<<=()

    sha1_hash& operator<<= (int n);

shift left `n` bits.

### operator>>=()

    sha1_hash& operator>>= (int n);

shift r `n` bits.

### operator!=() operator<() operator==()

    bool operator!= (sha1_hash const& n) const;
    bool operator< (sha1_hash const& n) const;
    bool operator== (sha1_hash const& n) const;

standard comparison operators

### operator~()

    sha1_hash operator~ () const;

returns a bit-wise negated copy of the sha1-hash

### operator^()

    sha1_hash operator^ (sha1_hash const& n) const;

returns the bit-wise XOR of the two sha1-hashes.

### operator^=()

    sha1_hash& operator^= (sha1_hash const& n);

in-place bit-wise XOR with the passed in sha1_hash.

### operator&()

    sha1_hash operator& (sha1_hash const& n) const;

returns the bit-wise AND of the two sha1-hashes.

### operator&=()

    sha1_hash& operator&= (sha1_hash const& n);

in-place bit-wise AND of the passed in sha1_hash

### operator|=()

    sha1_hash& operator|= (sha1_hash const& n);

in-place bit-wise OR of the two sha1-hash.

### operator[]()

    boost::uint8_t& operator[] (int i);
    boost::uint8_t const& operator[] (int i) const;

accessors for specific bytes

### begin() end()

    const_iterator begin () const;
    iterator begin ();
    iterator end ();
    const_iterator end () const;

start and end iterators for the hash. The value type of these iterators is `boost::uint8_t`.

### to_string()

    std::string to_string () const;

return a copy of the 20 bytes representing the sha1-hash as a std::string. It's still a binary string with 20 binary characters.

## hash_value()

Declared in "libtorrent/sha1_hash.hpp"

    inline std::size_t hash_value (sha1_hash const& b);

## operator<<()

Declared in "libtorrent/sha1_hash.hpp"

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

print a sha1_hash object to an ostream as 40 hexadecimal digits

## operator>>()

Declared in "libtorrent/sha1_hash.hpp"

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

read 40 hexadecimal digits from an istream into a sha1_hash