Debian Codegraph @

cores/arduino/WString.h

raw
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, [email protected]
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<const __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 static size_t const FLT_MAX_DECIMAL_PLACES;
54 static size_t const DBL_MAX_DECIMAL_PLACES;
55
56 public:
57 // constructors
58 // creates a copy of the initial value.
59 // if the initial value is null or invalid, or if memory allocation
60 // fails, the string will be marked as invalid (i.e. "if (s)" will
61 // be false).
62 String(const char *cstr = "");
63 String(const String &str);
64 String(const __FlashStringHelper *str);
65 #if __cplusplus >= 201103L || defined(__GXX_EXPERIMENTAL_CXX0X__)
66 String(String &&rval);
67 String(StringSumHelper &&rval);
68 #endif
69 explicit String(char c);
70 explicit String(unsigned char, unsigned char base=10);
71 explicit String(int, unsigned char base=10);
72 explicit String(unsigned int, unsigned char base=10);
73 explicit String(long, unsigned char base=10);
74 explicit String(unsigned long, unsigned char base=10);
75 explicit String(float, unsigned char decimalPlaces=2);
76 explicit String(double, unsigned char decimalPlaces=2);
77 ~String(void);
78
79 // memory management
80 // return true on success, false on failure (in which case, the string
81 // is left unchanged). reserve(0), if successful, will validate an
82 // invalid string (i.e., "if (s)" will be true afterwards)
83 unsigned char reserve(unsigned int size);
84 inline unsigned int length(void) const {return len;}
85
86 // creates a copy of the assigned value. if the value is null or
87 // invalid, or if the memory allocation fails, the string will be
88 // marked as invalid ("if (s)" will be false).
89 String & operator = (const String &rhs);
90 String & operator = (const char *cstr);
91 String & operator = (const __FlashStringHelper *str);
92 #if __cplusplus >= 201103L || defined(__GXX_EXPERIMENTAL_CXX0X__)
93 String & operator = (String &&rval);
94 String & operator = (StringSumHelper &&rval);
95 #endif
96
97 // concatenate (works w/ built-in types)
98
99 // returns true on success, false on failure (in which case, the string
100 // is left unchanged). if the argument is null or invalid, the
101 // concatenation is considered unsuccessful.
102 unsigned char concat(const String &str);
103 unsigned char concat(const char *cstr);
104 unsigned char concat(char c);
105 unsigned char concat(unsigned char c);
106 unsigned char concat(int num);
107 unsigned char concat(unsigned int num);
108 unsigned char concat(long num);
109 unsigned char concat(unsigned long num);
110 unsigned char concat(float num);
111 unsigned char concat(double num);
112 unsigned char concat(const __FlashStringHelper * str);
113
114 // if there's not enough memory for the concatenated value, the string
115 // will be left unchanged (but this isn't signalled in any way)
116 String & operator += (const String &rhs) {concat(rhs); return (*this);}
117 String & operator += (const char *cstr) {concat(cstr); return (*this);}
118 String & operator += (char c) {concat(c); return (*this);}
119 String & operator += (unsigned char num) {concat(num); return (*this);}
120 String & operator += (int num) {concat(num); return (*this);}
121 String & operator += (unsigned int num) {concat(num); return (*this);}
122 String & operator += (long num) {concat(num); return (*this);}
123 String & operator += (unsigned long num) {concat(num); return (*this);}
124 String & operator += (float num) {concat(num); return (*this);}
125 String & operator += (double num) {concat(num); return (*this);}
126 String & operator += (const __FlashStringHelper *str){concat(str); return (*this);}
127
128 friend StringSumHelper & operator + (const StringSumHelper &lhs, const String &rhs);
129 friend StringSumHelper & operator + (const StringSumHelper &lhs, const char *cstr);
130 friend StringSumHelper & operator + (const StringSumHelper &lhs, char c);
131 friend StringSumHelper & operator + (const StringSumHelper &lhs, unsigned char num);
132 friend StringSumHelper & operator + (const StringSumHelper &lhs, int num);
133 friend StringSumHelper & operator + (const StringSumHelper &lhs, unsigned int num);
134 friend StringSumHelper & operator + (const StringSumHelper &lhs, long num);
135 friend StringSumHelper & operator + (const StringSumHelper &lhs, unsigned long num);
136 friend StringSumHelper & operator + (const StringSumHelper &lhs, float num);
137 friend StringSumHelper & operator + (const StringSumHelper &lhs, double num);
138 friend StringSumHelper & operator + (const StringSumHelper &lhs, const __FlashStringHelper *rhs);
139
140 // comparison (only works w/ Strings and "strings")
141 operator StringIfHelperType() const { return buffer ? &String::StringIfHelper : 0; }
142 int compareTo(const String &s) const;
143 unsigned char equals(const String &s) const;
144 unsigned char equals(const char *cstr) const;
145 unsigned char operator == (const String &rhs) const {return equals(rhs);}
146 unsigned char operator == (const char *cstr) const {return equals(cstr);}
147 unsigned char operator != (const String &rhs) const {return !equals(rhs);}
148 unsigned char operator != (const char *cstr) const {return !equals(cstr);}
149 unsigned char operator < (const String &rhs) const;
150 unsigned char operator > (const String &rhs) const;
151 unsigned char operator <= (const String &rhs) const;
152 unsigned char operator >= (const String &rhs) const;
153 unsigned char equalsIgnoreCase(const String &s) const;
154 unsigned char startsWith( const String &prefix) const;
155 unsigned char startsWith(const String &prefix, unsigned int offset) const;
156 unsigned char endsWith(const String &suffix) const;
157
158 // character access
159 char charAt(unsigned int index) const;
160 void setCharAt(unsigned int index, char c);
161 char operator [] (unsigned int index) const;
162 char& operator [] (unsigned int index);
163 void getBytes(unsigned char *buf, unsigned int bufsize, unsigned int index=0) const;
164 void toCharArray(char *buf, unsigned int bufsize, unsigned int index=0) const
165 { getBytes((unsigned char *)buf, bufsize, index); }
166 const char* c_str() const { return buffer; }
167 char* begin() { return buffer; }
168 char* end() { return buffer + length(); }
169 const char* begin() const { return c_str(); }
170 const char* end() const { return c_str() + length(); }
171
172 // search
173 int indexOf( char ch ) const;
174 int indexOf( char ch, unsigned int fromIndex ) const;
175 int indexOf( const String &str ) const;
176 int indexOf( const String &str, unsigned int fromIndex ) const;
177 int lastIndexOf( char ch ) const;
178 int lastIndexOf( char ch, unsigned int fromIndex ) const;
179 int lastIndexOf( const String &str ) const;
180 int lastIndexOf( const String &str, unsigned int fromIndex ) const;
181 String substring( unsigned int beginIndex ) const { return substring(beginIndex, len); };
182 String substring( unsigned int beginIndex, unsigned int endIndex ) const;
183
184 // modification
185 void replace(char find, char replace);
186 void replace(const String& find, const String& replace);
187 void remove(unsigned int index);
188 void remove(unsigned int index, unsigned int count);
189 void toLowerCase(void);
190 void toUpperCase(void);
191 void trim(void);
192
193 // parsing/conversion
194 long toInt(void) const;
195 float toFloat(void) const;
196 double toDouble(void) const;
197
198 protected:
199 char *buffer; // the actual char array
200 unsigned int capacity; // the array length minus one (for the '\0')
201 unsigned int len; // the String length (not counting the '\0')
202 protected:
203 void init(void);
204 void invalidate(void);
205 unsigned char changeBuffer(unsigned int maxStrLen);
206 unsigned char concat(const char *cstr, unsigned int length);
207
208 // copy and move
209 String & copy(const char *cstr, unsigned int length);
210 String & copy(const __FlashStringHelper *pstr, unsigned int length);
211 #if __cplusplus >= 201103L || defined(__GXX_EXPERIMENTAL_CXX0X__)
212 void move(String &rhs);
213 #endif
214 };
215
216 class StringSumHelper : public String
217 {
218 public:
219 StringSumHelper(const String &s) : String(s) {}
220 StringSumHelper(const char *p) : String(p) {}
221 StringSumHelper(char c) : String(c) {}
222 StringSumHelper(unsigned char num) : String(num) {}
223 StringSumHelper(int num) : String(num) {}
224 StringSumHelper(unsigned int num) : String(num) {}
225 StringSumHelper(long num) : String(num) {}
226 StringSumHelper(unsigned long num) : String(num) {}
227 StringSumHelper(float num) : String(num) {}
228 StringSumHelper(double num) : String(num) {}
229 };
230
231 #endif // __cplusplus
232 #endif // String_class_h