name.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_NAME_HPP
#define NDN_CXX_NAME_HPP

#include "ndn-cxx/name-component.hpp"
#include "ndn-cxx/util/optional.hpp"

#include <iterator>

namespace ndn {

class Name;

using PartialName = Name;

class Name
{
public: // nested types
  using Error = name::Component::Error;

  using Component = name::Component;
  using component_container = std::vector<Component>;

  // Name appears as a container 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        = component_container::difference_type;
  using size_type              = component_container::size_type;

public: // constructors, encoding, decoding
  Name();

  explicit
  Name(const Block& wire);

  Name(const char* uri);

  Name(std::string 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
  NDN_CXX_NODISCARD bool
  empty() const
  {
    return m_wire.elements().empty();
  }

  size_t
  size() const
  {
    return m_wire.elements_size();
  }

  const Component&
  get(ssize_t i) const
  {
    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
  {
    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
  {
    return reinterpret_cast<const_iterator>(m_wire.elements().data());
  }

  const_iterator
  end() const
  {
    return reinterpret_cast<const_iterator>(m_wire.elements().data() + m_wire.elements().size());
  }

  const_reverse_iterator
  rbegin() const
  {
    return const_reverse_iterator(end());
  }

  const_reverse_iterator
  rend() const
  {
    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));
  }

  [[deprecated("use the overload that takes a span<>")]]
  Name&
  append(uint32_t type, const uint8_t* value, size_t count)
  {
    return append(type, make_span(value, count));
  }

  [[deprecated("use the overload that takes a span<>")]]
  Name&
  append(const uint8_t* value, size_t count)
  {
    return append(make_span(value, count));
  }

  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 optional<uint64_t>& version = nullopt);

  Name&
  appendTimestamp(const optional<time::system_clock::time_point>& timestamp = 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(const char* keyword)
  {
    return append(Component(tlv::KeywordNameComponent, {reinterpret_cast<const uint8_t*>(keyword),
                                                        std::char_traits<char>::length(keyword)}));
  }

  template<class T>
  void
  push_back(const T& component)
  {
    append(component);
  }

  void
  erase(ssize_t i);

  void
  clear();

public: // algorithms
  Name
  getSuccessor() const;

  bool
  isPrefixOf(const Name& other) const;

  bool
  equals(const Name& other) const;

  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.

  friend bool
  operator==(const Name& lhs, const Name& rhs)
  {
    return lhs.equals(rhs);
  }

  friend bool
  operator!=(const Name& lhs, const Name& rhs)
  {
    return !lhs.equals(rhs);
  }

  friend bool
  operator<(const Name& lhs, const Name& rhs)
  {
    return lhs.compare(rhs) < 0;
  }

  friend bool
  operator<=(const Name& lhs, const Name& rhs)
  {
    return lhs.compare(rhs) <= 0;
  }

  friend bool
  operator>(const Name& lhs, const Name& rhs)
  {
    return lhs.compare(rhs) > 0;
  }

  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 const size_t npos;

private:
  mutable Block m_wire;
};

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