NS-3 based Named Data Networking (NDN) simulator
ndnSIM 2.3: 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-2017 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  * @author Jeff Thompson <jefft0@remap.ucla.edu>
22  * @author Alexander Afanasyev <http://lasr.cs.ucla.edu/afanasyev/index.html>
23  * @author Zhenkai Zhu <http://irl.cs.ucla.edu/~zhenkai/>
24  */
25 
26 #ifndef NDN_NAME_HPP
27 #define NDN_NAME_HPP
28 
29 #include "name-component.hpp"
30 #include <iterator>
31 
32 namespace ndn {
33 
34 class Name;
35 
38 using PartialName = Name;
39 
42 class Name
43 {
44 public: // nested types
46  {
47  public:
48  explicit
49  Error(const std::string& what)
50  : name::Component::Error(what)
51  {
52  }
53  };
54 
56  using component_container = std::vector<Component>;
57 
58  // Name appears as a container of name components
60  using allocator_type = void;
61  using reference = Component&;
62  using const_reference = const Component&;
63  using pointer = Component*;
64  using const_pointer = const Component*;
65  using iterator = const Component*; // disallow modifying via iterator
66  using const_iterator = const Component*;
67  using reverse_iterator = std::reverse_iterator<iterator>;
68  using const_reverse_iterator = std::reverse_iterator<const_iterator>;
69  using difference_type = component_container::difference_type;
70  using size_type = component_container::size_type;
71 
72 public: // constructors, encoding, decoding
76  Name();
77 
87  explicit
88  Name(const Block& wire);
89 
94  Name(const char* uri);
95 
100  Name(std::string uri);
101 
107  std::string
108  toUri() const;
109 
112  bool
113  hasWire() const
114  {
115  return m_wire.hasWire();
116  }
117 
120  template<encoding::Tag TAG>
121  size_t
122  wireEncode(EncodingImpl<TAG>& encoder) const;
123 
127  const Block&
128  wireEncode() const;
129 
134  void
135  wireDecode(const Block& wire);
136 
139  Name
140  deepCopy() const;
141 
142 public: // access
145  bool
146  empty() const
147  {
148  return m_wire.elements().empty();
149  }
150 
153  size_t
154  size() const
155  {
156  return m_wire.elements_size();
157  }
158 
163  const Component&
164  get(ssize_t i) const
165  {
166  if (i < 0) {
167  i += size();
168  }
169  return reinterpret_cast<const Component&>(m_wire.elements()[i]);
170  }
171 
174  const Component&
175  operator[](ssize_t i) const
176  {
177  return get(i);
178  }
179 
184  const Component&
185  at(ssize_t i) const;
186 
200  getSubName(ssize_t iStartComponent, size_t nComponents = npos) const;
201 
210  getPrefix(ssize_t nComponents) const
211  {
212  if (nComponents < 0)
213  return getSubName(0, size() + nComponents);
214  else
215  return getSubName(0, nComponents);
216  }
217 
218 public: // iterators
222  begin() const
223  {
224  return reinterpret_cast<const_iterator>(m_wire.elements().data());
225  }
226 
230  end() const
231  {
232  return reinterpret_cast<const_iterator>(m_wire.elements().data() + m_wire.elements().size());
233  }
234 
238  rbegin() const
239  {
240  return const_reverse_iterator(end());
241  }
242 
246  rend() const
247  {
248  return const_reverse_iterator(begin());
249  }
250 
251 public: // modifiers
255  Name&
256  append(const Component& component)
257  {
258  m_wire.push_back(component);
259  return *this;
260  }
261 
269  Name&
270  append(const char* value)
271  {
272  return append(Component(value));
273  }
274 
278  Name&
279  append(const uint8_t* value, size_t valueLength)
280  {
281  return append(Component(value, valueLength));
282  }
283 
292  template<class Iterator>
293  Name&
294  append(Iterator first, Iterator last)
295  {
296  static_assert(sizeof(std::iterator_traits<Iterator>::value_type) == 1,
297  "iterator does not dereference to one-octet value type");
298  return append(Component(first, last));
299  }
300 
305  Name&
307  {
308  if (value.type() == tlv::NameComponent) {
309  m_wire.push_back(value);
310  }
311  else {
312  m_wire.push_back(Block(tlv::NameComponent, value));
313  }
314 
315  return *this;
316  }
317 
323  Name&
324  appendNumber(uint64_t number)
325  {
326  return append(Component::fromNumber(number));
327  }
328 
338  Name&
339  appendNumberWithMarker(uint8_t marker, uint64_t number)
340  {
341  return append(Component::fromNumberWithMarker(marker, number));
342  }
343 
348  Name&
350  {
351  return append(Component::fromVersion(version));
352  }
353 
361  Name&
362  appendVersion();
363 
368  Name&
369  appendSegment(uint64_t segmentNo)
370  {
371  return append(Component::fromSegment(segmentNo));
372  }
373 
378  Name&
379  appendSegmentOffset(uint64_t offset)
380  {
381  return append(Component::fromSegmentOffset(offset));
382  }
383 
388  Name&
390  {
391  return append(Component::fromTimestamp(timePoint));
392  }
393 
398  Name&
399  appendTimestamp();
400 
405  Name&
406  appendSequenceNumber(uint64_t seqNo)
407  {
408  return append(Component::fromSequenceNumber(seqNo));
409  }
410 
414  Name&
416  {
418  }
419 
423  Name&
424  appendImplicitSha256Digest(const uint8_t* digest, size_t digestSize)
425  {
426  return append(Component::fromImplicitSha256Digest(digest, digestSize));
427  }
428 
433  Name&
434  append(const PartialName& name);
435 
439  template<class T>
440  void
441  push_back(const T& component)
442  {
443  append(component);
444  }
445 
449  void
451  {
452  m_wire = Block(tlv::Name);
453  }
454 
455 public: // algorithms
476  Name
477  getSuccessor() const;
478 
487  bool
488  isPrefixOf(const Name& other) const;
489 
495  bool
496  equals(const Name& other) const;
497 
519  int
520  compare(const Name& other) const
521  {
522  return this->compare(0, npos, other);
523  }
524 
530  int
531  compare(size_t pos1, size_t count1,
532  const Name& other, size_t pos2 = 0, size_t count2 = npos) const;
533 
534 public:
537  static const size_t npos;
538 
539 private:
540  mutable Block m_wire;
541 };
542 
544 
545 inline bool
546 operator==(const Name& lhs, const Name& rhs)
547 {
548  return lhs.equals(rhs);
549 }
550 
551 inline bool
552 operator!=(const Name& lhs, const Name& rhs)
553 {
554  return !lhs.equals(rhs);
555 }
556 
557 inline bool
558 operator<=(const Name& lhs, const Name& rhs)
559 {
560  return lhs.compare(rhs) <= 0;
561 }
562 
563 inline bool
564 operator<(const Name& lhs, const Name& rhs)
565 {
566  return lhs.compare(rhs) < 0;
567 }
568 
569 inline bool
570 operator>=(const Name& lhs, const Name& rhs)
571 {
572  return lhs.compare(rhs) >= 0;
573 }
574 
575 inline bool
576 operator>(const Name& lhs, const Name& rhs)
577 {
578  return lhs.compare(rhs) > 0;
579 }
580 
584 std::ostream&
585 operator<<(std::ostream& os, const Name& name);
586 
590 std::istream&
591 operator>>(std::istream& is, Name& name);
592 
593 } // namespace ndn
594 
595 namespace std {
596 
597 template<>
598 struct hash<ndn::Name>
599 {
600  size_t
601  operator()(const ndn::Name& name) const;
602 };
603 
604 } // namespace std
605 
606 #endif // NDN_NAME_HPP
static Component fromNumber(uint64_t number)
Create a component encoded as nonNegativeInteger.
static Component fromSequenceNumber(uint64_t seqNo)
Create sequence number component using NDN naming conventions.
void allocator_type
Definition: name.hpp:60
Copyright (c) 2011-2015 Regents of the University of California.
Name & appendTimestamp()
Append a timestamp component based on current time.
Definition: name.cpp:226
const_iterator begin() const
Begin iterator.
Definition: name.hpp:222
static Component fromNumberWithMarker(uint8_t marker, uint64_t number)
Create a component encoded as NameComponentWithMarker.
Name & appendTimestamp(const time::system_clock::TimePoint &timePoint)
Append a timestamp component.
Definition: name.hpp:389
Name getSuccessor() const
Get the successor of a name.
Definition: name.cpp:247
Name & append(const char *value)
Append a component, copying from a zero-terminated byte string.
Definition: name.hpp:270
std::reverse_iterator< iterator > reverse_iterator
Definition: name.hpp:67
std::ostream & operator<<(std::ostream &os, const Data &data)
Definition: data.cpp:274
Name & appendVersion(uint64_t version)
Append a version component.
Definition: name.hpp:349
static Component fromTimestamp(const time::system_clock::TimePoint &timePoint)
Create sequence number component using NDN naming conventions.
static const size_t npos
indicates "until the end" in getSubName and compare
Definition: name.hpp:537
STL namespace.
Represents a TLV element of NDN packet format.
Definition: block.hpp:42
bool operator<=(const Delegation &lhs, const Delegation &rhs)
Definition: delegation.cpp:43
bool operator!=(const Data &lhs, const Data &rhs)
Definition: data.hpp:259
Name & appendNumber(uint64_t number)
Append a component with a nonNegativeInteger.
Definition: name.hpp:324
Name & append(const Component &component)
Append a component.
Definition: name.hpp:256
static Component fromSegmentOffset(uint64_t offset)
Create segment offset component using NDN naming conventions.
const Component & operator[](ssize_t i) const
Equivalent to get(i)
Definition: name.hpp:175
std::reverse_iterator< const_iterator > const_reverse_iterator
Definition: name.hpp:68
static Component fromSegment(uint64_t segmentNo)
Create segment number component using NDN naming conventions.
std::string toUri() const
Get URI representation of the name.
Definition: name.cpp:122
const Block & wireEncode() const
Perform wire encoding, or return existing wire encoding.
Definition: name.cpp:146
const_iterator end() const
End iterator.
Definition: name.hpp:230
bool equals(const Name &other) const
Check if this name equals another name.
Definition: name.cpp:276
const_reverse_iterator rend() const
Reverse end iterator.
Definition: name.hpp:246
Name & appendSegmentOffset(uint64_t offset)
Append a segment byte offset component.
Definition: name.hpp:379
bool hasWire() const
Check if this Name instance already has wire encoding.
Definition: name.hpp:113
Name & append(const Block &value)
Append a component, decoding from a Block.
Definition: name.hpp:306
component_container::size_type size_type
Definition: name.hpp:70
name::Component Component
Definition: name.hpp:55
size_t size() const
Get number of components.
Definition: name.hpp:154
Name & appendSequenceNumber(uint64_t seqNo)
Append a sequence number component.
Definition: name.hpp:406
std::istream & operator>>(std::istream &is, Name &name)
Parse URI from stream as Name.
Definition: name.cpp:324
Represents an absolute name.
Definition: name.hpp:42
bool isPrefixOf(const Name &other) const
Check if this name is a prefix of another name.
Definition: name.cpp:260
Name & append(Iterator first, Iterator last)
Append a component, copying from [first, last)
Definition: name.hpp:294
Error(const std::string &what)
Definition: name.hpp:49
const Component & at(ssize_t i) const
Get the component at the given index.
Definition: name.cpp:185
void push_back(const T &component)
Append a component.
Definition: name.hpp:441
const_reverse_iterator rbegin() const
Reverse begin iterator.
Definition: name.hpp:238
NDN_CXX_DECLARE_WIRE_ENCODE_INSTANTIATIONS(Exclude)
uint32_t type() const
Get TLV-TYPE.
Definition: block.hpp:235
time_point TimePoint
Definition: time.hpp:90
bool operator>(const Delegation &lhs, const Delegation &rhs)
Definition: delegation.hpp:54
Component holds a read-only name component value.
static Component fromImplicitSha256Digest(const ConstBufferPtr &digest)
Create ImplicitSha256DigestComponent component.
int compare(const Name &other) const
Compare this to the other Name using NDN canonical ordering.
Definition: name.hpp:520
bool operator>=(const Delegation &lhs, const Delegation &rhs)
Definition: delegation.hpp:60
Name deepCopy() const
Make a deep copy of the name, reallocating the underlying memory buffer.
Definition: name.cpp:174
Name & append(const uint8_t *value, size_t valueLength)
Append a component, copying from [value, value + valueLength)
Definition: name.hpp:279
bool empty() const
Check if name is empty.
Definition: name.hpp:146
PartialName getSubName(ssize_t iStartComponent, size_t nComponents=npos) const
Extract some components as a sub-name (PartialName)
Definition: name.cpp:199
PartialName getPrefix(ssize_t nComponents) const
Extract a prefix of the name.
Definition: name.hpp:210
bool operator==(const Data &lhs, const Data &rhs)
Definition: data.cpp:265
Name & appendImplicitSha256Digest(const uint8_t *digest, size_t digestSize)
Append an ImplicitSha256Digest component.
Definition: name.hpp:424
static Component fromVersion(uint64_t version)
Create version component using NDN naming conventions.
component_container::difference_type difference_type
Definition: name.hpp:69
Name & appendNumberWithMarker(uint8_t marker, uint64_t number)
Append a component with a marked number.
Definition: name.hpp:339
void wireDecode(const Block &wire)
Decode name from wire encoding.
Definition: name.cpp:164
std::vector< Component > component_container
Definition: name.hpp:56
void clear()
Remove all components.
Definition: name.hpp:450
bool operator<(const Delegation &lhs, const Delegation &rhs)
Definition: delegation.cpp:36
Name & appendSegment(uint64_t segmentNo)
Append a segment number (sequential) component.
Definition: name.hpp:369
Name & appendImplicitSha256Digest(const ConstBufferPtr &digest)
Append an ImplicitSha256Digest component.
Definition: name.hpp:415
Name & appendVersion()
Append a version component based on current time.
Definition: name.cpp:220
Name()
Create an empty name.
Definition: name.cpp:56
Error that can be thrown from name::Component.
shared_ptr< const Buffer > ConstBufferPtr
Definition: buffer.hpp:89