Framework (A-Z)

Reference for Wiring version 1.0 Build 0100+ If you have a previous version, use the reference included with your software. If see any errors or have any comments, let us know.

Name

String

Examples
// declares s1 with an initial string
String s1 = String("string number one"); 
byte bytes[20];  // array of byte. 
char array[20];  // array of char.

void setup() {
  Serial.begin(9600); 
  // turn ON wiring hardware LED
  pinMode(WLED, OUTPUT);  
  digitalWrite(WLED, HIGH);

  // s2 holds "10000"
  String s2 = String(10000);  
  Serial.println("s2 holds: " + s2);

  // s3 holds "567000"
  String s3 = String(567000, DEC); 
  Serial.println("s3 holds: " + s3);

  // s4 holds "string number four"
  String s4 = "string number four";  
  Serial.println("s4 holds: " + s4);

  // use + operator to add a string
  s4 += " plus another part";  
  // user + operator when printing to serial
  Serial.println("now s4 holds: " + s4);  

  // get character at position 5
  char c = s4.charAt(5);  
  Serial.print ("c holds: ");
  Serial.println(c);  // prints 'g'

  // s5 holds "string number one"
  String s5 = String("string number one");  

  int cmp = s1.compareTo(s5);  // compare s1 to s5
  if (cmp == 0) {
    Serial.println("s1 and s5 are equal");  // prints equal
  } 
  else {
    Serial.println("s1 and s5 are different");
  }

  // check if s5 ends with "one"
  if (s5.endsWith("one"))  
    // prints "s5 ends with "one""
    Serial.println("s5 ends with one");  

  if (s1.equals(s5))  // check if s1 equal to s5
      Serial.println("s1 and s5 are equal");  // prints equal

  // s6 holds "string NUMBER one"
  String s6 = String("string NUMBER one");  
  // check if s5 and s6 are equal ignoring case differences
  if (s5.equalsIgnoreCase(s6))  
    // prints equal
    Serial.println("s6 and s5 are equal ignoring the case");  

  Serial.print ("index of char R pn s6 is: ");
  Serial.println(s6.indexOf('R'), DEC);  // prints 12

  Serial.print ("index of char R on s6 from index 13 is: ");
  // prints -1, not found
  Serial.println(s6.indexOf('R', 13), DEC);  

  String s7 = s6.substring(7, 13);
  Serial.println("s7 is: "+s7);  // prints "NUMBER"

  Serial.print ("index of string NUMBER on s6 is: ");  
  Serial.println(s6.indexOf(s7), DEC);  // prints 7

  Serial.print ("last index of char 'n' on s6 is: ");  
  Serial.println(s6.lastIndexOf('n'), DEC);  // prints 15

  Serial.print ("length of s6 is: ");  
  Serial.println(s6.length(), DEC);  // prints 17

  // set character at index 15 to 'N'
  s6.setCharAt(15, 'N');  
  // prints "string NUMBER oNe"
  Serial.println("s6 is: "+s6);  

  // check if s6 starts with "string"
  if (s6.startsWith("string"))  
    // s6 starts with "string" string
    Serial.println("s6 starts with string"); 

  // prints "string number one"
  s6.toLowerCase();
  Serial.println("s6 to lower case is: "+s6);  

  // prints "STRING NUMBER ONE"
  s6.toUpperCase();
  Serial.println("s6 to upper case is: "+s6);  

  s6.concat(" plus spaces at the end   ");  // concat a string
  // prints "STRING NUMBER ONE plus spaces at the end   "
  Serial.println("s6 is: "+s6);  

  // prints "STRING NUMBER ONE plus spaces at the end" 
  s6.trim();
  Serial.println("trim of s6 is: "+s6); 

  // prints "STRING NUMBER ONE plus spac5s at th5 5nd"
  s6.replace('e', '5');
  Serial.println("s6 is: "+s6);  

  // get the byte array in the array byte.
  s6.getBytes(bytes, 20);  
  Serial.print ("array byte. is: ");
  for (int i=0; i<20; i++) {
    // prints "S T R I N G   N U M B E R   O N E   p"
    Serial.write(bytes[i]);
    Serial.print(" ");
  }
  Serial.println();
  Serial.print ("array array is: ");
  s6.toCharArray(array, 20);
  Serial.println(array);  // Prints "STRING NUMBER ONE p"
}

void loop() {

}

Description A string is a sequence of characters. 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').

Note that the Wiring String class has differences with the processing or Java String class. The main difference is that some methods modify the actual string instead of returning a modified copy of it.
Methods
charAt() Returns the character at the specified index
compareTo() Compares two strings lexicographically
concat() Concatenates the String argument specified
endsWith() Returns true if the current string ends with the input string
equals() Compares a string to a specified string
equalsIgnoreCase() Compares a string to a specified string, ignoring case considerations
indexOf() Returns the index value of the first occurrence of a character or string within the input string
lastIndexOf() Returns the index value of the last occurrence of a character or string within the input string
length() Returns the number of characters in the string
setCharAt() Changes the character specified at the specified index
startsWith() Returns true if the current string starts with the input string
substring() Returns a new string that is part of the input string
toLowerCase() Converts all the characters to lower case
toUpperCase() Converts all the characters to upper case
toInt() Returns the numerical representation of a string
trim() Returns a copy of the string, with leading and trailing whitespace omitted
getBytes() Returns an array of bytes containing the characters of the String as bytes
toCharArray() Returns the content of the specified String as an array of chars
replace() Replaces all the occurrences of a character in a string with the specified character
Constructor
String(data)
String(data, base)
Parameters
data byte[], char[]: array of bytes to be decoded into characters or array of characters to be combined into a string, int, long: string conversion of the specified value, String: string to be copied into the created string
base DEC, HEX, OCT or BIN (exclusive for int or long data)
Usage Application
Updated on July 07, 2011 11:09:03pm PDT

Creative Commons License