Arduino Programming Language: StringObject

Name

String (object)

Description

The class String includes methods for examining individual characters, comparing strings, searching strings, extracting parts of strings, and for converting an entire string uppercase and lowercase. Strings are always defined inside double quotes ("Abc") and characters are always defined inside single quotes('A').

Functions

Name

String()

Example


String strOne = "Hello String"; // using a constant String
String strOne = String('a'); // converting a constant char into a String
String strTwo = String("This is a string"); // converting a constant string into a String object
String strOne = String(strTwo + " with more"); // concatenating two strings
String strOne = String(13); // using a constant integer
String strOne = String(analogRead(0), DEC); // using an int and a base
String strOne = String(45, HEX); // using an int and a base (hexadecimal)
String strOne = String(255, BIN); // using an int and a base (binary)
String strOne = String(millis(), DEC); // using a long and a base


Constructing a String from a number results in a string that contains the ASCII representation of that number. The default is base ten, so

String thisString = String(13,HEX);

gives you the String "13". You can use other bases, however

Description

Constructs an instance of the String class.

Syntax

String(val)String(val, base)

Parameters

  • val: a variable to format as a String - string, char, byte, int, long, unsigned int, unsigned long
  • base (optional): the base in which to format an integral value

Returns

an instance of the String class.

Usage

Application

Name

  • charAt()

Description

Access a particular character of the String.

Syntax

string.charAt(n)

Parameters

  • string: a variable of type String
  • n: the character to access

Returns

the n'th character of the String

Name

  • compareTo()

Description


Compares two Strings, testing whether one comes before or after the other, or whether they're equal. The strings are compared character by character, using the ASCII values of the characters. That means, for example, that 'a' comes before 'b' but after 'A'. Numbers come before letters.

Syntax

string.compareTo(string2);

Parameters

  • string: a variable of type String
  • string2: another variable of type String

Returns

  • a negative number: if string comes before string2
  • 0: if string equals string2
  • a positive number: if string comes after string2

Name

  • concat()

Description

Combines, or concatenates two strings into one new String. The second string is appended to the first, and the result is placed in a new String

Syntax

string.concat(string, string2)

Parameters

  • string, string2: variables of type String

Returns

new String that is the combination of the original two Strings

Name

  • c_str()

Description

Converts the contents of a string as a C-style, null-terminated string. Note that this gives direct access to the internal String buffer and should be used with care. In particular, you should never modify the string through the pointer returned. When you modify the String object, or when it is destroyed, any pointer previously returned by c_str() becomes invalid and should not be used any longer.

Syntax

string.c_str()

Parameters

none

Returns

A pointer to the C-style version of the invoking string.

Name

  • endsWith()

Description

Tests whether or not a String ends with the characters of another String.

Syntax

string.endsWith(string2)

Parameters

  • string: a variable of type String
  • string2: another variable of type String

Returns

  • true: if string ends with the characters of string2
  • false: otherwise

Name

  • equals()

Description

Compares two strings for equality. The comparison is case-sensitive, meaning the String "hello" is not equal to the String "HELLO".

Syntax

string.equals(string2)

Parameters

  • string, string2: variables of type String

Returns

  • true: if string equals string2
  • false: otherwise

Name

  • equalsIgnoreCase()

Description

Compares two strings for equality. The comparison is not case-sensitive, meaning the String("hello") is equal to the String("HELLO").

Syntax

string.equalsIgnoreCase(string2)

Parameters

  • string, string2: variables of type String

Returns

  • true: if string equals string2 (ignoring case)
  • false: otherwise

Name

  • getBytes()

Description

Copies the string's characters to the supplied buffer.

Syntax

string.getBytes(buf, len)

Parameters

  • string: a variable of type String
  • buf: the buffer to copy the characters into (byte [])
  • len: the size of the buffer (unsigned int)

Returns

None

Name

  • indexOf()

Description

Locates a character or String within another String. By default, searches from the beginning of the String, but can also start from a given index, allowing for the locating of all instances of the character or String.

Syntax

string.indexOf(val)string.indexOf(val, from)

Parameters

  • string: a variable of type String
  • val: the value to search for - char or String
  • from: the index to start the search from

Returns

The index of val within the String, or -1 if not found.

Name

  • lastIndexOf()

Description

Locates a character or String within another String. By default, searches from the end of the String, but can also work backwards from a given index, allowing for the locating of all instances of the character or String.

Syntax

string.lastIndexOf(val) 
string.lastIndexOf(val, from)

Parameters

  • string: a variable of type String
  • val: the value to search for - char or String
  • from: the index to work backwards from

Returns

The index of val within the String, or -1 if not found.

Name

  • lenght()

Description

Returns the length of the String, in characters. (Note that this doesn't include a trailing null character.)

Syntax

string.length()

Parameters

  • string: a variable of type String

Returns

The length of the String in characters.

Name

  • remove()

Description

Modify in place a string removing chars from the provided index to the end of the string or from the provided index to index plus count.

Syntax

string.remove(index) string.remove(index, count)

Parameters

  • index: a variable of type unsigned int
  • count: a variable of type unsigned int

Returns

none

Name

  • replace()

Description

The String replace() function allows you to replace all instances of a given character with another character. You can also use replace to replace substrings of a string with a different substring.

Syntax

string.replace(substring1, substring2)

Parameters

  • string: a variable of type String
  • substring1: another variable of type String
  • substring2: another variable of type String

Returns

another String containing the new string with replaced characters.

Name

  • reserve()

Description

The String reserve() function allows you to allocate a buffer in memory for manipulating strings.

Syntax

string.reserve(size)

Parameters

  • size: unsigned int declaring the number of bytes in memory to save for string manipulation

Returns

none

Name

  • setCharAt()

Description

Sets a character of the String. Has no effect on indices outside the existing length of the String.

Syntax

string.setCharAt(index, c)

Parameters

  • string: a variable of type String
  • index: the index to set the character at
  • c: the character to store to the given location

Returns

None

Name

  • startsWith()

Description

Tests whether or not a String starts with the characters of another String.

Syntax

string.startsWith(string2)

Parameters

  • string, string2: variable2 of type String

Returns

  • true: if string starts with the characters of string2
  • false: otherwise

Name

  • substring()

Description

Get a substring of a String. The starting index is inclusive (the corresponding character is included in the substring), but the optional ending index is exclusive (the corresponding character is not included in the substring). If the ending index is omitted, the substring continues to the end of the String.

Syntax

string.substring(from)string.substring(from, to)

Parameters

  • string: a variable of type String
  • from: the index to start the substring at
  • to (optional): the index to end the substring before

Returns

the substring

Name

  • toCharArray()

Description

Copies the string's characters to the supplied buffer.

Syntax

string.toCharArray(buf, len)

Parameters

  • string: a variable of type String
  • buf: the buffer to copy the characters into (char [])
  • len: the size of the buffer (unsigned int)

Returns

none

Name

  • toInt()

Description

Converts a valid String to an integer. The input string should start with an integer number. If the string contains non-integer numbers, the function will stop performing the conversion.

Syntax

string.toInt()

Parameters

  • string: a variable of type String

Returns

long. (If no valid conversion could be performed because the string doesn't start with a integer number, a zero is returned).

Name

  • toFloat()

Description

Converts a valid String to a float. The input string should start with a digit. If the string contains non-digit characters, the function will stop performing the conversion. For example, the strings "123.45", "123", and "123fish" are converted to 123.45, 123.00, and 123.00 respectively. Note that "123.456" is approximated with 123.46. Note too that floats have only 6-7 decimal digits of precision and that longer strings might be truncated.

Syntax

string.toFloat()

Parameters

  • string: a variable of type String

Returns

float. (If no valid conversion could be performed because the string doesn't start with a digit, a zero is returned).

Name

  • toLowerCase()

Description

Get a lower-case version of a String. As of 1.0, toLowerCase() modifies the string in place rather than returning a new one.

Syntax

string.toLowerCase()

Parameters

  • string: a variable of type String

Returns

none

Name

  • toUpperCase()

Description

Get an upper-case version of a String. As of 1.0, toUpperCase() modifies the string in place rather than returning a new one.

Syntax

string.toUpperCase()

Parameters

  • string: a variable of type String

Returns

none

Name

  • trim()

Description

Get a version of the String with any leading and trailing whitespace removed. As of 1.0, trim() modifies the string in place rather than returning a new one.

Syntax

string.trim()

Parameters

  • string: a variable of type String

Returns

none


Based on the reference originally written by Arduino Community,  wiring.org.co and  arduino.cc