Cristiano Barbosa / microbit-dal2

security manager conflict commented 2

Dependencies:   BLE_API mbed-dev-bin nRF51822

Fork of microbit-dal by Lancaster University

inc/types/ManagedString.h@74:8cb1c4aa4527, 2018-01-26 (annotated)

Committer:
cristianobarbosa
Date:
Fri Jan 26 14:11:55 2018 +0000
Revision:
74:8cb1c4aa4527
Parent:
69:b62f231e51ce 
sender

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Jonathan Austin 1:8aa5cdb4ab67 1 /*
Jonathan Austin 1:8aa5cdb4ab67 2 The MIT License (MIT)
Jonathan Austin 1:8aa5cdb4ab67 3
Jonathan Austin 1:8aa5cdb4ab67 4 Copyright (c) 2016 British Broadcasting Corporation.
Jonathan Austin 1:8aa5cdb4ab67 5 This software is provided by Lancaster University by arrangement with the BBC.
Jonathan Austin 1:8aa5cdb4ab67 6
Jonathan Austin 1:8aa5cdb4ab67 7 Permission is hereby granted, free of charge, to any person obtaining a
Jonathan Austin 1:8aa5cdb4ab67 8 copy of this software and associated documentation files (the "Software"),
Jonathan Austin 1:8aa5cdb4ab67 9 to deal in the Software without restriction, including without limitation
Jonathan Austin 1:8aa5cdb4ab67 10 the rights to use, copy, modify, merge, publish, distribute, sublicense,
Jonathan Austin 1:8aa5cdb4ab67 11 and/or sell copies of the Software, and to permit persons to whom the
Jonathan Austin 1:8aa5cdb4ab67 12 Software is furnished to do so, subject to the following conditions:
Jonathan Austin 1:8aa5cdb4ab67 13
Jonathan Austin 1:8aa5cdb4ab67 14 The above copyright notice and this permission notice shall be included in
Jonathan Austin 1:8aa5cdb4ab67 15 all copies or substantial portions of the Software.
Jonathan Austin 1:8aa5cdb4ab67 16
Jonathan Austin 1:8aa5cdb4ab67 17 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
Jonathan Austin 1:8aa5cdb4ab67 18 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
Jonathan Austin 1:8aa5cdb4ab67 19 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
Jonathan Austin 1:8aa5cdb4ab67 20 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
Jonathan Austin 1:8aa5cdb4ab67 21 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
Jonathan Austin 1:8aa5cdb4ab67 22 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
Jonathan Austin 1:8aa5cdb4ab67 23 DEALINGS IN THE SOFTWARE.
Jonathan Austin 1:8aa5cdb4ab67 24 */
Jonathan Austin 1:8aa5cdb4ab67 25
Jonathan Austin 1:8aa5cdb4ab67 26 #ifndef MANAGED_STRING_H
Jonathan Austin 1:8aa5cdb4ab67 27 #define MANAGED_STRING_H
Jonathan Austin 1:8aa5cdb4ab67 28
Jonathan Austin 1:8aa5cdb4ab67 29 #include "MicroBitConfig.h"
Jonathan Austin 1:8aa5cdb4ab67 30 #include "RefCounted.h"
Jonathan Austin 1:8aa5cdb4ab67 31 #include "PacketBuffer.h"
Jonathan Austin 1:8aa5cdb4ab67 32
Jonathan Austin 1:8aa5cdb4ab67 33 struct StringData : RefCounted
Jonathan Austin 1:8aa5cdb4ab67 34 {
Jonathan Austin 1:8aa5cdb4ab67 35 uint16_t len;
Jonathan Austin 1:8aa5cdb4ab67 36 char data[0];
Jonathan Austin 1:8aa5cdb4ab67 37 };
Jonathan Austin 1:8aa5cdb4ab67 38
Jonathan Austin 1:8aa5cdb4ab67 39
Jonathan Austin 1:8aa5cdb4ab67 40 /**
Jonathan Austin 1:8aa5cdb4ab67 41 * Class definition for a ManagedString.
Jonathan Austin 1:8aa5cdb4ab67 42 *
Jonathan Austin 1:8aa5cdb4ab67 43 * Uses basic reference counting to implement a copy-assignable, immutable string.
Jonathan Austin 1:8aa5cdb4ab67 44 *
Jonathan Austin 1:8aa5cdb4ab67 45 * This maps closely to the constructs found in many high level application languages,
Jonathan Austin 1:8aa5cdb4ab67 46 * such as Touch Develop.
Jonathan Austin 1:8aa5cdb4ab67 47 *
Jonathan Austin 1:8aa5cdb4ab67 48 * Written from first principles here, for several reasons:
Jonathan Austin 1:8aa5cdb4ab67 49 * 1) std::shared_ptr is not yet availiable on the ARMCC compiler
Jonathan Austin 1:8aa5cdb4ab67 50 *
Jonathan Austin 1:8aa5cdb4ab67 51 * 2) to reduce memory footprint - we don't need many of the other features in the std library
Jonathan Austin 1:8aa5cdb4ab67 52 *
Jonathan Austin 1:8aa5cdb4ab67 53 * 3) it makes an interesting case study for anyone interested in seeing how it works!
Jonathan Austin 1:8aa5cdb4ab67 54 *
Jonathan Austin 1:8aa5cdb4ab67 55 * 4) we need explicit reference counting to inter-op with low-level application langauge runtimes.
Jonathan Austin 1:8aa5cdb4ab67 56 *
Jonathan Austin 1:8aa5cdb4ab67 57 * 5) the reference counting needs to also work for read-only, flash-resident strings
Jonathan Austin 1:8aa5cdb4ab67 58 */
Jonathan Austin 1:8aa5cdb4ab67 59 class ManagedString
Jonathan Austin 1:8aa5cdb4ab67 60 {
Jonathan Austin 1:8aa5cdb4ab67 61 // StringData contains the reference count, the length, follwed by char[] data, all in one block.
Jonathan Austin 1:8aa5cdb4ab67 62 // When referece count is 0xffff, then it's read only and should not be counted.
Jonathan Austin 1:8aa5cdb4ab67 63 // Otherwise the block was malloc()ed.
Jonathan Austin 1:8aa5cdb4ab67 64 // We control access to this to proide immutability and reference counting.
Jonathan Austin 1:8aa5cdb4ab67 65 StringData *ptr;
Jonathan Austin 1:8aa5cdb4ab67 66
Jonathan Austin 1:8aa5cdb4ab67 67 public:
Jonathan Austin 1:8aa5cdb4ab67 68
Jonathan Austin 1:8aa5cdb4ab67 69 /**
Jonathan Austin 1:8aa5cdb4ab67 70 * Constructor.
Jonathan Austin 1:8aa5cdb4ab67 71 * Create a managed string from a specially prepared string literal.
Jonathan Austin 1:8aa5cdb4ab67 72 *
Jonathan Austin 1:8aa5cdb4ab67 73 * @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.
Jonathan Austin 1:8aa5cdb4ab67 74 *
Jonathan Austin 1:8aa5cdb4ab67 75 * @code
Jonathan Austin 1:8aa5cdb4ab67 76 * static const char hello[] __attribute__ ((aligned (4))) = "\xff\xff\x05\x00" "Hello";
Jonathan Austin 1:8aa5cdb4ab67 77 * ManagedString s((StringData*)(void*)hello);
Jonathan Austin 1:8aa5cdb4ab67 78 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 79 */
Jonathan Austin 1:8aa5cdb4ab67 80 ManagedString(StringData *ptr);
Jonathan Austin 1:8aa5cdb4ab67 81
Jonathan Austin 1:8aa5cdb4ab67 82 /**
Jonathan Austin 1:8aa5cdb4ab67 83 * Get current ptr, do not decr() it, and set the current instance to empty string.
Jonathan Austin 1:8aa5cdb4ab67 84 *
Jonathan Austin 1:8aa5cdb4ab67 85 * This is to be used by specialized runtimes which pass StringData around.
Jonathan Austin 1:8aa5cdb4ab67 86 */
Jonathan Austin 1:8aa5cdb4ab67 87 StringData *leakData();
Jonathan Austin 1:8aa5cdb4ab67 88
Jonathan Austin 1:8aa5cdb4ab67 89 /**
Jonathan Austin 1:8aa5cdb4ab67 90 * Constructor.
Jonathan Austin 1:8aa5cdb4ab67 91 *
Jonathan Austin 1:8aa5cdb4ab67 92 * Create a managed string from a pointer to an 8-bit character buffer.
Jonathan Austin 1:8aa5cdb4ab67 93 *
Jonathan Austin 1:8aa5cdb4ab67 94 * The buffer is copied to ensure safe memory management (the supplied
Jonathan Austin 1:8aa5cdb4ab67 95 * character buffer may be declared on the stack for instance).
Jonathan Austin 1:8aa5cdb4ab67 96 *
Jonathan Austin 1:8aa5cdb4ab67 97 * @param str The character array on which to base the new ManagedString.
Jonathan Austin 1:8aa5cdb4ab67 98 *
Jonathan Austin 1:8aa5cdb4ab67 99 * @code
Jonathan Austin 1:8aa5cdb4ab67 100 * ManagedString s("abcdefg");
Jonathan Austin 1:8aa5cdb4ab67 101 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 102 */
Jonathan Austin 1:8aa5cdb4ab67 103 ManagedString(const char *str);
Jonathan Austin 1:8aa5cdb4ab67 104
Jonathan Austin 1:8aa5cdb4ab67 105 /**
Jonathan Austin 1:8aa5cdb4ab67 106 * Constructor.
Jonathan Austin 1:8aa5cdb4ab67 107 *
Jonathan Austin 1:8aa5cdb4ab67 108 * Create a managed string from a given integer.
Jonathan Austin 1:8aa5cdb4ab67 109 *
Jonathan Austin 1:8aa5cdb4ab67 110 * @param value The integer from which to create the ManagedString.
Jonathan Austin 1:8aa5cdb4ab67 111 *
Jonathan Austin 1:8aa5cdb4ab67 112 * @code
Jonathan Austin 1:8aa5cdb4ab67 113 * ManagedString s(20);
Jonathan Austin 1:8aa5cdb4ab67 114 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 115 */
Jonathan Austin 1:8aa5cdb4ab67 116 ManagedString(const int value);
Jonathan Austin 1:8aa5cdb4ab67 117
Jonathan Austin 1:8aa5cdb4ab67 118
Jonathan Austin 1:8aa5cdb4ab67 119 /**
Jonathan Austin 1:8aa5cdb4ab67 120 * Constructor.
Jonathan Austin 1:8aa5cdb4ab67 121 * Create a managed string from a given char.
Jonathan Austin 1:8aa5cdb4ab67 122 *
Jonathan Austin 1:8aa5cdb4ab67 123 * @param value The character from which to create the ManagedString.
Jonathan Austin 1:8aa5cdb4ab67 124 *
Jonathan Austin 1:8aa5cdb4ab67 125 * @code
Jonathan Austin 1:8aa5cdb4ab67 126 * ManagedString s('a');
Jonathan Austin 1:8aa5cdb4ab67 127 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 128 */
Jonathan Austin 1:8aa5cdb4ab67 129 ManagedString(const char value);
Jonathan Austin 1:8aa5cdb4ab67 130
Jonathan Austin 1:8aa5cdb4ab67 131 /**
Jonathan Austin 1:8aa5cdb4ab67 132 * Constructor.
Jonathan Austin 1:8aa5cdb4ab67 133 * Create a ManagedString from a PacketBuffer. All bytes in the
Jonathan Austin 1:8aa5cdb4ab67 134 * PacketBuffer are added to the ManagedString.
Jonathan Austin 1:8aa5cdb4ab67 135 *
Jonathan Austin 1:8aa5cdb4ab67 136 * @param buffer The PacktBuffer from which to create the ManagedString.
Jonathan Austin 1:8aa5cdb4ab67 137 *
Jonathan Austin 1:8aa5cdb4ab67 138 * @code
Jonathan Austin 1:8aa5cdb4ab67 139 * ManagedString s = radio.datagram.recv();
Jonathan Austin 1:8aa5cdb4ab67 140 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 141 */
Jonathan Austin 1:8aa5cdb4ab67 142 ManagedString(PacketBuffer buffer);
Jonathan Austin 1:8aa5cdb4ab67 143
Jonathan Austin 1:8aa5cdb4ab67 144 /**
Jonathan Austin 1:8aa5cdb4ab67 145 * Constructor.
Jonathan Austin 1:8aa5cdb4ab67 146 * Create a ManagedString from a pointer to an 8-bit character buffer of a given length.
Jonathan Austin 1:8aa5cdb4ab67 147 *
Jonathan Austin 1:8aa5cdb4ab67 148 * The buffer is copied to ensure sane memory management (the supplied
Jonathan Austin 1:8aa5cdb4ab67 149 * character buffer may be declared on the stack for instance).
Jonathan Austin 1:8aa5cdb4ab67 150 *
Jonathan Austin 1:8aa5cdb4ab67 151 * @param str The character array on which to base the new ManagedString.
Jonathan Austin 1:8aa5cdb4ab67 152 *
Jonathan Austin 1:8aa5cdb4ab67 153 * @param length The length of the character array
Jonathan Austin 1:8aa5cdb4ab67 154 *
Jonathan Austin 1:8aa5cdb4ab67 155 * @code
Jonathan Austin 1:8aa5cdb4ab67 156 * ManagedString s("abcdefg",7);
Jonathan Austin 1:8aa5cdb4ab67 157 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 158 */
Jonathan Austin 1:8aa5cdb4ab67 159 ManagedString(const char *str, const int16_t length);
Jonathan Austin 1:8aa5cdb4ab67 160
Jonathan Austin 1:8aa5cdb4ab67 161 /**
Jonathan Austin 1:8aa5cdb4ab67 162 * Copy constructor.
Jonathan Austin 1:8aa5cdb4ab67 163 * Makes a new ManagedString identical to the one supplied.
Jonathan Austin 1:8aa5cdb4ab67 164 *
Jonathan Austin 1:8aa5cdb4ab67 165 * Shares the character buffer and reference count with the supplied ManagedString.
Jonathan Austin 1:8aa5cdb4ab67 166 *
Jonathan Austin 1:8aa5cdb4ab67 167 * @param s The ManagedString to copy.
Jonathan Austin 1:8aa5cdb4ab67 168 *
Jonathan Austin 1:8aa5cdb4ab67 169 * @code
Jonathan Austin 1:8aa5cdb4ab67 170 * ManagedString s("abcdefg");
Jonathan Austin 1:8aa5cdb4ab67 171 * ManagedString p(s);
Jonathan Austin 1:8aa5cdb4ab67 172 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 173 */
Jonathan Austin 1:8aa5cdb4ab67 174 ManagedString(const ManagedString &s);
Jonathan Austin 1:8aa5cdb4ab67 175
Jonathan Austin 1:8aa5cdb4ab67 176 /**
Jonathan Austin 1:8aa5cdb4ab67 177 * Default constructor.
Jonathan Austin 1:8aa5cdb4ab67 178 *
Jonathan Austin 1:8aa5cdb4ab67 179 * Create an empty ManagedString.
Jonathan Austin 1:8aa5cdb4ab67 180 *
Jonathan Austin 1:8aa5cdb4ab67 181 * @code
Jonathan Austin 1:8aa5cdb4ab67 182 * ManagedString s();
Jonathan Austin 1:8aa5cdb4ab67 183 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 184 */
Jonathan Austin 1:8aa5cdb4ab67 185 ManagedString();
Jonathan Austin 1:8aa5cdb4ab67 186
Jonathan Austin 1:8aa5cdb4ab67 187 /**
Jonathan Austin 1:8aa5cdb4ab67 188 * Destructor.
Jonathan Austin 1:8aa5cdb4ab67 189 *
Jonathan Austin 1:8aa5cdb4ab67 190 * Free this ManagedString, and decrement the reference count to the
Jonathan Austin 1:8aa5cdb4ab67 191 * internal character buffer.
Jonathan Austin 1:8aa5cdb4ab67 192 *
Jonathan Austin 1:8aa5cdb4ab67 193 * If we're holding the last reference, also free the character buffer.
Jonathan Austin 1:8aa5cdb4ab67 194 */
Jonathan Austin 1:8aa5cdb4ab67 195 ~ManagedString();
Jonathan Austin 1:8aa5cdb4ab67 196
Jonathan Austin 1:8aa5cdb4ab67 197 /**
Jonathan Austin 1:8aa5cdb4ab67 198 * Copy assign operation.
Jonathan Austin 1:8aa5cdb4ab67 199 *
Jonathan Austin 1:8aa5cdb4ab67 200 * Called when one ManagedString is assigned the value of another.
Jonathan Austin 1:8aa5cdb4ab67 201 *
LancasterUniversity 69:b62f231e51ce 202 * If the ManagedString being assigned is already referring to a character buffer,
Jonathan Austin 1:8aa5cdb4ab67 203 * decrement the reference count and free up the buffer as necessary.
Jonathan Austin 1:8aa5cdb4ab67 204 *
Jonathan Austin 1:8aa5cdb4ab67 205 * Then, update our character buffer to refer to that of the supplied ManagedString,
Jonathan Austin 1:8aa5cdb4ab67 206 * and increase its reference count.
Jonathan Austin 1:8aa5cdb4ab67 207 *
Jonathan Austin 1:8aa5cdb4ab67 208 * @param s The ManagedString to copy.
Jonathan Austin 1:8aa5cdb4ab67 209 *
Jonathan Austin 1:8aa5cdb4ab67 210 * @code
Jonathan Austin 1:8aa5cdb4ab67 211 * ManagedString s("abcd");
Jonathan Austin 1:8aa5cdb4ab67 212 * ManagedString p("efgh");
Jonathan Austin 1:8aa5cdb4ab67 213 * p = s // p now points to s, s' ref is incremented
Jonathan Austin 1:8aa5cdb4ab67 214 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 215 */
Jonathan Austin 1:8aa5cdb4ab67 216 ManagedString& operator = (const ManagedString& s);
Jonathan Austin 1:8aa5cdb4ab67 217
Jonathan Austin 1:8aa5cdb4ab67 218 /**
Jonathan Austin 1:8aa5cdb4ab67 219 * Equality operation.
Jonathan Austin 1:8aa5cdb4ab67 220 *
Jonathan Austin 1:8aa5cdb4ab67 221 * Called when one ManagedString is tested to be equal to another using the '==' operator.
Jonathan Austin 1:8aa5cdb4ab67 222 *
Jonathan Austin 1:8aa5cdb4ab67 223 * @param s The ManagedString to test ourselves against.
Jonathan Austin 1:8aa5cdb4ab67 224 *
Jonathan Austin 1:8aa5cdb4ab67 225 * @return true if this ManagedString is identical to the one supplied, false otherwise.
Jonathan Austin 1:8aa5cdb4ab67 226 *
Jonathan Austin 1:8aa5cdb4ab67 227 * @code
Jonathan Austin 1:8aa5cdb4ab67 228 * MicroBitDisplay display;
Jonathan Austin 1:8aa5cdb4ab67 229 * ManagedString s("abcd");
Jonathan Austin 1:8aa5cdb4ab67 230 * ManagedString p("efgh");
Jonathan Austin 1:8aa5cdb4ab67 231 *
Jonathan Austin 1:8aa5cdb4ab67 232 * if(p == s)
Jonathan Austin 1:8aa5cdb4ab67 233 * display.scroll("We are the same!");
Jonathan Austin 1:8aa5cdb4ab67 234 * else
Jonathan Austin 1:8aa5cdb4ab67 235 * display.scroll("We are different!"); //p is not equal to s - this will be called
Jonathan Austin 1:8aa5cdb4ab67 236 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 237 */
Jonathan Austin 1:8aa5cdb4ab67 238 bool operator== (const ManagedString& s);
Jonathan Austin 1:8aa5cdb4ab67 239
Jonathan Austin 1:8aa5cdb4ab67 240 /**
Jonathan Austin 1:8aa5cdb4ab67 241 * Inequality operation.
Jonathan Austin 1:8aa5cdb4ab67 242 *
Jonathan Austin 1:8aa5cdb4ab67 243 * Called when one ManagedString is tested to be less than another using the '<' operator.
Jonathan Austin 1:8aa5cdb4ab67 244 *
Jonathan Austin 1:8aa5cdb4ab67 245 * @param s The ManagedString to test ourselves against.
Jonathan Austin 1:8aa5cdb4ab67 246 *
Jonathan Austin 1:8aa5cdb4ab67 247 * @return true if this ManagedString is alphabetically less than to the one supplied, false otherwise.
Jonathan Austin 1:8aa5cdb4ab67 248 *
Jonathan Austin 1:8aa5cdb4ab67 249 * @code
Jonathan Austin 1:8aa5cdb4ab67 250 * MicroBitDisplay display;
Jonathan Austin 1:8aa5cdb4ab67 251 * ManagedString s("a");
Jonathan Austin 1:8aa5cdb4ab67 252 * ManagedString p("b");
Jonathan Austin 1:8aa5cdb4ab67 253 *
Jonathan Austin 1:8aa5cdb4ab67 254 * if(s < p)
Jonathan Austin 1:8aa5cdb4ab67 255 * display.scroll("a is before b!"); //a is before b
Jonathan Austin 1:8aa5cdb4ab67 256 * else
Jonathan Austin 1:8aa5cdb4ab67 257 * display.scroll("b is before a!");
Jonathan Austin 1:8aa5cdb4ab67 258 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 259 */
Jonathan Austin 1:8aa5cdb4ab67 260 bool operator< (const ManagedString& s);
Jonathan Austin 1:8aa5cdb4ab67 261
Jonathan Austin 1:8aa5cdb4ab67 262 /**
Jonathan Austin 1:8aa5cdb4ab67 263 * Inequality operation.
Jonathan Austin 1:8aa5cdb4ab67 264 *
Jonathan Austin 1:8aa5cdb4ab67 265 * Called when one ManagedString is tested to be greater than another using the '>' operator.
Jonathan Austin 1:8aa5cdb4ab67 266 *
Jonathan Austin 1:8aa5cdb4ab67 267 * @param s The ManagedString to test ourselves against.
Jonathan Austin 1:8aa5cdb4ab67 268 *
Jonathan Austin 1:8aa5cdb4ab67 269 * @return true if this ManagedString is alphabetically greater than to the one supplied, false otherwise.
Jonathan Austin 1:8aa5cdb4ab67 270 *
Jonathan Austin 1:8aa5cdb4ab67 271 * @code
Jonathan Austin 1:8aa5cdb4ab67 272 * MicroBitDisplay display;
Jonathan Austin 1:8aa5cdb4ab67 273 * ManagedString s("a");
Jonathan Austin 1:8aa5cdb4ab67 274 * ManagedString p("b");
Jonathan Austin 1:8aa5cdb4ab67 275 *
Jonathan Austin 1:8aa5cdb4ab67 276 * if(p>a)
Jonathan Austin 1:8aa5cdb4ab67 277 * display.scroll("b is after a!"); //b is after a
Jonathan Austin 1:8aa5cdb4ab67 278 * else
Jonathan Austin 1:8aa5cdb4ab67 279 * display.scroll("a is after b!");
Jonathan Austin 1:8aa5cdb4ab67 280 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 281 */
Jonathan Austin 1:8aa5cdb4ab67 282 bool operator> (const ManagedString& s);
Jonathan Austin 1:8aa5cdb4ab67 283
Jonathan Austin 1:8aa5cdb4ab67 284 /**
Jonathan Austin 1:8aa5cdb4ab67 285 * Extracts a ManagedString from this string, at the position provided.
Jonathan Austin 1:8aa5cdb4ab67 286 *
Jonathan Austin 1:8aa5cdb4ab67 287 * @param start The index of the first character to extract, indexed from zero.
Jonathan Austin 1:8aa5cdb4ab67 288 *
Jonathan Austin 1:8aa5cdb4ab67 289 * @param length The number of characters to extract from the start position
Jonathan Austin 1:8aa5cdb4ab67 290 *
Jonathan Austin 1:8aa5cdb4ab67 291 * @return a ManagedString representing the requested substring.
Jonathan Austin 1:8aa5cdb4ab67 292 *
Jonathan Austin 1:8aa5cdb4ab67 293 * @code
Jonathan Austin 1:8aa5cdb4ab67 294 * MicroBitDisplay display;
Jonathan Austin 1:8aa5cdb4ab67 295 * ManagedString s("abcdefg");
Jonathan Austin 1:8aa5cdb4ab67 296 *
Jonathan Austin 1:8aa5cdb4ab67 297 * display.scroll(s.substring(0,2)) // displays "ab"
Jonathan Austin 1:8aa5cdb4ab67 298 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 299 */
Jonathan Austin 1:8aa5cdb4ab67 300 ManagedString substring(int16_t start, int16_t length);
Jonathan Austin 1:8aa5cdb4ab67 301
Jonathan Austin 1:8aa5cdb4ab67 302 /**
LancasterUniversity 52:3db7b4d64316 303 * Concatenates two strings.
Jonathan Austin 1:8aa5cdb4ab67 304 *
LancasterUniversity 52:3db7b4d64316 305 * @param lhs The first ManagedString to concatenate.
LancasterUniversity 52:3db7b4d64316 306 * @param rhs The second ManagedString to concatenate.
Jonathan Austin 1:8aa5cdb4ab67 307 *
Jonathan Austin 1:8aa5cdb4ab67 308 * @return a new ManagedString representing the joined strings.
Jonathan Austin 1:8aa5cdb4ab67 309 *
Jonathan Austin 1:8aa5cdb4ab67 310 * @code
Jonathan Austin 1:8aa5cdb4ab67 311 * MicroBitDisplay display;
Jonathan Austin 1:8aa5cdb4ab67 312 * ManagedString s("abcd");
Jonathan Austin 1:8aa5cdb4ab67 313 * ManagedString p("efgh")
Jonathan Austin 1:8aa5cdb4ab67 314 *
Jonathan Austin 1:8aa5cdb4ab67 315 * display.scroll(s + p) // scrolls "abcdefgh"
Jonathan Austin 1:8aa5cdb4ab67 316 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 317 */
LancasterUniversity 52:3db7b4d64316 318 friend ManagedString operator+ (const ManagedString& lhs, const ManagedString& rhs);
Jonathan Austin 1:8aa5cdb4ab67 319
Jonathan Austin 1:8aa5cdb4ab67 320 /**
Jonathan Austin 1:8aa5cdb4ab67 321 * Provides a character value at a given position in the string, indexed from zero.
Jonathan Austin 1:8aa5cdb4ab67 322 *
Jonathan Austin 1:8aa5cdb4ab67 323 * @param index The position of the character to return.
Jonathan Austin 1:8aa5cdb4ab67 324 *
Jonathan Austin 1:8aa5cdb4ab67 325 * @return the character at posisiton index, zero if index is invalid.
Jonathan Austin 1:8aa5cdb4ab67 326 *
Jonathan Austin 1:8aa5cdb4ab67 327 * @code
Jonathan Austin 1:8aa5cdb4ab67 328 * MicroBitDisplay display;
Jonathan Austin 1:8aa5cdb4ab67 329 * ManagedString s("abcd");
Jonathan Austin 1:8aa5cdb4ab67 330 *
Jonathan Austin 1:8aa5cdb4ab67 331 * display.scroll(s.charAt(1)) // scrolls "b"
Jonathan Austin 1:8aa5cdb4ab67 332 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 333 */
Jonathan Austin 1:8aa5cdb4ab67 334 char charAt(int16_t index);
Jonathan Austin 1:8aa5cdb4ab67 335
Jonathan Austin 1:8aa5cdb4ab67 336
Jonathan Austin 1:8aa5cdb4ab67 337 /**
Jonathan Austin 1:8aa5cdb4ab67 338 * Provides an immutable 8 bit wide character buffer representing this string.
Jonathan Austin 1:8aa5cdb4ab67 339 *
Jonathan Austin 1:8aa5cdb4ab67 340 * @return a pointer to the character buffer.
Jonathan Austin 1:8aa5cdb4ab67 341 */
Jonathan Austin 1:8aa5cdb4ab67 342 const char *toCharArray() const
Jonathan Austin 1:8aa5cdb4ab67 343 {
Jonathan Austin 1:8aa5cdb4ab67 344 return ptr->data;
Jonathan Austin 1:8aa5cdb4ab67 345 }
Jonathan Austin 1:8aa5cdb4ab67 346
Jonathan Austin 1:8aa5cdb4ab67 347 /**
Jonathan Austin 1:8aa5cdb4ab67 348 * Determines the length of this ManagedString in characters.
Jonathan Austin 1:8aa5cdb4ab67 349 *
Jonathan Austin 1:8aa5cdb4ab67 350 * @return the length of the string in characters.
Jonathan Austin 1:8aa5cdb4ab67 351 *
Jonathan Austin 1:8aa5cdb4ab67 352 * @code
Jonathan Austin 1:8aa5cdb4ab67 353 * MicroBitDisplay display;
Jonathan Austin 1:8aa5cdb4ab67 354 * ManagedString s("abcd");
Jonathan Austin 1:8aa5cdb4ab67 355 *
Jonathan Austin 1:8aa5cdb4ab67 356 * display.scroll(s.length()) // scrolls "4"
Jonathan Austin 1:8aa5cdb4ab67 357 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 358 */
Jonathan Austin 1:8aa5cdb4ab67 359 int16_t length() const
Jonathan Austin 1:8aa5cdb4ab67 360 {
Jonathan Austin 1:8aa5cdb4ab67 361 return ptr->len;
Jonathan Austin 1:8aa5cdb4ab67 362 }
Jonathan Austin 1:8aa5cdb4ab67 363
Jonathan Austin 1:8aa5cdb4ab67 364 /**
Jonathan Austin 1:8aa5cdb4ab67 365 * Empty String constant
Jonathan Austin 1:8aa5cdb4ab67 366 */
Jonathan Austin 1:8aa5cdb4ab67 367 static ManagedString EmptyString;
Jonathan Austin 1:8aa5cdb4ab67 368
Jonathan Austin 1:8aa5cdb4ab67 369 private:
Jonathan Austin 1:8aa5cdb4ab67 370
Jonathan Austin 1:8aa5cdb4ab67 371 /**
Jonathan Austin 1:8aa5cdb4ab67 372 * Internal constructor helper.
Jonathan Austin 1:8aa5cdb4ab67 373 *
Jonathan Austin 1:8aa5cdb4ab67 374 * Configures this ManagedString to refer to the static EmptyString
Jonathan Austin 1:8aa5cdb4ab67 375 */
Jonathan Austin 1:8aa5cdb4ab67 376 void initEmpty();
Jonathan Austin 1:8aa5cdb4ab67 377
Jonathan Austin 1:8aa5cdb4ab67 378 /**
Jonathan Austin 1:8aa5cdb4ab67 379 * Internal constructor helper.
Jonathan Austin 1:8aa5cdb4ab67 380 *
Jonathan Austin 1:8aa5cdb4ab67 381 * Creates this ManagedString based on a given null terminated char array.
Jonathan Austin 1:8aa5cdb4ab67 382 */
Jonathan Austin 1:8aa5cdb4ab67 383 void initString(const char *str);
Jonathan Austin 1:8aa5cdb4ab67 384
Jonathan Austin 1:8aa5cdb4ab67 385 /**
Jonathan Austin 1:8aa5cdb4ab67 386 * Private Constructor.
Jonathan Austin 1:8aa5cdb4ab67 387 *
Jonathan Austin 1:8aa5cdb4ab67 388 * Create a managed string based on a concat of two strings.
Jonathan Austin 1:8aa5cdb4ab67 389 * The buffer is copied to ensure sane memory management (the supplied
Jonathan Austin 1:8aa5cdb4ab67 390 * character buffer may be declared on the stack for instance).
Jonathan Austin 1:8aa5cdb4ab67 391 *
Jonathan Austin 1:8aa5cdb4ab67 392 * @param str1 The first string on which to base the new ManagedString.
Jonathan Austin 1:8aa5cdb4ab67 393 *
Jonathan Austin 1:8aa5cdb4ab67 394 * @param str2 The second string on which to base the new ManagedString.
Jonathan Austin 1:8aa5cdb4ab67 395 */
Jonathan Austin 1:8aa5cdb4ab67 396 ManagedString(const ManagedString &s1, const ManagedString &s2);
Jonathan Austin 1:8aa5cdb4ab67 397
Jonathan Austin 1:8aa5cdb4ab67 398 };
Jonathan Austin 1:8aa5cdb4ab67 399
LancasterUniversity 51:9198e7bb83dc 400 #endif