AceCommon  1.6.1
Arduino library for low-level common functions and features with no external dependencies
KString.h
1 /*
2 MIT License
3 
4 Copyright (c) 2021 Brian T. Park
5 
6 Permission is hereby granted, free of charge, to any person obtaining a copy
7 of this software and associated documentation files (the "Software"), to deal
8 in the Software without restriction, including without limitation the rights
9 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10 copies of the Software, and to permit persons to whom the Software is
11 furnished to do so, subject to the following conditions:
12 
13 The above copyright notice and this permission notice shall be included in all
14 copies or substantial portions of the Software.
15 
16 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22 SOFTWARE.
23 */
24 
25 #ifndef ACE_COMMON_KSTRING_H
26 #define ACE_COMMON_KSTRING_H
27 
28 #include <stdint.h> // int8_t
29 class __FlashStringHelper;
30 class Print;
31 
32 namespace ace_common {
33 
34 class KStringIterator;
35 
53 class KString {
54  friend class KStringIterator;
55  friend class KStringKeywords;
56 
57  public:
68  explicit KString(
69  const char* s,
70  const char* const* keywords,
71  uint8_t numKeywords
72  ):
73  string_(s),
74  keywords_((const void* const*) keywords),
75  stringType_(kTypeCstring),
76  keywordType_(kTypeCstring),
77  numKeywords_(numKeywords > 0x20 ? 0x20 : numKeywords)
78  {}
79 
91  explicit KString(
92  const __FlashStringHelper* s,
93  const char* const* keywords,
94  uint8_t numKeywords
95  ):
96  string_(s),
97  keywords_((const void* const*) keywords),
98  stringType_(kTypeFstring),
99  keywordType_(kTypeCstring),
100  numKeywords_(numKeywords > 0x20 ? 0x20 : numKeywords)
101  {}
102 
119  explicit KString(
120  const char* s,
121  const __FlashStringHelper* const* keywords,
122  uint8_t numKeywords
123  ):
124  string_(s),
125  keywords_((const void* const*) keywords),
126  stringType_(kTypeCstring),
127  keywordType_(kTypeFstring),
128  numKeywords_(numKeywords > 0x20 ? 0x20 : numKeywords)
129  {}
130 
147  explicit KString(
148  const __FlashStringHelper* s,
149  const __FlashStringHelper* const* keywords,
150  uint8_t numKeywords
151  ):
152  string_(s),
153  keywords_((const void* const*) keywords),
154  stringType_(kTypeFstring),
155  keywordType_(kTypeFstring),
156  numKeywords_(numKeywords > 0x20 ? 0x20 : numKeywords)
157  {}
158 
165  int compareTo(const char* s);
166 
172  int compareTo(const KString& s);
173 
175  void printTo(Print& printer);
176 
177  private:
178  static const uint8_t kTypeCstring = 0;
179  static const uint8_t kTypeFstring = 1;
180 
181  // The order of the following fields is deliberate to reduce the memory
182  // size of this class on 32-bit processors.
183  const void* const string_;
184  const void* const* const keywords_;
185  uint8_t const stringType_;
186  uint8_t const keywordType_;
187  uint8_t const numKeywords_;
188 };
189 
199  public:
202  ks_(ks),
203  firstPtr_((const char*) ks.string_),
204  secondPtr_(nullptr),
205  firstType_(ks.stringType_),
206  secondType_(KString::kTypeCstring) // initial value can be anything
207  {}
208 
218  char get();
219 
221  void next() { firstPtr_++; }
222 
223  private:
224  static char getInternal(uint8_t type, const char* p) {
225  return (type == KString::kTypeCstring) ? *p : pgm_read_byte(p);
226  }
227 
228  private:
229  // ordering of fields optimized to reduce gaps on 32-bit processors
230  const KString& ks_;
231  const char* firstPtr_;
232  const char* secondPtr_;
233  uint8_t firstType_;
234  uint8_t secondType_;
235 };
236 
243  public:
250  KStringKeywords(uint8_t type, const void* const* keywords) :
251  type_(type),
252  keywords_(keywords)
253  {}
254 
260  const char* get(uint8_t i) const {
261  if (type_ == KString::kTypeCstring) {
262  auto words = (const char* const*) keywords_;
263  return words[i];
264  } else {
265  auto words = (const __FlashStringHelper* const*) keywords_;
266  return (const char*) pgm_read_ptr(words + i);
267  }
268  }
269 
270  private:
271  uint8_t type_;
272  const void* const* keywords_;
273 };
274 
275 } // ace_common
276 
277 #endif
An interator that points to a character inside a KString.
Definition: KString.h:198
KStringIterator(const KString &ks)
Constructor.
Definition: KString.h:201
void next()
Advance the iterator one character,.
Definition: KString.h:221
char get()
Return the current character referenced by the iterator.
Definition: KString.cpp:110
A thin helper object around an array of const char* in regular memory, or an array of const __FlashSt...
Definition: KString.h:242
KStringKeywords(uint8_t type, const void *const *keywords)
Definition: KString.h:250
const char * get(uint8_t i) const
Return the string pointer of index i.
Definition: KString.h:260
A wrapper class around a normal c-string or Arduino f-string which is encoded and compressed using ke...
Definition: KString.h:53
void printTo(Print &printer)
Expand and print the current string to the given printer.
Definition: KString.cpp:84
KString(const char *s, const __FlashStringHelper *const *keywords, uint8_t numKeywords)
Constructor around a c-string, and an array of keyword strings in flash memory.
Definition: KString.h:119
int compareTo(const char *s)
Compare this string against a c-string s and return <0, 0 or >0 if this string is <,...
Definition: KString.cpp:7
KString(const char *s, const char *const *keywords, uint8_t numKeywords)
Constructor around a simple c-string, and an array of keyword strings in normal memory.
Definition: KString.h:68
KString(const __FlashStringHelper *s, const __FlashStringHelper *const *keywords, uint8_t numKeywords)
Constructor around an f-string, and an array of keyword strings in flash memory.
Definition: KString.h:147
KString(const __FlashStringHelper *s, const char *const *keywords, uint8_t numKeywords)
Constructor around an f-string, and an array of keyword strings in normal memory.
Definition: KString.h:91