juce_StringArray.h

/*
  ==============================================================================
 
   This file is part of the JUCE library.
   Copyright (c) 2022 - Raw Material Software Limited
 
   JUCE is an open source library subject to commercial or open-source
   licensing.
 
   The code included in this file is provided under the terms of the ISC license
   http://www.isc.org/downloads/software-support-policy/isc-license. Permission
   To use, copy, modify, and/or distribute this software for any purpose with or
   without fee is hereby granted provided that the above copyright notice and
   this permission notice appear in all copies.
 
   JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
   EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
   DISCLAIMED.
 
  ==============================================================================
*/
 
namespace juce
{
 
//==============================================================================
class JUCE_API  StringArray
{
public:
    //==============================================================================
    StringArray() noexcept;

    StringArray (const StringArray&);

    StringArray (StringArray&&) noexcept;

    StringArray (const String& firstValue);

    template <typename... OtherElements>
    StringArray (StringRef firstValue, OtherElements&&... otherValues)
        : strings (firstValue, std::forward<OtherElements> (otherValues)...) {}

    StringArray (const std::initializer_list<const char*>& strings);

    StringArray (Array<String>&&) noexcept;

    template <typename Type>
    StringArray (const Array<Type>& stringArray)
    {
        addArray (stringArray.begin(), stringArray.end());
    }

    StringArray (const String* strings, int numberOfStrings);

    StringArray (const char* const* strings, int numberOfStrings);

    explicit StringArray (const char* const* strings);

    explicit StringArray (const wchar_t* const* strings);

    StringArray (const wchar_t* const* strings, int numberOfStrings);

    ~StringArray() = default;

    StringArray& operator= (const StringArray&);

    StringArray& operator= (StringArray&&) noexcept;

    template <typename Type>
    StringArray& operator= (const Array<Type>& stringArray)
    {
        addArray (stringArray.begin(), stringArray.end());
        return *this;
    }

    void swapWith (StringArray&) noexcept;
 
    //==============================================================================
    bool operator== (const StringArray&) const noexcept;

    bool operator!= (const StringArray&) const noexcept;
 
    //==============================================================================
    inline int size() const noexcept                                    { return strings.size(); }

    inline bool isEmpty() const noexcept                                { return size() == 0; }

    const String& operator[] (int index) const noexcept;

    String& getReference (int index) noexcept;

    const String& getReference (int index) const noexcept;

    inline String* begin() noexcept                 { return strings.begin(); }

    inline const String* begin() const noexcept     { return strings.begin(); }

    inline String* end() noexcept                  { return strings.end(); }

    inline const String* end() const noexcept       { return strings.end(); }
 

    bool contains (StringRef stringToLookFor,
                   bool ignoreCase = false) const;

    int indexOf (StringRef stringToLookFor,
                 bool ignoreCase = false,
                 int startIndex = 0) const;
 
    //==============================================================================
    void add (String stringToAdd);

    void insert (int index, String stringToAdd);

    bool addIfNotAlreadyThere (const String& stringToAdd, bool ignoreCase = false);

    void set (int index, String newString);

    void addArray (const StringArray& other,
                   int startIndex = 0,
                   int numElementsToAdd = -1);

    template <typename Iterator>
    void addArray (Iterator&& start, Iterator&& end)
    {
        ensureStorageAllocated (size() + (int) static_cast<size_t> (end - start));
 
        while (start != end)
            strings.add (*start++);
    }

    void mergeArray (const StringArray& other,
                     bool ignoreCase = false);

    int addTokens (StringRef stringToTokenise, bool preserveQuotedStrings);

    int addTokens (StringRef stringToTokenise,
                   StringRef breakCharacters,
                   StringRef quoteCharacters);

    int addLines (StringRef stringToBreakUp);

    static StringArray fromTokens (StringRef stringToTokenise,
                                   bool preserveQuotedStrings);

    static StringArray fromTokens (StringRef stringToTokenise,
                                   StringRef breakCharacters,
                                   StringRef quoteCharacters);

    static StringArray fromLines (StringRef stringToBreakUp);
 
    //==============================================================================
    void clear();

    void clearQuick();

    void remove (int index);

    void removeString (StringRef stringToRemove,
                       bool ignoreCase = false);

    void removeRange (int startIndex, int numberToRemove);

    void removeDuplicates (bool ignoreCase);

    void removeEmptyStrings (bool removeWhitespaceStrings = true);

    void move (int currentIndex, int newIndex) noexcept;

    void trim();

    void appendNumbersToDuplicates (bool ignoreCaseWhenComparing,
                                    bool appendNumberToFirstInstance,
                                    CharPointer_UTF8 preNumberString = CharPointer_UTF8 (nullptr),
                                    CharPointer_UTF8 postNumberString = CharPointer_UTF8 (nullptr));
 
    //==============================================================================
    String joinIntoString (StringRef separatorString,
                           int startIndex = 0,
                           int numberOfElements = -1) const;
 
    //==============================================================================
    void sort (bool ignoreCase);

    void sortNatural();
 
    //==============================================================================
    void ensureStorageAllocated (int minNumElements);

    void minimiseStorageOverheads();

    Array<String> strings;
 
private:
    JUCE_LEAK_DETECTOR (StringArray)
};
 
} // namespace juce