blob: 0bcf8620a6e45a70e9e3e9ab2eea6da3aaf24479 [file] [log] [blame]
Jeff Thompsonfa306642013-06-17 15:06:57 -07001/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil -*- */
2/*
3 * Copyright (c) 2013, Regents of the University of California
4 * Alexander Afanasyev
5 *
6 * BSD license, See the LICENSE file for more information
7 *
8 * Author: Alexander Afanasyev <alexander.afanasyev@ucla.edu>
9 */
10
11#ifndef NDN_NAME_COMPONENT_H
12#define NDN_NAME_COMPONENT_H
13
14#include <string>
15#include <vector>
16
17#include "blob.h"
18#include <stdint.h>
19
20namespace ndn {
21
22namespace name {
23
24/**
25 * @brief Class to representing binary blob of NDN name component
26 *
27 * This class is based on std::vector<char> and just provides several helpers
28 * to work with name components, as well as operator to apply canonical
29 * ordering on name components
30 */
31class Component : public Blob
32{
33public:
34 /**
35 * @brief Default constructor an empty exclude
36 */
37 Component ();
38
39 /**
40 * @brief Create component from URI encoded string
41 * @param uri URI encoded name component (convert escaped with % characters)
42 */
43 Component (const std::string &uri);
44
45 /**
46 * @brief Create component from URI encoded string, with string specified by a pair of iterators
47 * @param begin begin iterator pointing to the URI encoded name
48 * @param end end iterator
49 */
50 Component (std::string::const_iterator begin, std::string::const_iterator end);
51
52 /**
53 * @brief Create component using a binary blob
54 * @param buf pointer to first byte of binary blob to store as a name component
55 * @param length length of the binary blob
56 */
57 Component (const void *buf, size_t length);
58
59 /**
60 * @brief Apply canonical ordering on component comparison
61 * @return 0 They compare equal
62 * <0 If *this comes before other in the canonical ordering
63 * >0 If *this comes after in the canonical ordering
64 *
65 * @see http://www.ccnx.org/releases/latest/doc/technical/CanonicalOrder.html
66 */
67 int
68 compare (const Component &other) const;
69
70 /**
71 * @brief Apply canonical ordering on component comparison (less or equal)
72 *
73 * @see http://www.ccnx.org/releases/latest/doc/technical/CanonicalOrder.html
74 */
75 inline bool
76 operator <= (const Component &other) const;
77
78 /**
79 * @brief Apply canonical ordering on component comparison (less)
80 *
81 * @see http://www.ccnx.org/releases/latest/doc/technical/CanonicalOrder.html
82 */
83 inline bool
84 operator < (const Component &other) const;
85
86 /**
87 * @brief Apply canonical ordering on component comparison (greater or equal)
88 *
89 * @see http://www.ccnx.org/releases/latest/doc/technical/CanonicalOrder.html
90 */
91 inline bool
92 operator >= (const Component &other) const;
93
94 /**
95 * @brief Apply canonical ordering on component comparison (greater)
96 *
97 * @see http://www.ccnx.org/releases/latest/doc/technical/CanonicalOrder.html
98 */
99 inline bool
100 operator > (const Component &other) const;
101
102 ////////////////////////////////////
103 // Component construction helpers //
104 ////////////////////////////////////
105
106 /**
107 * @brief Create network-ordered numeric component
108 *
109 * @param number number to be encoded and added as a component
110 *
111 * Number is encoded and added in network order. Tail zero-bytes are not included.
112 * For example, if the number is 1, then 1-byte binary blob will be added 0x01.
113 * If the number is 256, then 2 binary blob will be added: 0x01 0x01
114 *
115 * If the number is zero, an empty component will be created
116 */
117 static Component
118 fromNumber (uint64_t number);
119
120 /**
121 * @brief Create network-ordered numeric component to the name with marker
122 *
123 * @param number number to be encoded and added as a component
124 * @param marker byte marker, specified by the desired naming convention
125 *
126 * Currently defined naming conventions of the marker:
127 * - 0x00 sequence number
128 * - 0xC1 control number
129 * - 0xFB block id
130 * - 0xFD version number
131 *
132 * This version is almost exactly as appendNumber, with exception that it adds initial marker.
133 * The number is formatted in the exactly the same way.
134 *
135 * @see fromNumber
136 */
137 static Component
138 fromNumberWithMarker (uint64_t number, unsigned char marker);
139
140 //////////////////////////////////////////////////////////////////////////////////
141 // helpers
142 //////////////////////////////////////////////////////////////////////////////////
143
144 /**
145 * @brief Convert binary blob name component to std::string (no conversion is made)
146 * @param comp name component to be converted
147 * @see asUriString
148 */
149 std::string
150 toBlob () const;
151
152 /**
153 * @brief Write blob of the name component to the specified output stream
154 * @param os output stream
155 */
156 void
157 toBlob (std::ostream &os) const;
158
159 /**
160 * @brief Convert binary blob name component to std::string, escaping all non-printable characters in URI format
161 * @param comp name component to be converted
162 * @see asString
163 */
164 std::string
165 toUri () const;
166
167 /**
168 * @brief Write name as URI to the specified output stream
169 * @param os output stream
170 */
171 void
172 toUri (std::ostream &os) const;
173
174 /**
175 * @brief Convert binary blob name component (network-ordered number) to number
176 * @param comp name component to be converted
177 */
178 uint64_t
179 toNumber () const;
180
181 /**
182 * @brief Convert binary blob name component (network-ordered number) to number, using appropriate marker from the naming convention
183 * @param comp name component to be converted
184 * @param marker required marker from the naming convention
185 *
186 * If the required marker does not exist, an exception will be thrown
187 */
188 uint64_t
189 toNumberWithMarker (unsigned char marker) const;
190
191 /**
192 * @brief Convert binary blob name component, assuming sequence number naming convention (marker = 0x00)
193 * @param comp name component to be converted
194 * @see asNumberWithMarker
195 */
196 inline uint64_t
197 toSeqNum () const;
198
199 /**
200 * @brief Convert binary blob name component, assuming control number naming convention (marker = 0xC1)
201 * @param comp name component to be converted
202 * @see asNumberWithMarker
203 */
204 inline uint64_t
205 toControlNum () const;
206
207 /**
208 * @brief Convert binary blob name component, assuming block ID naming convention (marker = 0xFB)
209 * @param comp name component to be converted
210 * @see asNumberWithMarker
211 */
212 inline uint64_t
213 toBlkId () const;
214
215 /**
216 * @brief Convert binary blob name component, assuming time-stamping version naming convention (marker = 0xFD)
217 * @param comp name component to be converted
218 * @see asNumberWithMarker
219 */
220 inline uint64_t
221 toVersion () const;
222};
223
224bool
225Component::operator <= (const Component &other) const
226{
227 return (compare (other) <= 0);
228}
229
230bool
231Component::operator < (const Component &other) const
232{
233 return (compare (other) < 0);
234}
235
236bool
237Component::operator >= (const Component &other) const
238{
239 return (compare (other) >= 0);
240}
241
242bool
243Component::operator > (const Component &other) const
244{
245 return (compare (other) > 0);
246}
247
248inline uint64_t
249Component::toSeqNum () const
250{
251 return toNumberWithMarker (0x00);
252}
253
254inline uint64_t
255Component::toControlNum () const
256{
257 return toNumberWithMarker (0xC1);
258}
259
260inline uint64_t
261Component::toBlkId () const
262{
263 return toNumberWithMarker (0xFB);
264}
265
266inline uint64_t
267Component::toVersion () const
268{
269 return toNumberWithMarker (0xFD);
270}
271
272/**
273 * @brief Stream output operator (output in escaped URI format)
274 */
275std::ostream&
276operator <<(std::ostream &os, const Component &name);
277
278} // name
279
280} // ndn
281
282#endif // NDN_EXCLUDE_H