WString.h

Go to the documentation of this file.

/* $Id: WString.h 1156 2011-06-07 04:01:16Z bhagman $
||
|| @author         Paul Stoffregen <paul@pjrc.com>
|| @url            http://wiring.org.co/
|| @contribution   Hernando Barragan <b@wiring.org.co>
|| @contribution   Brett Hagman <bhagman@wiring.org.co>
|| @contribution   Alexander Brevig <abrevig@wiring.org.co>
||
|| @description
|| | String class.
|| |
|| | Wiring Common API
|| #
||
|| @license Please see cores/Common/License.txt.
||
*/
 
/*
 * @author: 2 Oct 2018 - mikee47 <mike@sillyhouse.net>
 *
 * The standard String object default constructor creates an empty string, which requires a heap allocation of 1 byte.
 * I changed this behaviour to default to a null string (invalid) to avoid this (usually) un-necessary allocation.
 * If the value of the string hasn't actually been assigned yet then an 'invalid' (or null) string is the more logical choice.
 * Additional changes ensure that the content of such a string are equivalent to an empty string "".
 *
 * Background
 *
 * The intent of the Wiring authors seems to be that an expression producing a String object will fail and produce
 * an 'invalid' String (that evaluates to False) if any of the allocations within that expression fail. This could
 * be due to heap fragmentation, low memory or a String which is just too big.
 *
 * By example:
 *
 *  String tmp = String("A") + String("B");
 *
 * If a heap allocation fails on either "A" or "B" the the result should be a null string. However, this is not actually
 * the case. In practice, if "A" fails but "B" does not then the result will be "B", while if "A" succeeds but "B" fails
 * then the result will be 'invalid'. This would appear to be an oversight in the Wiring library (last updated July 2016).
 *
 * I made a decision with these changes that heap allocation errors are a rare enough occurrence that attempting to deal with
 * them in such a manner causes more problems than it solves.
 *
 * These changes have a knock-on effect in that if any of the allocations in an expression fail, then the result, tmp,
 * will be unpredictable.
 *
 * @author Nov 2019 mikee47 <mike@sillyhouse.net>
 *
 * Small String Optimisation (SSO). Based on the Arduino ESP8266 core implementation.
 * An empty String object now consumes 12 bytes (from 8) but provides an SSO capacity of 11 characters.
 * Capacity and length types changed to size_t, thus String is no longer restricted to 64K.
 *
 */
 
#pragma once
 
#ifdef __cplusplus
 
#include "WConstants.h"
#include <cstddef>
#include <string.h>
#include <sming_attr.h>
 
#include <FlashString/String.hpp>
 
using FlashString = FSTR::String;
 
#ifndef __GXX_EXPERIMENTAL_CXX0X__
#define __GXX_EXPERIMENTAL_CXX0X__
#endif
 
// When compiling programs with this class, the following gcc parameters
// dramatically increase performance and memory (RAM) efficiency, typically
// with little or no increase in code size.
//     -felide-constructors
//     -std=c++0x
 
// An inherited class for holding the result of a concatenation.  These
// result objects are assumed to be writable by subsequent concatenations.
class StringSumHelper;
 
// Arduino-style flash strings
class __FlashStringHelper; // Never actually defined
using flash_string_t = const __FlashStringHelper*;
 
#define FPSTR(pstr_pointer) reinterpret_cast<flash_string_t>(pstr_pointer)
 
#define F(string_literal) String(FPSTR(PSTR_COUNTED(string_literal)), sizeof(string_literal) - 1)
 
class String
{
    // use a function pointer to allow for "if (s)" without the
    // complications of an operator bool(). for more information, see:
    // http://www.artima.com/cppsource/safebool.html
    using StringIfHelperType = void (String::*)() const;
    void StringIfHelper() const
    {
    }
 
public:
    // Use these for const references, e.g. in function return values
    static const String nullstr; 
    static const String empty;   
 
    String() : ptr{nullptr, 0, 0}
    {
    }
 
    String(const char* cstr);
    String(const char* cstr, size_t length) : String()
    {
        if(cstr)
            copy(cstr, length);
    }
    String(const String& str) : String()
    {
        *this = str;
    }
    explicit String(flash_string_t pstr, size_t length) : String()
    {
        setString(pstr, length);
    }
    explicit String(flash_string_t pstr) : String()
    {
        setString(pstr);
    }
 
#ifdef __GXX_EXPERIMENTAL_CXX0X__
    String(String&& rval) noexcept : String()
    {
        move(rval);
    }
    String(StringSumHelper&& rval) noexcept;
#endif
    explicit String(char c);
    explicit String(unsigned char, unsigned char base = 10, unsigned char width = 0, char pad = '0');
    explicit String(int num, unsigned char base = 10, unsigned char width = 0, char pad = '0')
        : String(long(num), base, width, pad)
    {
    }
    explicit String(unsigned int num, unsigned char base = 10, unsigned char width = 0, char pad = '0')
        : String((unsigned long)(num), base, width, pad)
    {
    }
    explicit String(long, unsigned char base = 10, unsigned char width = 0, char pad = '0');
    explicit String(long long, unsigned char base = 10, unsigned char width = 0, char pad = '0');
    explicit String(unsigned long, unsigned char base = 10, unsigned char width = 0, char pad = '0');
    explicit String(unsigned long long, unsigned char base = 10, unsigned char width = 0, char pad = '0');
    explicit String(float, unsigned char decimalPlaces = 2);
    explicit String(double, unsigned char decimalPlaces = 2);
    ~String(void)
    {
        invalidate();
    }
 
    void setString(const char* cstr);
    void setString(const char* cstr, size_t length);
    void setString(flash_string_t pstr);
    void setString(flash_string_t pstr, size_t length);
 
    // memory management
 
    bool reserve(size_t size);
 
    bool setLength(size_t length);
 
    inline size_t length(void) const
    {
        return sso.set ? sso.len : ptr.len;
    }
 
    struct Buffer {
        char* data; 
        size_t size;   
        size_t length; 
    };
 
    bool setBuffer(const Buffer& buffer);
 
    Buffer getBuffer();
 
    String& operator=(const String& rhs);
    String& operator=(const char* cstr);
#ifdef __GXX_EXPERIMENTAL_CXX0X__
    String& operator=(String&& rval) noexcept
    {
        if(this != &rval)
            move(rval);
        return *this;
    }
    String& operator=(StringSumHelper&& rval) noexcept;
#endif
    bool concat(const String& str)
    {
        return concat(str.cbuffer(), str.length());
    }
    bool concat(const FlashString& fstr);
    bool concat(const char* cstr);
    bool concat(const char* cstr, size_t length);
    bool concat(char c)
    {
        return concat(&c, 1);
    }
    bool concat(unsigned char num, unsigned char base = 10, unsigned char width = 0, char pad = '0');
    bool concat(int num, unsigned char base = 10, unsigned char width = 0, char pad = '0')
    {
        return concat(long(num), base, width, pad);
    }
    bool concat(unsigned int num, unsigned char base = 10, unsigned char width = 0, char pad = '0')
    {
        return concat((unsigned long)(num), base, width, pad);
    }
    bool concat(long num, unsigned char base = 10, unsigned char width = 0, char pad = '0');
    bool concat(long long num, unsigned char base = 10, unsigned char width = 0, char pad = '0');
    bool concat(unsigned long num, unsigned char base = 10, unsigned char width = 0, char pad = '0');
    bool concat(unsigned long long num, unsigned char base = 10, unsigned char width = 0, char pad = '0');
    bool concat(float num);
    bool concat(double num);
 
    template <typename E>
    constexpr typename std::enable_if<std::is_enum<E>::value && !std::is_convertible<E, int>::value, bool>::type
    concat(E value)
    {
        extern String toString(E);
        return concat(toString(value));
    }
    String& operator+=(const String& rhs)
    {
        concat(rhs);
        return (*this);
    }
    String& operator+=(const FlashString& rhs)
    {
        concat(rhs);
        return (*this);
    }
    String& operator+=(const char* cstr)
    {
        concat(cstr);
        return (*this);
    }
    template <typename T> String& operator+=(T value)
    {
        concat(value);
        return *this;
    }
    friend StringSumHelper& operator+(const StringSumHelper& lhs, const String& rhs);
    friend StringSumHelper& operator+(const StringSumHelper& lhs, const char* cstr);
    friend StringSumHelper& operator+(const StringSumHelper& lhs, char c);
    friend StringSumHelper& operator+(const StringSumHelper& lhs, unsigned char num);
    friend StringSumHelper& operator+(const StringSumHelper& lhs, int num);
    friend StringSumHelper& operator+(const StringSumHelper& lhs, unsigned int num);
    friend StringSumHelper& operator+(const StringSumHelper& lhs, long num);
    friend StringSumHelper& operator+(const StringSumHelper& lhs, unsigned long num);
    friend StringSumHelper& operator+(const StringSumHelper& lhs, unsigned long long num);
    friend StringSumHelper& operator+(const StringSumHelper& lhs, float num);
    friend StringSumHelper& operator+(const StringSumHelper& lhs, double num);
 
    operator StringIfHelperType() const
    {
        return isNull() ? 0 : &String::StringIfHelper;
    }
 
    int compareTo(const char* cstr, size_t length) const;
    int compareTo(const String& s) const
    {
        return compareTo(s.cbuffer(), s.length());
    }
    bool equals(const String& s) const
    {
        return equals(s.cbuffer(), s.length());
    }
    bool equals(const char* cstr) const;
    bool equals(const char* cstr, size_t length) const;
    bool equals(const FlashString& fstr) const
    {
        return fstr.equals(*this);
    }
    bool operator==(const String& rhs) const
    {
        return equals(rhs);
    }
    bool operator==(const char* cstr) const
    {
        return equals(cstr);
    }
    bool operator==(const FlashString& fstr) const
    {
        return equals(fstr);
    }
    bool operator!=(const String& rhs) const
    {
        return !equals(rhs);
    }
    bool operator!=(const char* cstr) const
    {
        return !equals(cstr);
    }
    bool operator<(const String& rhs) const
    {
        return compareTo(rhs) < 0;
    }
    bool operator>(const String& rhs) const
    {
        return compareTo(rhs) > 0;
    }
    bool operator<=(const String& rhs) const
    {
        return compareTo(rhs) <= 0;
    }
    bool operator>=(const String& rhs) const
    {
        return compareTo(rhs) >= 0;
    }
    bool equalsIgnoreCase(const char* cstr) const;
    bool equalsIgnoreCase(const char* cstr, size_t length) const;
    bool equalsIgnoreCase(const String& s2) const
    {
        return equalsIgnoreCase(s2.cbuffer(), s2.length());
    }
    bool equalsIgnoreCase(const FlashString& fstr) const
    {
        return fstr.equalsIgnoreCase(*this);
    }
    bool startsWith(const String& prefix) const
    {
        return startsWith(prefix, 0);
    }
 
    bool startsWith(const String& prefix, size_t offset) const;
 
    bool endsWith(char suffix) const;
 
    bool endsWith(const String& suffix) const;
 
    // character access
 
    char charAt(size_t index) const
    {
        return operator[](index);
    }
 
    void setCharAt(size_t index, char c);
 
    char operator[](size_t index) const;
    char& operator[](size_t index);
    size_t getBytes(unsigned char* buf, size_t bufsize, size_t index = 0) const;
 
    void toCharArray(char* buf, size_t bufsize, size_t index = 0) const
    {
        getBytes((unsigned char*)buf, bufsize, index);
    }
 
    const char* c_str() const
    {
        return cbuffer() ?: empty.cbuffer();
    }
 
    char* begin()
    {
        return buffer();
    }
 
    char* end()
    {
        return buffer() + length();
    }
    const char* begin() const
    {
        return c_str();
    }
    const char* end() const
    {
        return c_str() + length();
    }
 
    // search
 
    int indexOf(char ch, size_t fromIndex = 0) const;
    int indexOf(const char* s2_buf, size_t fromIndex, size_t s2_len) const;
    int indexOf(const char* s2_buf, size_t fromIndex = 0) const
    {
        return indexOf(s2_buf, fromIndex, strlen(s2_buf));
    }
    int indexOf(const String& s2, size_t fromIndex = 0) const
    {
        return indexOf(s2.cbuffer(), fromIndex, s2.length());
    }
    int lastIndexOf(char ch) const;
    int lastIndexOf(char ch, size_t fromIndex) const;
    int lastIndexOf(const String& s2) const;
    int lastIndexOf(const String& s2, size_t fromIndex) const;
    int lastIndexOf(const char* s2_buf, size_t fromIndex, size_t s2_len) const;
    String substring(size_t from, size_t to) const;
    String substring(size_t from) const
    {
        return substring(from, length());
    }
    // modification
 
    void replace(char find, char replace);
    bool replace(const String& find, const String& replace);
    bool replace(const char* find_buf, size_t find_len, const char* replace_buf, size_t replace_len);
    void remove(size_t index)
    {
        remove(index, SIZE_MAX);
    }
    void remove(size_t index, size_t count);
    void toLowerCase(void);
 
    void toUpperCase(void);
 
    void trim(const char* set = " \t\n\v\f\r");
 
    String& padLeft(uint16_t minWidth, char c = ' ')
    {
        return pad(-minWidth, c);
    }
 
    String& padRight(uint16_t minWidth, char c = ' ')
    {
        return pad(minWidth, c);
    }
 
    String& pad(int16_t minWidth, char c = ' ');
 
    // parsing/conversion
    long toInt(void) const;
    float toFloat(void) const;
 
    static constexpr size_t SSO_CAPACITY = STRING_OBJECT_SIZE - 2;
 
protected:
    struct PtrBuf {
        char* buffer;   // the actual char array
        size_t len;      // the String length (not counting the '\0')
        size_t capacity; // the array length minus one (for the '\0')
    };
    // For small strings we can store data directly without requiring the heap
    struct SsoBuf {
        char buffer[SSO_CAPACITY + 1];
        unsigned char len : 7;
        unsigned char set : 1; 
    };
    union {
        PtrBuf ptr;
        SsoBuf sso;
    };
 
    static_assert(STRING_OBJECT_SIZE == sizeof(SsoBuf), "SSO Buffer alignment problem");
    static_assert(STRING_OBJECT_SIZE >= sizeof(PtrBuf), "STRING_OBJECT_SIZE too small");
    static_assert(STRING_OBJECT_SIZE <= 128, "STRING_OBJECT_SIZE too large (max. 128)");
    static_assert(STRING_OBJECT_SIZE % 4 == 0, "STRING_OBJECT_SIZE must be a multiple of 4");
 
protected:
    // Free any heap memory and set to non-SSO mode; isNull() will return true
    void invalidate(void);
 
    // String is Null (invalid) by default, i.e. non-SSO and null buffer
    __forceinline bool isNull() const
    {
        return !sso.set && (ptr.buffer == nullptr);
    }
 
    // Get writeable buffer pointer
    __forceinline char* buffer()
    {
        return sso.set ? sso.buffer : ptr.buffer;
    }
 
    // Get read-only buffer pointer
    __forceinline const char* cbuffer() const
    {
        return sso.set ? sso.buffer : ptr.buffer;
    }
 
    // Get currently assigned capacity for current mode
    __forceinline size_t capacity() const
    {
        return sso.set ? SSO_CAPACITY : ptr.capacity;
    }
 
    // Called whenever string length changes to ensure NUL terminator is set
    __forceinline void setlen(size_t len)
    {
        if(sso.set) {
            sso.len = len;
            sso.buffer[len] = '\0';
        } else {
            ptr.len = len;
            if(ptr.buffer != nullptr) {
                ptr.buffer[len] = '\0';
            }
        }
    }
 
    // copy and move
    String& copy(const char* cstr, size_t length);
    String& copy(flash_string_t pstr, size_t length);
#ifdef __GXX_EXPERIMENTAL_CXX0X__
    void move(String& rhs);
#endif
};
 
class StringSumHelper : public String
{
public:
    StringSumHelper(const String& s) : String(s)
    {
    }
    StringSumHelper(const char* p) : String(p)
    {
    }
    StringSumHelper(char c) : String(c)
    {
    }
    StringSumHelper(unsigned char num) : String(num)
    {
    }
    StringSumHelper(int num) : String(num)
    {
    }
    StringSumHelper(unsigned int num) : String(num)
    {
    }
    StringSumHelper(long num) : String(num)
    {
    }
    StringSumHelper(long long num) : String(num)
    {
    }
    StringSumHelper(unsigned long num) : String(num)
    {
    }
    StringSumHelper(unsigned long long num) : String(num)
    {
    }
    StringSumHelper(float num) : String(num)
    {
    }
    StringSumHelper(double num) : String(num)
    {
    }
};
 
#include "SplitString.h"
 
#endif // __cplusplus