String.Copy(String) Method

Reference

Definition

Namespace:: System

Assembly:: System.Runtime.dll

Assembly:: mscorlib.dll

Assembly:: netstandard.dll

Source:: String.cs

Source:: String.cs

Source:: String.cs

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Caution

This API should not be used to create mutable strings. See https://go.microsoft.com/fwlink/?linkid=2084035 for alternatives.

Creates a new instance of String with the same value as a specified String.

public:
 static System::String ^ Copy(System::String ^ str);

[System.Obsolete("This API should not be used to create mutable strings. See https://go.microsoft.com/fwlink/?linkid=2084035 for alternatives.")]
public static string Copy (string str);

public static string Copy (string str);

[<System.Obsolete("This API should not be used to create mutable strings. See https://go.microsoft.com/fwlink/?linkid=2084035 for alternatives.")>]
static member Copy : string -> string

static member Copy : string -> string

Public Shared Function Copy (str As String) As String

Parameters

str: String

The string to copy.

Returns

String

A new string with the same value as str.

Attributes: ObsoleteAttribute

Exceptions

ArgumentNullException

str is null.

Remarks

The Copy method returns a 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.

var original = "This is a sentence. This is a second sentence.";
var sentence1 = original.Substring(0, original.IndexOf(".") + 1);
Console.WriteLine(original);
Console.WriteLine(sentence1);
// The example displays the following output:
//    This is a sentence. This is a second sentence.
//    This is a sentence.

let original = "This is a sentence. This is a second sentence."
let sentence1 = original.Substring(0, original.IndexOf "." + 1)
printfn $"{original}"
printfn $"{sentence1}"
// The example displays the following output:
//    This is a sentence. This is a second sentence.
//    This is a sentence.

Dim original = "This is a sentence. This is a second sentence."
Dim sentence1 = original.Substring(0, original.IndexOf(".") + 1)
Console.WriteLine(original)
Console.WriteLine(sentence1)
' The example displays the following output:
'    This is a sentence. This is a second sentence.
'    This is a sentence.

In this case, calling the Copy method to create a new string before calling the Substring 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 String.ToCharArray or StringBuilder.StringBuilder(String) constructor. For example:

private static void UseMutableBuffer()
{
    var original = "This is a sentence. This is a second sentence.";
    var chars = original.ToCharArray();
    var span = new Span<char>(chars);
    var slice = span.Slice(span.IndexOf('.'), 3);
    slice = MergeSentence(slice);
    Console.WriteLine($"Original string: {original}");
    Console.WriteLine($"Modified string: {span.ToString()}");

    static Span<char> MergeSentence(Span<char> span)
    {
        if (span.Length == 0) return Span<char>.Empty;

        span[0] = ';';
        span[2] = Char.ToLower(span[2]);
        return span;
    }
}
// The example displays the following output:
//    Original string: This is a sentence. This is a second sentence.
//    Modified string: This is a sentence; this is a second sentence.

let mergeSentence (span: Span<char>) =
    if span.Length = 0 then
        Span<char>.Empty
    else
        span[0] <- '\000'
        span[2] <- Char.ToLower span[2]
        span

let useMutableBuffer () =
    let original = "This is a sentence. This is a second sentence."
    let chars = original.ToCharArray()
    let span = Span chars
    let slice = span.Slice(span.IndexOf '.', 3)
    let slice = mergeSentence slice
    let span = span.ToString()
    printfn $"Original string: {original}"
    printfn $"Modified string: {span}"
// The example displays the following output:
//    Original string: This is a sentence. This is a second sentence.
//    Modified string: This is a sentence this is a second sentence.

Private Sub UseMutableBuffer()
    Dim original = "This is a sentence. This is a second sentence."
    Dim sb = new StringBuilder(original)
    Dim index = original.IndexOf(".")
    sb(index) = ";"
    sb(index + 2) = Char.ToLower(sb(index + 2))
    Console.WriteLine($"Original string: {original}")
    Console.WriteLine($"Modified string: {sb.ToString()}")
End Sub
' The example displays the following output:
'    Original string: This is a sentence. This is a second sentence.
'    Modified string: This is a sentence; this is a second sentence.

If you want to create a mutable copy of the string so that you can use unsafe code to modify the string contents, use Marshal.StringToHGlobalUni method. The following example uses the Marshal.StringToHGlobalUni 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.

private static void UseUnmanaged()
{
    var original = "This is a single sentence.";
    var len = original.Length; 
    var ptr = Marshal.StringToHGlobalUni(original);
    string? result;
    unsafe 
    {
        char *ch = (char *) ptr.ToPointer();
        while (len-- > 0)
        {
            char c = Convert.ToChar(Convert.ToUInt16(*ch) + 1);
            *ch++ = c;
        } 
        result = Marshal.PtrToStringUni(ptr);
        Marshal.FreeHGlobal(ptr);
    }
    Console.WriteLine($"Original string: {original}");
    Console.WriteLine($"String from interop: '{result}'");
}
// The example displays the following output:
//    Original string: This is a single sentence.
//    String from interop: 'Uijt!jt!b!tjohmf!tfoufodf/'

#nowarn "9"
open FSharp.NativeInterop

let useUnmanaged () =
    let original = "This is a single sentence."
    let mutable len = original.Length 
    let ptr = Marshal.StringToHGlobalUni original
    let mutable ch = ptr.ToPointer() |> NativePtr.ofVoidPtr<char> 
    while len > 0 do
        len <- len - 1
        Convert.ToUInt16(NativePtr.read ch) + 1us
        |> Convert.ToChar
        |> NativePtr.write (NativePtr.add ch 1)
        ch <- NativePtr.add ch 1

    let result = Marshal.PtrToStringUni ptr
    Marshal.FreeHGlobal ptr
    printfn $"Original string: {original}"
    printfn $"String from interop: '{result}'"

// The example displays the following output:
//    Original string: This is a single sentence.
//    String from interop: 'Uijt!jt!b!tjohmf!tfoufodf/'

Applies to

Jaa