Statistics
| Branch: | Revision:

root / arduino-1.0 / hardware / arduino / cores / arduino / WString.h @ 58d82c77

History | View | Annotate | Download (8.27 KB)

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