NS-3 based Named Data Networking (NDN) simulator
ndnSIM 2.5: NDN, CCN, CCNx, content centric networks
API Documentation
name.hpp
Go to the documentation of this file.
1 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
2 /*
3  * Copyright (c) 2013-2022 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_HPP
23 #define NDN_CXX_NAME_HPP
24 
27 
28 #include <iterator>
29 
30 namespace ndn {
31 
32 class Name;
33 
36 using PartialName = Name;
37 
41 class Name
42 {
43 public: // nested types
45 
47  using component_container = std::vector<Component>;
48 
49  // Name appears as a container of name components
51  using allocator_type = void;
52  using reference = Component&;
53  using const_reference = const Component&;
54  using pointer = Component*;
55  using const_pointer = const Component*;
56  using iterator = const Component*; // disallow modifying via iterator
57  using const_iterator = const Component*;
58  using reverse_iterator = std::reverse_iterator<iterator>;
59  using const_reverse_iterator = std::reverse_iterator<const_iterator>;
60  using difference_type = component_container::difference_type;
61  using size_type = component_container::size_type;
62 
63 public: // constructors, encoding, decoding
67  Name();
68 
78  explicit
79  Name(const Block& wire);
80 
85  Name(const char* uri);
86 
91  Name(std::string uri);
92 
96  void
97  toUri(std::ostream& os, name::UriFormat format = name::UriFormat::DEFAULT) const;
98 
104  std::string
106 
109  bool
110  hasWire() const noexcept
111  {
112  return m_wire.hasWire();
113  }
114 
117  template<encoding::Tag TAG>
118  size_t
119  wireEncode(EncodingImpl<TAG>& encoder) const;
120 
124  const Block&
125  wireEncode() const;
126 
131  void
132  wireDecode(const Block& wire);
133 
136  Name
137  deepCopy() const;
138 
139 public: // access
142  NDN_CXX_NODISCARD bool
143  empty() const
144  {
145  return m_wire.elements().empty();
146  }
147 
150  size_t
151  size() const
152  {
153  return m_wire.elements_size();
154  }
155 
161  const Component&
162  get(ssize_t i) const
163  {
164  if (i < 0) {
165  i += static_cast<ssize_t>(size());
166  }
167  return static_cast<const Component&>(m_wire.elements()[static_cast<size_t>(i)]);
168  }
169 
172  const Component&
173  operator[](ssize_t i) const
174  {
175  return get(i);
176  }
177 
184  const Component&
185  at(ssize_t i) const;
186 
200  getSubName(ssize_t iStartComponent, size_t nComponents = npos) const;
201 
209  getPrefix(ssize_t nComponents) const
210  {
211  if (nComponents < 0)
212  return getSubName(0, size() + nComponents);
213  else
214  return getSubName(0, nComponents);
215  }
216 
217 public: // iterators
221  begin() const
222  {
223  return reinterpret_cast<const_iterator>(m_wire.elements().data());
224  }
225 
229  end() const
230  {
231  return reinterpret_cast<const_iterator>(m_wire.elements().data() + m_wire.elements().size());
232  }
233 
237  rbegin() const
238  {
239  return const_reverse_iterator(end());
240  }
241 
245  rend() const
246  {
247  return const_reverse_iterator(begin());
248  }
249 
250 public: // modifiers
258  Name&
259  set(ssize_t i, const Component& component);
260 
268  Name&
269  set(ssize_t i, Component&& component);
270 
274  Name&
275  append(const Component& component)
276  {
277  m_wire.push_back(component);
278  return *this;
279  }
280 
284  Name&
285  append(Component&& component)
286  {
287  m_wire.push_back(std::move(component));
288  return *this;
289  }
290 
295  Name&
296  append(uint32_t type, span<const uint8_t> value)
297  {
298  return append(Component(type, value));
299  }
300 
305  Name&
306  append(span<const uint8_t> value)
307  {
309  }
310 
316  [[deprecated("use the overload that takes a span<>")]]
317  Name&
318  append(uint32_t type, const uint8_t* value, size_t count)
319  {
320  return append(type, make_span(value, count));
321  }
322 
328  [[deprecated("use the overload that takes a span<>")]]
329  Name&
330  append(const uint8_t* value, size_t count)
331  {
332  return append(make_span(value, count));
333  }
334 
343  template<class Iterator>
344  Name&
345  append(uint32_t type, Iterator first, Iterator last)
346  {
347  return append(Component(type, first, last));
348  }
349 
357  template<class Iterator>
358  Name&
359  append(Iterator first, Iterator last)
360  {
361  return append(Component(tlv::GenericNameComponent, first, last));
362  }
363 
369  Name&
370  append(const char* str)
371  {
372  return append(Component(str));
373  }
374 
379  Name&
380  append(const PartialName& name);
381 
386  Name&
387  appendNumber(uint64_t number)
388  {
389  return append(Component::fromNumber(number));
390  }
391 
402  Name&
403  appendNumberWithMarker(uint8_t marker, uint64_t number)
404  {
405  return append(Component::fromNumberWithMarker(marker, number));
406  }
407 
414  Name&
415  appendSegment(uint64_t segmentNo)
416  {
417  return append(Component::fromSegment(segmentNo));
418  }
419 
426  Name&
427  appendByteOffset(uint64_t offset)
428  {
429  return append(Component::fromByteOffset(offset));
430  }
431 
440  Name&
441  appendVersion(const optional<uint64_t>& version = nullopt);
442 
450  Name&
451  appendTimestamp(const optional<time::system_clock::time_point>& timestamp = nullopt);
452 
459  Name&
460  appendSequenceNumber(uint64_t seqNo)
461  {
462  return append(Component::fromSequenceNumber(seqNo));
463  }
464 
469  Name&
471  {
473  }
474 
479  Name&
480  appendImplicitSha256Digest(span<const uint8_t> digestBytes)
481  {
483  }
484 
489  Name&
491  {
493  }
494 
499  Name&
500  appendParametersSha256Digest(span<const uint8_t> digestBytes)
501  {
503  }
504 
509  Name&
511 
516  Name&
517  appendKeyword(span<const uint8_t> keyword)
518  {
519  return append(Component(tlv::KeywordNameComponent, keyword));
520  }
521 
526  Name&
527  appendKeyword(const char* keyword)
528  {
529  return append(Component(tlv::KeywordNameComponent, {reinterpret_cast<const uint8_t*>(keyword),
530  std::char_traits<char>::length(keyword)}));
531  }
532 
537  template<class T>
538  void
539  push_back(const T& component)
540  {
541  append(component);
542  }
543 
550  void
551  erase(ssize_t i);
552 
557  void
558  clear();
559 
560 public: // algorithms
585  Name
586  getSuccessor() const;
587 
596  bool
597  isPrefixOf(const Name& other) const;
598 
604  bool
605  equals(const Name& other) const;
606 
628  int
629  compare(const Name& other) const
630  {
631  return this->compare(0, npos, other);
632  }
633 
639  int
640  compare(size_t pos1, size_t count1,
641  const Name& other, size_t pos2 = 0, size_t count2 = npos) const;
642 
643 private: // non-member operators
644  // NOTE: the following "hidden friend" operators are available via
645  // argument-dependent lookup only and must be defined inline.
646 
647  friend bool
648  operator==(const Name& lhs, const Name& rhs)
649  {
650  return lhs.equals(rhs);
651  }
652 
653  friend bool
654  operator!=(const Name& lhs, const Name& rhs)
655  {
656  return !lhs.equals(rhs);
657  }
658 
659  friend bool
660  operator<(const Name& lhs, const Name& rhs)
661  {
662  return lhs.compare(rhs) < 0;
663  }
664 
665  friend bool
666  operator<=(const Name& lhs, const Name& rhs)
667  {
668  return lhs.compare(rhs) <= 0;
669  }
670 
671  friend bool
672  operator>(const Name& lhs, const Name& rhs)
673  {
674  return lhs.compare(rhs) > 0;
675  }
676 
677  friend bool
678  operator>=(const Name& lhs, const Name& rhs)
679  {
680  return lhs.compare(rhs) >= 0;
681  }
682 
686  friend std::ostream&
687  operator<<(std::ostream& os, const Name& name)
688  {
689  name.toUri(os);
690  return os;
691  }
692 
693 public:
696  static const size_t npos;
697 
698 private:
699  mutable Block m_wire;
700 };
701 
703 
707 std::istream&
708 operator>>(std::istream& is, Name& name);
709 
710 } // namespace ndn
711 
712 namespace std {
713 
714 template<>
715 struct hash<ndn::Name>
716 {
717  size_t
718  operator()(const ndn::Name& name) const;
719 };
720 
721 } // namespace std
722 
723 #endif // NDN_CXX_NAME_HPP
Name & appendImplicitSha256Digest(span< const uint8_t > digestBytes)
Append an ImplicitSha256Digest component.
Definition: name.hpp:480
friend bool operator==(const Name &lhs, const Name &rhs)
Definition: name.hpp:648
Name & appendByteOffset(uint64_t offset)
Append a byte offset component.
Definition: name.hpp:427
static Component fromSequenceNumber(uint64_t seqNo)
Create a sequence number component using NDN naming conventions.
friend bool operator>=(const Name &lhs, const Name &rhs)
Definition: name.hpp:678
PartialName getPrefix(ssize_t nComponents) const
Returns a prefix of the name.
Definition: name.hpp:209
void allocator_type
Definition: name.hpp:51
Copyright (c) 2011-2015 Regents of the University of California.
Name & appendParametersSha256Digest(ConstBufferPtr digest)
Append a ParametersSha256Digest component.
Definition: name.hpp:490
bool equals(const Name &other) const
Check if this name equals another name.
Definition: name.cpp:316
static Component fromNumberWithMarker(uint8_t marker, uint64_t number)
Create a component encoded as NameComponentWithMarker.
const Block & wireEncode() const
Perform wire encoding, or return existing wire encoding.
Definition: name.cpp:132
UriFormat
Format used for the URI representation of a name.
const_iterator end() const
End iterator.
Definition: name.hpp:229
const Component & operator[](ssize_t i) const
Equivalent to get(i).
Definition: name.hpp:173
friend std::ostream & operator<<(std::ostream &os, const Name &name)
Print the URI representation of a name.
Definition: name.hpp:687
Name & appendImplicitSha256Digest(ConstBufferPtr digest)
Append an ImplicitSha256Digest component.
Definition: name.hpp:470
std::reverse_iterator< iterator > reverse_iterator
Definition: name.hpp:58
bool isPrefixOf(const Name &other) const
Check if this name is a prefix of another name.
Definition: name.cpp:300
friend bool operator<(const Name &lhs, const Name &rhs)
Definition: name.hpp:660
Name getSuccessor() const
Get the successor of a name.
Definition: name.cpp:289
const_reverse_iterator rend() const
Reverse end iterator.
Definition: name.hpp:245
static const size_t npos
Indicates "until the end" in getSubName() and compare().
Definition: name.hpp:696
STL namespace.
friend bool operator>(const Name &lhs, const Name &rhs)
Definition: name.hpp:672
Represents a TLV element of the NDN packet format.
Definition: block.hpp:44
const_reverse_iterator rbegin() const
Reverse begin iterator.
Definition: name.hpp:237
bool hasWire() const noexcept
Check if the Block contains a fully encoded wire representation.
Definition: block.hpp:221
Name & append(Component &&component)
Append a component.
Definition: name.hpp:285
Name & appendNumber(uint64_t number)
Append a component with a NonNegativeInteger.
Definition: name.hpp:387
Name & append(const Component &component)
Append a component.
Definition: name.hpp:275
Name & append(span< const uint8_t > value)
Append a GenericNameComponent, copying the TLV-VALUE from value.
Definition: name.hpp:306
Name & appendVersion(const optional< uint64_t > &version=nullopt)
Append a version component.
Definition: name.cpp:230
friend bool operator!=(const Name &lhs, const Name &rhs)
Definition: name.hpp:654
const element_container & elements() const
Get container of sub-elements.
Definition: block.hpp:425
std::reverse_iterator< const_iterator > const_reverse_iterator
Definition: name.hpp:59
friend bool operator<=(const Name &lhs, const Name &rhs)
Definition: name.hpp:666
const Component & at(ssize_t i) const
Returns an immutable reference to the component at the specified index, with bounds checking...
Definition: name.cpp:171
static Component fromSegment(uint64_t segmentNo)
Create a segment number component using NDN naming conventions.
Use the library&#39;s default format; currently equivalent to UriFormat::ENV_OR_ALTERNATE.
int compare(const Name &other) const
Compare this to the other Name using NDN canonical ordering.
Definition: name.hpp:629
NDN_CXX_NODISCARD bool empty() const
Checks if the name is empty, i.e.
Definition: name.hpp:143
static Component fromByteOffset(uint64_t offset)
Create a byte offset component using NDN naming conventions.
#define NDN_CXX_NODISCARD
Definition: backports.hpp:68
component_container::size_type size_type
Definition: name.hpp:61
Name & append(uint32_t type, Iterator first, Iterator last)
Append a NameComponent of TLV-TYPE type, copying TLV-VALUE from a range.
Definition: name.hpp:345
name::Component Component
Definition: name.hpp:46
Name & append(uint32_t type, span< const uint8_t > value)
Append a NameComponent of TLV-TYPE type, copying the TLV-VALUE from value.
Definition: name.hpp:296
Name & appendSequenceNumber(uint64_t seqNo)
Append a sequence number component.
Definition: name.hpp:460
std::istream & operator>>(std::istream &is, Name &name)
Parse URI from stream as Name.
Definition: name.cpp:371
Represents an absolute name.
Definition: name.hpp:41
void push_back(const Block &element)
Append a sub-element.
Definition: block.cpp:455
Name & append(Iterator first, Iterator last)
Append a GenericNameComponent, copying TLV-VALUE from a range.
Definition: name.hpp:359
size_t elements_size() const
Equivalent to elements().size()
Definition: block.hpp:449
Name & append(const uint8_t *value, size_t count)
Append a GenericNameComponent, copying count bytes at value as TLV-VALUE.
Definition: name.hpp:330
const_iterator begin() const
Begin iterator.
Definition: name.hpp:221
void push_back(const T &component)
Append a component.
Definition: name.hpp:539
size_t size() const
Returns the number of components.
Definition: name.hpp:151
Represents a name component.
void erase(ssize_t i)
Erase the component at the specified index.
Definition: name.cpp:270
static Component fromNumber(uint64_t number, uint32_t type=tlv::GenericNameComponent)
Create a component encoded as NonNegativeInteger.
Name & appendTimestamp(const optional< time::system_clock::time_point > &timestamp=nullopt)
Append a timestamp component.
Definition: name.cpp:236
void toUri(std::ostream &os, name::UriFormat format=name::UriFormat::DEFAULT) const
Write URI representation of the name to the output stream.
Definition: name.cpp:349
Name & appendKeyword(const char *keyword)
Append a keyword component.
Definition: name.hpp:527
Name & append(const char *str)
Append a GenericNameComponent, copying TLV-VALUE from a null-terminated string.
Definition: name.hpp:370
bool hasWire() const noexcept
Check if this instance already has wire encoding.
Definition: name.hpp:110
Name deepCopy() const
Make a deep copy of the name, reallocating the underlying memory buffer.
Definition: name.cpp:160
component_container::difference_type difference_type
Definition: name.hpp:60
Name & appendNumberWithMarker(uint8_t marker, uint64_t number)
Append a component with a marked number.
Definition: name.hpp:403
Name & appendParametersSha256Digest(span< const uint8_t > digestBytes)
Append a ParametersSha256Digest component.
Definition: name.hpp:500
void wireDecode(const Block &wire)
Decode name from wire encoding.
Definition: name.cpp:150
Name & append(uint32_t type, const uint8_t *value, size_t count)
Append a NameComponent of TLV-TYPE type, copying count bytes at value as TLV-VALUE.
Definition: name.hpp:318
std::vector< Component > component_container
Definition: name.hpp:47
void clear()
Remove all components.
Definition: name.cpp:281
Name & appendParametersSha256DigestPlaceholder()
Append a placeholder for a ParametersSha256Digest component.
Definition: name.cpp:263
PartialName getSubName(ssize_t iStartComponent, size_t nComponents=npos) const
Extracts some components as a sub-name (PartialName).
Definition: name.cpp:185
const nullopt_t nullopt((nullopt_t::init()))
Name & appendSegment(uint64_t segmentNo)
Append a segment number (sequential) component.
Definition: name.hpp:415
NDN_CXX_DECLARE_WIRE_ENCODE_INSTANTIATIONS(Interest)
Name()
Create an empty name.
Definition: name.cpp:54
Name & appendKeyword(span< const uint8_t > keyword)
Append a keyword component.
Definition: name.hpp:517
shared_ptr< const Buffer > ConstBufferPtr
Definition: buffer.hpp:139