WString.h

00001 /*
00002   WString.h - String library for Wiring & Arduino
00003   ...mostly rewritten by Paul Stoffregen...
00004   Copyright (c) 2009-10 Hernando Barragan.  All right reserved.
00005   Copyright 2011, Paul Stoffregen, paul@pjrc.com
00006 
00007   This library is free software; you can redistribute it and/or
00008   modify it under the terms of the GNU Lesser General Public
00009   License as published by the Free Software Foundation; either
00010   version 2.1 of the License, or (at your option) any later version.
00011 
00012   This library is distributed in the hope that it will be useful,
00013   but WITHOUT ANY WARRANTY; without even the implied warranty of
00014   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00015   Lesser General Public License for more details.
00016 
00017   You should have received a copy of the GNU Lesser General Public
00018   License along with this library; if not, write to the Free Software
00019   Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
00020 */
00021 
00022 #ifndef String_class_h
00023 #define String_class_h
00024 
00025 #ifdef __cplusplus
00026 
00027 #include <Arduino.h>
00028 #include "PokittoFakeavr.h "
00029 
00030 #include <stdlib.h>
00031 #include <string.h>
00032 #include <ctype.h>
00033 //#include <avr/pgmspace.h>
00034 
00035 // When compiling programs with this class, the following gcc parameters
00036 // dramatically increase performance and memory (RAM) efficiency, typically
00037 // with little or no increase in code size.
00038 //     -felide-constructors
00039 //     -std=c++0x
00040 
00041 class __FlashStringHelper;
00042 
00043 #define PSTR(s) \
00044     ((const PROGMEM char *)(s))
00045 
00046 #define F(string_literal) (reinterpret_cast<const __FlashStringHelper *>(PSTR(string_literal)))
00047 
00048 // An inherited class for holding the result of a concatenation.  These
00049 // result objects are assumed to be writable by subsequent concatenations.
00050 class StringSumHelper;
00051 
00052 // The string class
00053 class String
00054 {
00055     // use a function pointer to allow for "if (s)" without the
00056     // complications of an operator bool(). for more information, see:
00057     // http://www.artima.com/cppsource/safebool.html
00058     typedef void (String::*StringIfHelperType)() const;
00059     void StringIfHelper() const {}
00060 
00061 public:
00062     // constructors
00063     // creates a copy of the initial value.
00064     // if the initial value is null or invalid, or if memory allocation
00065     // fails, the string will be marked as invalid (i.e. "if (s)" will
00066     // be false).
00067     String(const char *cstr = "");
00068     String(const String &str);
00069     #ifdef __GXX_EXPERIMENTAL_CXX0X__
00070     String(String &&rval);
00071     String(StringSumHelper &&rval);
00072     #endif
00073     explicit String(char c);
00074     explicit String(unsigned char, unsigned char base=10);
00075     explicit String(int, unsigned char base=10);
00076     explicit String(unsigned int, unsigned char base=10);
00077     explicit String(long, unsigned char base=10);
00078     explicit String(unsigned long, unsigned char base=10);
00079     ~String(void);
00080 
00081     // memory management
00082     // return true on success, false on failure (in which case, the string
00083     // is left unchanged).  reserve(0), if successful, will validate an
00084     // invalid string (i.e., "if (s)" will be true afterwards)
00085     unsigned char reserve(unsigned int size);
00086     inline unsigned int length(void) const {return len;}
00087 
00088     // creates a copy of the assigned value.  if the value is null or
00089     // invalid, or if the memory allocation fails, the string will be
00090     // marked as invalid ("if (s)" will be false).
00091     String & operator = (const String &rhs);
00092     String & operator = (const char *cstr);
00093     #ifdef __GXX_EXPERIMENTAL_CXX0X__
00094     String & operator = (String &&rval);
00095     String & operator = (StringSumHelper &&rval);
00096     #endif
00097 
00098     // concatenate (works w/ built-in types)
00099 
00100     // returns true on success, false on failure (in which case, the string
00101     // is left unchanged).  if the argument is null or invalid, the
00102     // concatenation is considered unsucessful.
00103     unsigned char concat(const String &str);
00104     unsigned char concat(const char *cstr);
00105     unsigned char concat(char c);
00106     unsigned char concat(unsigned char c);
00107     unsigned char concat(int num);
00108     unsigned char concat(unsigned int num);
00109     unsigned char concat(long num);
00110     unsigned char concat(unsigned long num);
00111 
00112     // if there's not enough memory for the concatenated value, the string
00113     // will be left unchanged (but this isn't signalled in any way)
00114     String & operator += (const String &rhs)    {concat(rhs); return (*this);}
00115     String & operator += (const char *cstr)     {concat(cstr); return (*this);}
00116     String & operator += (char c)           {concat(c); return (*this);}
00117     String & operator += (unsigned char num)        {concat(num); return (*this);}
00118     String & operator += (int num)          {concat(num); return (*this);}
00119     String & operator += (unsigned int num)     {concat(num); return (*this);}
00120     String & operator += (long num)         {concat(num); return (*this);}
00121     String & operator += (unsigned long num)    {concat(num); return (*this);}
00122 
00123     friend StringSumHelper & operator + (const StringSumHelper &lhs, const String &rhs);
00124     friend StringSumHelper & operator + (const StringSumHelper &lhs, const char *cstr);
00125     friend StringSumHelper & operator + (const StringSumHelper &lhs, char c);
00126     friend StringSumHelper & operator + (const StringSumHelper &lhs, unsigned char num);
00127     friend StringSumHelper & operator + (const StringSumHelper &lhs, int num);
00128     friend StringSumHelper & operator + (const StringSumHelper &lhs, unsigned int num);
00129     friend StringSumHelper & operator + (const StringSumHelper &lhs, long num);
00130     friend StringSumHelper & operator + (const StringSumHelper &lhs, unsigned long num);
00131 
00132     // comparison (only works w/ Strings and "strings")
00133     operator StringIfHelperType() const { return buffer ? &String::StringIfHelper : 0; }
00134     int compareTo(const String &s) const;
00135     unsigned char equals(const String &s) const;
00136     unsigned char equals(const char *cstr) const;
00137     unsigned char operator == (const String &rhs) const {return equals(rhs);}
00138     unsigned char operator == (const char *cstr) const {return equals(cstr);}
00139     unsigned char operator != (const String &rhs) const {return !equals(rhs);}
00140     unsigned char operator != (const char *cstr) const {return !equals(cstr);}
00141     unsigned char operator <  (const String &rhs) const;
00142     unsigned char operator >  (const String &rhs) const;
00143     unsigned char operator <= (const String &rhs) const;
00144     unsigned char operator >= (const String &rhs) const;
00145     unsigned char equalsIgnoreCase(const String &s) const;
00146     unsigned char startsWith( const String &prefix) const;
00147     unsigned char startsWith(const String &prefix, unsigned int offset) const;
00148     unsigned char endsWith(const String &suffix) const;
00149 
00150     // character acccess
00151     char charAt(unsigned int index) const;
00152     void setCharAt(unsigned int index, char c);
00153     char operator [] (unsigned int index) const;
00154     char& operator [] (unsigned int index);
00155     void getBytes(unsigned char *buf, unsigned int bufsize, unsigned int index=0) const;
00156     void toCharArray(char *buf, unsigned int bufsize, unsigned int index=0) const
00157         {getBytes((unsigned char *)buf, bufsize, index);}
00158 
00159     // search
00160     int indexOf( char ch ) const;
00161     int indexOf( char ch, unsigned int fromIndex ) const;
00162     int indexOf( const String &str ) const;
00163     int indexOf( const String &str, unsigned int fromIndex ) const;
00164     int lastIndexOf( char ch ) const;
00165     int lastIndexOf( char ch, unsigned int fromIndex ) const;
00166     int lastIndexOf( const String &str ) const;
00167     int lastIndexOf( const String &str, unsigned int fromIndex ) const;
00168     String substring( unsigned int beginIndex ) const;
00169     String substring( unsigned int beginIndex, unsigned int endIndex ) const;
00170 
00171     // modification
00172     void replace(char find, char replace);
00173     void replace(const String& find, const String& replace);
00174     void toLowerCase(void);
00175     void toUpperCase(void);
00176     void trim(void);
00177 
00178     // parsing/conversion
00179     long toInt(void) const;
00180 
00181 protected:
00182     char *buffer;           // the actual char array
00183     unsigned int capacity;  // the array length minus one (for the '\0')
00184     unsigned int len;       // the String length (not counting the '\0')
00185     unsigned char flags;    // unused, for future features
00186 protected:
00187     void init(void);
00188     void invalidate(void);
00189     unsigned char changeBuffer(unsigned int maxStrLen);
00190     unsigned char concat(const char *cstr, unsigned int length);
00191 
00192     // copy and move
00193     String & copy(const char *cstr, unsigned int length);
00194     #ifdef __GXX_EXPERIMENTAL_CXX0X__
00195     void move(String &rhs);
00196     #endif
00197 };
00198 
00199 class StringSumHelper : public String
00200 {
00201 public:
00202     StringSumHelper(const String &s) : String(s) {}
00203     StringSumHelper(const char *p) : String(p) {}
00204     StringSumHelper(char c) : String(c) {}
00205     StringSumHelper(unsigned char num) : String(num) {}
00206     StringSumHelper(int num) : String(num) {}
00207     StringSumHelper(unsigned int num) : String(num) {}
00208     StringSumHelper(long num) : String(num) {}
00209     StringSumHelper(unsigned long num) : String(num) {}
00210 };
00211 
00212 #endif  // __cplusplus
00213 #endif  // String_class_h