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; -*- */
26 #ifndef NDN_NAME_HPP
27 #define NDN_NAME_HPP
28 
29 #include "common.hpp"
30 #include "name-component.hpp"
31 
32 #include <boost/iterator/reverse_iterator.hpp>
33 
34 namespace ndn {
35 
36 class Name;
37 
41 typedef Name PartialName;
42 
46 class Name : public enable_shared_from_this<Name>
47 {
48 public:
53  {
54  public:
55  explicit
56  Error(const std::string& what)
57  : name::Component::Error(what)
58  {
59  }
60  };
61 
63 
64  typedef std::vector<Component> component_container;
65 
66  typedef Component value_type;
67  typedef void allocator_type;
68  typedef Component& reference;
69  typedef const Component const_reference;
70  typedef Component* pointer;
71  typedef const Component* const_pointer;
72  typedef Component* iterator;
73  typedef const Component* const_iterator;
74 
75  typedef boost::reverse_iterator<iterator> reverse_iterator;
76  typedef boost::reverse_iterator<const_iterator> const_reverse_iterator;
77 
78  typedef component_container::difference_type difference_type;
79  typedef component_container::size_type size_type;
80 
84  Name();
85 
95  explicit
96  Name(const Block& wire);
97 
102  Name(const char* uri);
103 
108  Name(std::string uri);
109 
113  Name
114  deepCopy() const;
115 
119  template<encoding::Tag TAG>
120  size_t
121  wireEncode(EncodingImpl<TAG>& encoder) const;
122 
123  const Block&
124  wireEncode() const;
125 
126  void
127  wireDecode(const Block& wire);
128 
132  bool
133  hasWire() const;
134 
139  Name&
140  append(const uint8_t* value, size_t valueLength)
141  {
142  m_nameBlock.push_back(Component(value, valueLength));
143  return *this;
144  }
145 
155  template<class Iterator>
156  Name&
157  append(Iterator first, Iterator last)
158  {
159  m_nameBlock.push_back(Component(first, last));
160  return *this;
161  }
162 
166  Name&
167  append(const Component& value)
168  {
169  m_nameBlock.push_back(value);
170  return *this;
171  }
172 
180  Name&
181  append(const char* value)
182  {
183  m_nameBlock.push_back(Component(value));
184  return *this;
185  }
186 
187  Name&
188  append(const Block& value)
189  {
190  if (value.type() == tlv::NameComponent)
191  m_nameBlock.push_back(value);
192  else
193  m_nameBlock.push_back(Block(tlv::NameComponent, value));
194 
195  return *this;
196  }
197 
203  Name&
204  append(const PartialName& name);
205 
209  void
211  {
212  m_nameBlock = Block(tlv::Name);
213  }
214 
229  PartialName
230  getSubName(ssize_t iStartComponent, size_t nComponents = npos) const;
231 
240  PartialName
241  getPrefix(ssize_t nComponents) const
242  {
243  if (nComponents < 0)
244  return getSubName(0, m_nameBlock.elements_size() + nComponents);
245  else
246  return getSubName(0, nComponents);
247  }
248 
253  std::string
254  toUri() const;
255 
264  Name&
265  appendNumber(uint64_t number);
266 
275  Name&
276  appendNumberWithMarker(uint8_t marker, uint64_t number);
277 
283  Name&
284  appendVersion(uint64_t version);
285 
292  Name&
293  appendVersion();
294 
300  Name&
301  appendSegment(uint64_t segmentNo);
302 
308  Name&
309  appendSegmentOffset(uint64_t offset);
310 
316  Name&
318 
324  Name&
325  appendSequenceNumber(uint64_t seqNo);
326 
330  Name&
332 
336  Name&
337  appendImplicitSha256Digest(const uint8_t* digest, size_t digestSize);
338 
360  Name
361  getSuccessor() const;
362 
368  bool
369  equals(const Name& name) const;
370 
379  bool
380  isPrefixOf(const Name& name) const;
381 
382  //
383  // vector equivalent interface.
384  //
385 
389  bool
390  empty() const
391  {
392  return m_nameBlock.elements().empty();
393  }
394 
399  size_t
400  size() const
401  {
402  return m_nameBlock.elements_size();
403  }
404 
410  const Component&
411  get(ssize_t i) const
412  {
413  if (i >= 0)
414  return reinterpret_cast<const Component&>(m_nameBlock.elements()[i]);
415  else
416  return reinterpret_cast<const Component&>(m_nameBlock.elements()[size() + i]);
417  }
418 
419  const Component&
420  operator[](ssize_t i) const
421  {
422  return get(i);
423  }
424 
433  const Component&
434  at(ssize_t i) const
435  {
436  if ((i >= 0 && static_cast<size_t>(i) >= size()) ||
437  (i < 0 && static_cast<size_t>(-i) > size()))
438  BOOST_THROW_EXCEPTION(Error("Requested component does not exist (out of bounds)"));
439 
440  return get(i);
441  }
442 
465  int
466  compare(const Name& other) const
467  {
468  return this->compare(0, npos, other);
469  }
470 
476  int
477  compare(size_t pos1, size_t count1,
478  const Name& other, size_t pos2 = 0, size_t count2 = npos) const;
479 
484  template<class T> void
485  push_back(const T& component)
486  {
487  append(component);
488  }
489 
495  bool
496  operator==(const Name& name) const
497  {
498  return equals(name);
499  }
500 
506  bool
507  operator!=(const Name& name) const
508  {
509  return !equals(name);
510  }
511 
518  bool
519  operator<=(const Name& other) const
520  {
521  return compare(other) <= 0;
522  }
523 
530  bool
531  operator<(const Name& other) const
532  {
533  return compare(other) < 0;
534  }
535 
542  bool
543  operator>=(const Name& other) const
544  {
545  return compare(other) >= 0;
546  }
547 
554  bool
555  operator>(const Name& other) const
556  {
557  return compare(other) > 0;
558  }
559 
560  //
561  // Iterator interface to name components.
562  //
563 
567  const_iterator
568  begin() const
569  {
570  return reinterpret_cast<const_iterator>(&*m_nameBlock.elements().begin());
571  }
572 
578  const_iterator
579  end() const
580  {
581  return reinterpret_cast<const_iterator>(&*m_nameBlock.elements().end());
582  }
583 
587  const_reverse_iterator
588  rbegin() const
589  {
590  return const_reverse_iterator(end());
591  }
592 
596  const_reverse_iterator
597  rend() const
598  {
599  return const_reverse_iterator(begin());
600  }
601 
602 public:
605  static const size_t npos;
606 
607 private:
608  mutable Block m_nameBlock;
609 };
610 
611 std::ostream&
612 operator<<(std::ostream& os, const Name& name);
613 
614 std::istream&
615 operator>>(std::istream& is, Name& name);
616 
617 inline bool
619 {
620  return m_nameBlock.hasWire();
621 }
622 
623 } // namespace ndn
624 
625 namespace std {
626 template<>
627 struct hash<ndn::Name>
628 {
629  size_t
630  operator()(const ndn::Name& name) const;
631 };
632 
633 } // namespace std
634 
635 #endif
bool equals(const Name &name) const
Check if this name has the same component count and components as the given name. ...
Definition: name.cpp:294
PartialName getPrefix(ssize_t nComponents) const
Extract a prefix (PartialName) of the name, containing first nComponents components.
Definition: name.hpp:241
Copyright (c) 2011-2015 Regents of the University of California.
name::Component Component
Definition: name.hpp:62
Component * pointer
Definition: name.hpp:70
std::string toUri() const
Encode this name as a URI.
Definition: name.cpp:171
const Block & wireEncode() const
Definition: name.cpp:143
const Component & at(ssize_t i) const
Get component at the specified index.
Definition: name.hpp:434
Name & appendNumber(uint64_t number)
Append a component with the number encoded as nonNegativeInteger.
Definition: name.cpp:192
Name & append(const char *value)
Append name component that represented as a string.
Definition: name.hpp:181
bool operator<(const Name &other) const
Return true if this is less than the other Name in the NDN canonical ordering.
Definition: name.hpp:531
const_iterator end() const
End iterator (const).
Definition: name.hpp:579
const Component & operator[](ssize_t i) const
Definition: name.hpp:420
std::ostream & operator<<(std::ostream &os, const Data &data)
Definition: data.cpp:320
component_container::size_type size_type
Definition: name.hpp:79
const Component const_reference
Definition: name.hpp:69
Name getSuccessor() const
Get the successor of a name.
Definition: name.cpp:281
const_reverse_iterator rend() const
Reverse end iterator (const).
Definition: name.hpp:597
Name & append(const Component &value)
Append component value.
Definition: name.hpp:167
static const size_t npos
indicates "until the end" in getSubName and compare
Definition: name.hpp:605
std::vector< Component > component_container
Definition: name.hpp:64
STL namespace.
Class representing a wire element of NDN-TLV packet format.
Definition: block.hpp:43
const_reverse_iterator rbegin() const
Reverse begin iterator (const).
Definition: name.hpp:588
static time_point now() noexcept
Definition: time.cpp:45
Copyright (c) 2013-2016 Regents of the University of California.
bool operator==(const Name &name) const
Check if this name has the same component count and components as the given name. ...
Definition: name.hpp:496
Name & appendSequenceNumber(uint64_t seqNo)
Append sequence number using NDN naming conventions.
Definition: name.cpp:241
Error that can be thrown from Name.
Definition: name.hpp:52
Component value_type
Definition: name.hpp:66
boost::reverse_iterator< iterator > reverse_iterator
Definition: name.hpp:75
int compare(const Name &other) const
Compare this to the other Name using NDN canonical ordering.
Definition: name.hpp:466
Name & appendSegmentOffset(uint64_t offset)
Append segment byte offset using NDN naming conventions.
Definition: name.cpp:227
const Component * const_iterator
Definition: name.hpp:73
Name & appendSegment(uint64_t segmentNo)
Append segment number (sequential) using NDN naming conventions.
Definition: name.cpp:220
Name & append(const Block &value)
Definition: name.hpp:188
const Component * const_pointer
Definition: name.hpp:71
bool operator>(const Name &other) const
Return true if this is greater than the other Name in the NDN canonical ordering. ...
Definition: name.hpp:555
bool operator>=(const Name &other) const
Return true if this is less than or equal to the other Name in the NDN canonical ordering.
Definition: name.hpp:543
Component * iterator
Definition: name.hpp:72
Name & appendTimestamp(const time::system_clock::TimePoint &timePoint=time::system_clock::now())
Append timestamp using NDN naming conventions.
Definition: name.cpp:234
std::istream & operator>>(std::istream &is, Name &name)
Definition: name.cpp:358
Name abstraction to represent an absolute name.
Definition: name.hpp:46
bool isPrefixOf(const Name &name) const
Check if the N components of this name are the same as the first N components of the given name...
Definition: name.cpp:308
Name & append(Iterator first, Iterator last)
Append a new component, copying from value frome the range [first, last) of bytes.
Definition: name.hpp:157
Error(const std::string &what)
Definition: name.hpp:56
const_iterator begin() const
Begin iterator (const).
Definition: name.hpp:568
void push_back(const T &component)
Append the component.
Definition: name.hpp:485
size_t size() const
Get the number of components.
Definition: name.hpp:400
time_point TimePoint
Definition: time.hpp:90
bool operator<=(const Name &other) const
Return true if this is less than or equal to the other Name in the NDN canonical ordering.
Definition: name.hpp:519
bool operator!=(const Name &name) const
Check if this name has the same component count and components as the given name. ...
Definition: name.hpp:507
Component holds a read-only name component value.
Name & appendNumberWithMarker(uint8_t marker, uint64_t number)
Create a component encoded as NameComponentWithMarker.
Definition: name.cpp:199
Component & reference
Definition: name.hpp:68
Name & append(const uint8_t *value, size_t valueLength)
Append a new component, copying from value of length valueLength.
Definition: name.hpp:140
bool empty() const
Check if name is emtpy.
Definition: name.hpp:390
component_container::difference_type difference_type
Definition: name.hpp:78
Name PartialName
Partial name abstraction to represent an arbitrary sequence of name components.
Definition: name.hpp:36
Name deepCopy() const
Make a deep copy of the name, reallocating the underlying memory buffer.
Definition: name.cpp:112
shared_ptr< const Buffer > ConstBufferPtr
Definition: buffer.hpp:33
void wireDecode(const Block &wire)
Definition: name.cpp:161
void allocator_type
Definition: name.hpp:67
boost::reverse_iterator< const_iterator > const_reverse_iterator
Definition: name.hpp:76
void clear()
Clear all the components.
Definition: name.hpp:210
PartialName getSubName(ssize_t iStartComponent, size_t nComponents=npos) const
Extract a sub-name (PartialName) of nComponents components starting from iStartComponent.
Definition: name.cpp:262
uint32_t type() const
Definition: block.hpp:324
Name & appendVersion()
Append version using NDN naming conventions based on current UNIX timestamp in milliseconds.
Definition: name.cpp:213
Name()
Create a new Name with no components.
Definition: name.cpp:46
Error that can be thrown from name::Component.
bool hasWire() const
Check if already has wire.
Definition: name.hpp:618
Name & appendImplicitSha256Digest(const ConstBufferPtr &digest)
Append ImplicitSha256Digest.
Definition: name.cpp:248