juce/source/src/text/juce_StringArray.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_STRINGARRAY_JUCEHEADER__
  27 #define __JUCE_STRINGARRAY_JUCEHEADER__
  28
  29 #include "juce_String.h"
  30 #include "../containers/juce_Array.h"
  31
  32
  33 //==============================================================================
  34 /**
  35     A special array for holding a list of strings.
  36
  37     @see String, StringPairArray
  38 */
  39 class JUCE_API  StringArray
  40 {
  41 public:
  42     //==============================================================================
  43     /** Creates an empty string array */
  44     StringArray() noexcept;
  45
  46     /** Creates a copy of another string array */
  47     StringArray (const StringArray& other);
  48
  49     /** Creates an array containing a single string. */
  50     explicit StringArray (const String& firstValue);
  51
  52     /** Creates a copy of an array of string literals.
  53         @param strings          an array of strings to add. Null pointers in the array will be
  54                                 treated as empty strings
  55         @param numberOfStrings  how many items there are in the array
  56     */
  57     StringArray (const char* const* strings, int numberOfStrings);
  58
  59     /** Creates a copy of a null-terminated array of string literals.
  60
  61         Each item from the array passed-in is added, until it encounters a null pointer,
  62         at which point it stops.
  63     */
  64     explicit StringArray (const char* const* strings);
  65
  66     /** Creates a copy of a null-terminated array of string literals.
  67         Each item from the array passed-in is added, until it encounters a null pointer,
  68         at which point it stops.
  69     */
  70     explicit StringArray (const wchar_t* const* strings);
  71
  72     /** Creates a copy of an array of string literals.
  73         @param strings          an array of strings to add. Null pointers in the array will be
  74                                 treated as empty strings
  75         @param numberOfStrings  how many items there are in the array
  76     */
  77     StringArray (const wchar_t* const* strings, int numberOfStrings);
  78
  79     /** Destructor. */
  80     ~StringArray();
  81
  82     /** Copies the contents of another string array into this one */
  83     StringArray& operator= (const StringArray& other);
  84
  85     //==============================================================================
  86     /** Compares two arrays.
  87         Comparisons are case-sensitive.
  88         @returns    true only if the other array contains exactly the same strings in the same order
  89     */
  90     bool operator== (const StringArray& other) const noexcept;
  91
  92     /** Compares two arrays.
  93         Comparisons are case-sensitive.
  94         @returns    false if the other array contains exactly the same strings in the same order
  95     */
  96     bool operator!= (const StringArray& other) const noexcept;
  97
  98     //==============================================================================
  99     /** Returns the number of strings in the array */
 100     inline int size() const noexcept                                    { return strings.size(); };
 101
 102     /** Returns one of the strings from the array.
 103
 104         If the index is out-of-range, an empty string is returned.
 105
 106         Obviously the reference returned shouldn't be stored for later use, as the
 107         string it refers to may disappear when the array changes.
 108     */
 109     const String& operator[] (int index) const noexcept;
 110
 111     /** Returns a reference to one of the strings in the array.
 112         This lets you modify a string in-place in the array, but you must be sure that
 113         the index is in-range.
 114     */
 115     String& getReference (int index) noexcept;
 116
 117     /** Searches for a string in the array.
 118
 119         The comparison will be case-insensitive if the ignoreCase parameter is true.
 120
 121         @returns    true if the string is found inside the array
 122     */
 123     bool contains (const String& stringToLookFor,
 124                    bool ignoreCase = false) const;
 125
 126     /** Searches for a string in the array.
 127
 128         The comparison will be case-insensitive if the ignoreCase parameter is true.
 129
 130         @param stringToLookFor  the string to try to find
 131         @param ignoreCase       whether the comparison should be case-insensitive
 132         @param startIndex       the first index to start searching from
 133         @returns                the index of the first occurrence of the string in this array,
 134                                 or -1 if it isn't found.
 135     */
 136     int indexOf (const String& stringToLookFor,
 137                  bool ignoreCase = false,
 138                  int startIndex = 0) const;
 139
 140     //==============================================================================
 141     /** Appends a string at the end of the array. */
 142     void add (const String& stringToAdd);
 143
 144     /** Inserts a string into the array.
 145
 146         This will insert a string into the array at the given index, moving
 147         up the other elements to make room for it.
 148         If the index is less than zero or greater than the size of the array,
 149         the new string will be added to the end of the array.
 150     */
 151     void insert (int index, const String& stringToAdd);
 152
 153     /** Adds a string to the array as long as it's not already in there.
 154
 155         The search can optionally be case-insensitive.
 156     */
 157     void addIfNotAlreadyThere (const String& stringToAdd, bool ignoreCase = false);
 158
 159     /** Replaces one of the strings in the array with another one.
 160
 161         If the index is higher than the array's size, the new string will be
 162         added to the end of the array; if it's less than zero nothing happens.
 163     */
 164     void set (int index, const String& newString);
 165
 166     /** Appends some strings from another array to the end of this one.
 167
 168         @param other                the array to add
 169         @param startIndex           the first element of the other array to add
 170         @param numElementsToAdd     the maximum number of elements to add (if this is
 171                                     less than zero, they are all added)
 172     */
 173     void addArray (const StringArray& other,
 174                    int startIndex = 0,
 175                    int numElementsToAdd = -1);
 176
 177     /** Breaks up a string into tokens and adds them to this array.
 178
 179         This will tokenise the given string using whitespace characters as the
 180         token delimiters, and will add these tokens to the end of the array.
 181
 182         @returns    the number of tokens added
 183     */
 184     int addTokens (const String& stringToTokenise,
 185                    bool preserveQuotedStrings);
 186
 187     /** Breaks up a string into tokens and adds them to this array.
 188
 189         This will tokenise the given string (using the string passed in to define the
 190         token delimiters), and will add these tokens to the end of the array.
 191
 192         @param stringToTokenise     the string to tokenise
 193         @param breakCharacters      a string of characters, any of which will be considered
 194                                     to be a token delimiter.
 195         @param quoteCharacters      if this string isn't empty, it defines a set of characters
 196                                     which are treated as quotes. Any text occurring
 197                                     between quotes is not broken up into tokens.
 198         @returns    the number of tokens added
 199     */
 200     int addTokens (const String& stringToTokenise,
 201                    const String& breakCharacters,
 202                    const String& quoteCharacters);
 203
 204     /** Breaks up a string into lines and adds them to this array.
 205
 206         This breaks a string down into lines separated by \\n or \\r\\n, and adds each line
 207         to the array. Line-break characters are omitted from the strings that are added to
 208         the array.
 209     */
 210     int addLines (const String& stringToBreakUp);
 211
 212     //==============================================================================
 213     /** Removes all elements from the array. */
 214     void clear();
 215
 216     /** Removes a string from the array.
 217
 218         If the index is out-of-range, no action will be taken.
 219     */
 220     void remove (int index);
 221
 222     /** Finds a string in the array and removes it.
 223
 224         This will remove the first occurrence of the given string from the array. The
 225         comparison may be case-insensitive depending on the ignoreCase parameter.
 226     */
 227     void removeString (const String& stringToRemove,
 228                        bool ignoreCase = false);
 229
 230     /** Removes a range of elements from the array.
 231
 232         This will remove a set of elements, starting from the given index,
 233         and move subsequent elements down to close the gap.
 234
 235         If the range extends beyond the bounds of the array, it will
 236         be safely clipped to the size of the array.
 237
 238         @param startIndex       the index of the first element to remove
 239         @param numberToRemove   how many elements should be removed
 240     */
 241     void removeRange (int startIndex, int numberToRemove);
 242
 243     /** Removes any duplicated elements from the array.
 244
 245         If any string appears in the array more than once, only the first occurrence of
 246         it will be retained.
 247
 248         @param ignoreCase   whether to use a case-insensitive comparison
 249     */
 250     void removeDuplicates (bool ignoreCase);
 251
 252     /** Removes empty strings from the array.
 253
 254         @param removeWhitespaceStrings  if true, strings that only contain whitespace
 255                                         characters will also be removed
 256     */
 257     void removeEmptyStrings (bool removeWhitespaceStrings = true);
 258
 259     /** Moves one of the strings to a different position.
 260
 261         This will move the string to a specified index, shuffling along
 262         any intervening elements as required.
 263
 264         So for example, if you have the array { 0, 1, 2, 3, 4, 5 } then calling
 265         move (2, 4) would result in { 0, 1, 3, 4, 2, 5 }.
 266
 267         @param currentIndex     the index of the value to be moved. If this isn't a
 268                                 valid index, then nothing will be done
 269         @param newIndex         the index at which you'd like this value to end up. If this
 270                                 is less than zero, the value will be moved to the end
 271                                 of the array
 272     */
 273     void move (int currentIndex, int newIndex) noexcept;
 274
 275     /** Deletes any whitespace characters from the starts and ends of all the strings. */
 276     void trim();
 277
 278     /** Adds numbers to the strings in the array, to make each string unique.
 279
 280         This will add numbers to the ends of groups of similar strings.
 281         e.g. if there are two "moose" strings, they will become "moose (1)" and "moose (2)"
 282
 283         @param ignoreCaseWhenComparing      whether the comparison used is case-insensitive
 284         @param appendNumberToFirstInstance  whether the first of a group of similar strings
 285                                             also has a number appended to it.
 286         @param preNumberString              when adding a number, this string is added before the number.
 287                                             If you pass 0, a default string will be used, which adds
 288                                             brackets around the number.
 289         @param postNumberString             this string is appended after any numbers that are added.
 290                                             If you pass 0, a default string will be used, which adds
 291                                             brackets around the number.
 292     */
 293     void appendNumbersToDuplicates (bool ignoreCaseWhenComparing,
 294                                     bool appendNumberToFirstInstance,
 295                                     CharPointer_UTF8 preNumberString = CharPointer_UTF8 (nullptr),
 296                                     CharPointer_UTF8 postNumberString = CharPointer_UTF8 (nullptr));
 297
 298     //==============================================================================
 299     /** Joins the strings in the array together into one string.
 300
 301         This will join a range of elements from the array into a string, separating
 302         them with a given string.
 303
 304         e.g. joinIntoString (",") will turn an array of "a" "b" and "c" into "a,b,c".
 305
 306         @param separatorString      the string to insert between all the strings
 307         @param startIndex           the first element to join
 308         @param numberOfElements     how many elements to join together. If this is less
 309                                     than zero, all available elements will be used.
 310     */
 311     String joinIntoString (const String& separatorString,
 312                            int startIndex = 0,
 313                            int numberOfElements = -1) const;
 314
 315     //==============================================================================
 316     /** Sorts the array into alphabetical order.
 317
 318         @param ignoreCase       if true, the comparisons used will be case-sensitive.
 319     */
 320     void sort (bool ignoreCase);
 321
 322     //==============================================================================
 323     /** Reduces the amount of storage being used by the array.
 324
 325         Arrays typically allocate slightly more storage than they need, and after
 326         removing elements, they may have quite a lot of unused space allocated.
 327         This method will reduce the amount of allocated storage to a minimum.
 328     */
 329     void minimiseStorageOverheads();
 330
 331
 332 private:
 333     //==============================================================================
 334     Array <String> strings;
 335
 336     JUCE_LEAK_DETECTOR (StringArray);
 337 };
 338
 339
 340 #endif   // __JUCE_STRINGARRAY_JUCEHEADER__