blob: 1603618e7cc922fc1079301df3575901840f67c1 [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 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -080024class Name : public ptr_lib::enable_shared_from_this<Name> {
Jeff Thompson9c41dfe2013-06-27 12:10:25 -070025public:
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
Jeff Thompsonafc45a92014-01-15 12:42:45 -0800652 /**
653 * Compare this to the other Name using NDN canonical ordering. If the first components of each name are not equal,
654 * this returns -1 if the first comes before the second using the NDN canonical ordering for name components, or 1 if it comes after.
655 * If they are equal, this compares the second components of each name, etc. If both names are the same up to
656 * the size of the shorter name, this returns -1 if the first name is shorter than the second or 1 if it is longer.
657 * For example, if you std::sort gives: /a/b/d /a/b/cc /c /c/a /bb . This is intuitive because all names
658 * with the prefix /a are next to each other. But it may be also be counter-intuitive because /c comes before /bb
659 * according to NDN canonical ordering since it is shorter.
660 * @param other The other Name to compare with.
661 * @return 0 If they compare equal, -1 if *this comes before other in the canonical ordering, or
662 * 1 if *this comes after other in the canonical ordering.
663 *
664 * @see http://named-data.net/doc/0.2/technical/CanonicalOrder.html
665 */
666 int
667 compare(const Name& other) const;
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700668
669 const Component&
670 operator [] (int i) const
671 {
672 return get(i);
673 }
674
675 /**
676 * Append the component
677 * @param component The component of type T.
678 */
679 template<class T> void
680 push_back(const T &component)
681 {
682 append(component);
683 }
684
Jeff Thompson91737f52013-10-04 11:07:24 -0700685 /**
686 * Check if this name has the same component count and components as the given name.
687 * @param name The Name to check.
688 * @return true if the names are equal, otherwise false.
689 */
690 bool
691 operator == (const Name &name) const { return equals(name); }
692
693 /**
694 * Check if this name has the same component count and components as the given name.
695 * @param name The Name to check.
696 * @return true if the names are not equal, otherwise false.
697 */
698 bool
699 operator != (const Name &name) const { return !equals(name); }
Jeff Thompson82568ad2013-12-17 15:17:40 -0800700
701 /**
Jeff Thompsonafc45a92014-01-15 12:42:45 -0800702 * Return true if this is less than or equal to the other Name in the NDN canonical ordering.
703 * @param other The other Name to compare with.
704 *
705 * @see http://named-data.net/doc/0.2/technical/CanonicalOrder.html
Jeff Thompson82568ad2013-12-17 15:17:40 -0800706 */
Jeff Thompsonafc45a92014-01-15 12:42:45 -0800707 bool
708 operator <= (const Name& other) const { return compare(other) <= 0; }
709
710 /**
711 * Return true if this is less than the other Name in the NDN canonical ordering.
712 * @param other The other Name to compare with.
713 *
714 * @see http://named-data.net/doc/0.2/technical/CanonicalOrder.html
715 */
716 bool
717 operator < (const Name& other) const { return compare(other) < 0; }
718
719 /**
720 * Return true if this is less than or equal to the other Name in the NDN canonical ordering.
721 * @param other The other Name to compare with.
722 *
723 * @see http://named-data.net/doc/0.2/technical/CanonicalOrder.html
724 */
725 bool
726 operator >= (const Name& other) const { return compare(other) >= 0; }
727
728 /**
729 * Return true if this is greater than the other Name in the NDN canonical ordering.
730 * @param other The other Name to compare with.
731 *
732 * @see http://named-data.net/doc/0.2/technical/CanonicalOrder.html
733 */
734 bool
735 operator > (const Name& other) const { return compare(other) > 0; }
Jeff Thompson82568ad2013-12-17 15:17:40 -0800736
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700737 //
738 // Iterator interface to name components.
739 //
740 typedef std::vector<Component>::iterator iterator;
741 typedef std::vector<Component>::const_iterator const_iterator;
742 typedef std::vector<Component>::reverse_iterator reverse_iterator;
743 typedef std::vector<Component>::const_reverse_iterator const_reverse_iterator;
744 typedef std::vector<Component>::reference reference;
745 typedef std::vector<Component>::const_reference const_reference;
746
Alexander Afanasyev58743332014-01-12 13:24:42 -0800747 typedef std::vector<Component>::difference_type difference_type;
748 typedef std::vector<Component>::size_type size_type;
749
750 typedef std::vector<Component>::value_type value_type;
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700751
752 /**
753 * Begin iterator (const).
754 */
755 const_iterator
Jeff Thompson91737f52013-10-04 11:07:24 -0700756 begin() const { return components_.begin(); }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700757
758 /**
759 * Begin iterator.
760 */
761 iterator
Jeff Thompson91737f52013-10-04 11:07:24 -0700762 begin() { return components_.begin(); }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700763
764 /**
765 * End iterator (const).
766 */
767 const_iterator
Jeff Thompson91737f52013-10-04 11:07:24 -0700768 end() const { return components_.end(); }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700769
770 /**
771 * End iterator.
772 */
773 iterator
Jeff Thompson91737f52013-10-04 11:07:24 -0700774 end() { return components_.end(); }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700775
776 /**
777 * Reverse begin iterator (const).
778 */
779 const_reverse_iterator
Jeff Thompson91737f52013-10-04 11:07:24 -0700780 rbegin() const { return components_.rbegin(); }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700781
782 /**
783 * Reverse begin iterator.
784 */
785 reverse_iterator
Jeff Thompson91737f52013-10-04 11:07:24 -0700786 rbegin() { return components_.rbegin(); }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700787
788 /**
789 * Reverse end iterator (const).
790 */
791 const_reverse_iterator
Jeff Thompson91737f52013-10-04 11:07:24 -0700792 rend() const { return components_.rend(); }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700793
794 /**
795 * Reverse end iterator.
796 */
797 reverse_iterator
Jeff Thompson91737f52013-10-04 11:07:24 -0700798 rend() { return components_.rend(); }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700799
Jeff Thompson9c41dfe2013-06-27 12:10:25 -0700800private:
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -0700801 std::vector<Component> components_;
Jeff Thompson9c41dfe2013-06-27 12:10:25 -0700802
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800803 mutable Block wire_;
804};
805
806std::ostream &
807operator << (std::ostream &os, const Name &name);
808
Alexander Afanasyev58743332014-01-12 13:24:42 -0800809inline std::ostream &
810operator << (std::ostream &os, const Name::Component &component)
811{
812 component.toEscapedString(os);
813 return os;
814}
815
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800816inline std::string
817Name::toUri() const
Jeff Thompson49e321a2013-10-04 17:35:59 -0700818{
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800819 std::ostringstream os;
820 os << *this;
821 return os.str();
Jeff Thompson49e321a2013-10-04 17:35:59 -0700822}
823
Jeff Thompson9c41dfe2013-06-27 12:10:25 -0700824}
825
826#endif
827