reststringmap.h@ 74410

Last change on this file since 74410 was 74402, checked in by vboxsync, 6 years ago
IPRT/rest: Implemented array and string-map support for deserializating polymorphic objects. bugref:9167
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 16.9 KB

Line
1	/** @file
2	* IPRT - C++ Representational State Transfer (REST) String Map Template.
3	*/
4
5	/*
6	* Copyright (C) 2008-2018 Oracle Corporation
7	*
8	* This file is part of VirtualBox Open Source Edition (OSE), as
9	* available from http://www.virtualbox.org. This file is free software;
10	* you can redistribute it and/or modify it under the terms of the GNU
11	* General Public License (GPL) as published by the Free Software
12	* Foundation, in version 2 as it comes in the "COPYING" file of the
13	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15	*
16	* The contents of this file may alternatively be used under the terms
17	* of the Common Development and Distribution License Version 1.0
18	* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19	* VirtualBox OSE distribution, in which case the provisions of the
20	* CDDL are applicable instead of those of the GPL.
21	*
22	* You may elect to license modified versions of this file under the
23	* terms and conditions of either the GPL or the CDDL or both.
24	*/
25
26	#ifndef ___iprt_cpp_reststringmap_h
27	#define ___iprt_cpp_reststringmap_h
28
29	#include <iprt/list.h>
30	#include <iprt/string.h>
31	#include <iprt/cpp/restbase.h>
32
33
34	/** @defgroup grp_rt_cpp_reststingmap C++ Representational State Transfer (REST) String Map Template
35	* @ingroup grp_rt_cpp
36	* @{
37	*/
38
39	/**
40	* Abstract base class for the RTCRestStringMap template.
41	*/
42	class RT_DECL_CLASS RTCRestStringMapBase : public RTCRestObjectBase
43	{
44	public:
45	/** Default destructor. */
46	RTCRestStringMapBase();
47	/** Copy constructor. */
48	RTCRestStringMapBase(RTCRestStringMapBase const &a_rThat);
49	/** Destructor. */
50	virtual ~RTCRestStringMapBase();
51	/** Copy assignment operator. */
52	RTCRestStringMapBase &operator=(RTCRestStringMapBase const &a_rThat);
53
54	/* Overridden methods: */
55	virtual RTCRestObjectBase *baseClone() const RT_OVERRIDE;
56	virtual int resetToDefault() RT_OVERRIDE;
57	virtual RTCRestOutputBase &serializeAsJson(RTCRestOutputBase &a_rDst) const RT_OVERRIDE;
58	virtual int deserializeFromJson(RTCRestJsonCursor const &a_rCursor) RT_OVERRIDE;
59	// later?
60	//virtual int toString(RTCString *a_pDst, uint32_t a_fFlags = kCollectionFormat_Unspecified) const RT_OVERRIDE;
61	//virtual int fromString(RTCString const &a_rValue, const char *a_pszName, PRTERRINFO a_pErrInfo = NULL,
62	// uint32_t a_fFlags = kCollectionFormat_Unspecified) RT_OVERRIDE;
63	virtual kTypeClass typeClass(void) const RT_OVERRIDE;
64	virtual const char *typeName(void) const RT_OVERRIDE;
65
66	/**
67	* Clear the content of the map.
68	*/
69	void clear();
70
71	/**
72	* Checks if the map is empty.
73	*/
74	inline bool isEmpty() const { return m_cEntries == 0; }
75
76	/**
77	* Gets the number of entries in the map.
78	*/
79	size_t size() const;
80
81	/**
82	* Checks if the map contains the given key.
83	* @returns true if key found, false if not.
84	* @param a_pszKey The key to check fo.
85	*/
86	bool containsKey(const char *a_pszKey) const;
87
88	/**
89	* Checks if the map contains the given key.
90	* @returns true if key found, false if not.
91	* @param a_rStrKey The key to check fo.
92	*/
93	bool containsKey(RTCString const &a_rStrKey) const;
94
95	/**
96	* Remove any key-value pair with the given key.
97	* @returns true if anything was removed, false if not found.
98	* @param a_pszKey The key to remove.
99	*/
100	bool remove(const char *a_pszKey);
101
102	/**
103	* Remove any key-value pair with the given key.
104	* @returns true if anything was removed, false if not found.
105	* @param a_rStrKey The key to remove.
106	*/
107	bool remove(RTCString const &a_rStrKey);
108
109	/**
110	* Creates a new value and inserts it under the given key, returning the new value.
111	*
112	* @returns VINF_SUCCESS or VWRN_ALREADY_EXISTS on success.
113	* VERR_ALREADY_EXISTS, VERR_NO_MEMORY or VERR_NO_STR_MEMORY on failure.
114	* @param a_ppValue Where to return the pointer to the value.
115	* @param a_pszKey The key to put it under.
116	* @param a_cchKey The length of the key. Default is the entire string.
117	* @param a_fReplace Whether to replace or fail on key collision.
118	*/
119	int putNewValue(RTCRestObjectBase *a_ppValue, const char a_pszKey, size_t a_cchKey = RTSTR_MAX, bool a_fReplace = false);
120
121	/**
122	* Creates a new value and inserts it under the given key, returning the new value.
123	*
124	* @returns VINF_SUCCESS or VWRN_ALREADY_EXISTS on success.
125	* VERR_ALREADY_EXISTS, VERR_NO_MEMORY or VERR_NO_STR_MEMORY on failure.
126	* @param a_ppValue Where to return the pointer to the value.
127	* @param a_rStrKey The key to put it under.
128	* @param a_fReplace Whether to replace or fail on key collision.
129	*/
130	int putNewValue(RTCRestObjectBase **a_ppValue, RTCString const &a_rStrKey, bool a_fReplace = false);
131
132	protected:
133	/** Map entry. */
134	typedef struct MapEntry
135	{
136	/** String space core. */
137	RTSTRSPACECORE Core;
138	/** List node for enumeration. */
139	RTLISTNODE ListEntry;
140	/** The key.
141	* @remarks Core.pszString points to the value of this object. So, consider it const. */
142	RTCString strKey;
143	/** The value. */
144	RTCRestObjectBase *pValue;
145	} MapEntry;
146	/** The map tree. */
147	RTSTRSPACE m_Map;
148	/** The enumeration list head (MapEntry). */
149	RTLISTANCHOR m_ListHead;
150	/** Number of map entries. */
151	size_t m_cEntries;
152
153	public:
154	/** @name Map Iteration
155	* @{ */
156	/** Const iterator. */
157	class ConstIterator
158	{
159	private:
160	MapEntry *m_pCur;
161	ConstIterator();
162	protected:
163	ConstIterator(MapEntry *a_pEntry) : m_pCur(a_pEntry) { }
164	public:
165	ConstIterator(ConstIterator const &a_rThat) : m_pCur(a_rThat.m_pCur) { }
166
167	/** Gets the key string. */
168	inline RTCString const &getKey() { return m_pCur->strKey; }
169	/** Gets poitner to the value object. */
170	inline RTCRestObjectBase const *getValue() { return m_pCur->pValue; }
171
172	/** Advance to the next map entry. */
173	inline ConstIterator &operator++()
174	{
175	m_pCur = RTListNodeGetNextCpp(&m_pCur->ListEntry, MapEntry, ListEntry);
176	return *this;
177	}
178
179	/** Advance to the previous map entry. */
180	inline ConstIterator &operator--()
181	{
182	m_pCur = RTListNodeGetPrevCpp(&m_pCur->ListEntry, MapEntry, ListEntry);
183	return *this;
184	}
185
186	/** Compare equal. */
187	inline bool operator==(ConstIterator const &a_rThat) { return m_pCur == a_rThat.m_pCur; }
188	/** Compare not equal. */
189	inline bool operator!=(ConstIterator const &a_rThat) { return m_pCur != a_rThat.m_pCur; }
190
191	/* Map class must be friend so it can use the MapEntry constructor. */
192	friend class RTCRestStringMapBase;
193	};
194
195	/** Returns iterator for the first map entry (unless it's empty and it's also the end). */
196	inline ConstIterator begin() const
197	{
198	if (!RTListIsEmpty(&m_ListHead))
199	return ConstIterator(RTListNodeGetNextCpp(&m_ListHead, MapEntry, ListEntry));
200	return end();
201	}
202	/** Returns iterator for the last map entry (unless it's empty and it's also the end). */
203	inline ConstIterator last() const
204	{
205	if (!RTListIsEmpty(&m_ListHead))
206	return ConstIterator(RTListNodeGetPrevCpp(&m_ListHead, MapEntry, ListEntry));
207	return end();
208	}
209	/** Returns the end iterator. This does not ever refer to an actual map entry. */
210	inline ConstIterator end() const
211	{
212	return ConstIterator(RT_FROM_CPP_MEMBER(&m_ListHead, MapEntry, ListEntry));
213	}
214	/** @} */
215
216
217	protected:
218	/**
219	* Helper for creating a clone.
220	*
221	* @returns Pointer to new map object on success, NULL if out of memory.
222	*/
223	virtual RTCRestStringMapBase *createClone(void) const = 0;
224
225	/**
226	* Wrapper around the value constructor.
227	*
228	* @returns Pointer to new value object on success, NULL if out of memory.
229	*/
230	virtual RTCRestObjectBase *createValue(void) = 0;
231
232	/**
233	* For accessing the static deserializeInstanceFromJson() method of the value.
234	*/
235	virtual int deserializeValueInstanceFromJson(RTCRestJsonCursor const &a_rCursor, RTCRestObjectBase **a_ppInstance) = 0;
236
237	/**
238	* Worker for the copy constructor and the assignment operator.
239	*
240	* This will use createEntryCopy to do the copying.
241	*
242	* @returns VINF_SUCCESS on success, VERR_NO_MEMORY or VERR_NO_STR_MEMORY on failure.
243	* @param a_rThat The map to copy. Caller makes 100% sure the it has
244	* the same type as the destination.
245	* @param a_fThrow Whether to throw error.
246	*/
247	int copyMapWorker(RTCRestStringMapBase const &a_rThat, bool a_fThrow);
248
249	/**
250	* Worker for performing inserts.
251	*
252	* @returns VINF_SUCCESS or VWRN_ALREADY_EXISTS on success.
253	* VERR_ALREADY_EXISTS, VERR_NO_MEMORY or VERR_NO_STR_MEMORY on failure.
254	* @param a_pszKey The key.
255	* @param a_pValue The value to insert. Ownership is transferred to the map on success.
256	* @param a_fReplace Whether to replace existing key-value pair with matching key.
257	* @param a_cchKey The key length, the whole string by default.
258	*/
259	int putWorker(const char a_pszKey, RTCRestObjectBase a_pValue, bool a_fReplace, size_t a_cchKey = RTSTR_MAX);
260
261	/**
262	* Worker for performing inserts.
263	*
264	* @returns VINF_SUCCESS or VWRN_ALREADY_EXISTS on success.
265	* VERR_ALREADY_EXISTS, VERR_NO_MEMORY or VERR_NO_STR_MEMORY on failure.
266	* @param a_pszKey The key.
267	* @param a_rValue The value to copy into the map.
268	* @param a_fReplace Whether to replace existing key-value pair with matching key.
269	* @param a_cchKey The key length, the whole string by default.
270	*/
271	int putCopyWorker(const char *a_pszKey, RTCRestObjectBase const &a_rValue, bool a_fReplace, size_t a_cchKey = RTSTR_MAX);
272
273	/**
274	* Worker for getting the value corresponding to the given key.
275	*
276	* @returns Pointer to the value object if found, NULL if key not in the map.
277	* @param a_pszKey The key which value to look up.
278	*/
279	RTCRestObjectBase getWorker(const char a_pszKey);
280
281	/**
282	* Worker for getting the value corresponding to the given key, const variant.
283	*
284	* @returns Pointer to the value object if found, NULL if key not in the map.
285	* @param a_pszKey The key which value to look up.
286	*/
287	RTCRestObjectBase const getWorker(const char a_pszKey) const;
288
289	private:
290	static DECLCALLBACK(int) stringSpaceDestructorCallback(PRTSTRSPACECORE pStr, void *pvUser);
291	};
292
293
294	/**
295	* Limited map class.
296	*/
297	template<class ValueType> class RTCRestStringMap : public RTCRestStringMapBase
298	{
299	public:
300	/** Default constructor, creates emtpy map. */
301	RTCRestStringMap()
302	: RTCRestStringMapBase()
303	{}
304
305	/** Copy constructor. */
306	RTCRestStringMap(RTCRestStringMap const &a_rThat)
307	: RTCRestStringMapBase()
308	{
309	copyMapWorker(a_rThat, true /a_fThrow/);
310	}
311
312	/** Destructor. */
313	virtual ~RTCRestStringMap()
314	{
315	/* nothing to do here. */
316	}
317
318	/** Copy assignment operator. */
319	RTCRestStringMap &operator=(RTCRestStringMap const &a_rThat)
320	{
321	copyMapWorker(a_rThat, true /a_fThrow/);
322	return *this;
323	}
324
325	/** Safe copy assignment method. */
326	int assignCopy(RTCRestStringMap const &a_rThat)
327	{
328	return copyMapWorker(a_rThat, false /a_fThrow/);
329	}
330
331	/** Make a clone of this object. */
332	inline RTCRestStringMap *clone() const
333	{
334	return (RTCRestStringMap *)baseClone();
335	}
336
337	/** Factory method. */
338	static DECLCALLBACK(RTCRestObjectBase *) createInstance(void)
339	{
340	return new (std::nothrow) RTCRestStringMap<ValueType>();
341	}
342
343	/** Factory method for values. */
344	static DECLCALLBACK(RTCRestObjectBase *) createValueInstance(void)
345	{
346	return new (std::nothrow) ValueType();
347	}
348
349	/** @copydoc RTCRestObjectBase::FNDESERIALIZEINSTANCEFROMJSON */
350	static DECLCALLBACK(int) deserializeInstanceFromJson(RTCRestJsonCursor const &a_rCursor, RTCRestObjectBase **a_ppInstance)
351	{
352	*a_ppInstance = new (std::nothrow) RTCRestStringMap<ValueType>();
353	if (*a_ppInstance)
354	return (*a_ppInstance)->deserializeFromJson(a_rCursor);
355	return a_rCursor.m_pPrimary->addError(a_rCursor, VERR_NO_MEMORY, "Out of memory");
356	}
357
358	/**
359	* Inserts the given object into the map.
360	*
361	* @returns VINF_SUCCESS or VWRN_ALREADY_EXISTS on success.
362	* VERR_ALREADY_EXISTS, VERR_NO_MEMORY or VERR_NO_STR_MEMORY on failure.
363	* @param a_pszKey The key.
364	* @param a_pValue The value to insert. Ownership is transferred to the map on success.
365	* @param a_fReplace Whether to replace existing key-value pair with matching key.
366	*/
367	inline int put(const char a_pszKey, ValueType a_pValue, bool a_fReplace = false)
368	{
369	return putWorker(a_pszKey, a_pValue, a_fReplace);
370	}
371
372	/**
373	* Inserts the given object into the map.
374	*
375	* @returns VINF_SUCCESS or VWRN_ALREADY_EXISTS on success.
376	* VERR_ALREADY_EXISTS, VERR_NO_MEMORY or VERR_NO_STR_MEMORY on failure.
377	* @param a_rStrKey The key.
378	* @param a_pValue The value to insert. Ownership is transferred to the map on success.
379	* @param a_fReplace Whether to replace existing key-value pair with matching key.
380	*/
381	inline int put(RTCString const &a_rStrKey, ValueType *a_pValue, bool a_fReplace = false)
382	{
383	return putWorker(a_rStrKey.c_str(), a_pValue, a_fReplace, a_rStrKey.length());
384	}
385
386	/**
387	* Inserts a copy of the given object into the map.
388	*
389	* @returns VINF_SUCCESS or VWRN_ALREADY_EXISTS on success.
390	* VERR_ALREADY_EXISTS, VERR_NO_MEMORY or VERR_NO_STR_MEMORY on failure.
391	* @param a_pszKey The key.
392	* @param a_rValue The value to insert a copy of.
393	* @param a_fReplace Whether to replace existing key-value pair with matching key.
394	*/
395	inline int putCopy(const char *a_pszKey, const ValueType &a_rValue, bool a_fReplace = false)
396	{
397	return putCopyWorker(a_pszKey, a_rValue, a_fReplace);
398	}
399
400	/**
401	* Inserts a copy of the given object into the map.
402	*
403	* @returns VINF_SUCCESS or VWRN_ALREADY_EXISTS on success.
404	* VERR_ALREADY_EXISTS, VERR_NO_MEMORY or VERR_NO_STR_MEMORY on failure.
405	* @param a_rStrKey The key.
406	* @param a_rValue The value to insert a copy of.
407	* @param a_fReplace Whether to replace existing key-value pair with matching key.
408	*/
409	inline int putCopy(RTCString const &a_rStrKey, const ValueType &a_rValue, bool a_fReplace = false)
410	{
411	return putCopyWorker(a_rStrKey.c_str(), a_rValue, a_fReplace, a_rStrKey.length());
412	}
413
414	/**
415	* Gets the value corresponding to the given key.
416	*
417	* @returns Pointer to the value object if found, NULL if key not in the map.
418	* @param a_pszKey The key which value to look up.
419	*/
420	inline ValueType get(const char a_pszKey)
421	{
422	return (ValueType *)getWorker(a_pszKey);
423	}
424
425	/**
426	* Gets the value corresponding to the given key.
427	*
428	* @returns Pointer to the value object if found, NULL if key not in the map.
429	* @param a_rStrKey The key which value to look up.
430	*/
431	inline ValueType *get(RTCString const &a_rStrKey)
432	{
433	return (ValueType *)getWorker(a_rStrKey.c_str());
434	}
435
436	/**
437	* Gets the const value corresponding to the given key.
438	*
439	* @returns Pointer to the value object if found, NULL if key not in the map.
440	* @param a_pszKey The key which value to look up.
441	*/
442	inline ValueType const get(const char a_pszKey) const
443	{
444	return (ValueType const *)getWorker(a_pszKey);
445	}
446
447	/**
448	* Gets the const value corresponding to the given key.
449	*
450	* @returns Pointer to the value object if found, NULL if key not in the map.
451	* @param a_rStrKey The key which value to look up.
452	*/
453	inline ValueType const *get(RTCString const &a_rStrKey) const
454	{
455	return (ValueType const *)getWorker(a_rStrKey.c_str());
456	}
457
458	/** @todo enumerator*/
459
460	protected:
461	virtual RTCRestStringMapBase *createClone(void) const RT_OVERRIDE
462	{
463	return new (std::nothrow) RTCRestStringMap();
464	}
465
466	virtual RTCRestObjectBase *createValue(void) RT_OVERRIDE
467	{
468	return new (std::nothrow) ValueType();
469	}
470
471	virtual int deserializeValueInstanceFromJson(RTCRestJsonCursor const &a_rCursor, RTCRestObjectBase **a_ppInstance) RT_OVERRIDE
472	{
473	return ValueType::deserializeInstanceFromJson(a_rCursor, a_ppInstance);
474	}
475	};
476
477
478	/** @} */
479
480	#endif
481

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/include/iprt/cpp/reststringmap.h@ 74410

Download in other formats: