QoreString.h

/* -*- mode: c++; indent-tabs-mode: nil -*- */
/*
    QoreString.h
 
    QoreString Class Definition
 
    Qore Programming Language
 
    Copyright (C) 2003 - 2024 Qore Technologies, s.r.o.
 
    Permission is hereby granted, free of charge, to any person obtaining a
    copy of this software and associated documentation files (the "Software"),
    to deal in the Software without restriction, including without limitation
    the rights to use, copy, modify, merge, publish, distribute, sublicense,
    and/or sell copies of the Software, and to permit persons to whom the
    Software is furnished to do so, subject to the following conditions:
 
    The above copyright notice and this permission notice shall be included in
    all copies or substantial portions of the Software.
 
    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
    DEALINGS IN THE SOFTWARE.
 
    Note that the Qore library is released under a choice of three open-source
    licenses: MIT (as above), LGPL 2+, or GPL 2+; see README-LICENSE for more
    information.
*/
 
#ifndef _QORE_QORESTRING_H
 
#define _QORE_QORESTRING_H
 
#include <cstdarg>
#include <string>
 
class DateTime;
class BinaryNode;
 
 
#define CE_HTML (1 << 0)
#define CE_XML  (1 << 1)
#define CE_NONASCII (1 << 2)
#define CE_XHTML (CE_HTML | CE_XML)
#define CE_ALL (CE_XHTML | CE_NONASCII)
 
 
#define CD_HTML (1 << 0)
#define CD_XML  (1 << 1)
#define CD_NUM_REF (1 << 2)
#define CD_XHTML (CD_HTML | CD_XML)
#define CD_ALL (CD_XHTML | CD_NUM_REF)
 
 
#define QS_RE_GLOBAL    (1 << 0)
#define QS_RE_CASELESS  (1 << 1)
#define QS_RE_DOTALL    (1 << 2)
#define QS_RE_EXTENDED  (1 << 3)
#define QS_RE_MULTILINE (1 << 4)
 
 
class QoreString {
    friend hashdecl qore_string_private;
 
public:
    DLLEXPORT QoreString();
 
    DLLEXPORT QoreString(bool b);
 
    DLLEXPORT QoreString(const char* str);
 
    DLLEXPORT QoreString(const char* str, const QoreEncoding* new_qorecharset);
 
    DLLEXPORT QoreString(const QoreEncoding* new_qorecharset);
 
    DLLEXPORT QoreString(const char* str, size_t len, const QoreEncoding* new_qorecharset = QCS_DEFAULT);
 
    DLLEXPORT QoreString(const std::string& str, const QoreEncoding* new_encoding = QCS_DEFAULT);
 
    DLLEXPORT QoreString(char c);
 
    DLLEXPORT QoreString(const QoreString& str);
 
    DLLEXPORT QoreString(const QoreString* str);
 
    DLLEXPORT QoreString(const QoreString* str, size_t len);
 
    DLLEXPORT QoreString(int64 i);
 
    DLLEXPORT QoreString(double f);
 
    DLLEXPORT QoreString(const DateTime* date);
 
    DLLEXPORT QoreString(const BinaryNode* bin);
 
    DLLEXPORT QoreString(const BinaryNode* bin, size_t maxlinelen);
 
    DLLEXPORT QoreString(char* nbuf, size_t nlen, size_t nallocated, const QoreEncoding* enc);
 
    DLLEXPORT ~QoreString();
 
 
    DLLEXPORT size_t length() const;
 
    DLLEXPORT void set(const char* str, const QoreEncoding* new_qorecharset = QCS_DEFAULT);
 
 
    DLLEXPORT void set(const char* str, size_t len);
 
    DLLEXPORT void set(const std::string& str, const QoreEncoding* new_qorecharset = QCS_DEFAULT);
 
    DLLEXPORT void set(const QoreString* str);
 
    DLLEXPORT void set(const QoreString& str);
 
    DLLEXPORT void set(char* nbuf, size_t nlen, size_t nallocated, const QoreEncoding* enc);
 
    DLLEXPORT void setEncoding(const QoreEncoding* new_encoding);
 
 
    DLLEXPORT int concatEncode(ExceptionSink* xsink, const QoreString& str, unsigned code = CE_XHTML);
 
 
    DLLEXPORT int concatDecode(ExceptionSink* xsink, const QoreString& str, unsigned code = CD_ALL);
 
 
    DLLEXPORT void concatAndHTMLEncode(const char* str);
 
 
    DLLEXPORT void concatAndHTMLDecode(const QoreString* str);
 
 
    DLLEXPORT void concatAndHTMLDecode(const char* str, size_t slen);
 
 
    DLLEXPORT void concatAndHTMLDecode(const char* str);
 
 
    DLLEXPORT void concatDecodeUrl(const char* url);
 
    DLLEXPORT int concatDecodeUrl(const QoreString& url, ExceptionSink* xsink);
 
 
    DLLEXPORT int concatEncodeUrl(ExceptionSink* xsink, const QoreString& url, bool encode_all = false);
 
 
    DLLEXPORT int concatDecodeUriRequest(const QoreString& url, ExceptionSink* xsink);
 
 
    DLLEXPORT int concatEncodeUriRequest(ExceptionSink* xsink, const QoreString& url);
 
    DLLEXPORT void concatEscape(const QoreString* str, char c, char esc_char, ExceptionSink* xsink);
 
    DLLEXPORT void concatEscape(const char* str, char c, char esc_char = '\\');
 
 
    DLLEXPORT void concatAndHTMLEncode(const QoreString* str, ExceptionSink* xsink);
 
    DLLEXPORT void concat(const QoreString* str, ExceptionSink* xsink);
 
 
    DLLEXPORT int concat(const QoreString& str, qore_offset_t pos, ExceptionSink* xsink);
 
 
    DLLEXPORT int concat(const QoreString& str, qore_offset_t pos, qore_offset_t len, ExceptionSink* xsink);
 
 
    DLLEXPORT void concat(const QoreString* str, size_t size, ExceptionSink* xsink);
 
    DLLEXPORT void concatBase64(const char* buf, size_t size);
 
    DLLEXPORT void concatBase64(const BinaryNode* bin);
 
 
    DLLEXPORT void concatBase64(const QoreString* str);
 
 
    DLLEXPORT void concatBase64(const char* buf, size_t size, size_t maxlinelen);
 
 
    DLLEXPORT void concatBase64(const BinaryNode* bin, size_t maxlinelen);
 
 
    DLLEXPORT void concatBase64(const QoreString* str, size_t maxlinelen);
 
 
    DLLEXPORT void concatBase64Url(const BinaryNode& bin);
 
 
    DLLEXPORT void concatBase64Url(const QoreString& str);
 
 
    DLLEXPORT BinaryNode* parseBase64(ExceptionSink* xsink) const;
 
 
    DLLEXPORT QoreString* parseBase64ToString(ExceptionSink* xsink) const;
 
 
    DLLEXPORT QoreString* parseBase64ToString(const QoreEncoding* enc, ExceptionSink* xsink) const;
 
 
    DLLEXPORT BinaryNode* parseBase64Url(ExceptionSink* xsink) const;
 
 
    DLLEXPORT QoreString* parseBase64UrlToString(ExceptionSink* xsink) const;
 
 
    DLLEXPORT QoreString* parseBase64UrlToString(const QoreEncoding* enc, ExceptionSink* xsink) const;
 
 
    DLLEXPORT void concatHex(const char* buf, size_t size);
 
    DLLEXPORT void concatHex(const BinaryNode* bin);
 
    DLLEXPORT void concatHex(const QoreString* str);
 
 
    DLLEXPORT BinaryNode* parseHex(ExceptionSink* xsink) const;
 
    DLLEXPORT void concat(const DateTime* d);
 
    DLLEXPORT void concatISO8601DateTime(const DateTime* d);
 
    DLLEXPORT void concat(const char* str);
 
    DLLEXPORT void concat(const std::string& str);
 
    DLLEXPORT void concat(const char* str, size_t size);
 
    DLLEXPORT void concat(const char c);
 
 
    DLLEXPORT int compareSoft(const QoreString* str, ExceptionSink* xsink) const;
 
 
    DLLEXPORT int compare(const QoreString* str) const;
 
 
    DLLEXPORT int compare(const char* str) const;
 
 
    DLLEXPORT bool equal(const QoreString& str) const;
 
 
    DLLEXPORT bool equal(const char* str) const;
 
 
    DLLEXPORT bool equalSoft(const QoreString& str, ExceptionSink* xsink) const;
 
 
    DLLEXPORT bool equalPartial(const QoreString& str) const;
 
 
    DLLEXPORT bool equalPartial(const char* str) const;
 
 
    DLLEXPORT bool equalPartialSoft(const QoreString& str, ExceptionSink* xsink) const;
 
 
    DLLEXPORT bool equalPartialPath(const QoreString& str, ExceptionSink* xsink) const;
 
 
    DLLEXPORT bool startsWith(const char* str) const;
 
 
    DLLEXPORT bool startsWith(const std::string& str) const;
 
 
    DLLEXPORT bool endsWith(const char* str) const;
 
 
    DLLEXPORT bool endsWith(const std::string& str) const;
 
    DLLEXPORT void terminate(size_t size);
 
 
    DLLEXPORT void reserve(size_t size);
 
 
    DLLEXPORT int sprintf(const char* fmt, ...);
 
 
    DLLEXPORT int vsprintf(const char* fmt, va_list args);
 
 
    DLLEXPORT void take(char* str);
 
    DLLEXPORT void take(char* str, const QoreEncoding* enc);
 
    DLLEXPORT void take(char* str, size_t size);
 
    DLLEXPORT void take(char* str, size_t size, const QoreEncoding* enc);
 
    DLLEXPORT void takeAndTerminate(char* str, size_t size);
 
    DLLEXPORT void takeAndTerminate(char* str, size_t size, const QoreEncoding* enc);
 
 
    DLLEXPORT QoreString* convertEncoding(const QoreEncoding* nccs, ExceptionSink* xsink) const;
 
 
    DLLEXPORT char* giveBuffer();
 
    DLLEXPORT void clear();
 
 
    DLLEXPORT void reset();
 
 
    DLLEXPORT void replaceAll(const char* old_str, const char* new_str);
 
 
    DLLEXPORT void replace(size_t offset, size_t len, const char* str);
 
 
    DLLEXPORT void replace(size_t offset, size_t len, const QoreString* str, ExceptionSink* xsink);
 
 
    DLLEXPORT void replaceChar(size_t offset, char c);
 
 
    DLLEXPORT void splice(qore_offset_t offset, ExceptionSink* xsink);
 
 
    DLLEXPORT void splice(qore_offset_t offset, qore_offset_t length, ExceptionSink* xsink);
 
 
    DLLEXPORT void splice(qore_offset_t offset, qore_offset_t length, QoreValue strn, ExceptionSink* xsink);
 
 
    DLLEXPORT void splice(qore_offset_t offset, qore_offset_t length, const QoreString& str, ExceptionSink* xsink);
 
 
    DLLEXPORT QoreString* extract(qore_offset_t offset, ExceptionSink* xsink);
 
 
    DLLEXPORT QoreString* extract(qore_offset_t offset, qore_offset_t length, ExceptionSink* xsink);
 
 
    DLLEXPORT QoreString* extract(qore_offset_t offset, qore_offset_t length, QoreValue strn, ExceptionSink* xsink);
 
 
    DLLEXPORT QoreString* substr(qore_offset_t offset, ExceptionSink* xsink) const;
 
 
    DLLEXPORT QoreString* substr(qore_offset_t offset, qore_offset_t length, ExceptionSink* xsink) const;
 
 
    DLLEXPORT QoreString* regexSubst(QoreString& match, QoreString& subst, int opts, ExceptionSink* xsink) const;
 
 
    DLLEXPORT int regexSubst(QoreString& output, QoreString& match, QoreString& subst, int opts,
            ExceptionSink* xsink) const;
 
 
    DLLEXPORT int regexSubstInPlace(QoreString& match, QoreString& subst, int opts, ExceptionSink* xsink) const;
 
 
    DLLEXPORT QoreListNode* split(const char* sep, bool with_separator = false);
 
 
    DLLEXPORT QoreListNode* split(ExceptionSink* xsink, const char* sep, const char* quote,
            bool trim_unquoted = false);
 
    DLLEXPORT size_t chomp();
 
    DLLEXPORT const QoreEncoding* getEncoding() const;
 
    DLLEXPORT QoreString* copy() const;
 
 
    DLLEXPORT void tolwr();
 
 
    DLLEXPORT void toupr();
 
    DLLEXPORT size_t strlen() const;
 
    DLLEXPORT size_t size() const;
 
    DLLEXPORT size_t capacity() const;
 
    DLLEXPORT const char* getBuffer() const;
 
    DLLEXPORT const char* c_str() const;
 
 
    DLLEXPORT void allocate(unsigned requested_size);
 
 
    DLLEXPORT int insertch(char c, size_t pos, unsigned times);
 
 
    DLLEXPORT int insert(const char* str, size_t pos);
 
    DLLEXPORT void addch(char c, unsigned times);
 
 
    DLLEXPORT void concatUTF8FromUnicode(unsigned code);
 
 
    DLLEXPORT int concatUnicode(unsigned code, ExceptionSink* xsink);
 
 
    DLLEXPORT int concatUnicode(unsigned code);
 
 
    DLLEXPORT QoreString* reverse() const;
 
 
    DLLEXPORT void trim_trailing(const char* chars = 0);
 
 
    DLLEXPORT void trim_leading(const char* chars = 0);
 
 
    DLLEXPORT void trim(const char* chars = 0);
 
 
    DLLEXPORT void trim_trailing(char c);
 
 
    DLLEXPORT void trim_single_trailing(char c);
 
 
    DLLEXPORT void trim_leading(char c);
 
 
    DLLEXPORT void trim_single_leading(char c);
 
 
    DLLEXPORT void trim(char c);
 
 
    DLLEXPORT int trim(ExceptionSink* xsink, const QoreString* chars = nullptr);
 
 
    DLLEXPORT int trimLeading(ExceptionSink* xsink, const QoreString* chars = nullptr);
 
 
    DLLEXPORT int trimTrailing(ExceptionSink* xsink, const QoreString* chars = nullptr);
 
 
    DLLEXPORT unsigned int getUnicodePointFromUTF8(qore_offset_t offset = 0) const;
 
 
    DLLEXPORT unsigned int getUnicodePoint(qore_offset_t offset, ExceptionSink* xsink) const;
 
 
    DLLEXPORT unsigned int getUnicodePointFromBytePos(size_t offset, unsigned& len, ExceptionSink* xsink) const;
 
    DLLEXPORT void prepend(const char* str);
 
    DLLEXPORT void prepend(const char* str, size_t size);
 
    DLLEXPORT QoreString& operator=(const QoreString& other);
 
    DLLEXPORT QoreString& operator=(const char* other);
 
    DLLEXPORT QoreString& operator=(const std::string& other);
 
    DLLEXPORT bool operator==(const QoreString& other) const;
 
    DLLEXPORT bool operator==(const std::string& other) const;
 
    DLLEXPORT bool operator==(const char* other) const;
 
    DLLLOCAL bool operator!=(const QoreString& other) const {
        return !(*this == other);
    }
 
    DLLLOCAL bool operator!=(const std::string& other) const {
        return !(*this == other);
    }
 
    DLLLOCAL bool operator!=(const char* other) const {
        return !(*this == other);
    }
 
 
    DLLEXPORT int operator[](qore_offset_t pos) const;
 
    DLLEXPORT QoreString& operator+=(const char* str);
 
    DLLEXPORT QoreString& operator+=(const std::string& str);
 
    DLLEXPORT bool empty() const;
 
    DLLEXPORT qore_offset_t index(const QoreString& needle, qore_offset_t pos, ExceptionSink* xsink) const;
 
    DLLEXPORT qore_offset_t bindex(const QoreString& needle, qore_offset_t pos = 0) const;
 
    DLLEXPORT qore_offset_t bindex(const char* needle, qore_offset_t pos = 0) const;
 
    DLLEXPORT qore_offset_t bindex(const std::string& needle, qore_offset_t pos = 0) const;
 
 
    DLLEXPORT qore_offset_t rindex(const QoreString& needle, qore_offset_t pos, ExceptionSink* xsink) const;
 
    DLLEXPORT qore_offset_t brindex(const QoreString& needle, qore_offset_t pos = -1) const;
 
    DLLEXPORT qore_offset_t brindex(const char* needle, qore_offset_t pos = -1) const;
 
    DLLEXPORT qore_offset_t brindex(const std::string& needle, qore_offset_t pos = -1) const;
 
    DLLEXPORT qore_offset_t find(char c, qore_offset_t pos = 0) const;
 
    DLLEXPORT qore_offset_t rfind(char c, qore_offset_t pos = -1) const;
 
 
    DLLEXPORT qore_offset_t find(const char* str, qore_offset_t pos = 0) const;
 
 
    DLLEXPORT qore_offset_t rfind(const char* str, qore_offset_t pos = -1) const;
 
 
    DLLEXPORT qore_offset_t find(const std::string& str, qore_offset_t pos = 0) const;
 
 
    DLLEXPORT qore_offset_t rfind(const std::string& str, qore_offset_t pos = -1) const;
 
    DLLEXPORT qore_offset_t findAny(const char *str, qore_offset_t pos = 0) const;
 
    DLLEXPORT qore_offset_t rfindAny(const char *str, qore_offset_t pos = -1) const;
 
 
    DLLEXPORT bool isDataPrintableAscii() const;
 
 
    DLLEXPORT bool isDataAscii() const;
 
    DLLEXPORT int64 toBigInt() const;
 
 
    DLLEXPORT size_t getCharWidth(ExceptionSink* xsink) const;
 
 
    DLLEXPORT qore_offset_t getByteOffset(size_t i, ExceptionSink* xsink) const;
 
    // Removes the given number of bytes from the beginning of the string
    DLLEXPORT size_t removeBytes(size_t len);
 
    // concatenates a qorestring without converting encodings - internal only
    DLLLOCAL void concat(const QoreString* str);
 
    // private constructor
    DLLLOCAL QoreString(struct qore_string_private* p);
 
protected:
    hashdecl qore_string_private* priv = nullptr;
 
    // writes a new QoreString with the characters reversed of the "this" QoreString
    // assumes the encoding is the same and the length is 0
    DLLLOCAL void concat_reverse(QoreString* targ) const;
 
    DLLLOCAL int snprintf(size_t size, const char* fmt, ...);
    DLLLOCAL int vsnprintf(size_t size, const char* fmt, va_list args);
};
 
DLLEXPORT QoreString* checkEncoding(const QoreString* str, const QoreEncoding* enc, ExceptionSink* xsink);
 
class QoreStringMaker : public QoreString {
public:
 
    DLLEXPORT QoreStringMaker(const char* fmt, ...);
 
 
    DLLEXPORT QoreStringMaker(const QoreEncoding* enc, const char* fmt, ...);
 
private:
    DLLLOCAL QoreStringMaker(const QoreStringMaker& str) = delete;
    DLLLOCAL QoreStringMaker& operator=(const QoreStringMaker&) = delete;
};
 
 
class TempString {
public:
    DLLLOCAL TempString() : str(new QoreString) {
    }
 
    DLLLOCAL TempString(const QoreEncoding* enc) : str(new QoreString(enc)) {
    }
 
    DLLLOCAL TempString(QoreString* s) {
        str = s;
    }
 
    DLLLOCAL ~TempString() {
        delete str;
    }
 
    DLLLOCAL QoreString* operator->(){ return str; };
 
    DLLLOCAL QoreString* operator*() { return str; };
 
    DLLLOCAL operator bool() const { return str != nullptr; }
 
    DLLLOCAL QoreString* release() {
        QoreString* rv = str;
        str = nullptr;
        return rv;
    }
 
private:
    QoreString* str;
 
    TempString(const TempString&) = delete;
    TempString& operator=(const TempString&) = delete;
    void* operator new(size_t) = delete;
};
 
 
class TempEncodingHelper {
public:
 
    DLLLOCAL TempEncodingHelper(const QoreString& s, const QoreEncoding* qe, ExceptionSink* xsink) {
        set_intern(&s, qe, xsink);
    }
 
 
    DLLLOCAL TempEncodingHelper(const QoreString* s, const QoreEncoding* qe, ExceptionSink* xsink) {
        set_intern(s, qe, xsink);
    }
 
    DLLLOCAL TempEncodingHelper() {
    }
 
    DLLLOCAL ~TempEncodingHelper() {
        discard_intern();
    }
 
 
    DLLLOCAL int set(const QoreString* s, const QoreEncoding* qe, ExceptionSink* xsink) {
        discard_intern();
 
        set_intern(s, qe, xsink);
        return str != nullptr;
    }
 
    DLLLOCAL bool is_temp() const {
        return temp;
    }
 
    DLLLOCAL void makeTemp() {
        if (!temp && str) {
            str = new QoreString(*str);
            temp = true;
        }
    }
 
    DLLLOCAL const QoreString* operator->(){ return str; };
 
    DLLLOCAL const QoreString* operator*() { return str; };
 
 
    DLLLOCAL operator bool() const { return str != 0; }
 
 
    DLLLOCAL char* giveBuffer() {
        if (!str)
            return nullptr;
        if (temp)
            return str->giveBuffer();
        return strdup(str->getBuffer());
    }
 
 
    DLLEXPORT void removeBom();
 
private:
    QoreString* str = nullptr;
    bool temp = false;
 
    DLLLOCAL TempEncodingHelper(const TempEncodingHelper&) = delete;
    DLLLOCAL TempEncodingHelper& operator=(const TempEncodingHelper&) = delete;
    DLLLOCAL void* operator new(size_t) = delete;
 
    DLLLOCAL void discard_intern() {
        if (temp && str)
            delete str;
    }
 
 
    DLLLOCAL void set_intern(const QoreString* s, const QoreEncoding* qe, ExceptionSink* xsink) {
        if (s->getEncoding() != qe) {
            str = s->convertEncoding(qe, xsink);
            temp = true;
        } else {
            str = const_cast<QoreString* >(s);
            temp = false;
        }
    }
};
 
 
DLLEXPORT size_t qore_get_unicode_character_width(int ucs);
 
#endif