blob: 4c3ecca87f4819662afe000dba2907fc116a5baf [file] [log] [blame]
Alexander Afanasyev95e8c2f2014-02-06 17:29:30 -08001/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil -*- */
2/**
3 * Copyright (C) 2013 Regents of the University of California.
4 * @author: Jeff Thompson <jefft0@remap.ucla.edu>
5 * @author: Alexander Afanasyev <alexander.afanasyev@ucla.edu>
6 * @author: Zhenkai Zhu <zhenkai@cs.ucla.edu>
7 * See COPYING for copyright and distribution information.
8 */
9
10#ifndef NDN_NAME_COMPONENT_HPP
11#define NDN_NAME_COMPONENT_HPP
12
13#include "common.hpp"
14#include "encoding/block.hpp"
15#include "encoding/encoding-buffer.hpp"
16
17namespace ndn {
18namespace name {
19
20/**
21 * A Name::Component holds a read-only name component value.
22 */
23class Component : public Block
24{
25public:
26 /// @brief Error that can be thrown from the block
27 struct Error : public std::runtime_error { Error(const std::string &what) : std::runtime_error(what) {} };
28
29 /**
30 * Create a new Name::Component with a null value.
31 */
32 Component()
33 : Block(Tlv::NameComponent)
34 {
35 }
36
Alexander Afanasyev52eb20d2014-02-06 18:25:54 -080037 /**
38 * @brief Directly create component from wire block
39 *
40 * ATTENTION wire MUST BE of type Tlv::Component. Any other value would cause an exception
41 */
42 Component(const Block& wire)
43 : Block(wire)
44 {
45 if (type() != Tlv::NameComponent)
46 throw Error("Constructing name component from non name component TLV wire block");
47 }
Alexander Afanasyev95e8c2f2014-02-06 17:29:30 -080048
49 /**
50 * Create a new Name::Component, taking another pointer to the Blob value.
51 * @param value A blob with a pointer to an immutable array. The pointer is copied.
52 */
53 Component(const ConstBufferPtr &buffer)
54 : Block (Tlv::NameComponent, buffer)
55 {
56 }
57
58 /**
59 * Create a new Name::Component, copying the given value.
60 * @param value The value byte array.
61 */
62 Component(const Buffer& value)
63 : Block (Tlv::NameComponent, ConstBufferPtr(new Buffer(value)))
64 {
65 }
66
67 /**
68 * Create a new Name::Component, copying the given value.
69 * @param value Pointer to the value byte array.
70 * @param valueLen Length of value.
71 */
72 Component(const uint8_t *value, size_t valueLen)
73 : Block (Tlv::NameComponent, ConstBufferPtr(new Buffer(value, valueLen)))
74 {
75 }
76
77 template<class InputIterator>
78 Component(InputIterator begin, InputIterator end)
79 : Block (Tlv::NameComponent, ConstBufferPtr(new Buffer(begin, end)))
80 {
81 }
Alexander Afanasyev52eb20d2014-02-06 18:25:54 -080082
83 explicit
84 Component(const char *str)
85 : Block (Tlv::NameComponent, ConstBufferPtr(new Buffer(str, ::strlen(str))))
Alexander Afanasyev95e8c2f2014-02-06 17:29:30 -080086 {
87 }
88
Alexander Afanasyev52eb20d2014-02-06 18:25:54 -080089 explicit
90 Component(const std::string& str)
91 : Block (Tlv::NameComponent, ConstBufferPtr(new Buffer(str.begin(), str.end())))
92 {
93 }
94
Alexander Afanasyev95e8c2f2014-02-06 17:29:30 -080095 /**
96 * @brief Fast encoding or block size estimation
97 */
98 template<bool T>
99 size_t
100 wireEncode(EncodingImpl<T> &block) const;
101
102 /**
103 * Make a Blob value by decoding the escapedString between beginOffset and endOffset according to the NDN URI Scheme.
104 * If the escaped string is "", "." or ".." then return a Blob with a null pointer,
105 * which means the component should be skipped in a URI name.
106 * @param escapedString The escaped string. It does not need to be null-terminated because we only scan to endOffset.
107 * @param beginOffset The offset in escapedString of the beginning of the portion to decode.
108 * @param endOffset The offset in escapedString of the end of the portion to decode.
109 * @return The Blob value. If the escapedString is not a valid escaped component, then the Blob is a null pointer.
110 */
111 static Component
112 fromEscapedString(const char *escapedString, size_t beginOffset, size_t endOffset);
113
114 /**
115 * Make a Blob value by decoding the escapedString according to the NDN URI Scheme.
116 * If the escaped string is "", "." or ".." then return a Blob with a null pointer,
117 * which means the component should be skipped in a URI name.
118 * @param escapedString The null-terminated escaped string.
119 * @return The Blob value. If the escapedString is not a valid escaped component, then the Blob is a null pointer.
120 */
121 static Component
122 fromEscapedString(const char *escapedString)
123 {
124 return fromEscapedString(escapedString, 0, ::strlen(escapedString));
125 }
126
127 /**
128 * Make a Blob value by decoding the escapedString according to the NDN URI Scheme.
129 * If the escaped string is "", "." or ".." then return a Blob with a null pointer,
130 * which means the component should be skipped in a URI name.
131 * @param escapedString The escaped string.
132 * @return The Blob value. If the escapedString is not a valid escaped component, then the Blob is a null pointer.
133 */
134 static Component
135 fromEscapedString(const std::string& escapedString)
136 {
137 return fromEscapedString(escapedString.c_str());
138 }
139
140 /**
141 * Write the value to result, escaping characters according to the NDN URI Scheme.
142 * This also adds "..." to a value with zero or more ".".
143 * @param value the buffer with the value to escape
144 * @param result the string stream to write to.
145 */
146 void
147 toEscapedString(std::ostream& result) const;
148
149 /**
150 * Convert the value by escaping characters according to the NDN URI Scheme.
151 * This also adds "..." to a value with zero or more ".".
152 * @param value the buffer with the value to escape
153 * @return The escaped string.
154 */
155 inline std::string
156 toEscapedString() const
157 {
158 std::ostringstream result;
159 toEscapedString(result);
160 return result.str();
161 }
Alexander Afanasyev52eb20d2014-02-06 18:25:54 -0800162
163 inline void
164 toUri(std::ostream& result) const
165 {
166 return toEscapedString(result);
167 }
168
169 inline std::string
170 toUri() const
171 {
172 return toEscapedString();
173 }
Alexander Afanasyev95e8c2f2014-02-06 17:29:30 -0800174
175 /**
176 * Interpret this name component as a network-ordered number and return an integer.
177 * @return The integer number.
178 */
179 uint64_t
180 toNumber() const;
181
182 /**
183 * Interpret this name component as a network-ordered number with a marker and return an integer.
184 * @param marker The required first byte of the component.
185 * @return The integer number.
186 * @throw runtime_error If the first byte of the component does not equal the marker.
187 */
188 uint64_t
189 toNumberWithMarker(uint8_t marker) const;
190
191 /**
192 * Interpret this name component as a segment number according to NDN name conventions (a network-ordered number
193 * where the first byte is the marker 0x00).
194 * @return The integer segment number.
195 * @throw runtime_error If the first byte of the component is not the expected marker.
196 */
197 uint64_t
198 toSegment() const
199 {
200 return toNumberWithMarker(0x00);
201 }
202
203 /**
204 * @deprecated Use toSegment.
205 */
206 uint64_t
207 toSeqNum() const
208 {
209 return toSegment();
210 }
211
212 /**
213 * Interpret this name component as a version number according to NDN name conventions (a network-ordered number
214 * where the first byte is the marker 0xFD). Note that this returns the exact number from the component
215 * without converting it to a time representation.
216 * @return The integer segment number.
217 * @throw runtime_error If the first byte of the component is not the expected marker.
218 */
219 uint64_t
220 toVersion() const
221 {
222 return toNumberWithMarker(0xFD);
223 }
224
225 /**
226 * Create a component whose value is the network-ordered encoding of the number.
227 * Note: if the number is zero, the result is empty.
228 * @param number The number to be encoded.
229 * @return The component value.
230 */
231 static Component
232 fromNumber(uint64_t number);
233
234 /**
235 * Create a component whose value is the marker appended with the network-ordered encoding of the number.
236 * Note: if the number is zero, no bytes are used for the number - the result will have only the marker.
237 * @param number The number to be encoded.
238 * @param marker The marker to use as the first byte of the component.
239 * @return The component value.
240 */
241 static Component
242 fromNumberWithMarker(uint64_t number, uint8_t marker);
243
244 /**
245 * Check if this is the same component as other.
246 * @param other The other Component to compare with.
247 * @return true if the components are equal, otherwise false.
248 */
249 bool
250 equals(const Component& other) const
251 {
252 if (value_size() != other.value_size())
253 return false;
254
255 return std::equal(value_begin(), value_end(), other.value_begin());
256 }
257
258 bool
259 empty() const
260 {
261 return !hasValue();
262 }
263
264 /**
265 * Check if this is the same component as other.
266 * @param other The other Component to compare with.
267 * @return true if the components are equal, otherwise false.
268 */
269 bool
270 operator == (const Component& other) const { return equals(other); }
271
272 /**
273 * Check if this is not the same component as other.
274 * @param other The other Component to compare with.
275 * @return true if the components are not equal, otherwise false.
276 */
277 bool
278 operator != (const Component& other) const { return !equals(other); }
279
280 /**
281 * Compare this to the other Component using NDN canonical ordering.
282 * @param other The other Component to compare with.
283 * @return 0 If they compare equal, -1 if *this comes before other in the canonical ordering, or
284 * 1 if *this comes after other in the canonical ordering.
285 *
286 * @see http://named-data.net/doc/0.2/technical/CanonicalOrder.html
287 */
288 int
289 compare(const Component& other) const;
290
291 /**
292 * Return true if this is less than or equal to the other Component in the NDN canonical ordering.
293 * @param other The other Component to compare with.
294 *
295 * @see http://named-data.net/doc/0.2/technical/CanonicalOrder.html
296 */
297 bool
298 operator <= (const Component& other) const { return compare(other) <= 0; }
299
300 /**
301 * Return true if this is less than the other Component in the NDN canonical ordering.
302 * @param other The other Component to compare with.
303 *
304 * @see http://named-data.net/doc/0.2/technical/CanonicalOrder.html
305 */
306 bool
307 operator < (const Component& other) const { return compare(other) < 0; }
308
309 /**
310 * Return true if this is less than or equal to the other Component in the NDN canonical ordering.
311 * @param other The other Component to compare with.
312 *
313 * @see http://named-data.net/doc/0.2/technical/CanonicalOrder.html
314 */
315 bool
316 operator >= (const Component& other) const { return compare(other) >= 0; }
317
318 /**
319 * Return true if this is greater than the other Component in the NDN canonical ordering.
320 * @param other The other Component to compare with.
321 *
322 * @see http://named-data.net/doc/0.2/technical/CanonicalOrder.html
323 */
324 bool
325 operator > (const Component& other) const { return compare(other) > 0; }
326
327 //
328 // !!! MUST NOT INCLUDE ANY DATA HERE !!!
329 //
330 // This class is just a helper and is directly reinterpret_cast'ed from Block
331};
332
333inline std::ostream &
334operator << (std::ostream &os, const Component &component)
335{
336 component.toEscapedString(os);
337 return os;
338}
339
340template<bool T>
341inline size_t
342Component::wireEncode(EncodingImpl<T>& block) const
343{
344 size_t total_len = 0;
Alexander Afanasyev380420b2014-02-09 20:52:29 -0800345 if (value_size() > 0)
346 total_len += block.prependByteArray (value(), value_size());
Alexander Afanasyev95e8c2f2014-02-06 17:29:30 -0800347 total_len += block.prependVarNumber (value_size());
348 total_len += block.prependVarNumber (Tlv::NameComponent);
349 return total_len;
350}
351
Alexander Afanasyev95e8c2f2014-02-06 17:29:30 -0800352} // namespace name
353} // namespace ndn
354
355#endif // NDN_NAME_COMPONENT_HPP