NS-3 based Named Data Networking (NDN) simulator
ndnSIM 2.0: 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(const std::string& uri);
109 
113  template<encoding::Tag TAG>
114  size_t
115  wireEncode(EncodingImpl<TAG>& encoder) const;
116 
117  const Block&
118  wireEncode() const;
119 
120  void
121  wireDecode(const Block& wire);
122 
126  bool
127  hasWire() const;
128 
132  DEPRECATED(
133  void
134  set(const char* uri));
135 
139  DEPRECATED(
140  void
141  set(const std::string& uri));
142 
147  Name&
148  append(const uint8_t* value, size_t valueLength)
149  {
150  m_nameBlock.push_back(Component(value, valueLength));
151  return *this;
152  }
153 
163  template<class Iterator>
164  Name&
165  append(Iterator first, Iterator last)
166  {
167  m_nameBlock.push_back(Component(first, last));
168  return *this;
169  }
170 
174  Name&
175  append(const Component& value)
176  {
177  m_nameBlock.push_back(value);
178  return *this;
179  }
180 
188  Name&
189  append(const char* value)
190  {
191  m_nameBlock.push_back(Component(value));
192  return *this;
193  }
194 
195  Name&
196  append(const Block& value)
197  {
198  if (value.type() == tlv::NameComponent)
199  m_nameBlock.push_back(value);
200  else
201  m_nameBlock.push_back(Block(tlv::NameComponent, value));
202 
203  return *this;
204  }
205 
211  Name&
212  append(const PartialName& name);
213 
217  void
219  {
220  m_nameBlock = Block(tlv::Name);
221  }
222 
237  PartialName
238  getSubName(ssize_t iStartComponent, size_t nComponents = npos) const;
239 
248  PartialName
249  getPrefix(ssize_t nComponents) const
250  {
251  if (nComponents < 0)
252  return getSubName(0, m_nameBlock.elements_size() + nComponents);
253  else
254  return getSubName(0, nComponents);
255  }
256 
261  std::string
262  toUri() const;
263 
272  Name&
273  appendNumber(uint64_t number);
274 
283  Name&
284  appendNumberWithMarker(uint8_t marker, uint64_t number);
285 
291  Name&
292  appendVersion(uint64_t version);
293 
300  Name&
301  appendVersion();
302 
308  Name&
309  appendSegment(uint64_t segmentNo);
310 
316  Name&
317  appendSegmentOffset(uint64_t offset);
318 
324  Name&
326 
332  Name&
333  appendSequenceNumber(uint64_t seqNo);
334 
338  Name&
340 
344  Name&
345  appendImplicitSha256Digest(const uint8_t* digest, size_t digestSize);
346 
368  Name
369  getSuccessor() const;
370 
376  bool
377  equals(const Name& name) const;
378 
387  bool
388  isPrefixOf(const Name& name) const;
389 
390  //
391  // vector equivalent interface.
392  //
393 
397  bool
398  empty() const
399  {
400  return m_nameBlock.elements().empty();
401  }
402 
407  size_t
408  size() const
409  {
410  return m_nameBlock.elements_size();
411  }
412 
418  const Component&
419  get(ssize_t i) const
420  {
421  if (i >= 0)
422  return reinterpret_cast<const Component&>(m_nameBlock.elements()[i]);
423  else
424  return reinterpret_cast<const Component&>(m_nameBlock.elements()[size() + i]);
425  }
426 
427  const Component&
428  operator[](ssize_t i) const
429  {
430  return get(i);
431  }
432 
441  const Component&
442  at(ssize_t i) const
443  {
444  if ((i >= 0 && static_cast<size_t>(i) >= size()) ||
445  (i < 0 && static_cast<size_t>(-i) > size()))
446  BOOST_THROW_EXCEPTION(Error("Requested component does not exist (out of bounds)"));
447 
448  return get(i);
449  }
450 
473  int
474  compare(const Name& other) const
475  {
476  return this->compare(0, npos, other);
477  }
478 
484  int
485  compare(size_t pos1, size_t count1,
486  const Name& other, size_t pos2 = 0, size_t count2 = npos) const;
487 
492  template<class T> void
493  push_back(const T& component)
494  {
495  append(component);
496  }
497 
503  bool
504  operator==(const Name& name) const
505  {
506  return equals(name);
507  }
508 
514  bool
515  operator!=(const Name& name) const
516  {
517  return !equals(name);
518  }
519 
526  bool
527  operator<=(const Name& other) const
528  {
529  return compare(other) <= 0;
530  }
531 
538  bool
539  operator<(const Name& other) const
540  {
541  return compare(other) < 0;
542  }
543 
550  bool
551  operator>=(const Name& other) const
552  {
553  return compare(other) >= 0;
554  }
555 
562  bool
563  operator>(const Name& other) const
564  {
565  return compare(other) > 0;
566  }
567 
568  //
569  // Iterator interface to name components.
570  //
571 
575  const_iterator
576  begin() const
577  {
578  return reinterpret_cast<const_iterator>(&*m_nameBlock.elements().begin());
579  }
580 
586  const_iterator
587  end() const
588  {
589  return reinterpret_cast<const_iterator>(&*m_nameBlock.elements().end());
590  }
591 
595  const_reverse_iterator
596  rbegin() const
597  {
598  return const_reverse_iterator(end());
599  }
600 
604  const_reverse_iterator
605  rend() const
606  {
607  return const_reverse_iterator(begin());
608  }
609 
610 private:
611  void
612  construct(const char* uri);
613 
614 public:
617  static const size_t npos;
618 
619 private:
620  mutable Block m_nameBlock;
621 };
622 
623 std::ostream&
624 operator<<(std::ostream& os, const Name& name);
625 
626 std::istream&
627 operator>>(std::istream& is, Name& name);
628 
629 inline bool
631 {
632  return m_nameBlock.hasWire();
633 }
634 
635 } // namespace ndn
636 
637 namespace std {
638 template<>
639 struct hash<ndn::Name>
640 {
641  size_t
642  operator()(const ndn::Name& name) const;
643 };
644 
645 } // namespace std
646 
647 #endif
Copyright (c) 2011-2015 Regents of the University of California.
name::Component Component
Definition: name.hpp:62
bool operator!=(const Name &name) const
Check if this name has the same component count and components as the given name. ...
Definition: name.hpp:515
Component * pointer
Definition: name.hpp:70
const_iterator begin() const
Begin iterator (const).
Definition: name.hpp:576
Name & appendNumber(uint64_t number)
Append a component with the number encoded as nonNegativeInteger.
Definition: name.cpp:204
Name getSuccessor() const
Get the successor of a name.
Definition: name.cpp:293
Name & append(const char *value)
Append name component that represented as a string.
Definition: name.hpp:189
std::ostream & operator<<(std::ostream &os, const Data &data)
Definition: data.cpp:340
bool operator==(const Name &name) const
Check if this name has the same component count and components as the given name. ...
Definition: name.hpp:504
component_container::size_type size_type
Definition: name.hpp:79
const Component const_reference
Definition: name.hpp:69
Name & append(const Component &value)
Append component value.
Definition: name.hpp:175
static const size_t npos
indicates "until the end" in getSubName and compare
Definition: name.hpp:617
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
static time_point now() noexcept
Definition: time.cpp:45
Copyright (c) 2013-2014 Regents of the University of California.
const Component & operator[](ssize_t i) const
Definition: name.hpp:428
Name & appendSequenceNumber(uint64_t seqNo)
Append sequence number using NDN naming conventions.
Definition: name.cpp:253
Error that can be thrown from Name.
Definition: name.hpp:52
Component value_type
Definition: name.hpp:66
std::string toUri() const
Encode this name as a URI.
Definition: name.cpp:183
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:551
const Block & wireEncode() const
Definition: name.cpp:90
boost::reverse_iterator< iterator > reverse_iterator
Definition: name.hpp:75
Name & appendSegmentOffset(uint64_t offset)
Append segment byte offset using NDN naming conventions.
Definition: name.cpp:239
const_iterator end() const
End iterator (const).
Definition: name.hpp:587
const Component * const_iterator
Definition: name.hpp:73
const_reverse_iterator rend() const
Reverse end iterator (const).
Definition: name.hpp:605
Name & appendSegment(uint64_t segmentNo)
Append segment number (sequential) using NDN naming conventions.
Definition: name.cpp:232
bool hasWire() const
Check if already has wire.
Definition: name.hpp:630
Name & append(const Block &value)
Definition: name.hpp:196
const Component * const_pointer
Definition: name.hpp:71
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:527
Component * iterator
Definition: name.hpp:72
size_t size() const
Get the number of components.
Definition: name.hpp:408
Name & appendTimestamp(const time::system_clock::TimePoint &timePoint=time::system_clock::now())
Append timestamp using NDN naming conventions.
Definition: name.cpp:246
std::istream & operator>>(std::istream &is, Name &name)
Definition: name.cpp:370
Name abstraction to represent an absolute name.
Definition: name.hpp:46
Name & append(Iterator first, Iterator last)
Append a new component, copying from value frome the range [first, last) of bytes.
Definition: name.hpp:165
Error(const std::string &what)
Definition: name.hpp:56
void push_back(const T &component)
Append the component.
Definition: name.hpp:493
const_reverse_iterator rbegin() const
Reverse begin iterator (const).
Definition: name.hpp:596
uint32_t type() const
Definition: block.hpp:346
time_point TimePoint
Definition: time.hpp:78
Component holds a read-only name component value.
bool operator>(const Name &other) const
Return true if this is greater than the other Name in the NDN canonical ordering. ...
Definition: name.hpp:563
int compare(const Name &other) const
Compare this to the other Name using NDN canonical ordering.
Definition: name.hpp:474
bool operator<(const Name &other) const
Return true if this is less than the other Name in the NDN canonical ordering.
Definition: name.hpp:539
Name & appendNumberWithMarker(uint8_t marker, uint64_t number)
Create a component encoded as NameComponentWithMarker.
Definition: name.cpp:211
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:148
bool empty() const
Check if name is emtpy.
Definition: name.hpp:398
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:320
DEPRECATED(void set(const char *uri))
PartialName getSubName(ssize_t iStartComponent, size_t nComponents=npos) const
Extract a sub-name (PartialName) of nComponents components starting from iStartComponent.
Definition: name.cpp:274
PartialName getPrefix(ssize_t nComponents) const
Extract a prefix (PartialName) of the name, containing first nComponents components.
Definition: name.hpp:249
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
bool equals(const Name &name) const
Check if this name has the same component count and components as the given name. ...
Definition: name.cpp:306
shared_ptr< const Buffer > ConstBufferPtr
Definition: buffer.hpp:33
void wireDecode(const Block &wire)
Definition: name.cpp:108
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:218
const Component & at(ssize_t i) const
Get component at the specified index.
Definition: name.hpp:442
Name & appendVersion()
Append version using NDN naming conventions based on current UNIX timestamp in milliseconds.
Definition: name.cpp:225
Name()
Create a new Name with no components.
Definition: name.cpp:46
Error that can be thrown from name::Component.
Name & appendImplicitSha256Digest(const ConstBufferPtr &digest)
Append ImplicitSha256Digest.
Definition: name.cpp:260