name-component.hpp
Go to the documentation of this file.
1 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
2 /*
3  * Copyright (c) 2013-2024 Regents of the University of California.
4  *
5  * This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
6  *
7  * ndn-cxx library is free software: you can redistribute it and/or modify it under the
8  * terms of the GNU Lesser General Public License as published by the Free Software
9  * Foundation, either version 3 of the License, or (at your option) any later version.
10  *
11  * ndn-cxx library is distributed in the hope that it will be useful, but WITHOUT ANY
12  * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
13  * PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
14  *
15  * You should have received copies of the GNU General Public License and GNU Lesser
16  * General Public License along with ndn-cxx, e.g., in COPYING.md file. If not, see
17  * <http://www.gnu.org/licenses/>.
18  *
19  * See AUTHORS.md for complete list of ndn-cxx authors and contributors.
20  */
21 
22 #ifndef NDN_CXX_NAME_COMPONENT_HPP
23 #define NDN_CXX_NAME_COMPONENT_HPP
24 
27 #include "ndn-cxx/util/time.hpp"
28 
29 namespace ndn::name {
30 
35 enum class UriFormat {
37  CANONICAL,
39  ALTERNATE,
46 };
47 
52 enum class Convention {
53  MARKER = 1 << 0,
54  TYPED = 1 << 1,
55  EITHER = MARKER | TYPED,
56 };
57 
62 enum : uint8_t {
68 };
69 
76 getConventionEncoding() noexcept;
77 
82 void
84 
91 getConventionDecoding() noexcept;
92 
98 void
100 
112 class Component : public Block, private boost::less_than_comparable<Component>
113 {
114 public:
115  class Error : public Block::Error
116  {
117  public:
118  using Block::Error::Error;
119  };
120 
121 public: // constructors
126  explicit
127  Component(uint32_t type = tlv::GenericNameComponent);
128 
133  explicit
134  Component(const Block& block);
135 
144  Component(uint32_t type, ConstBufferPtr buffer);
145 
154  explicit
156  : Component(tlv::GenericNameComponent, std::move(buffer))
157  {
158  }
159 
163  Component(uint32_t type, span<const uint8_t> value);
164 
168  explicit
169  Component(span<const uint8_t> value)
170  : Component(tlv::GenericNameComponent, value)
171  {
172  }
173 
182  template<class Iterator>
183  Component(uint32_t type, Iterator first, Iterator last)
184  : Block(makeBinaryBlock(type, first, last))
185  {
186  }
187 
191  template<class Iterator>
192  Component(Iterator first, Iterator last)
193  : Component(tlv::GenericNameComponent, first, last)
194  {
195  }
196 
202  explicit
203  Component(std::string_view str);
204 
205 public: // encoding and URI
209  template<encoding::Tag TAG>
210  size_t
211  wireEncode(EncodingImpl<TAG>& encoder) const;
212 
216  const Block&
217  wireEncode() const;
218 
222  void
223  wireDecode(const Block& wire);
224 
230  static Component
231  fromUri(std::string_view input);
232 
233  [[deprecated("use fromUri")]]
234  static Component
235  fromEscapedString(std::string_view input)
236  {
237  return Component::fromUri(input);
238  }
239 
244  void
245  toUri(std::ostream& os, UriFormat format = UriFormat::DEFAULT) const;
246 
251  std::string
252  toUri(UriFormat format = UriFormat::DEFAULT) const;
253 
254 public: // naming conventions
259  bool
260  isNumber() const noexcept;
261 
267  bool
268  isNumberWithMarker(uint8_t marker) const noexcept;
269 
274  bool
275  isSegment() const noexcept;
276 
281  bool
282  isByteOffset() const noexcept;
283 
288  bool
289  isVersion() const noexcept;
290 
295  bool
296  isTimestamp() const noexcept;
297 
302  bool
303  isSequenceNumber() const noexcept;
304 
310  uint64_t
311  toNumber() const;
312 
324  uint64_t
325  toNumberWithMarker(uint8_t marker) const;
326 
332  uint64_t
333  toSegment() const;
334 
340  uint64_t
341  toByteOffset() const;
342 
348  uint64_t
349  toVersion() const;
350 
356  time::system_clock::time_point
357  toTimestamp() const;
358 
364  uint64_t
365  toSequenceNumber() const;
366 
375  static Component
376  fromNumber(uint64_t number, uint32_t type = tlv::GenericNameComponent);
377 
395  static Component
396  fromNumberWithMarker(uint8_t marker, uint64_t number);
397 
402  static Component
403  fromSegment(uint64_t segmentNo);
404 
409  static Component
410  fromByteOffset(uint64_t offset);
411 
416  static Component
417  fromVersion(uint64_t version);
418 
423  static Component
424  fromTimestamp(const time::system_clock::time_point& timePoint);
425 
430  static Component
431  fromSequenceNumber(uint64_t seqNo);
432 
433 public: // commonly used TLV-TYPEs
438  bool
439  isGeneric() const noexcept
440  {
441  return type() == tlv::GenericNameComponent;
442  }
443 
449  bool
450  isImplicitSha256Digest() const noexcept;
451 
457  bool
458  isParametersSha256Digest() const noexcept;
459 
464  bool
465  isKeyword() const noexcept
466  {
467  return type() == tlv::KeywordNameComponent;
468  }
469 
470 public: // comparison
471  [[nodiscard]] bool
472  empty() const noexcept
473  {
474  return value_size() == 0;
475  }
476 
487  int
488  compare(const Component& other) const;
489 
515  Component
516  getSuccessor() const;
517 
518 private:
522  void
523  ensureValid() const;
524 
525 private: // non-member operators
526  // NOTE: the following "hidden friend" operators are available via
527  // argument-dependent lookup only and must be defined inline.
528  // Block provides == and != operators.
529  // boost::less_than_comparable provides <=, >=, and > operators.
530 
531  friend bool
532  operator<(const Component& lhs, const Component& rhs)
533  {
534  return lhs.compare(rhs) < 0;
535  }
536 
537  friend std::ostream&
538  operator<<(std::ostream& os, const Component& component)
539  {
540  component.toUri(os);
541  return os;
542  }
543 
544  // !!! NOTE TO IMPLEMENTOR !!!
545  //
546  // This class MUST NOT contain any non-static data members.
547  // Block can be reinterpret_cast'ed as Component type.
548 };
549 
551 
552 } // namespace ndn::name
553 
554 #endif // NDN_CXX_NAME_COMPONENT_HPP
Represents a TLV element of the NDN packet format.
Definition: block.hpp:45
Represents a name component.
Component(ConstBufferPtr buffer)
Construct a GenericNameComponent, using TLV-VALUE from buffer.
static Component fromEscapedString(std::string_view input)
static Component fromUri(std::string_view input)
Construct a NameComponent from its string representation in NDN URI format.
Component(span< const uint8_t > value)
Construct a GenericNameComponent, copying the TLV-VALUE from value.
Component(Iterator first, Iterator last)
Construct a GenericNameComponent, copying the TLV-VALUE from a range.
void toUri(std::ostream &os, UriFormat format=UriFormat::DEFAULT) const
Write *this to the output stream, escaping characters according to the NDN URI format.
bool empty() const noexcept
Component(uint32_t type, Iterator first, Iterator last)
Construct a NameComponent of TLV-TYPE type, copying the TLV-VALUE from a range.
int compare(const Component &other) const
Compare this component to other using NDN canonical ordering.
Error(const char *expectedType, uint32_t actualType)
Definition: tlv.cpp:28
#define NDN_CXX_DECLARE_WIRE_ENCODE_INSTANTIATIONS(ClassName)
Block makeBinaryBlock(uint32_t type, span< const uint8_t > value)
Create a TLV block copying the TLV-VALUE from a byte range.
Convention
Identify a style of NDN Naming Conventions.
@ MARKER
Component markers (revision 1)
@ TYPED
Typed name components (revision 3)
@ SEQUENCE_NUMBER_MARKER
void setConventionDecoding(Convention convention)
Set which Naming Conventions style(s) to accept while decoding.
Convention getConventionEncoding() noexcept
Return which Naming Conventions style to use while encoding.
void setConventionEncoding(Convention convention)
Set which Naming Conventions style to use while encoding.
UriFormat
Format used for the URI representation of a name.
@ CANONICAL
Always use <type-number>=<percent-encoded-value> format.
@ DEFAULT
Use the library's default format; currently equivalent to UriFormat::ENV_OR_ALTERNATE.
@ ALTERNATE
Always prefer the alternate format when available.
@ ENV_OR_ALTERNATE
Same as UriFormat::ALTERNATE, unless NDN_NAME_ALT_URI environment variable is set to '0'.
@ ENV_OR_CANONICAL
Same as UriFormat::CANONICAL, unless NDN_NAME_ALT_URI environment variable is set to '1'.
Convention getConventionDecoding() noexcept
Return which Naming Conventions style(s) to accept while decoding.
@ GenericNameComponent
Definition: tlv.hpp:72
@ KeywordNameComponent
Definition: tlv.hpp:75
std::ostream & operator<<(std::ostream &os, const Data &data)
Definition: data.cpp:377
std::shared_ptr< const Buffer > ConstBufferPtr
Definition: buffer.hpp:140