block-helpers.hpp

Go to the documentation of this file.

/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
 * Copyright (c) 2013-2022 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.
 */
 
#ifndef NDN_CXX_ENCODING_BLOCK_HELPERS_HPP
#define NDN_CXX_ENCODING_BLOCK_HELPERS_HPP
 
#include "ndn-cxx/encoding/block.hpp"
#include "ndn-cxx/encoding/encoding-buffer.hpp"
#include "ndn-cxx/util/concepts.hpp"
 
namespace ndn {
namespace encoding {
 
template<Tag TAG>
size_t
prependNonNegativeIntegerBlock(EncodingImpl<TAG>& encoder, uint32_t type, uint64_t value);
 
extern template size_t
prependNonNegativeIntegerBlock<EstimatorTag>(EncodingImpl<EstimatorTag>&, uint32_t, uint64_t);
 
extern template size_t
prependNonNegativeIntegerBlock<EncoderTag>(EncodingImpl<EncoderTag>&, uint32_t, uint64_t);
 
Block
makeNonNegativeIntegerBlock(uint32_t type, uint64_t value);
 
uint64_t
readNonNegativeInteger(const Block& block);
 
template<typename R>
std::enable_if_t<std::is_integral<R>::value, R>
readNonNegativeIntegerAs(const Block& block)
{
  uint64_t value = readNonNegativeInteger(block);
  if (value > std::numeric_limits<R>::max()) {
    NDN_THROW(tlv::Error("Value in TLV element of type " + to_string(block.type()) + " is too large"));
  }
  return static_cast<R>(value);
}
 
template<typename R>
std::enable_if_t<std::is_enum<R>::value, R>
readNonNegativeIntegerAs(const Block& block)
{
  return static_cast<R>(readNonNegativeIntegerAs<std::underlying_type_t<R>>(block));
}
 
template<Tag TAG>
size_t
prependEmptyBlock(EncodingImpl<TAG>& encoder, uint32_t type);
 
extern template size_t
prependEmptyBlock<EstimatorTag>(EncodingImpl<EstimatorTag>&, uint32_t);
 
extern template size_t
prependEmptyBlock<EncoderTag>(EncodingImpl<EncoderTag>&, uint32_t);
 
Block
makeEmptyBlock(uint32_t type);
 
template<Tag TAG>
size_t
prependStringBlock(EncodingImpl<TAG>& encoder, uint32_t type, const std::string& value);
 
extern template size_t
prependStringBlock<EstimatorTag>(EncodingImpl<EstimatorTag>&, uint32_t, const std::string&);
 
extern template size_t
prependStringBlock<EncoderTag>(EncodingImpl<EncoderTag>&, uint32_t, const std::string&);
 
Block
makeStringBlock(uint32_t type, const std::string& value);
 
std::string
readString(const Block& block);
 
template<Tag TAG>
size_t
prependDoubleBlock(EncodingImpl<TAG>& encoder, uint32_t type, double value);
 
extern template size_t
prependDoubleBlock<EstimatorTag>(EncodingImpl<EstimatorTag>&, uint32_t, double);
 
extern template size_t
prependDoubleBlock<EncoderTag>(EncodingImpl<EncoderTag>&, uint32_t, double);
 
Block
makeDoubleBlock(uint32_t type, double value);
 
double
readDouble(const Block& block);
 
template<Tag TAG>
size_t
prependBinaryBlock(EncodingImpl<TAG>& encoder, uint32_t type, span<const uint8_t> value);
 
extern template size_t
prependBinaryBlock<EstimatorTag>(EncodingImpl<EstimatorTag>&, uint32_t, span<const uint8_t>);
 
extern template size_t
prependBinaryBlock<EncoderTag>(EncodingImpl<EncoderTag>&, uint32_t, span<const uint8_t>);
 
Block
makeBinaryBlock(uint32_t type, span<const uint8_t> value);
 
[[deprecated("use the overload that takes a span<>")]]
inline Block
makeBinaryBlock(uint32_t type, const uint8_t* value, size_t length)
{
  return makeBinaryBlock(type, {value, length});
}
 
inline Block
makeBinaryBlock(uint32_t type, const char* value, size_t length)
{
  return makeBinaryBlock(type, {reinterpret_cast<const uint8_t*>(value), length});
}
 
namespace detail {
 
template<class Iterator>
class BinaryBlockFast
{
public:
  BOOST_CONCEPT_ASSERT((boost::RandomAccessIterator<Iterator>));
 
  static Block
  makeBlock(uint32_t type, Iterator first, Iterator last)
  {
    EncodingEstimator estimator;
    size_t valueLength = last - first;
    size_t totalLength = valueLength;
    totalLength += estimator.prependVarNumber(valueLength);
    totalLength += estimator.prependVarNumber(type);
 
    EncodingBuffer encoder(totalLength, 0);
    encoder.prependRange(first, last);
    encoder.prependVarNumber(valueLength);
    encoder.prependVarNumber(type);
 
    return encoder.block();
  }
};
 
template<class Iterator>
class BinaryBlockSlow
{
public:
  BOOST_CONCEPT_ASSERT((boost::InputIterator<Iterator>));
 
  static Block
  makeBlock(uint32_t type, Iterator first, Iterator last)
  {
    // reserve 4 bytes in front (common for 1(type)-3(length) encoding
    // Actual size will be adjusted as necessary by the encoder
    EncodingBuffer encoder(4, 4);
    size_t valueLength = encoder.appendRange(first, last);
    encoder.prependVarNumber(valueLength);
    encoder.prependVarNumber(type);
 
    return encoder.block();
  }
};
 
} // namespace detail
 
template<class Iterator>
Block
makeBinaryBlock(uint32_t type, Iterator first, Iterator last)
{
  using BinaryBlockHelper = std::conditional_t<
    std::is_base_of<std::random_access_iterator_tag,
                    typename std::iterator_traits<Iterator>::iterator_category>::value,
    detail::BinaryBlockFast<Iterator>,
    detail::BinaryBlockSlow<Iterator>>;
 
  return BinaryBlockHelper::makeBlock(type, first, last);
}
 
template<Tag TAG>
size_t
prependBlock(EncodingImpl<TAG>& encoder, const Block& block);
 
extern template size_t
prependBlock<EstimatorTag>(EncodingImpl<EstimatorTag>&, const Block&);
 
extern template size_t
prependBlock<EncoderTag>(EncodingImpl<EncoderTag>&, const Block&);
 
template<Tag TAG, class U>
size_t
prependNestedBlock(EncodingImpl<TAG>& encoder, uint32_t type, const U& value)
{
  BOOST_CONCEPT_ASSERT((WireEncodableWithEncodingBuffer<U>));
 
  size_t length = value.wireEncode(encoder);
  length += encoder.prependVarNumber(length);
  length += encoder.prependVarNumber(type);
  return length;
}
 
template<class U>
Block
makeNestedBlock(uint32_t type, const U& value)
{
  EncodingEstimator estimator;
  size_t totalLength = prependNestedBlock(estimator, type, value);
 
  EncodingBuffer encoder(totalLength, 0);
  prependNestedBlock(encoder, type, value);
  return encoder.block();
}
 
template<Tag TAG, class I>
size_t
prependNestedBlock(EncodingImpl<TAG>& encoder, uint32_t type, I first, I last)
{
  BOOST_CONCEPT_ASSERT((WireEncodableWithEncodingBuffer<typename std::iterator_traits<I>::value_type>));
 
  auto rfirst = std::make_reverse_iterator(last);
  auto rlast = std::make_reverse_iterator(first);
 
  size_t length = 0;
  for (auto i = rfirst; i != rlast; ++i) {
    length += i->wireEncode(encoder);
  }
 
  length += encoder.prependVarNumber(length);
  length += encoder.prependVarNumber(type);
  return length;
}
 
template<class I>
Block
makeNestedBlock(uint32_t type, I first, I last)
{
  EncodingEstimator estimator;
  size_t totalLength = prependNestedBlock(estimator, type, first, last);
 
  EncodingBuffer encoder(totalLength, 0);
  prependNestedBlock(encoder, type, first, last);
  return encoder.block();
}
 
} // namespace encoding
 
using encoding::makeNonNegativeIntegerBlock;
using encoding::readNonNegativeInteger;
using encoding::readNonNegativeIntegerAs;
using encoding::makeEmptyBlock;
using encoding::makeStringBlock;
using encoding::readString;
using encoding::makeBinaryBlock;
using encoding::makeNestedBlock;
 
} // namespace ndn
 
#endif // NDN_CXX_ENCODING_BLOCK_HELPERS_HPP