blob: 132def5c954239d407bdc7e9a4484fb7c49aaf07 [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 Thompson27b2bf92013-10-12 14:38:13 -070015#include <string.h>
Jeff Thompsonec7789a2013-08-21 11:08:36 -070016#include <sstream>
Jeff Thompson995aba52013-09-12 12:04:52 -070017#include "util/blob.hpp"
Jeff Thompson9c41dfe2013-06-27 12:10:25 -070018
Jeff Thompson25b4e612013-10-10 16:03:24 -070019struct ndn_NameComponent;
20struct ndn_Name;
21
Jeff Thompson9c41dfe2013-06-27 12:10:25 -070022namespace ndn {
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -070023
Jeff Thompsonc7d65502013-11-06 17:22:26 -080024/**
25 * A Name holds an array of Name::Component and represents an NDN name.
26 */
Jeff Thompson9c41dfe2013-06-27 12:10:25 -070027class Name {
28public:
Jeff Thompsonc1c12e42013-09-13 19:08:45 -070029 /**
Jeff Thompsonc7d65502013-11-06 17:22:26 -080030 * A Name::Component holds a read-only name component value.
Jeff Thompsonc1c12e42013-09-13 19:08:45 -070031 */
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -070032 class Component {
33 public:
34 /**
Jeff Thompson46411c92013-09-13 19:31:25 -070035 * Create a new Name::Component with a null value.
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -070036 */
37 Component()
38 {
39 }
40
41 /**
42 * Create a new Name::Component, copying the given value.
43 * @param value The value byte array.
44 */
Jeff Thompson10ad12a2013-09-24 16:19:11 -070045 Component(const std::vector<uint8_t>& value)
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -070046 : value_(value)
47 {
48 }
49
50 /**
51 * Create a new Name::Component, copying the given value.
52 * @param value Pointer to the value byte array.
53 * @param valueLen Length of value.
54 */
Jeff Thompson97223af2013-09-24 17:01:27 -070055 Component(const uint8_t *value, size_t valueLen)
Jeff Thompson995aba52013-09-12 12:04:52 -070056 : value_(value, valueLen)
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -070057 {
58 }
Jeff Thompson0f743452013-09-12 14:23:18 -070059
60 /**
61 * Create a new Name::Component, taking another pointer to the Blob value.
62 * @param value A blob with a pointer to an immutable array. The pointer is copied.
63 */
64 Component(const Blob &value)
65 : value_(value)
66 {
67 }
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -070068
69 /**
70 * Set the componentStruct to point to this component, without copying any memory.
71 * WARNING: The resulting pointer in componentStruct is invalid after a further use of this object which could reallocate memory.
72 * @param componentStruct The C ndn_NameComponent struct to receive the pointer.
73 */
Jeff Thompson0050abe2013-09-17 12:50:25 -070074 void
Jeff Thompson25b4e612013-10-10 16:03:24 -070075 get(struct ndn_NameComponent& componentStruct) const;
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -070076
Jeff Thompson0050abe2013-09-17 12:50:25 -070077 const Blob&
78 getValue() const { return value_; }
Jeff Thompson6653b0b2013-09-23 12:32:39 -070079
80 /**
81 * Write this component value to result, escaping characters according to the NDN URI Scheme.
82 * This also adds "..." to a value with zero or more ".".
Jeff Thompson6653b0b2013-09-23 12:32:39 -070083 * @param result the string stream to write to.
84 */
85 void
Jeff Thompsond0159d72013-09-23 13:34:15 -070086 toEscapedString(std::ostringstream& result) const
Jeff Thompson6653b0b2013-09-23 12:32:39 -070087 {
88 Name::toEscapedString(*value_, result);
89 }
90
91 /**
92 * Convert this component value by escaping characters according to the NDN URI Scheme.
93 * This also adds "..." to a value with zero or more ".".
94 * @return The escaped string.
95 */
96 std::string
Jeff Thompsond0159d72013-09-23 13:34:15 -070097 toEscapedString() const
Jeff Thompson6653b0b2013-09-23 12:32:39 -070098 {
99 return Name::toEscapedString(*value_);
100 }
Jeff Thompson9bdb3b22013-09-12 12:42:13 -0700101
Jeff Thompson50b37912013-10-08 13:39:33 -0700102 /**
103 * Interpret this name component as a network-ordered number and return an integer.
104 * @return The integer number.
105 */
106 uint64_t
Jeff Thompson25b4e612013-10-10 16:03:24 -0700107 toNumber() const;
Jeff Thompson27cae532013-10-08 12:52:41 -0700108
Jeff Thompson50b37912013-10-08 13:39:33 -0700109 /**
110 * Interpret this name component as a network-ordered number with a marker and return an integer.
111 * @param marker The required first byte of the component.
112 * @return The integer number.
113 * @throw runtime_error If the first byte of the component does not equal the marker.
114 */
115 uint64_t
116 toNumberWithMarker(uint8_t marker) const;
117
118 /**
119 * Interpret this name component as a segment number according to NDN name conventions (a network-ordered number
120 * where the first byte is the marker 0x00).
121 * @return The integer segment number.
122 * @throw runtime_error If the first byte of the component is not the expected marker.
123 */
124 uint64_t
125 toSegment() const
126 {
127 return toNumberWithMarker(0x00);
128 }
129
130 /**
131 * @deprecated Use toSegment.
132 */
133 uint64_t
134 toSeqNum() const
135 {
136 return toSegment();
137 }
138
139 /**
140 * Interpret this name component as a version number according to NDN name conventions (a network-ordered number
141 * where the first byte is the marker 0xFD). Note that this returns the exact number from the component
142 * without converting it to a time representation.
143 * @return The integer segment number.
144 * @throw runtime_error If the first byte of the component is not the expected marker.
145 */
146 uint64_t
147 toVersion() const
148 {
149 return toNumberWithMarker(0xFD);
150 }
Jeff Thompson27cae532013-10-08 12:52:41 -0700151
Jeff Thompsonc1c12e42013-09-13 19:08:45 -0700152 /**
Jeff Thompsond129ac12013-10-11 14:30:12 -0700153 * Create a component whose value is the network-ordered encoding of the number.
154 * Note: if the number is zero, the result is empty.
155 * @param number The number to be encoded.
156 * @return The component value.
157 */
158 static Component
159 fromNumber(uint64_t number);
Jeff Thompson8aac1992013-08-12 17:26:02 -0700160
161 /**
Jeff Thompsond129ac12013-10-11 14:30:12 -0700162 * Create a component whose value is the marker appended with the network-ordered encoding of the number.
163 * Note: if the number is zero, no bytes are used for the number - the result will have only the marker.
164 * @param number The number to be encoded.
165 * @param marker The marker to use as the first byte of the component.
166 * @return The component value.
Jeff Thompson8aac1992013-08-12 17:26:02 -0700167 */
Jeff Thompsond129ac12013-10-11 14:30:12 -0700168 static Component
169 fromNumberWithMarker(uint64_t number, uint8_t marker);
Jeff Thompsona98000c2013-12-16 14:40:09 -0800170
171 /**
172 * Check if this is the same component as other.
173 * @param other The other Component to compare with.
174 * @return true if the components are equal, otherwise false.
175 */
176 bool
177 equals(const Component& other) const
178 {
179 return *value_ == *other.value_;
180 }
181
182 /**
183 * Check if this is the same component as other.
184 * @param other The other Component to compare with.
185 * @return true if the components are equal, otherwise false.
186 */
187 bool
188 operator == (const Component& other) const { return equals(other); }
189
190 /**
191 * Check if this is not the same component as other.
192 * @param other The other Component to compare with.
193 * @return true if the components are not equal, otherwise false.
194 */
195 bool
196 operator != (const Component& other) const { return !equals(other); }
197
198 /**
199 * Compare this to the other Component using NDN canonical ordering.
200 * @param other The other Component to compare with.
201 * @return 0 If they compare equal, -1 if *this comes before other in the canonical ordering, or
202 * 1 if *this comes after other in the canonical ordering.
203 *
204 * @see http://named-data.net/doc/0.2/technical/CanonicalOrder.html
205 */
206 int
207 compare(const Component& other) const;
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -0700208
Jeff Thompsona98000c2013-12-16 14:40:09 -0800209 /**
210 * Return true if this is less than or equal to the other Component in the NDN canonical ordering.
211 * @param other The other Component to compare with.
212 *
213 * @see http://named-data.net/doc/0.2/technical/CanonicalOrder.html
214 */
215 bool
216 operator <= (const Component& other) const { return compare(other) <= 0; }
217
218 /**
219 * Return true if this is less than 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 or equal to 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 greater than 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
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -0700245 private:
Jeff Thompson995aba52013-09-12 12:04:52 -0700246 Blob value_;
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -0700247 };
248
Jeff Thompson443398d2013-07-02 19:45:46 -0700249 /**
250 * Create a new Name with no components.
251 */
Jeff Thompson016ed642013-07-02 14:39:06 -0700252 Name() {
253 }
Jeff Thompson443398d2013-07-02 19:45:46 -0700254
255 /**
Jeff Thompson3f2175b2013-07-31 17:12:47 -0700256 * Create a new Name, copying the name components.
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -0700257 * @param components A vector of Component
Jeff Thompson3f2175b2013-07-31 17:12:47 -0700258 */
Jeff Thompson1656e6a2013-08-29 18:01:48 -0700259 Name(const std::vector<Component>& components)
Jeff Thompson3f2175b2013-07-31 17:12:47 -0700260 : components_(components)
261 {
262 }
263
264 /**
Jeff Thompson443398d2013-07-02 19:45:46 -0700265 * Parse the uri according to the NDN URI Scheme and create the name with the components.
Jeff Thompson3f2175b2013-07-31 17:12:47 -0700266 * @param uri The URI string.
Jeff Thompson443398d2013-07-02 19:45:46 -0700267 */
Jeff Thompson3549ef32013-09-25 14:05:17 -0700268 Name(const char* uri)
Jeff Thompson67515bd2013-08-15 17:43:22 -0700269 {
270 set(uri);
271 }
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -0700272
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700273 /**
Jeff Thompson3549ef32013-09-25 14:05:17 -0700274 * Parse the uri according to the NDN URI Scheme and create the name with the components.
275 * @param uri The URI string.
276 */
277 Name(const std::string& uri)
278 {
279 set(uri.c_str());
280 }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700281
Jeff Thompson3549ef32013-09-25 14:05:17 -0700282 /**
Jeff Thompson016ed642013-07-02 14:39:06 -0700283 * Set the nameStruct to point to the components in this name, without copying any memory.
284 * WARNING: The resulting pointers in nameStruct are invalid after a further use of this object which could reallocate memory.
Jeff Thompson3f2175b2013-07-31 17:12:47 -0700285 * @param nameStruct A C ndn_Name struct where the components array is already allocated.
Jeff Thompson016ed642013-07-02 14:39:06 -0700286 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700287 void
288 get(struct ndn_Name& nameStruct) const;
Jeff Thompson016ed642013-07-02 14:39:06 -0700289
290 /**
Jeff Thompson8b27e3a2013-07-03 18:19:53 -0700291 * Clear this name, and set the components by copying from the name struct.
Jeff Thompson3f2175b2013-07-31 17:12:47 -0700292 * @param nameStruct A C ndn_Name struct
Jeff Thompsonb468c312013-07-01 17:50:14 -0700293 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700294 void
295 set(const struct ndn_Name& nameStruct);
Jeff Thompsonb468c312013-07-01 17:50:14 -0700296
297 /**
Jeff Thompson67515bd2013-08-15 17:43:22 -0700298 * Parse the uri according to the NDN URI Scheme and set the name with the components.
Jeff Thompson7781b392013-12-17 11:45:59 -0800299 * @param uri The null-terminated URI string.
Jeff Thompson67515bd2013-08-15 17:43:22 -0700300 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700301 void
302 set(const char *uri);
Jeff Thompson67515bd2013-08-15 17:43:22 -0700303
304 /**
Jeff Thompson7781b392013-12-17 11:45:59 -0800305 * Parse the uri according to the NDN URI Scheme and set the name with the components.
306 * @param uri The URI string.
307 */
308 void
309 set(const std::string& uri) { set(uri.c_str()); }
310
311 /**
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700312 * Append a new component, copying from value of length valueLength.
Jeff Thompson26b0d792013-09-23 16:19:01 -0700313 * @return This name so that you can chain calls to append.
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700314 */
Jeff Thompson26b0d792013-09-23 16:19:01 -0700315 Name&
Jeff Thompson97223af2013-09-24 17:01:27 -0700316 append(const uint8_t *value, size_t valueLength)
Jeff Thompson0f743452013-09-12 14:23:18 -0700317 {
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -0700318 components_.push_back(Component(value, valueLength));
Jeff Thompson26b0d792013-09-23 16:19:01 -0700319 return *this;
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700320 }
Jeff Thompsonf72b1ac2013-08-16 16:44:41 -0700321
322 /**
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700323 * Append a new component, copying from value.
Jeff Thompson26b0d792013-09-23 16:19:01 -0700324 * @return This name so that you can chain calls to append.
Jeff Thompsonf72b1ac2013-08-16 16:44:41 -0700325 */
Jeff Thompson26b0d792013-09-23 16:19:01 -0700326 Name&
Jeff Thompson10ad12a2013-09-24 16:19:11 -0700327 append(const std::vector<uint8_t>& value)
Jeff Thompson0f743452013-09-12 14:23:18 -0700328 {
329 components_.push_back(value);
Jeff Thompson26b0d792013-09-23 16:19:01 -0700330 return *this;
Jeff Thompson0f743452013-09-12 14:23:18 -0700331 }
332
Jeff Thompson26b0d792013-09-23 16:19:01 -0700333 Name&
334 append(const Blob &value)
Jeff Thompson0f743452013-09-12 14:23:18 -0700335 {
Jeff Thompsonf72b1ac2013-08-16 16:44:41 -0700336 components_.push_back(value);
Jeff Thompson26b0d792013-09-23 16:19:01 -0700337 return *this;
Jeff Thompsonf72b1ac2013-08-16 16:44:41 -0700338 }
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700339
Jeff Thompson21eb7212013-09-26 09:05:40 -0700340 Name&
341 append(const Component &value)
342 {
343 components_.push_back(value);
344 return *this;
345 }
346
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700347 /**
Jeff Thompson26b0d792013-09-23 16:19:01 -0700348 * Append the components of the given name to this name.
349 * @param name The Name with components to append.
350 * @return This name so that you can chain calls to append.
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700351 */
Jeff Thompson26b0d792013-09-23 16:19:01 -0700352 Name&
353 append(const Name& name);
354
355 /**
356 * @deprecated Use append.
357 */
358 Name&
Jeff Thompson97223af2013-09-24 17:01:27 -0700359 appendComponent(const uint8_t *value, size_t valueLength)
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700360 {
Jeff Thompson26b0d792013-09-23 16:19:01 -0700361 return append(value, valueLength);
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700362 }
363
364 /**
Jeff Thompson26b0d792013-09-23 16:19:01 -0700365 * @deprecated Use append.
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700366 */
Jeff Thompson26b0d792013-09-23 16:19:01 -0700367 Name&
Jeff Thompson10ad12a2013-09-24 16:19:11 -0700368 appendComponent(const std::vector<uint8_t>& value)
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700369 {
Jeff Thompson26b0d792013-09-23 16:19:01 -0700370 return append(value);
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700371 }
372
373 /**
Jeff Thompson26b0d792013-09-23 16:19:01 -0700374 * @deprecated Use append.
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700375 */
Jeff Thompson26b0d792013-09-23 16:19:01 -0700376 Name&
377 appendComponent(const Blob &value)
378 {
379 return append(value);
380 }
381
382 /**
383 * @deprecated Use append.
384 */
385 Name&
Jeff Thompson97223af2013-09-24 17:01:27 -0700386 addComponent(const uint8_t *value, size_t valueLength)
Jeff Thompson26b0d792013-09-23 16:19:01 -0700387 {
388 return append(value, valueLength);
389 }
390
391 /**
392 * @deprecated Use append.
393 */
394 Name&
Jeff Thompson10ad12a2013-09-24 16:19:11 -0700395 addComponent(const std::vector<uint8_t>& value)
Jeff Thompson26b0d792013-09-23 16:19:01 -0700396 {
397 return append(value);
398 }
399
400 /**
401 * @deprecated Use append.
402 */
403 Name&
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700404 addComponent(const Blob &value)
405 {
Jeff Thompson26b0d792013-09-23 16:19:01 -0700406 return append(value);
Jeff Thompson0aa66f22013-09-23 13:02:13 -0700407 }
408
409 /**
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700410 * Clear all the components.
411 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700412 void
413 clear() {
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700414 components_.clear();
415 }
416
417 /**
Jeff Thompsoneba62eb2013-10-30 13:24:22 -0700418 * @deprecated use size().
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700419 */
Jeff Thompson97223af2013-09-24 17:01:27 -0700420 size_t
Jeff Thompsoneba62eb2013-10-30 13:24:22 -0700421 getComponentCount() const { return size(); }
Jeff Thompsone5f839b2013-06-28 12:50:38 -0700422
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700423 /**
Jeff Thompsoneba62eb2013-10-30 13:24:22 -0700424 * @deprecated Use get(i).
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700425 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700426 const Component&
Jeff Thompsoneba62eb2013-10-30 13:24:22 -0700427 getComponent(size_t i) const { return get(i); }
Jeff Thompson443398d2013-07-02 19:45:46 -0700428
Jeff Thompsone6063512013-07-01 15:11:28 -0700429 /**
Jeff Thompsond0159d72013-09-23 13:34:15 -0700430 * Get a new name, constructed as a subset of components.
431 * @param iStartComponent The index if the first component to get.
432 * @param nComponents The number of components starting at iStartComponent.
433 * @return A new name.
434 */
435 Name
436 getSubName(size_t iStartComponent, size_t nComponents) const;
437
438 /**
439 * Get a new name, constructed as a subset of components starting at iStartComponent until the end of the name.
440 * @param iStartComponent The index if the first component to get.
441 * @return A new name.
442 */
443 Name
444 getSubName(size_t iStartComponent) const;
445
446 /**
447 * Return a new Name with the first nComponents components of this Name.
Jeff Thompsoneb0358f2013-12-17 10:59:53 -0800448 * @param nComponents The number of prefix components. If nComponents is -N then return the prefix up
449 * to name.size() - N. For example getPrefix(-1) returns the name without the final component.
Jeff Thompsond0159d72013-09-23 13:34:15 -0700450 * @return A new Name.
451 */
452 Name
Jeff Thompsoneb0358f2013-12-17 10:59:53 -0800453 getPrefix(int nComponents) const
Jeff Thompsond0159d72013-09-23 13:34:15 -0700454 {
Jeff Thompsoneb0358f2013-12-17 10:59:53 -0800455 if (nComponents < 0)
456 return getSubName(0, components_.size() + nComponents);
457 else
458 return getSubName(0, nComponents);
Jeff Thompsond0159d72013-09-23 13:34:15 -0700459 }
460
461 /**
Jeff Thompsone6063512013-07-01 15:11:28 -0700462 * Encode this name as a URI.
Jeff Thompson3f2175b2013-07-31 17:12:47 -0700463 * @return The encoded URI.
Jeff Thompsone6063512013-07-01 15:11:28 -0700464 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700465 std::string
466 toUri() const;
Jeff Thompsone6063512013-07-01 15:11:28 -0700467
Jeff Thompson21844fc2013-08-08 14:52:51 -0700468 /**
469 * @deprecated Use toUri().
470 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700471 std::string
472 to_uri() const
Jeff Thompson21844fc2013-08-08 14:52:51 -0700473 {
474 return toUri();
475 }
Jeff Thompson26b0d792013-09-23 16:19:01 -0700476
Jeff Thompson8aac1992013-08-12 17:26:02 -0700477 /**
478 * Append a component with the encoded segment number.
479 * @param segment The segment number.
Jeff Thompson26b0d792013-09-23 16:19:01 -0700480 * @return This name so that you can chain calls to append.
481 */
482 Name&
Jeff Thompsond129ac12013-10-11 14:30:12 -0700483 appendSegment(uint64_t segment)
Jeff Thompson8aac1992013-08-12 17:26:02 -0700484 {
Jeff Thompsond129ac12013-10-11 14:30:12 -0700485 components_.push_back(Component::fromNumberWithMarker(segment, 0x00));
486 return *this;
487 }
488
489 /**
490 * Append a component with the encoded version number.
491 * Note that this encodes the exact value of version without converting from a time representation.
492 * @param version The version number.
493 * @return This name so that you can chain calls to append.
494 */
495 Name&
496 appendVersion(uint64_t version)
497 {
498 components_.push_back(Component::fromNumberWithMarker(version, 0xFD));
Jeff Thompson26b0d792013-09-23 16:19:01 -0700499 return *this;
Jeff Thompson8aac1992013-08-12 17:26:02 -0700500 }
Jeff Thompsoncc35cd42013-08-20 12:23:14 -0700501
Jeff Thompsonec7789a2013-08-21 11:08:36 -0700502 /**
Jeff Thompson3c2ab012013-10-02 14:18:16 -0700503 * Check if this name has the same component count and components as the given name.
504 * @param name The Name to check.
505 * @return true if the names are equal, otherwise false.
506 */
507 bool
508 equals(const Name& name) const;
509
510 /**
Jeff Thompsonec7789a2013-08-21 11:08:36 -0700511 * Check if the N components of this name are the same as the first N components of the given name.
512 * @param name The Name to check.
513 * @return true if this matches the given name, otherwise false. This always returns true if this name is empty.
514 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700515 bool
516 match(const Name& name) const;
Jeff Thompsonec7789a2013-08-21 11:08:36 -0700517
518 /**
Jeff Thompsond8e53e62013-10-29 16:59:49 -0700519 * 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 -0800520 * If the escaped string is "", "." or ".." then return a Blob with a null pointer,
521 * which means the component should be skipped in a URI name.
Jeff Thompsond8e53e62013-10-29 16:59:49 -0700522 * @param escapedString The escaped string. It does not need to be null-terminated because we only scan to endOffset.
523 * @param beginOffset The offset in escapedString of the beginning of the portion to decode.
524 * @param endOffset The offset in escapedString of the end of the portion to decode.
525 * @return The Blob value. If the escapedString is not a valid escaped component, then the Blob is a null pointer.
526 */
527 static Blob
528 fromEscapedString(const char *escapedString, size_t beginOffset, size_t endOffset);
529
530 /**
531 * Make a Blob value by decoding the escapedString according to the NDN URI Scheme.
Jeff Thompson08493592013-11-07 17:44:41 -0800532 * If the escaped string is "", "." or ".." then return a Blob with a null pointer,
533 * which means the component should be skipped in a URI name.
Jeff Thompsond8e53e62013-10-29 16:59:49 -0700534 * @param escapedString The null-terminated escaped string.
535 * @return The Blob value. If the escapedString is not a valid escaped component, then the Blob is a null pointer.
536 */
537 static Blob
538 fromEscapedString(const char *escapedString);
539
540 /**
Jeff Thompson7781b392013-12-17 11:45:59 -0800541 * Make a Blob value by decoding the escapedString according to the NDN URI Scheme.
542 * If the escaped string is "", "." or ".." then return a Blob with a null pointer,
543 * which means the component should be skipped in a URI name.
544 * @param escapedString The escaped string.
545 * @return The Blob value. If the escapedString is not a valid escaped component, then the Blob is a null pointer.
546 */
547 static Blob
548 fromEscapedString(const std::string& escapedString) { return fromEscapedString(escapedString.c_str()); }
549
550 /**
Jeff Thompsonec7789a2013-08-21 11:08:36 -0700551 * Write the value to result, escaping characters according to the NDN URI Scheme.
552 * This also adds "..." to a value with zero or more ".".
553 * @param value the buffer with the value to escape
554 * @param result the string stream to write to.
555 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700556 static void
Jeff Thompson10ad12a2013-09-24 16:19:11 -0700557 toEscapedString(const std::vector<uint8_t>& value, std::ostringstream& result);
Jeff Thompson21844fc2013-08-08 14:52:51 -0700558
Jeff Thompson6653b0b2013-09-23 12:32:39 -0700559 /**
560 * Convert the value by escaping characters according to the NDN URI Scheme.
561 * This also adds "..." to a value with zero or more ".".
562 * @param value the buffer with the value to escape
563 * @return The escaped string.
564 */
565 static std::string
Jeff Thompson10ad12a2013-09-24 16:19:11 -0700566 toEscapedString(const std::vector<uint8_t>& value);
Jeff Thompson6653b0b2013-09-23 12:32:39 -0700567
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700568 //
569 // vector equivalent interface.
570 //
571
572 /**
573 * Get the number of components.
574 * @return The number of components.
575 */
576 size_t
Jeff Thompsoneba62eb2013-10-30 13:24:22 -0700577 size() const { return components_.size(); }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700578
579 /**
580 * Get the component at the given index.
581 * @param i The index of the component, starting from 0.
582 * @return The name component at the index.
583 */
584 const Component&
Jeff Thompsoneba62eb2013-10-30 13:24:22 -0700585 get(size_t i) const { return components_[i]; }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700586
587
588 const Component&
589 operator [] (int i) const
590 {
591 return get(i);
592 }
593
594 /**
595 * Append the component
596 * @param component The component of type T.
597 */
598 template<class T> void
599 push_back(const T &component)
600 {
601 append(component);
602 }
603
Jeff Thompson91737f52013-10-04 11:07:24 -0700604 /**
605 * Check if this name has the same component count and components as the given name.
606 * @param name The Name to check.
607 * @return true if the names are equal, otherwise false.
608 */
609 bool
610 operator == (const Name &name) const { return equals(name); }
611
612 /**
613 * Check if this name has the same component count and components as the given name.
614 * @param name The Name to check.
615 * @return true if the names are not equal, otherwise false.
616 */
617 bool
618 operator != (const Name &name) const { return !equals(name); }
619
Jeff Thompson82568ad2013-12-17 15:17:40 -0800620 /**
621 * Compare two names for "less than" using breadth first. If the first components of each name are not equal,
622 * this returns true if the first comes before the second using the NDN canonical ordering for name components.
623 * If they are equal, this compares the second components of each name, etc. If both names are the same up to
624 * the size of the shorter name, this returns true if the first name is shorter than the second. For example, if you
625 * use breadthFirstLess in std::sort, it gives: /a/b/d /a/b/cc /c /c/a /bb . This is intuitive because all names
626 * with the prefix /a are next to each other. But it may be also be counter-intuitive because /c comes before /bb
627 * according to NDN canonical ordering since it is shorter. Note: We don't define this directly as the Name
628 * less than operation because there are other valid ways to sort names.
629 * @param name1 The first name to compare.
630 * @param name2 The second name to compare.
631 * @return True if the first name is less than the second using breadth first comparison.
632 */
633 static bool
634 breadthFirstLess(const Name& name1, const Name& name2);
635
636 /**
637 * Name::BreadthFirstLess is a function object which calls breadthFirstLess, for use as the "less" operator in map, etc.
638 * For example, you can use Name as the key type in a map as follows: map<Name, int, Name::BreadthFirstLess>.
639 */
640 struct BreadthFirstLess {
641 bool operator() (const Name& name1, const Name& name2) const { return breadthFirstLess(name1, name2); }
642 };
643
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700644 //
645 // Iterator interface to name components.
646 //
647 typedef std::vector<Component>::iterator iterator;
648 typedef std::vector<Component>::const_iterator const_iterator;
649 typedef std::vector<Component>::reverse_iterator reverse_iterator;
650 typedef std::vector<Component>::const_reverse_iterator const_reverse_iterator;
651 typedef std::vector<Component>::reference reference;
652 typedef std::vector<Component>::const_reference const_reference;
653
654 typedef Component partial_type;
655
656 /**
657 * Begin iterator (const).
658 */
659 const_iterator
Jeff Thompson91737f52013-10-04 11:07:24 -0700660 begin() const { return components_.begin(); }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700661
662 /**
663 * Begin iterator.
664 */
665 iterator
Jeff Thompson91737f52013-10-04 11:07:24 -0700666 begin() { return components_.begin(); }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700667
668 /**
669 * End iterator (const).
670 */
671 const_iterator
Jeff Thompson91737f52013-10-04 11:07:24 -0700672 end() const { return components_.end(); }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700673
674 /**
675 * End iterator.
676 */
677 iterator
Jeff Thompson91737f52013-10-04 11:07:24 -0700678 end() { return components_.end(); }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700679
680 /**
681 * Reverse begin iterator (const).
682 */
683 const_reverse_iterator
Jeff Thompson91737f52013-10-04 11:07:24 -0700684 rbegin() const { return components_.rbegin(); }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700685
686 /**
687 * Reverse begin iterator.
688 */
689 reverse_iterator
Jeff Thompson91737f52013-10-04 11:07:24 -0700690 rbegin() { return components_.rbegin(); }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700691
692 /**
693 * Reverse end iterator (const).
694 */
695 const_reverse_iterator
Jeff Thompson91737f52013-10-04 11:07:24 -0700696 rend() const { return components_.rend(); }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700697
698 /**
699 * Reverse end iterator.
700 */
701 reverse_iterator
Jeff Thompson91737f52013-10-04 11:07:24 -0700702 rend() { return components_.rend(); }
Jeff Thompsonec39fbd2013-10-04 10:56:23 -0700703
Jeff Thompson9c41dfe2013-06-27 12:10:25 -0700704private:
Jeff Thompson5a6b5ab2013-08-05 15:43:47 -0700705 std::vector<Component> components_;
Jeff Thompson9c41dfe2013-06-27 12:10:25 -0700706};
707
Jeff Thompson49e321a2013-10-04 17:35:59 -0700708inline std::ostream&
709operator << (std::ostream& os, const Name& name)
710{
711 os << name.toUri();
712 return os;
713}
714
Jeff Thompson9c41dfe2013-06-27 12:10:25 -0700715}
716
717#endif
718