mirror of
https://github.com/XRPLF/rippled.git
synced 2026-06-03 08:46:46 +00:00
88794a1ea9
Bulk documentation pass covering 702 C++ source files in src/libxrpl, src/xrpld, and include/xrpl. Adds class, function, parameter, and invariant docs per docs/DOCUMENTATION_STANDARDS.md. Squashed from the original three-part series (part 1 / part 2 / part 3) to avoid merge-conflict noise when rebasing the work onto current develop.
410 lines
12 KiB
C++
410 lines
12 KiB
C++
/** @file
|
|
* Declares STVector256, the serialized type for ordered lists of uint256 values.
|
|
*
|
|
* On the wire the array is encoded as a single VL-prefixed blob of concatenated
|
|
* 32-byte hashes (type identifier STI_VECTOR256, code 19). Common ledger fields
|
|
* that use this type include sfAmendments, sfIndexes, and sfHashes.
|
|
*/
|
|
|
|
#pragma once
|
|
|
|
#include <xrpl/basics/CountedObject.h>
|
|
#include <xrpl/protocol/STBase.h>
|
|
#include <xrpl/protocol/STBitString.h>
|
|
#include <xrpl/protocol/STInteger.h>
|
|
|
|
namespace xrpl {
|
|
|
|
/** Serialized type for an ordered list of 256-bit hash values.
|
|
*
|
|
* Wraps a `std::vector<uint256>` with the `STBase` contract so that hash
|
|
* collections can be stored as named, typed fields inside `STObject` —
|
|
* giving them a wire-format identity (`STI_VECTOR256`, code 19), a
|
|
* canonical binary encoding (VL-prefixed blob of packed 32-byte values),
|
|
* and a JSON representation (array of hex strings). Typical ledger uses
|
|
* include `sfAmendments` (active amendments in a validator vote),
|
|
* `sfIndexes` (keys in a `DirectoryNode` page), and `sfHashes`.
|
|
*
|
|
* An empty `STVector256` is the canonical default state and is omitted from
|
|
* the wire encoding when the field is declared optional.
|
|
*
|
|
* The `CountedObject<STVector256>` mixin adds lock-free instance counting
|
|
* for diagnostic purposes, with no overhead in the fast path.
|
|
*/
|
|
class STVector256 : public STBase, public CountedObject<STVector256>
|
|
{
|
|
std::vector<uint256> value_;
|
|
|
|
public:
|
|
/** Reference type used when this value is passed as a read-only handle. */
|
|
using value_type = std::vector<uint256> const&;
|
|
|
|
/** Construct an empty, unnamed STVector256. */
|
|
STVector256() = default;
|
|
|
|
/** Construct an empty STVector256 bound to the given field name.
|
|
*
|
|
* @param n The SField that identifies this field in its parent STObject.
|
|
*/
|
|
explicit STVector256(SField const& n);
|
|
|
|
/** Construct an unnamed STVector256 pre-populated with @p vector.
|
|
*
|
|
* @param vector Initial contents; copied into the internal store.
|
|
*/
|
|
explicit STVector256(std::vector<uint256> const& vector);
|
|
|
|
/** Construct an STVector256 bound to @p n and pre-populated with @p vector.
|
|
*
|
|
* @param n The SField that identifies this field in its parent STObject.
|
|
* @param vector Initial contents; copied into the internal store.
|
|
*/
|
|
STVector256(SField const& n, std::vector<uint256> const& vector);
|
|
|
|
/** Deserialize an STVector256 from a wire-format stream.
|
|
*
|
|
* Reads a single VL-prefixed blob from @p sit and partitions it into
|
|
* consecutive 32-byte chunks, each becoming one `uint256` entry. The
|
|
* resulting vector retains the original wire order.
|
|
*
|
|
* @param sit Forward-only iterator positioned at the VL length prefix of
|
|
* the field. Consumed by exactly one VL-length + slice read pair.
|
|
* @param name The SField that identifies this field within its parent STObject.
|
|
* @throws std::runtime_error if the decoded blob length is not an exact
|
|
* multiple of 32 bytes, indicating corrupt or truncated data.
|
|
*/
|
|
STVector256(SerialIter& sit, SField const& name);
|
|
|
|
/** Return the serialized type identifier for this field.
|
|
*
|
|
* @return `STI_VECTOR256` (code 19).
|
|
*/
|
|
[[nodiscard]] SerializedTypeID
|
|
getSType() const override;
|
|
|
|
/** Serialize this array into @p s as a VL-prefixed blob.
|
|
*
|
|
* Writes a length prefix followed by the concatenated raw bytes of each
|
|
* `uint256` entry (32 bytes per element, no padding or separators).
|
|
*
|
|
* @param s Accumulator to append the encoded field into.
|
|
* @note Asserts (debug builds only) that the associated SField is marked
|
|
* binary and carries type `STI_VECTOR256`. These guards catch accidental
|
|
* field-type mismatches before data reaches the wire.
|
|
*/
|
|
void
|
|
add(Serializer& s) const override;
|
|
|
|
/** Produce a JSON array of hex-encoded hash strings.
|
|
*
|
|
* Each `uint256` entry is rendered as a lowercase hex string via
|
|
* `to_string()`. The @p options parameter is accepted for interface
|
|
* conformance but is unused; the representation is identical across
|
|
* all API versions.
|
|
*
|
|
* @return A `json::arrayValue` with one hex string per entry.
|
|
*/
|
|
[[nodiscard]] json::Value getJson(JsonOptions) const override;
|
|
|
|
/** Test deep equality with another STBase instance.
|
|
*
|
|
* Two `STVector256` objects are equivalent when they contain the same
|
|
* sequence of `uint256` values in the same order.
|
|
*
|
|
* @param t The object to compare against.
|
|
* @return `true` if @p t is an `STVector256` with identical contents;
|
|
* `false` if the types differ or the sequences do not match.
|
|
*/
|
|
[[nodiscard]] bool
|
|
isEquivalent(STBase const& t) const override;
|
|
|
|
/** Return whether this object holds no entries.
|
|
*
|
|
* An empty `STVector256` is the canonical default value. Per XRPL
|
|
* serialization rules, default-valued optional fields are omitted from
|
|
* the wire encoding and contribute nothing to a transaction or ledger hash.
|
|
*
|
|
* @return `true` if the internal vector is empty.
|
|
*/
|
|
[[nodiscard]] bool
|
|
isDefault() const override;
|
|
|
|
/** Replace the contents with a copy of @p v.
|
|
*
|
|
* @param v Source vector; copied into the internal store.
|
|
* @return Reference to this object.
|
|
*/
|
|
STVector256&
|
|
operator=(std::vector<uint256> const& v);
|
|
|
|
/** Replace the contents by moving @p v into the internal store.
|
|
*
|
|
* @param v Source vector; left in a valid but unspecified state after the call.
|
|
* @return Reference to this object.
|
|
*/
|
|
STVector256&
|
|
operator=(std::vector<uint256>&& v);
|
|
|
|
/** Copy the inner vector from @p v, leaving the SField name unchanged.
|
|
*
|
|
* Unlike `operator=`, this copies only the payload (`mValue`), not the
|
|
* field binding. Use this when you need to transfer values between two
|
|
* fields that have different SField identities.
|
|
*
|
|
* @param v Source object whose contents are copied.
|
|
*/
|
|
void
|
|
setValue(STVector256 const& v);
|
|
|
|
/** Return a copy of the internal vector.
|
|
*
|
|
* Marked `explicit` to prevent accidental implicit copies in generic
|
|
* contexts; prefer `value()` for read-only access.
|
|
*/
|
|
explicit
|
|
operator std::vector<uint256>() const;
|
|
|
|
/** Return the number of entries in the vector.
|
|
*
|
|
* @return Entry count; 0 for an empty (default) object.
|
|
*/
|
|
[[nodiscard]] std::size_t
|
|
size() const;
|
|
|
|
/** Resize the internal vector to @p n entries.
|
|
*
|
|
* New entries (if any) are value-initialized to the zero `uint256`.
|
|
*
|
|
* @param n Target size.
|
|
*/
|
|
void
|
|
resize(std::size_t n);
|
|
|
|
/** Return whether the vector contains no entries.
|
|
*
|
|
* @return `true` if `size() == 0`.
|
|
*/
|
|
[[nodiscard]] bool
|
|
empty() const;
|
|
|
|
/** Return a mutable reference to the entry at index @p n.
|
|
*
|
|
* @param n Zero-based index; behavior is undefined if out of range.
|
|
*/
|
|
std::vector<uint256>::reference
|
|
operator[](std::vector<uint256>::size_type n);
|
|
|
|
/** Return a read-only reference to the entry at index @p n.
|
|
*
|
|
* @param n Zero-based index; behavior is undefined if out of range.
|
|
*/
|
|
std::vector<uint256>::const_reference
|
|
operator[](std::vector<uint256>::size_type n) const;
|
|
|
|
/** Return a read-only reference to the internal vector.
|
|
*
|
|
* Prefer this over the explicit conversion operator for non-owning access.
|
|
*
|
|
* @return Const reference to the underlying `std::vector<uint256>`.
|
|
*/
|
|
[[nodiscard]] std::vector<uint256> const&
|
|
value() const;
|
|
|
|
/** Insert @p value before @p pos.
|
|
*
|
|
* @param pos Iterator before which the new element is inserted.
|
|
* @param value Hash to insert.
|
|
* @return Iterator to the inserted element.
|
|
*/
|
|
std::vector<uint256>::iterator
|
|
insert(std::vector<uint256>::const_iterator pos, uint256 const& value);
|
|
|
|
/** Append @p v to the end of the vector.
|
|
*
|
|
* @param v Hash to append.
|
|
*/
|
|
void
|
|
pushBack(uint256 const& v);
|
|
|
|
/** Return a mutable iterator to the first element. */
|
|
std::vector<uint256>::iterator
|
|
begin();
|
|
|
|
/** Return a read-only iterator to the first element. */
|
|
[[nodiscard]] std::vector<uint256>::const_iterator
|
|
begin() const;
|
|
|
|
/** Return a mutable past-the-end iterator. */
|
|
std::vector<uint256>::iterator
|
|
end();
|
|
|
|
/** Return a read-only past-the-end iterator. */
|
|
[[nodiscard]] std::vector<uint256>::const_iterator
|
|
end() const;
|
|
|
|
/** Remove the element at @p position.
|
|
*
|
|
* @param position Iterator to the element to remove.
|
|
* @return Iterator to the element following the removed one.
|
|
*/
|
|
std::vector<uint256>::iterator
|
|
erase(std::vector<uint256>::iterator position);
|
|
|
|
/** Remove all entries, leaving the vector empty. */
|
|
void
|
|
clear() noexcept;
|
|
|
|
private:
|
|
/** Copy this object into a caller-supplied buffer via the STVar placement protocol.
|
|
*
|
|
* Called only by `detail::STVar`. Delegates to `STBase::emplace`, which
|
|
* constructs in-place when @p buf is large enough, or heap-allocates otherwise.
|
|
*
|
|
* @param n Size of the buffer at @p buf, in bytes.
|
|
* @param buf Destination buffer for placement construction.
|
|
* @return Pointer to the newly constructed `STVector256`.
|
|
*/
|
|
STBase*
|
|
copy(std::size_t n, void* buf) const override;
|
|
|
|
/** Move this object into a caller-supplied buffer via the STVar placement protocol.
|
|
*
|
|
* Called only by `detail::STVar`. Delegates to `STBase::emplace`, which
|
|
* constructs in-place when @p buf is large enough, or heap-allocates otherwise.
|
|
* The source is left in a valid but unspecified state.
|
|
*
|
|
* @param n Size of the buffer at @p buf, in bytes.
|
|
* @param buf Destination buffer for placement construction.
|
|
* @return Pointer to the newly constructed `STVector256`.
|
|
*/
|
|
STBase*
|
|
move(std::size_t n, void* buf) override;
|
|
|
|
friend class detail::STVar;
|
|
};
|
|
|
|
inline STVector256::STVector256(SField const& n) : STBase(n)
|
|
{
|
|
}
|
|
|
|
inline STVector256::STVector256(std::vector<uint256> const& vector) : value_(vector)
|
|
{
|
|
}
|
|
|
|
inline STVector256::STVector256(SField const& n, std::vector<uint256> const& vector)
|
|
: STBase(n), value_(vector)
|
|
{
|
|
}
|
|
|
|
inline STVector256&
|
|
STVector256::operator=(std::vector<uint256> const& v)
|
|
{
|
|
value_ = v;
|
|
return *this;
|
|
}
|
|
|
|
inline STVector256&
|
|
STVector256::operator=(std::vector<uint256>&& v)
|
|
{
|
|
value_ = std::move(v);
|
|
return *this;
|
|
}
|
|
|
|
inline void
|
|
STVector256::setValue(STVector256 const& v)
|
|
{
|
|
value_ = v.value_;
|
|
}
|
|
|
|
inline STVector256::
|
|
operator std::vector<uint256>() const
|
|
{
|
|
return value_;
|
|
}
|
|
|
|
inline std::size_t
|
|
STVector256::size() const
|
|
{
|
|
return value_.size();
|
|
}
|
|
|
|
inline void
|
|
STVector256::resize(std::size_t n)
|
|
{
|
|
value_.resize(n);
|
|
}
|
|
|
|
inline bool
|
|
STVector256::empty() const
|
|
{
|
|
return value_.empty();
|
|
}
|
|
|
|
inline std::vector<uint256>::reference
|
|
STVector256::operator[](std::vector<uint256>::size_type n)
|
|
{
|
|
return value_[n];
|
|
}
|
|
|
|
inline std::vector<uint256>::const_reference
|
|
STVector256::operator[](std::vector<uint256>::size_type n) const
|
|
{
|
|
return value_[n];
|
|
}
|
|
|
|
inline std::vector<uint256> const&
|
|
STVector256::value() const
|
|
{
|
|
return value_;
|
|
}
|
|
|
|
inline std::vector<uint256>::iterator
|
|
STVector256::insert(std::vector<uint256>::const_iterator pos, uint256 const& value)
|
|
{
|
|
return value_.insert(pos, value);
|
|
}
|
|
|
|
inline void
|
|
STVector256::pushBack(uint256 const& v)
|
|
{
|
|
value_.push_back(v);
|
|
}
|
|
|
|
inline std::vector<uint256>::iterator
|
|
STVector256::begin()
|
|
{
|
|
return value_.begin();
|
|
}
|
|
|
|
inline std::vector<uint256>::const_iterator
|
|
STVector256::begin() const
|
|
{
|
|
return value_.begin();
|
|
}
|
|
|
|
inline std::vector<uint256>::iterator
|
|
STVector256::end()
|
|
{
|
|
return value_.end();
|
|
}
|
|
|
|
inline std::vector<uint256>::const_iterator
|
|
STVector256::end() const
|
|
{
|
|
return value_.end();
|
|
}
|
|
|
|
inline std::vector<uint256>::iterator
|
|
STVector256::erase(std::vector<uint256>::iterator position)
|
|
{
|
|
return value_.erase(position);
|
|
}
|
|
|
|
inline void
|
|
STVector256::clear() noexcept
|
|
{
|
|
value_.clear();
|
|
}
|
|
|
|
} // namespace xrpl
|