Uso da classe StringBuilder no .NETUsing the StringBuilder Class in .NET

O objeto String é imutável.The String object is immutable. Sempre que usa um dos métodos na classe System.String, você cria um novo objeto de cadeia de caracteres na memória, o que requer uma nova alocação de espaço para esse novo objeto.Every time you use one of the methods in the System.String class, you create a new string object in memory, which requires a new allocation of space for that new object. Em situações em que você precisa realizar repetidas modificações em uma cadeia de caracteres, a sobrecarga associada à criação de um novo objeto String pode ser dispendiosa.In situations where you need to perform repeated modifications to a string, the overhead associated with creating a new String object can be costly. A classe System.Text.StringBuilder pode ser usada quando você deseja modificar uma cadeia de caracteres sem criar um novo objeto.The System.Text.StringBuilder class can be used when you want to modify a string without creating a new object. Por exemplo, o uso da classe StringBuilder pode melhorar o desempenho ao concatenar várias cadeias de caracteres em um loop.For example, using the StringBuilder class can boost performance when concatenating many strings together in a loop.

Importando o namespace System.TextImporting the System.Text Namespace

A classe StringBuilder é encontrada no namespace System.Text.The StringBuilder class is found in the System.Text namespace. Para evitar ter que fornecer um nome de tipo totalmente qualificado no código, você pode importar o namespace System.Text:To avoid having to provide a fully qualified type name in your code, you can import the System.Text namespace:

using namespace System;
using namespace System::Text;
using System;
using System.Text;
Imports System.Text

Criando uma instância de um objeto StringBuilderInstantiating a StringBuilder Object

Você pode criar uma nova instância da classe StringBuilder inicializando sua variável com um dos métodos do construtor sobrecarregados, conforme ilustrado no exemplo a seguir.You can create a new instance of the StringBuilder class by initializing your variable with one of the overloaded constructor methods, as illustrated in the following example.

StringBuilder^ myStringBuilder = gcnew StringBuilder("Hello World!");
StringBuilder myStringBuilder = new StringBuilder("Hello World!");
Dim myStringBuilder As New StringBuilder("Hello World!")

Definindo a capacidade e o comprimentoSetting the Capacity and Length

Embora o StringBuilder seja um objeto dinâmico que permite que você expanda o número de caracteres na cadeia de caracteres que ele encapsula, você pode especificar um valor para o número máximo de caracteres que ele pode conter.Although the StringBuilder is a dynamic object that allows you to expand the number of characters in the string that it encapsulates, you can specify a value for the maximum number of characters that it can hold. Esse valor é chamado de capacidade do objeto e não deve ser confundido com o comprimento da cadeia de caracteres que o StringBuilder atual contém.This value is called the capacity of the object and should not be confused with the length of the string that the current StringBuilder holds. Por exemplo, você pode criar uma nova instância da classe StringBuilder com a cadeia de caracteres "Hello", que tem um comprimento de 5 caracteres e você pode especificar que o objeto tenha uma capacidade máxima de 25.For example, you might create a new instance of the StringBuilder class with the string "Hello", which has a length of 5, and you might specify that the object has a maximum capacity of 25. Quando você modifica o StringBuilder, ele não realoca tamanho para si mesmo até que a capacidade seja atingida.When you modify the StringBuilder, it does not reallocate size for itself until the capacity is reached. Quando isso ocorre, o novo espaço é alocado automaticamente e a capacidade é dobrada.When this occurs, the new space is allocated automatically and the capacity is doubled. Você pode especificar a capacidade da classe StringBuilder usando um dos construtores sobrecarregados.You can specify the capacity of the StringBuilder class using one of the overloaded constructors. O exemplo a seguir especifica que o objeto myStringBuilder pode ser expandido para um máximo de 25 espaços.The following example specifies that the myStringBuilder object can be expanded to a maximum of 25 spaces.

StringBuilder^ myStringBuilder = gcnew StringBuilder("Hello World!", 25);
StringBuilder myStringBuilder = new StringBuilder("Hello World!", 25);  
Dim myStringBuilder As New StringBuilder("Hello World!", 25) 

Além disso, você pode usar a propriedade Capacity de leitura/gravação para definir o comprimento máximo do objeto.Additionally, you can use the read/write Capacity property to set the maximum length of your object. O exemplo a seguir usa a propriedade Capacidade para definir o comprimento máximo de objeto.The following example uses the Capacity property to define the maximum object length.

myStringBuilder->Capacity = 25;
myStringBuilder.Capacity = 25;
myStringBuilder.Capacity = 25

O método EnsureCapacity pode ser usado para verificar a capacidade do StringBuilder atual.The EnsureCapacity method can be used to check the capacity of the current StringBuilder. Se a capacidade for maior que o valor transmitido, nenhuma alteração é feita; no entanto, se a capacidade for menor do que o valor transmitido, a capacidade atual é alterada para corresponder ao valor transmitido.If the capacity is greater than the passed value, no change is made; however, if the capacity is smaller than the passed value, the current capacity is changed to match the passed value.

A propriedade Length também pode ser exibida ou definida.The Length property can also be viewed or set. Se você definir a propriedade Comprimento para um valor maior que a propriedade Capacidade, a propriedade Capacidade será alterada automaticamente para o mesmo valor que a propriedade Comprimento.If you set the Length property to a value that is greater than the Capacity property, the Capacity property is automatically changed to the same value as the Length property. Definir a propriedade Comprimento para um valor menor que o comprimento da cadeia de caracteres no StringBuilder atual, diminui a cadeia de caracteres.Setting the Length property to a value that is less than the length of the string within the current StringBuilder shortens the string.

Modificando a cadeia de caracteres do StringBuilderModifying the StringBuilder String

A tabela a seguir lista os métodos que você pode usar para modificar o conteúdo de um StringBuilder.The following table lists the methods you can use to modify the contents of a StringBuilder.

Nome do métodoMethod name UseUse
StringBuilder.Append Acrescenta informações ao final do StringBuilder atual.Appends information to the end of the current StringBuilder.
StringBuilder.AppendFormat Substitui um especificador de formato transmitido em uma cadeia de caracteres com texto formatado.Replaces a format specifier passed in a string with formatted text.
StringBuilder.Insert Insere uma cadeia de caracteres ou um objeto no índice especificado do StringBuilder atual.Inserts a string or object into the specified index of the current StringBuilder.
StringBuilder.Remove Remove um número especificado de caracteres do StringBuilder atual.Removes a specified number of characters from the current StringBuilder.
StringBuilder.Replace Substitui um caractere especificado em um índice especificado.Replaces a specified character at a specified index.

AcrescentarAppend

O método Append pode ser usado para adicionar texto ou uma representação de cadeia de caracteres de um objeto ao final de uma cadeia de caracteres representada pelo StringBuilder atual.The Append method can be used to add text or a string representation of an object to the end of a string represented by the current StringBuilder. O exemplo a seguir inicializa um StringBuilder para "Hello World" e, em seguida, acrescenta algum texto ao final do objeto.The following example initializes a StringBuilder to "Hello World" and then appends some text to the end of the object. Espaço é alocado automaticamente conforme necessário.Space is allocated automatically as needed.

StringBuilder^ myStringBuilder = gcnew StringBuilder("Hello World!");
myStringBuilder->Append(" What a beautiful day.");
Console::WriteLine(myStringBuilder);
// The example displays the following output:
//       Hello World! What a beautiful day.
StringBuilder myStringBuilder = new StringBuilder("Hello World!");
myStringBuilder.Append(" What a beautiful day.");
Console.WriteLine(myStringBuilder);
// The example displays the following output:
//       Hello World! What a beautiful day.
Dim myStringBuilder As New StringBuilder("Hello World!")
myStringBuilder.Append(" What a beautiful day.")
Console.WriteLine(myStringBuilder)
' The example displays the following output:
'       Hello World! What a beautiful day.

AppendFormatAppendFormat

O método StringBuilder.AppendFormat adiciona texto ao final do objeto StringBuilder.The StringBuilder.AppendFormat method adds text to the end of the StringBuilder object. Ele dá suporte ao recurso de formatação de composição (para obter mais informações, confira Formatação de composição) chamando a implementação IFormattable do objeto ou objetos a serem formatados.It supports the composite formatting feature (for more information, see Composite Formatting) by calling the IFormattable implementation of the object or objects to be formatted. Portanto, aceita as cadeias de caracteres de formato padrão para valores numéricos, data e hora e enumeração, cadeias de caracteres de formato personalizado para valores numéricos e de data e hora e cadeias de caracteres de formato definidas para tipos personalizados.Therefore, it accepts the standard format strings for numeric, date and time, and enumeration values, the custom format strings for numeric and date and time values, and the format strings defined for custom types. (Para obter informações sobre a formatação, consulte Formatando tipos.) Você pode usar esse método para personalizar o formato de variáveis e acrescentar esses valores a um StringBuilder.(For information about formatting, see Formatting Types.) You can use this method to customize the format of variables and append those values to a StringBuilder. O exemplo a seguir usa o método AppendFormat para colocar um valor inteiro, formatado como um valor de moeda, no final de um objeto StringBuilder.The following example uses the AppendFormat method to place an integer value formatted as a currency value at the end of a StringBuilder object.

int MyInt = 25;
StringBuilder^ myStringBuilder = gcnew StringBuilder("Your total is ");
myStringBuilder->AppendFormat("{0:C} ", MyInt);
Console::WriteLine(myStringBuilder);
// The example displays the following output:
//       Your total is $25.00
int MyInt = 25; 
StringBuilder myStringBuilder = new StringBuilder("Your total is ");
myStringBuilder.AppendFormat("{0:C} ", MyInt);
Console.WriteLine(myStringBuilder);
// The example displays the following output:
//       Your total is $25.00      
Dim MyInt As Integer = 25
Dim myStringBuilder As New StringBuilder("Your total is ")
myStringBuilder.AppendFormat("{0:C} ", MyInt)
Console.WriteLine(myStringBuilder)
' The example displays the following output:
'     Your total is $25.00  

InserirInsert

O método Insert adiciona uma cadeia de caracteres ou um objeto a uma posição especificada no objeto StringBuilder atual.The Insert method adds a string or object to a specified position in the current StringBuilder object. O exemplo a seguir usa esse método para inserir uma palavra na sexta posição de um objeto StringBuilder.The following example uses this method to insert a word into the sixth position of a StringBuilder object.

StringBuilder^ myStringBuilder = gcnew StringBuilder("Hello World!");
myStringBuilder->Insert(6,"Beautiful ");
Console::WriteLine(myStringBuilder);
// The example displays the following output:
//       Hello Beautiful World!
StringBuilder myStringBuilder = new StringBuilder("Hello World!");
myStringBuilder.Insert(6,"Beautiful ");
Console.WriteLine(myStringBuilder);
// The example displays the following output:
//       Hello Beautiful World!
Dim myStringBuilder As New StringBuilder("Hello World!")
myStringBuilder.Insert(6, "Beautiful ")
Console.WriteLine(myStringBuilder)
' The example displays the following output:
'      Hello Beautiful World!

RemoverRemove

Você pode usar o método Remove para remover um número especificado de caracteres do objeto StringBuilder atual, começando em um índice com base zero especificado.You can use the Remove method to remove a specified number of characters from the current StringBuilder object, beginning at a specified zero-based index. O exemplo a seguir usa o método Remove para reduzir um objeto StringBuilder.The following example uses the Remove method to shorten a StringBuilder object.

StringBuilder^ myStringBuilder = gcnew StringBuilder("Hello World!");
myStringBuilder->Remove(5,7);
Console::WriteLine(myStringBuilder);
// The example displays the following output:
//       Hello
StringBuilder myStringBuilder = new StringBuilder("Hello World!");
myStringBuilder.Remove(5,7);
Console.WriteLine(myStringBuilder);
// The example displays the following output:
//       Hello
Dim myStringBuilder As New StringBuilder("Hello World!")
myStringBuilder.Remove(5, 7)
Console.WriteLine(myStringBuilder)
' The example displays the following output:
'       Hello

SubstituirReplace

O método Replace pode ser usado para substituir caracteres dentro do objeto StringBuilder com outro caractere especificado.The Replace method can be used to replace characters within the StringBuilder object with another specified character. O exemplo a seguir usa o método Replace para pesquisar, em um objeto StringBuilder, todas as instâncias do caractere de ponto de exclamação (!) e substituí-los com o caractere de ponto de interrogação (?).The following example uses the Replace method to search a StringBuilder object for all instances of the exclamation point character (!) and replace them with the question mark character (?).

StringBuilder^ myStringBuilder = gcnew StringBuilder("Hello World!");
myStringBuilder->Replace('!', '?');
Console::WriteLine(myStringBuilder);
// The example displays the following output:
//       Hello World?
StringBuilder myStringBuilder = new StringBuilder("Hello World!");
myStringBuilder.Replace('!', '?');
Console.WriteLine(myStringBuilder);
// The example displays the following output:
//       Hello World?
Dim myStringBuilder As New StringBuilder("Hello World!")
myStringBuilder.Replace("!"c, "?"c)
Console.WriteLine(myStringBuilder)
' The example displays the following output:
'       Hello World?

Convertendo um objeto StringBuilder em uma cadeia de caracteresConverting a StringBuilder Object to a String

Você deve converter o objeto StringBuilder em um objeto Stringpara transmitir a cadeia de caracteres representada pelo objeto StringBuilder para um método que tem um parâmetro String ou exibi-lo na interface do usuário.You must convert the StringBuilder object to a String object before you can pass the string represented by the StringBuilder object to a method that has a String parameter or display it in the user interface. Você faz essa conversão chamando o método StringBuilder.ToString.You do this conversion by calling the StringBuilder.ToString method. O exemplo a seguir chama vários métodos StringBuilder e chama o método StringBuilder.ToString() para exibir a cadeia de caracteres.The following example calls a number of StringBuilder methods and then calls the StringBuilder.ToString() method to display the string.

using System;
using System.Text;

public class Example
{
   public static void Main()
   {
      StringBuilder sb = new StringBuilder();
      bool flag = true;
      string[] spellings = { "recieve", "receeve", "receive" };
      sb.AppendFormat("Which of the following spellings is {0}:", flag);
      sb.AppendLine();
      for (int ctr = 0; ctr <= spellings.GetUpperBound(0); ctr++) {
         sb.AppendFormat("   {0}. {1}", ctr, spellings[ctr]);
         sb.AppendLine();
      }
      sb.AppendLine();
      Console.WriteLine(sb.ToString());
   }
}
// The example displays the following output:
//       Which of the following spellings is True:
//          0. recieve
//          1. receeve
//          2. receive
Imports System.Text

Module Example
   Public Sub Main()
      Dim sb As New StringBuilder()
      Dim flag As Boolean = True
      Dim spellings() As String = { "recieve", "receeve", "receive" }
      sb.AppendFormat("Which of the following spellings is {0}:", flag)
      sb.AppendLine()
      For ctr As Integer = 0 To spellings.GetUpperBound(0)
         sb.AppendFormat("   {0}. {1}", ctr, spellings(ctr))
         sb.AppendLine()
      Next
      sb.AppendLine()
      Console.WriteLine(sb.ToString())
   End Sub
End Module
' The example displays the following output:
'       Which of the following spellings is True:
'          0. recieve
'          1. receeve
'          2. receive

Consulte tambémSee also