Skip to content

Emphasized that String.Copy is obsolete #2546

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 6, 2019
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 24 additions & 10 deletions xml/System/String.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4275,17 +4275,31 @@ You can download the [Sorting Weight Tables](https://www.microsoft.com/download/
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
The <xref:System.String.Copy%2A> method returns a <xref:System.String> object that has the same value as the original string but represents a different object reference. It differs from an assignment operation, which assigns an existing string reference to an additional object variable. The example illustrates the difference.



## Examples
The following example creates two string objects with different values. When it calls the <xref:System.String.Copy%2A> method to assign the first value to the second string, the output indicates that the strings represent different object references although their values are now equal. On the other hand, when the first string is assigned to the second string, the two strings have identical values because they represent the same object reference.

[!code-csharp[System.String.Copy#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.copy/cs/copy1.cs#1)]
[!code-vb[System.String.Copy#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.string.copy/vb/copy1.vb#1)]
## Remarks

The `Copy` method returns a <xref:System.String> object that has the same value as the original string but represents a different object reference. It differs from an assignment operation, which assigns an existing string reference to an additional object variable.

> [!IMPORTANT]
> Starting with .NET Core 3.0, this method is obsolete. However, we do not recommend its use in any .NET implementation. In particular, because of changes in string interning in .NET Core 3.0, in some cases the `Copy` method will not create a new string but will simply return a reference to an existing interned string.

Depending on Why you want to call the `Copy` method, there are a number of alternatives:

- If you want a different string instance to use in an operation that modifies the string, use the original string instance. Because strings are immutable, the string operation creates a new string instance, and the original string remains unaffected. In this case, you should not assign the new string reference to the original string variable. The following example provides an illustration.

[!code-csharp[Performing a string operation](~/samples/snippets/csharp/api/system/string/copy/program.cs#1)]
[!code-vb[Performing a string operation](~/samples/snippets/visualbasic/api/system/string/copy/program.vb#1)]

In this case, calling the `Copy` method to create a new string before calling the <xref:System.String.Substring%2A> method unnecessarily creates a new string instance.

- If you want to create a mutable buffer with the same contents as the original string, call the <xref:System.String.ToCharArray%2A?displayProperty=nameWithType> or <xref:System.Text.StringBuilder.%23ctor(System.String)?displayProperty=nameWithType> constructor. For example:

[!code-csharp[Performing a string operation](~/samples/snippets/csharp/api/system/string/copy/program.cs#2)]
[!code-vb[Performing a string operation](~/samples/snippets/visualbasic/api/system/string/copy/program.vb#2)]

- If you want to create a mutable copy of the string so that you can use unsafe code to modify the string contents, use <xref:System.Runtime.InteropServices.Marshal.StringToHGlobalUni%2A?displayProperty=nameWithType> method. The following example uses the <xref:System.Runtime.InteropServices.Marshal.StringToHGlobalUni%2A?displayProperty=nameWithType> method to get a pointer to the location of an copied string in unmanaged memory, increments the Unicode code point of each character in the string by one, and copies the resulting string back to a managed string.

[!code-csharp[Performing a string operation](~/samples/snippets/csharp/api/system/string/copy/program.cs#3)]

]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">
Expand Down