protocol/usb_hid/arduino-1.0.1/cores/arduino/WString.h

   1 /*
   2   WString.h - String library for Wiring & Arduino
   3   ...mostly rewritten by Paul Stoffregen...
   4   Copyright (c) 2009-10 Hernando Barragan.  All right reserved.
   5   Copyright 2011, Paul Stoffregen, paul@pjrc.com
   6
   7   This library is free software; you can redistribute it and/or
   8   modify it under the terms of the GNU Lesser General Public
   9   License as published by the Free Software Foundation; either
  10   version 2.1 of the License, or (at your option) any later version.
  11
  12   This library is distributed in the hope that it will be useful,
  13   but WITHOUT ANY WARRANTY; without even the implied warranty of
  14   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15   Lesser General Public License for more details.
  16
  17   You should have received a copy of the GNU Lesser General Public
  18   License along with this library; if not, write to the Free Software
  19   Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  20 */
  21
  22 #ifndef String_class_h
  23 #define String_class_h
  24 #ifdef __cplusplus
  25
  26 #include <stdlib.h>
  27 #include <string.h>
  28 #include <ctype.h>
  29 #include <avr/pgmspace.h>
  30
  31 // When compiling programs with this class, the following gcc parameters
  32 // dramatically increase performance and memory (RAM) efficiency, typically
  33 // with little or no increase in code size.
  34 //     -felide-constructors
  35 //     -std=c++0x
  36
  37 class __FlashStringHelper;
  38 #define F(string_literal) (reinterpret_cast<__FlashStringHelper *>(PSTR(string_literal)))
  39
  40 // An inherited class for holding the result of a concatenation.  These
  41 // result objects are assumed to be writable by subsequent concatenations.
  42 class StringSumHelper;
  43
  44 // The string class
  45 class String
  46 {
  47         // use a function pointer to allow for "if (s)" without the
  48         // complications of an operator bool(). for more information, see:
  49         // http://www.artima.com/cppsource/safebool.html
  50         typedef void (String::*StringIfHelperType)() const;
  51         void StringIfHelper() const {}
  52
  53 public:
  54         // constructors
  55         // creates a copy of the initial value.
  56         // if the initial value is null or invalid, or if memory allocation
  57         // fails, the string will be marked as invalid (i.e. "if (s)" will
  58         // be false).
  59         String(const char *cstr = "");
  60         String(const String &str);
  61         #ifdef __GXX_EXPERIMENTAL_CXX0X__
  62         String(String &&rval);
  63         String(StringSumHelper &&rval);
  64         #endif
  65         explicit String(char c);
  66         explicit String(unsigned char, unsigned char base=10);
  67         explicit String(int, unsigned char base=10);
  68         explicit String(unsigned int, unsigned char base=10);
  69         explicit String(long, unsigned char base=10);
  70         explicit String(unsigned long, unsigned char base=10);
  71         ~String(void);
  72
  73         // memory management
  74         // return true on success, false on failure (in which case, the string
  75         // is left unchanged).  reserve(0), if successful, will validate an
  76         // invalid string (i.e., "if (s)" will be true afterwards)
  77         unsigned char reserve(unsigned int size);
  78         inline unsigned int length(void) const {return len;}
  79
  80         // creates a copy of the assigned value.  if the value is null or
  81         // invalid, or if the memory allocation fails, the string will be
  82         // marked as invalid ("if (s)" will be false).
  83         String & operator = (const String &rhs);
  84         String & operator = (const char *cstr);
  85         #ifdef __GXX_EXPERIMENTAL_CXX0X__
  86         String & operator = (String &&rval);
  87         String & operator = (StringSumHelper &&rval);
  88         #endif
  89
  90         // concatenate (works w/ built-in types)
  91
  92         // returns true on success, false on failure (in which case, the string
  93         // is left unchanged).  if the argument is null or invalid, the
  94         // concatenation is considered unsucessful.
  95         unsigned char concat(const String &str);
  96         unsigned char concat(const char *cstr);
  97         unsigned char concat(char c);
  98         unsigned char concat(unsigned char c);
  99         unsigned char concat(int num);
 100         unsigned char concat(unsigned int num);
 101         unsigned char concat(long num);
 102         unsigned char concat(unsigned long num);
 103
 104         // if there's not enough memory for the concatenated value, the string
 105         // will be left unchanged (but this isn't signalled in any way)
 106         String & operator += (const String &rhs)        {concat(rhs); return (*this);}
 107         String & operator += (const char *cstr)         {concat(cstr); return (*this);}
 108         String & operator += (char c)                   {concat(c); return (*this);}
 109         String & operator += (unsigned char num)                {concat(num); return (*this);}
 110         String & operator += (int num)                  {concat(num); return (*this);}
 111         String & operator += (unsigned int num)         {concat(num); return (*this);}
 112         String & operator += (long num)                 {concat(num); return (*this);}
 113         String & operator += (unsigned long num)        {concat(num); return (*this);}
 114
 115         friend StringSumHelper & operator + (const StringSumHelper &lhs, const String &rhs);
 116         friend StringSumHelper & operator + (const StringSumHelper &lhs, const char *cstr);
 117         friend StringSumHelper & operator + (const StringSumHelper &lhs, char c);
 118         friend StringSumHelper & operator + (const StringSumHelper &lhs, unsigned char num);
 119         friend StringSumHelper & operator + (const StringSumHelper &lhs, int num);
 120         friend StringSumHelper & operator + (const StringSumHelper &lhs, unsigned int num);
 121         friend StringSumHelper & operator + (const StringSumHelper &lhs, long num);
 122         friend StringSumHelper & operator + (const StringSumHelper &lhs, unsigned long num);
 123
 124         // comparison (only works w/ Strings and "strings")
 125         operator StringIfHelperType() const { return buffer ? &String::StringIfHelper : 0; }
 126         int compareTo(const String &s) const;
 127         unsigned char equals(const String &s) const;
 128         unsigned char equals(const char *cstr) const;
 129         unsigned char operator == (const String &rhs) const {return equals(rhs);}
 130         unsigned char operator == (const char *cstr) const {return equals(cstr);}
 131         unsigned char operator != (const String &rhs) const {return !equals(rhs);}
 132         unsigned char operator != (const char *cstr) const {return !equals(cstr);}
 133         unsigned char operator <  (const String &rhs) const;
 134         unsigned char operator >  (const String &rhs) const;
 135         unsigned char operator <= (const String &rhs) const;
 136         unsigned char operator >= (const String &rhs) const;
 137         unsigned char equalsIgnoreCase(const String &s) const;
 138         unsigned char startsWith( const String &prefix) const;
 139         unsigned char startsWith(const String &prefix, unsigned int offset) const;
 140         unsigned char endsWith(const String &suffix) const;
 141
 142         // character acccess
 143         char charAt(unsigned int index) const;
 144         void setCharAt(unsigned int index, char c);
 145         char operator [] (unsigned int index) const;
 146         char& operator [] (unsigned int index);
 147         void getBytes(unsigned char *buf, unsigned int bufsize, unsigned int index=0) const;
 148         void toCharArray(char *buf, unsigned int bufsize, unsigned int index=0) const
 149                 {getBytes((unsigned char *)buf, bufsize, index);}
 150
 151         // search
 152         int indexOf( char ch ) const;
 153         int indexOf( char ch, unsigned int fromIndex ) const;
 154         int indexOf( const String &str ) const;
 155         int indexOf( const String &str, unsigned int fromIndex ) const;
 156         int lastIndexOf( char ch ) const;
 157         int lastIndexOf( char ch, unsigned int fromIndex ) const;
 158         int lastIndexOf( const String &str ) const;
 159         int lastIndexOf( const String &str, unsigned int fromIndex ) const;
 160         String substring( unsigned int beginIndex ) const;
 161         String substring( unsigned int beginIndex, unsigned int endIndex ) const;
 162
 163         // modification
 164         void replace(char find, char replace);
 165         void replace(const String& find, const String& replace);
 166         void toLowerCase(void);
 167         void toUpperCase(void);
 168         void trim(void);
 169
 170         // parsing/conversion
 171         long toInt(void) const;
 172
 173 protected:
 174         char *buffer;           // the actual char array
 175         unsigned int capacity;  // the array length minus one (for the '\0')
 176         unsigned int len;       // the String length (not counting the '\0')
 177         unsigned char flags;    // unused, for future features
 178 protected:
 179         void init(void);
 180         void invalidate(void);
 181         unsigned char changeBuffer(unsigned int maxStrLen);
 182         unsigned char concat(const char *cstr, unsigned int length);
 183
 184         // copy and move
 185         String & copy(const char *cstr, unsigned int length);
 186         #ifdef __GXX_EXPERIMENTAL_CXX0X__
 187         void move(String &rhs);
 188         #endif
 189 };
 190
 191 class StringSumHelper : public String
 192 {
 193 public:
 194         StringSumHelper(const String &s) : String(s) {}
 195         StringSumHelper(const char *p) : String(p) {}
 196         StringSumHelper(char c) : String(c) {}
 197         StringSumHelper(unsigned char num) : String(num) {}
 198         StringSumHelper(int num) : String(num) {}
 199         StringSumHelper(unsigned int num) : String(num) {}
 200         StringSumHelper(long num) : String(num) {}
 201         StringSumHelper(unsigned long num) : String(num) {}
 202 };
 203
 204 #endif  // __cplusplus
 205 #endif  // String_class_h