ndn::name::Component Class Reference

Represents a name component. More...

#include <ndn-cxx/name-component.hpp>

+ Inheritance diagram for ndn::name::Component:
+ Collaboration diagram for ndn::name::Component:

Classes

class  Error
 

Public Types

using element_const_iterator = element_container::const_iterator
 
using element_container = std::vector< Block >
 
using element_iterator = element_container::iterator
 

Public Member Functions

 Component (const Block &wire)
 Construct a NameComponent from block. More...
 
 Component (const char *str)
 Construct a GenericNameComponent, copying TLV-VALUE from a null-terminated string. More...
 
 Component (const std::string &str)
 Construct a GenericNameComponent, copying TLV-VALUE from a string. More...
 
 Component (const uint8_t *value, size_t count)
 Construct a GenericNameComponent, copying count bytes at value as TLV-VALUE. More...
 
 Component (ConstBufferPtr buffer)
 Construct a GenericNameComponent, using TLV-VALUE from buffer. More...
 
template<class Iterator >
 Component (Iterator first, Iterator last)
 Construct a GenericNameComponent, copying TLV-VALUE from a range. More...
 
 Component (span< const uint8_t > buffer)
 Construct a GenericNameComponent, copying TLV-VALUE from buffer. More...
 
 Component (uint32_t type, const uint8_t *value, size_t count)
 Construct a NameComponent of TLV-TYPE type, copying count bytes at value as TLV-VALUE. More...
 
 Component (uint32_t type, ConstBufferPtr buffer)
 Construct a NameComponent of TLV-TYPE type, using TLV-VALUE from buffer. More...
 
template<class Iterator >
 Component (uint32_t type, Iterator first, Iterator last)
 Construct a NameComponent of TLV-TYPE type, copying TLV-VALUE from a range. More...
 
 Component (uint32_t type, span< const uint8_t > buffer)
 Construct a NameComponent of TLV-TYPE type, copying TLV-VALUE from buffer. More...
 
 Component (uint32_t type=tlv::GenericNameComponent)
 Construct a NameComponent of TLV-TYPE type and with empty TLV-VALUE. More...
 
Buffer::const_iterator begin () const
 Get begin iterator of encoded wire. More...
 
Block blockFromValue () const
 
int compare (const Component &other) const
 Compare this to the other Component using NDN canonical ordering. More...
 
const element_containerelements () const
 Get container of sub-elements. More...
 
element_const_iterator elements_begin () const
 Equivalent to elements().begin() More...
 
element_const_iterator elements_end () const
 Equivalent to elements().end() More...
 
size_t elements_size () const
 Equivalent to elements().size() More...
 
bool empty () const
 
void encode ()
 Encode sub-elements into TLV-VALUE. More...
 
Buffer::const_iterator end () const
 Get end iterator of encoded wire. More...
 
bool equals (const Component &other) const
 Check if this is the same component as other. More...
 
element_iterator erase (element_const_iterator first, element_const_iterator last)
 Erase a range of sub-elements. More...
 
element_iterator erase (element_const_iterator position)
 Erase a sub-element. More...
 
element_const_iterator find (uint32_t type) const
 Find the first sub-element of the specified TLV-TYPE. More...
 
const Blockget (uint32_t type) const
 Return the first sub-element of the specified TLV-TYPE. More...
 
ConstBufferPtr getBuffer () const
 Get underlying buffer. More...
 
Component getSuccessor () const
 Get the successor of this name component. More...
 
bool hasValue () const noexcept
 Check if the Block has a non-empty TLV-VALUE. More...
 
bool hasWire () const noexcept
 Check if the Block contains a fully encoded wire representation. More...
 
element_iterator insert (element_const_iterator pos, const Block &element)
 Insert a sub-element. More...
 
bool isByteOffset () const
 Check if the component is a byte offset per NDN naming conventions. More...
 
bool isGeneric () const
 Check if the component is GenericNameComponent. More...
 
bool isImplicitSha256Digest () const
 Check if the component is ImplicitSha256DigestComponent. More...
 
bool isNumber () const
 Check if the component is a NonNegativeInteger. More...
 
bool isNumberWithMarker (uint8_t marker) const
 Check if the component is a NameComponentWithMarker per NDN naming conventions rev1. More...
 
bool isParametersSha256Digest () const
 Check if the component is ParametersSha256DigestComponent. More...
 
bool isSegment () const
 Check if the component is a segment number per NDN naming conventions. More...
 
bool isSequenceNumber () const
 Check if the component is a sequence number per NDN naming conventions. More...
 
bool isTimestamp () const
 Check if the component is a timestamp per NDN naming conventions. More...
 
bool isValid () const noexcept
 Check if the Block is valid. More...
 
bool isVersion () const
 Check if the component is a version per NDN naming conventions. More...
 
 operator boost::asio::const_buffer () const
 Implicit conversion to boost::asio::const_buffer More...
 
void parse () const
 Parse TLV-VALUE into sub-elements. More...
 
void push_back (const Block &element)
 Append a sub-element. More...
 
void remove (uint32_t type)
 Remove all sub-elements of the specified TLV-TYPE. More...
 
void reset () noexcept
 Reset the Block to a default-constructed state. More...
 
void resetWire () noexcept
 Reset wire buffer but keep TLV-TYPE and sub-elements (if any) More...
 
size_t size () const
 Return the size of the encoded wire, i.e. More...
 
uint64_t toByteOffset () const
 Interpret as byte offset component using NDN naming conventions. More...
 
uint64_t toNumber () const
 Interpret this name component as NonNegativeInteger. More...
 
uint64_t toNumberWithMarker (uint8_t marker) const
 Interpret this name component as NameComponentWithMarker. More...
 
uint64_t toSegment () const
 Interpret as segment number component using NDN naming conventions. More...
 
uint64_t toSequenceNumber () const
 Interpret as sequence number component using NDN naming conventions. More...
 
time::system_clock::time_point toTimestamp () const
 Interpret as timestamp component using NDN naming conventions. More...
 
void toUri (std::ostream &os, UriFormat format=UriFormat::DEFAULT) const
 Write *this to the output stream, escaping characters according to the NDN URI format. More...
 
std::string toUri (UriFormat format=UriFormat::DEFAULT) const
 Convert *this by escaping characters according to the NDN URI format. More...
 
uint64_t toVersion () const
 Interpret as version component using NDN naming conventions. More...
 
uint32_t type () const
 Return the TLV-TYPE of the Block. More...
 
const uint8_t * value () const noexcept
 Return a raw pointer to the beginning of TLV-VALUE. More...
 
Buffer::const_iterator value_begin () const
 Get begin iterator of TLV-VALUE. More...
 
Buffer::const_iterator value_end () const
 Get end iterator of TLV-VALUE. More...
 
size_t value_size () const noexcept
 Return the size of TLV-VALUE, aka TLV-LENGTH. More...
 
const uint8_t * wire () const
 Return a raw pointer to the beginning of the encoded wire. More...
 
void wireDecode (const Block &wire)
 Decode from the wire format. More...
 
const BlockwireEncode () const
 Encode to a wire format. More...
 
template<encoding::Tag TAG>
size_t wireEncode (EncodingImpl< TAG > &encoder) const
 Fast encoding or block size estimation. More...
 

Static Public Member Functions

static std::tuple< bool, BlockfromBuffer (const uint8_t *buf, size_t bufSize)
 Try to parse Block from a raw buffer. More...
 
static std::tuple< bool, BlockfromBuffer (ConstBufferPtr buffer, size_t offset=0)
 Try to parse Block from a wire buffer. More...
 
static std::tuple< bool, BlockfromBuffer (span< const uint8_t > buffer)
 Try to parse Block from a byte range. More...
 
static Component fromByteOffset (uint64_t offset)
 Create a byte offset component using NDN naming conventions. More...
 
static Component fromEscapedString (const char *input)
 Decode NameComponent from a URI component. More...
 
static Component fromEscapedString (const char *input, size_t beginOffset, size_t endOffset)
 Decode NameComponent from a URI component. More...
 
static Component fromEscapedString (const std::string &input)
 Decode NameComponent from a URI component. More...
 
static Component fromImplicitSha256Digest (ConstBufferPtr digest)
 Create ImplicitSha256DigestComponent component. More...
 
static Component fromImplicitSha256Digest (span< const uint8_t > digest)
 Create ImplicitSha256DigestComponent component. More...
 
static Component fromNumber (uint64_t number, uint32_t type=tlv::GenericNameComponent)
 Create a component encoded as NonNegativeInteger. More...
 
static Component fromNumberWithMarker (uint8_t marker, uint64_t number)
 Create a component encoded as NameComponentWithMarker. More...
 
static Component fromParametersSha256Digest (ConstBufferPtr digest)
 Create ParametersSha256DigestComponent component. More...
 
static Component fromParametersSha256Digest (span< const uint8_t > digest)
 Create ParametersSha256DigestComponent component. More...
 
static Component fromSegment (uint64_t segmentNo)
 Create a segment number component using NDN naming conventions. More...
 
static Component fromSequenceNumber (uint64_t seqNo)
 Create a sequence number component using NDN naming conventions. More...
 
static Block fromStream (std::istream &is)
 Parse Block from an input stream. More...
 
static Component fromTimestamp (const time::system_clock::time_point &timePoint)
 Create a timestamp component using NDN naming conventions. More...
 
static Component fromVersion (uint64_t version)
 Create a version component using NDN naming conventions. More...
 

Protected Attributes

Buffer::const_iterator m_begin
 
shared_ptr< const Bufferm_buffer
 Underlying buffer storing TLV-VALUE and possibly TLV-TYPE and TLV-LENGTH fields. More...
 
element_container m_elements
 Contains the sub-elements. More...
 
Buffer::const_iterator m_end
 
size_t m_size = 0
 Total size including Type-Length-Value. More...
 
uint32_t m_type = tlv::Invalid
 TLV-TYPE. More...
 
Buffer::const_iterator m_valueBegin
 
Buffer::const_iterator m_valueEnd
 

Friends

bool operator!= (const Component &lhs, const Component &rhs)
 
bool operator< (const Component &lhs, const Component &rhs)
 
std::ostream & operator<< (std::ostream &os, const Component &component)
 
bool operator<= (const Component &lhs, const Component &rhs)
 
bool operator== (const Component &lhs, const Component &rhs)
 
bool operator> (const Component &lhs, const Component &rhs)
 
bool operator>= (const Component &lhs, const Component &rhs)
 

Detailed Description

Represents a name component.

The Component class provides a read-only view of a Block interpreted as a name component. Although it inherits mutation methods from the Block base class, they must not be used, because the enclosing Name would not be updated correctly.

A name component is considered invalid if its TLV-TYPE is outside the range [1, 65535], or, if it is an ImplicitSha256DigestComponent or a ParametersSha256DigestComponent, its TLV-LENGTH is not 32.

Definition at line 107 of file name-component.hpp.

Member Typedef Documentation

◆ element_const_iterator

using ndn::Block::element_const_iterator = element_container::const_iterator
inherited

Definition at line 49 of file block.hpp.

◆ element_container

using ndn::Block::element_container = std::vector<Block>
inherited

Definition at line 47 of file block.hpp.

◆ element_iterator

using ndn::Block::element_iterator = element_container::iterator
inherited

Definition at line 48 of file block.hpp.

Constructor & Destructor Documentation

◆ Component() [1/12]

ndn::name::Component::Component ( uint32_t  type = tlv::GenericNameComponent)
explicit

Construct a NameComponent of TLV-TYPE type and with empty TLV-VALUE.

Exceptions
Errorthe NameComponent is invalid.

Definition at line 128 of file name-component.cpp.

◆ Component() [2/12]

ndn::name::Component::Component ( const Block wire)

Construct a NameComponent from block.

Exceptions
Errorthe NameComponent is invalid.

This contructor enables implicit conversion from a Block.

Definition at line 134 of file name-component.cpp.

◆ Component() [3/12]

ndn::name::Component::Component ( uint32_t  type,
ConstBufferPtr  buffer 
)

Construct a NameComponent of TLV-TYPE type, using TLV-VALUE from buffer.

Exceptions
Errorthe NameComponent is invalid.

This constructor does not copy the underlying buffer, but retains a pointer to it. Therefore, the caller must not change the underlying buffer.

Definition at line 140 of file name-component.cpp.

◆ Component() [4/12]

ndn::name::Component::Component ( ConstBufferPtr  buffer)
inlineexplicit

Construct a GenericNameComponent, using TLV-VALUE from buffer.

Exceptions
Errorthe NameComponent is invalid.

This constructor does not copy the underlying buffer, but retains a pointer to it. Therefore, the caller must not change the underlying buffer.

Definition at line 149 of file name-component.hpp.

◆ Component() [5/12]

ndn::name::Component::Component ( uint32_t  type,
span< const uint8_t >  buffer 
)

Construct a NameComponent of TLV-TYPE type, copying TLV-VALUE from buffer.

Definition at line 146 of file name-component.cpp.

◆ Component() [6/12]

ndn::name::Component::Component ( span< const uint8_t >  buffer)
inlineexplicit

Construct a GenericNameComponent, copying TLV-VALUE from buffer.

Definition at line 163 of file name-component.hpp.

◆ Component() [7/12]

ndn::name::Component::Component ( uint32_t  type,
const uint8_t *  value,
size_t  count 
)
inline

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

Definition at line 172 of file name-component.hpp.

◆ Component() [8/12]

ndn::name::Component::Component ( const uint8_t *  value,
size_t  count 
)
inline

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

Definition at line 180 of file name-component.hpp.

◆ Component() [9/12]

template<class Iterator >
ndn::name::Component::Component ( uint32_t  type,
Iterator  first,
Iterator  last 
)
inline

Construct 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.

Definition at line 194 of file name-component.hpp.

◆ Component() [10/12]

template<class Iterator >
ndn::name::Component::Component ( Iterator  first,
Iterator  last 
)
inline

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

Definition at line 203 of file name-component.hpp.

◆ Component() [11/12]

ndn::name::Component::Component ( const char *  str)
explicit

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

Bytes from the string are copied as is, and not interpreted as URI component.

Definition at line 152 of file name-component.cpp.

◆ Component() [12/12]

ndn::name::Component::Component ( const std::string &  str)
explicit

Construct a GenericNameComponent, copying TLV-VALUE from a string.

Bytes from the string are copied as is, and not interpreted as URI component.

Definition at line 157 of file name-component.cpp.

Member Function Documentation

◆ begin()

Buffer::const_iterator ndn::Block::begin ( ) const
inherited

Get begin iterator of encoded wire.

Precondition
hasWire() == true

Definition at line 278 of file block.cpp.

◆ blockFromValue()

Block ndn::Block::blockFromValue ( ) const
inherited

Definition at line 329 of file block.cpp.

◆ compare()

int ndn::name::Component::compare ( const Component other) const

Compare this to the other Component using NDN canonical ordering.

Parameters
otherThe other Component 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 480 of file name-component.cpp.

◆ elements()

const element_container& ndn::Block::elements ( ) const
inlineinherited

Get container of sub-elements.

Precondition
parse() has been executed

Definition at line 402 of file block.hpp.

◆ elements_begin()

element_const_iterator ndn::Block::elements_begin ( ) const
inlineinherited

Equivalent to elements().begin()

Definition at line 410 of file block.hpp.

◆ elements_end()

element_const_iterator ndn::Block::elements_end ( ) const
inlineinherited

Equivalent to elements().end()

Definition at line 418 of file block.hpp.

◆ elements_size()

size_t ndn::Block::elements_size ( ) const
inlineinherited

Equivalent to elements().size()

Definition at line 426 of file block.hpp.

◆ empty()

bool ndn::name::Component::empty ( ) const
inline

Definition at line 529 of file name-component.hpp.

◆ encode()

void ndn::Block::encode ( )
inherited

Encode sub-elements into TLV-VALUE.

Postcondition
TLV-VALUE contains sub-elements from elements()

Definition at line 368 of file block.cpp.

◆ end()

Buffer::const_iterator ndn::Block::end ( ) const
inherited

Get end iterator of encoded wire.

Precondition
hasWire() == true

Definition at line 287 of file block.cpp.

◆ equals()

bool ndn::name::Component::equals ( const Component other) const

Check if this is the same component as other.

Parameters
otherThe other Component to compare with
Returns
true if the components are equal, otherwise false.

Definition at line 472 of file name-component.cpp.

◆ erase() [1/2]

Block::element_iterator ndn::Block::erase ( Block::element_const_iterator  first,
Block::element_const_iterator  last 
)
inherited

Erase a range of sub-elements.

Definition at line 465 of file block.cpp.

◆ erase() [2/2]

Block::element_iterator ndn::Block::erase ( Block::element_const_iterator  position)
inherited

Erase a sub-element.

Definition at line 458 of file block.cpp.

◆ find()

Block::element_const_iterator ndn::Block::find ( uint32_t  type) const
inherited

Find the first sub-element of the specified TLV-TYPE.

Precondition
parse() has been executed
Returns
iterator in elements() to the found sub-element, or elements_end() if no such sub-element exists in elements()

Definition at line 441 of file block.cpp.

◆ fromBuffer() [1/3]

std::tuple< bool, Block > ndn::Block::fromBuffer ( const uint8_t *  buf,
size_t  bufSize 
)
staticinherited

Try to parse Block from a raw buffer.

Parameters
bufpointer to the first octet of a TLV element
bufSizesize of the raw buffer; may be greater than the actual size of the TLV element
Returns
true and the parsed Block if parsing succeeds; otherwise false and an invalid Block
Note
This overload copies the TLV element octets to an internal buffer.
This function does not throw upon decoding failure.
Deprecated:

Definition at line 225 of file block.cpp.

◆ fromBuffer() [2/3]

std::tuple< bool, Block > ndn::Block::fromBuffer ( ConstBufferPtr  buffer,
size_t  offset = 0 
)
staticinherited

Try to parse Block from a wire buffer.

Parameters
buffera Buffer containing a TLV element at offset offset
offsetbegin position of the TLV element within buffer
Returns
true and the parsed Block if parsing succeeds; otherwise false and an invalid Block
Note
This function does not throw upon decoding failure.

Definition at line 167 of file block.cpp.

◆ fromBuffer() [3/3]

std::tuple< bool, Block > ndn::Block::fromBuffer ( span< const uint8_t >  buffer)
staticinherited

Try to parse Block from a byte range.

Parameters
buffersequence of bytes containing a TLV element; the element must be found at the beginning of the buffer but does not need to span the entire buffer
Returns
true and the parsed Block if parsing succeeds; otherwise false and an invalid Block
Note
This overload copies the TLV element octets to an internal buffer.
This function does not throw upon decoding failure.

Definition at line 195 of file block.cpp.

◆ fromByteOffset()

Component ndn::name::Component::fromByteOffset ( uint64_t  offset)
static

Create a byte offset component using NDN naming conventions.

See also
https://named-data.net/publications/techreports/ndn-tr-22-3-ndn-memo-naming-conventions/

Definition at line 401 of file name-component.cpp.

◆ fromEscapedString() [1/3]

static Component ndn::name::Component::fromEscapedString ( const char *  input)
inlinestatic

Decode NameComponent from a URI component.

Exceptions
ErrorURI component does not represent a valid NameComponent.

Definition at line 262 of file name-component.hpp.

◆ fromEscapedString() [2/3]

static Component ndn::name::Component::fromEscapedString ( const char *  input,
size_t  beginOffset,
size_t  endOffset 
)
inlinestatic

Decode NameComponent from a URI component.

The URI component is read from [input+beginOffset, input+endOffset) range.

Exceptions
ErrorURI component does not represent a valid NameComponent.

Definition at line 252 of file name-component.hpp.

◆ fromEscapedString() [3/3]

Component ndn::name::Component::fromEscapedString ( const std::string &  input)
static

Decode NameComponent from a URI component.

Exceptions
ErrorURI component does not represent a valid NameComponent.

Definition at line 178 of file name-component.cpp.

◆ fromImplicitSha256Digest() [1/2]

Component ndn::name::Component::fromImplicitSha256Digest ( ConstBufferPtr  digest)
static

Create ImplicitSha256DigestComponent component.

Definition at line 440 of file name-component.cpp.

◆ fromImplicitSha256Digest() [2/2]

Component ndn::name::Component::fromImplicitSha256Digest ( span< const uint8_t >  digest)
static

Create ImplicitSha256DigestComponent component.

Definition at line 446 of file name-component.cpp.

◆ fromNumber()

Component ndn::name::Component::fromNumber ( uint64_t  number,
uint32_t  type = tlv::GenericNameComponent 
)
static

Create a component encoded as NonNegativeInteger.

See also
https://named-data.net/doc/NDN-packet-spec/current/tlv.html#non-negative-integer-encoding
Parameters
numberThe non-negative number
typeTLV-TYPE

Definition at line 360 of file name-component.cpp.

◆ fromNumberWithMarker()

Component ndn::name::Component::fromNumberWithMarker ( uint8_t  marker,
uint64_t  number 
)
static

Create a component encoded as NameComponentWithMarker.

NameComponentWithMarker is defined as:

NameComponentWithMarker ::= NAME-COMPONENT-TYPE TLV-LENGTH
                              Marker
                              includedNonNegativeInteger
Marker ::= BYTE
includedNonNegativeInteger ::= BYTE{1,2,4,8}
See also
NDN Naming Conventions revision 1 (obsolete) https://named-data.net/wp-content/uploads/2014/08/ndn-tr-22-ndn-memo-naming-conventions.pdf
Parameters
marker1-byte marker octet
numberThe non-negative number

Definition at line 366 of file name-component.cpp.

◆ fromParametersSha256Digest() [1/2]

Component ndn::name::Component::fromParametersSha256Digest ( ConstBufferPtr  digest)
static

Create ParametersSha256DigestComponent component.

Definition at line 458 of file name-component.cpp.

◆ fromParametersSha256Digest() [2/2]

Component ndn::name::Component::fromParametersSha256Digest ( span< const uint8_t >  digest)
static

Create ParametersSha256DigestComponent component.

Definition at line 464 of file name-component.cpp.

◆ fromSegment()

Component ndn::name::Component::fromSegment ( uint64_t  segmentNo)
static

Create a segment number component using NDN naming conventions.

See also
https://named-data.net/publications/techreports/ndn-tr-22-3-ndn-memo-naming-conventions/

Definition at line 393 of file name-component.cpp.

◆ fromSequenceNumber()

Component ndn::name::Component::fromSequenceNumber ( uint64_t  seqNo)
static

Create a sequence number component using NDN naming conventions.

See also
https://named-data.net/publications/techreports/ndn-tr-22-3-ndn-memo-naming-conventions/

Definition at line 418 of file name-component.cpp.

◆ fromStream()

Block ndn::Block::fromStream ( std::istream &  is)
staticinherited

Parse Block from an input stream.

Exceptions
tlv::ErrorTLV-LENGTH is zero or exceeds upper bound
Warning
If decoding fails, bytes are still consumed from the input stream.

Definition at line 231 of file block.cpp.

◆ fromTimestamp()

Component ndn::name::Component::fromTimestamp ( const time::system_clock::time_point timePoint)
static

Create a timestamp component using NDN naming conventions.

See also
https://named-data.net/publications/techreports/ndn-tr-22-3-ndn-memo-naming-conventions/

Definition at line 409 of file name-component.cpp.

◆ fromVersion()

Component ndn::name::Component::fromVersion ( uint64_t  version)
static

Create a version component using NDN naming conventions.

See also
https://named-data.net/publications/techreports/ndn-tr-22-3-ndn-memo-naming-conventions/

Definition at line 385 of file name-component.cpp.

◆ get()

const Block & ndn::Block::get ( uint32_t  type) const
inherited

Return the first sub-element of the specified TLV-TYPE.

Precondition
parse() has been executed
Exceptions
tlv::Errora sub-element of the specified type does not exist

Definition at line 429 of file block.cpp.

◆ getBuffer()

ConstBufferPtr ndn::Block::getBuffer ( ) const
inlineinherited

Get underlying buffer.

Definition at line 275 of file block.hpp.

◆ getSuccessor()

Component ndn::name::Component::getSuccessor ( ) const

Get the successor of this name component.

The successor of a name component is defined as follows:

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

In plain words, successor of a name component is the next possible name component.

Examples:

  • successor of sha256digest=0000000000000000000000000000000000000000000000000000000000000000 is sha256digest=0000000000000000000000000000000000000000000000000000000000000001.
  • successor of sha256digest=ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff is params-sha256=0000000000000000000000000000000000000000000000000000000000000000.
  • successor of params-sha256=0000000000000000000000000000000000000000000000000000000000000000 is params-sha256=0000000000000000000000000000000000000000000000000000000000000001.
  • successor of params-sha256=ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff is 3=....
  • successor of ... is %00.
  • successor of A is B.
  • successor of FF is %00%00.

Definition at line 505 of file name-component.cpp.

◆ hasValue()

bool ndn::Block::hasValue ( ) const
inlinenoexceptinherited

Check if the Block has a non-empty TLV-VALUE.

This property reflects whether the underlying buffer contains a TLV-VALUE. If this is false, TLV-VALUE has zero-length. If this is true, TLV-VALUE may be zero-length.

See also
value_size()

Definition at line 298 of file block.hpp.

◆ hasWire()

bool ndn::Block::hasWire ( ) const
inlinenoexceptinherited

Check if the Block contains a fully encoded wire representation.

A Block has a fully encoded wire if the underlying buffer exists and contains the full Type-Length-Value instead of just the TLV-VALUE field.

Definition at line 241 of file block.hpp.

◆ insert()

Block::element_iterator ndn::Block::insert ( Block::element_const_iterator  pos,
const Block element 
)
inherited

Insert a sub-element.

Parameters
posposition of the new sub-element
elementnew sub-element to insert
Returns
iterator in elements() to the new sub-element

Definition at line 479 of file block.cpp.

◆ isByteOffset()

bool ndn::name::Component::isByteOffset ( ) const

Check if the component is a byte offset per NDN naming conventions.

See also
https://named-data.net/publications/techreports/ndn-tr-22-3-ndn-memo-naming-conventions/

Definition at line 251 of file name-component.cpp.

◆ isGeneric()

bool ndn::name::Component::isGeneric ( ) const

Check if the component is GenericNameComponent.

Definition at line 428 of file name-component.cpp.

◆ isImplicitSha256Digest()

bool ndn::name::Component::isImplicitSha256Digest ( ) const

Check if the component is ImplicitSha256DigestComponent.

Definition at line 434 of file name-component.cpp.

◆ isNumber()

bool ndn::name::Component::isNumber ( ) const

Check if the component is a NonNegativeInteger.

See also
https://named-data.net/doc/NDN-packet-spec/current/tlv.html#non-negative-integer-encoding

Definition at line 223 of file name-component.cpp.

◆ isNumberWithMarker()

bool ndn::name::Component::isNumberWithMarker ( uint8_t  marker) const

Check if the component is a NameComponentWithMarker per NDN naming conventions rev1.

See also
NDN Naming Conventions revision 1 (obsolete) https://named-data.net/wp-content/uploads/2014/08/ndn-tr-22-ndn-memo-naming-conventions.pdf

Definition at line 230 of file name-component.cpp.

◆ isParametersSha256Digest()

bool ndn::name::Component::isParametersSha256Digest ( ) const

Check if the component is ParametersSha256DigestComponent.

Definition at line 452 of file name-component.cpp.

◆ isSegment()

bool ndn::name::Component::isSegment ( ) const

Check if the component is a segment number per NDN naming conventions.

See also
https://named-data.net/publications/techreports/ndn-tr-22-3-ndn-memo-naming-conventions/

Definition at line 244 of file name-component.cpp.

◆ isSequenceNumber()

bool ndn::name::Component::isSequenceNumber ( ) const

Check if the component is a sequence number per NDN naming conventions.

See also
https://named-data.net/publications/techreports/ndn-tr-22-3-ndn-memo-naming-conventions/

Definition at line 265 of file name-component.cpp.

◆ isTimestamp()

bool ndn::name::Component::isTimestamp ( ) const

Check if the component is a timestamp per NDN naming conventions.

See also
https://named-data.net/publications/techreports/ndn-tr-22-3-ndn-memo-naming-conventions/

Definition at line 258 of file name-component.cpp.

◆ isValid()

bool ndn::Block::isValid ( ) const
inlinenoexceptinherited

Check if the Block is valid.

A Block is valid unless it has an invalid TLV-TYPE or is default-constructed. In particular, a Block with zero-length TLV-VALUE is valid.

Definition at line 212 of file block.hpp.

◆ isVersion()

bool ndn::name::Component::isVersion ( ) const

Check if the component is a version per NDN naming conventions.

See also
https://named-data.net/publications/techreports/ndn-tr-22-3-ndn-memo-naming-conventions/

Definition at line 237 of file name-component.cpp.

◆ operator boost::asio::const_buffer()

ndn::Block::operator boost::asio::const_buffer ( ) const
inherited

Implicit conversion to boost::asio::const_buffer

Definition at line 487 of file block.cpp.

◆ parse()

void ndn::Block::parse ( ) const
inherited

Parse TLV-VALUE into sub-elements.

Postcondition
elements() reflects sub-elements found in TLV-VALUE
Exceptions
tlv::ErrorTLV-VALUE is not a sequence of TLV elements
Note
This method does not perform recursive parsing.
This method has no effect if elements() is already populated.
This method is not really const, but it does not modify any data.

Definition at line 341 of file block.cpp.

◆ push_back()

void ndn::Block::push_back ( const Block element)
inherited

Append a sub-element.

Definition at line 472 of file block.cpp.

◆ remove()

void ndn::Block::remove ( uint32_t  type)
inherited

Remove all sub-elements of the specified TLV-TYPE.

Precondition
parse() has been executed
Postcondition
find(type) == elements_end()

Definition at line 448 of file block.cpp.

◆ reset()

void ndn::Block::reset ( )
noexceptinherited

Reset the Block to a default-constructed state.

Equivalent to *this = Block().

Postcondition
isValid() == false
See also
resetWire()

Definition at line 265 of file block.cpp.

◆ resetWire()

void ndn::Block::resetWire ( )
noexceptinherited

Reset wire buffer but keep TLV-TYPE and sub-elements (if any)

Postcondition
hasWire() == false
hasValue() == false
See also
reset()

Definition at line 271 of file block.cpp.

◆ size()

size_t ndn::Block::size ( ) const
inherited

Return the size of the encoded wire, i.e.

of the whole TLV

Precondition
isValid() == true
See also
value_size()

Definition at line 305 of file block.cpp.

◆ toByteOffset()

uint64_t ndn::name::Component::toByteOffset ( ) const

Interpret as byte offset component using NDN naming conventions.

See also
https://named-data.net/publications/techreports/ndn-tr-22-3-ndn-memo-naming-conventions/
Exceptions
tlv::Errornot a ByteOffset component interpreted by the chosen convention(s).

Definition at line 318 of file name-component.cpp.

◆ toNumber()

uint64_t ndn::name::Component::toNumber ( ) const

Interpret this name component as NonNegativeInteger.

See also
https://named-data.net/doc/NDN-packet-spec/current/tlv.html#non-negative-integer-encoding
Returns
The integer number.

Definition at line 274 of file name-component.cpp.

◆ toNumberWithMarker()

uint64_t ndn::name::Component::toNumberWithMarker ( uint8_t  marker) const

Interpret this name component as NameComponentWithMarker.

See also
NDN Naming Conventions revision 1 (obsolete) https://named-data.net/wp-content/uploads/2014/08/ndn-tr-22-ndn-memo-naming-conventions.pdf
Parameters
marker1-byte octet of the marker
Returns
The integer number.
Exceptions
Errorif name component does not have the specified marker. tlv::Error if format does not follow NameComponentWithMarker specification.

Definition at line 283 of file name-component.cpp.

◆ toSegment()

uint64_t ndn::name::Component::toSegment ( ) const

Interpret as segment number component using NDN naming conventions.

See also
https://named-data.net/publications/techreports/ndn-tr-22-3-ndn-memo-naming-conventions/
Exceptions
tlv::Errornot a Segment component interpreted by the chosen convention(s).

Definition at line 306 of file name-component.cpp.

◆ toSequenceNumber()

uint64_t ndn::name::Component::toSequenceNumber ( ) const

Interpret as sequence number component using NDN naming conventions.

See also
https://named-data.net/publications/techreports/ndn-tr-22-3-ndn-memo-naming-conventions/
Exceptions
tlv::Errornot a SequenceNumber component interpreted by the chosen convention(s).

Definition at line 346 of file name-component.cpp.

◆ toTimestamp()

time::system_clock::time_point ndn::name::Component::toTimestamp ( ) const

Interpret as timestamp component using NDN naming conventions.

See also
https://named-data.net/publications/techreports/ndn-tr-22-3-ndn-memo-naming-conventions/
Exceptions
tlv::Errornot a Timestamp component interpreted by the chosen convention(s).

Definition at line 330 of file name-component.cpp.

◆ toUri() [1/2]

void ndn::name::Component::toUri ( std::ostream &  os,
UriFormat  format = UriFormat::DEFAULT 
) const

Write *this to the output stream, escaping characters according to the NDN URI format.

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

Definition at line 202 of file name-component.cpp.

◆ toUri() [2/2]

std::string ndn::name::Component::toUri ( UriFormat  format = UriFormat::DEFAULT) const

Convert *this by escaping characters according to the NDN URI format.

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

Definition at line 213 of file name-component.cpp.

◆ toVersion()

uint64_t ndn::name::Component::toVersion ( ) const

Interpret as version component using NDN naming conventions.

See also
https://named-data.net/publications/techreports/ndn-tr-22-3-ndn-memo-naming-conventions/
Exceptions
tlv::Errornot a Version component interpreted by the chosen convention(s).

Definition at line 294 of file name-component.cpp.

◆ type()

uint32_t ndn::Block::type ( ) const
inlineinherited

Return the TLV-TYPE of the Block.

Note
This will return tlv::Invalid if isValid() is false.

Definition at line 285 of file block.hpp.

◆ value()

const uint8_t * ndn::Block::value ( ) const
noexceptinherited

Return a raw pointer to the beginning of TLV-VALUE.

See also
wire()

Definition at line 317 of file block.cpp.

◆ value_begin()

Buffer::const_iterator ndn::Block::value_begin ( ) const
inlineinherited

Get begin iterator of TLV-VALUE.

Precondition
hasValue() == true

Definition at line 307 of file block.hpp.

◆ value_end()

Buffer::const_iterator ndn::Block::value_end ( ) const
inlineinherited

Get end iterator of TLV-VALUE.

Precondition
hasValue() == true

Definition at line 316 of file block.hpp.

◆ value_size()

size_t ndn::Block::value_size ( ) const
noexceptinherited

Return the size of TLV-VALUE, aka TLV-LENGTH.

See also
size()

Definition at line 323 of file block.cpp.

◆ wire()

const uint8_t * ndn::Block::wire ( ) const
inherited

Return a raw pointer to the beginning of the encoded wire.

Precondition
hasWire() == true
See also
value()

Definition at line 296 of file block.cpp.

◆ wireDecode()

void ndn::name::Component::wireDecode ( const Block wire)

Decode from the wire format.

Definition at line 550 of file name-component.cpp.

◆ wireEncode() [1/2]

const Block & ndn::name::Component::wireEncode ( ) const

Encode to a wire format.

Definition at line 534 of file name-component.cpp.

◆ wireEncode() [2/2]

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

Fast encoding or block size estimation.

Definition at line 521 of file name-component.cpp.

Friends And Related Function Documentation

◆ operator!=

bool operator!= ( const Component lhs,
const Component rhs 
)
friend

Definition at line 602 of file name-component.hpp.

◆ operator<

bool operator< ( const Component lhs,
const Component rhs 
)
friend

Definition at line 607 of file name-component.hpp.

◆ operator<<

std::ostream& operator<< ( std::ostream &  os,
const Component component 
)
friend

Definition at line 631 of file name-component.hpp.

◆ operator<=

bool operator<= ( const Component lhs,
const Component rhs 
)
friend

Definition at line 613 of file name-component.hpp.

◆ operator==

bool operator== ( const Component lhs,
const Component rhs 
)
friend

Definition at line 596 of file name-component.hpp.

◆ operator>

bool operator> ( const Component lhs,
const Component rhs 
)
friend

Definition at line 620 of file name-component.hpp.

◆ operator>=

bool operator>= ( const Component lhs,
const Component rhs 
)
friend

Definition at line 626 of file name-component.hpp.

Member Data Documentation

◆ m_begin

Buffer::const_iterator ndn::Block::m_begin
protectedinherited
See also
m_buffer

Definition at line 464 of file block.hpp.

◆ m_buffer

shared_ptr<const Buffer> ndn::Block::m_buffer
protectedinherited

Underlying buffer storing TLV-VALUE and possibly TLV-TYPE and TLV-LENGTH fields.

If m_buffer is nullptr, this is an invalid or zero-length Block with TLV-TYPE given in m_type. Otherwise,

  • [m_valueBegin, m_valueEnd) point to the TLV-VALUE inside m_buffer.
  • If m_begin != m_end, [m_begin, m_end) point to Type-Length-Value of this Block in m_buffer. Otherwise, m_buffer does not contain TLV-TYPE and TLV-LENGTH fields.

Definition at line 463 of file block.hpp.

◆ m_elements

element_container ndn::Block::m_elements
mutableprotectedinherited

Contains the sub-elements.

This field is valid only if parse() has been executed.

Definition at line 482 of file block.hpp.

◆ m_end

Buffer::const_iterator ndn::Block::m_end
protectedinherited
See also
m_buffer

Definition at line 465 of file block.hpp.

◆ m_size

size_t ndn::Block::m_size = 0
protectedinherited

Total size including Type-Length-Value.

This field is meaningful only if isValid() is true.

Definition at line 476 of file block.hpp.

◆ m_type

uint32_t ndn::Block::m_type = tlv::Invalid
protectedinherited

TLV-TYPE.

Definition at line 470 of file block.hpp.

◆ m_valueBegin

Buffer::const_iterator ndn::Block::m_valueBegin
protectedinherited
See also
m_buffer

Definition at line 467 of file block.hpp.

◆ m_valueEnd

Buffer::const_iterator ndn::Block::m_valueEnd
protectedinherited
See also
m_buffer

Definition at line 468 of file block.hpp.