name.hpp

Go to the documentation of this file.

/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
 * Copyright (c) 2013-2024 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_NAME_HPP
#define NDN_CXX_NAME_HPP
 
#include "ndn-cxx/name-component.hpp"
 
#include <iterator>
#include <limits>
#include <optional>
 
namespace ndn {
 
class Name;
 
using PartialName = Name;
 
class Name : private boost::totally_ordered<Name>
{
public: // nested types
  using Component = name::Component;
  using Error = Component::Error;
 
  // Name appears as an ordered sequence of name components
  using value_type             = Component;
  using allocator_type         = void;
  using reference              = Component&;
  using const_reference        = const Component&;
  using pointer                = Component*;
  using const_pointer          = const Component*;
  using iterator               = const Component*; // disallow modifying via iterator
  using const_iterator         = const Component*;
  using reverse_iterator       = std::reverse_iterator<iterator>;
  using const_reverse_iterator = std::reverse_iterator<const_iterator>;
  using difference_type        = std::vector<Component>::difference_type;
  using size_type              = std::vector<Component>::size_type;
 
public: // constructors, encoding, decoding
  Name();
 
  explicit
  Name(const Block& wire);
 
  explicit
  Name(std::string_view uri);
 
  Name(const char* uri)
    : Name(std::string_view(uri))
  {
  }
 
  Name(const std::string& uri)
    : Name(std::string_view(uri))
  {
  }
 
  void
  toUri(std::ostream& os, name::UriFormat format = name::UriFormat::DEFAULT) const;
 
  std::string
  toUri(name::UriFormat format = name::UriFormat::DEFAULT) const;
 
  bool
  hasWire() const noexcept
  {
    return m_wire.hasWire();
  }
 
  template<encoding::Tag TAG>
  size_t
  wireEncode(EncodingImpl<TAG>& encoder) const;
 
  const Block&
  wireEncode() const;
 
  void
  wireDecode(const Block& wire);
 
  Name
  deepCopy() const;
 
public: // access
  [[nodiscard]] bool
  empty() const noexcept
  {
    return m_wire.elements().empty();
  }
 
  size_t
  size() const noexcept
  {
    return m_wire.elements_size();
  }
 
  const Component&
  get(ssize_t i) const noexcept
  {
    if (i < 0) {
      i += static_cast<ssize_t>(size());
    }
    return static_cast<const Component&>(m_wire.elements()[static_cast<size_t>(i)]);
  }
 
  const Component&
  operator[](ssize_t i) const noexcept
  {
    return get(i);
  }
 
  const Component&
  at(ssize_t i) const;
 
  PartialName
  getSubName(ssize_t iStartComponent, size_t nComponents = npos) const;
 
  PartialName
  getPrefix(ssize_t nComponents) const
  {
    if (nComponents < 0)
      return getSubName(0, size() + nComponents);
    else
      return getSubName(0, nComponents);
  }
 
public: // iterators
  const_iterator
  begin() const noexcept
  {
    return reinterpret_cast<const_iterator>(m_wire.elements().data());
  }
 
  const_iterator
  end() const noexcept
  {
    return reinterpret_cast<const_iterator>(m_wire.elements().data() + m_wire.elements().size());
  }
 
  const_reverse_iterator
  rbegin() const noexcept
  {
    return const_reverse_iterator(end());
  }
 
  const_reverse_iterator
  rend() const noexcept
  {
    return const_reverse_iterator(begin());
  }
 
public: // modifiers
  Name&
  set(ssize_t i, const Component& component);
 
  Name&
  set(ssize_t i, Component&& component);
 
  Name&
  append(const Component& component)
  {
    m_wire.push_back(component);
    return *this;
  }
 
  Name&
  append(Component&& component)
  {
    m_wire.push_back(std::move(component));
    return *this;
  }
 
  Name&
  append(uint32_t type, span<const uint8_t> value)
  {
    return append(Component(type, value));
  }
 
  Name&
  append(span<const uint8_t> value)
  {
    return append(Component(tlv::GenericNameComponent, value));
  }
 
  template<class Iterator>
  Name&
  append(uint32_t type, Iterator first, Iterator last)
  {
    return append(Component(type, first, last));
  }
 
  template<class Iterator>
  Name&
  append(Iterator first, Iterator last)
  {
    return append(Component(tlv::GenericNameComponent, first, last));
  }
 
  Name&
  append(const char* str)
  {
    return append(Component(str));
  }
 
  Name&
  append(const PartialName& name);
 
  Name&
  appendNumber(uint64_t number)
  {
    return append(Component::fromNumber(number));
  }
 
  Name&
  appendNumberWithMarker(uint8_t marker, uint64_t number)
  {
    return append(Component::fromNumberWithMarker(marker, number));
  }
 
  Name&
  appendSegment(uint64_t segmentNo)
  {
    return append(Component::fromSegment(segmentNo));
  }
 
  Name&
  appendByteOffset(uint64_t offset)
  {
    return append(Component::fromByteOffset(offset));
  }
 
  Name&
  appendVersion(const std::optional<uint64_t>& version = std::nullopt);
 
  Name&
  appendTimestamp(const std::optional<time::system_clock::time_point>& timestamp = std::nullopt);
 
  Name&
  appendSequenceNumber(uint64_t seqNo)
  {
    return append(Component::fromSequenceNumber(seqNo));
  }
 
  Name&
  appendImplicitSha256Digest(ConstBufferPtr digest)
  {
    return append(Component(tlv::ImplicitSha256DigestComponent, std::move(digest)));
  }
 
  Name&
  appendImplicitSha256Digest(span<const uint8_t> digestBytes)
  {
    return append(Component(tlv::ImplicitSha256DigestComponent, digestBytes));
  }
 
  Name&
  appendParametersSha256Digest(ConstBufferPtr digest)
  {
    return append(Component(tlv::ParametersSha256DigestComponent, std::move(digest)));
  }
 
  Name&
  appendParametersSha256Digest(span<const uint8_t> digestBytes)
  {
    return append(Component(tlv::ParametersSha256DigestComponent, digestBytes));
  }
 
  Name&
  appendParametersSha256DigestPlaceholder();
 
  Name&
  appendKeyword(span<const uint8_t> keyword)
  {
    return append(Component(tlv::KeywordNameComponent, keyword));
  }
 
  Name&
  appendKeyword(std::string_view keyword)
  {
    return append(Component(tlv::KeywordNameComponent,
                            {reinterpret_cast<const uint8_t*>(keyword.data()), keyword.size()}));
  }
 
  void
  erase(ssize_t i);
 
  void
  clear();
 
public: // algorithms
  Name
  getSuccessor() const;
 
  bool
  isPrefixOf(const Name& other) const noexcept;
 
  bool
  equals(const Name& other) const noexcept;
 
  int
  compare(const Name& other) const
  {
    return this->compare(0, npos, other);
  }
 
  int
  compare(size_t pos1, size_t count1,
          const Name& other, size_t pos2 = 0, size_t count2 = npos) const;
 
private: // non-member operators
  // NOTE: the following "hidden friend" operators are available via
  //       argument-dependent lookup only and must be defined inline.
  // boost::totally_ordered provides !=, <=, >=, and > operators.
 
  friend bool
  operator==(const Name& lhs, const Name& rhs) noexcept
  {
    return lhs.equals(rhs);
  }
 
  friend bool
  operator<(const Name& lhs, const Name& rhs)
  {
    return lhs.compare(rhs) < 0;
  }
 
  friend std::ostream&
  operator<<(std::ostream& os, const Name& name)
  {
    name.toUri(os);
    return os;
  }
 
public:
  static constexpr size_t npos = std::numeric_limits<size_t>::max();
 
private:
  mutable Block m_wire{tlv::Name};
};
 
NDN_CXX_DECLARE_WIRE_ENCODE_INSTANTIATIONS(Name);
 
std::istream&
operator>>(std::istream& is, Name& name);
 
} // namespace ndn
 
namespace std {
 
template<>
struct hash<ndn::Name>
{
  size_t
  operator()(const ndn::Name& name) const;
};
 
} // namespace std
 
#endif // NDN_CXX_NAME_HPP