ManagedString#

Overview#

ManagedString represents a text string in the micro:bit runtime.

A string is simply a sequence of characters such as “joe” or “micro:bit”.

In the C language, the end of the string is marked by a special character (a NULL character, commonly with the value zero).

Simple strings are often represented as literal character arrays:

uBit.display.scroll("HELLO");

Which is almost exactly the same as:

char message[6] = {'H', 'E', 'L', 'L', 'O', 0};
uBit.display.scroll(message);

Although fantastically simple, strings of this form are well known to lead to memory leaks and be sources of bugs in code (especially when the programmers are still learning!).

As a result, most modern high level languages such as Java, C#, Javascript and TouchDevelop do not use strings of this format. Instead, they provide code that is capable of ensuring strings remain safe.

ManagedString provides this equivalent functionality for the micro:bit, as a building block for higher level languages. However, it can also makes programming the micro:bit in C easier too!

Note

This is a managed type. This means that it will automatically use and release memory as needed. There is no need for you to explicitly free or release memory when your done - the memory will be freed as soon as the last piece of code stops using the data.

Creating Strings#

Images are simple to create - just create them like a variable, and provide the text or number you would like to build the string from.

For example:

ManagedString hi("HELLO");
ManagedString message("micro:bit");
ManagedString n(42);

The runtime will also create a ManagedString for you from a number or quoted literal anytime a function requires a ManagedString.

In the example below, even though the scroll function of MicroBitDisplay expects a ManagedString, it is totally fine to pass a literal value in quotes or a number (or in fact, any parameter that is listed in the API section as a legal constructor will work):

ManagedString hi("HELLO");
ManagedString message("micro:bit");
ManagedString n(42);

// All these calls are legal:
uBit.display.scroll(hi);
uBit.display.scroll(n);
uBit.display.scroll("THANKS!");

Manipulating Strings#

ManagedStrings are immutable, meaning that once created, they cannot be changed. However, you can join them, search them, extract characters from them and create other strings!

The micro:bit runtime makes use of operator overloading to keep this easy to use.

In other words, we make use of the = + < > and == operators to let you easily assign and compare strings.

Although this may sound complex, it is easy once you see how to do it.

Here is how you would join together more than one string, and assign it to a new one:

ManagedString hi("HELLO");
ManagedString message("micro:bit");
ManagedString space(" ");

ManagedString s = hi + space + message;

// This would say "HELLO micro:bit" on the LED display.
uBit.display.scroll(s);

You can compare strings (alphabetically) in a similar way:

ManagedString hi("HELLO");
ManagedString message("micro:bit");

if (hi == message)
    uBit.display.scroll("SAME");

if (hi < message)
    uBit.display.scroll("LESS");

if (hi > message)
    uBit.display.scroll("MORE");

You can also determine the length of a string, extract parts of strings, retrieve individual characters at a given index or convert a ManagedString to a C-style character array using the length, substring, charAt and toCharArray functions respectively.

See the API documentation below for further details.

API#

Constructor#


ManagedString(
StringData *
ptr)#

Description#

Constructor. Create a managed string from a specially prepared string literal.

Parameters#

StringData *
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.

Example#
 static const char hello[] __attribute__ ((aligned (4))) = "\xff\xff\x05\x00" "Hello"; 
 ManagedString s((StringData*)(void*)hello); 

leakData#


StringData
leakData
()#

Description#

Get current ptr, do not decr() it, and set the current instance to empty string.

This is to be used by specialized runtimes which pass StringData around.

Constructor#


ManagedString(
const char *
str)#

Description#

Constructor.

Create a managed string from a pointer to an 8-bit character buffer.

The buffer is copied to ensure safe memory management (the supplied character buffer may be declared on the stack for instance).

Parameters#

const char *
str - The character array on which to base the new ManagedString .

Example#
 ManagedString s("abcdefg"); 


ManagedString(
const int
value)#

Description#

Constructor.

Create a managed string from a given integer.

Parameters#

const int
value - The integer from which to create the ManagedString .

Example#
 ManagedString s(20); 


ManagedString(
const char
value)#

Description#

Constructor. Create a managed string from a given char.

Parameters#

const char
value - The character from which to create the ManagedString .

Example#
 ManagedString s('a'); 


ManagedString(
PacketBuffer
buffer)#

Description#

Constructor. Create a ManagedString from a PacketBuffer . All bytes in the PacketBuffer are added to the ManagedString .

Parameters#

PacketBuffer
buffer - The PacktBuffer from which to create the ManagedString .

Example#
 ManagedString s = radio.datagram.recv(); 


ManagedString(
const char *
str,
const int16_t
length)#

Description#

Constructor. Create a ManagedString from a pointer to an 8-bit character buffer of a given length.

The buffer is copied to ensure sane memory management (the supplied character buffer may be declared on the stack for instance).

Parameters#

const char *
str - The character array on which to base the new ManagedString .

const int16_t
length - The length of the character array

Example#
 ManagedString s("abcdefg",7); 


ManagedString(
const ManagedString &
s)#

Description#

Copy constructor. Makes a new ManagedString identical to the one supplied.

Shares the character buffer and reference count with the supplied ManagedString .

Parameters#

const ManagedString &
s - The ManagedString to copy.

Example#
 ManagedString s("abcdefg"); 
 ManagedString p(s); 


ManagedString()#

Description#

Default constructor.

Create an empty ManagedString .

Example#
 ManagedString s(); 

operator=#


ManagedString
operator=
(
const ManagedString &
s)#

Description#

Copy assign operation.

Called when one ManagedString is assigned the value of another.

If the ManagedString being assigned is already referring to a character buffer, decrement the reference count and free up the buffer as necessary.

Then, update our character buffer to refer to that of the supplied ManagedString , and increase its reference count.

Parameters#

const ManagedString &
s - The ManagedString to copy.

Example#
 ManagedString s("abcd"); 
 ManagedString p("efgh"); 
 p = s // p now points to s, s' ref is incremented 

operator==#


bool
operator==
(
const ManagedString &
s)#

Description#

Equality operation.

Called when one ManagedString is tested to be equal to another using the ‘==’ operator.

Parameters#

const ManagedString &
s - The ManagedString to test ourselves against.

Returns#

true if this ManagedString is identical to the one supplied, false otherwise.

Example#
 MicroBitDisplay display; 
 ManagedString s("abcd"); 
 ManagedString p("efgh"); 

 if(p == s) 
 display.scroll("We are the same!"); 
 else 
 display.scroll("We are different!"); //p is not equal to s - this will be called 

operator<#


bool
operator<
(
const ManagedString &
s)#

Description#

Inequality operation.

Called when one ManagedString is tested to be less than another using the ‘<’ operator.

Parameters#

const ManagedString &
s - The ManagedString to test ourselves against.

Returns#

true if this ManagedString is alphabetically less than to the one supplied, false otherwise.

Example#
 MicroBitDisplay display; 
 ManagedString s("a"); 
 ManagedString p("b"); 

 if(s < p) 
 display.scroll("a is before b!"); //a is before b 
 else 
 display.scroll("b is before a!"); 

operator>#


bool
operator>
(
const ManagedString &
s)#

Description#

Inequality operation.

Called when one ManagedString is tested to be greater than another using the ‘>’ operator.

Parameters#

const ManagedString &
s - The ManagedString to test ourselves against.

Returns#

true if this ManagedString is alphabetically greater than to the one supplied, false otherwise.

Example#
 MicroBitDisplay display; 
 ManagedString s("a"); 
 ManagedString p("b"); 

 if(p>a) 
 display.scroll("b is after a!"); //b is after a 
 else 
 display.scroll("a is after b!"); 

substring#


ManagedString
substring
(
int16_t
start,
int16_t
length)#

Description#

Extracts a ManagedString from this string, at the position provided.

Parameters#

int16_t
start - The index of the first character to extract, indexed from zero.

int16_t
length - The number of characters to extract from the start position

Returns#

a ManagedString representing the requested substring.

Example#
 MicroBitDisplay display; 
 ManagedString s("abcdefg"); 

 display.scroll(s.substring(0,2)) // displays "ab" 

charAt#


char
charAt
(
int16_t
index)#

Description#

Provides a character value at a given position in the string, indexed from zero.

Parameters#

int16_t
index - The position of the character to return.

Returns#

the character at posisiton index, zero if index is invalid.

Example#
 MicroBitDisplay display; 
 ManagedString s("abcd"); 

 display.scroll(s.charAt(1)) // scrolls "b" 

toCharArray#


const char *
toCharArray
()#

Description#

Provides an immutable 8 bit wide character buffer representing this string.

Returns#

a pointer to the character buffer.

length#


int16_t
length
()#

Description#

Determines the length of this ManagedString in characters.

Returns#

the length of the string in characters.

Example#
 MicroBitDisplay display; 
 ManagedString s("abcd"); 

 display.scroll(s.length()) // scrolls "4"