blob: cf8318f65750f930ee2ddee39325f31f77295aaa [file] [log] [blame]
Alexander Afanasyevc169a812014-05-20 20:37:29 -04001/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
Jeff Thompson47eecfc2013-07-07 22:56:46 -07002/**
Junxiao Shia6452ac2015-01-23 11:21:06 -07003 * Copyright (c) 2013-2015 Regents of the University of California.
Alexander Afanasyevdfa52c42014-04-24 21:10:11 -07004 *
5 * This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
Alexander Afanasyevdfa52c42014-04-24 21:10:11 -07006 *
Alexander Afanasyevc169a812014-05-20 20:37:29 -04007 * ndn-cxx library is free software: you can redistribute it and/or modify it under the
8 * terms of the GNU Lesser General Public License as published by the Free Software
9 * Foundation, either version 3 of the License, or (at your option) any later version.
10 *
11 * ndn-cxx library is distributed in the hope that it will be useful, but WITHOUT ANY
12 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
13 * PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
14 *
15 * You should have received copies of the GNU General Public License and GNU Lesser
16 * General Public License along with ndn-cxx, e.g., in COPYING.md file. If not, see
17 * <http://www.gnu.org/licenses/>.
18 *
19 * See AUTHORS.md for complete list of ndn-cxx authors and contributors.
Alexander Afanasyevdfa52c42014-04-24 21:10:11 -070020 *
21 * @author Jeff Thompson <jefft0@remap.ucla.edu>
22 * @author Alexander Afanasyev <http://lasr.cs.ucla.edu/afanasyev/index.html>
23 * @author Zhenkai Zhu <http://irl.cs.ucla.edu/~zhenkai/>
Jeff Thompson9c41dfe2013-06-27 12:10:25 -070024 */
25
26#ifndef NDN_NAME_HPP
Jeff Thompson2d27e2f2013-08-09 12:55:00 -070027#define NDN_NAME_HPP
Jeff Thompson9c41dfe2013-06-27 12:10:25 -070028
Alexander Afanasyev95e8c2f2014-02-06 17:29:30 -080029#include "common.hpp"
30#include "name-component.hpp"
Jeff Thompson25b4e612013-10-10 16:03:24 -070031
Alexander Afanasyev95e8c2f2014-02-06 17:29:30 -080032#include <boost/iterator/reverse_iterator.hpp>
33
Jeff Thompson9c41dfe2013-06-27 12:10:25 -070034namespace ndn {
Alexander Afanasyev95e8c2f2014-02-06 17:29:30 -080035
Jeff Thompsonc7d65502013-11-06 17:22:26 -080036/**
Alexander Afanasyevc89efb42015-02-10 18:26:42 -080037 * @brief A Name holds an array of name::Component and represents an NDN name
Jeff Thompsonc7d65502013-11-06 17:22:26 -080038 */
Alexander Afanasyevf73f0632014-05-12 18:02:37 -070039class Name : public enable_shared_from_this<Name>
Alexander Afanasyev2a7f7202014-04-23 14:25:29 -070040{
Jeff Thompson9c41dfe2013-06-27 12:10:25 -070041public:
Alexander Afanasyev2a7f7202014-04-23 14:25:29 -070042 /// @brief Error that can be thrown from Name
43 class Error : public name::Component::Error
44 {
Alexander Afanasyev1dd95c52014-03-22 19:11:36 -070045 public:
Alexander Afanasyev2a7f7202014-04-23 14:25:29 -070046 explicit
Alexander Afanasyev1dd95c52014-03-22 19:11:36 -070047 Error(const std::string& what)
Alexander Afanasyev2a7f7202014-04-23 14:25:29 -070048 : name::Component::Error(what)
49 {
50 }
Alexander Afanasyev1dd95c52014-03-22 19:11:36 -070051 };
Alexander Afanasyevaf283d82014-01-03 13:23:34 -080052
Alexander Afanasyev95e8c2f2014-02-06 17:29:30 -080053 typedef name::Component Component;
54
55 typedef std::vector<Component> component_container;
56
57 typedef Component value_type;
58 typedef void allocator_type;
59 typedef Component& reference;
60 typedef const Component const_reference;
61 typedef Component* pointer;
62 typedef const Component* const_pointer;
63 typedef Component* iterator;
64 typedef const Component* const_iterator;
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -070065
Alexander Afanasyev95e8c2f2014-02-06 17:29:30 -080066 typedef boost::reverse_iterator<iterator> reverse_iterator;
67 typedef boost::reverse_iterator<const_iterator> const_reverse_iterator;
68
69 typedef component_container::difference_type difference_type;
70 typedef component_container::size_type size_type;
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -070071
Jeff Thompson443398d2013-07-02 19:45:46 -070072 /**
Alexander Afanasyevc89efb42015-02-10 18:26:42 -080073 * @brief Create a new Name with no components.
Jeff Thompson443398d2013-07-02 19:45:46 -070074 */
Alexander Afanasyevc89efb42015-02-10 18:26:42 -080075 Name();
Alexander Afanasyev52eb20d2014-02-06 18:25:54 -080076
77 /**
78 * @brief Create Name object from wire block
79 *
80 * This is a more efficient equivalent for
81 * @code
82 * Name name;
83 * name.wireDecode(wire);
84 * @endcode
85 */
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -080086 explicit
Alexander Afanasyevc89efb42015-02-10 18:26:42 -080087 Name(const Block& wire);
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -070088
Jeff Thompson3f2175b2013-07-31 17:12:47 -070089 /**
Alexander Afanasyevc89efb42015-02-10 18:26:42 -080090 * @brief Create name from @p uri (NDN URI scheme)
91 * @param uri The null-terminated URI string
Jeff Thompson443398d2013-07-02 19:45:46 -070092 */
Alexander Afanasyevc89efb42015-02-10 18:26:42 -080093 Name(const char* uri);
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -070094
Jeff Thompsone5f839b2013-06-28 12:50:38 -070095 /**
Alexander Afanasyevc89efb42015-02-10 18:26:42 -080096 * @brief Create name from @p uri (NDN URI scheme)
97 * @param uri The URI string
Jeff Thompson3549ef32013-09-25 14:05:17 -070098 */
Alexander Afanasyevc89efb42015-02-10 18:26:42 -080099 Name(const std::string& uri);
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700100
Alexander Afanasyev380420b2014-02-09 20:52:29 -0800101 /**
102 * @brief Fast encoding or block size estimation
103 */
Alexander Afanasyev74633892015-02-08 18:08:46 -0800104 template<encoding::Tag TAG>
Wentao Shang77949212014-02-01 23:42:24 -0800105 size_t
Alexander Afanasyev74633892015-02-08 18:08:46 -0800106 wireEncode(EncodingImpl<TAG>& block) const;
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700107
Alexander Afanasyev1dd95c52014-03-22 19:11:36 -0700108 const Block&
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800109 wireEncode() const;
Alexander Afanasyev848c61a2014-01-03 13:52:04 -0800110
111 void
Alexander Afanasyev1dd95c52014-03-22 19:11:36 -0700112 wireDecode(const Block& wire);
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800113
114 /**
115 * @brief Check if already has wire
116 */
117 bool
118 hasWire() const;
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700119
Jeff Thompsonb468c312013-07-01 17:50:14 -0700120 /**
Alexander Afanasyevc89efb42015-02-10 18:26:42 -0800121 * @deprecated Use appropriate constructor
Jeff Thompson67515bd2013-08-15 17:43:22 -0700122 */
Alexander Afanasyevc89efb42015-02-10 18:26:42 -0800123 DEPRECATED(
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700124 void
Alexander Afanasyevc89efb42015-02-10 18:26:42 -0800125 set(const char* uri));
Jeff Thompson67515bd2013-08-15 17:43:22 -0700126
127 /**
Alexander Afanasyevc89efb42015-02-10 18:26:42 -0800128 * @deprecated Use appropriate constructor
Jeff Thompson7781b392013-12-17 11:45:59 -0800129 */
Alexander Afanasyevc89efb42015-02-10 18:26:42 -0800130 DEPRECATED(
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700131 void
Alexander Afanasyevc89efb42015-02-10 18:26:42 -0800132 set(const std::string& uri));
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700133
Jeff Thompson7781b392013-12-17 11:45:59 -0800134 /**
Alexander Afanasyevc89efb42015-02-10 18:26:42 -0800135 * @brief Append a new component, copying from value of length valueLength.
Jeff Thompson26b0d792013-09-23 16:19:01 -0700136 * @return This name so that you can chain calls to append.
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700137 */
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700138 Name&
Alexander Afanasyev1dd95c52014-03-22 19:11:36 -0700139 append(const uint8_t* value, size_t valueLength)
Jeff Thompson0f743452013-09-12 14:23:18 -0700140 {
Alexander Afanasyev29e5c3d2014-02-11 00:01:10 -0800141 m_nameBlock.push_back(Component(value, valueLength));
Jeff Thompson26b0d792013-09-23 16:19:01 -0700142 return *this;
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700143 }
Jeff Thompsonf72b1ac2013-08-16 16:44:41 -0700144
Alexander Afanasyevbf9671d2014-02-11 13:44:13 -0800145 /**
Alexander Afanasyev74633892015-02-08 18:08:46 -0800146 * @brief Append a new component, copying from value frome the range [@p first, @p last) of bytes
147 * @param first Iterator pointing to the beginning of the buffer
148 * @param last Iterator pointing to the ending of the buffer
149 * @tparam Iterator iterator type satisfying at least InputIterator concept. Implementation
150 * is more optimal when the iterator type satisfies RandomAccessIterator concept.
151 * It is required that sizeof(std::iterator_traits<Iterator>::value_type) == 1.
Alexander Afanasyevbf9671d2014-02-11 13:44:13 -0800152 * @return This name so that you can chain calls to append.
153 */
Alexander Afanasyev74633892015-02-08 18:08:46 -0800154 template<class Iterator>
Alexander Afanasyevbf9671d2014-02-11 13:44:13 -0800155 Name&
Alexander Afanasyev74633892015-02-08 18:08:46 -0800156 append(Iterator first, Iterator last)
Alexander Afanasyevbf9671d2014-02-11 13:44:13 -0800157 {
Alexander Afanasyev74633892015-02-08 18:08:46 -0800158 m_nameBlock.push_back(Component(first, last));
Alexander Afanasyevbf9671d2014-02-11 13:44:13 -0800159 return *this;
160 }
161
Alexander Afanasyevc89efb42015-02-10 18:26:42 -0800162 /**
163 * @brief Append component @p value
164 */
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700165 Name&
Alexander Afanasyev1dd95c52014-03-22 19:11:36 -0700166 append(const Component& value)
Jeff Thompson21eb7212013-09-26 09:05:40 -0700167 {
Alexander Afanasyev29e5c3d2014-02-11 00:01:10 -0800168 m_nameBlock.push_back(value);
Jeff Thompson21eb7212013-09-26 09:05:40 -0700169 return *this;
170 }
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800171
Alexander Afanasyev594cdb22014-01-03 15:11:33 -0800172 /**
173 * @brief Append name component that represented as a string
174 *
175 * Note that this method is necessary to ensure correctness and unambiguity of
176 * ``append("string")`` operations (both Component and Name can be implicitly
177 * converted from string, each having different outcomes
178 */
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700179 Name&
Alexander Afanasyev1dd95c52014-03-22 19:11:36 -0700180 append(const char* value)
Alexander Afanasyev594cdb22014-01-03 15:11:33 -0800181 {
Alexander Afanasyev29e5c3d2014-02-11 00:01:10 -0800182 m_nameBlock.push_back(Component(value));
Alexander Afanasyev594cdb22014-01-03 15:11:33 -0800183 return *this;
184 }
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700185
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800186 Name&
Alexander Afanasyev1dd95c52014-03-22 19:11:36 -0700187 append(const Block& value)
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800188 {
Steve DiBenedetto54ce6682014-07-22 13:22:57 -0600189 if (value.type() == tlv::NameComponent)
Alexander Afanasyev29e5c3d2014-02-11 00:01:10 -0800190 m_nameBlock.push_back(value);
Alexander Afanasyev380420b2014-02-09 20:52:29 -0800191 else
Steve DiBenedetto54ce6682014-07-22 13:22:57 -0600192 m_nameBlock.push_back(Block(tlv::NameComponent, value));
Alexander Afanasyev380420b2014-02-09 20:52:29 -0800193
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800194 return *this;
195 }
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700196
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700197 /**
Jeff Thompson26b0d792013-09-23 16:19:01 -0700198 * Append the components of the given name to this name.
199 * @param name The Name with components to append.
200 * @return This name so that you can chain calls to append.
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700201 */
Jeff Thompson26b0d792013-09-23 16:19:01 -0700202 Name&
203 append(const Name& name);
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700204
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700205 /**
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700206 * Clear all the components.
207 */
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700208 void
Alexander Afanasyev95e8c2f2014-02-06 17:29:30 -0800209 clear()
210 {
Steve DiBenedetto54ce6682014-07-22 13:22:57 -0600211 m_nameBlock = Block(tlv::Name);
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700212 }
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700213
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700214 /**
Jeff Thompsond0159d72013-09-23 13:34:15 -0700215 * Get a new name, constructed as a subset of components.
216 * @param iStartComponent The index if the first component to get.
217 * @param nComponents The number of components starting at iStartComponent.
Junxiao Shia6452ac2015-01-23 11:21:06 -0700218 * Use npos to get the sub Name until the end of this Name.
Jeff Thompsond0159d72013-09-23 13:34:15 -0700219 * @return A new name.
220 */
221 Name
Junxiao Shia6452ac2015-01-23 11:21:06 -0700222 getSubName(size_t iStartComponent, size_t nComponents = npos) const;
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700223
Jeff Thompsond0159d72013-09-23 13:34:15 -0700224 /**
Alexander Afanasyev15f67312014-07-22 15:11:09 -0700225 * @brief Return a new Name with the first nComponents components of this Name.
226 *
227 * @param nComponents The number of prefix components. If nComponents is -N then return
228 * the prefix up to name.size() - N. For example getPrefix(-1)
229 * returns the name without the final component.
Jeff Thompsond0159d72013-09-23 13:34:15 -0700230 * @return A new Name.
231 */
232 Name
Alexander Afanasyev15f67312014-07-22 15:11:09 -0700233 getPrefix(ssize_t nComponents) const
Jeff Thompsond0159d72013-09-23 13:34:15 -0700234 {
Jeff Thompsoneb0358f2013-12-17 10:59:53 -0800235 if (nComponents < 0)
Alexander Afanasyev29e5c3d2014-02-11 00:01:10 -0800236 return getSubName(0, m_nameBlock.elements_size() + nComponents);
Jeff Thompsoneb0358f2013-12-17 10:59:53 -0800237 else
238 return getSubName(0, nComponents);
Jeff Thompsond0159d72013-09-23 13:34:15 -0700239 }
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700240
Jeff Thompsond0159d72013-09-23 13:34:15 -0700241 /**
Jeff Thompsone6063512013-07-01 15:11:28 -0700242 * Encode this name as a URI.
Jeff Thompson3f2175b2013-07-31 17:12:47 -0700243 * @return The encoded URI.
Jeff Thompsone6063512013-07-01 15:11:28 -0700244 */
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700245 std::string
Jeff Thompson0050abe2013-09-17 12:50:25 -0700246 toUri() const;
Jeff Thompsond129ac12013-10-11 14:30:12 -0700247
248 /**
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700249 * @brief Append a component with the number encoded as nonNegativeInteger
250 *
251 * @see http://named-data.net/doc/ndn-tlv/tlv.html#non-negative-integer-encoding
252 *
Steve DiBenedettoc145d492014-03-11 16:35:45 -0600253 * @param number The non-negative number
254 * @return This name so that you can chain calls to append.
255 */
256 Name&
Alexander Afanasyev15f67312014-07-22 15:11:09 -0700257 appendNumber(uint64_t number);
Steve DiBenedettoc145d492014-03-11 16:35:45 -0600258
Jeff Thompsonec7789a2013-08-21 11:08:36 -0700259 /**
Alexander Afanasyev15f67312014-07-22 15:11:09 -0700260 * @brief Create a component encoded as NameComponentWithMarker
261 *
262 * @see http://named-data.net/doc/tech-memos/naming-conventions.pdf
263 *
264 * @param marker 1-byte marker octet
265 * @param number The non-negative number
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700266 */
267 Name&
Alexander Afanasyev15f67312014-07-22 15:11:09 -0700268 appendNumberWithMarker(uint8_t marker, uint64_t number);
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700269
270 /**
Alexander Afanasyev15f67312014-07-22 15:11:09 -0700271 * @brief Append version using NDN naming conventions
272 *
273 * @see http://named-data.net/doc/tech-memos/naming-conventions.pdf
274 */
275 Name&
276 appendVersion(uint64_t version);
277
278 /**
279 * @brief Append version using NDN naming conventions based on current UNIX timestamp
280 * in milliseconds
281 *
282 * @see http://named-data.net/doc/tech-memos/naming-conventions.pdf
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700283 */
284 Name&
285 appendVersion();
286
287 /**
Alexander Afanasyev15f67312014-07-22 15:11:09 -0700288 * @brief Append segment number (sequential) using NDN naming conventions
289 *
290 * @see http://named-data.net/doc/tech-memos/naming-conventions.pdf
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700291 */
292 Name&
Alexander Afanasyev15f67312014-07-22 15:11:09 -0700293 appendSegment(uint64_t segmentNo);
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700294
295 /**
Alexander Afanasyev15f67312014-07-22 15:11:09 -0700296 * @brief Append segment byte offset using NDN naming conventions
297 *
298 * @see http://named-data.net/doc/tech-memos/naming-conventions.pdf
299 */
300 Name&
301 appendSegmentOffset(uint64_t offset);
302
303 /**
304 * @brief Append timestamp using NDN naming conventions
305 *
306 * @see http://named-data.net/doc/tech-memos/naming-conventions.pdf
307 */
308 Name&
309 appendTimestamp(const time::system_clock::TimePoint& timePoint = time::system_clock::now());
310
311 /**
312 * @brief Append sequence number using NDN naming conventions
313 *
314 * @see http://named-data.net/doc/tech-memos/naming-conventions.pdf
315 */
316 Name&
317 appendSequenceNumber(uint64_t seqNo);
318
319 /**
Alexander Afanasyev6486d522014-10-23 14:14:11 -0700320 * @brief Append ImplicitSha256Digest
321 */
322 Name&
323 appendImplicitSha256Digest(const ConstBufferPtr& digest);
324
325 /**
326 * @brief Append ImplicitSha256Digest
327 */
328 Name&
329 appendImplicitSha256Digest(const uint8_t* digest, size_t digestSize);
330
331 /**
Alexander Afanasyev15f67312014-07-22 15:11:09 -0700332 * @brief Get the successor of a name
333 *
334 * The successor of a name is defined as follows:
335 *
336 * N represents the set of NDN Names, and X,Y ∈ N.
337 * Operator < is defined by canonical order on N.
338 * Y is the successor of X, if (a) X < Y, and (b) ∄ Z ∈ N s.t. X < Z < Y.
339 *
340 * In plain words, successor of a name is the same name, but with its last component
341 * advanced to a next possible value.
342 *
343 * Examples:
344 *
345 * - successor for / is /%00
346 * - successor for /%00%01/%01%02 is /%00%01/%01%03
347 * - successor for /%00%01/%01%FF is /%00%01/%02%00
348 * - successor for /%00%01/%FF%FF is /%00%01/%00%00%00
349 *
Shuo Chen5aa8c742014-06-22 15:00:02 +0800350 * @return a new name
351 */
352 Name
353 getSuccessor() const;
354
355 /**
Jeff Thompson3c2ab012013-10-02 14:18:16 -0700356 * Check if this name has the same component count and components as the given name.
357 * @param name The Name to check.
358 * @return true if the names are equal, otherwise false.
359 */
360 bool
361 equals(const Name& name) const;
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700362
Jeff Thompson3c2ab012013-10-02 14:18:16 -0700363 /**
Alexander Afanasyev15f67312014-07-22 15:11:09 -0700364 * @brief Check if the N components of this name are the same as the first N components
365 * of the given name.
366 *
Jeff Thompsonec7789a2013-08-21 11:08:36 -0700367 * @param name The Name to check.
Alexander Afanasyev15f67312014-07-22 15:11:09 -0700368 * @return true if this matches the given name, otherwise false. This always returns
369 * true if this name is empty.
Jeff Thompsonec7789a2013-08-21 11:08:36 -0700370 */
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700371 bool
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800372 isPrefixOf(const Name& name) const;
373
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700374 //
375 // vector equivalent interface.
376 //
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800377
378 /**
379 * @brief Check if name is emtpy
380 */
381 bool
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700382 empty() const
383 {
384 return m_nameBlock.elements().empty();
385 }
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700386
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700387 /**
388 * Get the number of components.
389 * @return The number of components.
390 */
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700391 size_t
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700392 size() const
393 {
394 return m_nameBlock.elements_size();
395 }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700396
397 /**
398 * Get the component at the given index.
399 * @param i The index of the component, starting from 0.
400 * @return The name component at the index.
401 */
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700402 const Component&
Alexander Afanasyev8f9aa8bed2013-12-30 15:58:57 -0800403 get(ssize_t i) const
404 {
405 if (i >= 0)
Alexander Afanasyev95e8c2f2014-02-06 17:29:30 -0800406 return reinterpret_cast<const Component&>(m_nameBlock.elements()[i]);
Alexander Afanasyev8f9aa8bed2013-12-30 15:58:57 -0800407 else
Alexander Afanasyev95e8c2f2014-02-06 17:29:30 -0800408 return reinterpret_cast<const Component&>(m_nameBlock.elements()[size() + i]);
409 }
410
411 const Component&
Alexander Afanasyev1dd95c52014-03-22 19:11:36 -0700412 operator[](ssize_t i) const
Alexander Afanasyev95e8c2f2014-02-06 17:29:30 -0800413 {
414 return get(i);
Alexander Afanasyev8f9aa8bed2013-12-30 15:58:57 -0800415 }
Alexander Afanasyevc2344292014-03-02 00:08:00 +0000416
417 /**
418 * @brief Get component at the specified index
419 *
420 * Unlike get() and operator[] methods, at() checks for out of bounds
421 * and will throw Name::Error when it happens
422 *
423 * @throws Name::Error if index out of bounds
424 */
Alexander Afanasyev95e8c2f2014-02-06 17:29:30 -0800425 const Component&
426 at(ssize_t i) const
427 {
Alexander Afanasyev1dd95c52014-03-22 19:11:36 -0700428 if ((i >= 0 && static_cast<size_t>(i) >= size()) ||
429 (i < 0 && static_cast<size_t>(-i) > size()))
Alexander Afanasyevc2344292014-03-02 00:08:00 +0000430 throw Error("Requested component does not exist (out of bounds)");
431
Alexander Afanasyev95e8c2f2014-02-06 17:29:30 -0800432 return get(i);
433 }
434
Jeff Thompsonafc45a92014-01-15 12:42:45 -0800435 /**
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700436 * @brief Compare this to the other Name using NDN canonical ordering.
Jeff Thompsonafc45a92014-01-15 12:42:45 -0800437 *
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700438 * If the first components of each name are not equal, this returns -1 if the first comes
439 * before the second using the NDN canonical ordering for name components, or 1 if it
440 * comes after. If they are equal, this compares the second components of each name, etc.
441 * If both names are the same up to the size of the shorter name, this returns -1 if the
442 * first name is shorter than the second or 1 if it is longer. For example, if you
443 * std::sort gives: /a/b/d /a/b/cc /c /c/a /bb . This is intuitive because all names with
444 * the prefix /a are next to each other. But it may be also be counter-intuitive because
445 * /c comes before /bb according to NDN canonical ordering since it is shorter. @param
Junxiao Shia6452ac2015-01-23 11:21:06 -0700446 * other The other Name to compare with.
447 *
448 * @retval 0 if they compare equal
449 * @retval -1 if *this comes before other in the canonical ordering
450 * @retval 1 if *this comes after other in the canonical ordering
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700451 *
452 * @see http://named-data.net/doc/ndn-tlv/name.html#canonical-order
Jeff Thompsonafc45a92014-01-15 12:42:45 -0800453 */
454 int
Junxiao Shia6452ac2015-01-23 11:21:06 -0700455 compare(const Name& other) const
456 {
457 return this->compare(0, npos, other);
458 }
459
460 /** \brief compares [pos1, pos1+count1) components in this Name
461 * to [pos2, pos2+count2) components in \p other
462 *
463 * This is equivalent to this->getSubName(pos1, count1).compare(other.getSubName(pos2, count2));
464 */
465 int
466 compare(size_t pos1, size_t count1,
467 const Name& other, size_t pos2 = 0, size_t count2 = npos) const;
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700468
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700469 /**
470 * Append the component
471 * @param component The component of type T.
472 */
473 template<class T> void
Alexander Afanasyev1dd95c52014-03-22 19:11:36 -0700474 push_back(const T& component)
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700475 {
476 append(component);
477 }
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700478
Jeff Thompson91737f52013-10-04 11:07:24 -0700479 /**
480 * Check if this name has the same component count and components as the given name.
481 * @param name The Name to check.
482 * @return true if the names are equal, otherwise false.
483 */
484 bool
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700485 operator==(const Name& name) const
486 {
487 return equals(name);
488 }
Jeff Thompson91737f52013-10-04 11:07:24 -0700489
490 /**
491 * Check if this name has the same component count and components as the given name.
492 * @param name The Name to check.
493 * @return true if the names are not equal, otherwise false.
494 */
495 bool
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700496 operator!=(const Name& name) const
497 {
498 return !equals(name);
499 }
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700500
Jeff Thompson82568ad2013-12-17 15:17:40 -0800501 /**
Jeff Thompsonafc45a92014-01-15 12:42:45 -0800502 * Return true if this is less than or equal to the other Name in the NDN canonical ordering.
503 * @param other The other Name to compare with.
504 *
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700505 * @see http://named-data.net/doc/ndn-tlv/name.html#canonical-order
Jeff Thompson82568ad2013-12-17 15:17:40 -0800506 */
Jeff Thompsonafc45a92014-01-15 12:42:45 -0800507 bool
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700508 operator<=(const Name& other) const
509 {
510 return compare(other) <= 0;
511 }
Jeff Thompsonafc45a92014-01-15 12:42:45 -0800512
513 /**
514 * Return true if this is less than the other Name in the NDN canonical ordering.
515 * @param other The other Name to compare with.
516 *
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700517 * @see http://named-data.net/doc/ndn-tlv/name.html#canonical-order
Jeff Thompsonafc45a92014-01-15 12:42:45 -0800518 */
519 bool
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700520 operator<(const Name& other) const
521 {
522 return compare(other) < 0;
523 }
Jeff Thompsonafc45a92014-01-15 12:42:45 -0800524
525 /**
526 * Return true if this is less than or equal to the other Name in the NDN canonical ordering.
527 * @param other The other Name to compare with.
528 *
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700529 * @see http://named-data.net/doc/ndn-tlv/name.html#canonical-order
Jeff Thompsonafc45a92014-01-15 12:42:45 -0800530 */
531 bool
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700532 operator>=(const Name& other) const
533 {
534 return compare(other) >= 0;
535 }
Jeff Thompsonafc45a92014-01-15 12:42:45 -0800536
537 /**
538 * Return true if this is greater than the other Name in the NDN canonical ordering.
539 * @param other The other Name to compare with.
540 *
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700541 * @see http://named-data.net/doc/ndn-tlv/name.html#canonical-order
Jeff Thompsonafc45a92014-01-15 12:42:45 -0800542 */
543 bool
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700544 operator>(const Name& other) const
545 {
546 return compare(other) > 0;
547 }
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700548
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700549 //
550 // Iterator interface to name components.
551 //
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700552
553 /**
554 * Begin iterator (const).
555 */
556 const_iterator
Alexander Afanasyev95e8c2f2014-02-06 17:29:30 -0800557 begin() const
558 {
559 return reinterpret_cast<const_iterator>(&*m_nameBlock.elements().begin());
560 }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700561
562 /**
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700563 * End iterator (const).
Alexander Afanasyev95e8c2f2014-02-06 17:29:30 -0800564 *
565 * @todo Check if this crash when there are no elements in the buffer
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700566 */
567 const_iterator
Alexander Afanasyev29e5c3d2014-02-11 00:01:10 -0800568 end() const
569 {
570 return reinterpret_cast<const_iterator>(&*m_nameBlock.elements().end());
571 }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700572
573 /**
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700574 * Reverse begin iterator (const).
575 */
576 const_reverse_iterator
Alexander Afanasyev29e5c3d2014-02-11 00:01:10 -0800577 rbegin() const
578 {
579 return const_reverse_iterator(end());
580 }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700581
582 /**
583 * Reverse end iterator (const).
584 */
585 const_reverse_iterator
Alexander Afanasyev29e5c3d2014-02-11 00:01:10 -0800586 rend() const
587 {
588 return const_reverse_iterator(begin());
589 }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700590
Alexander Afanasyevc89efb42015-02-10 18:26:42 -0800591private:
592 void
593 construct(const char* uri);
594
Junxiao Shia6452ac2015-01-23 11:21:06 -0700595public:
596 /** \brief indicates "until the end" in getSubName and compare
597 */
598 static const size_t npos;
599
Jeff Thompson9c41dfe2013-06-27 12:10:25 -0700600private:
Alexander Afanasyev95e8c2f2014-02-06 17:29:30 -0800601 mutable Block m_nameBlock;
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800602};
603
Alexander Afanasyev15f67312014-07-22 15:11:09 -0700604std::ostream&
605operator<<(std::ostream& os, const Name& name);
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700606
Alexander Afanasyev15f67312014-07-22 15:11:09 -0700607std::istream&
608operator>>(std::istream& is, Name& name);
Alexander Afanasyev52eb20d2014-02-06 18:25:54 -0800609
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800610inline bool
611Name::hasWire() const
Alexander Afanasyev52eb20d2014-02-06 18:25:54 -0800612{
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800613 return m_nameBlock.hasWire();
Alexander Afanasyev52eb20d2014-02-06 18:25:54 -0800614}
615
Alexander Afanasyev95e8c2f2014-02-06 17:29:30 -0800616} // namespace ndn
Jeff Thompson9c41dfe2013-06-27 12:10:25 -0700617
Yingdi Yu90e23582014-11-06 14:21:04 -0800618namespace std {
619template<>
620struct hash<ndn::Name>
621{
622 size_t
623 operator()(const ndn::Name& name) const;
624};
625
626} // namespace std
627
Jeff Thompson9c41dfe2013-06-27 12:10:25 -0700628#endif