StringArray.h

Go to the documentation of this file.

/*
  ==============================================================================
 
   This file is part of the Water library.
   Copyright (c) 2016 ROLI Ltd.
   Copyright (C) 2017 Filipe Coelho <falktx@falktx.com>
 
   Permission is granted to use this software 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.
 
   THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH REGARD
   TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
   FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT,
   OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
   USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
   TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
   OF THIS SOFTWARE.
 
  ==============================================================================
*/
 
#ifndef WATER_STRINGARRAY_H_INCLUDED
#define WATER_STRINGARRAY_H_INCLUDED
 
#include "String.h"
#include "../containers/Array.h"
 
namespace water {
 
//==============================================================================
class StringArray
{
public:
    //==============================================================================
    StringArray() noexcept;

    StringArray (const StringArray&);

    explicit StringArray (const String& firstValue);

    StringArray (const String* strings, int numberOfStrings);

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

    explicit StringArray (const char* const* strings);

    ~StringArray();

    StringArray& operator= (const StringArray&);

    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;

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

    inline 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;
 
    //==============================================================================
    bool add (const String& stringToAdd);

    bool insert (int index, const String& stringToAdd);

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

    void set (int index, const String& newString);

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

    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 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;
};
 
}
 
#endif // WATER_STRINGARRAY_H_INCLUDED