1 // Generated by gmmproc 2.64.2 -- DO NOT MODIFY!
2 #ifndef _GLIBMM_VARIANTTYPE_H
3 #define _GLIBMM_VARIANTTYPE_H
4
5
6 /* Copyright 2010 The glibmm Development Team
7 *
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Lesser General Public
10 * License as published by the Free Software Foundation; either
11 * version 2.1 of the License, or (at your option) any later version.
12 *
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Lesser General Public License for more details.
17 *
18 * You should have received a copy of the GNU Lesser General Public
19 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
20 */
21
22
23 #include <glibmmconfig.h>
24 #include <glib-object.h> //For gsize
25 #include <glibmm/value.h>
26 #include <string>
27 #include <vector>
28
29 #ifndef DOXYGEN_SHOULD_SKIP_THIS
30 typedef struct _GVariantType GVariantType;
31 #endif //DOXYGEN_SHOULD_SKIP_THIS
32
33 namespace Glib
34 {
35
36 /** VariantType - The VariantBase type system.
37 * The VariantBase type system is based, in large part, on the D-Bus type
38 * system, with two major changes and some minor lifting of restrictions. <a
39 * href="http://dbus.freedesktop.org/doc/dbus-specification.html">The
40 * D-Bus specification</a>, therefore, provides a significant amount of
41 * information that is useful when working with VariantBase.
42 *
43 * The first major change with respect to the D-Bus type system is the
44 * introduction of maybe (or "nullable") types. Any type in VariantBase
45 * can be converted to a maybe type, in which case, "nothing" (or "null")
46 * becomes a valid value. Maybe types have been added by introducing the
47 * character "m" to type strings.
48 *
49 * The second major change is that the VariantBase type system supports
50 * the concept of "indefinite types" -- types that are less specific than the
51 * normal types found in D-Bus. For example, it is possible to speak of "an
52 * array of any type" in VariantBase, where the D-Bus type system would
53 * require you to speak of "an array of integers" or "an array of strings".
54 * Indefinite types have been added by introducing the characters "*", "?" and
55 * "r" to type strings.
56 *
57 * Finally, all arbitrary restrictions relating to the complexity of types are
58 * lifted along with the restriction that dictionary entries may only appear
59 * nested inside of arrays.
60 *
61 * Just as in D-Bus, VariantBase types are described with strings ("type
62 * strings"). Subject to the differences mentioned above, these strings are of
63 * the same form as those found in D-Bus. Note, however: D-Bus always works in
64 * terms of messages and therefore individual type strings appear nowhere in
65 * its interface. Instead, "signatures" are a concatenation of the strings of
66 * the type of each argument in a message. VariantBase deals with single
67 * values directly so VariantBase type strings always describe the type
68 * of exactly one value. This means that a D-Bus signature string is generally
69 * not a valid VariantBase type string -- except in the case that it is
70 * the signature of a message containing exactly one argument.
71 *
72 * An indefinite type is similar in spirit to what may be called an abstract
73 * type in other type systems. No value can exist that has an indefinite type
74 * as its type, but values can exist that have types that are subtypes of
75 * indefinite types. That is to say, VariantBase::get_type() will never
76 * return an indefinite type, but calling VariantBase::is_of_type() with
77 * an indefinite type may return <tt>true</tt>. For example, you cannot have a
78 * value that represents "an array of no particular type", but you can have an
79 * "array of integers" which certainly matches the type of "an array of no
80 * particular type", since "array of integers" is a subtype of "array of no
81 * particular type".
82 *
83 * This is similar to how instances of abstract classes may not directly exist
84 * in other type systems, but instances of their non-abstract subtypes may. For
85 * example, in gtkmm, no object that has the type of Gtk::Bin can exist (since
86 * Gtk::Bin is an abstract class), but a Gtk::Window can certainly be
87 * instantiated, and you would say that the Gtk::Window is a Gtk::Bin (since
88 * Gtk::Window is a subclass of Gtk::Bin).
89 *
90 * See the underlying GVariantType documentation for <a href="http://library.gnome.org/devel/glib/unstable/glib-GVariantType.html#gvariant-typestrings">detailed description of the VariantBase type strings</a>.
91 *
92 * @newin{2,28}
93 * @ingroup Variant
94 */
95 class GLIBMM_API VariantType
96 {
97 public:
98 #ifndef DOXYGEN_SHOULD_SKIP_THIS
99 using CppObjectType = VariantType;
100 using BaseObjectType = GVariantType;
101 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
102
103 /** Constructs an invalid object.
104 * E.g. for output arguments to methods. There is not much you can do with
105 * the object before it has been assigned a valid value.
106 */
107 VariantType();
108
109 // Use make_a_copy=true when getting it directly from a struct.
110 explicit VariantType(GVariantType* castitem, bool make_a_copy = false);
111
112 VariantType(const VariantType& src);
113 VariantType& operator=(const VariantType& src);
114
115 VariantType(VariantType&& other) noexcept;
116 VariantType& operator=(VariantType&& other) noexcept;
117
118 ~VariantType() noexcept;
119
120 void swap(VariantType& other) noexcept;
121
gobj()122 GVariantType* gobj() { return gobject_; }
gobj()123 const GVariantType* gobj() const { return gobject_; }
124
125 ///Provides access to the underlying C instance. The caller is responsible for freeing it. Use when directly setting fields in structs.
126 GVariantType* gobj_copy() const;
127
128 protected:
129 GVariantType* gobject_;
130
131 private:
132
133
134 public:
135
136 /** Copy the C item into a new VariantType instance.
137 */
138 explicit VariantType(const GVariantType* castitem);
139
140 /** Creates a new VariantType corresponding to the type string given by @a type_string.
141 *
142 * It is a programmer error to call this function with an invalid type string. Use string_is_valid() if you are unsure.
143 */
144 explicit VariantType(const std::string& type_string);
145
146
147 VariantType& operator=(const GVariantType* castitem);
148
149
150 //The C parameters are actually const, but gmmproc doesn't understand that,
151 //so we add a m4 conversion to satisfy it:
152
153
154 /** Constructs the type corresponding to an array of elements of the
155 * type @a type.
156 *
157 * It is appropriate to call g_variant_type_free() on the return value.
158 *
159 * @newin{2,24}
160 *
161 * @param element A VariantType.
162 * @return A new array VariantType.
163 */
164 static VariantType create_array(const VariantType& element);
165
166 /** Constructs the type corresponding to a maybe instance containing
167 * type @a type or Nothing.
168 *
169 * It is appropriate to call g_variant_type_free() on the return value.
170 *
171 * @newin{2,24}
172 *
173 * @param element A VariantType.
174 * @return A new maybe VariantType.
175 */
176 static VariantType create_maybe(const VariantType& element);
177
178 /** Constructs a new tuple type, from @a items.
179 *
180 * @param items A vector of VariantTypes, one for each item.
181 * @return A new tuple VariantType.
182 *
183 * @newin{2,36}
184 */
185 static VariantType create_tuple(const std::vector<VariantType>& items);
186
187
188 /** Constructs the type corresponding to a dictionary entry with a key
189 * of type @a key and a value of type @a value.
190 *
191 * It is appropriate to call g_variant_type_free() on the return value.
192 *
193 * @newin{2,24}
194 *
195 * @param key A basic VariantType.
196 * @param value A VariantType.
197 * @return A new dictionary entry VariantType.
198 */
199 static VariantType create_dict_entry(const VariantType& key, const VariantType& value);
200
201 //TODO: Use something instead of gsize?
202
203 /** Returns the length of the type string corresponding to the given
204 * @a type. This function must be used to determine the valid extent of
205 * the memory region returned by g_variant_type_peek_string().
206 *
207 * @newin{2,24}
208 *
209 * @return The length of the corresponding type string.
210 */
211 gsize _get_string_length() const;
212
213 /** Returns the type string corresponding to the given @a type. The
214 * result is not nul-terminated; in order to determine its length you
215 * must call g_variant_type_get_string_length().
216 *
217 * To get a nul-terminated string, see g_variant_type_dup_string().
218 *
219 * @newin{2,24}
220 *
221 * @return The corresponding type string (not nul-terminated).
222 */
223
224 std::string get_string() const;
225
226
227 /** Determines if the given @a type is definite (ie: not indefinite).
228 *
229 * A type is definite if its type string does not contain any indefinite
230 * type characters ('*', '?', or 'r').
231 *
232 * A Variant instance may not have an indefinite type, so calling
233 * this function on the result of g_variant_get_type() will always
234 * result in <tt>true</tt> being returned. Calling this function on an
235 * indefinite type like G_VARIANT_TYPE_ARRAY, however, will result in
236 * <tt>false</tt> being returned.
237 *
238 * @newin{2,24}
239 *
240 * @return <tt>true</tt> if @a type is definite.
241 */
242 bool is_definite() const;
243
244 /** Determines if the given @a type is a container type.
245 *
246 * Container types are any array, maybe, tuple, or dictionary
247 * entry types plus the variant type.
248 *
249 * This function returns <tt>true</tt> for any indefinite type for which every
250 * definite subtype is a container -- G_VARIANT_TYPE_ARRAY, for
251 * example.
252 *
253 * @newin{2,24}
254 *
255 * @return <tt>true</tt> if @a type is a container type.
256 */
257 bool is_container() const;
258
259 /** Determines if the given @a type is a basic type.
260 *
261 * Basic types are booleans, bytes, integers, doubles, strings, object
262 * paths and signatures.
263 *
264 * Only a basic type may be used as the key of a dictionary entry.
265 *
266 * This function returns <tt>false</tt> for all indefinite types except
267 * G_VARIANT_TYPE_BASIC.
268 *
269 * @newin{2,24}
270 *
271 * @return <tt>true</tt> if @a type is a basic type.
272 */
273 bool is_basic() const;
274
275 /** Determines if the given @a type is a maybe type. This is true if the
276 * type string for @a type starts with an 'm'.
277 *
278 * This function returns <tt>true</tt> for any indefinite type for which every
279 * definite subtype is a maybe type -- G_VARIANT_TYPE_MAYBE, for
280 * example.
281 *
282 * @newin{2,24}
283 *
284 * @return <tt>true</tt> if @a type is a maybe type.
285 */
286 bool is_maybe() const;
287
288 /** Determines if the given @a type is an array type. This is true if the
289 * type string for @a type starts with an 'a'.
290 *
291 * This function returns <tt>true</tt> for any indefinite type for which every
292 * definite subtype is an array type -- G_VARIANT_TYPE_ARRAY, for
293 * example.
294 *
295 * @newin{2,24}
296 *
297 * @return <tt>true</tt> if @a type is an array type.
298 */
299 bool is_array() const;
300
301 /** Determines if the given @a type is a tuple type. This is true if the
302 * type string for @a type starts with a '(' or if @a type is
303 * G_VARIANT_TYPE_TUPLE.
304 *
305 * This function returns <tt>true</tt> for any indefinite type for which every
306 * definite subtype is a tuple type -- G_VARIANT_TYPE_TUPLE, for
307 * example.
308 *
309 * @newin{2,24}
310 *
311 * @return <tt>true</tt> if @a type is a tuple type.
312 */
313 bool is_tuple() const;
314
315 /** Determines if the given @a type is a dictionary entry type. This is
316 * true if the type string for @a type starts with a '{'.
317 *
318 * This function returns <tt>true</tt> for any indefinite type for which every
319 * definite subtype is a dictionary entry type --
320 * G_VARIANT_TYPE_DICT_ENTRY, for example.
321 *
322 * @newin{2,24}
323 *
324 * @return <tt>true</tt> if @a type is a dictionary entry type.
325 */
326 bool is_dict_entry() const;
327
328 /** Determines if the given @a type is the variant type.
329 *
330 * @newin{2,24}
331 *
332 * @return <tt>true</tt> if @a type is the variant type.
333 */
334 bool is_variant() const;
335
336
337 /** Hashes @a type.
338 *
339 * The argument type of @a type is only #gconstpointer to allow use with
340 * HashTable without function pointer casting. A valid
341 * VariantType must be provided.
342 *
343 * @newin{2,24}
344 *
345 * @return The hash value.
346 */
347 guint hash() const;
348
349
350 /** Compares @a *this and @a other for equality.
351 *
352 * Only returns <tt>true</tt> if the types are exactly equal. Even if one type
353 * is an indefinite type and the other is a subtype of it, <tt>false</tt> will
354 * be returned if they are not exactly equal. If you want to check for
355 * subtypes, use is_subtype_of().
356 *
357 * @param other The VariantType to compare with.
358 * @return <tt>true</tt> if @a *this and @a other are exactly equal.
359 *
360 * @newin{2,24}
361 */
362 bool equal(const VariantType& other) const;
363
364
365 /** Checks if @a type is a subtype of @a supertype.
366 *
367 * This function returns <tt>true</tt> if @a type is a subtype of @a supertype. All
368 * types are considered to be subtypes of themselves. Aside from that,
369 * only indefinite types can have subtypes.
370 *
371 * @newin{2,24}
372 *
373 * @param supertype A VariantType.
374 * @return <tt>true</tt> if @a type is a subtype of @a supertype.
375 */
376 bool is_subtype_of(const VariantType& supertype) const;
377
378 // It's necessary to take an extra reference of the 'const GVariantType*'
379 // returned by g_variant_type_element(), g_variant_type_key() and
380 // g_variant_type_value() because they don't do that already.
381
382
383 /** Determines the element type of an array or maybe type.
384 *
385 * This function may only be used with array or maybe types.
386 *
387 * @newin{2,24}
388 *
389 * @return The element type of @a type.
390 */
391 VariantType element() const;
392
393 #ifndef GLIBMM_DISABLE_DEPRECATED
394
395 /** Determines the first item type of a tuple or dictionary entry
396 * type.
397 *
398 * This function may only be used with tuple or dictionary entry types,
399 * but must not be used with the generic tuple type
400 * G_VARIANT_TYPE_TUPLE.
401 *
402 * In the case of a dictionary entry type, this returns the type of
403 * the key.
404 *
405 * <tt>nullptr</tt> is returned in case of @a type being G_VARIANT_TYPE_UNIT.
406 *
407 * This call, together with g_variant_type_next() provides an iterator
408 * interface over tuple and dictionary entry types.
409 *
410 * @newin{2,24}
411 *
412 * @deprecated Use get_item_types() instead.
413 *
414 * @return The first item type of @a type, or <tt>nullptr</tt>.
415 */
416 VariantType first() const;
417 #endif // GLIBMM_DISABLE_DEPRECATED
418
419
420 #ifndef GLIBMM_DISABLE_DEPRECATED
421
422 /** Determines the next item type of a tuple or dictionary entry
423 * type.
424 *
425 * @a type must be the result of a previous call to
426 * g_variant_type_first() or g_variant_type_next().
427 *
428 * If called on the key type of a dictionary entry then this call
429 * returns the value type. If called on the value type of a dictionary
430 * entry then this call returns <tt>nullptr</tt>.
431 *
432 * For tuples, <tt>nullptr</tt> is returned when @a type is the last item in a tuple.
433 *
434 * @newin{2,24}
435 *
436 * @deprecated Use get_item_types() instead.
437 *
438 * @return The next VariantType after @a type, or <tt>nullptr</tt>.
439 */
440 VariantType next() const;
441 #endif // GLIBMM_DISABLE_DEPRECATED
442
443
444 /** Determines the number of items contained in a tuple or
445 * dictionary entry type.
446 *
447 * This function may only be used with tuple or dictionary entry types,
448 * but must not be used with the generic tuple type
449 * G_VARIANT_TYPE_TUPLE.
450 *
451 * In the case of a dictionary entry type, this function will always
452 * return 2.
453 *
454 * @newin{2,24}
455 *
456 * @return The number of items in @a type.
457 */
458 gsize n_items() const;
459
460 /** Determines the key type of a dictionary entry type.
461 *
462 * This function may only be used with a dictionary entry type. Other
463 * than the additional restriction, this call is equivalent to
464 * g_variant_type_first().
465 *
466 * @newin{2,24}
467 *
468 * @return The key type of the dictionary entry.
469 */
470 VariantType key() const;
471
472 /** Determines the value type of a dictionary entry type.
473 *
474 * This function may only be used with a dictionary entry type.
475 *
476 * @newin{2,24}
477 *
478 * @return The value type of the dictionary entry.
479 */
480 VariantType value() const;
481
482 /** Determines the item types of a tuple or dictionary entry type.
483 *
484 * This function may only be used with tuple or dictionary entry types,
485 * but must not be used with the generic tuple type VARIANT_TYPE_TUPLE.
486 *
487 * In the case of a dictionary entry type, returns a vector with
488 * 2 elements, the type of the key followed by the value type.
489 *
490 * An empty vector is returned in case of this %VariantType being VARIANT_TYPE_UNIT.
491 *
492 * @newin{2,52}
493 *
494 * @return The item types of this %VariantType, or an empty vector.
495 */
496 std::vector<VariantType> get_item_types() const;
497
498 // This function is part of unexposed API in gvarianttypeinfo.{h,c} for an
499 // also unexposed GVariantTypeInfo structure of glib.
500
501
502 };
503
504 extern GLIBMM_API const VariantType VARIANT_TYPE_BOOL;
505
506 extern GLIBMM_API const VariantType VARIANT_TYPE_BYTE;
507
508 extern GLIBMM_API const VariantType VARIANT_TYPE_INT16;
509
510 extern GLIBMM_API const VariantType VARIANT_TYPE_UINT16;
511
512 extern GLIBMM_API const VariantType VARIANT_TYPE_INT32;
513
514 extern GLIBMM_API const VariantType VARIANT_TYPE_UINT32;
515
516 extern GLIBMM_API const VariantType VARIANT_TYPE_INT64;
517
518 extern GLIBMM_API const VariantType VARIANT_TYPE_UINT64;
519
520 extern GLIBMM_API const VariantType VARIANT_TYPE_DOUBLE;
521
522 extern GLIBMM_API const VariantType VARIANT_TYPE_STRING;
523
524 extern GLIBMM_API const VariantType VARIANT_TYPE_OBJECT_PATH;
525
526 extern GLIBMM_API const VariantType VARIANT_TYPE_SIGNATURE;
527
528 extern GLIBMM_API const VariantType VARIANT_TYPE_VARIANT;
529
530 extern GLIBMM_API const VariantType VARIANT_TYPE_HANDLE;
531
532 extern GLIBMM_API const VariantType VARIANT_TYPE_UNIT;
533
534 extern GLIBMM_API const VariantType VARIANT_TYPE_ANY;
535
536 extern GLIBMM_API const VariantType VARIANT_TYPE_BASIC;
537
538 extern GLIBMM_API const VariantType VARIANT_TYPE_MAYBE;
539
540 extern GLIBMM_API const VariantType VARIANT_TYPE_ARRAY;
541
542 extern GLIBMM_API const VariantType VARIANT_TYPE_TUPLE;
543
544 extern GLIBMM_API const VariantType VARIANT_TYPE_DICT_ENTRY;
545
546 extern GLIBMM_API const VariantType VARIANT_TYPE_DICTIONARY;
547
548 extern GLIBMM_API const VariantType VARIANT_TYPE_STRING_ARRAY;
549
550 extern GLIBMM_API const VariantType VARIANT_TYPE_OBJECT_PATH_ARRAY;
551
552 extern GLIBMM_API const VariantType VARIANT_TYPE_BYTESTRING;
553
554 extern GLIBMM_API const VariantType VARIANT_TYPE_BYTESTRING_ARRAY;
555
556 #ifndef DOXYGEN_SHOULD_SKIP_THIS
557 // This is needed so Glib::VariantType can be used with
558 // Glib::Value and _WRAP_PROPERTY in Gio::Action and elsewhere.
559 template <>
560 class GLIBMM_API Value<Glib::VariantType> : public ValueBase_Boxed
561 {
562 public:
563 using CppType = Glib::VariantType;
564 using CType = GVariantType*;
565
566 static GType value_type();
567
568 void set(const CppType& data);
569 CppType get() const;
570 };
571 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
572
573 } // namespace Glib
574
575
576 namespace Glib
577 {
578
579 /** @relates Glib::VariantType
580 * @param lhs The left-hand side
581 * @param rhs The right-hand side
582 */
swap(VariantType & lhs,VariantType & rhs)583 inline void swap(VariantType& lhs, VariantType& rhs) noexcept
584 { lhs.swap(rhs); }
585
586 } // namespace Glib
587
588 namespace Glib
589 {
590
591 /** A Glib::wrap() method for this object.
592 *
593 * @param object The C instance.
594 * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
595 * @result A C++ instance that wraps this C instance.
596 *
597 * @relates Glib::VariantType
598 */
599 GLIBMM_API
600 Glib::VariantType wrap(GVariantType* object, bool take_copy = false);
601
602 } // namespace Glib
603
604
605 #endif /* _GLIBMM_VARIANTTYPE_H */
606
607