ndn::Name Class Reference

Represents an absolute name. More...

#include <ndn-cxx/name.hpp>

Public Types

using allocator_type = void
 
using Component = name::Component
 
using component_container = std::vector< Component >
 
using const_iterator = const Component *
 
using const_pointer = const Component *
 
using const_reference = const Component &
 
using const_reverse_iterator = std::reverse_iterator< const_iterator >
 
using difference_type = component_container::difference_type
 
using Error = name::Component::Error
 
using iterator = const Component *
 
using pointer = Component *
 
using reference = Component &
 
using reverse_iterator = std::reverse_iterator< iterator >
 
using size_type = component_container::size_type
 
using value_type = Component
 

Public Member Functions

 Name ()
 Create an empty name. More...
 
 Name (const Block &wire)
 Decode Name from wire encoding. More...
 
 Name (const char *uri)
 Parse name from NDN URI. More...
 
 Name (std::string uri)
 Create name from NDN URI. More...
 
Nameappend (const Component &component)
 Append a component. More...
 
Nameappend (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. More...
 
Nameappend (const uint8_t *value, size_t count)
 Append a GenericNameComponent, copying count bytes at value as TLV-VALUE. More...
 
template<class Iterator >
Nameappend (uint32_t type, Iterator first, Iterator last)
 Append a NameComponent of TLV-TYPE type, copying TLV-VALUE from a range. More...
 
template<class Iterator >
Nameappend (Iterator first, Iterator last)
 Append a GenericNameComponent, copying TLV-VALUE from a range. More...
 
Nameappend (const char *str)
 Append a GenericNameComponent, copying TLV-VALUE from a null-terminated string. More...
 
Nameappend (const Block &value)
 Append a GenericNameComponent from a TLV element. More...
 
Nameappend (const PartialName &name)
 Append a PartialName. More...
 
NameappendByteOffset (uint64_t offset)
 Append a byte offset component. More...
 
NameappendImplicitSha256Digest (ConstBufferPtr digest)
 Append an ImplicitSha256Digest component. More...
 
NameappendImplicitSha256Digest (const uint8_t *digest, size_t digestSize)
 Append an ImplicitSha256Digest component. More...
 
NameappendNumber (uint64_t number)
 Append a component with a nonNegativeInteger. More...
 
NameappendNumberWithMarker (uint8_t marker, uint64_t number)
 Append a component with a marked number. More...
 
NameappendSegment (uint64_t segmentNo)
 Append a segment number (sequential) component. More...
 
NameappendSegmentOffset (uint64_t offset)
 
NameappendSequenceNumber (uint64_t seqNo)
 Append a sequence number component. More...
 
NameappendTimestamp (optional< time::system_clock::TimePoint > timestamp=nullopt)
 Append a timestamp component. More...
 
NameappendVersion (optional< uint64_t > version=nullopt)
 Append a version component. More...
 
const Componentat (ssize_t i) const
 Get the component at the given index. More...
 
const_iterator begin () const
 Begin iterator. More...
 
void clear ()
 Remove all components. More...
 
int compare (const Name &other) const
 Compare this to the other Name using NDN canonical ordering. More...
 
int compare (size_t pos1, size_t count1, const Name &other, size_t pos2=0, size_t count2=npos) const
 compares [pos1, pos1+count1) components in this Name to [pos2, pos2+count2) components in other More...
 
Name deepCopy () const
 Make a deep copy of the name, reallocating the underlying memory buffer. More...
 
bool empty () const
 Check if name is empty. More...
 
const_iterator end () const
 End iterator. More...
 
bool equals (const Name &other) const
 Check if this name equals another name. More...
 
const Componentget (ssize_t i) const
 Get the component at the given index. More...
 
PartialName getPrefix (ssize_t nComponents) const
 Extract a prefix of the name. More...
 
PartialName getSubName (ssize_t iStartComponent, size_t nComponents=npos) const
 Extract some components as a sub-name (PartialName) More...
 
Name getSuccessor () const
 Get the successor of a name. More...
 
bool hasWire () const
 Check if this Name instance already has wire encoding. More...
 
bool isPrefixOf (const Name &other) const
 Check if this name is a prefix of another name. More...
 
const Componentoperator[] (ssize_t i) const
 Equivalent to get(i) More...
 
template<class T >
void push_back (const T &component)
 Append a component. More...
 
const_reverse_iterator rbegin () const
 Reverse begin iterator. More...
 
const_reverse_iterator rend () const
 Reverse end iterator. More...
 
size_t size () const
 Get number of components. More...
 
std::string toUri () const
 Get URI representation of the name. More...
 
void wireDecode (const Block &wire)
 Decode name from wire encoding. More...
 
template<encoding::Tag TAG>
size_t wireEncode (EncodingImpl< TAG > &encoder) const
 Fast encoding or block size estimation. More...
 
const BlockwireEncode () const
 Perform wire encoding, or return existing wire encoding. More...
 

Static Public Attributes

static const size_t npos = std::numeric_limits<size_t>::max()
 indicates "until the end" in getSubName and compare More...
 

Detailed Description

Represents an absolute name.

Definition at line 43 of file name.hpp.

Member Typedef Documentation

Definition at line 53 of file name.hpp.

Definition at line 48 of file name.hpp.

Definition at line 49 of file name.hpp.

Definition at line 59 of file name.hpp.

Definition at line 57 of file name.hpp.

Definition at line 55 of file name.hpp.

using ndn::Name::const_reverse_iterator = std::reverse_iterator<const_iterator>

Definition at line 61 of file name.hpp.

using ndn::Name::difference_type = component_container::difference_type

Definition at line 62 of file name.hpp.

Definition at line 46 of file name.hpp.

Definition at line 58 of file name.hpp.

Definition at line 56 of file name.hpp.

Definition at line 54 of file name.hpp.

using ndn::Name::reverse_iterator = std::reverse_iterator<iterator>

Definition at line 60 of file name.hpp.

using ndn::Name::size_type = component_container::size_type

Definition at line 63 of file name.hpp.

Definition at line 52 of file name.hpp.

Constructor & Destructor Documentation

ndn::Name::Name ( )

Create an empty name.

Postcondition
empty() == true

Definition at line 54 of file name.cpp.

ndn::Name::Name ( const Block wire)
explicit

Decode Name from wire encoding.

Exceptions
tlv::Errorwire encoding is invalid

This is a more efficient equivalent for

Name name;
name.wireDecode(wire);

Definition at line 59 of file name.cpp.

ndn::Name::Name ( const char *  uri)

Parse name from NDN URI.

Parameters
uria null-terminated URI string
See also
https://named-data.net/doc/NDN-packet-spec/current/name.html#ndn-uri-scheme

Definition at line 65 of file name.cpp.

ndn::Name::Name ( std::string  uri)

Create name from NDN URI.

Parameters
uria URI string
See also
https://named-data.net/doc/NDN-packet-spec/current/name.html#ndn-uri-scheme

Definition at line 70 of file name.cpp.

Member Function Documentation

Name& ndn::Name::append ( const Component component)
inline

Append a component.

Returns
a reference to this name, to allow chaining.

Definition at line 249 of file name.hpp.

Name& ndn::Name::append ( uint32_t  type,
const uint8_t *  value,
size_t  count 
)
inline

Append a NameComponent of TLV-TYPE type, copying count bytes at value as TLV-VALUE.

Returns
a reference to this name, to allow chaining.

Definition at line 260 of file name.hpp.

Name& ndn::Name::append ( const uint8_t *  value,
size_t  count 
)
inline

Append a GenericNameComponent, copying count bytes at value as TLV-VALUE.

Returns
a reference to this name, to allow chaining.

Definition at line 269 of file name.hpp.

template<class Iterator >
Name& ndn::Name::append ( uint32_t  type,
Iterator  first,
Iterator  last 
)
inline

Append a NameComponent of TLV-TYPE type, copying TLV-VALUE from a range.

Template Parameters
Iteratoran InputIterator dereferencing to a one-octet value type. More efficient implementation is available when it is a RandomAccessIterator.
Parameters
typethe TLV-TYPE.
firstbeginning of the range.
lastpast-end of the range.
Returns
a reference to this name, to allow chaining.

Definition at line 284 of file name.hpp.

template<class Iterator >
Name& ndn::Name::append ( Iterator  first,
Iterator  last 
)
inline

Append a GenericNameComponent, copying TLV-VALUE from a range.

Template Parameters
Iteratoran InputIterator dereferencing to a one-octet value type. More efficient implementation is available when it is a RandomAccessIterator.
Parameters
firstbeginning of the range.
lastpast-end of the range.
Returns
a reference to this name, to allow chaining.

Definition at line 298 of file name.hpp.

Name& ndn::Name::append ( const char *  str)
inline

Append a GenericNameComponent, copying TLV-VALUE from a null-terminated string.

Parameters
stra null-terminated string. Bytes from the string are copied as is, and not interpreted as URI component.
Returns
a reference to this name, to allow chaining.

Definition at line 309 of file name.hpp.

Name& ndn::Name::append ( const Block value)
inline

Append a GenericNameComponent from a TLV element.

Parameters
valuea TLV element. If its type is tlv::GenericNameComponent, it is used as is. Otherwise, it is encapsulated into a GenericNameComponent.
Returns
a reference to this name, to allow chaining.

Definition at line 320 of file name.hpp.

Name & ndn::Name::append ( const PartialName name)

Append a PartialName.

Parameters
namethe components to append
Returns
a reference to this name, to allow chaining

Definition at line 226 of file name.cpp.

Name& ndn::Name::appendByteOffset ( uint64_t  offset)
inline

Append a byte offset component.

Returns
a reference to this name, to allow chaining
See also
NDN Naming Conventions https://named-data.net/doc/tech-memos/naming-conventions.pdf

Definition at line 381 of file name.hpp.

Name& ndn::Name::appendImplicitSha256Digest ( ConstBufferPtr  digest)
inline

Append an ImplicitSha256Digest component.

Returns
a reference to this name, to allow chaining

Definition at line 415 of file name.hpp.

Name& ndn::Name::appendImplicitSha256Digest ( const uint8_t *  digest,
size_t  digestSize 
)
inline

Append an ImplicitSha256Digest component.

Returns
a reference to this name, to allow chaining

Definition at line 424 of file name.hpp.

Name& ndn::Name::appendNumber ( uint64_t  number)
inline

Append a component with a nonNegativeInteger.

See also
number the number
Returns
a reference to this name, to allow chaining
See also
https://named-data.net/doc/NDN-packet-spec/current/tlv.html#non-negative-integer-encoding

Definition at line 337 of file name.hpp.

Name& ndn::Name::appendNumberWithMarker ( uint8_t  marker,
uint64_t  number 
)
inline

Append a component with a marked number.

Parameters
marker1-octet marker
numberthe number

The component is encoded as a 1-octet marker, followed by a nonNegativeInteger.

Returns
a reference to this name, to allow chaining
See also
NDN Naming Conventions https://named-data.net/doc/tech-memos/naming-conventions.pdf

Definition at line 352 of file name.hpp.

Name& ndn::Name::appendSegment ( uint64_t  segmentNo)
inline

Append a segment number (sequential) component.

Returns
a reference to this name, to allow chaining
See also
NDN Naming Conventions https://named-data.net/doc/tech-memos/naming-conventions.pdf

Definition at line 371 of file name.hpp.

Name& ndn::Name::appendSegmentOffset ( uint64_t  offset)
inline
Deprecated:
use appendByteOffset

Definition at line 388 of file name.hpp.

Name& ndn::Name::appendSequenceNumber ( uint64_t  seqNo)
inline

Append a sequence number component.

Returns
a reference to this name, to allow chaining
See also
NDN Naming Conventions https://named-data.net/doc/tech-memos/naming-conventions.pdf

Definition at line 406 of file name.hpp.

Name & ndn::Name::appendTimestamp ( optional< time::system_clock::TimePoint timestamp = nullopt)

Append a timestamp component.

Parameters
timestampthe timestamp to append; if nullopt, the current system time is used
Returns
a reference to this name, to allow chaining
See also
NDN Naming Conventions https://named-data.net/doc/tech-memos/naming-conventions.pdf

Definition at line 220 of file name.cpp.

Name & ndn::Name::appendVersion ( optional< uint64_t >  version = nullopt)

Append a version component.

Parameters
versionthe version number to append; if nullopt, the current UNIX time in milliseconds is used
Returns
a reference to this name, to allow chaining
See also
NDN Naming Conventions https://named-data.net/doc/tech-memos/naming-conventions.pdf

Definition at line 214 of file name.cpp.

const name::Component & ndn::Name::at ( ssize_t  i) const

Get the component at the given index.

Parameters
izero-based index; if negative, size()+i is used instead
Exceptions
Name::Errorindex is out of bounds

Definition at line 179 of file name.cpp.

const_iterator ndn::Name::begin ( ) const
inline

Begin iterator.

Definition at line 215 of file name.hpp.

void ndn::Name::clear ( )
inline

Remove all components.

Postcondition
empty() == true

Definition at line 450 of file name.hpp.

int ndn::Name::compare ( const Name other) const
inline

Compare this to the other Name using NDN canonical ordering.

If the first components of each name are not equal, this returns a negative value if the first comes before the second using the NDN canonical ordering for name components, or a positive value if it comes after. If they are equal, this compares the second components of each name, etc. If both names are the same up to the size of the shorter name, this returns a negative value if the first name is shorter than the second or a positive value if it is longer. For example, if you std::sort gives: /a/b/d /a/b/cc /c /c/a /bb . This is intuitive because all names with the prefix /a are next to each other. But it may be also be counter-intuitive because /c comes before /bb according to NDN canonical ordering since it is shorter.

Parameters
otherThe other Name to compare with.
Return values
negativethis comes before other in canonical ordering
zerothis equals other
positivethis comes after other in canonical ordering
See also
https://named-data.net/doc/NDN-packet-spec/current/name.html#canonical-order

Definition at line 524 of file name.hpp.

int ndn::Name::compare ( size_t  pos1,
size_t  count1,
const Name other,
size_t  pos2 = 0,
size_t  count2 = npos 
) const

compares [pos1, pos1+count1) components in this Name to [pos2, pos2+count2) components in other

This is equivalent to this->getSubName(pos1, count1).compare(other.getSubName(pos2, count2));

Definition at line 281 of file name.cpp.

Name ndn::Name::deepCopy ( ) const

Make a deep copy of the name, reallocating the underlying memory buffer.

Definition at line 168 of file name.cpp.

bool ndn::Name::empty ( ) const
inline

Check if name is empty.

Definition at line 139 of file name.hpp.

const_iterator ndn::Name::end ( ) const
inline

End iterator.

Definition at line 223 of file name.hpp.

bool ndn::Name::equals ( const Name other) const

Check if this name equals another name.

Two names are equal if they have the same number of components, and components at each index are equal.

Definition at line 267 of file name.cpp.

const Component& ndn::Name::get ( ssize_t  i) const
inline

Get the component at the given index.

Parameters
izero-based index; if negative, it starts at the end of this name
Warning
Indexing out of bounds triggers undefined behavior.

Definition at line 157 of file name.hpp.

PartialName ndn::Name::getPrefix ( ssize_t  nComponents) const
inline

Extract a prefix of the name.

Parameters
nComponentsNumber of components; if negative, size()+nComponents is used instead
Returns
a new Name containing the prefix the prefix up to name.size() - N. For example getPrefix(-1) returns the name without the final component.
A new partial name

Definition at line 203 of file name.hpp.

PartialName ndn::Name::getSubName ( ssize_t  iStartComponent,
size_t  nComponents = npos 
) const

Extract some components as a sub-name (PartialName)

Parameters
iStartComponentzero-based index of the first component; if negative, size()+iStartComponent is used instead
nComponentsNumber of components starting at iStartComponent. Use npos to get the PartialName until the end of this Name.
Returns
a new PartialName containing the extracted components

If iStartComponent is positive and indexes out of bounds, returns an empty PartialName. If iStartComponent is negative and indexes out of bounds, returns components starting from the beginning of the Name. If nComponents is out of bounds, returns the components until the end of this Name.

Definition at line 193 of file name.cpp.

Name ndn::Name::getSuccessor ( ) const

Get the successor of a name.

The successor of a name is defined as follows:

N represents the set of NDN Names, and X,Y ∈ N.
Operator < is defined by canonical order on N.
Y is the successor of X, if (a) X < Y, and (b) ∄ Z ∈ N s.t. X < Z < Y.

In plain words, successor of a name is the same name, but with its last component advanced to a next possible value.

Examples:

  • successor of / is /sha256digest=0000000000000000000000000000000000000000000000000000000000000000.
  • successor of /sha256digest=0000000000000000000000000000000000000000000000000000000000000000 is /sha256digest=0000000000000000000000000000000000000000000000000000000000000001.
  • successor of /sha256digest=ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff is /2=....
  • successor of /P/A is /P/B.
  • successor of /Q/FF is /Q/%00%00.
Returns
a new Name containing the successor

Definition at line 241 of file name.cpp.

bool ndn::Name::hasWire ( ) const
inline

Check if this Name instance already has wire encoding.

Definition at line 106 of file name.hpp.

bool ndn::Name::isPrefixOf ( const Name other) const

Check if this name is a prefix of another name.

This name is a prefix of other if the N components of this name are same as the first N components of other.

Return values
truethis name is a prefix of other
falsethis name is not a prefix of other

Definition at line 251 of file name.cpp.

const Component& ndn::Name::operator[] ( ssize_t  i) const
inline

Equivalent to get(i)

Definition at line 168 of file name.hpp.

template<class T >
void ndn::Name::push_back ( const T &  component)
inline

Append a component.

Note
This makes push_back an alias of append, giving Name a similar API as STL vector.

Definition at line 441 of file name.hpp.

const_reverse_iterator ndn::Name::rbegin ( ) const
inline

Reverse begin iterator.

Definition at line 231 of file name.hpp.

const_reverse_iterator ndn::Name::rend ( ) const
inline

Reverse end iterator.

Definition at line 239 of file name.hpp.

size_t ndn::Name::size ( ) const
inline

Get number of components.

Definition at line 147 of file name.hpp.

std::string ndn::Name::toUri ( ) const

Get URI representation of the name.

Returns
URI representation; "ndn:" scheme identifier is not included
See also
https://named-data.net/doc/NDN-packet-spec/current/name.html#ndn-uri-scheme
Note
To print URI representation into a stream, it is more efficient to use os << name.

Definition at line 116 of file name.cpp.

void ndn::Name::wireDecode ( const Block wire)

Decode name from wire encoding.

Exceptions
tlv::Errorwire encoding is invalid
Postcondition
hasWire() == true

Definition at line 158 of file name.cpp.

template<encoding::Tag TAG>
size_t ndn::Name::wireEncode ( EncodingImpl< TAG > &  encoder) const

Fast encoding or block size estimation.

Definition at line 125 of file name.cpp.

const Block & ndn::Name::wireEncode ( ) const

Perform wire encoding, or return existing wire encoding.

Postcondition
hasWire() == true

Definition at line 140 of file name.cpp.

Member Data Documentation

const size_t ndn::Name::npos = std::numeric_limits<size_t>::max()
static

indicates "until the end" in getSubName and compare

Definition at line 541 of file name.hpp.