Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

String.Intern Method

Retrieves the system's reference to the specified String.

[Visual Basic]
Public Shared Function Intern( _
   ByVal str As String _
) As String
[C#]
public static string Intern(
 string str
);
[C++]
public: static String* Intern(
 String* str
);
[JScript]
public static function Intern(
   str : String
) : String;

Parameters

str
A String.

Return Value

If the value of str is already interned, the system's reference is returned; otherwise, a new reference to a string with the value of str is returned.

Exceptions

Exception Type Condition
ArgumentNullException str is a 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 C# example that follows, 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. Since such a string exists, the method returns the same reference that is assigned to s1, then that reference is assigned to s3.

References s1 and s2 compare unequal because they refer to different objects, while references s1 and s3 compare equal because they refer to the same string.

String s1 = "MyTest"; 
String s2 = new StringBuilder().Append("My").Append("Test").ToString(); 
String s3 = String.Intern(s2); 
Console.WriteLine((Object)s2==(Object)s1); // Different references. 
Console.WriteLine((Object)s3==(Object)s1); // The same reference.

Compare this method to the IsInterned method.

Example

[Visual Basic] 
' Sample for String.Intern(String)
Imports System
Imports System.Text

Class Sample
   
   Public Shared Sub Main()
      Dim s1 As [String] = "MyTest"
      Dim s2 As [String] = New StringBuilder().Append("My").Append("Test").ToString()
      Dim s3 As [String] = [String].Intern(s2)
      Console.WriteLine("s1 = '{0}'", s1)
      Console.WriteLine("s2 = '{0}'", s2)
      Console.WriteLine("s3 = '{0}'", s3)
      Console.WriteLine("Is s2 the same reference as s1?: {0}", s2 Is s1)
      Console.WriteLine("Is s3 the same reference as s1?: {0}", s3 Is s1)
   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
'

[C#] 
// Sample for String.Intern(String)
using System;
using System.Text;

class Sample {
    public static void Main() {
    String s1 = "MyTest";
    String s2 = new StringBuilder().Append("My").Append("Test").ToString(); 
    String s3 = String.Intern(s2); 
    Console.WriteLine("s1 == '{0}'", s1);
    Console.WriteLine("s2 == '{0}'", s2);
    Console.WriteLine("s3 == '{0}'", s3);
    Console.WriteLine("Is s2 the same reference as s1?: {0}", (Object)s2==(Object)s1); 
    Console.WriteLine("Is s3 the same reference as s1?: {0}", (Object)s3==(Object)s1);
    }
}
/*
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
*/

[C++] 
// Sample for String::Intern(String)
#using <mscorlib.dll>

using namespace System;
using namespace System::Text;

int main() {
    String* s1 = S"MyTest";
    String* s2 = (new StringBuilder())->Append(S"My")->Append(S"Test")->ToString(); 
    String* s3 = String::Intern(s2); 
    Console::WriteLine(S"s1 == '{0}'", s1);
    Console::WriteLine(S"s2 == '{0}'", s2);
    Console::WriteLine(S"s3 == '{0}'", s3);
    Console::WriteLine(S"Is s2 the same reference as s1?: {0}", __box(s2==s1)); 
    Console::WriteLine(S"Is s3 the same reference as s1?: {0}", __box(s3==s1));
}
/*
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
*/

[JScript] No example is available for JScript. To view a Visual Basic, C#, or C++ example, click the Language Filter button Language Filter in the upper-left corner of the page.

Requirements

Platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family, .NET Compact Framework, Common Language Infrastructure (CLI) Standard

See Also

String Class | String Members | System Namespace | IsInterned

Show:
© 2014 Microsoft