blob: c4e7e5cc17729835dc4ba8fbf818458338fe1805 [file] [log] [blame]
Jeff Thompson25b4e612013-10-10 16:03:24 -07001/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil -*- */
Jeff Thompson47eecfc2013-07-07 22:56:46 -07002/**
Jeff Thompson7687dc02013-09-13 11:54:07 -07003 * Copyright (C) 2013 Regents of the University of California.
4 * @author: Jeff Thompson <jefft0@remap.ucla.edu>
Jeff Thompsonec39fbd2013-10-04 10:56:23 -07005 * @author: Alexander Afanasyev <alexander.afanasyev@ucla.edu>
6 * @author: Zhenkai Zhu <zhenkai@cs.ucla.edu>
Jeff Thompson47eecfc2013-07-07 22:56:46 -07007 * See COPYING for copyright and distribution information.
Jeff Thompson9c41dfe2013-06-27 12:10:25 -07008 */
9
10#ifndef NDN_NAME_HPP
Jeff Thompson2d27e2f2013-08-09 12:55:00 -070011#define NDN_NAME_HPP
Jeff Thompson9c41dfe2013-06-27 12:10:25 -070012
13#include <vector>
Jeff Thompson443398d2013-07-02 19:45:46 -070014#include <string>
Jeff Thompsonec7789a2013-08-21 11:08:36 -070015#include <sstream>
Alexander Afanasyevaf283d82014-01-03 13:23:34 -080016#include <string.h>
17#include "encoding/block.hpp"
Jeff Thompson25b4e612013-10-10 16:03:24 -070018
Jeff Thompson9c41dfe2013-06-27 12:10:25 -070019namespace ndn {
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -070020
Jeff Thompsonc7d65502013-11-06 17:22:26 -080021/**
22 * A Name holds an array of Name::Component and represents an NDN name.
23 */
Jeff Thompson9c41dfe2013-06-27 12:10:25 -070024class Name {
25public:
Jeff Thompsonc1c12e42013-09-13 19:08:45 -070026 /**
Jeff Thompsonc7d65502013-11-06 17:22:26 -080027 * A Name::Component holds a read-only name component value.
Jeff Thompsonc1c12e42013-09-13 19:08:45 -070028 */
Alexander Afanasyev58743332014-01-12 13:24:42 -080029 class Component
Alexander Afanasyevaf283d82014-01-03 13:23:34 -080030 {
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -070031 public:
32 /**
Jeff Thompson46411c92013-09-13 19:31:25 -070033 * Create a new Name::Component with a null value.
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -070034 */
35 Component()
36 {
37 }
Alexander Afanasyevaf283d82014-01-03 13:23:34 -080038
39 // copy constructor OK
40
41 /**
42 * Create a new Name::Component, taking another pointer to the Blob value.
43 * @param value A blob with a pointer to an immutable array. The pointer is copied.
44 */
45 Component(const ConstBufferPtr &buffer)
Alexander Afanasyev58743332014-01-12 13:24:42 -080046 : value_ (buffer)
Alexander Afanasyevaf283d82014-01-03 13:23:34 -080047 {
48 }
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -070049
50 /**
51 * Create a new Name::Component, copying the given value.
52 * @param value The value byte array.
53 */
Alexander Afanasyevaf283d82014-01-03 13:23:34 -080054 Component(const Buffer& value)
Alexander Afanasyev58743332014-01-12 13:24:42 -080055 : value_ (new Buffer(value))
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -070056 {
57 }
58
59 /**
60 * Create a new Name::Component, copying the given value.
61 * @param value Pointer to the value byte array.
62 * @param valueLen Length of value.
63 */
Jeff Thompson97223af2013-09-24 17:01:27 -070064 Component(const uint8_t *value, size_t valueLen)
Alexander Afanasyev58743332014-01-12 13:24:42 -080065 : value_ (new Buffer(value, valueLen))
Alexander Afanasyevaf283d82014-01-03 13:23:34 -080066 {
67 }
68
69 template<class InputIterator>
70 Component(InputIterator begin, InputIterator end)
Alexander Afanasyev58743332014-01-12 13:24:42 -080071 : value_ (new Buffer(begin, end))
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -070072 {
73 }
Jeff Thompson0f743452013-09-12 14:23:18 -070074
Alexander Afanasyev848c61a2014-01-03 13:52:04 -080075 Component(const char *string)
Alexander Afanasyev58743332014-01-12 13:24:42 -080076 : value_ (new Buffer(string, ::strlen(string)))
Alexander Afanasyev848c61a2014-01-03 13:52:04 -080077 {
78 }
79
Alexander Afanasyevaf283d82014-01-03 13:23:34 -080080 const Buffer&
Alexander Afanasyev58743332014-01-12 13:24:42 -080081 getValue() const { return *value_; }
Jeff Thompson6653b0b2013-09-23 12:32:39 -070082
83 /**
84 * Write this component value to result, escaping characters according to the NDN URI Scheme.
85 * This also adds "..." to a value with zero or more ".".
Jeff Thompson6653b0b2013-09-23 12:32:39 -070086 * @param result the string stream to write to.
87 */
88 void
Alexander Afanasyevaf283d82014-01-03 13:23:34 -080089 toEscapedString(std::ostream& result) const
Jeff Thompson6653b0b2013-09-23 12:32:39 -070090 {
Alexander Afanasyev58743332014-01-12 13:24:42 -080091 Name::toEscapedString(*value_, result);
Jeff Thompson6653b0b2013-09-23 12:32:39 -070092 }
93
94 /**
95 * Convert this component value by escaping characters according to the NDN URI Scheme.
96 * This also adds "..." to a value with zero or more ".".
97 * @return The escaped string.
98 */
99 std::string
Jeff Thompsond0159d72013-09-23 13:34:15 -0700100 toEscapedString() const
Jeff Thompson6653b0b2013-09-23 12:32:39 -0700101 {
Alexander Afanasyev58743332014-01-12 13:24:42 -0800102 return Name::toEscapedString(*value_);
Jeff Thompson6653b0b2013-09-23 12:32:39 -0700103 }
Jeff Thompson9bdb3b22013-09-12 12:42:13 -0700104
Jeff Thompson50b37912013-10-08 13:39:33 -0700105 /**
106 * Interpret this name component as a network-ordered number and return an integer.
107 * @return The integer number.
108 */
109 uint64_t
Jeff Thompson25b4e612013-10-10 16:03:24 -0700110 toNumber() const;
Jeff Thompson27cae532013-10-08 12:52:41 -0700111
Jeff Thompson50b37912013-10-08 13:39:33 -0700112 /**
113 * Interpret this name component as a network-ordered number with a marker and return an integer.
114 * @param marker The required first byte of the component.
115 * @return The integer number.
116 * @throw runtime_error If the first byte of the component does not equal the marker.
117 */
118 uint64_t
119 toNumberWithMarker(uint8_t marker) const;
120
121 /**
122 * Interpret this name component as a segment number according to NDN name conventions (a network-ordered number
123 * where the first byte is the marker 0x00).
124 * @return The integer segment number.
125 * @throw runtime_error If the first byte of the component is not the expected marker.
126 */
127 uint64_t
128 toSegment() const
129 {
130 return toNumberWithMarker(0x00);
131 }
132
133 /**
134 * @deprecated Use toSegment.
135 */
136 uint64_t
137 toSeqNum() const
138 {
139 return toSegment();
140 }
141
142 /**
143 * Interpret this name component as a version number according to NDN name conventions (a network-ordered number
144 * where the first byte is the marker 0xFD). Note that this returns the exact number from the component
145 * without converting it to a time representation.
146 * @return The integer segment number.
147 * @throw runtime_error If the first byte of the component is not the expected marker.
148 */
149 uint64_t
150 toVersion() const
151 {
152 return toNumberWithMarker(0xFD);
153 }
Jeff Thompson27cae532013-10-08 12:52:41 -0700154
Jeff Thompsonc1c12e42013-09-13 19:08:45 -0700155 /**
Jeff Thompsond129ac12013-10-11 14:30:12 -0700156 * Create a component whose value is the network-ordered encoding of the number.
157 * Note: if the number is zero, the result is empty.
158 * @param number The number to be encoded.
159 * @return The component value.
160 */
161 static Component
162 fromNumber(uint64_t number);
Jeff Thompson8aac1992013-08-12 17:26:02 -0700163
164 /**
Jeff Thompsond129ac12013-10-11 14:30:12 -0700165 * Create a component whose value is the marker appended with the network-ordered encoding of the number.
166 * Note: if the number is zero, no bytes are used for the number - the result will have only the marker.
167 * @param number The number to be encoded.
168 * @param marker The marker to use as the first byte of the component.
169 * @return The component value.
Jeff Thompson8aac1992013-08-12 17:26:02 -0700170 */
Jeff Thompsond129ac12013-10-11 14:30:12 -0700171 static Component
172 fromNumberWithMarker(uint64_t number, uint8_t marker);
Jeff Thompsona98000c2013-12-16 14:40:09 -0800173
174 /**
175 * Check if this is the same component as other.
176 * @param other The other Component to compare with.
177 * @return true if the components are equal, otherwise false.
178 */
179 bool
180 equals(const Component& other) const
181 {
Alexander Afanasyev58743332014-01-12 13:24:42 -0800182 return *value_ == *other.value_;
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800183 }
184
185 bool
186 empty() const
187 {
Alexander Afanasyev58743332014-01-12 13:24:42 -0800188 return !value_ || value_->empty();
Jeff Thompsona98000c2013-12-16 14:40:09 -0800189 }
190
191 /**
192 * Check if this is the same component as other.
193 * @param other The other Component to compare with.
194 * @return true if the components are equal, otherwise false.
195 */
196 bool
197 operator == (const Component& other) const { return equals(other); }
198
199 /**
200 * Check if this is not the same component as other.
201 * @param other The other Component to compare with.
202 * @return true if the components are not equal, otherwise false.
203 */
204 bool
205 operator != (const Component& other) const { return !equals(other); }
206
207 /**
208 * Compare this to the other Component using NDN canonical ordering.
209 * @param other The other Component to compare with.
210 * @return 0 If they compare equal, -1 if *this comes before other in the canonical ordering, or
211 * 1 if *this comes after other in the canonical ordering.
212 *
213 * @see http://named-data.net/doc/0.2/technical/CanonicalOrder.html
214 */
215 int
216 compare(const Component& other) const;
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -0700217
Jeff Thompsona98000c2013-12-16 14:40:09 -0800218 /**
219 * Return true if this is less than or equal to the other Component in the NDN canonical ordering.
220 * @param other The other Component to compare with.
221 *
222 * @see http://named-data.net/doc/0.2/technical/CanonicalOrder.html
223 */
224 bool
225 operator <= (const Component& other) const { return compare(other) <= 0; }
226
227 /**
228 * Return true if this is less than the other Component in the NDN canonical ordering.
229 * @param other The other Component to compare with.
230 *
231 * @see http://named-data.net/doc/0.2/technical/CanonicalOrder.html
232 */
233 bool
234 operator < (const Component& other) const { return compare(other) < 0; }
235
236 /**
237 * Return true if this is less than or equal to the other Component in the NDN canonical ordering.
238 * @param other The other Component to compare with.
239 *
240 * @see http://named-data.net/doc/0.2/technical/CanonicalOrder.html
241 */
242 bool
243 operator >= (const Component& other) const { return compare(other) >= 0; }
244
245 /**
246 * Return true if this is greater than the other Component in the NDN canonical ordering.
247 * @param other The other Component to compare with.
248 *
249 * @see http://named-data.net/doc/0.2/technical/CanonicalOrder.html
250 */
251 bool
252 operator > (const Component& other) const { return compare(other) > 0; }
Alexander Afanasyev58743332014-01-12 13:24:42 -0800253 private:
254 ConstBufferPtr value_;
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800255 };
Jeff Thompsona98000c2013-12-16 14:40:09 -0800256
Jeff Thompson443398d2013-07-02 19:45:46 -0700257 /**
258 * Create a new Name with no components.
259 */
Jeff Thompson016ed642013-07-02 14:39:06 -0700260 Name() {
261 }
Jeff Thompson443398d2013-07-02 19:45:46 -0700262
263 /**
Jeff Thompson3f2175b2013-07-31 17:12:47 -0700264 * Create a new Name, copying the name components.
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -0700265 * @param components A vector of Component
Jeff Thompson3f2175b2013-07-31 17:12:47 -0700266 */
Jeff Thompson1656e6a2013-08-29 18:01:48 -0700267 Name(const std::vector<Component>& components)
Jeff Thompson3f2175b2013-07-31 17:12:47 -0700268 : components_(components)
269 {
270 }
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800271
272 Name(const Block &name)
273 {
274 for (Block::element_const_iterator i = name.getAll().begin();
275 i != name.getAll().end();
276 ++i)
277 {
278 append(Component(i->value_begin(), i->value_end()));
279 }
280 }
Jeff Thompson3f2175b2013-07-31 17:12:47 -0700281
282 /**
Jeff Thompson443398d2013-07-02 19:45:46 -0700283 * Parse the uri according to the NDN URI Scheme and create the name with the components.
Jeff Thompson3f2175b2013-07-31 17:12:47 -0700284 * @param uri The URI string.
Jeff Thompson443398d2013-07-02 19:45:46 -0700285 */
Jeff Thompson3549ef32013-09-25 14:05:17 -0700286 Name(const char* uri)
Jeff Thompson67515bd2013-08-15 17:43:22 -0700287 {
288 set(uri);
289 }
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -0700290
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700291 /**
Jeff Thompson3549ef32013-09-25 14:05:17 -0700292 * Parse the uri according to the NDN URI Scheme and create the name with the components.
293 * @param uri The URI string.
294 */
295 Name(const std::string& uri)
296 {
297 set(uri.c_str());
298 }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700299
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800300 const Block &
301 wireEncode() const;
Alexander Afanasyev848c61a2014-01-03 13:52:04 -0800302
303 void
304 wireDecode(const Block &wire);
Jeff Thompsonb468c312013-07-01 17:50:14 -0700305
306 /**
Jeff Thompson67515bd2013-08-15 17:43:22 -0700307 * Parse the uri according to the NDN URI Scheme and set the name with the components.
Jeff Thompson7781b392013-12-17 11:45:59 -0800308 * @param uri The null-terminated URI string.
Jeff Thompson67515bd2013-08-15 17:43:22 -0700309 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700310 void
311 set(const char *uri);
Jeff Thompson67515bd2013-08-15 17:43:22 -0700312
313 /**
Jeff Thompson7781b392013-12-17 11:45:59 -0800314 * Parse the uri according to the NDN URI Scheme and set the name with the components.
315 * @param uri The URI string.
316 */
317 void
318 set(const std::string& uri) { set(uri.c_str()); }
319
320 /**
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700321 * Append a new component, copying from value of length valueLength.
Jeff Thompson26b0d792013-09-23 16:19:01 -0700322 * @return This name so that you can chain calls to append.
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700323 */
Jeff Thompson26b0d792013-09-23 16:19:01 -0700324 Name&
Jeff Thompson97223af2013-09-24 17:01:27 -0700325 append(const uint8_t *value, size_t valueLength)
Jeff Thompson0f743452013-09-12 14:23:18 -0700326 {
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -0700327 components_.push_back(Component(value, valueLength));
Jeff Thompson26b0d792013-09-23 16:19:01 -0700328 return *this;
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700329 }
Jeff Thompsonf72b1ac2013-08-16 16:44:41 -0700330
331 /**
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700332 * Append a new component, copying from value.
Jeff Thompson26b0d792013-09-23 16:19:01 -0700333 * @return This name so that you can chain calls to append.
Jeff Thompsonf72b1ac2013-08-16 16:44:41 -0700334 */
Jeff Thompson26b0d792013-09-23 16:19:01 -0700335 Name&
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800336 append(const Buffer& value)
Jeff Thompson0f743452013-09-12 14:23:18 -0700337 {
338 components_.push_back(value);
Jeff Thompson26b0d792013-09-23 16:19:01 -0700339 return *this;
Jeff Thompson0f743452013-09-12 14:23:18 -0700340 }
341
Jeff Thompson26b0d792013-09-23 16:19:01 -0700342 Name&
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800343 append(const ConstBufferPtr &value)
Jeff Thompson0f743452013-09-12 14:23:18 -0700344 {
Jeff Thompsonf72b1ac2013-08-16 16:44:41 -0700345 components_.push_back(value);
Jeff Thompson26b0d792013-09-23 16:19:01 -0700346 return *this;
Jeff Thompsonf72b1ac2013-08-16 16:44:41 -0700347 }
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700348
Jeff Thompson21eb7212013-09-26 09:05:40 -0700349 Name&
350 append(const Component &value)
351 {
352 components_.push_back(value);
353 return *this;
354 }
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800355
Alexander Afanasyev594cdb22014-01-03 15:11:33 -0800356 /**
357 * @brief Append name component that represented as a string
358 *
359 * Note that this method is necessary to ensure correctness and unambiguity of
360 * ``append("string")`` operations (both Component and Name can be implicitly
361 * converted from string, each having different outcomes
362 */
363 Name&
364 append(const char *value)
365 {
366 components_.push_back(Component(value));
367 return *this;
368 }
369
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800370 Name&
371 append(const Block &value)
372 {
373 components_.push_back(Component(value.begin(), value.end()));
374 return *this;
375 }
Jeff Thompson21eb7212013-09-26 09:05:40 -0700376
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700377 /**
Jeff Thompson26b0d792013-09-23 16:19:01 -0700378 * Append the components of the given name to this name.
379 * @param name The Name with components to append.
380 * @return This name so that you can chain calls to append.
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700381 */
Jeff Thompson26b0d792013-09-23 16:19:01 -0700382 Name&
383 append(const Name& name);
384
385 /**
386 * @deprecated Use append.
387 */
388 Name&
Jeff Thompson97223af2013-09-24 17:01:27 -0700389 appendComponent(const uint8_t *value, size_t valueLength)
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700390 {
Jeff Thompson26b0d792013-09-23 16:19:01 -0700391 return append(value, valueLength);
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700392 }
393
394 /**
Jeff Thompson26b0d792013-09-23 16:19:01 -0700395 * @deprecated Use append.
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700396 */
Jeff Thompson26b0d792013-09-23 16:19:01 -0700397 Name&
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800398 appendComponent(const Buffer& value)
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700399 {
Jeff Thompson26b0d792013-09-23 16:19:01 -0700400 return append(value);
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700401 }
402
403 /**
Jeff Thompson26b0d792013-09-23 16:19:01 -0700404 * @deprecated Use append.
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700405 */
Jeff Thompson26b0d792013-09-23 16:19:01 -0700406 Name&
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800407 appendComponent(const ConstBufferPtr &value)
Jeff Thompson26b0d792013-09-23 16:19:01 -0700408 {
409 return append(value);
410 }
411
412 /**
413 * @deprecated Use append.
414 */
415 Name&
Jeff Thompson97223af2013-09-24 17:01:27 -0700416 addComponent(const uint8_t *value, size_t valueLength)
Jeff Thompson26b0d792013-09-23 16:19:01 -0700417 {
418 return append(value, valueLength);
419 }
420
421 /**
422 * @deprecated Use append.
423 */
424 Name&
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800425 addComponent(const Buffer& value)
Jeff Thompson26b0d792013-09-23 16:19:01 -0700426 {
427 return append(value);
428 }
429
430 /**
431 * @deprecated Use append.
432 */
433 Name&
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800434 addComponent(const ConstBufferPtr &value)
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700435 {
Jeff Thompson26b0d792013-09-23 16:19:01 -0700436 return append(value);
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700437 }
438
439 /**
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700440 * Clear all the components.
441 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700442 void
443 clear() {
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700444 components_.clear();
445 }
446
447 /**
Jeff Thompsoneba62eb2013-10-30 13:24:22 -0700448 * @deprecated use size().
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700449 */
Jeff Thompson97223af2013-09-24 17:01:27 -0700450 size_t
Jeff Thompsoneba62eb2013-10-30 13:24:22 -0700451 getComponentCount() const { return size(); }
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700452
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700453 /**
Jeff Thompsoneba62eb2013-10-30 13:24:22 -0700454 * @deprecated Use get(i).
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700455 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700456 const Component&
Jeff Thompsoneba62eb2013-10-30 13:24:22 -0700457 getComponent(size_t i) const { return get(i); }
Jeff Thompson443398d2013-07-02 19:45:46 -0700458
Jeff Thompsone6063512013-07-01 15:11:28 -0700459 /**
Jeff Thompsond0159d72013-09-23 13:34:15 -0700460 * Get a new name, constructed as a subset of components.
461 * @param iStartComponent The index if the first component to get.
462 * @param nComponents The number of components starting at iStartComponent.
463 * @return A new name.
464 */
465 Name
466 getSubName(size_t iStartComponent, size_t nComponents) const;
467
468 /**
469 * Get a new name, constructed as a subset of components starting at iStartComponent until the end of the name.
470 * @param iStartComponent The index if the first component to get.
471 * @return A new name.
472 */
473 Name
474 getSubName(size_t iStartComponent) const;
475
476 /**
477 * Return a new Name with the first nComponents components of this Name.
Jeff Thompsoneb0358f2013-12-17 10:59:53 -0800478 * @param nComponents The number of prefix components. If nComponents is -N then return the prefix up
479 * to name.size() - N. For example getPrefix(-1) returns the name without the final component.
Jeff Thompsond0159d72013-09-23 13:34:15 -0700480 * @return A new Name.
481 */
482 Name
Jeff Thompsoneb0358f2013-12-17 10:59:53 -0800483 getPrefix(int nComponents) const
Jeff Thompsond0159d72013-09-23 13:34:15 -0700484 {
Jeff Thompsoneb0358f2013-12-17 10:59:53 -0800485 if (nComponents < 0)
486 return getSubName(0, components_.size() + nComponents);
487 else
488 return getSubName(0, nComponents);
Jeff Thompsond0159d72013-09-23 13:34:15 -0700489 }
490
491 /**
Jeff Thompsone6063512013-07-01 15:11:28 -0700492 * Encode this name as a URI.
Jeff Thompson3f2175b2013-07-31 17:12:47 -0700493 * @return The encoded URI.
Jeff Thompsone6063512013-07-01 15:11:28 -0700494 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700495 std::string
496 toUri() const;
Jeff Thompsone6063512013-07-01 15:11:28 -0700497
Jeff Thompson21844fc2013-08-08 14:52:51 -0700498 /**
Jeff Thompson8aac1992013-08-12 17:26:02 -0700499 * Append a component with the encoded segment number.
500 * @param segment The segment number.
Jeff Thompson26b0d792013-09-23 16:19:01 -0700501 * @return This name so that you can chain calls to append.
502 */
503 Name&
Jeff Thompsond129ac12013-10-11 14:30:12 -0700504 appendSegment(uint64_t segment)
Jeff Thompson8aac1992013-08-12 17:26:02 -0700505 {
Jeff Thompsond129ac12013-10-11 14:30:12 -0700506 components_.push_back(Component::fromNumberWithMarker(segment, 0x00));
507 return *this;
508 }
509
510 /**
511 * Append a component with the encoded version number.
512 * Note that this encodes the exact value of version without converting from a time representation.
513 * @param version The version number.
514 * @return This name so that you can chain calls to append.
515 */
516 Name&
517 appendVersion(uint64_t version)
518 {
519 components_.push_back(Component::fromNumberWithMarker(version, 0xFD));
Jeff Thompson26b0d792013-09-23 16:19:01 -0700520 return *this;
Jeff Thompson8aac1992013-08-12 17:26:02 -0700521 }
Alexander Afanasyev594cdb22014-01-03 15:11:33 -0800522
523 /**
524 * @brief Append a component with the encoded version number.
525 *
526 * This version of the method creates version number based on the current timestamp
527 * @return This name so that you can chain calls to append.
528 */
529 Name&
530 appendVersion();
Jeff Thompsoncc35cd42013-08-20 12:23:14 -0700531
Jeff Thompsonec7789a2013-08-21 11:08:36 -0700532 /**
Jeff Thompson3c2ab012013-10-02 14:18:16 -0700533 * Check if this name has the same component count and components as the given name.
534 * @param name The Name to check.
535 * @return true if the names are equal, otherwise false.
536 */
537 bool
538 equals(const Name& name) const;
539
540 /**
Jeff Thompsonec7789a2013-08-21 11:08:36 -0700541 * Check if the N components of this name are the same as the first N components of the given name.
542 * @param name The Name to check.
543 * @return true if this matches the given name, otherwise false. This always returns true if this name is empty.
544 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700545 bool
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800546 isPrefixOf(const Name& name) const;
547
548 bool
549 match(const Name& name) const
550 {
551 return isPrefixOf(name);
552 }
Jeff Thompsonec7789a2013-08-21 11:08:36 -0700553
554 /**
Jeff Thompsond8e53e62013-10-29 16:59:49 -0700555 * Make a Blob value by decoding the escapedString between beginOffset and endOffset according to the NDN URI Scheme.
Jeff Thompson08493592013-11-07 17:44:41 -0800556 * If the escaped string is "", "." or ".." then return a Blob with a null pointer,
557 * which means the component should be skipped in a URI name.
Jeff Thompsond8e53e62013-10-29 16:59:49 -0700558 * @param escapedString The escaped string. It does not need to be null-terminated because we only scan to endOffset.
559 * @param beginOffset The offset in escapedString of the beginning of the portion to decode.
560 * @param endOffset The offset in escapedString of the end of the portion to decode.
561 * @return The Blob value. If the escapedString is not a valid escaped component, then the Blob is a null pointer.
562 */
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800563 static Component
Jeff Thompsond8e53e62013-10-29 16:59:49 -0700564 fromEscapedString(const char *escapedString, size_t beginOffset, size_t endOffset);
565
566 /**
567 * Make a Blob value by decoding the escapedString according to the NDN URI Scheme.
Jeff Thompson08493592013-11-07 17:44:41 -0800568 * If the escaped string is "", "." or ".." then return a Blob with a null pointer,
569 * which means the component should be skipped in a URI name.
Jeff Thompsond8e53e62013-10-29 16:59:49 -0700570 * @param escapedString The null-terminated escaped string.
571 * @return The Blob value. If the escapedString is not a valid escaped component, then the Blob is a null pointer.
572 */
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800573 static Component
Jeff Thompsond8e53e62013-10-29 16:59:49 -0700574 fromEscapedString(const char *escapedString);
575
576 /**
Jeff Thompson7781b392013-12-17 11:45:59 -0800577 * Make a Blob value by decoding the escapedString according to the NDN URI Scheme.
578 * If the escaped string is "", "." or ".." then return a Blob with a null pointer,
579 * which means the component should be skipped in a URI name.
580 * @param escapedString The escaped string.
581 * @return The Blob value. If the escapedString is not a valid escaped component, then the Blob is a null pointer.
582 */
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800583 static Component
Jeff Thompson7781b392013-12-17 11:45:59 -0800584 fromEscapedString(const std::string& escapedString) { return fromEscapedString(escapedString.c_str()); }
585
586 /**
Jeff Thompsonec7789a2013-08-21 11:08:36 -0700587 * Write the value to result, escaping characters according to the NDN URI Scheme.
588 * This also adds "..." to a value with zero or more ".".
589 * @param value the buffer with the value to escape
590 * @param result the string stream to write to.
591 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700592 static void
Alexander Afanasyev2a742762013-12-28 14:09:46 -0800593 toEscapedString(const uint8_t *value, size_t valueSize, std::ostream& result);
Jeff Thompson21844fc2013-08-08 14:52:51 -0700594
Alexander Afanasyev2a742762013-12-28 14:09:46 -0800595 inline static void
596 toEscapedString(const std::vector<uint8_t>& value, std::ostream& result)
597 {
598 toEscapedString(&*value.begin(), value.size(), result);
599 }
600
Jeff Thompson6653b0b2013-09-23 12:32:39 -0700601 /**
602 * Convert the value by escaping characters according to the NDN URI Scheme.
603 * This also adds "..." to a value with zero or more ".".
604 * @param value the buffer with the value to escape
605 * @return The escaped string.
606 */
Alexander Afanasyev2a742762013-12-28 14:09:46 -0800607 inline static std::string
608 toEscapedString(const uint8_t *value, size_t valueSize)
609 {
610 std::ostringstream result;
611 toEscapedString(value, valueSize, result);
612 return result.str();
613 }
Jeff Thompson6653b0b2013-09-23 12:32:39 -0700614
Alexander Afanasyev2a742762013-12-28 14:09:46 -0800615 static inline std::string
616 toEscapedString(const std::vector<uint8_t>& value)
617 {
618 return toEscapedString(&*value.begin(), value.size());
619 }
620
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700621 //
622 // vector equivalent interface.
623 //
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800624
625 /**
626 * @brief Check if name is emtpy
627 */
628 bool
629 empty() const { return components_.empty(); }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700630
631 /**
632 * Get the number of components.
633 * @return The number of components.
634 */
635 size_t
Jeff Thompsoneba62eb2013-10-30 13:24:22 -0700636 size() const { return components_.size(); }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700637
638 /**
639 * Get the component at the given index.
640 * @param i The index of the component, starting from 0.
641 * @return The name component at the index.
642 */
643 const Component&
Alexander Afanasyev8f9aa8bed2013-12-30 15:58:57 -0800644 get(ssize_t i) const
645 {
646 if (i >= 0)
647 return components_[i];
648 else
649 return components_[size() + i];
650 }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700651
652
653 const Component&
654 operator [] (int i) const
655 {
656 return get(i);
657 }
658
659 /**
660 * Append the component
661 * @param component The component of type T.
662 */
663 template<class T> void
664 push_back(const T &component)
665 {
666 append(component);
667 }
668
Jeff Thompson91737f52013-10-04 11:07:24 -0700669 /**
670 * Check if this name has the same component count and components as the given name.
671 * @param name The Name to check.
672 * @return true if the names are equal, otherwise false.
673 */
674 bool
675 operator == (const Name &name) const { return equals(name); }
676
677 /**
678 * Check if this name has the same component count and components as the given name.
679 * @param name The Name to check.
680 * @return true if the names are not equal, otherwise false.
681 */
682 bool
683 operator != (const Name &name) const { return !equals(name); }
684
Jeff Thompson82568ad2013-12-17 15:17:40 -0800685 /**
686 * Compare two names for "less than" using breadth first. If the first components of each name are not equal,
687 * this returns true if the first comes before the second using the NDN canonical ordering for name components.
688 * If they are equal, this compares the second components of each name, etc. If both names are the same up to
689 * the size of the shorter name, this returns true if the first name is shorter than the second. For example, if you
690 * use breadthFirstLess in std::sort, it gives: /a/b/d /a/b/cc /c /c/a /bb . This is intuitive because all names
691 * with the prefix /a are next to each other. But it may be also be counter-intuitive because /c comes before /bb
692 * according to NDN canonical ordering since it is shorter. Note: We don't define this directly as the Name
693 * less than operation because there are other valid ways to sort names.
694 * @param name1 The first name to compare.
695 * @param name2 The second name to compare.
696 * @return True if the first name is less than the second using breadth first comparison.
697 */
698 static bool
699 breadthFirstLess(const Name& name1, const Name& name2);
700
701 /**
702 * Name::BreadthFirstLess is a function object which calls breadthFirstLess, for use as the "less" operator in map, etc.
703 * For example, you can use Name as the key type in a map as follows: map<Name, int, Name::BreadthFirstLess>.
704 */
705 struct BreadthFirstLess {
706 bool operator() (const Name& name1, const Name& name2) const { return breadthFirstLess(name1, name2); }
707 };
708
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700709 //
710 // Iterator interface to name components.
711 //
712 typedef std::vector<Component>::iterator iterator;
713 typedef std::vector<Component>::const_iterator const_iterator;
714 typedef std::vector<Component>::reverse_iterator reverse_iterator;
715 typedef std::vector<Component>::const_reverse_iterator const_reverse_iterator;
716 typedef std::vector<Component>::reference reference;
717 typedef std::vector<Component>::const_reference const_reference;
718
Alexander Afanasyev58743332014-01-12 13:24:42 -0800719 typedef std::vector<Component>::difference_type difference_type;
720 typedef std::vector<Component>::size_type size_type;
721
722 typedef std::vector<Component>::value_type value_type;
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700723
724 /**
725 * Begin iterator (const).
726 */
727 const_iterator
Jeff Thompson91737f52013-10-04 11:07:24 -0700728 begin() const { return components_.begin(); }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700729
730 /**
731 * Begin iterator.
732 */
733 iterator
Jeff Thompson91737f52013-10-04 11:07:24 -0700734 begin() { return components_.begin(); }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700735
736 /**
737 * End iterator (const).
738 */
739 const_iterator
Jeff Thompson91737f52013-10-04 11:07:24 -0700740 end() const { return components_.end(); }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700741
742 /**
743 * End iterator.
744 */
745 iterator
Jeff Thompson91737f52013-10-04 11:07:24 -0700746 end() { return components_.end(); }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700747
748 /**
749 * Reverse begin iterator (const).
750 */
751 const_reverse_iterator
Jeff Thompson91737f52013-10-04 11:07:24 -0700752 rbegin() const { return components_.rbegin(); }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700753
754 /**
755 * Reverse begin iterator.
756 */
757 reverse_iterator
Jeff Thompson91737f52013-10-04 11:07:24 -0700758 rbegin() { return components_.rbegin(); }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700759
760 /**
761 * Reverse end iterator (const).
762 */
763 const_reverse_iterator
Jeff Thompson91737f52013-10-04 11:07:24 -0700764 rend() const { return components_.rend(); }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700765
766 /**
767 * Reverse end iterator.
768 */
769 reverse_iterator
Jeff Thompson91737f52013-10-04 11:07:24 -0700770 rend() { return components_.rend(); }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700771
Jeff Thompson9c41dfe2013-06-27 12:10:25 -0700772private:
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -0700773 std::vector<Component> components_;
Jeff Thompson9c41dfe2013-06-27 12:10:25 -0700774
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800775 mutable Block wire_;
776};
777
778std::ostream &
779operator << (std::ostream &os, const Name &name);
780
Alexander Afanasyev58743332014-01-12 13:24:42 -0800781inline std::ostream &
782operator << (std::ostream &os, const Name::Component &component)
783{
784 component.toEscapedString(os);
785 return os;
786}
787
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800788inline std::string
789Name::toUri() const
Jeff Thompson49e321a2013-10-04 17:35:59 -0700790{
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800791 std::ostringstream os;
792 os << *this;
793 return os.str();
Jeff Thompson49e321a2013-10-04 17:35:59 -0700794}
795
Jeff Thompson9c41dfe2013-06-27 12:10:25 -0700796}
797
798#endif
799