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/detail/common.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();

void
setConventionEncoding(Convention convention);

Convention
getConventionDecoding();

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;

  bool
  isNumberWithMarker(uint8_t marker) const;

  bool
  isSegment() const;

  bool
  isByteOffset() const;

  bool
  isVersion() const;

  bool
  isTimestamp() const;

  bool
  isSequenceNumber() const;

  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;

  [[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;

  [[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
  {
    return value_size() == 0;
  }

  bool
  equals(const Component& other) const;

  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)
  {
    return lhs.equals(rhs);
  }

  friend bool
  operator!=(const Component& lhs, const Component& rhs)
  {
    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