String.Intern Method (System)

Intern Method

Collapse All

Language Filter

This page is specific to

Microsoft Visual Studio 2008/.NET Framework 3.5

Other versions are also available for the following:

.NET Framework Class Library

String..::.Intern Method

Updated: July 2008

Retrieves the system's reference to the specified String.

Namespace: System
Assembly: mscorlib (in mscorlib.dll)

Syntax

Visual Basic (Declaration)

Public Shared Function Intern ( _
    str As String _
) As String

Visual Basic (Usage)

Dim str As String
Dim returnValue As String

returnValue = String.Intern(str)

public static string Intern(
    string str
)

Visual C++

public:
static String^ Intern(
    String^ str
)

JScript

public static function Intern(
    str : String
) : String

Parameters

str: Type: System..::.String
A String.

Return Value

Type: System..::.String
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	Condition
ArgumentNullException	str is nullNothingnullptra 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.

Visual Basic

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(CObj(s2) Is CObj(s1))      ' Different references.
Console.WriteLine(CObj(s3) Is CObj(s1))      ' The same reference.

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.

Version Considerations

In the .NET Framework version 3.5 Service Pack 1, the Intern method reverts to its behavior in the .NET Framework version 1.0 and .NET Framework version 1.1 with regard to interning the empty string. In the following example, the variable str1 is assigned a reference to Empty, and the variable str2 is assigned the reference to Empty that is returned by calling the Intern method after converting a StringBuilder object whose value is Empty to a string. Then the references contained in str1 and str2 are compared for equality.

Visual Basic

        Dim str1 As String = String.Empty
        Dim str2 As String = String.Empty

        Dim sb As StringBuilder = New StringBuilder().Append(String.Empty)
        str2 = String.Intern(sb.ToString())    
        
        If CObj(str1) Is CObj(str2) Then
            Console.WriteLine("The strings are equal.")
        Else
            Console.WriteLine("The strings are not equal.")
        End If

        string str1 = String.Empty;
        string str2 = String.Empty;

        StringBuilder sb = new StringBuilder().Append(String.Empty);
        str2 = String.Intern(sb.ToString());    
        
        if((object)str1==(object)str2)
            Console.WriteLine("The strings are equal.");
        else
            Console.WriteLine("The strings are not equal.");

In the .NET Framework 1.0, .NET Framework 1.1, and .NET Framework 3.5 SP1, str1 and str2 are equal. In the .NET Framework version 2.0 Service Pack 1 and .NET Framework version 3.0, str1 and str2 are not equal.

Performance Considerations

If you are trying to reduce the total amount of memory your application allocates, keep in mind that interning a string has two unwanted side effects. First, the memory allocated for interned String objects is not likely be released until the common language runtime (CLR) terminates. The reason is that the CLR's reference to the interned String object can persist after your application, or even your application domain, terminates. Second, to intern a string, you must first create the string. The memory used by the String object must still be allocated, even though the memory will eventually be garbage collected.

The .NET Framework version 2.0 introduces the CompilationRelaxations..::.NoStringInterning enumeration member. The NoStringInterning member marks an assembly as not requiring string-literal interning. You can apply NoStringInterning to an assembly using the CompilationRelaxationsAttribute attribute. Also, when you use the Native Image Generator (Ngen.exe) to compile an assembly in advance of run time, strings are not interned across modules.

Examples

The following example uses three strings that are equal in value to determine whether a newly created string and an interned string are equal.

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
'

// 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
*/

Visual C++

// Sample for String::Intern(String)
using namespace System;
using namespace System::Text;
int main()
{
   String^ s1 = "MyTest";
   String^ s2 = (gcnew 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}", s2 == s1 );
   Console::WriteLine( "Is s3 the same reference as s1?: {0}", 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
*/

Platforms

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98, Windows CE, Windows Mobile for Smartphone, Windows Mobile for Pocket PC, Xbox 360, Zune

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Version Information