1 | /** @file
|
---|
2 | * IPRT - C++ Representational State Transfer (REST) Array Template Class.
|
---|
3 | */
|
---|
4 |
|
---|
5 | /*
|
---|
6 | * Copyright (C) 2008-2022 Oracle and/or its affiliates.
|
---|
7 | *
|
---|
8 | * This file is part of VirtualBox base platform packages, as
|
---|
9 | * available from https://www.virtualbox.org.
|
---|
10 | *
|
---|
11 | * This program is free software; you can redistribute it and/or
|
---|
12 | * modify it under the terms of the GNU General Public License
|
---|
13 | * as published by the Free Software Foundation, in version 3 of the
|
---|
14 | * License.
|
---|
15 | *
|
---|
16 | * This program is distributed in the hope that it will be useful, but
|
---|
17 | * WITHOUT ANY WARRANTY; without even the implied warranty of
|
---|
18 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
---|
19 | * General Public License for more details.
|
---|
20 | *
|
---|
21 | * You should have received a copy of the GNU General Public License
|
---|
22 | * along with this program; if not, see <https://www.gnu.org/licenses>.
|
---|
23 | *
|
---|
24 | * The contents of this file may alternatively be used under the terms
|
---|
25 | * of the Common Development and Distribution License Version 1.0
|
---|
26 | * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
|
---|
27 | * in the VirtualBox distribution, in which case the provisions of the
|
---|
28 | * CDDL are applicable instead of those of the GPL.
|
---|
29 | *
|
---|
30 | * You may elect to license modified versions of this file under the
|
---|
31 | * terms and conditions of either the GPL or the CDDL or both.
|
---|
32 | *
|
---|
33 | * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
|
---|
34 | */
|
---|
35 |
|
---|
36 | #ifndef IPRT_INCLUDED_cpp_restarray_h
|
---|
37 | #define IPRT_INCLUDED_cpp_restarray_h
|
---|
38 | #ifndef RT_WITHOUT_PRAGMA_ONCE
|
---|
39 | # pragma once
|
---|
40 | #endif
|
---|
41 |
|
---|
42 | #include <iprt/cpp/restbase.h>
|
---|
43 |
|
---|
44 |
|
---|
45 | /** @defgroup grp_rt_cpp_restarray C++ Representational State Transfer (REST) Array Template Class.
|
---|
46 | * @ingroup grp_rt_cpp
|
---|
47 | * @{
|
---|
48 | */
|
---|
49 |
|
---|
50 | /**
|
---|
51 | * Abstract base class for the RTCRestArray template.
|
---|
52 | */
|
---|
53 | class RT_DECL_CLASS RTCRestArrayBase : public RTCRestObjectBase
|
---|
54 | {
|
---|
55 | public:
|
---|
56 | /** Default destructor. */
|
---|
57 | RTCRestArrayBase() RT_NOEXCEPT;
|
---|
58 | /** Destructor. */
|
---|
59 | virtual ~RTCRestArrayBase();
|
---|
60 |
|
---|
61 | /* Overridden methods: */
|
---|
62 | virtual RTCRestObjectBase *baseClone() const RT_NOEXCEPT RT_OVERRIDE;
|
---|
63 | virtual int resetToDefault() RT_NOEXCEPT RT_OVERRIDE;
|
---|
64 | virtual RTCRestOutputBase &serializeAsJson(RTCRestOutputBase &a_rDst) const RT_NOEXCEPT RT_OVERRIDE;
|
---|
65 | virtual int deserializeFromJson(RTCRestJsonCursor const &a_rCursor) RT_NOEXCEPT RT_OVERRIDE;
|
---|
66 | virtual int toString(RTCString *a_pDst, uint32_t a_fFlags = kCollectionFormat_Unspecified) const RT_NOEXCEPT RT_OVERRIDE;
|
---|
67 | virtual int fromString(RTCString const &a_rValue, const char *a_pszName, PRTERRINFO a_pErrInfo = NULL,
|
---|
68 | uint32_t a_fFlags = kCollectionFormat_Unspecified) RT_NOEXCEPT RT_OVERRIDE;
|
---|
69 | virtual kTypeClass typeClass(void) const RT_NOEXCEPT RT_OVERRIDE;
|
---|
70 | virtual const char *typeName(void) const RT_NOEXCEPT RT_OVERRIDE;
|
---|
71 |
|
---|
72 | /**
|
---|
73 | * Clear the content of the map.
|
---|
74 | */
|
---|
75 | void clear() RT_NOEXCEPT;
|
---|
76 |
|
---|
77 | /**
|
---|
78 | * Check if an list contains any items.
|
---|
79 | *
|
---|
80 | * @return True if there is more than zero items, false otherwise.
|
---|
81 | */
|
---|
82 | inline bool isEmpty() const RT_NOEXCEPT
|
---|
83 | {
|
---|
84 | return m_cElements == 0;
|
---|
85 | }
|
---|
86 |
|
---|
87 | /**
|
---|
88 | * Gets the number of entries in the map.
|
---|
89 | */
|
---|
90 | inline size_t size() const RT_NOEXCEPT
|
---|
91 | {
|
---|
92 | return m_cElements;
|
---|
93 | }
|
---|
94 |
|
---|
95 | /**
|
---|
96 | * Returns the base object pointer at a given index.
|
---|
97 | *
|
---|
98 | * @returns The base object at @a a_idx, NULL if out of range.
|
---|
99 | * @param a_idx The array index.
|
---|
100 | */
|
---|
101 | inline RTCRestObjectBase *atBase(size_t a_idx) RT_NOEXCEPT
|
---|
102 | {
|
---|
103 | if (a_idx < m_cElements)
|
---|
104 | return m_papElements[a_idx];
|
---|
105 | return NULL;
|
---|
106 | }
|
---|
107 |
|
---|
108 | /**
|
---|
109 | * Returns the const base object pointer at a given index.
|
---|
110 | *
|
---|
111 | * @returns The base object at @a a_idx, NULL if out of range.
|
---|
112 | * @param a_idx The array index.
|
---|
113 | */
|
---|
114 | inline RTCRestObjectBase const *atBase(size_t a_idx) const RT_NOEXCEPT
|
---|
115 | {
|
---|
116 | if (a_idx < m_cElements)
|
---|
117 | return m_papElements[a_idx];
|
---|
118 | return NULL;
|
---|
119 | }
|
---|
120 |
|
---|
121 | /**
|
---|
122 | * Removes the element at @a a_idx.
|
---|
123 | * @returns true if @a a_idx is valid, false if out of range.
|
---|
124 | * @param a_idx The index of the element to remove.
|
---|
125 | * The value ~(size_t)0 is an alias for the final element.
|
---|
126 | */
|
---|
127 | bool removeAt(size_t a_idx) RT_NOEXCEPT;
|
---|
128 |
|
---|
129 | /**
|
---|
130 | * Makes sure the array can hold at the given number of entries.
|
---|
131 | *
|
---|
132 | * @returns VINF_SUCCESS or VERR_NO_MEMORY.
|
---|
133 | * @param a_cEnsureCapacity The number of elements to ensure capacity to hold.
|
---|
134 | */
|
---|
135 | int ensureCapacity(size_t a_cEnsureCapacity) RT_NOEXCEPT;
|
---|
136 |
|
---|
137 |
|
---|
138 | protected:
|
---|
139 | /** The array. */
|
---|
140 | RTCRestObjectBase **m_papElements;
|
---|
141 | /** Number of elements in the array. */
|
---|
142 | size_t m_cElements;
|
---|
143 | /** The number of elements m_papElements can hold.
|
---|
144 | * The difference between m_cCapacity and m_cElements are all NULLs. */
|
---|
145 | size_t m_cCapacity;
|
---|
146 |
|
---|
147 | /**
|
---|
148 | * Helper for creating a clone.
|
---|
149 | *
|
---|
150 | * @returns Pointer to new array on success, NULL if out of memory.
|
---|
151 | */
|
---|
152 | virtual RTCRestArrayBase *createClone(void) const RT_NOEXCEPT = 0;
|
---|
153 |
|
---|
154 | /**
|
---|
155 | * Wrapper around the value constructor.
|
---|
156 | *
|
---|
157 | * @returns Pointer to new value object on success, NULL if out of memory.
|
---|
158 | */
|
---|
159 | virtual RTCRestObjectBase *createValue(void) RT_NOEXCEPT = 0;
|
---|
160 |
|
---|
161 | /**
|
---|
162 | * For accessing the static deserializeInstanceFromJson() method of the value.
|
---|
163 | */
|
---|
164 | virtual int deserializeValueInstanceFromJson(RTCRestJsonCursor const &a_rCursor, RTCRestObjectBase **a_ppInstance) RT_NOEXCEPT = 0;
|
---|
165 |
|
---|
166 | /**
|
---|
167 | * Worker for the copy assignment method and copyArrayWorkerMayThrow().
|
---|
168 | *
|
---|
169 | * This will use createEntryCopy to do the copying.
|
---|
170 | *
|
---|
171 | * @returns VINF_SUCCESS on success, VERR_NO_MEMORY or VERR_NO_STR_MEMORY on failure.
|
---|
172 | * @param a_rThat The array to copy. Caller makes 100% sure the it has
|
---|
173 | * the same type as the destination.
|
---|
174 | */
|
---|
175 | int copyArrayWorkerNoThrow(RTCRestArrayBase const &a_rThat) RT_NOEXCEPT;
|
---|
176 |
|
---|
177 | /**
|
---|
178 | * Wrapper around copyArrayWorkerNoThrow for the copy constructor and the
|
---|
179 | * assignment operator.
|
---|
180 | */
|
---|
181 | void copyArrayWorkerMayThrow(RTCRestArrayBase const &a_rThat);
|
---|
182 |
|
---|
183 | /**
|
---|
184 | * Worker for performing inserts.
|
---|
185 | *
|
---|
186 | * @returns VINF_SUCCESS or VWRN_ALREADY_EXISTS on success.
|
---|
187 | * VERR_ALREADY_EXISTS, VERR_NO_MEMORY or VERR_NO_STR_MEMORY on failure.
|
---|
188 | * @param a_idx Where to insert it. The value ~(size_t)0 is an alias for m_cElements.
|
---|
189 | * @param a_pValue The value to insert. Ownership is transferred to the map on success.
|
---|
190 | * @param a_fReplace Whether to replace existing entry rather than insert.
|
---|
191 | */
|
---|
192 | int insertWorker(size_t a_idx, RTCRestObjectBase *a_pValue, bool a_fReplace) RT_NOEXCEPT;
|
---|
193 |
|
---|
194 | /**
|
---|
195 | * Worker for performing inserts.
|
---|
196 | *
|
---|
197 | * @returns VINF_SUCCESS or VWRN_ALREADY_EXISTS on success.
|
---|
198 | * VERR_ALREADY_EXISTS, VERR_NO_MEMORY or VERR_NO_STR_MEMORY on failure.
|
---|
199 | * @param a_idx Where to insert it. The value ~(size_t)0 is an alias for m_cElements.
|
---|
200 | * @param a_rValue The value to copy into the map.
|
---|
201 | * @param a_fReplace Whether to replace existing key-value pair with matching key.
|
---|
202 | */
|
---|
203 | int insertCopyWorker(size_t a_idx, RTCRestObjectBase const &a_rValue, bool a_fReplace) RT_NOEXCEPT;
|
---|
204 |
|
---|
205 | private:
|
---|
206 | /** Copy constructor on this class should never be used. */
|
---|
207 | RTCRestArrayBase(RTCRestArrayBase const &a_rThat);
|
---|
208 | /** Copy assignment operator on this class should never be used. */
|
---|
209 | RTCRestArrayBase &operator=(RTCRestArrayBase const &a_rThat);
|
---|
210 | };
|
---|
211 |
|
---|
212 |
|
---|
213 |
|
---|
214 | /**
|
---|
215 | * Limited array class.
|
---|
216 | */
|
---|
217 | template<class ElementType> class RTCRestArray : public RTCRestArrayBase
|
---|
218 | {
|
---|
219 | public:
|
---|
220 | /** Default constructor - empty array. */
|
---|
221 | RTCRestArray() RT_NOEXCEPT
|
---|
222 | : RTCRestArrayBase()
|
---|
223 | {
|
---|
224 | }
|
---|
225 |
|
---|
226 | /** Destructor. */
|
---|
227 | ~RTCRestArray()
|
---|
228 | {
|
---|
229 | }
|
---|
230 |
|
---|
231 | /** Copy constructor. */
|
---|
232 | RTCRestArray(RTCRestArray const &a_rThat)
|
---|
233 | : RTCRestArrayBase()
|
---|
234 | {
|
---|
235 | copyArrayWorkerMayThrow(a_rThat);
|
---|
236 | }
|
---|
237 |
|
---|
238 | /** Copy assignment operator. */
|
---|
239 | inline RTCRestArray &operator=(RTCRestArray const &a_rThat)
|
---|
240 | {
|
---|
241 | copyArrayWorkerMayThrow(a_rThat);
|
---|
242 | return *this;
|
---|
243 | }
|
---|
244 |
|
---|
245 | /** Safe copy assignment method. */
|
---|
246 | inline int assignCopy(RTCRestArray const &a_rThat) RT_NOEXCEPT
|
---|
247 | {
|
---|
248 | return copyArrayWorkerNoThrow(a_rThat);
|
---|
249 | }
|
---|
250 |
|
---|
251 | /** Make a clone of this object. */
|
---|
252 | inline RTCRestArray *clone() const RT_NOEXCEPT
|
---|
253 | {
|
---|
254 | return (RTCRestArray *)baseClone();
|
---|
255 | }
|
---|
256 |
|
---|
257 | /** Factory method. */
|
---|
258 | static DECLCALLBACK(RTCRestObjectBase *) createInstance(void) RT_NOEXCEPT
|
---|
259 | {
|
---|
260 | return new (std::nothrow) RTCRestArray<ElementType>();
|
---|
261 | }
|
---|
262 |
|
---|
263 | /** Factory method for elements. */
|
---|
264 | static DECLCALLBACK(RTCRestObjectBase *) createElementInstance(void) RT_NOEXCEPT
|
---|
265 | {
|
---|
266 | return new (std::nothrow) ElementType();
|
---|
267 | }
|
---|
268 |
|
---|
269 | /** @copydoc RTCRestObjectBase::FNDESERIALIZEINSTANCEFROMJSON */
|
---|
270 | static DECLCALLBACK(int) deserializeInstanceFromJson(RTCRestJsonCursor const &a_rCursor, RTCRestObjectBase **a_ppInstance) RT_NOEXCEPT
|
---|
271 | {
|
---|
272 | *a_ppInstance = new (std::nothrow) RTCRestArray<ElementType>();
|
---|
273 | if (*a_ppInstance)
|
---|
274 | return (*a_ppInstance)->deserializeFromJson(a_rCursor);
|
---|
275 | return a_rCursor.m_pPrimary->addError(a_rCursor, VERR_NO_MEMORY, "Out of memory");
|
---|
276 | }
|
---|
277 |
|
---|
278 |
|
---|
279 | /**
|
---|
280 | * Insert the given object at the specified index.
|
---|
281 | *
|
---|
282 | * @returns VINF_SUCCESS on success.
|
---|
283 | * VERR_INVALID_POINTER, VERR_NO_MEMORY, VERR_NO_STR_MEMORY or VERR_OUT_OF_RANGE on failure.
|
---|
284 | * @param a_idx The insertion index. ~(size_t)0 is an alias for the end.
|
---|
285 | * @param a_pThat The object to insert. The array takes ownership of the object on success.
|
---|
286 | */
|
---|
287 | inline int insert(size_t a_idx, ElementType *a_pThat) RT_NOEXCEPT
|
---|
288 | {
|
---|
289 | return insertWorker(a_idx, a_pThat, false /*a_fReplace*/);
|
---|
290 | }
|
---|
291 |
|
---|
292 | /**
|
---|
293 | * Insert a copy of the object at the specified index.
|
---|
294 | *
|
---|
295 | * @returns VINF_SUCCESS on success.
|
---|
296 | * VERR_NO_MEMORY, VERR_NO_STR_MEMORY or VERR_OUT_OF_RANGE on failure.
|
---|
297 | * @param a_idx The insertion index. ~(size_t)0 is an alias for the end.
|
---|
298 | * @param a_rThat The object to insert a copy of.
|
---|
299 | */
|
---|
300 | inline int insertCopy(size_t a_idx, ElementType const &a_rThat) RT_NOEXCEPT
|
---|
301 | {
|
---|
302 | return insertCopyWorker(a_idx, a_rThat, false /*a_fReplace*/);
|
---|
303 | }
|
---|
304 |
|
---|
305 | /**
|
---|
306 | * Appends the given object to the array.
|
---|
307 | *
|
---|
308 | * @returns VINF_SUCCESS on success.
|
---|
309 | * VERR_INVALID_POINTER, VERR_NO_MEMORY, VERR_NO_STR_MEMORY or VERR_OUT_OF_RANGE on failure.
|
---|
310 | * @param a_pThat The object to insert. The array takes ownership of the object on success.
|
---|
311 | */
|
---|
312 | inline int append(ElementType *a_pThat) RT_NOEXCEPT
|
---|
313 | {
|
---|
314 | return insertWorker(~(size_t)0, a_pThat, false /*a_fReplace*/);
|
---|
315 | }
|
---|
316 |
|
---|
317 | /**
|
---|
318 | * Appends a copy of the object at the specified index.
|
---|
319 | *
|
---|
320 | * @returns VINF_SUCCESS on success.
|
---|
321 | * VERR_NO_MEMORY, VERR_NO_STR_MEMORY or VERR_OUT_OF_RANGE on failure.
|
---|
322 | * @param a_rThat The object to insert a copy of.
|
---|
323 | */
|
---|
324 | inline int appendCopy(ElementType const &a_rThat) RT_NOEXCEPT
|
---|
325 | {
|
---|
326 | return insertCopyWorker(~(size_t)0, a_rThat, false /*a_fReplace*/);
|
---|
327 | }
|
---|
328 |
|
---|
329 | /**
|
---|
330 | * Prepends the given object to the array.
|
---|
331 | *
|
---|
332 | * @returns VINF_SUCCESS on success.
|
---|
333 | * VERR_INVALID_POINTER, VERR_NO_MEMORY, VERR_NO_STR_MEMORY or VERR_OUT_OF_RANGE on failure.
|
---|
334 | * @param a_pThat The object to insert. The array takes ownership of the object on success.
|
---|
335 | */
|
---|
336 | inline int prepend(ElementType *a_pThat) RT_NOEXCEPT
|
---|
337 | {
|
---|
338 | return insertWorker(0, a_pThat, false /*a_fReplace*/);
|
---|
339 | }
|
---|
340 |
|
---|
341 | /**
|
---|
342 | * Prepends a copy of the object at the specified index.
|
---|
343 | *
|
---|
344 | * @returns VINF_SUCCESS on success.
|
---|
345 | * VERR_NO_MEMORY, VERR_NO_STR_MEMORY or VERR_OUT_OF_RANGE on failure.
|
---|
346 | * @param a_rThat The object to insert a copy of.
|
---|
347 | */
|
---|
348 | inline int prependCopy(ElementType const &a_rThat) RT_NOEXCEPT
|
---|
349 | {
|
---|
350 | return insertCopyWorker(0, a_rThat, false /*a_fReplace*/);
|
---|
351 | }
|
---|
352 |
|
---|
353 | /**
|
---|
354 | * Insert the given object at the specified index.
|
---|
355 | *
|
---|
356 | * @returns VINF_SUCCESS on success.
|
---|
357 | * VERR_INVALID_POINTER, VERR_NO_MEMORY, VERR_NO_STR_MEMORY or VERR_OUT_OF_RANGE on failure.
|
---|
358 | * @param a_idx The index of the existing object to replace.
|
---|
359 | * @param a_pThat The replacement object. The array takes ownership of the object on success.
|
---|
360 | */
|
---|
361 | inline int replace(size_t a_idx, ElementType *a_pThat) RT_NOEXCEPT
|
---|
362 | {
|
---|
363 | return insertWorker(a_idx, a_pThat, true /*a_fReplace*/);
|
---|
364 | }
|
---|
365 |
|
---|
366 | /**
|
---|
367 | * Insert a copy of the object at the specified index.
|
---|
368 | *
|
---|
369 | * @returns VINF_SUCCESS on success.
|
---|
370 | * VERR_NO_MEMORY, VERR_NO_STR_MEMORY or VERR_OUT_OF_RANGE on failure.
|
---|
371 | * @param a_idx The index of the existing object to replace.
|
---|
372 | * @param a_rThat The object to insert a copy of.
|
---|
373 | */
|
---|
374 | inline int replaceCopy(size_t a_idx, ElementType const &a_rThat) RT_NOEXCEPT
|
---|
375 | {
|
---|
376 | return insertCopyWorker(a_idx, a_rThat, true /*a_fReplace*/);
|
---|
377 | }
|
---|
378 |
|
---|
379 | /**
|
---|
380 | * Returns the object at a given index.
|
---|
381 | *
|
---|
382 | * @returns The object at @a a_idx, NULL if out of range.
|
---|
383 | * @param a_idx The array index.
|
---|
384 | */
|
---|
385 | inline ElementType *at(size_t a_idx) RT_NOEXCEPT
|
---|
386 | {
|
---|
387 | if (a_idx < m_cElements)
|
---|
388 | return (ElementType *)m_papElements[a_idx];
|
---|
389 | return NULL;
|
---|
390 | }
|
---|
391 |
|
---|
392 | /**
|
---|
393 | * Returns the object at a given index, const variant.
|
---|
394 | *
|
---|
395 | * @returns The object at @a a_idx, NULL if out of range.
|
---|
396 | * @param a_idx The array index.
|
---|
397 | */
|
---|
398 | inline ElementType const *at(size_t a_idx) const RT_NOEXCEPT
|
---|
399 | {
|
---|
400 | if (a_idx < m_cElements)
|
---|
401 | return (ElementType const *)m_papElements[a_idx];
|
---|
402 | return NULL;
|
---|
403 | }
|
---|
404 |
|
---|
405 | /**
|
---|
406 | * Returns the first object in the array.
|
---|
407 | * @returns The first object, NULL if empty.
|
---|
408 | */
|
---|
409 | inline ElementType *first() RT_NOEXCEPT
|
---|
410 | {
|
---|
411 | return at(0);
|
---|
412 | }
|
---|
413 |
|
---|
414 | /**
|
---|
415 | * Returns the first object in the array, const variant.
|
---|
416 | * @returns The first object, NULL if empty.
|
---|
417 | */
|
---|
418 | inline ElementType const *first() const RT_NOEXCEPT
|
---|
419 | {
|
---|
420 | return at(0);
|
---|
421 | }
|
---|
422 |
|
---|
423 | /**
|
---|
424 | * Returns the last object in the array.
|
---|
425 | * @returns The last object, NULL if empty.
|
---|
426 | */
|
---|
427 | inline ElementType *last() RT_NOEXCEPT
|
---|
428 | {
|
---|
429 | return at(m_cElements - 1);
|
---|
430 | }
|
---|
431 |
|
---|
432 | /**
|
---|
433 | * Returns the last object in the array, const variant.
|
---|
434 | * @returns The last object, NULL if empty.
|
---|
435 | */
|
---|
436 | inline ElementType const *last() const RT_NOEXCEPT
|
---|
437 | {
|
---|
438 | return at(m_cElements - 1);
|
---|
439 | }
|
---|
440 |
|
---|
441 |
|
---|
442 | protected:
|
---|
443 | virtual RTCRestArrayBase *createClone(void) const RT_NOEXCEPT RT_OVERRIDE
|
---|
444 | {
|
---|
445 | return new (std::nothrow) RTCRestArray();
|
---|
446 | }
|
---|
447 |
|
---|
448 | virtual RTCRestObjectBase *createValue(void) RT_NOEXCEPT RT_OVERRIDE
|
---|
449 | {
|
---|
450 | return new (std::nothrow) ElementType();
|
---|
451 | }
|
---|
452 |
|
---|
453 | virtual int deserializeValueInstanceFromJson(RTCRestJsonCursor const &a_rCursor, RTCRestObjectBase **a_ppInstance) RT_NOEXCEPT RT_OVERRIDE
|
---|
454 | {
|
---|
455 | return ElementType::deserializeInstanceFromJson(a_rCursor, a_ppInstance);
|
---|
456 | }
|
---|
457 | };
|
---|
458 |
|
---|
459 |
|
---|
460 | /** @} */
|
---|
461 |
|
---|
462 | #endif /* !IPRT_INCLUDED_cpp_restarray_h */
|
---|
463 |
|
---|