juce_String.h

Go to the documentation of this file.

/*
  ==============================================================================
 
   This file is part of the juce_core module of the JUCE library.
   Copyright (c) 2015 - ROLI Ltd.
 
   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 THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD
   TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN
   NO EVENT SHALL THE AUTHOR 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.
 
   ------------------------------------------------------------------------------
 
   NOTE! This permissive ISC license applies ONLY to files within the juce_core module!
   All other JUCE modules are covered by a dual GPL/commercial license, so if you are
   using any other modules, be sure to check that you also comply with their license.
 
   For more details, visit www.juce.com
 
  ==============================================================================
*/
 
#ifndef JUCE_STRING_H_INCLUDED
#define JUCE_STRING_H_INCLUDED
 
 
//==============================================================================
class JUCE_API  String
{
public:
    //==============================================================================
    String() noexcept;
 
    String (const String& other) noexcept;
 
   #if JUCE_COMPILER_SUPPORTS_MOVE_SEMANTICS
    String (String&& other) noexcept;
   #endif
 
    String (const char* text);
 
    String (const char* text, size_t maxChars);
 
    String (const wchar_t* text);
 
    String (const wchar_t* 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 CharPointer_UTF16 text);
 
    String (const CharPointer_UTF16 text, size_t maxChars);
 
    String (const CharPointer_UTF16 start, const CharPointer_UTF16 end);
 
    //==============================================================================
    String (const CharPointer_UTF32 text);
 
    String (const CharPointer_UTF32 text, size_t maxChars);
 
    String (const CharPointer_UTF32 start, const CharPointer_UTF32 end);
 
    //==============================================================================
    String (const CharPointer_ASCII text);
 
    String (const std::string&);
 
    //==============================================================================
    static String charToString (juce_wchar character);
 
    ~String() noexcept;
 
    //==============================================================================
    static const String empty;
 
   #if (JUCE_STRING_UTF_TYPE == 32)
    typedef CharPointer_UTF32 CharPointerType;
   #elif (JUCE_STRING_UTF_TYPE == 16)
    typedef CharPointer_UTF16 CharPointerType;
   #elif (DOXYGEN || JUCE_STRING_UTF_TYPE == 8)
    typedef CharPointer_UTF8  CharPointerType;
   #else
    #error "You must set the value of JUCE_STRING_UTF_TYPE to be either 8, 16, or 32!"
   #endif
 
    //==============================================================================
    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;
 
   #if JUCE_COMPILER_SUPPORTS_MOVE_SEMANTICS
    String& operator= (String&& other) noexcept;
   #endif
 
    String& operator+= (const String& stringToAppend);
    String& operator+= (const char* textToAppend);
    String& operator+= (const wchar_t* textToAppend);
    String& operator+= (int numberToAppend);
    String& operator+= (int64 numberToAppend);
    String& operator+= (char characterToAppend);
    String& operator+= (wchar_t characterToAppend);
   #if ! JUCE_NATIVE_WCHAR_IS_UTF32
 
    String& operator+= (juce_wchar characterToAppend);
   #endif
 
    void append (const String& textToAppend, size_t maxCharsToTake);
 
    void appendCharPointer (const CharPointerType startOfTextToAppend,
                            const CharPointerType endOfTextToAppend);
 
    template <class CharPointer>
    void appendCharPointer (const CharPointer startOfTextToAppend,
                            const CharPointer endOfTextToAppend)
    {
        jassert (startOfTextToAppend.getAddress() != nullptr && endOfTextToAppend.getAddress() != nullptr);
 
        size_t extraBytesNeeded = 0, numChars = 1;
 
        for (CharPointer t (startOfTextToAppend); t != endOfTextToAppend && ! t.isEmpty(); ++numChars)
            extraBytesNeeded += CharPointerType::getBytesRequiredFor (t.getAndAdvance());
 
        if (extraBytesNeeded > 0)
        {
            const size_t byteOffsetOfNull = getByteOffsetOfEnd();
 
            preallocateBytes (byteOffsetOfNull + extraBytesNeeded);
            CharPointerType (addBytesToPointer (text.getAddress(), (int) byteOffsetOfNull))
                .writeWithCharLimit (startOfTextToAppend, (int) numChars);
        }
    }
 
    void appendCharPointer (const CharPointerType 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 += CharPointerType::getBytesRequiredFor (t.getAndAdvance());
 
            if (extraBytesNeeded > 0)
            {
                const size_t byteOffsetOfNull = getByteOffsetOfEnd();
 
                preallocateBytes (byteOffsetOfNull + extraBytesNeeded);
                CharPointerType (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 wchar_t* 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 compare (const wchar_t* other) const noexcept;
 
    int compareIgnoreCase (const String& other) const noexcept;
 
    int compareNatural (StringRef other) const noexcept;
 
    bool startsWith (StringRef text) const noexcept;
 
    bool startsWithChar (juce_wchar character) const noexcept;
 
    bool startsWithIgnoreCase (StringRef text) const noexcept;
 
    bool endsWith (StringRef text) const noexcept;
 
    bool endsWithChar (juce_wchar character) const noexcept;
 
    bool endsWithIgnoreCase (StringRef text) const noexcept;
 
    bool contains (StringRef text) const noexcept;
 
    bool containsChar (juce_wchar 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 (juce_wchar characterToLookFor) const noexcept;
 
    int indexOfChar (int startIndex, juce_wchar 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 (juce_wchar 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..
 
    juce_wchar operator[] (int index) const noexcept;
 
    juce_wchar 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 (juce_wchar characterToReplace,
                             juce_wchar 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 (juce_wchar quoteCharacter = '"') const;
 
 
    //==============================================================================
    static String repeatedString (StringRef stringToRepeat,
                                  int numberOfTimesToRepeat);
 
    String paddedLeft (juce_wchar padCharacter, int minimumLength) const;
 
    String paddedRight (juce_wchar 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 (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 CharPointerType getCharPointer() const noexcept      { return text; }
 
    CharPointer_UTF8 toUTF8() const;
 
    const char* toRawUTF8() const;
 
    CharPointer_UTF16 toUTF16() const;
 
    CharPointer_UTF32 toUTF32() const;
 
    const wchar_t* toWideCharPointer() 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;
 
    size_t copyToUTF16 (CharPointer_UTF16::CharType* destBuffer, size_t maxBufferSizeBytes) const noexcept;
 
    size_t copyToUTF32 (CharPointer_UTF32::CharType* destBuffer, size_t maxBufferSizeBytes) const noexcept;
 
    //==============================================================================
    void preallocateBytes (size_t numBytesNeeded);
 
    void swapWith (String& other) noexcept;
 
    //==============================================================================
   #if JUCE_MAC || JUCE_IOS || DOXYGEN
 
    static String fromCFString (CFStringRef cfString);
 
    CFStringRef toCFString() const;
 
    String convertToPrecomposedUnicode() const;
   #endif
 
    int getReferenceCount() const noexcept;
 
private:
    //==============================================================================
    CharPointerType 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;
    JUCE_DEPRECATED (String (const String&, size_t));
 
    // This private cast operator should prevent strings being accidentally cast
    // to bools (this is possible because the compiler can add an implicit cast
    // via a const char*)
    operator bool() const noexcept  { return false; }
};
 
//==============================================================================
JUCE_API String JUCE_CALLTYPE operator+ (const char* string1,     const String& string2);
JUCE_API String JUCE_CALLTYPE operator+ (const wchar_t* string1,  const String& string2);
JUCE_API String JUCE_CALLTYPE operator+ (char string1,            const String& string2);
JUCE_API String JUCE_CALLTYPE operator+ (wchar_t string1,         const String& string2);
#if ! JUCE_NATIVE_WCHAR_IS_UTF32
 
JUCE_API String JUCE_CALLTYPE operator+ (juce_wchar string1,      const String& string2);
#endif
 
JUCE_API String JUCE_CALLTYPE operator+ (String string1, const String& string2);
JUCE_API String JUCE_CALLTYPE operator+ (String string1, const char* string2);
JUCE_API String JUCE_CALLTYPE operator+ (String string1, const wchar_t* string2);
JUCE_API String JUCE_CALLTYPE operator+ (String string1, char characterToAppend);
JUCE_API String JUCE_CALLTYPE operator+ (String string1, wchar_t characterToAppend);
#if ! JUCE_NATIVE_WCHAR_IS_UTF32
 
JUCE_API String JUCE_CALLTYPE operator+ (String string1, juce_wchar characterToAppend);
#endif
 
//==============================================================================
JUCE_API String& JUCE_CALLTYPE operator<< (String& string1, char characterToAppend);
JUCE_API String& JUCE_CALLTYPE operator<< (String& string1, wchar_t characterToAppend);
#if ! JUCE_NATIVE_WCHAR_IS_UTF32
 
JUCE_API String& JUCE_CALLTYPE operator<< (String& string1, juce_wchar characterToAppend);
#endif
 
JUCE_API String& JUCE_CALLTYPE operator<< (String& string1, const char* string2);
JUCE_API String& JUCE_CALLTYPE operator<< (String& string1, const wchar_t* string2);
JUCE_API String& JUCE_CALLTYPE operator<< (String& string1, const String& string2);
 
JUCE_API String& JUCE_CALLTYPE operator<< (String& string1, short number);
JUCE_API String& JUCE_CALLTYPE operator<< (String& string1, int number);
JUCE_API String& JUCE_CALLTYPE operator<< (String& string1, long number);
JUCE_API String& JUCE_CALLTYPE operator<< (String& string1, int64 number);
JUCE_API String& JUCE_CALLTYPE operator<< (String& string1, uint64 number);
JUCE_API String& JUCE_CALLTYPE operator<< (String& string1, float number);
JUCE_API String& JUCE_CALLTYPE operator<< (String& string1, double number);
 
//==============================================================================
JUCE_API bool JUCE_CALLTYPE operator== (const String& string1, const String& string2) noexcept;
JUCE_API bool JUCE_CALLTYPE operator== (const String& string1, const char* string2) noexcept;
JUCE_API bool JUCE_CALLTYPE operator== (const String& string1, const wchar_t* string2) noexcept;
JUCE_API bool JUCE_CALLTYPE operator== (const String& string1, const CharPointer_UTF8 string2) noexcept;
JUCE_API bool JUCE_CALLTYPE operator== (const String& string1, const CharPointer_UTF16 string2) noexcept;
JUCE_API bool JUCE_CALLTYPE operator== (const String& string1, const CharPointer_UTF32 string2) noexcept;
 
JUCE_API bool JUCE_CALLTYPE operator!= (const String& string1, const String& string2) noexcept;
JUCE_API bool JUCE_CALLTYPE operator!= (const String& string1, const char* string2) noexcept;
JUCE_API bool JUCE_CALLTYPE operator!= (const String& string1, const wchar_t* string2) noexcept;
JUCE_API bool JUCE_CALLTYPE operator!= (const String& string1, const CharPointer_UTF8 string2) noexcept;
JUCE_API bool JUCE_CALLTYPE operator!= (const String& string1, const CharPointer_UTF16 string2) noexcept;
JUCE_API bool JUCE_CALLTYPE operator!= (const String& string1, const CharPointer_UTF32 string2) noexcept;
 
JUCE_API bool JUCE_CALLTYPE operator>  (const String& string1, const String& string2) noexcept;
JUCE_API bool JUCE_CALLTYPE operator<  (const String& string1, const String& string2) noexcept;
JUCE_API bool JUCE_CALLTYPE operator>= (const String& string1, const String& string2) noexcept;
JUCE_API bool JUCE_CALLTYPE operator<= (const String& string1, const String& string2) noexcept;
 
//==============================================================================
template <class traits>
std::basic_ostream <char, traits>& JUCE_CALLTYPE operator<< (std::basic_ostream <char, traits>& stream, const String& stringToWrite)
{
    return stream << stringToWrite.toRawUTF8();
}
 
template <class traits>
std::basic_ostream <wchar_t, traits>& JUCE_CALLTYPE operator<< (std::basic_ostream <wchar_t, traits>& stream, const String& stringToWrite)
{
    return stream << stringToWrite.toWideCharPointer();
}
 
JUCE_API OutputStream& JUCE_CALLTYPE operator<< (OutputStream& stream, const String& stringToWrite);
 
JUCE_API OutputStream& JUCE_CALLTYPE operator<< (OutputStream& stream, StringRef stringToWrite);
 
 
#endif   // JUCE_STRING_H_INCLUDED