block.hpp

Go to the documentation of this file.

/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
 * Copyright (c) 2013-2023 Regents of the University of California.
 *
 * This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
 *
 * ndn-cxx library is free software: you can redistribute it and/or modify it under the
 * terms of the GNU Lesser General Public License as published by the Free Software
 * Foundation, either version 3 of the License, or (at your option) any later version.
 *
 * ndn-cxx library is distributed in the hope that it will be useful, but WITHOUT ANY
 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
 * PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
 *
 * You should have received copies of the GNU General Public License and GNU Lesser
 * General Public License along with ndn-cxx, e.g., in COPYING.md file.  If not, see
 * <http://www.gnu.org/licenses/>.
 *
 * See AUTHORS.md for complete list of ndn-cxx authors and contributors.
 *
 * @author Alexander Afanasyev <http://lasr.cs.ucla.edu/afanasyev/index.html>
 */
 
#ifndef NDN_CXX_ENCODING_BLOCK_HPP
#define NDN_CXX_ENCODING_BLOCK_HPP
 
#include "ndn-cxx/encoding/buffer.hpp"
#include "ndn-cxx/encoding/encoding-buffer-fwd.hpp"
#include "ndn-cxx/encoding/tlv.hpp"
#include "ndn-cxx/util/span.hpp"
 
#include <boost/operators.hpp>
 
namespace boost::asio {
class const_buffer;
} // namespace boost::asio
 
namespace ndn {
 
class Block : private boost::equality_comparable<Block>
{
public:
  using value_type             = Buffer::value_type;
  using const_iterator         = Buffer::const_iterator;
  using element_container      = std::vector<Block>;
  using element_iterator       = element_container::iterator;
  using element_const_iterator = element_container::const_iterator;
 
  class Error : public tlv::Error
  {
  public:
    using tlv::Error::Error;
  };
 
public: // construction, assignment
  Block();
 
  Block(const Block&);
 
  Block&
  operator=(const Block&);
 
  Block(Block&&) noexcept;
 
  Block&
  operator=(Block&&) noexcept;
 
  explicit
  Block(span<const uint8_t> buffer);
 
  explicit
  Block(const EncodingBuffer& buffer);
 
  explicit
  Block(const ConstBufferPtr& buffer);
 
  Block(ConstBufferPtr buffer, Buffer::const_iterator begin, Buffer::const_iterator end,
        bool verifyLength = true);
 
  Block(const Block& block, Block::const_iterator begin, Block::const_iterator end,
        bool verifyLength = true);
 
  Block(ConstBufferPtr buffer, uint32_t type,
        Buffer::const_iterator begin, Buffer::const_iterator end,
        Buffer::const_iterator valueBegin, Buffer::const_iterator valueEnd);
 
  explicit
  Block(uint32_t type);
 
  Block(uint32_t type, ConstBufferPtr value);
 
  Block(uint32_t type, const Block& value);
 
  [[nodiscard]] static std::tuple<bool, Block>
  fromBuffer(ConstBufferPtr buffer, size_t offset = 0);
 
  [[nodiscard]] static std::tuple<bool, Block>
  fromBuffer(span<const uint8_t> buffer);
 
  static Block
  fromStream(std::istream& is);
 
public: // wire format
  bool
  isValid() const noexcept
  {
    return m_type != tlv::Invalid;
  }
 
  bool
  hasWire() const noexcept
  {
    return m_buffer != nullptr && m_begin != m_end;
  }
 
  const uint8_t*
  data() const;
 
  size_t
  size() const;
 
  const_iterator
  begin() const;
 
  const_iterator
  end() const;
 
  ConstBufferPtr
  getBuffer() const
  {
    return m_buffer;
  }
 
  void
  reset() noexcept;
 
  void
  resetWire() noexcept;
 
public: // type and value
  uint32_t
  type() const noexcept
  {
    return m_type;
  }
 
  bool
  hasValue() const noexcept
  {
    return m_buffer != nullptr;
  }
 
  size_t
  value_size() const noexcept
  {
    return hasValue() ? static_cast<size_t>(m_valueEnd - m_valueBegin) : 0;
  }
 
  span<const uint8_t>
  value_bytes() const noexcept
  {
    if (hasValue())
      return {m_valueBegin, m_valueEnd};
    else
      return {};
  }
 
  const uint8_t*
  value() const noexcept;
 
  const_iterator
  value_begin() const noexcept
  {
    return m_valueBegin;
  }
 
  const_iterator
  value_end() const noexcept
  {
    return m_valueEnd;
  }
 
  Block
  blockFromValue() const;
 
public: // sub-elements
  void
  parse() const;
 
  void
  encode();
 
  const Block&
  get(uint32_t type) const;
 
  element_const_iterator
  find(uint32_t type) const;
 
  void
  remove(uint32_t type);
 
  element_iterator
  erase(element_const_iterator position);
 
  element_iterator
  erase(element_const_iterator first, element_const_iterator last);
 
  void
  push_back(const Block& element);
 
  void
  push_back(Block&& element);
 
  element_iterator
  insert(element_const_iterator pos, const Block& element);
 
  const element_container&
  elements() const noexcept
  {
    return m_elements;
  }
 
  element_const_iterator
  elements_begin() const noexcept
  {
    return m_elements.begin();
  }
 
  element_const_iterator
  elements_end() const noexcept
  {
    return m_elements.end();
  }
 
  size_t
  elements_size() const noexcept
  {
    return m_elements.size();
  }
 
public: // misc
  operator boost::asio::const_buffer() const;
 
private:
  size_t
  encode(EncodingEstimator& estimator) const;
 
  size_t
  encodeValue(EncodingEstimator& estimator) const;
 
  size_t
  encode(EncodingBuffer& encoder);
 
  bool
  equals(const Block& other) const noexcept;
 
  void
  print(std::ostream& os) const;
 
private: // non-member operators
  // NOTE: the following "hidden friend" operators are available via
  //       argument-dependent lookup only and must be defined inline.
  // boost::equality_comparable provides != operator.
 
  friend bool
  operator==(const Block& lhs, const Block& rhs) noexcept
  {
    return lhs.equals(rhs);
  }
 
  friend std::ostream&
  operator<<(std::ostream& os, const Block& block)
  {
    block.print(os);
    return os;
  }
 
protected:
  shared_ptr<const Buffer> m_buffer;
  Buffer::const_iterator m_begin; 
  Buffer::const_iterator m_end; 
 
  Buffer::const_iterator m_valueBegin; 
  Buffer::const_iterator m_valueEnd; 
 
  uint32_t m_type = tlv::Invalid; 
 
  size_t m_size = 0;
 
  mutable element_container m_elements;
};
 
inline
Block::Block(Block&&) noexcept = default;
 
inline Block&
Block::operator=(Block&&) noexcept = default;
 
inline namespace literals {
inline namespace block_literals {
 
Block
operator ""_block(const char* input, std::size_t len);
 
} // inline namespace block_literals
} // inline namespace literals
} // namespace ndn
 
#endif // NDN_CXX_ENCODING_BLOCK_HPP