name-component.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_COMPONENT_HPP
#define NDN_CXX_NAME_COMPONENT_HPP
 
#include "ndn-cxx/encoding/block.hpp"
#include "ndn-cxx/encoding/block-helpers.hpp"
#include "ndn-cxx/util/time.hpp"
 
namespace ndn {
namespace name {
 
enum class UriFormat {
  CANONICAL,
  ALTERNATE,
  ENV_OR_CANONICAL,
  ENV_OR_ALTERNATE,
  DEFAULT = ENV_OR_ALTERNATE,
};
 
enum class Convention {
  MARKER = 1 << 0, 
  TYPED  = 1 << 1, 
  EITHER = MARKER | TYPED,
};
 
enum : uint8_t {
  SEGMENT_MARKER = 0x00,
  SEGMENT_OFFSET_MARKER = 0xFB,
  VERSION_MARKER = 0xFD,
  TIMESTAMP_MARKER = 0xFC,
  SEQUENCE_NUMBER_MARKER = 0xFE,
};
 
Convention
getConventionEncoding() noexcept;
 
void
setConventionEncoding(Convention convention);
 
Convention
getConventionDecoding() noexcept;
 
void
setConventionDecoding(Convention convention);
 
class Component : public Block
{
public:
  class Error : public Block::Error
  {
  public:
    using Block::Error::Error;
  };
 
public: // constructors
  explicit
  Component(uint32_t type = tlv::GenericNameComponent);
 
  explicit
  Component(const Block& block);
 
  Component(uint32_t type, ConstBufferPtr buffer);
 
  explicit
  Component(ConstBufferPtr buffer)
    : Component(tlv::GenericNameComponent, std::move(buffer))
  {
  }
 
  Component(uint32_t type, span<const uint8_t> value);
 
  explicit
  Component(span<const uint8_t> buffer)
    : Component(tlv::GenericNameComponent, buffer)
  {
  }
 
  [[deprecated("use the constructor that takes a span<>")]]
  Component(uint32_t type, const uint8_t* value, size_t count)
    : Component(type, {value, count})
  {
  }
 
  [[deprecated("use the constructor that takes a span<>")]]
  Component(const uint8_t* value, size_t count)
    : Component(tlv::GenericNameComponent, {value, count})
  {
  }
 
  template<class Iterator>
  Component(uint32_t type, Iterator first, Iterator last)
    : Block(makeBinaryBlock(type, first, last))
  {
  }
 
  template<class Iterator>
  Component(Iterator first, Iterator last)
    : Component(tlv::GenericNameComponent, first, last)
  {
  }
 
  explicit
  Component(const char* str);
 
  explicit
  Component(const std::string& str);
 
public: // encoding and URI
  template<encoding::Tag TAG>
  size_t
  wireEncode(EncodingImpl<TAG>& encoder) const;
 
  const Block&
  wireEncode() const;
 
  void
  wireDecode(const Block& wire);
 
  static Component
  fromEscapedString(const char* input, size_t beginOffset, size_t endOffset)
  {
    return fromEscapedString(std::string(input + beginOffset, input + endOffset));
  }
 
  static Component
  fromEscapedString(const char* input)
  {
    return fromEscapedString(std::string(input));
  }
 
  static Component
  fromEscapedString(const std::string& input);
 
  void
  toUri(std::ostream& os, UriFormat format = UriFormat::DEFAULT) const;
 
  std::string
  toUri(UriFormat format = UriFormat::DEFAULT) const;
 
public: // naming conventions
  bool
  isNumber() const noexcept;
 
  bool
  isNumberWithMarker(uint8_t marker) const noexcept;
 
  bool
  isSegment() const noexcept;
 
  bool
  isByteOffset() const noexcept;
 
  bool
  isVersion() const noexcept;
 
  bool
  isTimestamp() const noexcept;
 
  bool
  isSequenceNumber() const noexcept;
 
  uint64_t
  toNumber() const;
 
  uint64_t
  toNumberWithMarker(uint8_t marker) const;
 
  uint64_t
  toSegment() const;
 
  uint64_t
  toByteOffset() const;
 
  uint64_t
  toVersion() const;
 
  time::system_clock::time_point
  toTimestamp() const;
 
  uint64_t
  toSequenceNumber() const;
 
  static Component
  fromNumber(uint64_t number, uint32_t type = tlv::GenericNameComponent);
 
  static Component
  fromNumberWithMarker(uint8_t marker, uint64_t number);
 
  static Component
  fromSegment(uint64_t segmentNo);
 
  static Component
  fromByteOffset(uint64_t offset);
 
  static Component
  fromVersion(uint64_t version);
 
  static Component
  fromTimestamp(const time::system_clock::time_point& timePoint);
 
  static Component
  fromSequenceNumber(uint64_t seqNo);
 
public: // commonly used TLV-TYPEs
  bool
  isGeneric() const noexcept
  {
    return type() == tlv::GenericNameComponent;
  }
 
  bool
  isImplicitSha256Digest() const noexcept;
 
  [[deprecated("use one of the name::Component constructors")]]
  static Component
  fromImplicitSha256Digest(ConstBufferPtr digest);
 
  [[deprecated("use one of the name::Component constructors")]]
  static Component
  fromImplicitSha256Digest(span<const uint8_t> digest);
 
  bool
  isParametersSha256Digest() const noexcept;
 
  [[deprecated("use one of the name::Component constructors")]]
  static Component
  fromParametersSha256Digest(ConstBufferPtr digest);
 
  [[deprecated("use one of the name::Component constructors")]]
  static Component
  fromParametersSha256Digest(span<const uint8_t> digest);
 
  bool
  isKeyword() const noexcept
  {
    return type() == tlv::KeywordNameComponent;
  }
 
public: // comparison
  NDN_CXX_NODISCARD bool
  empty() const noexcept
  {
    return value_size() == 0;
  }
 
  bool
  equals(const Component& other) const noexcept;
 
  int
  compare(const Component& other) const;
 
  Component
  getSuccessor() const;
 
private:
  void
  ensureValid() 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 Component& lhs, const Component& rhs) noexcept
  {
    return lhs.equals(rhs);
  }
 
  friend bool
  operator!=(const Component& lhs, const Component& rhs) noexcept
  {
    return !lhs.equals(rhs);
  }
 
  friend bool
  operator<(const Component& lhs, const Component& rhs)
  {
    return lhs.compare(rhs) < 0;
  }
 
  friend bool
  operator<=(const Component& lhs, const Component& rhs)
  {
    return lhs.compare(rhs) <= 0;
  }
 
  friend bool
  operator>(const Component& lhs, const Component& rhs)
  {
    return lhs.compare(rhs) > 0;
  }
 
  friend bool
  operator>=(const Component& lhs, const Component& rhs)
  {
    return lhs.compare(rhs) >= 0;
  }
 
  friend std::ostream&
  operator<<(std::ostream& os, const Component& component)
  {
    component.toUri(os);
    return os;
  }
 
  // !!! NOTE TO IMPLEMENTOR !!!
  //
  // This class MUST NOT contain any data fields.
  // Block can be reinterpret_cast'ed as Component type.
};
 
NDN_CXX_DECLARE_WIRE_ENCODE_INSTANTIATIONS(Component);
 
} // namespace name
} // namespace ndn
 
#endif // NDN_CXX_NAME_COMPONENT_HPP