Forked to avoid changing the publioc repo
Dependencies: BLE_API mbed-dev-bin nRF51822
Fork of microbit-dal by
ManagedString.h
00001 /* 00002 The MIT License (MIT) 00003 00004 Copyright (c) 2016 British Broadcasting Corporation. 00005 This software is provided by Lancaster University by arrangement with the BBC. 00006 00007 Permission is hereby granted, free of charge, to any person obtaining a 00008 copy of this software and associated documentation files (the "Software"), 00009 to deal in the Software without restriction, including without limitation 00010 the rights to use, copy, modify, merge, publish, distribute, sublicense, 00011 and/or sell copies of the Software, and to permit persons to whom the 00012 Software is furnished to do so, subject to the following conditions: 00013 00014 The above copyright notice and this permission notice shall be included in 00015 all copies or substantial portions of the Software. 00016 00017 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 00018 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 00019 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 00020 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 00021 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 00022 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 00023 DEALINGS IN THE SOFTWARE. 00024 */ 00025 00026 #ifndef MANAGED_STRING_H 00027 #define MANAGED_STRING_H 00028 00029 #include "MicroBitConfig.h" 00030 #include "RefCounted.h" 00031 #include "PacketBuffer.h" 00032 00033 struct StringData : RefCounted 00034 { 00035 uint16_t len; 00036 char data[0]; 00037 }; 00038 00039 00040 /** 00041 * Class definition for a ManagedString. 00042 * 00043 * Uses basic reference counting to implement a copy-assignable, immutable string. 00044 * 00045 * This maps closely to the constructs found in many high level application languages, 00046 * such as Touch Develop. 00047 * 00048 * Written from first principles here, for several reasons: 00049 * 1) std::shared_ptr is not yet availiable on the ARMCC compiler 00050 * 00051 * 2) to reduce memory footprint - we don't need many of the other features in the std library 00052 * 00053 * 3) it makes an interesting case study for anyone interested in seeing how it works! 00054 * 00055 * 4) we need explicit reference counting to inter-op with low-level application langauge runtimes. 00056 * 00057 * 5) the reference counting needs to also work for read-only, flash-resident strings 00058 */ 00059 class ManagedString 00060 { 00061 // StringData contains the reference count, the length, follwed by char[] data, all in one block. 00062 // When referece count is 0xffff, then it's read only and should not be counted. 00063 // Otherwise the block was malloc()ed. 00064 // We control access to this to proide immutability and reference counting. 00065 StringData *ptr; 00066 00067 public: 00068 00069 /** 00070 * Constructor. 00071 * Create a managed string from a specially prepared string literal. 00072 * 00073 * @param ptr The literal - first two bytes should be 0xff, then the length in little endian, then the literal. The literal has to be 4-byte aligned. 00074 * 00075 * @code 00076 * static const char hello[] __attribute__ ((aligned (4))) = "\xff\xff\x05\x00" "Hello"; 00077 * ManagedString s((StringData*)(void*)hello); 00078 * @endcode 00079 */ 00080 ManagedString(StringData *ptr); 00081 00082 /** 00083 * Get current ptr, do not decr() it, and set the current instance to empty string. 00084 * 00085 * This is to be used by specialized runtimes which pass StringData around. 00086 */ 00087 StringData *leakData(); 00088 00089 /** 00090 * Constructor. 00091 * 00092 * Create a managed string from a pointer to an 8-bit character buffer. 00093 * 00094 * The buffer is copied to ensure safe memory management (the supplied 00095 * character buffer may be declared on the stack for instance). 00096 * 00097 * @param str The character array on which to base the new ManagedString. 00098 * 00099 * @code 00100 * ManagedString s("abcdefg"); 00101 * @endcode 00102 */ 00103 ManagedString(const char *str); 00104 00105 /** 00106 * Constructor. 00107 * 00108 * Create a managed string from a given integer. 00109 * 00110 * @param value The integer from which to create the ManagedString. 00111 * 00112 * @code 00113 * ManagedString s(20); 00114 * @endcode 00115 */ 00116 ManagedString(const int value); 00117 00118 00119 /** 00120 * Constructor. 00121 * Create a managed string from a given char. 00122 * 00123 * @param value The character from which to create the ManagedString. 00124 * 00125 * @code 00126 * ManagedString s('a'); 00127 * @endcode 00128 */ 00129 ManagedString(const char value); 00130 00131 /** 00132 * Constructor. 00133 * Create a ManagedString from a PacketBuffer. All bytes in the 00134 * PacketBuffer are added to the ManagedString. 00135 * 00136 * @param buffer The PacktBuffer from which to create the ManagedString. 00137 * 00138 * @code 00139 * ManagedString s = radio.datagram.recv(); 00140 * @endcode 00141 */ 00142 ManagedString(PacketBuffer buffer); 00143 00144 /** 00145 * Constructor. 00146 * Create a ManagedString from a pointer to an 8-bit character buffer of a given length. 00147 * 00148 * The buffer is copied to ensure sane memory management (the supplied 00149 * character buffer may be declared on the stack for instance). 00150 * 00151 * @param str The character array on which to base the new ManagedString. 00152 * 00153 * @param length The length of the character array 00154 * 00155 * @code 00156 * ManagedString s("abcdefg",7); 00157 * @endcode 00158 */ 00159 ManagedString(const char *str, const int16_t length); 00160 00161 /** 00162 * Copy constructor. 00163 * Makes a new ManagedString identical to the one supplied. 00164 * 00165 * Shares the character buffer and reference count with the supplied ManagedString. 00166 * 00167 * @param s The ManagedString to copy. 00168 * 00169 * @code 00170 * ManagedString s("abcdefg"); 00171 * ManagedString p(s); 00172 * @endcode 00173 */ 00174 ManagedString(const ManagedString &s); 00175 00176 /** 00177 * Default constructor. 00178 * 00179 * Create an empty ManagedString. 00180 * 00181 * @code 00182 * ManagedString s(); 00183 * @endcode 00184 */ 00185 ManagedString(); 00186 00187 /** 00188 * Destructor. 00189 * 00190 * Free this ManagedString, and decrement the reference count to the 00191 * internal character buffer. 00192 * 00193 * If we're holding the last reference, also free the character buffer. 00194 */ 00195 ~ManagedString(); 00196 00197 /** 00198 * Copy assign operation. 00199 * 00200 * Called when one ManagedString is assigned the value of another. 00201 * 00202 * If the ManagedString being assigned is already referring to a character buffer, 00203 * decrement the reference count and free up the buffer as necessary. 00204 * 00205 * Then, update our character buffer to refer to that of the supplied ManagedString, 00206 * and increase its reference count. 00207 * 00208 * @param s The ManagedString to copy. 00209 * 00210 * @code 00211 * ManagedString s("abcd"); 00212 * ManagedString p("efgh"); 00213 * p = s // p now points to s, s' ref is incremented 00214 * @endcode 00215 */ 00216 ManagedString& operator = (const ManagedString& s); 00217 00218 /** 00219 * Equality operation. 00220 * 00221 * Called when one ManagedString is tested to be equal to another using the '==' operator. 00222 * 00223 * @param s The ManagedString to test ourselves against. 00224 * 00225 * @return true if this ManagedString is identical to the one supplied, false otherwise. 00226 * 00227 * @code 00228 * MicroBitDisplay display; 00229 * ManagedString s("abcd"); 00230 * ManagedString p("efgh"); 00231 * 00232 * if(p == s) 00233 * display.scroll("We are the same!"); 00234 * else 00235 * display.scroll("We are different!"); //p is not equal to s - this will be called 00236 * @endcode 00237 */ 00238 bool operator== (const ManagedString& s); 00239 00240 /** 00241 * Inequality operation. 00242 * 00243 * Called when one ManagedString is tested to be less than another using the '<' operator. 00244 * 00245 * @param s The ManagedString to test ourselves against. 00246 * 00247 * @return true if this ManagedString is alphabetically less than to the one supplied, false otherwise. 00248 * 00249 * @code 00250 * MicroBitDisplay display; 00251 * ManagedString s("a"); 00252 * ManagedString p("b"); 00253 * 00254 * if(s < p) 00255 * display.scroll("a is before b!"); //a is before b 00256 * else 00257 * display.scroll("b is before a!"); 00258 * @endcode 00259 */ 00260 bool operator< (const ManagedString& s); 00261 00262 /** 00263 * Inequality operation. 00264 * 00265 * Called when one ManagedString is tested to be greater than another using the '>' operator. 00266 * 00267 * @param s The ManagedString to test ourselves against. 00268 * 00269 * @return true if this ManagedString is alphabetically greater than to the one supplied, false otherwise. 00270 * 00271 * @code 00272 * MicroBitDisplay display; 00273 * ManagedString s("a"); 00274 * ManagedString p("b"); 00275 * 00276 * if(p>a) 00277 * display.scroll("b is after a!"); //b is after a 00278 * else 00279 * display.scroll("a is after b!"); 00280 * @endcode 00281 */ 00282 bool operator> (const ManagedString& s); 00283 00284 /** 00285 * Extracts a ManagedString from this string, at the position provided. 00286 * 00287 * @param start The index of the first character to extract, indexed from zero. 00288 * 00289 * @param length The number of characters to extract from the start position 00290 * 00291 * @return a ManagedString representing the requested substring. 00292 * 00293 * @code 00294 * MicroBitDisplay display; 00295 * ManagedString s("abcdefg"); 00296 * 00297 * display.scroll(s.substring(0,2)) // displays "ab" 00298 * @endcode 00299 */ 00300 ManagedString substring(int16_t start, int16_t length); 00301 00302 /** 00303 * Concatenates two strings. 00304 * 00305 * @param lhs The first ManagedString to concatenate. 00306 * @param rhs The second ManagedString to concatenate. 00307 * 00308 * @return a new ManagedString representing the joined strings. 00309 * 00310 * @code 00311 * MicroBitDisplay display; 00312 * ManagedString s("abcd"); 00313 * ManagedString p("efgh") 00314 * 00315 * display.scroll(s + p) // scrolls "abcdefgh" 00316 * @endcode 00317 */ 00318 friend ManagedString operator+ (const ManagedString& lhs, const ManagedString& rhs); 00319 00320 /** 00321 * Provides a character value at a given position in the string, indexed from zero. 00322 * 00323 * @param index The position of the character to return. 00324 * 00325 * @return the character at posisiton index, zero if index is invalid. 00326 * 00327 * @code 00328 * MicroBitDisplay display; 00329 * ManagedString s("abcd"); 00330 * 00331 * display.scroll(s.charAt(1)) // scrolls "b" 00332 * @endcode 00333 */ 00334 char charAt(int16_t index); 00335 00336 00337 /** 00338 * Provides an immutable 8 bit wide character buffer representing this string. 00339 * 00340 * @return a pointer to the character buffer. 00341 */ 00342 const char *toCharArray() const 00343 { 00344 return ptr->data; 00345 } 00346 00347 /** 00348 * Determines the length of this ManagedString in characters. 00349 * 00350 * @return the length of the string in characters. 00351 * 00352 * @code 00353 * MicroBitDisplay display; 00354 * ManagedString s("abcd"); 00355 * 00356 * display.scroll(s.length()) // scrolls "4" 00357 * @endcode 00358 */ 00359 int16_t length() const 00360 { 00361 return ptr->len; 00362 } 00363 00364 /** 00365 * Empty String constant 00366 */ 00367 static ManagedString EmptyString; 00368 00369 private: 00370 00371 /** 00372 * Internal constructor helper. 00373 * 00374 * Configures this ManagedString to refer to the static EmptyString 00375 */ 00376 void initEmpty(); 00377 00378 /** 00379 * Internal constructor helper. 00380 * 00381 * Creates this ManagedString based on a given null terminated char array. 00382 */ 00383 void initString(const char *str); 00384 00385 /** 00386 * Private Constructor. 00387 * 00388 * Create a managed string based on a concat of two strings. 00389 * The buffer is copied to ensure sane memory management (the supplied 00390 * character buffer may be declared on the stack for instance). 00391 * 00392 * @param str1 The first string on which to base the new ManagedString. 00393 * 00394 * @param str2 The second string on which to base the new ManagedString. 00395 */ 00396 ManagedString(const ManagedString &s1, const ManagedString &s2); 00397 00398 }; 00399 00400 #endif
Generated on Tue Jul 12 2022 18:46:14 by 1.7.2