OpenShot Library | OpenShotAudio  0.2.2
juce_NamedValueSet.h
1 
2 /** @weakgroup juce_core-containers
3  * @{
4  */
5 /*
6  ==============================================================================
7 
8  This file is part of the JUCE library.
9  Copyright (c) 2017 - ROLI Ltd.
10 
11  JUCE is an open source library subject to commercial or open-source
12  licensing.
13 
14  The code included in this file is provided under the terms of the ISC license
15  http://www.isc.org/downloads/software-support-policy/isc-license. Permission
16  To use, copy, modify, and/or distribute this software for any purpose with or
17  without fee is hereby granted provided that the above copyright notice and
18  this permission notice appear in all copies.
19 
20  JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
21  EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
22  DISCLAIMED.
23 
24  ==============================================================================
25 */
26 
27 namespace juce
28 {
29 
30 //==============================================================================
31 /** Holds a set of named var objects.
32 
33  This can be used as a basic structure to hold a set of var object, which can
34  be retrieved by using their identifier.
35 
36  @tags{Core}
37 */
39 {
40 public:
41  //==============================================================================
42  /** Structure for a named var object */
44  {
45  NamedValue() noexcept;
46  ~NamedValue() noexcept;
47 
48  NamedValue (const Identifier& name, const var& value);
49  NamedValue (const Identifier& name, var&& value) noexcept;
50  NamedValue (Identifier&& name, var&& value) noexcept;
51 
52  NamedValue (const NamedValue&);
53  NamedValue (NamedValue&&) noexcept;
54  NamedValue& operator= (NamedValue&&) noexcept;
55 
56  bool operator== (const NamedValue&) const noexcept;
57  bool operator!= (const NamedValue&) const noexcept;
58 
59  Identifier name;
60  var value;
61  };
62 
63  //==============================================================================
64  /** Creates an empty set. */
65  NamedValueSet() noexcept;
66 
68  NamedValueSet (NamedValueSet&&) noexcept;
69  NamedValueSet& operator= (const NamedValueSet&);
70  NamedValueSet& operator= (NamedValueSet&&) noexcept;
71 
72  /** Creates a NamedValueSet from a list of names and properties. */
73  NamedValueSet (std::initializer_list<NamedValue>);
74 
75  /** Destructor. */
76  ~NamedValueSet() noexcept;
77 
78  /** Two NamedValueSets are considered equal if they contain all the same key/value
79  pairs, regardless of the order.
80  */
81  bool operator== (const NamedValueSet&) const noexcept;
82  bool operator!= (const NamedValueSet&) const noexcept;
83 
84  const NamedValueSet::NamedValue* begin() const noexcept { return values.begin(); }
85  const NamedValueSet::NamedValue* end() const noexcept { return values.end(); }
86 
87  //==============================================================================
88  /** Returns the total number of values that the set contains. */
89  int size() const noexcept;
90 
91  /** Returns true if the set is empty. */
92  bool isEmpty() const noexcept;
93 
94  /** Returns the value of a named item.
95  If the name isn't found, this will return a void variant.
96  */
97  const var& operator[] (const Identifier& name) const noexcept;
98 
99  /** Tries to return the named value, but if no such value is found, this will
100  instead return the supplied default value.
101  */
102  var getWithDefault (const Identifier& name, const var& defaultReturnValue) const;
103 
104  /** Changes or adds a named value.
105  @returns true if a value was changed or added; false if the
106  value was already set the value passed-in.
107  */
108  bool set (const Identifier& name, const var& newValue);
109 
110  /** Changes or adds a named value.
111  @returns true if a value was changed or added; false if the
112  value was already set the value passed-in.
113  */
114  bool set (const Identifier& name, var&& newValue);
115 
116  /** Returns true if the set contains an item with the specified name. */
117  bool contains (const Identifier& name) const noexcept;
118 
119  /** Removes a value from the set.
120  @returns true if a value was removed; false if there was no value
121  with the name that was given.
122  */
123  bool remove (const Identifier& name);
124 
125  /** Returns the name of the value at a given index.
126  The index must be between 0 and size() - 1.
127  */
128  Identifier getName (int index) const noexcept;
129 
130  /** Returns a pointer to the var that holds a named value, or null if there is
131  no value with this name.
132 
133  Do not use this method unless you really need access to the internal var object
134  for some reason - for normal reading and writing always prefer operator[]() and set().
135  Also note that the pointer returned may become invalid as soon as any subsequent
136  methods are called on the NamedValueSet.
137  */
138  var* getVarPointer (const Identifier& name) noexcept;
139 
140  /** Returns a pointer to the var that holds a named value, or null if there is
141  no value with this name.
142 
143  Do not use this method unless you really need access to the internal var object
144  for some reason - for normal reading and writing always prefer operator[]() and set().
145  Also note that the pointer returned may become invalid as soon as any subsequent
146  methods are called on the NamedValueSet.
147  */
148  const var* getVarPointer (const Identifier& name) const noexcept;
149 
150  /** Returns the value of the item at a given index.
151  The index must be between 0 and size() - 1.
152  */
153  const var& getValueAt (int index) const noexcept;
154 
155  /** Returns the value of the item at a given index.
156  The index must be between 0 and size() - 1, or this will return a nullptr
157  Also note that the pointer returned may become invalid as soon as any subsequent
158  methods are called on the NamedValueSet.
159  */
160  var* getVarPointerAt (int index) noexcept;
161 
162  /** Returns the value of the item at a given index.
163  The index must be between 0 and size() - 1, or this will return a nullptr
164  Also note that the pointer returned may become invalid as soon as any subsequent
165  methods are called on the NamedValueSet.
166  */
167  const var* getVarPointerAt (int index) const noexcept;
168 
169  /** Returns the index of the given name, or -1 if it's not found. */
170  int indexOf (const Identifier& name) const noexcept;
171 
172  /** Removes all values. */
173  void clear();
174 
175  //==============================================================================
176  /** Sets properties to the values of all of an XML element's attributes. */
177  void setFromXmlAttributes (const XmlElement& xml);
178 
179  /** Sets attributes in an XML element corresponding to each of this object's
180  properties.
181  */
182  void copyToXmlAttributes (XmlElement& xml) const;
183 
184 private:
185  //==============================================================================
186  Array<NamedValue> values;
187 };
188 
189 } // namespace juce
190 
191 /** @}*/
#define JUCE_API
This macro is added to all JUCE public class declarations.
Structure for a named var object.
Represents a string identifier, designed for accessing properties by name.
A variant class, that can be used to hold a range of primitive values.
Definition: juce_Variant.h:45
Used to build a tree of elements representing an XML document.
Holds a set of named var objects.
Holds a resizable array of primitive or copy-by-value objects.
Definition: juce_Array.h:59