juce/source/src/text/juce_StringPairArray.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_STRINGPAIRARRAY_JUCEHEADER__
  27 #define __JUCE_STRINGPAIRARRAY_JUCEHEADER__
  28
  29 #include "juce_StringArray.h"
  30
  31
  32 //==============================================================================
  33 /**
  34     A container for holding a set of strings which are keyed by another string.
  35
  36     @see StringArray
  37 */
  38 class JUCE_API  StringPairArray
  39 {
  40 public:
  41     //==============================================================================
  42     /** Creates an empty array */
  43     StringPairArray (bool ignoreCaseWhenComparingKeys = true);
  44
  45     /** Creates a copy of another array */
  46     StringPairArray (const StringPairArray& other);
  47
  48     /** Destructor. */
  49     ~StringPairArray();
  50
  51     /** Copies the contents of another string array into this one */
  52     StringPairArray& operator= (const StringPairArray& other);
  53
  54     //==============================================================================
  55     /** Compares two arrays.
  56
  57         Comparisons are case-sensitive.
  58
  59         @returns    true only if the other array contains exactly the same strings with the same keys
  60     */
  61     bool operator== (const StringPairArray& other) const;
  62
  63     /** Compares two arrays.
  64
  65         Comparisons are case-sensitive.
  66
  67         @returns    false if the other array contains exactly the same strings with the same keys
  68     */
  69     bool operator!= (const StringPairArray& other) const;
  70
  71     //==============================================================================
  72     /** Finds the value corresponding to a key string.
  73
  74         If no such key is found, this will just return an empty string. To check whether
  75         a given key actually exists (because it might actually be paired with an empty string), use
  76         the getAllKeys() method to obtain a list.
  77
  78         Obviously the reference returned shouldn't be stored for later use, as the
  79         string it refers to may disappear when the array changes.
  80
  81         @see getValue
  82     */
  83     const String& operator[] (const String& key) const;
  84
  85     /** Finds the value corresponding to a key string.
  86
  87         If no such key is found, this will just return the value provided as a default.
  88
  89         @see operator[]
  90     */
  91     String getValue (const String& key, const String& defaultReturnValue) const;
  92
  93
  94     /** Returns a list of all keys in the array. */
  95     const StringArray& getAllKeys() const noexcept          { return keys; }
  96
  97     /** Returns a list of all values in the array. */
  98     const StringArray& getAllValues() const noexcept        { return values; }
  99
 100     /** Returns the number of strings in the array */
 101     inline int size() const noexcept                        { return keys.size(); };
 102
 103
 104     //==============================================================================
 105     /** Adds or amends a key/value pair.
 106
 107         If a value already exists with this key, its value will be overwritten,
 108         otherwise the key/value pair will be added to the array.
 109     */
 110     void set (const String& key, const String& value);
 111
 112     /** Adds the items from another array to this one.
 113
 114         This is equivalent to using set() to add each of the pairs from the other array.
 115     */
 116     void addArray (const StringPairArray& other);
 117
 118     //==============================================================================
 119     /** Removes all elements from the array. */
 120     void clear();
 121
 122     /** Removes a string from the array based on its key.
 123
 124         If the key isn't found, nothing will happen.
 125     */
 126     void remove (const String& key);
 127
 128     /** Removes a string from the array based on its index.
 129
 130         If the index is out-of-range, no action will be taken.
 131     */
 132     void remove (int index);
 133
 134     //==============================================================================
 135     /** Indicates whether to use a case-insensitive search when looking up a key string.
 136     */
 137     void setIgnoresCase (bool shouldIgnoreCase);
 138
 139     //==============================================================================
 140     /** Returns a descriptive string containing the items.
 141         This is handy for dumping the contents of an array.
 142     */
 143     String getDescription() const;
 144
 145     //==============================================================================
 146     /** Reduces the amount of storage being used by the array.
 147
 148         Arrays typically allocate slightly more storage than they need, and after
 149         removing elements, they may have quite a lot of unused space allocated.
 150         This method will reduce the amount of allocated storage to a minimum.
 151     */
 152     void minimiseStorageOverheads();
 153
 154
 155 private:
 156     //==============================================================================
 157     StringArray keys, values;
 158     bool ignoreCase;
 159
 160     JUCE_LEAK_DETECTOR (StringPairArray);
 161 };
 162
 163
 164 #endif   // __JUCE_STRINGPAIRARRAY_JUCEHEADER__