View source for Java Programming/API/java.lang.String

You do not have permission to edit this page, for the following reason:
Your IP address is in a range that has been blocked on all Wikimedia Foundation wikis.
The block was made by ‪Jon Kolbert‬. The reason given is Open proxy/Webhost: See the help page if you are affected .
Start of block: 01:29, 13 May 2024
Expiry of block: 01:29, 13 May 2029
Your current IP address is 3.138.108.211. The blocked range is 3.138.0.0/16.
Please include all above details in any queries you make.
If you believe you were blocked by mistake, you can find additional information and instructions in the Stewards Block Wizard.
You can view and copy the source of this page.
<noinclude>{{Displaytitle|title=String}}
{| width="100%" style="border:solid 1px #71c837; background:#c6e9af; color:#2d5016;" class="noprint"
| style="text-align:left; width:33%; font-size:90%;" | [[File:Navigation Left Arrow.svg|18px]] [[Java Programming/Methods|Methods]]
| style="text-align:center; width:34%;" | [[Java Programming]]<br />'''String'''
| style="text-align:right; width:33%; font-size:90%;" | [[Java Programming/Classes, Objects and Types|Classes, Objects and Types]] [[File:Navigation Right Arrow.svg|18px]]
|}
{{Java Programming/LanguageFundamentalsTopic/Nav}}
__NOTOC__</noinclude>

{{java:String}} is a class built into the Java language defined in the <code>java.lang</code> package. It represents character strings. Strings are ubiquitous in Java. Study the <code>String</code> class and its methods carefully. It will serve you well to know how to manipulate them skillfully. [[Java Programming/Literals#String Literals|String literals]] in Java programs, such as "abc", are implemented as instances of this class like this:

{{XExample|1='''Code section 3.81: String example.'''
<syntaxhighlight lang="Java5" line start="1">
String str = "This is string literal";
</syntaxhighlight>}}

On the right hand side a String object is created represented by the string literal. Its object reference is assigned to the <code>str</code> variable.

== Immutability ==
Strings are ''immutable''; that is, they cannot be modified once created. Whenever it looks as if a String object was modified actually a new String object was created. For instance, the <code>String.trim()</code> method returns the string with leading and trailing whitespace removed. Actually, it creates a new trimmed string and then returns it. Pay attention on what happens in [[#code-section-82|Code section 3.82]]:

{| style="width: 100%;"
|valign="top"|{{XExample|1=<span id="code-section-82">'''Code section 3.82: Immutability.'''</span>
<syntaxhighlight lang="Java5" line start="1" highlight="4">
String badlyCutText = "     Java is great.     ";
System.out.println(badlyCutText);

badlyCutText.trim();
System.out.println(badlyCutText);
</syntaxhighlight>}}
|valign="top"|{{XConsole|1='''Output for Code section 3.82'''
<pre style="background-color:#000; color:#fff;">
     Java is great.    
     Java is great.    
</pre>}}
|}

The <code>trim()</code> method call does not modify the object so nothing happens. It creates a new trimmed string and then throws it away.
{| style="width: 100%;"
|valign="top"|{{XExample|1=<span id="code-section-83">'''Code section 3.83: Assignment.'''</span>
<syntaxhighlight lang="Java5" line start="1" highlight="4">
String badlyCutText = "     Java is great.     ";
System.out.println(badlyCutText);

badlyCutText = badlyCutText.trim();
System.out.println(badlyCutText);
</syntaxhighlight>}}
|valign="top"|{{XConsole|1='''Output for Code section 3.83'''
<pre style="background-color:#000; color:#fff;">
     Java is great.    
Java is great.
</pre>}}
|}

The returned string is assigned to the variable. It does the job as the <code>trim()</code> method has created a new <code>String</code> instance.

== Concatenation ==
The Java language provides special support for the string concatenation with operator <code>+</code>:
{| style="width: 100%;"
|valign="top"|{{XExample|1='''Code section 3.84: Examples of concatenation.'''
<syntaxhighlight lang="Java5" line start="1">
System.out.println("First part");
System.out.println(" second part");
String str = "First part" + " second part";
System.out.println(str);
</syntaxhighlight>}}
|valign="top"|{{XConsole|1='''Output for Code section 3.84'''
<pre style="background-color:#000; color:#fff;">
First part
 second part
First part second part
</pre>}}
|}

The concatenation is not always processed at the same time. [[Java Programming/Literals#String Literals|Raw string literals]] concatenation is done at compile time, hence there is a single string literal in the byte code of the class. Concatenation with at least one object is done at runtime.

<code>+</code> operator can concatenate other objects with strings. For instance, integers will be converted to strings before the concatenation:
{| style="width: 100%;"
|valign="top"|{{XExample|1='''Code section 3.85: Concatenation of integers.'''
<syntaxhighlight lang="Java5" line start="1">
System.out.println("Age=" + 25);
</syntaxhighlight>}}
|valign="top"|{{XConsole|1='''Output for Code section 3.85'''
<pre style="background-color:#000; color:#fff;">
Age=25
</pre>}}
|}

Each Java object has the <code>String toString()</code> inherited from the {{java:Object}} class. This method provides a way to convert objects into <code>String</code>s. Most classes override the default behavior to provide more specific (and more useful) data in the returned <code>String</code>:
{| style="width: 100%;"
|valign="top"|{{XExample|1='''Code section 3.86: Concatenation of objects.'''
<syntaxhighlight lang="Java5" line start="1">
System.out.println("Age=" + new Integer(31));
</syntaxhighlight>}}
|valign="top"|{{XConsole|1='''Output for Code section 3.86'''
<pre style="background-color:#000; color:#fff;">
Age=31
</pre>}}
|}

== Using StringBuilder/StringBuffer to concatenate strings ==

Remember that <code>String</code> objects are immutable objects. Once a <code>String</code> is created, it can not be modified, takes up memory until garbage collected. Be careful of writing a method like this:
{{XExample|1='''Code section 3.87: Raw concatenation.'''
<syntaxhighlight lang="Java5" line start="1" highlight="5">
public String convertToString(Collection<String> words) {
  String str = "";
  // Loops through every element in words collection
  for (String word : words) {
    str = str + word + " ";
  }
  return str;
}
</syntaxhighlight>}}
On the <code>+</code> operation a new {{java:String}} object is created at each iteration. Suppose <code>words</code> contains the elements <code>["Foo", "Bar", "Bam", "Baz"]</code>. At runtime, the method creates thirteen <code>String</code>s:
# <code>""</code>
# <code>"Foo"</code>
# <code>" "</code>
# <code>"Foo "</code>
# <code>"Foo Bar"</code>
# <code>" "</code>
# <code>"Foo Bar "</code>
# <code>"Foo Bar Bam"</code>
# <code>" "</code>
# <code>"Foo Bar Bam "</code>
# <code>"Foo Bar Bam Baz"</code>
# <code>" "</code>
# <code>"Foo Bar Bam Baz "</code>
Even though only the last one is actually useful.

To avoid unnecessary memory use like this, use the <code>StringBuilder</code> class. It provides similar functionality to {{java:String}}s, but stores its data in a mutable way. Only one <code>StringBuilder</code> object is created. Also because object creation is time consuming, using <code>StringBuilder</code> produces much faster code.
{{XExample|1='''Code section 3.88: Concatenation with <code>StringBuilder</code>.'''
<syntaxhighlight lang="Java5" line start="1">
public String convertToString(Collection<String> words) {
  StringBuilder buf = new StringBuilder();
  // Loops through every element in words collection
  for (String word : words) {
    buf.append(word);
    buf.append(" ");
  }
  return buf.toString();
}
</syntaxhighlight>}}

As <code>StringBuilder</code> isn't thread safe (see the chapter on [[Java Programming/Concurrent Programming|Concurrency]]) you can't use it in more than one thread. For a multi-thread environment, use <code>StringBuffer</code> instead which does the same and is thread safe. However, <code>StringBuffer</code> is slower so only use it when it is required. Moreover, before Java 5 only <code>StringBuffer</code> existed.

== Comparing Strings ==

Comparing strings is not as easy as it may first seem. Be aware of what you are doing when comparing <code>String</code>'s using <code>==</code>:

{| style="width: 100%;"
|valign="top"|{{XExample|1=<span id="code-section-89">'''Code section 3.89: Dangerous comparison.'''</span>
<syntaxhighlight lang="Java5" line start="1" highlight="3">
String greeting = "Hello World!";
if (greeting == "Hello World!") {
    System.out.println("Match found.");
}
</syntaxhighlight>}}
|valign="top"|{{XConsole|1='''Output for Code section 3.89'''
<pre style="background-color:#000; color:#fff;">
Match found.
</pre>}}
|}
The difference between the above and below code is that the above code checks
to see if the <code>String</code>'s are the same objects in memory which they are. This is as a result of the fact that
<code>String</code>'s are stored in a place in memory called the String Constant Pool. If the <code>new</code> keyword is not explicitly used when 
creating the <code>String</code> it checks to see if it already exists in the Pool and uses the existing one. If it does not exist, a new Object is created. This is what allows Strings to be immutable in Java.
To test for equality, use the <code>equals(Object)</code> method inherited by every class and defined by <code>String</code> to return {{java:true}} if and only if the object passed in is a <code>String</code> contains the exact same data:
{| style="width: 100%;"
|valign="top"|{{XExample|1=<span id="code-section-90">'''Code section 3.90: Right comparison.'''</span>
<syntaxhighlight lang="Java5" line start="1" highlight="3">
String greeting = "Hello World!";
if (greeting.equals("Hello World!")) {
    System.out.println("Match found.");
}
</syntaxhighlight>}}
|valign="top"|{{XConsole|1='''Output for Code section 3.90'''
<pre style="background-color:#000; color:#fff;">
Match found.
</pre>}}
|}

Remember that the comparison is case sensitive.
{| style="width: 100%;"
|valign="top"|{{XExample|1=<span id="code-section-91">'''Code section 3.91: Comparison with lowercase.'''</span>
<syntaxhighlight lang="Java5" line start="1" highlight="3">
String greeting = "Hello World!";
if (greeting.equals("hello world!")) {
    System.out.println("Match found.");
}
</syntaxhighlight>}}
|valign="top"|{{XConsole|1='''Output for Code section 3.91'''
<pre style="background-color:#000; color:#fff;">
</pre>}}
|}

To order <code>String</code> objects, use the '''<code>compareTo()</code>''' method, which can be accessed wherever we use a String datatype. The <code>compareTo()</code> method returns a negative, zero, or positive number if the parameter is less than, equal to, or greater than the object on which it is called. Let's take a look at an example:
{{XExample|1=<span id="code-section-92">'''Code section 3.92: Order.'''</span>
<syntaxhighlight lang="Java5" line start="1" highlight="3">
String person1 = "Peter";
String person2 = "John";
if (person1.compareTo(person2) > 0) {
    // Badly ordered
    String temp = person1;
    person1 = person2;
    person2 = temp;
}
</syntaxhighlight>}}

The [[#code-section-92|code section 3.92]] is comparing the String variable <code>person1</code> to <code>person2</code>. If <code>person1</code> is different even in the slightest manner, we will get a value above or below 0 depending on the exact difference. The result is negative if this String object lexicographically precedes the argument string. The result is positive if this String object lexicographically follows the argument string. Take a look at the [http://docs.oracle.com/javase/7/docs/api/java/lang/String.html#compareTo%28java.lang.String%29 Java API] for more details.

== Splitting a String ==
Sometimes it is useful to split a string into separate strings, based on a ''[[Regular Expressions|regular expressions]]''. The {{java:String}} class has a '''<code>split()</code>''' method, since Java 1.4, that will return a String array:

{{XExample|1=<span id="code-section-93">'''Code section 3.93: Order.'''</span>
<syntaxhighlight lang="Java5" line start="1" highlight="3">
String person = "Brown, John:100 Yonge Street, Toronto:(416)777-9999";
...
String[] personData = person.split(":");
...
String name    = personData[0];
String address = personData[1];
String phone   = personData[2];
</syntaxhighlight>}}

Another useful application could be to ''split'' the String text based on the new line character, so you could process the text line by line.

== Substrings ==
It may also be sometimes useful to create '''substrings''', or strings using the order of letters from an existing string.  This can be done in two methods.

The first method involves creating a substring out of the characters of a string from a given index to the end:
{| style="width: 100%;"
|valign="top"|{{XExample|1=<span id="code-section-94">'''Code section 3.94: Truncating string.'''</span>
<syntaxhighlight lang="Java5" line start="1" highlight="2">
String str = "coffee";
System.out.println(str.substring(3));
</syntaxhighlight>}}
|valign="top"|{{XConsole|1='''Output for Code section 3.94'''
<pre style="background-color:#000; color:#fff;">
fee
</pre>}}
|}

The index of the first character in a string is 0.
{| style="margin: auto;" cellspacing="0" cellpadding="2"
|style="color: blue;"|<code>c</code>
|style="color: blue;"|<code>o</code>
|style="color: blue;"|<code>f</code>
|style="color: blue; background: grey;"|<code>f</code>
|style="color: blue; background: grey;"|<code>e</code>
|style="color: blue; background: grey;"|<code>e</code>
|-
|''0''
|''1''
|''2''
|'''''3'''''
|''4''
|''5''
|}

By counting from there, it is apparent that the character in index 3 is the second "f" in "coffee". This is known as the <code>beginIndex</code>. All characters from the <code>beginIndex</code> until the end of the string will be copied into the new substring.

The second method involves a user-defined <code>beginIndex</code> and <code>endIndex</code>:
{| style="width: 100%;"
|valign="top"|{{XExample|1=<span id="code-section-95">'''Code section 3.95: Extraction of string.'''</span>
<syntaxhighlight lang="Java5" line start="1" highlight="2">
String str = "supporting";
System.out.println(str.substring(3, 7));
</syntaxhighlight>}}
|valign="top"|{{XConsole|1='''Output for Code section 3.95'''
<pre style="background-color:#000; color:#fff;">
port
</pre>}}
|}
The string returned by <code>substring()</code> would be "port".
{| style="margin: auto;" cellspacing="0" cellpadding="2"
|style="color: blue;"|<code>s</code>
|style="color: blue;"|<code>u</code>
|style="color: blue;"|<code>p</code>
|style="color: blue; background: grey;"|<code>p</code>
|style="color: blue; background: grey;"|<code>o</code>
|style="color: blue; background: grey;"|<code>r</code>
|style="color: blue; background: grey;"|<code>t</code>
|style="color: blue;"|<code>i</code>
|style="color: blue;"|<code>n</code>
|style="color: blue;"|<code>g</code>
|-
|''0''
|''1''
|''2''
|'''''3'''''
|''4''
|''5''
|''6''
|'''''7'''''
|''8''
|''9''
|}

Please note that the endIndex is '''not''' inclusive. This means that the last character will be of the index <code>endIndex-1</code>. Therefore, in this example, every character from index 3 to index 6, inclusive, was copied into the substring.

{{XNote|1=It is easy to mistake the method <code>substring()</code> for <code><span style="border-bottom: red 1px dashed">subString</span>()</code> (which does not exist and would return with a syntax error on compilation). ''Substring'' is considered to be one word. This is why the method name does not seem to follow the common syntax of Java. Just remember that this style only applies to methods or other elements that are made up of more than one word.}}

== String cases ==
The <code>String</code> class also allows for the modification of cases. The two methods that make this possible are <code>toLowerCase()</code> and <code>toUpperCase()</code>.
{| style="width: 100%;"
|valign="top"|{{XExample|1=<span id="code-section-96">'''Code section 3.96: Case modification.'''</span>
<syntaxhighlight lang="Java5" line start="1" highlight="2-3">
String str = "wIkIbOoKs";
System.out.println(str.toLowerCase());
System.out.println(str.toUpperCase());
</syntaxhighlight>}}
|valign="top"|{{XConsole|1='''Output for Code section 3.96'''
<pre style="background-color:#000; color:#fff;">
wikibooks
WIKIBOOKS
</pre>}}
|}

These methods are useful to do a search which is not case sensitive:
{{XExample|1='''Code section 3.97: Text search.'''
<syntaxhighlight lang="Java5" line start="1" highlight="8-9, 12, 18">
String word = "Integer";
String text = "A number without a decimal part is an integer."
  + " Integers are a list of digits.";

...

// Remove the case
String lowerCaseWord = word.toLowerCase();
String lowerCaseText = text.toLowerCase();

// Search
int index = lowerCaseText.indexOf(lowerCaseWord);
while (index != -1) {
  System.out.println(word
    + " appears at column "
    + (index + 1)
    + ".");
  index = lowerCaseText.indexOf(lowerCaseWord, index + 1);
}

</syntaxhighlight>}}

{{XConsole|1='''Output for Code section 3.97'''
<pre style="background-color:#000; color:#fff;">
Integer appears at column 38.
Integer appears at column 47.
</pre>}}

{{Java/Hidden begin|title=Test your knowledge}}
'''Question 3.12''': You have mail addresses in the following form: <code>''<firstName>''.''<lastName>''@''<companyName>''.org</code>

Write the <code>String getDisplayName(String)</code> method that receives the mail string as parameter and returns the readable person name like this: <code>LASTNAME Firstname</code>
{{Java/Hidden begin|title=Answer}}
{{XExample|1='''Answer 3.12: <code>getDisplayName()</code>'''
<syntaxhighlight lang="Java5" line start="1">
public static String getDisplayName(String mail) {
  String displayName = null;
 
  if (mail != null) {
    String[] mailParts = mail.split("@");
    String namePart = mailParts[0];
    String[] namesParts = namePart.split("\\.");
   
    // The last name
    String lastName = namesParts[1];
    lastName = lastName.toUpperCase();
   
    // The first name
    String firstName = namesParts[0];
   
    String firstNameInitial = firstName.substring(0, 1);
    firstNameInitial = firstNameInitial.toUpperCase();
   
    String firstNameEnd = firstName.substring(1);
    firstNameEnd = firstNameEnd.toLowerCase();
   
    // Concatenation
    StringBuilder displayNameBuilder = new StringBuilder(lastName).append(" ").append(firstNameInitial).append(firstNameEnd);
    displayName = displayNameBuilder.toString();
  }
 
  return displayName;
}
</syntaxhighlight>}}

# We only process non null strings,
# We first split the mail into two parts to separate the personal information from the company information and we keep the name data,
# Then we split the name information to separate the first name from the last name. As the <code>split()</code> method use regular expression and <code>.</code> is a wildcard character, we have to escape it (<code>\.</code>). However, in a string, the <code>\</code> is also a special character, so we need to escape it too (<code>\\.</code>),
# The last name is just capitalized,
# As the case of all the first name characters will not be the same, we have to cut the first name. Only the first name initial will be capitalized,
# Now we can concatenate all the fragments. We prefer to use a <code>StringBuilder</code> to do that.

{{Hidden end}}
{{Hidden end}}

== See also ==
* {{java web api|java/lang/String.html|java.lang.String}}
* {{java web api|java/lang/StringBuffer.html|java.lang.StringBuffer}}
* {{java web api|java/lang/StringBuilder.html|java.lang.StringBuilder}}

<noinclude>{| width="100%" style="border:solid 1px #71c837; background:#c6e9af; color:#2d5016;" class="noprint"
| style="text-align:left; width:33%; font-size:90%;" | [[File:Navigation Left Arrow.svg|18px]] [[Java Programming/Methods|Methods]]
| style="text-align:center; width:34%;" | [[Java Programming]]<br />'''String'''
| style="text-align:right; width:33%; font-size:90%;" | [[Java Programming/Classes, Objects and Types|Classes, Objects and Types]] [[File:Navigation Right Arrow.svg|18px]]
|}
{{Status|100%}}
{{BookCat|filing=deep}}</noinclude>
Templates used on this page:
Template:BOOKCATEGORY (view source) (protected)
Template:BookCat (view source) (protected)
Template:BookCat/core (view source) (protected)
Template:BookCat/default (view source) (protected)
Template:Displaytitle (view source) (protected)
Template:Evalx (view source) (protected)
Template:Hidden begin (view source) (protected)
Template:Hidden end (view source) (protected)
Template:Java/Hidden begin (edit)
Template:Java:Object (edit)
Template:Java:String (edit)
Template:Java:api (edit)
Template:Java:true (edit)
Template:Java Programming/LanguageFundamentals/Topic (edit)
Template:Java Programming/LanguageFundamentalsTopic/Nav (edit)
Template:Java web api (edit)
Template:NAIVEBOOKNAME (view source) (protected)
Template:Navbar (view source) (protected)
Template:Stage short (view source) (protected)
Template:Status (view source) (protected)
Template:Transclude (view source) (protected)
Template:XConsole (edit)
Template:XExample (edit)
Template:XNote (edit)
Module:TScope (view source) (protected)
Module:Wikilisp (view source) (protected)
Return to Java Programming/API/java.lang.String.
Retrieved from "https://en.wikibooks.org/wiki/Java_Programming/API/java.lang.String"