String.Intern Method
Microsoft Silverlight will reach end of support after October 2021. Learn more.
Retrieves the system's reference to the specified String.
Namespace: System
Assembly: mscorlib (in mscorlib.dll)
Syntax
'Declaration
<SecuritySafeCriticalAttribute> _
Public Shared Function Intern ( _
str As String _
) As String
[SecuritySafeCriticalAttribute]
public static string Intern(
string str
)
Parameters
- str
Type: System.String
The string to search for in the intern pool.
Return Value
Type: System.String
The system's reference to str, if it is interned; otherwise, a new reference to a string with the value of str.
Exceptions
| Exception | Condition |
|---|---|
| ArgumentNullException | str is nulla null reference (Nothing in Visual Basic). |
Remarks
The common language runtime conserves string storage by maintaining a table, called the intern pool, that contains a single reference to each unique literal string declared or created programmatically in your program. Consequently, an instance of a literal string with a particular value only exists once in the system.
For example, if you assign the same literal string to several variables, the runtime retrieves the same reference to the literal string from the intern pool and assigns it to each variable.
The Intern method uses the intern pool to search for a string equal to the value of str. If such a string exists, its reference in the intern pool is returned. If the string does not exist, a reference to str is added to the intern pool, then that reference is returned.
In the following example, the string s1, which has a value of "MyTest", is already interned because it is a literal in the program. The System.Text.StringBuilder class generates a new string object that has the same value as s1. A reference to that string is assigned to s2. The Intern method searches for a string that has the same value as s2. Because such a string exists, the method returns the same reference that is assigned to s1. That reference is then assigned to s3. References s1 and s2 compare unequal because they refer to different objects; references s1 and s3 compare equal because they refer to the same string.
Dim s1 As String = "MyTest"
Dim s2 As String = New StringBuilder().Append("My").Append("Test").ToString()
Dim s3 As String = String.Intern(s2)
outputBlock.Text += CStr(CObj(s2) Is CObj(s1)) + vbCrLf ' Different references.
outputBlock.Text += CStr(CObj(s3) Is CObj(s1)) + vbCrLf ' The same reference.
string s1 = "MyTest";
string s2 = new StringBuilder().Append("My").Append("Test").ToString();
string s3 = String.Intern(s2);
outputBlock.Text += ((Object)s2 == (Object)s1) + "\n"; // Different references.
outputBlock.Text += ((Object)s3 == (Object)s1) + "\n"; // The same reference.
Compare this method to the IsInterned method.
Examples
The following code example uses three strings that are equal in value to determine whether a newly created string and an interned string are equal.
' Sample for String.Intern(String)
Imports System.Text
Class Example
Public Shared Sub Demo(ByVal outputBlock As System.Windows.Controls.TextBlock)
Dim s1 As [String] = "MyTest"
Dim s2 As [String] = New StringBuilder().Append("My").Append("Test").ToString()
Dim s3 As [String] = [String].Intern(s2)
outputBlock.Text += String.Format("s1 = '{0}'", s1) & vbCrLf
outputBlock.Text += String.Format("s2 = '{0}'", s2) & vbCrLf
outputBlock.Text += String.Format("s3 = '{0}'", s3) & vbCrLf
outputBlock.Text += String.Format("Is s2 the same reference as s1?: {0}", s2 Is s1) & vbCrLf
outputBlock.Text += String.Format("Is s3 the same reference as s1?: {0}", s3 Is s1) & vbCrLf
End Sub 'Main
End Class 'Sample
'
's1 = 'MyTest'
's2 = 'MyTest'
's3 = 'MyTest'
'Is s2 the same reference as s1?: False
'Is s3 the same reference as s1?: True
'
// Sample for String.Intern(String)
using System;
using System.Text;
class Example
{
public static void Demo(System.Windows.Controls.TextBlock outputBlock)
{
String s1 = "MyTest";
String s2 = new StringBuilder().Append("My").Append("Test").ToString();
String s3 = String.Intern(s2);
outputBlock.Text += String.Format("s1 == '{0}'", s1) + "\n";
outputBlock.Text += String.Format("s2 == '{0}'", s2) + "\n";
outputBlock.Text += String.Format("s3 == '{0}'", s3) + "\n";
outputBlock.Text += String.Format("Is s2 the same reference as s1?: {0}", (Object)s2 == (Object)s1) + "\n";
outputBlock.Text += String.Format("Is s3 the same reference as s1?: {0}", (Object)s3 == (Object)s1) + "\n";
}
}
/*
This example produces the following results:
s1 == 'MyTest'
s2 == 'MyTest'
s3 == 'MyTest'
Is s2 the same reference as s1?: False
Is s3 the same reference as s1?: True
*/
Version Information
Silverlight
Supported in: 5, 4, 3
Silverlight for Windows Phone
Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0
XNA Framework
Supported in: Xbox 360, Windows Phone OS 7.0
Platforms
For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.