Export (0) Print
Expand All
2 out of 4 rated this helpful - Rate this topic

String.Intern Method

Retrieves the system's reference to the specified String.

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

public static string Intern (
	string str
)
public static String Intern (
	String str
)
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.
Exception typeCondition

ArgumentNullException

str is a null reference (Nothing in Visual Basic).

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.

Version Considerations

Starting with the .NET Framework version 2.0, there is a behavioral change in the Intern method. In the following C# code sequence, the variable str1 is assigned a reference to Empty, the variable str2 is assigned the reference to Empty that is returned by the Intern method, then the references contained in str1 and str2 are compared for equality.

string str1 = String.Empty;
string str2 = String.Intern(String.Empty);
if ((object) str1) == ((object) str2) …

In the .NET Framework version 1.1, str1 and str2 are not equal, but starting in the .NET Framework version 2.0, str1 and str2 are 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 languange 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 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)
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
*/

// Sample for String.Intern(String)
import System.*;
import System.Text.*;

class Sample
{
    public static void main(String[] args)
    {
        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}", 
            System.Convert.ToString((Object)s2 == (Object)s1));
        Console.WriteLine("Is s3 the same reference as s1?: {0}", 
            System.Convert.ToString((Object)s3 == (Object)s1));
    } //main
} //Sample
/*
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
*/

Windows 98, Windows 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile for Pocket PC, Windows Mobile for Smartphone, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

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

.NET Framework

Supported in: 2.0, 1.1, 1.0

.NET Compact Framework

Supported in: 2.0, 1.0
Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.