juce_StringArray.h 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422
  1. /*
  2. ==============================================================================
  3. This file is part of the juce_core module of the JUCE library.
  4. Copyright (c) 2013 - Raw Material Software Ltd.
  5. Permission to use, copy, modify, and/or distribute this software for any purpose with
  6. or without fee is hereby granted, provided that the above copyright notice and this
  7. permission notice appear in all copies.
  8. THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD
  9. TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN
  10. NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
  11. DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER
  12. IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
  13. CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  14. ------------------------------------------------------------------------------
  15. NOTE! This permissive ISC license applies ONLY to files within the juce_core module!
  16. All other JUCE modules are covered by a dual GPL/commercial license, so if you are
  17. using any other modules, be sure to check that you also comply with their license.
  18. For more details, visit www.juce.com
  19. ==============================================================================
  20. */
  21. #ifndef JUCE_STRINGARRAY_H_INCLUDED
  22. #define JUCE_STRINGARRAY_H_INCLUDED
  23. //==============================================================================
  24. /**
  25. A special array for holding a list of strings.
  26. @see String, StringPairArray
  27. */
  28. class JUCE_API StringArray
  29. {
  30. public:
  31. //==============================================================================
  32. /** Creates an empty string array */
  33. StringArray() noexcept;
  34. /** Creates a copy of another string array */
  35. StringArray (const StringArray&);
  36. #if JUCE_COMPILER_SUPPORTS_MOVE_SEMANTICS
  37. StringArray (StringArray&&) noexcept;
  38. #endif
  39. /** Creates an array containing a single string. */
  40. explicit StringArray (const String& firstValue);
  41. /** Creates an array from a raw array of strings.
  42. @param strings an array of strings to add
  43. @param numberOfStrings how many items there are in the array
  44. */
  45. StringArray (const String* strings, int numberOfStrings);
  46. /** Creates a copy of an array of string literals.
  47. @param strings an array of strings to add. Null pointers in the array will be
  48. treated as empty strings
  49. @param numberOfStrings how many items there are in the array
  50. */
  51. StringArray (const char* const* strings, int numberOfStrings);
  52. /** Creates a copy of a null-terminated array of string literals.
  53. Each item from the array passed-in is added, until it encounters a null pointer,
  54. at which point it stops.
  55. */
  56. explicit StringArray (const char* const* strings);
  57. /** Creates a copy of a null-terminated array of string literals.
  58. Each item from the array passed-in is added, until it encounters a null pointer,
  59. at which point it stops.
  60. */
  61. explicit StringArray (const wchar_t* const* strings);
  62. /** Creates a copy of an array of string literals.
  63. @param strings an array of strings to add. Null pointers in the array will be
  64. treated as empty strings
  65. @param numberOfStrings how many items there are in the array
  66. */
  67. StringArray (const wchar_t* const* strings, int numberOfStrings);
  68. /** Destructor. */
  69. ~StringArray();
  70. /** Copies the contents of another string array into this one */
  71. StringArray& operator= (const StringArray&);
  72. #if JUCE_COMPILER_SUPPORTS_MOVE_SEMANTICS
  73. StringArray& operator= (StringArray&&) noexcept;
  74. #endif
  75. /** Swaps the contents of this and another StringArray. */
  76. void swapWith (StringArray&) noexcept;
  77. //==============================================================================
  78. /** Compares two arrays.
  79. Comparisons are case-sensitive.
  80. @returns true only if the other array contains exactly the same strings in the same order
  81. */
  82. bool operator== (const StringArray&) const noexcept;
  83. /** Compares two arrays.
  84. Comparisons are case-sensitive.
  85. @returns false if the other array contains exactly the same strings in the same order
  86. */
  87. bool operator!= (const StringArray&) const noexcept;
  88. //==============================================================================
  89. /** Returns the number of strings in the array */
  90. inline int size() const noexcept { return strings.size(); };
  91. /** Returns one of the strings from the array.
  92. If the index is out-of-range, an empty string is returned.
  93. Obviously the reference returned shouldn't be stored for later use, as the
  94. string it refers to may disappear when the array changes.
  95. */
  96. const String& operator[] (int index) const noexcept;
  97. /** Returns a reference to one of the strings in the array.
  98. This lets you modify a string in-place in the array, but you must be sure that
  99. the index is in-range.
  100. */
  101. String& getReference (int index) noexcept;
  102. /** Returns a pointer to the first String in the array.
  103. This method is provided for compatibility with standard C++ iteration mechanisms.
  104. */
  105. inline String* begin() const noexcept { return strings.begin(); }
  106. /** Returns a pointer to the String which follows the last element in the array.
  107. This method is provided for compatibility with standard C++ iteration mechanisms.
  108. */
  109. inline String* end() const noexcept { return strings.end(); }
  110. /** Searches for a string in the array.
  111. The comparison will be case-insensitive if the ignoreCase parameter is true.
  112. @returns true if the string is found inside the array
  113. */
  114. bool contains (StringRef stringToLookFor,
  115. bool ignoreCase = false) const;
  116. /** Searches for a string in the array.
  117. The comparison will be case-insensitive if the ignoreCase parameter is true.
  118. @param stringToLookFor the string to try to find
  119. @param ignoreCase whether the comparison should be case-insensitive
  120. @param startIndex the first index to start searching from
  121. @returns the index of the first occurrence of the string in this array,
  122. or -1 if it isn't found.
  123. */
  124. int indexOf (StringRef stringToLookFor,
  125. bool ignoreCase = false,
  126. int startIndex = 0) const;
  127. //==============================================================================
  128. /** Appends a string at the end of the array. */
  129. void add (const String& stringToAdd);
  130. #if JUCE_COMPILER_SUPPORTS_MOVE_SEMANTICS
  131. /** Appends a string at the end of the array. */
  132. void add (String&& stringToAdd);
  133. #endif
  134. /** Inserts a string into the array.
  135. This will insert a string into the array at the given index, moving
  136. up the other elements to make room for it.
  137. If the index is less than zero or greater than the size of the array,
  138. the new string will be added to the end of the array.
  139. */
  140. void insert (int index, const String& stringToAdd);
  141. /** Adds a string to the array as long as it's not already in there.
  142. The search can optionally be case-insensitive.
  143. */
  144. void addIfNotAlreadyThere (const String& stringToAdd, bool ignoreCase = false);
  145. /** Replaces one of the strings in the array with another one.
  146. If the index is higher than the array's size, the new string will be
  147. added to the end of the array; if it's less than zero nothing happens.
  148. */
  149. void set (int index, const String& newString);
  150. /** Appends some strings from another array to the end of this one.
  151. @param other the array to add
  152. @param startIndex the first element of the other array to add
  153. @param numElementsToAdd the maximum number of elements to add (if this is
  154. less than zero, they are all added)
  155. */
  156. void addArray (const StringArray& other,
  157. int startIndex = 0,
  158. int numElementsToAdd = -1);
  159. /** Breaks up a string into tokens and adds them to this array.
  160. This will tokenise the given string using whitespace characters as the
  161. token delimiters, and will add these tokens to the end of the array.
  162. @returns the number of tokens added
  163. @see fromTokens
  164. */
  165. int addTokens (StringRef stringToTokenise, bool preserveQuotedStrings);
  166. /** Breaks up a string into tokens and adds them to this array.
  167. This will tokenise the given string (using the string passed in to define the
  168. token delimiters), and will add these tokens to the end of the array.
  169. @param stringToTokenise the string to tokenise
  170. @param breakCharacters a string of characters, any of which will be considered
  171. to be a token delimiter.
  172. @param quoteCharacters if this string isn't empty, it defines a set of characters
  173. which are treated as quotes. Any text occurring
  174. between quotes is not broken up into tokens.
  175. @returns the number of tokens added
  176. @see fromTokens
  177. */
  178. int addTokens (StringRef stringToTokenise,
  179. StringRef breakCharacters,
  180. StringRef quoteCharacters);
  181. /** Breaks up a string into lines and adds them to this array.
  182. This breaks a string down into lines separated by \\n or \\r\\n, and adds each line
  183. to the array. Line-break characters are omitted from the strings that are added to
  184. the array.
  185. */
  186. int addLines (StringRef stringToBreakUp);
  187. /** Returns an array containing the tokens in a given string.
  188. This will tokenise the given string using whitespace characters as the
  189. token delimiters, and return these tokens as an array.
  190. @see addTokens
  191. */
  192. static StringArray fromTokens (StringRef stringToTokenise,
  193. bool preserveQuotedStrings);
  194. /** Returns an array containing the tokens in a given string.
  195. This will tokenise the given string using whitespace characters as the
  196. token delimiters, and return these tokens as an array.
  197. @param stringToTokenise the string to tokenise
  198. @param breakCharacters a string of characters, any of which will be considered
  199. to be a token delimiter.
  200. @param quoteCharacters if this string isn't empty, it defines a set of characters
  201. which are treated as quotes. Any text occurring
  202. between quotes is not broken up into tokens.
  203. @see addTokens
  204. */
  205. static StringArray fromTokens (StringRef stringToTokenise,
  206. StringRef breakCharacters,
  207. StringRef quoteCharacters);
  208. /** Returns an array containing the lines in a given string.
  209. This breaks a string down into lines separated by \\n or \\r\\n, and returns an
  210. array containing these lines. Line-break characters are omitted from the strings that
  211. are added to the array.
  212. */
  213. static StringArray fromLines (StringRef stringToBreakUp);
  214. //==============================================================================
  215. /** Removes all elements from the array. */
  216. void clear();
  217. /** Removes all elements from the array without freeing the array's allocated storage.
  218. @see clear
  219. */
  220. void clearQuick();
  221. /** Removes a string from the array.
  222. If the index is out-of-range, no action will be taken.
  223. */
  224. void remove (int index);
  225. /** Finds a string in the array and removes it.
  226. This will remove the first occurrence of the given string from the array. The
  227. comparison may be case-insensitive depending on the ignoreCase parameter.
  228. */
  229. void removeString (StringRef stringToRemove,
  230. bool ignoreCase = false);
  231. /** Removes a range of elements from the array.
  232. This will remove a set of elements, starting from the given index,
  233. and move subsequent elements down to close the gap.
  234. If the range extends beyond the bounds of the array, it will
  235. be safely clipped to the size of the array.
  236. @param startIndex the index of the first element to remove
  237. @param numberToRemove how many elements should be removed
  238. */
  239. void removeRange (int startIndex, int numberToRemove);
  240. /** Removes any duplicated elements from the array.
  241. If any string appears in the array more than once, only the first occurrence of
  242. it will be retained.
  243. @param ignoreCase whether to use a case-insensitive comparison
  244. */
  245. void removeDuplicates (bool ignoreCase);
  246. /** Removes empty strings from the array.
  247. @param removeWhitespaceStrings if true, strings that only contain whitespace
  248. characters will also be removed
  249. */
  250. void removeEmptyStrings (bool removeWhitespaceStrings = true);
  251. /** Moves one of the strings to a different position.
  252. This will move the string to a specified index, shuffling along
  253. any intervening elements as required.
  254. So for example, if you have the array { 0, 1, 2, 3, 4, 5 } then calling
  255. move (2, 4) would result in { 0, 1, 3, 4, 2, 5 }.
  256. @param currentIndex the index of the value to be moved. If this isn't a
  257. valid index, then nothing will be done
  258. @param newIndex the index at which you'd like this value to end up. If this
  259. is less than zero, the value will be moved to the end
  260. of the array
  261. */
  262. void move (int currentIndex, int newIndex) noexcept;
  263. /** Deletes any whitespace characters from the starts and ends of all the strings. */
  264. void trim();
  265. /** Adds numbers to the strings in the array, to make each string unique.
  266. This will add numbers to the ends of groups of similar strings.
  267. e.g. if there are two "moose" strings, they will become "moose (1)" and "moose (2)"
  268. @param ignoreCaseWhenComparing whether the comparison used is case-insensitive
  269. @param appendNumberToFirstInstance whether the first of a group of similar strings
  270. also has a number appended to it.
  271. @param preNumberString when adding a number, this string is added before the number.
  272. If you pass 0, a default string will be used, which adds
  273. brackets around the number.
  274. @param postNumberString this string is appended after any numbers that are added.
  275. If you pass 0, a default string will be used, which adds
  276. brackets around the number.
  277. */
  278. void appendNumbersToDuplicates (bool ignoreCaseWhenComparing,
  279. bool appendNumberToFirstInstance,
  280. CharPointer_UTF8 preNumberString = CharPointer_UTF8 (nullptr),
  281. CharPointer_UTF8 postNumberString = CharPointer_UTF8 (nullptr));
  282. //==============================================================================
  283. /** Joins the strings in the array together into one string.
  284. This will join a range of elements from the array into a string, separating
  285. them with a given string.
  286. e.g. joinIntoString (",") will turn an array of "a" "b" and "c" into "a,b,c".
  287. @param separatorString the string to insert between all the strings
  288. @param startIndex the first element to join
  289. @param numberOfElements how many elements to join together. If this is less
  290. than zero, all available elements will be used.
  291. */
  292. String joinIntoString (StringRef separatorString,
  293. int startIndex = 0,
  294. int numberOfElements = -1) const;
  295. //==============================================================================
  296. /** Sorts the array into alphabetical order.
  297. @param ignoreCase if true, the comparisons used will be case-sensitive.
  298. */
  299. void sort (bool ignoreCase);
  300. /** Sorts the array using extra language-aware rules to do a better job of comparing
  301. words containing spaces and numbers.
  302. @see String::compareNatural()
  303. */
  304. void sortNatural();
  305. //==============================================================================
  306. /** Increases the array's internal storage to hold a minimum number of elements.
  307. Calling this before adding a large known number of elements means that
  308. the array won't have to keep dynamically resizing itself as the elements
  309. are added, and it'll therefore be more efficient.
  310. */
  311. void ensureStorageAllocated (int minNumElements);
  312. /** Reduces the amount of storage being used by the array.
  313. Arrays typically allocate slightly more storage than they need, and after
  314. removing elements, they may have quite a lot of unused space allocated.
  315. This method will reduce the amount of allocated storage to a minimum.
  316. */
  317. void minimiseStorageOverheads();
  318. /** This is the array holding the actual strings. This is public to allow direct access
  319. to array methods that may not already be provided by the StringArray class.
  320. */
  321. Array<String> strings;
  322. private:
  323. JUCE_LEAK_DETECTOR (StringArray)
  324. };
  325. #endif // JUCE_STRINGARRAY_H_INCLUDED