OpenShot Library | OpenShotAudio  0.2.2
juce_StringArray.h
1 
2 /** @weakgroup juce_core-text
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 /**
32  A special array for holding a list of strings.
33 
34  @see String, StringPairArray
35 
36  @tags{Core}
37 */
39 {
40 public:
41  //==============================================================================
42  /** Creates an empty string array */
43  StringArray() noexcept;
44 
45  /** Creates a copy of another string array */
46  StringArray (const StringArray&);
47 
48  /** Move constructor */
49  StringArray (StringArray&&) noexcept;
50 
51  /** Creates an array containing a single string. */
52  StringArray (const String& firstValue);
53 
54  /** Creates an array containing a list of strings. */
55  template <typename... OtherElements>
56  StringArray (StringRef firstValue, OtherElements... otherValues) : strings (firstValue, otherValues...) {}
57 
58  /** Creates an array containing a list of strings. */
59  StringArray (const std::initializer_list<const char*>& strings);
60 
61  /** Creates a StringArray by moving from an Array<String> */
62  StringArray (Array<String>&&) noexcept;
63 
64  /** Creates a StringArray from an array of objects which can be implicitly converted to Strings. */
65  template <typename Type>
66  StringArray (const Array<Type>& stringArray)
67  {
68  addArray (stringArray.begin(), stringArray.end());
69  }
70 
71  /** Creates an array from a raw array of strings.
72  @param strings an array of strings to add
73  @param numberOfStrings how many items there are in the array
74  */
75  StringArray (const String* strings, int numberOfStrings);
76 
77  /** Creates a copy of an array of string literals.
78  @param strings an array of strings to add. Null pointers in the array will be
79  treated as empty strings
80  @param numberOfStrings how many items there are in the array
81  */
82  StringArray (const char* const* strings, int numberOfStrings);
83 
84  /** Creates a copy of a null-terminated array of string literals.
85 
86  Each item from the array passed-in is added, until it encounters a null pointer,
87  at which point it stops.
88  */
89  explicit StringArray (const char* const* strings);
90 
91  /** Creates a copy of a null-terminated array of string literals.
92  Each item from the array passed-in is added, until it encounters a null pointer,
93  at which point it stops.
94  */
95  explicit StringArray (const wchar_t* const* strings);
96 
97  /** Creates a copy of an array of string literals.
98  @param strings an array of strings to add. Null pointers in the array will be
99  treated as empty strings
100  @param numberOfStrings how many items there are in the array
101  */
102  StringArray (const wchar_t* const* strings, int numberOfStrings);
103 
104  /** Destructor. */
105  ~StringArray();
106 
107  /** Copies the contents of another string array into this one */
108  StringArray& operator= (const StringArray&);
109 
110  /** Move assignment operator */
111  StringArray& operator= (StringArray&&) noexcept;
112 
113  /** Copies a StringArray from an array of objects which can be implicitly converted to Strings. */
114  template <typename Type>
115  StringArray& operator= (const Array<Type>& stringArray)
116  {
117  addArray (stringArray.begin(), stringArray.end());
118  return *this;
119  }
120 
121  /** Swaps the contents of this and another StringArray. */
122  void swapWith (StringArray&) noexcept;
123 
124  //==============================================================================
125  /** Compares two arrays.
126  Comparisons are case-sensitive.
127  @returns true only if the other array contains exactly the same strings in the same order
128  */
129  bool operator== (const StringArray&) const noexcept;
130 
131  /** Compares two arrays.
132  Comparisons are case-sensitive.
133  @returns false if the other array contains exactly the same strings in the same order
134  */
135  bool operator!= (const StringArray&) const noexcept;
136 
137  //==============================================================================
138  /** Returns the number of strings in the array */
139  inline int size() const noexcept { return strings.size(); }
140 
141  /** Returns true if the array is empty, false otherwise. */
142  inline bool isEmpty() const noexcept { return size() == 0; }
143 
144  /** Returns one of the strings from the array.
145 
146  If the index is out-of-range, an empty string is returned.
147 
148  Obviously the reference returned shouldn't be stored for later use, as the
149  string it refers to may disappear when the array changes.
150  */
151  const String& operator[] (int index) const noexcept;
152 
153  /** Returns a reference to one of the strings in the array.
154  This lets you modify a string in-place in the array, but you must be sure that
155  the index is in-range.
156  */
157  String& getReference (int index) noexcept;
158 
159  /** Returns a pointer to the first String in the array.
160  This method is provided for compatibility with standard C++ iteration mechanisms.
161  */
162  inline String* begin() noexcept { return strings.begin(); }
163 
164  /** Returns a pointer to the first String in the array.
165  This method is provided for compatibility with standard C++ iteration mechanisms.
166  */
167  inline const String* begin() const noexcept { return strings.begin(); }
168 
169  /** Returns a pointer to the String which follows the last element in the array.
170  This method is provided for compatibility with standard C++ iteration mechanisms.
171  */
172  inline String* end() noexcept { return strings.end(); }
173 
174  /** Returns a pointer to the String which follows the last element in the array.
175  This method is provided for compatibility with standard C++ iteration mechanisms.
176  */
177  inline const String* end() const noexcept { return strings.end(); }
178 
179 
180  /** Searches for a string in the array.
181 
182  The comparison will be case-insensitive if the ignoreCase parameter is true.
183 
184  @returns true if the string is found inside the array
185  */
186  bool contains (StringRef stringToLookFor,
187  bool ignoreCase = false) const;
188 
189  /** Searches for a string in the array.
190 
191  The comparison will be case-insensitive if the ignoreCase parameter is true.
192 
193  @param stringToLookFor the string to try to find
194  @param ignoreCase whether the comparison should be case-insensitive
195  @param startIndex the first index to start searching from
196  @returns the index of the first occurrence of the string in this array,
197  or -1 if it isn't found.
198  */
199  int indexOf (StringRef stringToLookFor,
200  bool ignoreCase = false,
201  int startIndex = 0) const;
202 
203  //==============================================================================
204  /** Appends a string at the end of the array. */
205  void add (String stringToAdd);
206 
207  /** Inserts a string into the array.
208 
209  This will insert a string into the array at the given index, moving
210  up the other elements to make room for it.
211  If the index is less than zero or greater than the size of the array,
212  the new string will be added to the end of the array.
213  */
214  void insert (int index, String stringToAdd);
215 
216  /** Adds a string to the array as long as it's not already in there.
217  The search can optionally be case-insensitive.
218 
219  @return true if the string has been added, false otherwise.
220  */
221  bool addIfNotAlreadyThere (const String& stringToAdd, bool ignoreCase = false);
222 
223  /** Replaces one of the strings in the array with another one.
224 
225  If the index is higher than the array's size, the new string will be
226  added to the end of the array; if it's less than zero nothing happens.
227  */
228  void set (int index, String newString);
229 
230  /** Appends some strings from another array to the end of this one.
231 
232  @param other the array to add
233  @param startIndex the first element of the other array to add
234  @param numElementsToAdd the maximum number of elements to add (if this is
235  less than zero, they are all added)
236  */
237  void addArray (const StringArray& other,
238  int startIndex = 0,
239  int numElementsToAdd = -1);
240 
241  /** Adds items from a range of start/end iterators of some kind of objects which
242  can be implicitly converted to Strings.
243  */
244  template <typename Iterator>
245  void addArray (Iterator&& start, Iterator&& end)
246  {
247  ensureStorageAllocated (size() + (int) static_cast<size_t> (end - start));
248 
249  while (start != end)
250  strings.add (*start++);
251  }
252 
253  /** Merges the strings from another array into this one.
254  This will not add a string that already exists.
255 
256  @param other the array to add
257  @param ignoreCase ignore case when merging
258  */
259  void mergeArray (const StringArray& other,
260  bool ignoreCase = false);
261 
262  /** Breaks up a string into tokens and adds them to this array.
263 
264  This will tokenise the given string using whitespace characters as the
265  token delimiters, and will add these tokens to the end of the array.
266  @returns the number of tokens added
267  @see fromTokens
268  */
269  int addTokens (StringRef stringToTokenise, bool preserveQuotedStrings);
270 
271  /** Breaks up a string into tokens and adds them to this array.
272 
273  This will tokenise the given string (using the string passed in to define the
274  token delimiters), and will add these tokens to the end of the array.
275 
276  @param stringToTokenise the string to tokenise
277  @param breakCharacters a string of characters, any of which will be considered
278  to be a token delimiter.
279  @param quoteCharacters if this string isn't empty, it defines a set of characters
280  which are treated as quotes. Any text occurring
281  between quotes is not broken up into tokens.
282  @returns the number of tokens added
283  @see fromTokens
284  */
285  int addTokens (StringRef stringToTokenise,
286  StringRef breakCharacters,
287  StringRef quoteCharacters);
288 
289  /** Breaks up a string into lines and adds them to this array.
290 
291  This breaks a string down into lines separated by \\n or \\r\\n, and adds each line
292  to the array. Line-break characters are omitted from the strings that are added to
293  the array.
294  */
295  int addLines (StringRef stringToBreakUp);
296 
297  /** Returns an array containing the tokens in a given string.
298 
299  This will tokenise the given string using whitespace characters as the
300  token delimiters, and return the parsed tokens as an array.
301  @see addTokens
302  */
303  static StringArray fromTokens (StringRef stringToTokenise,
304  bool preserveQuotedStrings);
305 
306  /** Returns an array containing the tokens in a given string.
307 
308  This will tokenise the given string using the breakCharacters string to define
309  the token delimiters, and will return the parsed tokens as an array.
310 
311  @param stringToTokenise the string to tokenise
312  @param breakCharacters a string of characters, any of which will be considered
313  to be a token delimiter.
314  @param quoteCharacters if this string isn't empty, it defines a set of characters
315  which are treated as quotes. Any text occurring
316  between quotes is not broken up into tokens.
317  @see addTokens
318  */
319  static StringArray fromTokens (StringRef stringToTokenise,
320  StringRef breakCharacters,
321  StringRef quoteCharacters);
322 
323  /** Returns an array containing the lines in a given string.
324 
325  This breaks a string down into lines separated by \\n or \\r\\n, and returns an
326  array containing these lines. Line-break characters are omitted from the strings that
327  are added to the array.
328  */
329  static StringArray fromLines (StringRef stringToBreakUp);
330 
331  //==============================================================================
332  /** Removes all elements from the array. */
333  void clear();
334 
335  /** Removes all elements from the array without freeing the array's allocated storage.
336  @see clear
337  */
338  void clearQuick();
339 
340  /** Removes a string from the array.
341  If the index is out-of-range, no action will be taken.
342  */
343  void remove (int index);
344 
345  /** Finds a string in the array and removes it.
346  This will remove all occurrences of the given string from the array.
347  The comparison may be case-insensitive depending on the ignoreCase parameter.
348  */
349  void removeString (StringRef stringToRemove,
350  bool ignoreCase = false);
351 
352  /** Removes a range of elements from the array.
353 
354  This will remove a set of elements, starting from the given index,
355  and move subsequent elements down to close the gap.
356 
357  If the range extends beyond the bounds of the array, it will
358  be safely clipped to the size of the array.
359 
360  @param startIndex the index of the first element to remove
361  @param numberToRemove how many elements should be removed
362  */
363  void removeRange (int startIndex, int numberToRemove);
364 
365  /** Removes any duplicated elements from the array.
366 
367  If any string appears in the array more than once, only the first occurrence of
368  it will be retained.
369 
370  @param ignoreCase whether to use a case-insensitive comparison
371  */
372  void removeDuplicates (bool ignoreCase);
373 
374  /** Removes empty strings from the array.
375  @param removeWhitespaceStrings if true, strings that only contain whitespace
376  characters will also be removed
377  */
378  void removeEmptyStrings (bool removeWhitespaceStrings = true);
379 
380  /** Moves one of the strings to a different position.
381 
382  This will move the string to a specified index, shuffling along
383  any intervening elements as required.
384 
385  So for example, if you have the array { 0, 1, 2, 3, 4, 5 } then calling
386  move (2, 4) would result in { 0, 1, 3, 4, 2, 5 }.
387 
388  @param currentIndex the index of the value to be moved. If this isn't a
389  valid index, then nothing will be done
390  @param newIndex the index at which you'd like this value to end up. If this
391  is less than zero, the value will be moved to the end
392  of the array
393  */
394  void move (int currentIndex, int newIndex) noexcept;
395 
396  /** Deletes any whitespace characters from the starts and ends of all the strings. */
397  void trim();
398 
399  /** Adds numbers to the strings in the array, to make each string unique.
400 
401  This will add numbers to the ends of groups of similar strings.
402  e.g. if there are two "moose" strings, they will become "moose (1)" and "moose (2)"
403 
404  @param ignoreCaseWhenComparing whether the comparison used is case-insensitive
405  @param appendNumberToFirstInstance whether the first of a group of similar strings
406  also has a number appended to it.
407  @param preNumberString when adding a number, this string is added before the number.
408  If you pass nullptr, a default string will be used, which adds
409  brackets around the number.
410  @param postNumberString this string is appended after any numbers that are added.
411  If you pass nullptr, a default string will be used, which adds
412  brackets around the number.
413  */
414  void appendNumbersToDuplicates (bool ignoreCaseWhenComparing,
415  bool appendNumberToFirstInstance,
416  CharPointer_UTF8 preNumberString = CharPointer_UTF8 (nullptr),
417  CharPointer_UTF8 postNumberString = CharPointer_UTF8 (nullptr));
418 
419  //==============================================================================
420  /** Joins the strings in the array together into one string.
421 
422  This will join a range of elements from the array into a string, separating
423  them with a given string.
424 
425  e.g. joinIntoString (",") will turn an array of "a" "b" and "c" into "a,b,c".
426 
427  @param separatorString the string to insert between all the strings
428  @param startIndex the first element to join
429  @param numberOfElements how many elements to join together. If this is less
430  than zero, all available elements will be used.
431  */
432  String joinIntoString (StringRef separatorString,
433  int startIndex = 0,
434  int numberOfElements = -1) const;
435 
436  //==============================================================================
437  /** Sorts the array into alphabetical order.
438  @param ignoreCase if true, the comparisons used will not be case-sensitive.
439  */
440  void sort (bool ignoreCase);
441 
442  /** Sorts the array using extra language-aware rules to do a better job of comparing
443  words containing spaces and numbers.
444  @see String::compareNatural()
445  */
446  void sortNatural();
447 
448  //==============================================================================
449  /** Increases the array's internal storage to hold a minimum number of elements.
450 
451  Calling this before adding a large known number of elements means that
452  the array won't have to keep dynamically resizing itself as the elements
453  are added, and it'll therefore be more efficient.
454  */
455  void ensureStorageAllocated (int minNumElements);
456 
457  /** Reduces the amount of storage being used by the array.
458 
459  Arrays typically allocate slightly more storage than they need, and after
460  removing elements, they may have quite a lot of unused space allocated.
461  This method will reduce the amount of allocated storage to a minimum.
462  */
463  void minimiseStorageOverheads();
464 
465  /** This is the array holding the actual strings. This is public to allow direct access
466  to array methods that may not already be provided by the StringArray class.
467  */
469 
470 private:
471  JUCE_LEAK_DETECTOR (StringArray)
472 };
473 
474 } // namespace juce
475 
476 /** @}*/
bool isEmpty() const noexcept
Returns true if the array is empty, false otherwise.
#define JUCE_API
This macro is added to all JUCE public class declarations.
const String * begin() const noexcept
Returns a pointer to the first String in the array.
String * begin() noexcept
Returns a pointer to the first String in the array.
StringArray(const Array< Type > &stringArray)
Creates a StringArray from an array of objects which can be implicitly converted to Strings...
ElementType * end() noexcept
Returns a pointer to the element which follows the last element in the array.
Definition: juce_Array.h:348
A simple class for holding temporary references to a string literal or String.
String * end() noexcept
Returns a pointer to the String which follows the last element in the array.
StringArray(StringRef firstValue, OtherElements... otherValues)
Creates an array containing a list of strings.
A special array for holding a list of strings.
The JUCE String class!
Definition: juce_String.h:42
ElementType * begin() noexcept
Returns a pointer to the first element in the array.
Definition: juce_Array.h:332
const String * end() const noexcept
Returns a pointer to the String which follows the last element in the array.
Holds a resizable array of primitive or copy-by-value objects.
Definition: juce_Array.h:59
int size() const noexcept
Returns the number of strings in the array.
Array< String > strings
This is the array holding the actual strings.
void addArray(Iterator &&start, Iterator &&end)
Adds items from a range of start/end iterators of some kind of objects which can be implicitly conver...
Wraps a pointer to a null-terminated UTF-8 character string, and provides various methods to operate ...