name: allow appending typed name components
This commit also adds test coverage for Name::isPrefixOf and
Name comparison operators.
refs #4526
Change-Id: I93996adb97408cbeec0a8b0fd06c3a12cbf5a78f
diff --git a/src/name-component.hpp b/src/name-component.hpp
index 4e3563c..1f5e16c 100644
--- a/src/name-component.hpp
+++ b/src/name-component.hpp
@@ -62,7 +62,7 @@
public: // constructors
/**
- * @brief Construct a NameComponent of @p type, using empty TLV-VALUE.
+ * @brief Construct a NameComponent of TLV-TYPE @p type, using empty TLV-VALUE.
* @throw Error the NameComponent is invalid (see @c ensureValid).
*/
explicit
@@ -77,7 +77,7 @@
Component(const Block& wire);
/**
- * @brief Construct a NameComponent of @p type, using TLV-VALUE from @p buffer.
+ * @brief Construct a NameComponent of TLV-TYPE @p type, using TLV-VALUE from @p buffer.
* @throw Error the NameComponent is invalid (see @c ensureValid).
*
* This constructor does not copy the underlying buffer, but retains a pointer to it.
@@ -99,7 +99,7 @@
}
/**
- * @brief Construct a NameComponent of @p type, copying TLV-VALUE from @p buffer.
+ * @brief Construct a NameComponent of TLV-TYPE @p type, copying TLV-VALUE from @p buffer.
*/
Component(uint32_t type, const Buffer& buffer)
: Component(type, buffer.data(), buffer.size())
@@ -116,7 +116,8 @@
}
/**
- * @brief Construct a NameComponent of @p type, copying @p count bytes at @p value as TLV-VALUE.
+ * @brief Construct a NameComponent of TLV-TYPE @p type, copying @p count bytes at @p value as
+ * TLV-VALUE.
*/
Component(uint32_t type, const uint8_t* value, size_t count);
@@ -129,7 +130,7 @@
}
/**
- * @brief Construct a NameComponent of @p type, copying TLV-VALUE from a range.
+ * @brief Construct a NameComponent of TLV-TYPE @p type, copying TLV-VALUE from a range.
* @tparam Iterator an @c InputIterator dereferencing to a one-octet value type. More efficient
* implementation is available when it is a @c RandomAccessIterator.
* @param type the TLV-TYPE.
@@ -222,7 +223,7 @@
*
* This also adds "..." to a value with zero or more "."
*
- * @param os The output stream to where write the URI escaped version *this
+ * @param os The output stream where to write the URI escaped version of *this
*/
void
toUri(std::ostream& os) const;
@@ -240,49 +241,49 @@
public: // naming conventions
/**
* @brief Check if the component is nonNegativeInteger
- * @see http://named-data.net/doc/ndn-tlv/tlv.html#non-negative-integer-encoding
+ * @sa https://named-data.net/doc/NDN-packet-spec/current/tlv.html#non-negative-integer-encoding
*/
bool
isNumber() const;
/**
* @brief Check if the component is NameComponentWithMarker per NDN naming conventions
- * @see http://named-data.net/doc/tech-memos/naming-conventions.pdf
+ * @sa NDN Naming Conventions https://named-data.net/doc/tech-memos/naming-conventions.pdf
*/
bool
isNumberWithMarker(uint8_t marker) const;
/**
* @brief Check if the component is version per NDN naming conventions
- * @see http://named-data.net/doc/tech-memos/naming-conventions.pdf
+ * @sa NDN Naming Conventions https://named-data.net/doc/tech-memos/naming-conventions.pdf
*/
bool
isVersion() const;
/**
* @brief Check if the component is segment number per NDN naming conventions
- * @see http://named-data.net/doc/tech-memos/naming-conventions.pdf
+ * @sa NDN Naming Conventions https://named-data.net/doc/tech-memos/naming-conventions.pdf
*/
bool
isSegment() const;
/**
* @brief Check if the component is segment offset per NDN naming conventions
- * @see http://named-data.net/doc/tech-memos/naming-conventions.pdf
+ * @sa NDN Naming Conventions https://named-data.net/doc/tech-memos/naming-conventions.pdf
*/
bool
isSegmentOffset() const;
/**
* @brief Check if the component is timestamp per NDN naming conventions
- * @see http://named-data.net/doc/tech-memos/naming-conventions.pdf
+ * @sa NDN Naming Conventions https://named-data.net/doc/tech-memos/naming-conventions.pdf
*/
bool
isTimestamp() const;
/**
* @brief Check if the component is sequence number per NDN naming conventions
- * @see http://named-data.net/doc/tech-memos/naming-conventions.pdf
+ * @sa NDN Naming Conventions https://named-data.net/doc/tech-memos/naming-conventions.pdf
*/
bool
isSequenceNumber() const;
@@ -290,7 +291,7 @@
/**
* @brief Interpret this name component as nonNegativeInteger
*
- * @see http://named-data.net/doc/ndn-tlv/tlv.html#non-negative-integer-encoding
+ * @sa https://named-data.net/doc/NDN-packet-spec/current/tlv.html#non-negative-integer-encoding
*
* @return The integer number.
*/
@@ -300,7 +301,7 @@
/**
* @brief Interpret this name component as NameComponentWithMarker
*
- * @see http://named-data.net/doc/tech-memos/naming-conventions.pdf
+ * @sa NDN Naming Conventions https://named-data.net/doc/tech-memos/naming-conventions.pdf
*
* @param marker 1-byte octet of the marker
* @return The integer number.
@@ -313,7 +314,7 @@
/**
* @brief Interpret as version component using NDN naming conventions
*
- * @see http://named-data.net/doc/tech-memos/naming-conventions.pdf
+ * @sa NDN Naming Conventions https://named-data.net/doc/tech-memos/naming-conventions.pdf
*
* @throws Error if name component does not have the specified marker.
* tlv::Error if format does not follow NameComponentWithMarker specification.
@@ -324,7 +325,7 @@
/**
* @brief Interpret as segment number component using NDN naming conventions
*
- * @see http://named-data.net/doc/tech-memos/naming-conventions.pdf
+ * @sa NDN Naming Conventions https://named-data.net/doc/tech-memos/naming-conventions.pdf
*
* @throws Error if name component does not have the specified marker.
* tlv::Error if format does not follow NameComponentWithMarker specification.
@@ -335,7 +336,7 @@
/**
* @brief Interpret as segment offset component using NDN naming conventions
*
- * @see http://named-data.net/doc/tech-memos/naming-conventions.pdf
+ * @sa NDN Naming Conventions https://named-data.net/doc/tech-memos/naming-conventions.pdf
*
* @throws Error if name component does not have the specified marker.
* tlv::Error if format does not follow NameComponentWithMarker specification.
@@ -346,7 +347,7 @@
/**
* @brief Interpret as timestamp component using NDN naming conventions
*
- * @see http://named-data.net/doc/tech-memos/naming-conventions.pdf
+ * @sa NDN Naming Conventions https://named-data.net/doc/tech-memos/naming-conventions.pdf
*
* @throws Error if name component does not have the specified marker.
* tlv::Error if format does not follow NameComponentWithMarker specification.
@@ -357,7 +358,7 @@
/**
* @brief Interpret as sequence number component using NDN naming conventions
*
- * @see http://named-data.net/doc/tech-memos/naming-conventions.pdf
+ * @sa NDN Naming Conventions https://named-data.net/doc/tech-memos/naming-conventions.pdf
*
* @throws Error if name component does not have the specified marker.
* tlv::Error if format does not follow NameComponentWithMarker specification.
@@ -368,7 +369,7 @@
/**
* @brief Create a component encoded as nonNegativeInteger
*
- * @see http://named-data.net/doc/ndn-tlv/tlv.html#non-negative-integer-encoding
+ * @sa https://named-data.net/doc/NDN-packet-spec/current/tlv.html#non-negative-integer-encoding
*
* @param number The non-negative number
* @return The component value.
@@ -391,7 +392,7 @@
* TLV-LENGTH := VAR-NUMBER
* TLV-VALUE := BYTE+
*
- * @see http://named-data.net/doc/tech-memos/naming-conventions.pdf
+ * @sa NDN Naming Conventions https://named-data.net/doc/tech-memos/naming-conventions.pdf
*
* @param marker 1-byte marker octet
* @param number The non-negative number
@@ -403,7 +404,7 @@
/**
* @brief Create version component using NDN naming conventions
*
- * @see http://named-data.net/doc/tech-memos/naming-conventions.pdf
+ * @sa NDN Naming Conventions https://named-data.net/doc/tech-memos/naming-conventions.pdf
*/
static Component
fromVersion(uint64_t version);
@@ -411,7 +412,7 @@
/**
* @brief Create segment number component using NDN naming conventions
*
- * @see http://named-data.net/doc/tech-memos/naming-conventions.pdf
+ * @sa NDN Naming Conventions https://named-data.net/doc/tech-memos/naming-conventions.pdf
*/
static Component
fromSegment(uint64_t segmentNo);
@@ -419,7 +420,7 @@
/**
* @brief Create segment offset component using NDN naming conventions
*
- * @see http://named-data.net/doc/tech-memos/naming-conventions.pdf
+ * @sa NDN Naming Conventions https://named-data.net/doc/tech-memos/naming-conventions.pdf
*/
static Component
fromSegmentOffset(uint64_t offset);
@@ -427,7 +428,7 @@
/**
* @brief Create sequence number component using NDN naming conventions
*
- * @see http://named-data.net/doc/tech-memos/naming-conventions.pdf
+ * @sa NDN Naming Conventions https://named-data.net/doc/tech-memos/naming-conventions.pdf
*/
static Component
fromTimestamp(const time::system_clock::TimePoint& timePoint);
@@ -435,7 +436,7 @@
/**
* @brief Create sequence number component using NDN naming conventions
*
- * @see http://named-data.net/doc/tech-memos/naming-conventions.pdf
+ * @sa NDN Naming Conventions https://named-data.net/doc/tech-memos/naming-conventions.pdf
*/
static Component
fromSequenceNumber(uint64_t seqNo);
@@ -489,7 +490,7 @@
* @retval zero this equals other
* @retval positive this comes after other in canonical ordering
*
- * @see http://named-data.net/doc/ndn-tlv/name.html#canonical-order
+ * @sa https://named-data.net/doc/NDN-packet-spec/current/name.html#canonical-order
*/
int
compare(const Component& other) const;
@@ -521,7 +522,7 @@
* @brief Check if the *this is less than or equal to the other in NDN canonical ordering
* @param other The other Component to compare with
*
- * @see http://named-data.net/doc/ndn-tlv/name.html#canonical-order
+ * @sa https://named-data.net/doc/NDN-packet-spec/current/name.html#canonical-order
*/
bool
operator<=(const Component& other) const
@@ -533,7 +534,7 @@
* @brief Check if the *this is less than the other in NDN canonical ordering
* @param other The other Component to compare with
*
- * @see http://named-data.net/doc/ndn-tlv/name.html#canonical-order
+ * @sa https://named-data.net/doc/NDN-packet-spec/current/name.html#canonical-order
*/
bool
operator<(const Component& other) const
@@ -545,7 +546,7 @@
* @brief Check if the *this is greater or equal than the other in NDN canonical ordering
* @param other The other Component to compare with
*
- * @see http://named-data.net/doc/ndn-tlv/name.html#canonical-order
+ * @sa https://named-data.net/doc/NDN-packet-spec/current/name.html#canonical-order
*/
bool
operator>=(const Component& other) const
@@ -557,7 +558,7 @@
* @brief Check if the *this is greater than the other in NDN canonical ordering
* @param other The other Component to compare with
*
- * @see http://named-data.net/doc/ndn-tlv/name.html#canonical-order
+ * @sa https://named-data.net/doc/NDN-packet-spec/current/name.html#canonical-order
*/
bool
operator>(const Component& other) const
diff --git a/src/name.hpp b/src/name.hpp
index b27f3fd..ad64424 100644
--- a/src/name.hpp
+++ b/src/name.hpp
@@ -1,6 +1,6 @@
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
- * Copyright (c) 2013-2017 Regents of the University of California.
+ * Copyright (c) 2013-2018 Regents of the University of California.
*
* This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
*
@@ -89,19 +89,19 @@
/** @brief Parse name from NDN URI
* @param uri a null-terminated URI string
- * @sa https://named-data.net/doc/ndn-tlv/name.html#ndn-uri-scheme
+ * @sa https://named-data.net/doc/NDN-packet-spec/current/name.html#ndn-uri-scheme
*/
Name(const char* uri);
/** @brief Create name from NDN URI
* @param uri a URI string
- * @sa https://named-data.net/doc/ndn-tlv/name.html#ndn-uri-scheme
+ * @sa https://named-data.net/doc/NDN-packet-spec/current/name.html#ndn-uri-scheme
*/
Name(std::string uri);
/** @brief Get URI representation of the name
* @return URI representation; "ndn:" scheme identifier is not included
- * @sa https://named-data.net/doc/ndn-tlv/name.html#ndn-uri-scheme
+ * @sa 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``.
*/
std::string
@@ -249,8 +249,8 @@
}
public: // modifiers
- /** @brief Append a component
- * @return a reference to this name, to allow chaining
+ /** @brief Append a component.
+ * @return a reference to this name, to allow chaining.
*/
Name&
append(const Component& component)
@@ -259,66 +259,86 @@
return *this;
}
- /** @brief Append a component, copying from a zero-terminated byte string
- * @param value a zero-terminated string; it will be constructed as a component as is
- * and will not be interpreted as a URI
- * @note This overload is necessary to ensure unambiguity of ``append("string")``, because both
- * Component and PartialName are implicitly convertible from zero-terminated byte string.
- * This overload ensures the string is constructed as a Component.
+ /** @brief Append a NameComponent of TLV-TYPE @p type, copying @p count bytes at @p value as
+ * TLV-VALUE.
+ * @return a reference to this name, to allow chaining.
*/
Name&
- append(const char* value)
+ append(uint32_t type, const uint8_t* value, size_t count)
{
- return append(Component(value));
+ return append(Component(type, value, count));
}
- /** @brief Append a component, copying from [@p value, @p value + @p valueLength)
- * @return a reference to this name, to allow chaining
+ /** @brief Append a GenericNameComponent, copying @p count bytes at @p value as TLV-VALUE.
+ * @return a reference to this name, to allow chaining.
*/
Name&
- append(const uint8_t* value, size_t valueLength)
+ append(const uint8_t* value, size_t count)
{
- return append(Component(value, valueLength));
+ return append(Component(value, count));
}
- /** @brief Append a component, copying from [@p first, @p last)
- * @tparam Iterator an InputIterator dereferencing to a one-octet value type. More efficient
- * implementation is available when @p Iterator additionally satisfies
- * RandomAccessIterator concept.
- * @param first begin position of the value
- * @param last end position of the value
- * @return a reference to this name, to allow chaining
+ /** @brief Append a NameComponent of TLV-TYPE @p type, copying TLV-VALUE from a range.
+ * @tparam Iterator an @c InputIterator dereferencing to a one-octet value type. More efficient
+ * implementation is available when it is a @c RandomAccessIterator.
+ * @param type the TLV-TYPE.
+ * @param first beginning of the range.
+ * @param last past-end of the range.
+ * @return a reference to this name, to allow chaining.
+ */
+ template<class Iterator>
+ Name&
+ append(uint32_t type, Iterator first, Iterator last)
+ {
+ return append(Component(type, first, last));
+ }
+
+ /** @brief Append a GenericNameComponent, copying TLV-VALUE from a range.
+ * @tparam Iterator an @c InputIterator dereferencing to a one-octet value type. More efficient
+ * implementation is available when it is a @c RandomAccessIterator.
+ * @param first beginning of the range.
+ * @param last past-end of the range.
+ * @return a reference to this name, to allow chaining.
*/
template<class Iterator>
Name&
append(Iterator first, Iterator last)
{
- static_assert(sizeof(typename std::iterator_traits<Iterator>::value_type) == 1,
- "iterator does not dereference to one-octet value type");
return append(Component(first, last));
}
- /** @brief Append a component, decoding from a Block
- * @param value a Block; if its TLV-TYPE is not NameComponent, it is nested into a NameComponent
- * @return a reference to this name, to allow chaining
+ /** @brief Append a GenericNameComponent, copying TLV-VALUE from a null-terminated string.
+ * @param str a null-terminated string. Bytes from the string are copied as is, and not
+ * interpreted as URI component.
+ * @return a reference to this name, to allow chaining.
+ */
+ Name&
+ append(const char* str)
+ {
+ return append(Component(str));
+ }
+
+ /** @brief Append a GenericNameComponent from a TLV element.
+ * @param value a TLV element. If its type is @c tlv::GenericNameComponent, it is used as is.
+ * Otherwise, it is encapsulated into a GenericNameComponent.
+ * @return a reference to this name, to allow chaining.
*/
Name&
append(const Block& value)
{
- if (value.type() == tlv::NameComponent) {
+ if (value.type() == tlv::GenericNameComponent) {
m_wire.push_back(value);
}
else {
- m_wire.push_back(Block(tlv::NameComponent, value));
+ m_wire.push_back(Block(tlv::GenericNameComponent, value));
}
-
return *this;
}
/** @brief Append a component with a nonNegativeInteger
* @sa number the number
* @return a reference to this name, to allow chaining
- * @sa https://named-data.net/doc/ndn-tlv/tlv.html#non-negative-integer-encoding
+ * @sa https://named-data.net/doc/NDN-packet-spec/current/tlv.html#non-negative-integer-encoding
*/
Name&
appendNumber(uint64_t number)
@@ -514,7 +534,7 @@
* @retval zero this equals other
* @retval positive this comes after other in canonical ordering
*
- * @sa https://named-data.net/doc/ndn-tlv/name.html#canonical-order
+ * @sa https://named-data.net/doc/NDN-packet-spec/current/name.html#canonical-order
*/
int
compare(const Name& other) const
@@ -579,13 +599,13 @@
}
/** @brief Print URI representation of a name
- * @sa https://named-data.net/doc/ndn-tlv/name.html#ndn-uri-scheme
+ * @sa https://named-data.net/doc/NDN-packet-spec/current/name.html#ndn-uri-scheme
*/
std::ostream&
operator<<(std::ostream& os, const Name& name);
/** @brief Parse URI from stream as Name
- * @sa https://named-data.net/doc/ndn-tlv/name.html#ndn-uri-scheme
+ * @sa https://named-data.net/doc/NDN-packet-spec/current/name.html#ndn-uri-scheme
*/
std::istream&
operator>>(std::istream& is, Name& name);