blob: 1719e92976527ed6d3baf836ac933f3ce32c1562 [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/**
Alexander Afanasyevc169a812014-05-20 20:37:29 -04003 * Copyright (c) 2013-2014 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/**
37 * A Name holds an array of Name::Component and represents an NDN name.
38 */
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 /**
73 * Create a new Name with no components.
74 */
Alexander Afanasyev95e8c2f2014-02-06 17:29:30 -080075 Name()
Steve DiBenedetto54ce6682014-07-22 13:22:57 -060076 : m_nameBlock(tlv::Name)
Alexander Afanasyev95e8c2f2014-02-06 17:29:30 -080077 {
Jeff Thompson016ed642013-07-02 14:39:06 -070078 }
Alexander Afanasyev52eb20d2014-02-06 18:25:54 -080079
80 /**
81 * @brief Create Name object from wire block
82 *
83 * This is a more efficient equivalent for
84 * @code
85 * Name name;
86 * name.wireDecode(wire);
87 * @endcode
88 */
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -080089 explicit
Alexander Afanasyev1dd95c52014-03-22 19:11:36 -070090 Name(const Block& wire)
Alexander Afanasyev52eb20d2014-02-06 18:25:54 -080091 {
92 m_nameBlock = wire;
93 m_nameBlock.parse();
94 }
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -070095
Jeff Thompson3f2175b2013-07-31 17:12:47 -070096 /**
Jeff Thompson443398d2013-07-02 19:45:46 -070097 * Parse the uri according to the NDN URI Scheme and create the name with the components.
Jeff Thompson3f2175b2013-07-31 17:12:47 -070098 * @param uri The URI string.
Jeff Thompson443398d2013-07-02 19:45:46 -070099 */
Jeff Thompson3549ef32013-09-25 14:05:17 -0700100 Name(const char* uri)
Jeff Thompson67515bd2013-08-15 17:43:22 -0700101 {
102 set(uri);
103 }
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700104
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700105 /**
Jeff Thompson3549ef32013-09-25 14:05:17 -0700106 * Parse the uri according to the NDN URI Scheme and create the name with the components.
107 * @param uri The URI string.
108 */
109 Name(const std::string& uri)
110 {
111 set(uri.c_str());
112 }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700113
Alexander Afanasyev380420b2014-02-09 20:52:29 -0800114 /**
115 * @brief Fast encoding or block size estimation
116 */
117 template<bool T>
Wentao Shang77949212014-02-01 23:42:24 -0800118 size_t
Alexander Afanasyev1dd95c52014-03-22 19:11:36 -0700119 wireEncode(EncodingImpl<T>& block) const;
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700120
Alexander Afanasyev1dd95c52014-03-22 19:11:36 -0700121 const Block&
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800122 wireEncode() const;
Alexander Afanasyev848c61a2014-01-03 13:52:04 -0800123
124 void
Alexander Afanasyev1dd95c52014-03-22 19:11:36 -0700125 wireDecode(const Block& wire);
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800126
127 /**
128 * @brief Check if already has wire
129 */
130 bool
131 hasWire() const;
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700132
Jeff Thompsonb468c312013-07-01 17:50:14 -0700133 /**
Jeff Thompson67515bd2013-08-15 17:43:22 -0700134 * Parse the uri according to the NDN URI Scheme and set the name with the components.
Jeff Thompson7781b392013-12-17 11:45:59 -0800135 * @param uri The null-terminated URI string.
Jeff Thompson67515bd2013-08-15 17:43:22 -0700136 */
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700137 void
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700138 set(const char* uri);
Jeff Thompson67515bd2013-08-15 17:43:22 -0700139
140 /**
Jeff Thompson7781b392013-12-17 11:45:59 -0800141 * Parse the uri according to the NDN URI Scheme and set the name with the components.
142 * @param uri The URI string.
143 */
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700144 void
Alexander Afanasyev95e8c2f2014-02-06 17:29:30 -0800145 set(const std::string& uri)
146 {
147 set(uri.c_str());
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700148 }
149
Jeff Thompson7781b392013-12-17 11:45:59 -0800150 /**
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700151 * Append a new component, copying from value of length valueLength.
Jeff Thompson26b0d792013-09-23 16:19:01 -0700152 * @return This name so that you can chain calls to append.
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700153 */
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700154 Name&
Alexander Afanasyev1dd95c52014-03-22 19:11:36 -0700155 append(const uint8_t* value, size_t valueLength)
Jeff Thompson0f743452013-09-12 14:23:18 -0700156 {
Alexander Afanasyev29e5c3d2014-02-11 00:01:10 -0800157 m_nameBlock.push_back(Component(value, valueLength));
Jeff Thompson26b0d792013-09-23 16:19:01 -0700158 return *this;
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700159 }
Jeff Thompsonf72b1ac2013-08-16 16:44:41 -0700160
Alexander Afanasyevbf9671d2014-02-11 13:44:13 -0800161 /**
162 * Append a new component, copying from value of length valueLength.
163 * @return This name so that you can chain calls to append.
164 */
165 template<class InputIterator>
166 Name&
167 append(InputIterator begin, InputIterator end)
168 {
169 m_nameBlock.push_back(Component(begin, end));
170 return *this;
171 }
172
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700173 Name&
Alexander Afanasyev1dd95c52014-03-22 19:11:36 -0700174 append(const Component& value)
Jeff Thompson21eb7212013-09-26 09:05:40 -0700175 {
Alexander Afanasyev29e5c3d2014-02-11 00:01:10 -0800176 m_nameBlock.push_back(value);
Jeff Thompson21eb7212013-09-26 09:05:40 -0700177 return *this;
178 }
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800179
Alexander Afanasyev594cdb22014-01-03 15:11:33 -0800180 /**
181 * @brief Append name component that represented as a string
182 *
183 * Note that this method is necessary to ensure correctness and unambiguity of
184 * ``append("string")`` operations (both Component and Name can be implicitly
185 * converted from string, each having different outcomes
186 */
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700187 Name&
Alexander Afanasyev1dd95c52014-03-22 19:11:36 -0700188 append(const char* value)
Alexander Afanasyev594cdb22014-01-03 15:11:33 -0800189 {
Alexander Afanasyev29e5c3d2014-02-11 00:01:10 -0800190 m_nameBlock.push_back(Component(value));
Alexander Afanasyev594cdb22014-01-03 15:11:33 -0800191 return *this;
192 }
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700193
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800194 Name&
Alexander Afanasyev1dd95c52014-03-22 19:11:36 -0700195 append(const Block& value)
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800196 {
Steve DiBenedetto54ce6682014-07-22 13:22:57 -0600197 if (value.type() == tlv::NameComponent)
Alexander Afanasyev29e5c3d2014-02-11 00:01:10 -0800198 m_nameBlock.push_back(value);
Alexander Afanasyev380420b2014-02-09 20:52:29 -0800199 else
Steve DiBenedetto54ce6682014-07-22 13:22:57 -0600200 m_nameBlock.push_back(Block(tlv::NameComponent, value));
Alexander Afanasyev380420b2014-02-09 20:52:29 -0800201
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800202 return *this;
203 }
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700204
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700205 /**
Jeff Thompson26b0d792013-09-23 16:19:01 -0700206 * Append the components of the given name to this name.
207 * @param name The Name with components to append.
208 * @return This name so that you can chain calls to append.
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700209 */
Jeff Thompson26b0d792013-09-23 16:19:01 -0700210 Name&
211 append(const Name& name);
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700212
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700213 /**
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700214 * Clear all the components.
215 */
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700216 void
Alexander Afanasyev95e8c2f2014-02-06 17:29:30 -0800217 clear()
218 {
Steve DiBenedetto54ce6682014-07-22 13:22:57 -0600219 m_nameBlock = Block(tlv::Name);
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700220 }
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700221
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700222 /**
Jeff Thompsond0159d72013-09-23 13:34:15 -0700223 * Get a new name, constructed as a subset of components.
224 * @param iStartComponent The index if the first component to get.
225 * @param nComponents The number of components starting at iStartComponent.
226 * @return A new name.
227 */
228 Name
229 getSubName(size_t iStartComponent, size_t nComponents) const;
230
231 /**
Alexander Afanasyev15f67312014-07-22 15:11:09 -0700232 * @brief Get a new name, constructed as a subset of components starting at
233 * iStartComponent until the end of the name.
234 *
Jeff Thompsond0159d72013-09-23 13:34:15 -0700235 * @param iStartComponent The index if the first component to get.
236 * @return A new name.
237 */
238 Name
239 getSubName(size_t iStartComponent) const;
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700240
Jeff Thompsond0159d72013-09-23 13:34:15 -0700241 /**
Alexander Afanasyev15f67312014-07-22 15:11:09 -0700242 * @brief Return a new Name with the first nComponents components of this Name.
243 *
244 * @param nComponents The number of prefix components. If nComponents is -N then return
245 * the prefix up to name.size() - N. For example getPrefix(-1)
246 * returns the name without the final component.
Jeff Thompsond0159d72013-09-23 13:34:15 -0700247 * @return A new Name.
248 */
249 Name
Alexander Afanasyev15f67312014-07-22 15:11:09 -0700250 getPrefix(ssize_t nComponents) const
Jeff Thompsond0159d72013-09-23 13:34:15 -0700251 {
Jeff Thompsoneb0358f2013-12-17 10:59:53 -0800252 if (nComponents < 0)
Alexander Afanasyev29e5c3d2014-02-11 00:01:10 -0800253 return getSubName(0, m_nameBlock.elements_size() + nComponents);
Jeff Thompsoneb0358f2013-12-17 10:59:53 -0800254 else
255 return getSubName(0, nComponents);
Jeff Thompsond0159d72013-09-23 13:34:15 -0700256 }
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700257
Jeff Thompsond0159d72013-09-23 13:34:15 -0700258 /**
Jeff Thompsone6063512013-07-01 15:11:28 -0700259 * Encode this name as a URI.
Jeff Thompson3f2175b2013-07-31 17:12:47 -0700260 * @return The encoded URI.
Jeff Thompsone6063512013-07-01 15:11:28 -0700261 */
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700262 std::string
Jeff Thompson0050abe2013-09-17 12:50:25 -0700263 toUri() const;
Jeff Thompsond129ac12013-10-11 14:30:12 -0700264
265 /**
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700266 * @brief Append a component with the number encoded as nonNegativeInteger
267 *
268 * @see http://named-data.net/doc/ndn-tlv/tlv.html#non-negative-integer-encoding
269 *
Steve DiBenedettoc145d492014-03-11 16:35:45 -0600270 * @param number The non-negative number
271 * @return This name so that you can chain calls to append.
272 */
273 Name&
Alexander Afanasyev15f67312014-07-22 15:11:09 -0700274 appendNumber(uint64_t number);
Steve DiBenedettoc145d492014-03-11 16:35:45 -0600275
Jeff Thompsonec7789a2013-08-21 11:08:36 -0700276 /**
Alexander Afanasyev15f67312014-07-22 15:11:09 -0700277 * @brief Create a component encoded as NameComponentWithMarker
278 *
279 * @see http://named-data.net/doc/tech-memos/naming-conventions.pdf
280 *
281 * @param marker 1-byte marker octet
282 * @param number The non-negative number
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700283 */
284 Name&
Alexander Afanasyev15f67312014-07-22 15:11:09 -0700285 appendNumberWithMarker(uint8_t marker, uint64_t number);
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700286
287 /**
Alexander Afanasyev15f67312014-07-22 15:11:09 -0700288 * @brief Append version using NDN naming conventions
289 *
290 * @see http://named-data.net/doc/tech-memos/naming-conventions.pdf
291 */
292 Name&
293 appendVersion(uint64_t version);
294
295 /**
296 * @brief Append version using NDN naming conventions based on current UNIX timestamp
297 * in milliseconds
298 *
299 * @see http://named-data.net/doc/tech-memos/naming-conventions.pdf
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700300 */
301 Name&
302 appendVersion();
303
304 /**
Alexander Afanasyev15f67312014-07-22 15:11:09 -0700305 * @brief Append segment number (sequential) using NDN naming conventions
306 *
307 * @see http://named-data.net/doc/tech-memos/naming-conventions.pdf
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700308 */
309 Name&
Alexander Afanasyev15f67312014-07-22 15:11:09 -0700310 appendSegment(uint64_t segmentNo);
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700311
312 /**
Alexander Afanasyev15f67312014-07-22 15:11:09 -0700313 * @brief Append segment byte offset using NDN naming conventions
314 *
315 * @see http://named-data.net/doc/tech-memos/naming-conventions.pdf
316 */
317 Name&
318 appendSegmentOffset(uint64_t offset);
319
320 /**
321 * @brief Append timestamp using NDN naming conventions
322 *
323 * @see http://named-data.net/doc/tech-memos/naming-conventions.pdf
324 */
325 Name&
326 appendTimestamp(const time::system_clock::TimePoint& timePoint = time::system_clock::now());
327
328 /**
329 * @brief Append sequence number using NDN naming conventions
330 *
331 * @see http://named-data.net/doc/tech-memos/naming-conventions.pdf
332 */
333 Name&
334 appendSequenceNumber(uint64_t seqNo);
335
336 /**
337 * @brief Get the successor of a name
338 *
339 * The successor of a name is defined as follows:
340 *
341 * N represents the set of NDN Names, and X,Y ∈ N.
342 * Operator < is defined by canonical order on N.
343 * Y is the successor of X, if (a) X < Y, and (b) ∄ Z ∈ N s.t. X < Z < Y.
344 *
345 * In plain words, successor of a name is the same name, but with its last component
346 * advanced to a next possible value.
347 *
348 * Examples:
349 *
350 * - successor for / is /%00
351 * - successor for /%00%01/%01%02 is /%00%01/%01%03
352 * - successor for /%00%01/%01%FF is /%00%01/%02%00
353 * - successor for /%00%01/%FF%FF is /%00%01/%00%00%00
354 *
Shuo Chen5aa8c742014-06-22 15:00:02 +0800355 * @return a new name
356 */
357 Name
358 getSuccessor() const;
359
360 /**
Jeff Thompson3c2ab012013-10-02 14:18:16 -0700361 * Check if this name has the same component count and components as the given name.
362 * @param name The Name to check.
363 * @return true if the names are equal, otherwise false.
364 */
365 bool
366 equals(const Name& name) const;
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700367
Jeff Thompson3c2ab012013-10-02 14:18:16 -0700368 /**
Alexander Afanasyev15f67312014-07-22 15:11:09 -0700369 * @brief Check if the N components of this name are the same as the first N components
370 * of the given name.
371 *
Jeff Thompsonec7789a2013-08-21 11:08:36 -0700372 * @param name The Name to check.
Alexander Afanasyev15f67312014-07-22 15:11:09 -0700373 * @return true if this matches the given name, otherwise false. This always returns
374 * true if this name is empty.
Jeff Thompsonec7789a2013-08-21 11:08:36 -0700375 */
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700376 bool
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800377 isPrefixOf(const Name& name) const;
378
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700379 //
380 // vector equivalent interface.
381 //
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800382
383 /**
384 * @brief Check if name is emtpy
385 */
386 bool
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700387 empty() const
388 {
389 return m_nameBlock.elements().empty();
390 }
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700391
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700392 /**
393 * Get the number of components.
394 * @return The number of components.
395 */
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700396 size_t
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700397 size() const
398 {
399 return m_nameBlock.elements_size();
400 }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700401
402 /**
403 * Get the component at the given index.
404 * @param i The index of the component, starting from 0.
405 * @return The name component at the index.
406 */
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700407 const Component&
Alexander Afanasyev8f9aa8bed2013-12-30 15:58:57 -0800408 get(ssize_t i) const
409 {
410 if (i >= 0)
Alexander Afanasyev95e8c2f2014-02-06 17:29:30 -0800411 return reinterpret_cast<const Component&>(m_nameBlock.elements()[i]);
Alexander Afanasyev8f9aa8bed2013-12-30 15:58:57 -0800412 else
Alexander Afanasyev95e8c2f2014-02-06 17:29:30 -0800413 return reinterpret_cast<const Component&>(m_nameBlock.elements()[size() + i]);
414 }
415
416 const Component&
Alexander Afanasyev1dd95c52014-03-22 19:11:36 -0700417 operator[](ssize_t i) const
Alexander Afanasyev95e8c2f2014-02-06 17:29:30 -0800418 {
419 return get(i);
Alexander Afanasyev8f9aa8bed2013-12-30 15:58:57 -0800420 }
Alexander Afanasyevc2344292014-03-02 00:08:00 +0000421
422 /**
423 * @brief Get component at the specified index
424 *
425 * Unlike get() and operator[] methods, at() checks for out of bounds
426 * and will throw Name::Error when it happens
427 *
428 * @throws Name::Error if index out of bounds
429 */
Alexander Afanasyev95e8c2f2014-02-06 17:29:30 -0800430 const Component&
431 at(ssize_t i) const
432 {
Alexander Afanasyev1dd95c52014-03-22 19:11:36 -0700433 if ((i >= 0 && static_cast<size_t>(i) >= size()) ||
434 (i < 0 && static_cast<size_t>(-i) > size()))
Alexander Afanasyevc2344292014-03-02 00:08:00 +0000435 throw Error("Requested component does not exist (out of bounds)");
436
Alexander Afanasyev95e8c2f2014-02-06 17:29:30 -0800437 return get(i);
438 }
439
Jeff Thompsonafc45a92014-01-15 12:42:45 -0800440 /**
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700441 * @brief Compare this to the other Name using NDN canonical ordering.
Jeff Thompsonafc45a92014-01-15 12:42:45 -0800442 *
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700443 * If the first components of each name are not equal, this returns -1 if the first comes
444 * before the second using the NDN canonical ordering for name components, or 1 if it
445 * comes after. If they are equal, this compares the second components of each name, etc.
446 * If both names are the same up to the size of the shorter name, this returns -1 if the
447 * first name is shorter than the second or 1 if it is longer. For example, if you
448 * std::sort gives: /a/b/d /a/b/cc /c /c/a /bb . This is intuitive because all names with
449 * the prefix /a are next to each other. But it may be also be counter-intuitive because
450 * /c comes before /bb according to NDN canonical ordering since it is shorter. @param
451 * other The other Name to compare with. @return 0 If they compare equal, -1 if *this
452 * comes before other in the canonical ordering, or 1 if *this comes after other in the
453 * canonical ordering.
454 *
455 * @see http://named-data.net/doc/ndn-tlv/name.html#canonical-order
Jeff Thompsonafc45a92014-01-15 12:42:45 -0800456 */
457 int
458 compare(const Name& other) const;
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700459
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700460 /**
461 * Append the component
462 * @param component The component of type T.
463 */
464 template<class T> void
Alexander Afanasyev1dd95c52014-03-22 19:11:36 -0700465 push_back(const T& component)
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700466 {
467 append(component);
468 }
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700469
Jeff Thompson91737f52013-10-04 11:07:24 -0700470 /**
471 * Check if this name has the same component count and components as the given name.
472 * @param name The Name to check.
473 * @return true if the names are equal, otherwise false.
474 */
475 bool
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700476 operator==(const Name& name) const
477 {
478 return equals(name);
479 }
Jeff Thompson91737f52013-10-04 11:07:24 -0700480
481 /**
482 * Check if this name has the same component count and components as the given name.
483 * @param name The Name to check.
484 * @return true if the names are not equal, otherwise false.
485 */
486 bool
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700487 operator!=(const Name& name) const
488 {
489 return !equals(name);
490 }
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700491
Jeff Thompson82568ad2013-12-17 15:17:40 -0800492 /**
Jeff Thompsonafc45a92014-01-15 12:42:45 -0800493 * Return true if this is less than or equal to the other Name in the NDN canonical ordering.
494 * @param other The other Name to compare with.
495 *
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700496 * @see http://named-data.net/doc/ndn-tlv/name.html#canonical-order
Jeff Thompson82568ad2013-12-17 15:17:40 -0800497 */
Jeff Thompsonafc45a92014-01-15 12:42:45 -0800498 bool
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700499 operator<=(const Name& other) const
500 {
501 return compare(other) <= 0;
502 }
Jeff Thompsonafc45a92014-01-15 12:42:45 -0800503
504 /**
505 * Return true if this is less than the other Name in the NDN canonical ordering.
506 * @param other The other Name to compare with.
507 *
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700508 * @see http://named-data.net/doc/ndn-tlv/name.html#canonical-order
Jeff Thompsonafc45a92014-01-15 12:42:45 -0800509 */
510 bool
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700511 operator<(const Name& other) const
512 {
513 return compare(other) < 0;
514 }
Jeff Thompsonafc45a92014-01-15 12:42:45 -0800515
516 /**
517 * Return true if this is less than or equal to the other Name in the NDN canonical ordering.
518 * @param other The other Name to compare with.
519 *
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700520 * @see http://named-data.net/doc/ndn-tlv/name.html#canonical-order
Jeff Thompsonafc45a92014-01-15 12:42:45 -0800521 */
522 bool
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700523 operator>=(const Name& other) const
524 {
525 return compare(other) >= 0;
526 }
Jeff Thompsonafc45a92014-01-15 12:42:45 -0800527
528 /**
529 * Return true if this is greater than the other Name in the NDN canonical ordering.
530 * @param other The other Name to compare with.
531 *
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700532 * @see http://named-data.net/doc/ndn-tlv/name.html#canonical-order
Jeff Thompsonafc45a92014-01-15 12:42:45 -0800533 */
534 bool
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700535 operator>(const Name& other) const
536 {
537 return compare(other) > 0;
538 }
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700539
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700540 //
541 // Iterator interface to name components.
542 //
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700543
544 /**
545 * Begin iterator (const).
546 */
547 const_iterator
Alexander Afanasyev95e8c2f2014-02-06 17:29:30 -0800548 begin() const
549 {
550 return reinterpret_cast<const_iterator>(&*m_nameBlock.elements().begin());
551 }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700552
553 /**
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700554 * End iterator (const).
Alexander Afanasyev95e8c2f2014-02-06 17:29:30 -0800555 *
556 * @todo Check if this crash when there are no elements in the buffer
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700557 */
558 const_iterator
Alexander Afanasyev29e5c3d2014-02-11 00:01:10 -0800559 end() const
560 {
561 return reinterpret_cast<const_iterator>(&*m_nameBlock.elements().end());
562 }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700563
564 /**
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700565 * Reverse begin iterator (const).
566 */
567 const_reverse_iterator
Alexander Afanasyev29e5c3d2014-02-11 00:01:10 -0800568 rbegin() const
569 {
570 return const_reverse_iterator(end());
571 }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700572
573 /**
574 * Reverse end iterator (const).
575 */
576 const_reverse_iterator
Alexander Afanasyev29e5c3d2014-02-11 00:01:10 -0800577 rend() const
578 {
579 return const_reverse_iterator(begin());
580 }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700581
Jeff Thompson9c41dfe2013-06-27 12:10:25 -0700582private:
Alexander Afanasyev95e8c2f2014-02-06 17:29:30 -0800583 mutable Block m_nameBlock;
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800584};
585
Alexander Afanasyev15f67312014-07-22 15:11:09 -0700586std::ostream&
587operator<<(std::ostream& os, const Name& name);
Alexander Afanasyev4b98e8c2014-03-22 19:10:19 -0700588
Alexander Afanasyev15f67312014-07-22 15:11:09 -0700589std::istream&
590operator>>(std::istream& is, Name& name);
Alexander Afanasyev52eb20d2014-02-06 18:25:54 -0800591
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800592inline bool
593Name::hasWire() const
Alexander Afanasyev52eb20d2014-02-06 18:25:54 -0800594{
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800595 return m_nameBlock.hasWire();
Alexander Afanasyev52eb20d2014-02-06 18:25:54 -0800596}
597
Alexander Afanasyev95e8c2f2014-02-06 17:29:30 -0800598} // namespace ndn
Jeff Thompson9c41dfe2013-06-27 12:10:25 -0700599
Yingdi Yu90e23582014-11-06 14:21:04 -0800600namespace std {
601template<>
602struct hash<ndn::Name>
603{
604 size_t
605 operator()(const ndn::Name& name) const;
606};
607
608} // namespace std
609
Jeff Thompson9c41dfe2013-06-27 12:10:25 -0700610#endif