String.h

Go to the documentation of this file.

/*
  ==============================================================================
 
   This file is part of the Water library.
   Copyright (c) 2016 ROLI Ltd.
   Copyright (C) 2017-2022 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_STRING_H_INCLUDED
#define WATER_STRING_H_INCLUDED
 
#include "CharPointer_UTF8.h"
#include "../memory/Memory.h"
 
#include <limits>
#include <string>
 
namespace water {
 
//==============================================================================
class String
{
public:
    //==============================================================================
    String() noexcept;

    String (const String& other) noexcept;

    String (const char* text);

    String (const char* text, size_t maxChars);
 
    //==============================================================================
    String (const CharPointer_UTF8 text);

    String (const CharPointer_UTF8 text, size_t maxChars);

    String (const CharPointer_UTF8 start, const CharPointer_UTF8 end);
 
    //==============================================================================
    String (const std::string&);

    String (StringRef);
 
    //==============================================================================
    static String charToString (water_uchar character);

    ~String() noexcept;
 
    //==============================================================================
    int hashCode() const noexcept;

    int64 hashCode64() const noexcept;

    size_t hash() const noexcept;

    int length() const noexcept;
 
    //==============================================================================
    // Assignment and concatenation operators..

    String& operator= (const String& other) noexcept;

    String& operator+= (const String& stringToAppend);
    String& operator+= (const char* textToAppend);
    String& operator+= (StringRef textToAppend);
    String& operator+= (int numberToAppend);
    String& operator+= (long numberToAppend);
    String& operator+= (int64 numberToAppend);
    String& operator+= (uint64 numberToAppend);
    String& operator+= (char characterToAppend);
    String& operator+= (water_uchar characterToAppend);

    void append (const String& textToAppend, size_t maxCharsToTake);

    void appendCharPointer (const CharPointer_UTF8 startOfTextToAppend,
                            const CharPointer_UTF8 endOfTextToAppend);

    template <class CharPointer>
    void appendCharPointer (const CharPointer startOfTextToAppend,
                            const CharPointer endOfTextToAppend)
    {
        wassert (startOfTextToAppend.getAddress() != nullptr && endOfTextToAppend.getAddress() != nullptr);
 
        size_t extraBytesNeeded = 0, numChars = 1;
 
        for (CharPointer t (startOfTextToAppend); t != endOfTextToAppend && ! t.isEmpty(); ++numChars)
            extraBytesNeeded += CharPointer_UTF8::getBytesRequiredFor (t.getAndAdvance());
 
        if (extraBytesNeeded > 0)
        {
            const size_t byteOffsetOfNull = getByteOffsetOfEnd();
 
            preallocateBytes (byteOffsetOfNull + extraBytesNeeded);
            CharPointer_UTF8 (addBytesToPointer (text.getAddress(), (int) byteOffsetOfNull))
                .writeWithCharLimit (startOfTextToAppend, (int) numChars);
        }
    }

    void appendCharPointer (const CharPointer_UTF8 textToAppend);

    template <class CharPointer>
    void appendCharPointer (const CharPointer textToAppend, size_t maxCharsToTake)
    {
        if (textToAppend.getAddress() != nullptr)
        {
            size_t extraBytesNeeded = 0, numChars = 1;
 
            for (CharPointer t (textToAppend); numChars <= maxCharsToTake && ! t.isEmpty(); ++numChars)
                extraBytesNeeded += CharPointer_UTF8::getBytesRequiredFor (t.getAndAdvance());
 
            if (extraBytesNeeded > 0)
            {
                const size_t byteOffsetOfNull = getByteOffsetOfEnd();
 
                preallocateBytes (byteOffsetOfNull + extraBytesNeeded);
                CharPointer_UTF8 (addBytesToPointer (text.getAddress(), (int) byteOffsetOfNull))
                    .writeWithCharLimit (textToAppend, (int) numChars);
            }
        }
    }

    template <class CharPointer>
    void appendCharPointer (const CharPointer textToAppend)
    {
        appendCharPointer (textToAppend, std::numeric_limits<size_t>::max());
    }
 
    //==============================================================================
    // Comparison methods..

    inline bool isEmpty() const noexcept                    { return text.isEmpty(); }

    inline bool isNotEmpty() const noexcept                 { return ! text.isEmpty(); }

    void clear() noexcept;

    bool equalsIgnoreCase (const String& other) const noexcept;

    bool equalsIgnoreCase (StringRef other) const noexcept;

    bool equalsIgnoreCase (const char* other) const noexcept;

    int compare (const String& other) const noexcept;

    int compare (const char* other) const noexcept;

    int compareIgnoreCase (const String& other) const noexcept;

    int compareNatural (StringRef other, bool isCaseSensitive = false) const noexcept;

    bool startsWith (StringRef text) const noexcept;

    bool startsWithChar (water_uchar character) const noexcept;

    bool startsWithIgnoreCase (StringRef text) const noexcept;

    bool endsWith (StringRef text) const noexcept;

    bool endsWithChar (water_uchar character) const noexcept;

    bool endsWithIgnoreCase (StringRef text) const noexcept;

    bool contains (StringRef text) const noexcept;

    bool containsChar (water_uchar character) const noexcept;

    bool containsIgnoreCase (StringRef text) const noexcept;

    bool containsWholeWord (StringRef wordToLookFor) const noexcept;

    bool containsWholeWordIgnoreCase (StringRef wordToLookFor) const noexcept;

    int indexOfWholeWord (StringRef wordToLookFor) const noexcept;

    int indexOfWholeWordIgnoreCase (StringRef wordToLookFor) const noexcept;

    bool containsAnyOf (StringRef charactersItMightContain) const noexcept;

    bool containsOnly (StringRef charactersItMightContain) const noexcept;

    bool containsNonWhitespaceChars() const noexcept;

    bool matchesWildcard (StringRef wildcard, bool ignoreCase) const noexcept;
 
    //==============================================================================
    // Substring location methods..

    int indexOfChar (water_uchar characterToLookFor) const noexcept;

    int indexOfChar (int startIndex, water_uchar characterToLookFor) const noexcept;

    int indexOfAnyOf (StringRef charactersToLookFor,
                      int startIndex = 0,
                      bool ignoreCase = false) const noexcept;

    int indexOf (StringRef textToLookFor) const noexcept;

    int indexOf (int startIndex, StringRef textToLookFor) const noexcept;

    int indexOfIgnoreCase (StringRef textToLookFor) const noexcept;

    int indexOfIgnoreCase (int startIndex, StringRef textToLookFor) const noexcept;

    int lastIndexOfChar (water_uchar character) const noexcept;

    int lastIndexOf (StringRef textToLookFor) const noexcept;

    int lastIndexOfIgnoreCase (StringRef textToLookFor) const noexcept;

    int lastIndexOfAnyOf (StringRef charactersToLookFor,
                          bool ignoreCase = false) const noexcept;
 
 
    //==============================================================================
    // Substring extraction and manipulation methods..

    water_uchar operator[] (int index) const noexcept;

    water_uchar getLastCharacter() const noexcept;
 
    //==============================================================================
    String substring (int startIndex, int endIndex) const;

    String substring (int startIndex) const;

    String dropLastCharacters (int numberToDrop) const;

    String getLastCharacters (int numCharacters) const;
 
    //==============================================================================
    String fromFirstOccurrenceOf (StringRef substringToStartFrom,
                                  bool includeSubStringInResult,
                                  bool ignoreCase) const;

    String fromLastOccurrenceOf (StringRef substringToFind,
                                 bool includeSubStringInResult,
                                 bool ignoreCase) const;

    String upToFirstOccurrenceOf (StringRef substringToEndWith,
                                  bool includeSubStringInResult,
                                  bool ignoreCase) const;

    String upToLastOccurrenceOf (StringRef substringToFind,
                                 bool includeSubStringInResult,
                                 bool ignoreCase) const;
 
    //==============================================================================
    String trim() const;

    String trimStart() const;

    String trimEnd() const;

    String trimCharactersAtStart (StringRef charactersToTrim) const;

    String trimCharactersAtEnd (StringRef charactersToTrim) const;
 
    //==============================================================================
    String toUpperCase() const;

    String toLowerCase() const;
 
    //==============================================================================
    String replaceSection (int startIndex,
                           int numCharactersToReplace,
                           StringRef stringToInsert) const;

    String replace (StringRef stringToReplace,
                    StringRef stringToInsertInstead,
                    bool ignoreCase = false) const;

    String replaceCharacter (water_uchar characterToReplace,
                             water_uchar characterToInsertInstead) const;

    String replaceCharacters (StringRef charactersToReplace,
                              StringRef charactersToInsertInstead) const;

    String retainCharacters (StringRef charactersToRetain) const;

    String removeCharacters (StringRef charactersToRemove) const;

    String initialSectionContainingOnly (StringRef permittedCharacters) const;

    String initialSectionNotContaining (StringRef charactersToStopAt) const;
 
    //==============================================================================
    bool isQuotedString() const;

    String unquoted() const;

    String quoted (water_uchar quoteCharacter = '"') const;
 
    //==============================================================================
    static String repeatedString (StringRef stringToRepeat,
                                  int numberOfTimesToRepeat);

    String paddedLeft (water_uchar padCharacter, int minimumLength) const;

    String paddedRight (water_uchar padCharacter, int minimumLength) const;

    static String createStringFromData (const void* data, int size);

    static String formatted (const String formatString, ... );
 
    //==============================================================================
    // Numeric conversions..

    explicit String (int decimalInteger);

    explicit String (unsigned int decimalInteger);

    explicit String (short decimalInteger);

    explicit String (unsigned short decimalInteger);

    explicit String (int64 largeIntegerValue);

    explicit String (uint64 largeIntegerValue);

    explicit String (long decimalInteger);

    explicit String (unsigned long decimalInteger);

    explicit String (float floatValue);

    explicit String (double doubleValue);

    String (float floatValue, int numberOfDecimalPlaces);

    String (double doubleValue, int numberOfDecimalPlaces);

    int getIntValue() const noexcept;

    int64 getLargeIntValue() const noexcept;

    int getTrailingIntValue() const noexcept;

    float getFloatValue() const noexcept;

    double getDoubleValue() const noexcept;

    int getHexValue32() const noexcept;

    int64 getHexValue64() const noexcept;

    static String toHexString (int number);

    static String toHexString (int64 number);

    static String toHexString (short number);

    static String toHexString (const void* data, int size, int groupSize = 1);
 
    //==============================================================================
    inline CharPointer_UTF8 getCharPointer() const noexcept      { return text; }

    CharPointer_UTF8 toUTF8() const;
 
   #ifdef CARLA_OS_WIN
    std::wstring toUTF16() const;
   #endif

    const char* toRawUTF8() const;

    std::string toStdString() const;
 
    //==============================================================================
    static String fromUTF8 (const char* utf8buffer, int bufferSizeBytes = -1);

    size_t getNumBytesAsUTF8() const noexcept;
 
    //==============================================================================
    size_t copyToUTF8 (CharPointer_UTF8::CharType* destBuffer, size_t maxBufferSizeBytes) const noexcept;
 
    //==============================================================================
    void preallocateBytes (size_t numBytesNeeded);

    void swapWith (String& other) noexcept;
 
    //==============================================================================
   #if 0 //def CARLA_OS_MAC
    static String fromCFString (CFStringRef cfString);

    CFStringRef toCFString() const;
   #endif
 
   #ifdef CARLA_OS_MAC
    String convertToPrecomposedUnicode() const;
   #endif

    int getReferenceCount() const noexcept;
 
private:
    //==============================================================================
    CharPointer_UTF8 text;
 
    //==============================================================================
    struct PreallocationBytes
    {
        explicit PreallocationBytes (size_t) noexcept;
        size_t numBytes;
    };
 
    explicit String (const PreallocationBytes&); // This constructor preallocates a certain amount of memory
    size_t getByteOffsetOfEnd() const noexcept;
};
 
//==============================================================================
String operator+ (const char* string1, const String& string2);
String operator+ (char string1, const String& string2);
String operator+ (water_uchar string1, const String& string2);

String operator+ (String string1, const String& string2);
String operator+ (String string1, const char* string2);
String operator+ (String string1, char characterToAppend);
String operator+ (String string1, water_uchar characterToAppend);
 
//==============================================================================
String& operator<< (String& string1, char characterToAppend);
String& operator<< (String& string1, water_uchar characterToAppend);

String& operator<< (String& string1, const char* string2);
String& operator<< (String& string1, const String& string2);
String& operator<< (String& string1, StringRef string2);

String& operator<< (String& string1, short number);
String& operator<< (String& string1, int number);
String& operator<< (String& string1, long number);
String& operator<< (String& string1, int64 number);
String& operator<< (String& string1, uint64 number);
String& operator<< (String& string1, float number);
String& operator<< (String& string1, double number);
 
//==============================================================================
bool operator== (const String& string1, const String& string2) noexcept;
bool operator== (const String& string1, const char* string2) noexcept;
bool operator== (const String& string1, const CharPointer_UTF8 string2) noexcept;

bool operator!= (const String& string1, const String& string2) noexcept;
bool operator!= (const String& string1, const char* string2) noexcept;
bool operator!= (const String& string1, const CharPointer_UTF8 string2) noexcept;

bool operator>  (const String& string1, const String& string2) noexcept;
bool operator<  (const String& string1, const String& string2) noexcept;
bool operator>= (const String& string1, const String& string2) noexcept;
bool operator<= (const String& string1, const String& string2) noexcept;
 
//==============================================================================
template <class traits>
std::basic_ostream <char, traits>& operator<< (std::basic_ostream <char, traits>& stream, const String& stringToWrite)
{
    return stream << stringToWrite.toRawUTF8();
}

OutputStream& operator<< (OutputStream& stream, const String& stringToWrite);

OutputStream& operator<< (OutputStream& stream, StringRef stringToWrite);
 
//==============================================================================
struct StartEndString {
    StartEndString (CharPointer_UTF8 s, CharPointer_UTF8 e) noexcept : start (s), end (e) {}
    operator String() const   { return String (start, end); }
    CharPointer_UTF8 start, end;
};
 
}
 
#include "StringRef.h"
 
#endif // WATER_STRING_H_INCLUDED