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
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.
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.
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
22 #ifndef String_class_h
23 #define String_class_h
29 #include <avr/pgmspace.h>
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
37 class __FlashStringHelper;
38 #define F(string_literal) (reinterpret_cast<const __FlashStringHelper *>(PSTR(string_literal)))
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;
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 {}
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
59 String(const char *cstr = "");
60 String(const String &str);
61 #ifdef __GXX_EXPERIMENTAL_CXX0X__
62 String(String &&rval);
63 String(StringSumHelper &&rval);
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);
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;}
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);
90 // concatenate (works w/ built-in types)
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);
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);}
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);
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;
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);}
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;
164 void replace(char find, char replace);
165 void replace(const String& find, const String& replace);
166 void toLowerCase(void);
167 void toUpperCase(void);
170 // parsing/conversion
171 long toInt(void) const;
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
180 void invalidate(void);
181 unsigned char changeBuffer(unsigned int maxStrLen);
182 unsigned char concat(const char *cstr, unsigned int length);
185 String & copy(const char *cstr, unsigned int length);
186 #ifdef __GXX_EXPERIMENTAL_CXX0X__
187 void move(String &rhs);
191 class StringSumHelper : public String
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) {}
204 #endif // __cplusplus
205 #endif // String_class_h