OpenShot Library | libopenshot-audio 0.2.0
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
27namespace 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{
40public:
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() const noexcept { return strings.begin(); }
163
164 /** Returns a pointer to the String which follows the last element in the array.
165 This method is provided for compatibility with standard C++ iteration mechanisms.
166 */
167 inline String* end() const noexcept { return strings.end(); }
168
169 /** Searches for a string in the array.
170
171 The comparison will be case-insensitive if the ignoreCase parameter is true.
172
173 @returns true if the string is found inside the array
174 */
175 bool contains (StringRef stringToLookFor,
176 bool ignoreCase = false) const;
177
178 /** Searches for a string in the array.
179
180 The comparison will be case-insensitive if the ignoreCase parameter is true.
181
182 @param stringToLookFor the string to try to find
183 @param ignoreCase whether the comparison should be case-insensitive
184 @param startIndex the first index to start searching from
185 @returns the index of the first occurrence of the string in this array,
186 or -1 if it isn't found.
187 */
188 int indexOf (StringRef stringToLookFor,
189 bool ignoreCase = false,
190 int startIndex = 0) const;
191
192 //==============================================================================
193 /** Appends a string at the end of the array. */
194 void add (String stringToAdd);
195
196 /** Inserts a string into the array.
197
198 This will insert a string into the array at the given index, moving
199 up the other elements to make room for it.
200 If the index is less than zero or greater than the size of the array,
201 the new string will be added to the end of the array.
202 */
203 void insert (int index, String stringToAdd);
204
205 /** Adds a string to the array as long as it's not already in there.
206 The search can optionally be case-insensitive.
207
208 @return true if the string has been added, false otherwise.
209 */
210 bool addIfNotAlreadyThere (const String& stringToAdd, bool ignoreCase = false);
211
212 /** Replaces one of the strings in the array with another one.
213
214 If the index is higher than the array's size, the new string will be
215 added to the end of the array; if it's less than zero nothing happens.
216 */
217 void set (int index, String newString);
218
219 /** Appends some strings from another array to the end of this one.
220
221 @param other the array to add
222 @param startIndex the first element of the other array to add
223 @param numElementsToAdd the maximum number of elements to add (if this is
224 less than zero, they are all added)
225 */
226 void addArray (const StringArray& other,
227 int startIndex = 0,
228 int numElementsToAdd = -1);
229
230 /** Adds items from a range of start/end iterators of some kind of objects which
231 can be implicitly converted to Strings.
232 */
233 template <typename Iterator>
234 void addArray (Iterator&& start, Iterator&& end)
235 {
236 ensureStorageAllocated (size() + (int) static_cast<size_t> (end - start));
237
238 while (start != end)
239 strings.add (*start++);
240 }
241
242 /** Merges the strings from another array into this one.
243 This will not add a string that already exists.
244
245 @param other the array to add
246 @param ignoreCase ignore case when merging
247 */
248 void mergeArray (const StringArray& other,
249 bool ignoreCase = false);
250
251 /** Breaks up a string into tokens and adds them to this array.
252
253 This will tokenise the given string using whitespace characters as the
254 token delimiters, and will add these tokens to the end of the array.
255 @returns the number of tokens added
256 @see fromTokens
257 */
258 int addTokens (StringRef stringToTokenise, bool preserveQuotedStrings);
259
260 /** Breaks up a string into tokens and adds them to this array.
261
262 This will tokenise the given string (using the string passed in to define the
263 token delimiters), and will add these tokens to the end of the array.
264
265 @param stringToTokenise the string to tokenise
266 @param breakCharacters a string of characters, any of which will be considered
267 to be a token delimiter.
268 @param quoteCharacters if this string isn't empty, it defines a set of characters
269 which are treated as quotes. Any text occurring
270 between quotes is not broken up into tokens.
271 @returns the number of tokens added
272 @see fromTokens
273 */
274 int addTokens (StringRef stringToTokenise,
275 StringRef breakCharacters,
276 StringRef quoteCharacters);
277
278 /** Breaks up a string into lines and adds them to this array.
279
280 This breaks a string down into lines separated by \\n or \\r\\n, and adds each line
281 to the array. Line-break characters are omitted from the strings that are added to
282 the array.
283 */
284 int addLines (StringRef stringToBreakUp);
285
286 /** Returns an array containing the tokens in a given string.
287
288 This will tokenise the given string using whitespace characters as the
289 token delimiters, and return the parsed tokens as an array.
290 @see addTokens
291 */
292 static StringArray fromTokens (StringRef stringToTokenise,
293 bool preserveQuotedStrings);
294
295 /** Returns an array containing the tokens in a given string.
296
297 This will tokenise the given string using the breakCharacters string to define
298 the token delimiters, and will return the parsed tokens as an array.
299
300 @param stringToTokenise the string to tokenise
301 @param breakCharacters a string of characters, any of which will be considered
302 to be a token delimiter.
303 @param quoteCharacters if this string isn't empty, it defines a set of characters
304 which are treated as quotes. Any text occurring
305 between quotes is not broken up into tokens.
306 @see addTokens
307 */
308 static StringArray fromTokens (StringRef stringToTokenise,
309 StringRef breakCharacters,
310 StringRef quoteCharacters);
311
312 /** Returns an array containing the lines in a given string.
313
314 This breaks a string down into lines separated by \\n or \\r\\n, and returns an
315 array containing these lines. Line-break characters are omitted from the strings that
316 are added to the array.
317 */
318 static StringArray fromLines (StringRef stringToBreakUp);
319
320 //==============================================================================
321 /** Removes all elements from the array. */
322 void clear();
323
324 /** Removes all elements from the array without freeing the array's allocated storage.
325 @see clear
326 */
327 void clearQuick();
328
329 /** Removes a string from the array.
330 If the index is out-of-range, no action will be taken.
331 */
332 void remove (int index);
333
334 /** Finds a string in the array and removes it.
335 This will remove all occurrences of the given string from the array.
336 The comparison may be case-insensitive depending on the ignoreCase parameter.
337 */
338 void removeString (StringRef stringToRemove,
339 bool ignoreCase = false);
340
341 /** Removes a range of elements from the array.
342
343 This will remove a set of elements, starting from the given index,
344 and move subsequent elements down to close the gap.
345
346 If the range extends beyond the bounds of the array, it will
347 be safely clipped to the size of the array.
348
349 @param startIndex the index of the first element to remove
350 @param numberToRemove how many elements should be removed
351 */
352 void removeRange (int startIndex, int numberToRemove);
353
354 /** Removes any duplicated elements from the array.
355
356 If any string appears in the array more than once, only the first occurrence of
357 it will be retained.
358
359 @param ignoreCase whether to use a case-insensitive comparison
360 */
361 void removeDuplicates (bool ignoreCase);
362
363 /** Removes empty strings from the array.
364 @param removeWhitespaceStrings if true, strings that only contain whitespace
365 characters will also be removed
366 */
367 void removeEmptyStrings (bool removeWhitespaceStrings = true);
368
369 /** Moves one of the strings to a different position.
370
371 This will move the string to a specified index, shuffling along
372 any intervening elements as required.
373
374 So for example, if you have the array { 0, 1, 2, 3, 4, 5 } then calling
375 move (2, 4) would result in { 0, 1, 3, 4, 2, 5 }.
376
377 @param currentIndex the index of the value to be moved. If this isn't a
378 valid index, then nothing will be done
379 @param newIndex the index at which you'd like this value to end up. If this
380 is less than zero, the value will be moved to the end
381 of the array
382 */
383 void move (int currentIndex, int newIndex) noexcept;
384
385 /** Deletes any whitespace characters from the starts and ends of all the strings. */
386 void trim();
387
388 /** Adds numbers to the strings in the array, to make each string unique.
389
390 This will add numbers to the ends of groups of similar strings.
391 e.g. if there are two "moose" strings, they will become "moose (1)" and "moose (2)"
392
393 @param ignoreCaseWhenComparing whether the comparison used is case-insensitive
394 @param appendNumberToFirstInstance whether the first of a group of similar strings
395 also has a number appended to it.
396 @param preNumberString when adding a number, this string is added before the number.
397 If you pass nullptr, a default string will be used, which adds
398 brackets around the number.
399 @param postNumberString this string is appended after any numbers that are added.
400 If you pass nullptr, a default string will be used, which adds
401 brackets around the number.
402 */
403 void appendNumbersToDuplicates (bool ignoreCaseWhenComparing,
404 bool appendNumberToFirstInstance,
405 CharPointer_UTF8 preNumberString = CharPointer_UTF8 (nullptr),
406 CharPointer_UTF8 postNumberString = CharPointer_UTF8 (nullptr));
407
408 //==============================================================================
409 /** Joins the strings in the array together into one string.
410
411 This will join a range of elements from the array into a string, separating
412 them with a given string.
413
414 e.g. joinIntoString (",") will turn an array of "a" "b" and "c" into "a,b,c".
415
416 @param separatorString the string to insert between all the strings
417 @param startIndex the first element to join
418 @param numberOfElements how many elements to join together. If this is less
419 than zero, all available elements will be used.
420 */
421 String joinIntoString (StringRef separatorString,
422 int startIndex = 0,
423 int numberOfElements = -1) const;
424
425 //==============================================================================
426 /** Sorts the array into alphabetical order.
427 @param ignoreCase if true, the comparisons used will not be case-sensitive.
428 */
429 void sort (bool ignoreCase);
430
431 /** Sorts the array using extra language-aware rules to do a better job of comparing
432 words containing spaces and numbers.
433 @see String::compareNatural()
434 */
435 void sortNatural();
436
437 //==============================================================================
438 /** Increases the array's internal storage to hold a minimum number of elements.
439
440 Calling this before adding a large known number of elements means that
441 the array won't have to keep dynamically resizing itself as the elements
442 are added, and it'll therefore be more efficient.
443 */
444 void ensureStorageAllocated (int minNumElements);
445
446 /** Reduces the amount of storage being used by the array.
447
448 Arrays typically allocate slightly more storage than they need, and after
449 removing elements, they may have quite a lot of unused space allocated.
450 This method will reduce the amount of allocated storage to a minimum.
451 */
452 void minimiseStorageOverheads();
453
454 /** This is the array holding the actual strings. This is public to allow direct access
455 to array methods that may not already be provided by the StringArray class.
456 */
458
459private:
460 JUCE_LEAK_DETECTOR (StringArray)
461};
462
463} // namespace juce
464
465/** @}*/
Holds a resizable array of primitive or copy-by-value objects.
Definition juce_Array.h:60
Wraps a pointer to a null-terminated UTF-8 character string, and provides various methods to operate ...
A special array for holding a list of strings.
StringArray(StringRef firstValue, OtherElements... otherValues)
Creates an array containing a list of strings.
String * end() const noexcept
Returns a pointer to the String which follows the last element 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...
String * begin() const noexcept
Returns a pointer to the first String in the array.
int size() const noexcept
Returns the number of strings in the array.
bool isEmpty() const noexcept
Returns true if the array is empty, false otherwise.
A simple class for holding temporary references to a string literal or String.
The JUCE String class!
Definition juce_String.h:43
#define JUCE_API
This macro is added to all JUCE public class declarations.