Home Library Learn Downloads Support Community
Sign in | United States - English | |
This topic has not yet been rated - Rate this topic

StringBuilder.Replace Method (String, String)

.NET Framework 4

Replaces all occurrences of a specified string in this instance with another specified string.

Namespace:  System.Text
Assembly:  mscorlib (in mscorlib.dll)
C#
C++
F#
VB
Copy 
public StringBuilder Replace(
	string oldValue,
	string newValue
)

Parameters

oldValue
Type: System.String
The string to replace.
newValue
Type: System.String
The string that replaces oldValue, or null.

Return Value

Type: System.Text.StringBuilder
A reference to this instance with all instances of oldValue replaced by newValue.
Exception Condition
ArgumentNullException

oldValue is null.

ArgumentException

The length of oldValue is zero.

ArgumentOutOfRangeException

Enlarging the value of this instance would exceed MaxCapacity.

The strings to replace are checked on an ordinal basis; that is, the replacement is not culture-aware. If newValue is null, all occurrences of oldValue are removed. This method is case-sensitive.

The following example demonstrates the Replace method.

C#
C++
VB
Copy 

using System;
using System.Text;

class Sample 
{
    public static void Main() 
    {
//                0----+----1----+----2----+----3----+----4---
//                01234567890123456789012345678901234567890123
    string str = "The quick br!wn d#g jumps #ver the lazy cat.";
    StringBuilder sb = new StringBuilder(str);

    Console.WriteLine();
    Console.WriteLine("StringBuilder.Replace method");
    Console.WriteLine();

    Console.WriteLine("Original value:");
    Show(sb);

    sb.Replace('#', '!', 15, 29);        // Some '#' -> '!'
    Show(sb);
    sb.Replace('!', 'o');                // All '!' -> 'o'
    Show(sb);
    sb.Replace("cat", "dog");            // All "cat" -> "dog"
    Show(sb);
    sb.Replace("dog", "fox", 15, 20);    // Some "dog" -> "fox"

    Console.WriteLine("Final value:");
    Show(sb);
    }

    public static void Show(StringBuilder sbs)
    {
    string rule1 = "0----+----1----+----2----+----3----+----4---";
    string rule2 = "01234567890123456789012345678901234567890123";

    Console.WriteLine(rule1);
    Console.WriteLine(rule2);
    Console.WriteLine("{0}", sbs.ToString());
    Console.WriteLine();
    }
}
/*
This example produces the following results:

StringBuilder.Replace method

Original value:
0----+----1----+----2----+----3----+----4---
01234567890123456789012345678901234567890123
The quick br!wn d#g jumps #ver the lazy cat.

0----+----1----+----2----+----3----+----4---
01234567890123456789012345678901234567890123
The quick br!wn d!g jumps !ver the lazy cat.

0----+----1----+----2----+----3----+----4---
01234567890123456789012345678901234567890123
The quick brown dog jumps over the lazy cat.

0----+----1----+----2----+----3----+----4---
01234567890123456789012345678901234567890123
The quick brown dog jumps over the lazy dog.

Final value:
0----+----1----+----2----+----3----+----4---
01234567890123456789012345678901234567890123
The quick brown fox jumps over the lazy dog.

*/

.NET Framework

Supported in: 4, 3.5, 3.0, 2.0, 1.1, 1.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Portable Class Library

Supported in: Portable Class Library

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.
Did you find this helpful?
(1500 characters remaining)
Community Content Add
Annotations FAQ
How know if replaced nothing?

It's too bad there isn't a way to know if the Replace call actually replaced something or found nothing to replace.

Has the StringBuilder Changed?

It is possible to determine whether the Replace method has modified the string by saving its string representation beforehand and then comparing that with its new string representation after the method call. For example:

using System;
using System.Text;

public class Example
{  
   public static void Main()
   {
      StringBuilder sb = new StringBuilder("A string.");
      string original = sb.ToString();
      sb.Replace("A", "One");
      if (!(sb.ToString() == original))
         Console.WriteLine("The replacement occurred.");
      else
         Console.WriteLine("There was no replacement.");
   }
}
--Ron Petrusha
Common Language Runtime User Education
Microsoft Corporation

History
Design decision around returning the current instance
What was the design decision around returning the current instance, instead of having a void return type? The examples of the StringBuilder.Replace on MSDN don't specify a return value (obviously in C# it is optional to use it). So if you modify the current instance, why return it?

E.g.

StringBuilder originalString = new StringBuilder("Foo");
originalString .Replace("Foo","Bar");

StringBuilder sameReference = originalString.Replace("Bar","Foo");
Console.WriteLine("Same objects?  {0}", originalString.Equals(sameReference));
// Output - "Same reference? true"

The Design Decision

The motivation for both modifying the current instance and returning the current instance is that it allows flexibility in method calls. For single-method operations, you can either call the method and ignore the return value, as reflected in the following two method calls:

originalString.Replace("o", "O")
originalString = originalString.Replace("o", "O)


But you can also "chain" successive method calls into a single statement, as in:

originalString.Replace("o", "O").Append("!").AppendFormat("{0:X}", 3840)


All StringBuilder methods that modify the value of the current instance can be called in either way.

I hope that this helps to answer your question.

--Ron Petrusha
Common Language Runtime User Education
Microsoft Corporation

History