| libtorrent

# Utility

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

Table of contents

- bitfield
- sha1_hash

# bitfield

Declared in "libtorrent/bitfield.hpp"

The bitfiled type stores any number of bits as a bitfield in a heap allocated or borrowed 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 borrow_bytes (char* b, int bits);
       void assign (char const* b, int bits);
       bool get_bit (int index) const;
       bool operator[] (int index) const;
       void clear_bit (int index);
       void set_bit (int index);
       bool all_set () const;
       int size () const;
       bool empty () const;
       char const* bytes () 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 boundry).

## borrow_bytes()

    void borrow_bytes (char* b, int bits);

assigns a bitfield pointed to `b` of `bits` number of bits, without taking ownership of the buffer. This is a way to avoid copying data and yet provide a raw buffer to functions that may operate on the bitfield type. It is the user's responsibility to make sure the passed-in buffer's life time exceeds all uses of the bitfield.

## 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[]() get_bit()

    bool get_bit (int index) const;
    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.

## bytes()

    char const* bytes () 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.

# 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);
       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~ ();
       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);
       unsigned char& operator[] (int i);
       unsigned char const& operator[] (int i) const;
       const_iterator begin () const;
       iterator begin ();
       iterator end ();
       const_iterator end () const;
       std::string to_string () const;

       static const int size = number_size;
    };

## sha1_hash()

    sha1_hash ();

constructs an all-sero 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 zeroes.

## 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~ ();

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[]()

    unsigned char& operator[] (int i);
    unsigned char 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 `unsigned char`.

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

number_size
  the number of bytes of the number

## identify_client()

Declared in "libtorrent/identify_client.hpp"

    std::string identify_client (const peer_id& p);

This function can can be used to extract a string describing a client version from its peer-id. It will recognize most clients that have this kind of identification in the peer-id.

## client_fingerprint()

Declared in "libtorrent/identify_client.hpp"

    boost::optional<fingerprint> client_fingerprint (peer_id const& p);

Returns an optional fingerprint if any can be identified from the peer id. This can be used to automate the identification of clients. It will not be able to identify peers with non- standard encodings. Only Azureus style, Shadow's style and Mainline style.

## 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

## sleep()

Declared in "libtorrent/thread.hpp"

    void sleep (int milliseconds);

pauses the calling thread at least for the specified number of milliseconds