String.hpp
Go to the documentation of this file.
1 /****
2  * String.hpp - Defines the String class and associated macros for efficient flash memory string access.
3  *
4  * Copyright 2019 mikee47 <mike@sillyhouse.net>
5  *
6  * This file is part of the FlashString Library
7  *
8  * This library is free software: you can redistribute it and/or modify it under the terms of the
9  * GNU General Public License as published by the Free Software Foundation, version 3 or later.
10  *
11  * This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
12  * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
13  * See the GNU General Public License for more details.
14  *
15  * You should have received a copy of the GNU General Public License along with this library.
16  * If not, see <https://www.gnu.org/licenses/>.
17  *
18  * @author: 2018 - Mikee47 <mike@sillyhouse.net>
19  *
20  ****/
21 
22 #pragma once
23 
24 #include "Object.hpp"
25 #include "StringPrinter.hpp"
26 
27 // Wiring String - this file is included from WString.h so define required types only
28 class String;
29 class __FlashStringHelper;
30 typedef const __FlashStringHelper* flash_string_t;
31 
43 #define FS_PTR(str) \
44  (__extension__({ \
45  static DEFINE_FSTR_DATA(__fstr__, str); \
46  static_cast<const FSTR::String*>(&__fstr__.object); \
47  }))
48 
56 #define FS(str) (*FS_PTR(str))
57 
63 #define DECLARE_FSTR(name) DECLARE_FSTR_OBJECT(name, FSTR::String)
64 
77 #define DEFINE_FSTR(name, str) \
78  static DEFINE_FSTR_DATA(FSTR_DATA_NAME(name), str); \
79  DEFINE_FSTR_REF_NAMED(name, FSTR::String);
80 
84 #define DEFINE_FSTR_LOCAL(name, str) \
85  static DEFINE_FSTR_DATA(FSTR_DATA_NAME(name), str); \
86  static constexpr DEFINE_FSTR_REF_NAMED(name, FSTR::String);
87 
93 #define DEFINE_FSTR_DATA(name, str) \
94  constexpr const struct { \
95  FSTR::ObjectBase object; \
96  char data[ALIGNUP4(sizeof(str))]; \
97  } name PROGMEM = {{sizeof(str) - 1}, str}; \
98  FSTR_CHECK_STRUCT(name);
99 
111 #define LOAD_FSTR(name, fstr) \
112  char name[(fstr).size()] FSTR_ALIGNED; \
113  memcpy_aligned(name, (fstr).data(), (fstr).length()); \
114  name[(fstr).length()] = '\0';
115 
123 #define FSTR_ARRAY(name, str) \
124  static DEFINE_FSTR_DATA(FSTR_DATA_NAME(name), str); \
125  LOAD_FSTR(name, FSTR_DATA_NAME(name).object.template as<FSTR::String>())
126 
133 #define IMPORT_FSTR(name, file) IMPORT_FSTR_OBJECT(name, FSTR::String, file)
134 
138 #define IMPORT_FSTR_LOCAL(name, file) IMPORT_FSTR_OBJECT_LOCAL(name, FSTR::String, file)
139 
161 #define FSTR_TABLE(name) const FSTR::String* const name[] PROGMEM
162 
163 namespace FSTR
164 {
168 typedef ::String WString;
169 
173 class String : public Object<String, char>
174 {
175 public:
180  size_t size() const
181  {
182  return ALIGNUP4(Object::length() + 1);
183  }
184 
189  {
190  return reinterpret_cast<flash_string_t>(Object::data());
191  }
192 
200  bool equals(const char* cstr, size_t len = 0) const;
201 
206  bool equals(const String& str) const;
207 
208  bool operator==(const char* str) const
209  {
210  return equals(str);
211  }
212 
213  bool operator==(const String& str) const
214  {
215  return equals(str);
216  }
217 
218  bool operator!=(const char* str) const
219  {
220  return !equals(str);
221  }
222 
223  bool operator!=(const String& str) const
224  {
225  return !equals(str);
226  }
227 
228  /* WString support */
229 
230  operator WString() const;
231 
232  bool equals(const WString& str) const;
233 
234  bool equalsIgnoreCase(const WString& str) const;
235 
236  bool operator==(const WString& str) const
237  {
238  return equals(str);
239  }
240 
241  bool operator!=(const WString& str) const
242  {
243  return !equals(str);
244  }
245 
246  /* Arduino Print support */
247 
258  {
259  return StringPrinter(*this);
260  }
261 
262  size_t printTo(Print& p) const
263  {
264  return printer().printTo(p);
265  }
266 };
267 
268 } // namespace FSTR
269 
const __FlashStringHelper * flash_string_t
Definition: String.hpp:29
const __FlashStringHelper * flash_string_t
Provides a strongly-typed pointer to allow safe implicit operation using String class methods.
Definition: WString.h:96
Base class template for all types.
Definition: Object.hpp:121
const ElementType * data() const
Definition: Object.hpp:203
size_t length() const
Get the length of the content in elements.
Definition: Object.hpp:164
Wrapper class to efficiently print large Strings.
Definition: StringPrinter.hpp:35
size_t printTo(Print &p) const
describes a counted string stored in flash memory
Definition: String.hpp:174
bool operator!=(const WString &str) const
Definition: String.hpp:241
bool operator!=(const String &str) const
Definition: String.hpp:223
bool operator==(const char *str) const
Definition: String.hpp:208
bool equalsIgnoreCase(const WString &str) const
bool operator==(const WString &str) const
Definition: String.hpp:236
bool equals(const String &str) const
Check for equality with another String.
bool operator==(const String &str) const
Definition: String.hpp:213
StringPrinter printer() const
Supports printing of large String objects.
Definition: String.hpp:257
bool equals(const char *cstr, size_t len=0) const
Check for equality with a C-string.
bool operator!=(const char *str) const
Definition: String.hpp:218
flash_string_t data() const
Get a WString-compatible pointer to the flash data.
Definition: String.hpp:188
bool equals(const WString &str) const
size_t size() const
Get the number of bytes used to store the String.
Definition: String.hpp:180
size_t printTo(Print &p) const
Definition: String.hpp:262
Provides formatted output to stream.
Definition: Print.h:37
The String class.
Definition: WString.h:137
#define ALIGNUP4(n)
Align a size up to the nearest word boundary.
Definition: FakePgmSpace.h:39
Definition: Array.hpp:108
::String WString
A Wiring String.
Definition: String.hpp:168
#define str(s)
Definition: testrunner.h:124