StringBuilder Classe

Definição

Representa uma cadeia de caracteres mutável. Essa classe não pode ser herdada.

public ref class StringBuilder sealed
public ref class StringBuilder sealed : System::Runtime::Serialization::ISerializable
public sealed class StringBuilder
public sealed class StringBuilder : System.Runtime.Serialization.ISerializable
[System.Serializable]
public sealed class StringBuilder
[System.Serializable]
[System.Runtime.InteropServices.ComVisible(true)]
public sealed class StringBuilder : System.Runtime.Serialization.ISerializable
type StringBuilder = class
type StringBuilder = class
    interface ISerializable
[<System.Serializable>]
type StringBuilder = class
[<System.Serializable>]
[<System.Runtime.InteropServices.ComVisible(true)>]
type StringBuilder = class
    interface ISerializable
Public NotInheritable Class StringBuilder
Public NotInheritable Class StringBuilder
Implements ISerializable
Herança
StringBuilder
Atributos
Implementações

Exemplos

O exemplo a seguir mostra como chamar muitos dos métodos definidos pela StringBuilder classe.

using namespace System;
using namespace System::Text;

int main()
{
    // Create a StringBuilder that expects to hold 50 characters.
    // Initialize the StringBuilder with "ABC".
    StringBuilder^ sb = gcnew StringBuilder("ABC", 50);

    // Append three characters (D, E, and F) to the end of the
    // StringBuilder.
    sb->Append(gcnew array<Char>{'D', 'E', 'F'});

    // Append a format string to the end of the StringBuilder.
    sb->AppendFormat("GHI{0}{1}", (Char)'J', (Char)'k');

    // Display the number of characters in the StringBuilder
    // and its string.
    Console::WriteLine("{0} chars: {1}", sb->Length, sb->ToString());

    // Insert a string at the beginning of the StringBuilder.
    sb->Insert(0, "Alphabet: ");

    // Replace all lowercase k's with uppercase K's.
    sb->Replace('k', 'K');

    // Display the number of characters in the StringBuilder
    // and its string.
    Console::WriteLine("{0} chars: {1}", sb->Length, sb->ToString());
}

// This code produces the following output.
//
// 11 chars: ABCDEFGHIJk
// 21 chars: Alphabet: ABCDEFGHIJK
using System;
using System.Text;

public sealed class App
{
    static void Main()
    {
        // Create a StringBuilder that expects to hold 50 characters.
        // Initialize the StringBuilder with "ABC".
        StringBuilder sb = new StringBuilder("ABC", 50);

        // Append three characters (D, E, and F) to the end of the StringBuilder.
        sb.Append(new char[] { 'D', 'E', 'F' });

        // Append a format string to the end of the StringBuilder.
        sb.AppendFormat("GHI{0}{1}", 'J', 'k');

        // Display the number of characters in the StringBuilder and its string.
        Console.WriteLine("{0} chars: {1}", sb.Length, sb.ToString());

        // Insert a string at the beginning of the StringBuilder.
        sb.Insert(0, "Alphabet: ");

        // Replace all lowercase k's with uppercase K's.
        sb.Replace('k', 'K');

        // Display the number of characters in the StringBuilder and its string.
        Console.WriteLine("{0} chars: {1}", sb.Length, sb.ToString());
    }
}

// This code produces the following output.
//
// 11 chars: ABCDEFGHIJk
// 21 chars: Alphabet: ABCDEFGHIJK
Imports System.Text

Public Module App 
    Public Sub Main() 
        ' Create a StringBuilder that expects to hold 50 characters.
        ' Initialize the StringBuilder with "ABC".
        Dim sb As New StringBuilder("ABC", 50)

        ' Append three characters (D, E, and F) to the end of the StringBuilder.
        sb.Append(New Char() {"D"c, "E"c, "F"c})

        ' Append a format string to the end of the StringBuilder.
        sb.AppendFormat("GHI{0}{1}", "J"c, "k"c)

        ' Display the number of characters in the StringBuilder and its string.
        Console.WriteLine("{0} chars: {1}", sb.Length, sb.ToString())

        ' Insert a string at the beginning of the StringBuilder.
        sb.Insert(0, "Alphabet: ")

        ' Replace all lowercase k's with uppercase K's.
        sb.Replace("k", "K")

        ' Display the number of characters in the StringBuilder and its string.
        Console.WriteLine("{0} chars: {1}", sb.Length, sb.ToString())
    End Sub
End Module

' This code produces the following output.
'
' 11 chars: ABCDEFGHIJk
' 21 chars: Alphabet: ABCDEFGHIJK

Comentários

Essa classe representa um objeto semelhante a uma cadeia de caracteres cujo valor é uma sequência mutável de caracteres.

Nesta seção:

Os tipos String e StringBuilder

Embora StringBuilder e String ambos representem sequências de caracteres, eles são implementados de forma diferente. String é um tipo imutável. Ou seja, cada operação que parece modificar um String objeto realmente cria uma nova cadeia de caracteres.

Por exemplo, a chamada para o String.Concat método no exemplo C# a seguir parece alterar o valor de uma variável de cadeia de caracteres chamada value. Na verdade, o Concat método retorna um value objeto que tem um valor e um endereço diferentes do value objeto que foi passado para o método. Observe que o exemplo deve ser compilado usando a opção do /unsafe compilador.

using System;

public class Example
{
   public unsafe static void Main()
   {
      string value = "This is the first sentence" + ".";
      fixed (char* start = value)
      {
         value = String.Concat(value, "This is the second sentence. ");
         fixed (char* current = value)
         {
            Console.WriteLine(start == current);
         }
      }   
   }
}
// The example displays the following output:
//      False

Para rotinas que executam uma manipulação de cadeia de caracteres extensa (como aplicativos que modificam uma cadeia de caracteres inúmeras vezes em um loop), modificar uma cadeia de caracteres repetidamente pode solicitar uma penalidade significativa de desempenho. A alternativa é usar StringBuilder, que é uma classe de cadeia de caracteres mutável. A mutabilidade significa que, depois que uma instância da classe for criada, ela poderá ser modificada acrescentando, removendo, substituindo ou inserindo caracteres. Um StringBuilder objeto mantém um buffer para acomodar expansões na cadeia de caracteres. Novos dados serão anexados ao buffer se a sala estiver disponível; caso contrário, um novo buffer maior é alocado, os dados do buffer original são copiados para o novo buffer e os novos dados são acrescentados ao novo buffer.

Importante

Embora a StringBuilder classe geralmente ofereça melhor desempenho do que a String classe, você não deve substituir String StringBuilder automaticamente sempre que quiser manipular cadeias de caracteres. O desempenho depende do tamanho da cadeia de caracteres, da quantidade de memória a ser alocada para a nova cadeia de caracteres, do sistema no qual o código está sendo executado e do tipo de operação. Você deve estar preparado para testar seu código para determinar se StringBuilder realmente oferece uma melhoria significativa de desempenho.

Considere usar a String classe nessas condições:

  • Quando o número de alterações que seu código fará em uma cadeia de caracteres é pequeno. Nesses casos, StringBuilder pode oferecer uma melhoria Stringde desempenho insignificante ou não .

  • Quando você estiver executando um número fixo de operações de concatenação, especialmente com literais de cadeia de caracteres. Nesse caso, o compilador pode combinar as operações de concatenação em uma única operação.

  • Quando você tiver que executar operações de pesquisa extensas enquanto estiver criando sua cadeia de caracteres. A StringBuilder classe não tem métodos de pesquisa como IndexOf ou StartsWith. Você terá que converter o StringBuilder objeto em um String para essas operações e isso pode negar o benefício de desempenho de usar StringBuilder. Para obter mais informações, consulte a seção Pesquisar o texto em uma seção de objeto StringBuilder .

Considere usar a StringBuilder classe nessas condições:

  • Quando você espera que seu código faça um número desconhecido de alterações em uma cadeia de caracteres em tempo de design (por exemplo, quando você estiver usando um loop para concatenar um número aleatório de cadeias de caracteres que contêm entrada do usuário).

  • Quando você espera que o código faça um número significativo de alterações em uma cadeia de caracteres.

Como StringBuilder funciona

A StringBuilder.Length propriedade indica o número de caracteres que o StringBuilder objeto contém atualmente. Se você adicionar caracteres ao StringBuilder objeto, seu comprimento aumentará até que ele seja igual ao tamanho da StringBuilder.Capacity propriedade, que define o número de caracteres que o objeto pode conter. Se o número de caracteres adicionados fizer com que o comprimento do StringBuilder objeto exceda sua capacidade atual, a nova memória será alocada, o valor da Capacity propriedade será duplicado, novos caracteres serão adicionados ao StringBuilder objeto e sua Length propriedade será ajustada. A memória adicional do StringBuilder objeto é alocada dinamicamente até atingir o valor definido pela StringBuilder.MaxCapacity propriedade. Quando a capacidade máxima é atingida, nenhuma memória adicional pode ser alocada para o StringBuilder objeto e tentar adicionar caracteres ou expandi-lo além de sua capacidade máxima gera uma ArgumentOutOfRangeException ou uma exceção OutOfMemoryException .

O exemplo a seguir ilustra como um StringBuilder objeto aloca nova memória e aumenta sua capacidade dinamicamente à medida que a cadeia de caracteres atribuída ao objeto se expande. O código cria um StringBuilder objeto chamando seu construtor padrão (sem parâmetros). A capacidade padrão desse objeto é de 16 caracteres e sua capacidade máxima é de mais de 2 bilhões de caracteres. Acrescentando a cadeia de caracteres "Esta é uma frase". resulta em uma nova alocação de memória porque o comprimento da cadeia de caracteres (19 caracteres) excede a capacidade padrão do StringBuilder objeto. A capacidade do objeto dobra para 32 caracteres, a nova cadeia de caracteres é adicionada e o comprimento do objeto agora é igual a 19 caracteres. Em seguida, o código acrescenta a cadeia de caracteres "Esta é uma frase adicional". para o valor do StringBuilder objeto 11 vezes. Sempre que a operação de acréscimo faz com que o StringBuilder comprimento do objeto exceda sua capacidade, sua capacidade existente é duplicada e a Append operação é bem-sucedida.

using System;
using System.Reflection;
using System.Text;

public class Example
{
   public static void Main()
   {
      StringBuilder sb = new StringBuilder();
      ShowSBInfo(sb);
      sb.Append("This is a sentence.");
      ShowSBInfo(sb);
      for (int ctr = 0; ctr <= 10; ctr++) {
         sb.Append("This is an additional sentence.");
         ShowSBInfo(sb);
      }   
   }
   
   private static void ShowSBInfo(StringBuilder sb)
   {
      foreach (var prop in sb.GetType().GetProperties()) {
         if (prop.GetIndexParameters().Length == 0)
            Console.Write("{0}: {1:N0}    ", prop.Name, prop.GetValue(sb));
      }
      Console.WriteLine();
   }
}
// The example displays the following output:
//    Capacity: 16    MaxCapacity: 2,147,483,647    Length: 0
//    Capacity: 32    MaxCapacity: 2,147,483,647    Length: 19
//    Capacity: 64    MaxCapacity: 2,147,483,647    Length: 50
//    Capacity: 128    MaxCapacity: 2,147,483,647    Length: 81
//    Capacity: 128    MaxCapacity: 2,147,483,647    Length: 112
//    Capacity: 256    MaxCapacity: 2,147,483,647    Length: 143
//    Capacity: 256    MaxCapacity: 2,147,483,647    Length: 174
//    Capacity: 256    MaxCapacity: 2,147,483,647    Length: 205
//    Capacity: 256    MaxCapacity: 2,147,483,647    Length: 236
//    Capacity: 512    MaxCapacity: 2,147,483,647    Length: 267
//    Capacity: 512    MaxCapacity: 2,147,483,647    Length: 298
//    Capacity: 512    MaxCapacity: 2,147,483,647    Length: 329
//    Capacity: 512    MaxCapacity: 2,147,483,647    Length: 360
Imports System.Reflection
Imports System.Text

Module Example
   Public Sub Main()
      Dim sb As New StringBuilder()
      ShowSBInfo(sb)
      sb.Append("This is a sentence.")
      ShowSbInfo(sb)
      For ctr As Integer = 0 To 10
         sb.Append("This is an additional sentence.")
         ShowSbInfo(sb)
      Next   
   End Sub
   
   Public Sub ShowSBInfo(sb As StringBuilder)
      For Each prop In sb.GetType().GetProperties
         If prop.GetIndexParameters().Length = 0 Then
            Console.Write("{0}: {1:N0}    ", prop.Name, prop.GetValue(sb))
         End If   
      Next
      Console.WriteLine()
   End Sub
End Module
' The example displays the following output:
'    Capacity: 16    MaxCapacity: 2,147,483,647    Length: 0
'    Capacity: 32    MaxCapacity: 2,147,483,647    Length: 19
'    Capacity: 64    MaxCapacity: 2,147,483,647    Length: 50
'    Capacity: 128    MaxCapacity: 2,147,483,647    Length: 81
'    Capacity: 128    MaxCapacity: 2,147,483,647    Length: 112
'    Capacity: 256    MaxCapacity: 2,147,483,647    Length: 143
'    Capacity: 256    MaxCapacity: 2,147,483,647    Length: 174
'    Capacity: 256    MaxCapacity: 2,147,483,647    Length: 205
'    Capacity: 256    MaxCapacity: 2,147,483,647    Length: 236
'    Capacity: 512    MaxCapacity: 2,147,483,647    Length: 267
'    Capacity: 512    MaxCapacity: 2,147,483,647    Length: 298
'    Capacity: 512    MaxCapacity: 2,147,483,647    Length: 329
'    Capacity: 512    MaxCapacity: 2,147,483,647    Length: 360

Alocação de memória

A capacidade padrão de um StringBuilder objeto é de 16 caracteres e sua capacidade máxima padrão é Int32.MaxValue. Esses valores padrão serão usados se você chamar e StringBuilder() StringBuilder(String) construtores.

Você pode definir explicitamente a capacidade inicial de um StringBuilder objeto das seguintes maneiras:

  • Chamando qualquer um dos StringBuilder construtores que inclui um capacity parâmetro quando você cria o objeto.

  • Atribuindo explicitamente um novo valor à StringBuilder.Capacity propriedade para expandir um objeto existente StringBuilder . Observe que a propriedade gera uma exceção se a nova capacidade for menor que a capacidade existente ou maior que a StringBuilder capacidade máxima do objeto.

  • Chamando o StringBuilder.EnsureCapacity método com a nova capacidade. A nova capacidade não deve ser maior que a StringBuilder capacidade máxima do objeto. No entanto, ao contrário de uma atribuição à Capacity propriedade, EnsureCapacity não gerará uma exceção se a nova capacidade desejada for menor que a capacidade existente; nesse caso, a chamada de método não terá efeito.

Se o comprimento da cadeia de caracteres atribuída ao StringBuilder objeto na chamada do construtor exceder a capacidade padrão ou a capacidade especificada, a Capacity propriedade será definida como o comprimento da cadeia de caracteres especificada com o value parâmetro.

Você pode definir explicitamente a capacidade máxima de um StringBuilder objeto chamando o StringBuilder(Int32, Int32) construtor. Você não pode alterar a capacidade máxima atribuindo um novo valor à MaxCapacity propriedade, pois ela é somente leitura.

Como mostra a seção anterior, sempre que a capacidade existente é inadequada, a memória adicional é alocada e a capacidade de um StringBuilder objeto dobra até o valor definido pela MaxCapacity propriedade.

Em geral, a capacidade padrão e a capacidade máxima são adequadas para a maioria dos aplicativos. Você pode considerar a configuração desses valores nas seguintes condições:

  • Se o tamanho eventual do StringBuilder objeto provavelmente crescer muito grande, normalmente acima de vários megabytes. Nesse caso, pode haver algum benefício de desempenho ao definir a propriedade inicial Capacity como um valor significativamente alto para eliminar a necessidade de muitas realocações de memória.

  • Se o código estiver em execução em um sistema com memória limitada. Nesse caso, talvez você queira considerar a configuração da MaxCapacity propriedade como menor do que Int32.MaxValue se o código estiver tratando cadeias de caracteres grandes que podem fazer com que ela seja executada em um ambiente com restrição de memória.

Criando uma instância de um objeto StringBuilder

Você cria uma instância de um StringBuilder objeto chamando um de seus seis construtores de classe sobrecarregados, que estão listados na tabela a seguir. Três dos construtores instanciam um StringBuilder objeto cujo valor é uma cadeia de caracteres vazia, mas definem seus valores e MaxCapacity valores Capacity de forma diferente. Os três construtores restantes definem um StringBuilder objeto que tem um valor e capacidade de cadeia de caracteres específicos. Dois dos três construtores usam a capacidade máxima padrão, Int32.MaxValueenquanto o terceiro permite que você defina a capacidade máxima.

Construtor Valor da cadeia de caracteres Capacity Capacidade máxima
StringBuilder() String.Empty 16 Int32.MaxValue
StringBuilder(Int32) String.Empty Definido pelo capacity parâmetro Int32.MaxValue
StringBuilder(Int32, Int32) String.Empty Definido pelo capacity parâmetro Definido pelo maxCapacity parâmetro
StringBuilder(String) Definido pelo value parâmetro 16 ou value. Length, o que for maior Int32.MaxValue
StringBuilder(String, Int32) Definido pelo value parâmetro Definido pelo capacity parâmetro ou value. Length, o que for maior. Int32.MaxValue
StringBuilder(String, Int32, Int32, Int32) Definido por value. Substring(startIndex, length) Definido pelo capacity parâmetro ou value. Length, o que for maior. Int32.MaxValue

O exemplo a seguir usa três dessas sobrecargas de construtor para instanciar StringBuilder objetos.

using System;
using System.Text;

public class Example
{
   public static void Main()
   {
      string value = "An ordinary string";
      int index = value.IndexOf("An ") + 3;
      int capacity = 0xFFFF;
      
      // Instantiate a StringBuilder from a string.
      StringBuilder sb1 = new StringBuilder(value);
      ShowSBInfo(sb1); 
      
      // Instantiate a StringBuilder from string and define a capacity.  
      StringBuilder sb2 = new StringBuilder(value, capacity);   
      ShowSBInfo(sb2); 
      
      // Instantiate a StringBuilder from substring and define a capacity.  
      StringBuilder sb3 = new StringBuilder(value, index, 
                                            value.Length - index, 
                                            capacity );
      ShowSBInfo(sb3); 
   }

   public static void ShowSBInfo(StringBuilder sb)
   {
      Console.WriteLine("\nValue: {0}", sb.ToString());
      foreach (var prop in sb.GetType().GetProperties()) {
         if (prop.GetIndexParameters().Length == 0)
            Console.Write("{0}: {1:N0}    ", prop.Name, prop.GetValue(sb));
      }
      Console.WriteLine();
   }
}
// The example displays the following output:
//    Value: An ordinary string
//    Capacity: 18    MaxCapacity: 2,147,483,647    Length: 18
//    
//    Value: An ordinary string
//    Capacity: 65,535    MaxCapacity: 2,147,483,647    Length: 18
//    
//    Value: ordinary string
//    Capacity: 65,535    MaxCapacity: 2,147,483,647    Length: 15
Imports System.Text

Module Example
   Public Sub Main()
      Dim value As String = "An ordinary string"
      Dim index As Integer = value.IndexOf("An ") + 3
      Dim capacity As Integer = &hFFFF
      
      ' Instantiate a StringBuilder from a string.
      Dim sb1 As New StringBuilder(value)
      ShowSBInfo(sb1) 
      
      ' Instantiate a StringBuilder from string and define a capacity.  
      Dim sb2 As New StringBuilder(value, capacity)   
      ShowSBInfo(sb2) 
      
      ' Instantiate a StringBuilder from substring and define a capacity.  
      Dim sb3 As New StringBuilder(value, index, 
                                   value.Length - index, 
                                   capacity )
      ShowSBInfo(sb3) 
   End Sub
   
   Public Sub ShowSBInfo(sb As StringBuilder)
      Console.WriteLine()
      Console.WriteLine("Value: {0}", sb.ToString())
      For Each prop In sb.GetType().GetProperties
         If prop.GetIndexParameters().Length = 0 Then
            Console.Write("{0}: {1:N0}    ", prop.Name, prop.GetValue(sb))
         End If   
      Next
      Console.WriteLine()
   End Sub
End Module
' The example displays the following output:
'    Value: An ordinary string
'    Capacity: 18    MaxCapacity: 2,147,483,647    Length: 18
'    
'    Value: An ordinary string
'    Capacity: 65,535    MaxCapacity: 2,147,483,647    Length: 18
'    
'    Value: ordinary string
'    Capacity: 65,535    MaxCapacity: 2,147,483,647    Length: 15

Chamando métodos StringBuilder

A maioria dos métodos que modificam a cadeia de caracteres em uma StringBuilder instância retorna uma referência a essa mesma instância. Isso permite que você chame StringBuilder métodos de duas maneiras:

  • Você pode fazer chamadas de método individuais e ignorar o valor retornado, como faz o exemplo a seguir.

    using System;
    using System.Text;
    
    public class Example
    {
       public static void Main()
       {
          StringBuilder sb = new StringBuilder();
          sb.Append("This is the beginning of a sentence, ");
          sb.Replace("the beginning of ", "");
          sb.Insert(sb.ToString().IndexOf("a ") + 2, "complete ");
          sb.Replace(",", ".");
          Console.WriteLine(sb.ToString());
       }
    }
    // The example displays the following output:
    //        This is a complete sentence.
    
    Imports System.Text
    
    Module Example
       Public Sub Main()
          Dim sb As New StringBuilder()
          sb.Append("This is the beginning of a sentence, ")
          sb.Replace("the beginning of ", "")
          sb.Insert(sb.ToString().IndexOf("a ") + 2, "complete ")
          sb.Replace(",", ".")
          Console.WriteLine(sb.ToString())
       End Sub
    End Module
    ' The example displays the following output:
    '       This is a complete sentence.
    
  • Você pode fazer uma série de chamadas de método em uma única instrução. Isso pode ser conveniente se você quiser escrever uma única instrução que encadeia operações sucessivas. O exemplo a seguir consolida três chamadas de método do exemplo anterior em uma única linha de código.

    using System;
    using System.Text;
    
    public class Example
    {
       public static void Main()
       {
          StringBuilder sb = new StringBuilder("This is the beginning of a sentence, ");
          sb.Replace("the beginning of ", "").Insert(sb.ToString().IndexOf("a ") + 2, 
                                                     "complete ").Replace(",", ".");
          Console.WriteLine(sb.ToString());
       }
    }
    // The example displays the following output:
    //        This is a complete sentence.
    
    Imports System.Text
    
    Module Example
       Public Sub Main()
          Dim sb As New StringBuilder("This is the beginning of a sentence, ")
          sb.Replace("the beginning of ", "").Insert(sb.ToString().IndexOf("a ") + 2, _
                                                     "complete ").Replace(", ", ".")
          Console.WriteLine(sb.ToString())
       End Sub
    End Module
    ' The example displays the following output:
    '       This is a complete sentence.
    

Executando operações StringBuilder

Você pode usar os métodos da StringBuilder classe para iterar, adicionar, excluir ou modificar caracteres em um StringBuilder objeto.

Iterando caracteres StringBuilder

Você pode acessar os caracteres em um StringBuilder objeto usando a StringBuilder.Chars[] propriedade. Em C#, Chars[] é um indexador; em Visual Basic, é a propriedade padrão da StringBuilder classe. Isso permite que você defina ou recupere caracteres individuais usando apenas seu índice, sem referenciar explicitamente a Chars[] propriedade. Os caracteres em um StringBuilder objeto começam no índice 0 (zero) e continuam a indexar Length - 1.

O exemplo a seguir ilustra a Chars[] propriedade. Ele acrescenta dez números aleatórios a um StringBuilder objeto e, em seguida, itera cada caractere. Se a categoria Unicode do caractere for UnicodeCategory.DecimalDigitNumber, ela diminuirá o número em 1 (ou alterará o número para 9 se seu valor for 0). O exemplo exibe o conteúdo do StringBuilder objeto antes e depois que os valores de caracteres individuais foram alterados.

using System;
using System.Globalization;
using System.Text;

public class Example
{
   public static void Main()
   {
      Random rnd = new Random();
      StringBuilder sb = new StringBuilder();
      
      // Generate 10 random numbers and store them in a StringBuilder.
      for (int ctr = 0; ctr <= 9; ctr++)
         sb.Append(rnd.Next().ToString("N5"));    

      Console.WriteLine("The original string:");
      Console.WriteLine(sb.ToString());
            
      // Decrease each number by one.
      for (int ctr = 0; ctr < sb.Length; ctr++) {
         if (Char.GetUnicodeCategory(sb[ctr]) == UnicodeCategory.DecimalDigitNumber) {
            int number = (int) Char.GetNumericValue(sb[ctr]);
            number--;
            if (number < 0) number = 9;
         
            sb[ctr] = number.ToString()[0];
         }
      }
      Console.WriteLine("\nThe new string:");
      Console.WriteLine(sb.ToString());
   }
}
// The example displays the following output:
//    The original string:
//    1,457,531,530.00000940,522,609.000001,668,113,564.000001,998,992,883.000001,792,660,834.00
//    000101,203,251.000002,051,183,075.000002,066,000,067.000001,643,701,043.000001,702,382,508
//    .00000
//    
//    The new string:
//    0,346,420,429.99999839,411,598.999990,557,002,453.999990,887,881,772.999990,681,559,723.99
//    999090,192,140.999991,940,072,964.999991,955,999,956.999990,532,690,932.999990,691,271,497
//    .99999
Imports System.Globalization
Imports System.Text

Module Example
   Public Sub Main()
      Dim rnd As New Random()
      Dim sb As New StringBuilder()
      
      ' Generate 10 random numbers and store them in a StringBuilder.
      For ctr As Integer = 0 To 9
         sb.Append(rnd.Next().ToString("N5"))    
      Next
      Console.WriteLine("The original string:")
      Console.WriteLine(sb.ToString())
      Console.WriteLine()
            
      ' Decrease each number by one.
      For ctr As Integer = 0 To sb.Length - 1
         If Char.GetUnicodeCategory(sb(ctr)) = UnicodeCategory.DecimalDigitNumber Then
            Dim number As Integer = CType(Char.GetNumericValue(sb(ctr)), Integer)
            number -= 1
            If number < 0 Then number = 9
         
            sb(ctr) = number.ToString()(0)
         End If
      Next
      Console.WriteLine("The new string:")
      Console.WriteLine(sb.ToString())
   End Sub
End Module
' The example displays the following output:
'    The original string:
'    1,457,531,530.00000940,522,609.000001,668,113,564.000001,998,992,883.000001,792,660,834.00
'    000101,203,251.000002,051,183,075.000002,066,000,067.000001,643,701,043.000001,702,382,508
'    .00000
'    
'    The new string:
'    0,346,420,429.99999839,411,598.999990,557,002,453.999990,887,881,772.999990,681,559,723.99
'    999090,192,140.999991,940,072,964.999991,955,999,956.999990,532,690,932.999990,691,271,497
'    .99999

O uso da indexação baseada em caracteres com a propriedade Chars[] pode ser extremamente lento nas seguintes condições:

O desempenho é afetado gravemente porque cada acesso de caractere percorre toda a lista vinculada de partes para localizar o buffer correto ao qual indexar.

Observação

Mesmo para um grande objeto StringBuilder “robusto", usar a propriedade Chars[] para o acesso baseado em índice a um ou um pequeno número de caracteres tem impacto insignificante sobre o desempenho. Normalmente, trata-se de uma operação 0(n). O impacto significativo sobre o desempenho ocorre ao iterar os caracteres no objeto StringBuilder, que é uma operação O(n^2).

Se encontrar problemas de desempenho ao usar a indexação baseada em caractere com objetos StringBuilder, você poderá usar qualquer uma das seguintes alternativas:

  • Converter a instância StringBuilder para um String chamando o método ToString e, em seguida, acessar os caracteres na cadeia de caracteres.

  • Copiar o conteúdo do objeto StringBuilder existente para um novo objeto StringBuilder pré-dimensionado. O desempenho melhora porque o novo objeto StringBuilder não é robusto. Por exemplo:

    // sbOriginal is the existing StringBuilder object
    var sbNew = new StringBuilder(sbOriginal.ToString(), sbOriginal.Length);
    
    ' sbOriginal is the existing StringBuilder object
    Dim sbNew = New StringBuilder(sbOriginal.ToString(), sbOriginal.Length)
    
  • Definir a capacidade inicial do objeto StringBuilder como um valor aproximadamente igual ao seu tamanho máximo esperado chamando o construtor StringBuilder(Int32). Observe que isso aloca o bloco de memória inteiro mesmo que o StringBuilder raramente atinja sua capacidade máxima.

Adicionando texto a um objeto StringBuilder

A StringBuilder classe inclui os seguintes métodos para expandir o conteúdo de um StringBuilder objeto:

  • O Append método acrescenta uma cadeia de caracteres, uma subcadeia de caracteres, uma matriz de caracteres, uma parte de uma matriz de caracteres, um único caractere repetido várias vezes ou a representação de cadeia de caracteres de um tipo de dados primitivo a um StringBuilder objeto.

  • O AppendLine método acrescenta um terminador de linha ou uma cadeia de caracteres junto com um terminador de linha a um StringBuilder objeto.

  • O AppendFormat método acrescenta uma cadeia de caracteres de formato composto a um StringBuilder objeto. As representações de cadeia de caracteres de objetos incluídas na cadeia de caracteres de resultado podem refletir as convenções de formatação da cultura do sistema atual ou de uma cultura especificada.

  • O Insert método insere uma cadeia de caracteres, uma subcadeia de caracteres, várias repetições de uma cadeia de caracteres, uma matriz de caracteres, ou a representação de cadeia de caracteres de um tipo de dados primitivo em uma posição especificada no StringBuilder objeto. A posição é definida por um índice baseado em zero.

O exemplo a seguir usa os Appendmétodos , AppendLineAppendFormate Insert , para expandir o texto de um StringBuilder objeto.

using System;
using System.Text;

public class Example
{
   public static void Main()
   {
      // Create a StringBuilder object with no text.
      StringBuilder sb = new StringBuilder();
      // Append some text.
      sb.Append('*', 10).Append(" Adding Text to a StringBuilder Object ").Append('*', 10);
      sb.AppendLine("\n");
      sb.AppendLine("Some code points and their corresponding characters:");
      // Append some formatted text.
      for (int ctr = 50; ctr <= 60; ctr++) {
         sb.AppendFormat("{0,12:X4} {1,12}", ctr, Convert.ToChar(ctr));
         sb.AppendLine();
      }
      // Find the end of the introduction to the column.
      int pos = sb.ToString().IndexOf("characters:") + 11 + 
                Environment.NewLine.Length;
      // Insert a column header.
      sb.Insert(pos, String.Format("{2}{0,12:X4} {1,12}{2}", "Code Unit", 
                                   "Character", "\n"));      

      // Convert the StringBuilder to a string and display it.      
      Console.WriteLine(sb.ToString());      
   }
}
// The example displays the following output:
//    ********** Adding Text to a StringBuilder Object **********
//    
//    Some code points and their corresponding characters:
//    
//       Code Unit    Character
//            0032            2
//            0033            3
//            0034            4
//            0035            5
//            0036            6
//            0037            7
//            0038            8
//            0039            9
//            003A            :
//            003B            ;
//            003C            <
Imports System.Text

Module Example
   Public Sub Main()
      ' Create a StringBuilder object with no text.
      Dim sb As New StringBuilder()
      ' Append some text.
      sb.Append("*"c, 10).Append(" Adding Text to a StringBuilder Object ").Append("*"c, 10)
      sb.AppendLine()
      sb.AppendLine()
      sb.AppendLine("Some code points and their corresponding characters:")
      ' Append some formatted text.
      For ctr = 50 To 60
         sb.AppendFormat("{0,12:X4} {1,12}", ctr, Convert.ToChar(ctr))
         sb.AppendLine()
      Next
      ' Find the end of the introduction to the column.
      Dim pos As Integer = sb.ToString().IndexOf("characters:") + 11 + 
                           Environment.NewLine.Length
      ' Insert a column header.
      sb.Insert(pos, String.Format("{2}{0,12:X4} {1,12}{2}", "Code Unit", 
                                   "Character", vbCrLf))      

      ' Convert the StringBuilder to a string and display it.      
      Console.WriteLine(sb.ToString())      
   End Sub
End Module
' The example displays the following output:
'       ********** Adding Text to a StringBuilder Object **********
'       
'       Some code points and their corresponding characters:
'       
'          Code Unit    Character
'               0032            2
'               0033            3
'               0034            4
'               0035            5
'               0036            6
'               0037            7
'               0038            8
'               0039            9
'               003A            :
'               003B            ;
'               003C            <

Excluindo texto de um objeto StringBuilder

A StringBuilder classe inclui métodos que podem reduzir o tamanho da instância atual StringBuilder . O Clear método remove todos os caracteres e define a Length propriedade como zero. O Remove método exclui um número especificado de caracteres começando em uma posição de índice específica. Além disso, você pode remover caracteres do final de um StringBuilder objeto definindo sua Length propriedade como um valor menor que o comprimento da instância atual.

O exemplo a seguir remove parte do texto de um StringBuilder objeto, exibe sua capacidade resultante, capacidade máxima e valores de propriedade de comprimento e, em seguida, chama o Clear método para remover todos os caracteres do StringBuilder objeto.

using System;
using System.Text;

public class Example
{
   public static void Main()
   {
      StringBuilder sb = new StringBuilder("A StringBuilder object");
      ShowSBInfo(sb);
      // Remove "object" from the text.
      string textToRemove = "object";
      int pos = sb.ToString().IndexOf(textToRemove);
      if (pos >= 0) {
         sb.Remove(pos, textToRemove.Length);
         ShowSBInfo(sb);
      }
      // Clear the StringBuilder contents.
      sb.Clear();
      ShowSBInfo(sb);   
   }

   public static void ShowSBInfo(StringBuilder sb)
   {
      Console.WriteLine("\nValue: {0}", sb.ToString());
      foreach (var prop in sb.GetType().GetProperties()) {
         if (prop.GetIndexParameters().Length == 0)
            Console.Write("{0}: {1:N0}    ", prop.Name, prop.GetValue(sb));
      }
      Console.WriteLine();
   }
}
// The example displays the following output:
//    Value: A StringBuilder object
//    Capacity: 22    MaxCapacity: 2,147,483,647    Length: 22
//    
//    Value: A StringBuilder
//    Capacity: 22    MaxCapacity: 2,147,483,647    Length: 16
//    
//    Value:
//    Capacity: 22    MaxCapacity: 2,147,483,647    Length: 0
Imports System.Text

Module Example
   Public Sub Main()
      Dim sb As New StringBuilder("A StringBuilder object")
      ShowSBInfo(sb)
      ' Remove "object" from the text.
      Dim textToRemove As String = "object"
      Dim pos As Integer = sb.ToString().IndexOf(textToRemove)
      If pos >= 0
         sb.Remove(pos, textToRemove.Length)
         ShowSBInfo(sb)
      End If
      ' Clear the StringBuilder contents.
      sb.Clear()
      ShowSBInfo(sb)   
   End Sub

   Public Sub ShowSBInfo(sb As StringBuilder)
      Console.WriteLine()
      Console.WriteLine("Value: {0}", sb.ToString())
      For Each prop In sb.GetType().GetProperties
         If prop.GetIndexParameters().Length = 0 Then
            Console.Write("{0}: {1:N0}    ", prop.Name, prop.GetValue(sb))
         End If   
      Next
      Console.WriteLine()
   End Sub
End Module
' The example displays the following output:
'    Value: A StringBuilder object
'    Capacity: 22    MaxCapacity: 2,147,483,647    Length: 22
'    
'    Value: A StringBuilder
'    Capacity: 22    MaxCapacity: 2,147,483,647    Length: 16
'    
'    Value:
'    Capacity: 22    MaxCapacity: 2,147,483,647    Length: 0

Alterando o texto em um objeto StringBuilder

O StringBuilder.Replace método substitui todas as ocorrências de um caractere ou uma cadeia de caracteres em todo StringBuilder o objeto ou em um intervalo de caracteres específico. O exemplo a seguir usa o Replace método para substituir todos os pontos de exclamação (!) por pontos de interrogação (?) no StringBuilder objeto.

using System;
using System.Text;

public class Example
{
   public static void Main()
   {
      StringBuilder MyStringBuilder = new StringBuilder("Hello World!");
      MyStringBuilder.Replace('!', '?');
      Console.WriteLine(MyStringBuilder);
   }
}
// The example displays the following output:
//       Hello World?
Imports System.Text

Module Example
   Public Sub Main()
      Dim MyStringBuilder As New StringBuilder("Hello World!")
      MyStringBuilder.Replace("!"c, "?"c)
      Console.WriteLine(MyStringBuilder)
   End Sub
End Module
' The example displays the following output:
'       Hello World?

Pesquisando o texto em um objeto StringBuilder

A StringBuilder classe não inclui métodos semelhantes ao String.Contains, String.IndexOfe String.StartsWith métodos fornecidos pela String classe, que permitem pesquisar no objeto um caractere específico ou uma subcadeia de caracteres. Determinar a presença ou a posição de caractere inicial de uma subcadeia de caracteres requer que você pesquise um String valor usando um método de pesquisa de cadeia de caracteres ou um método de expressão regular. Há quatro maneiras de implementar essas pesquisas, como mostra a tabela a seguir.

Técnica Vantagens Desvantagens
Pesquise valores de cadeia de caracteres antes de adicioná-los ao StringBuilder objeto. Útil para determinar se existe uma subcadeia de caracteres. Não é possível usar quando a posição de índice de uma subcadeia de caracteres é importante.
Chame ToString e pesquise o objeto retornado String . Fácil de usar se você atribuir todo o texto a um StringBuilder objeto e começar a modificá-lo. Complicado chamar ToString repetidamente se você precisar fazer modificações antes que todo o texto seja adicionado ao StringBuilder objeto.

Lembre-se de trabalhar do final do StringBuilder texto do objeto se estiver fazendo alterações.
Use a Chars[] propriedade para pesquisar sequencialmente um intervalo de caracteres. Útil se você estiver preocupado com caracteres individuais ou com uma subcadeia de caracteres pequena. Complicado se o número de caracteres a serem pesquisados for grande ou se a lógica de pesquisa for complexa.

Resulta em um desempenho muito ruim para objetos que cresceram muito grande por meio de chamadas de método repetidas.
Converta o StringBuilder objeto em um String objeto e execute modificações no String objeto. Útil se o número de modificações for pequeno. Nega o benefício de desempenho da StringBuilder classe se o número de modificações for grande.

Vamos examinar essas técnicas com mais detalhes.

  • Se o objetivo da pesquisa for determinar se existe uma subcadeia de caracteres específica (ou seja, se você não estiver interessado na posição da subcadeia de caracteres), poderá pesquisar cadeias de caracteres antes de armazená-las no StringBuilder objeto. O exemplo a seguir fornece uma implementação possível. Ele define uma StringBuilderFinder classe cujo construtor é passado uma referência a um StringBuilder objeto e a subcadeia de caracteres a ser encontrada na cadeia de caracteres. Nesse caso, o exemplo tenta determinar se as temperaturas registradas estão em Fahrenheit ou Celsius e adiciona o texto introdutório apropriado ao início do StringBuilder objeto. Um gerador de número aleatório é usado para selecionar uma matriz que contém dados em graus Celsius ou graus Fahrenheit.

    using System;
    using System.Text;
    
    public class Example
    {
       public static void Main()
       {
          Random rnd = new Random();
          string[] tempF = { "47.6F", "51.3F", "49.5F", "62.3F" };
          string[] tempC = { "21.2C", "16.1C", "23.5C", "22.9C" };
          string[][] temps = { tempF, tempC }; 
    
          StringBuilder sb = new StringBuilder();
          var f = new StringBuilderFinder(sb, "F");
          var baseDate = new DateTime(2013, 5, 1); 
          String[] temperatures = temps[rnd.Next(2)];
          bool isFahrenheit = false;
          foreach (var temperature in temperatures) {
             if (isFahrenheit)
                sb.AppendFormat("{0:d}: {1}\n", baseDate, temperature);
             else
                isFahrenheit = f.SearchAndAppend(String.Format("{0:d}: {1}\n", 
                                                 baseDate, temperature));
             baseDate = baseDate.AddDays(1);
          }            
          if (isFahrenheit) {
             sb.Insert(0, "Average Daily Temperature in Degrees Fahrenheit");
             sb.Insert(47, "\n\n");
          }
          else {
             sb.Insert(0, "Average Daily Temperature in Degrees Celsius");
             sb.Insert(44, "\n\n");
          }   
          Console.WriteLine(sb.ToString());
       }
    }
    
    public class StringBuilderFinder
    {
       private StringBuilder sb;
       private String text;
       
       public StringBuilderFinder(StringBuilder sb, String textToFind)
       {
          this.sb = sb;
          this.text = textToFind;
       }
       
       public bool SearchAndAppend(String stringToSearch)
       {
          sb.Append(stringToSearch);
          return stringToSearch.Contains(text);
       }
    }
    // The example displays output similar to the following:
    //    Average Daily Temperature in Degrees Celsius
    //    
    //    5/1/2013: 21.2C
    //    5/2/2013: 16.1C
    //    5/3/2013: 23.5C
    //    5/4/2013: 22.9C
    
    Imports System.Text
    
    Module Example
       Public Sub Main()
          Dim rnd As New Random()
          Dim tempF() As String = { "47.6F", "51.3F", "49.5F", "62.3F" }
          Dim tempC() As String = { "21.2C", "16.1C", "23.5C", "22.9C" }
          Dim temps()() As String = { tempF, tempC } 
    
          Dim sb As StringBuilder = New StringBuilder()
          Dim f As New StringBuilderFinder(sb, "F")
          Dim baseDate As New DateTime(2013, 5, 1) 
          Dim temperatures() As String = temps(rnd.Next(2))
          Dim isFahrenheit As Boolean = False
          For Each temperature In temperatures
             If isFahrenheit Then
                sb.AppendFormat("{0:d}: {1}{2}", baseDate, temperature, vbCrLf)
             Else
                isFahrenheit = f.SearchAndAppend(String.Format("{0:d}: {1}{2}", 
                                                 baseDate, temperature, vbCrLf))
             End If
             baseDate = baseDate.AddDays(1)
          Next            
          If isFahrenheit Then
             sb.Insert(0, "Average Daily Temperature in Degrees Fahrenheit")
             sb.Insert(47, vbCrLf + vbCrLf)
          Else
             sb.Insert(0, "Average Daily Temperature in Degrees Celsius")
             sb.Insert(44, vbCrLf + vbCrLf)
          End If   
          Console.WriteLine(sb.ToString())
       End Sub
    End Module
    
    Public Class StringBuilderFinder
       Private sb As StringBuilder
       Private text As String
       
       Public Sub New(sb As StringBuilder, textToFind As String)
          Me.sb = sb
          text = textToFind
       End Sub
       
       Public Function SearchAndAppend(stringToSearch As String) As Boolean
          sb.Append(stringToSearch)
          Return stringToSearch.Contains(text)
       End Function
    End Class
    ' The example displays output similar to the following:
    '    Average Daily Temperature in Degrees Celsius
    '    
    '    5/1/2013: 21.2C
    '    5/2/2013: 16.1C
    '    5/3/2013: 23.5C
    '    5/4/2013: 22.9C
    
  • Chame o StringBuilder.ToString método para converter o StringBuilder objeto em um String objeto. Você pode pesquisar a cadeia de caracteres usando métodos como String.LastIndexOf ou String.StartsWith, ou você pode usar expressões regulares e a Regex classe para pesquisar padrões. Como ambos e StringBuilder String objetos usam a codificação UTF-16 para armazenar caracteres, as posições de índice de caracteres, subcadeias de caracteres e correspondências de expressões regulares são as mesmas em ambos os objetos. Isso permite que você use StringBuilder métodos para fazer alterações na mesma posição na qual esse texto é encontrado no String objeto.

    Observação

    Se você adotar essa abordagem, deverá trabalhar do final do objeto até o StringBuilder início para que não precise converter repetidamente o StringBuilder objeto em uma cadeia de caracteres.

    O exemplo a seguir ilustra esta abordagem. Ele armazena quatro ocorrências de cada letra do alfabeto inglês em um StringBuilder objeto. Em seguida, ele converte o texto em um String objeto e usa uma expressão regular para identificar a posição inicial de cada sequência de quatro caracteres. Por fim, ele adiciona um sublinhado antes de cada sequência de quatro caracteres, exceto para a primeira sequência, e converte o primeiro caractere da sequência em maiúsculas.

    using System;
    using System.Text;
    using System.Text.RegularExpressions;
    
    public class Example
    {
       public static void Main()
       {
          // Create a StringBuilder object with 4 successive occurrences 
          // of each character in the English alphabet. 
          StringBuilder sb = new StringBuilder();
          for (ushort ctr = (ushort)'a'; ctr <= (ushort) 'z'; ctr++)
             sb.Append(Convert.ToChar(ctr), 4);
          
          // Create a parallel string object.
          String sbString = sb.ToString();
          // Determine where each new character sequence begins.
          String pattern = @"(\w)\1+";
          MatchCollection matches = Regex.Matches(sbString, pattern);
    
          // Uppercase the first occurrence of the sequence, and separate it
          // from the previous sequence by an underscore character.
          for (int ctr = matches.Count - 1; ctr >= 0; ctr--) { 
             Match m = matches[ctr];
             sb[m.Index] = Char.ToUpper(sb[m.Index]);
             if (m.Index > 0) sb.Insert(m.Index, "_");
          }
          // Display the resulting string.
          sbString = sb.ToString();
          int line = 0;
          do {
             int nChars = line * 80 + 79 <= sbString.Length ? 
                                 80 : sbString.Length - line * 80;
             Console.WriteLine(sbString.Substring(line * 80, nChars));
             line++;
          } while (line * 80 < sbString.Length);
       }
    }
    // The example displays the following output:
    //    Aaaa_Bbbb_Cccc_Dddd_Eeee_Ffff_Gggg_Hhhh_Iiii_Jjjj_Kkkk_Llll_Mmmm_Nnnn_Oooo_Pppp_
    //    Qqqq_Rrrr_Ssss_Tttt_Uuuu_Vvvv_Wwww_Xxxx_Yyyy_Zzzz
    
    Imports System.Text
    Imports System.Text.RegularExpressions
    
    Module Example
       Public Sub Main()
          ' Create a StringBuilder object with 4 successive occurrences 
          ' of each character in the English alphabet. 
          Dim sb As New StringBuilder()
          For ctr As UShort = AscW("a") To Ascw("z")
             sb.Append(ChrW(ctr), 4)
          Next    
          ' Create a parallel string object.
          Dim sbString As String = sb.ToString()
          ' Determine where each new character sequence begins.
          Dim pattern As String = "(\w)\1+"
          Dim matches As MatchCollection = Regex.Matches(sbString, pattern)
    
          ' Uppercase the first occurrence of the sequence, and separate it
          ' from the previous sequence by an underscore character.
          For ctr As Integer = matches.Count - 1 To 0 Step -1 
             Dim m As Match = matches(ctr)
             sb.Chars(m.Index) = Char.ToUpper(sb.Chars(m.index))
             If m.Index > 0 Then sb.Insert(m.Index, "_")
          Next
          ' Display the resulting string.
          sbString = sb.ToString()
          Dim line As Integer = 0
          Do
             Dim nChars As Integer = If(line * 80 + 79 <= sbString.Length, 
                                        80, sbString.Length - line * 80)
             Console.WriteLine(sbString.Substring(line * 80, nChars))
             line += 1
          Loop While line * 80 < sbString.Length
       End Sub
    End Module
    ' The example displays the following output:
    '    Aaaa_Bbbb_Cccc_Dddd_Eeee_Ffff_Gggg_Hhhh_Iiii_Jjjj_Kkkk_Llll_Mmmm_Nnnn_Oooo_Pppp_
    '    Qqqq_Rrrr_Ssss_Tttt_Uuuu_Vvvv_Wwww_Xxxx_Yyyy_Zzzz
    
  • Use a StringBuilder.Chars[] propriedade para pesquisar sequencialmente um intervalo de caracteres em um StringBuilder objeto. Essa abordagem pode não ser prática se o número de caracteres a serem pesquisados for grande ou a lógica de pesquisa for particularmente complexa. Para obter as implicações de desempenho do acesso baseado em índice de caractere por caractere para objetos muito grandes e em StringBuilder partes, consulte a documentação da StringBuilder.Chars[] propriedade.

    O exemplo a seguir é idêntico à funcionalidade do exemplo anterior, mas difere na implementação. Ele usa a Chars[] propriedade para detectar quando um valor de caractere foi alterado, insere um sublinhado nessa posição e converte o primeiro caractere na nova sequência em maiúsculas.

    using System;
    using System.Text;
    
    public class Example
    {
       public static void Main()
       {
          // Create a StringBuilder object with 4 successive occurrences 
          // of each character in the English alphabet. 
          StringBuilder sb = new StringBuilder();
          for (ushort ctr = (ushort) 'a'; ctr <= (ushort) 'z'; ctr++)
             sb.Append(Convert.ToChar(ctr), 4);
    
          // Iterate the text to determine when a new character sequence occurs.
          int position = 0;
          Char current = '\u0000';
          do {
             if (sb[position] != current) {
                current = sb[position];
                sb[position] = Char.ToUpper(sb[position]);
                if (position > 0) 
                   sb.Insert(position, "_");
                position += 2;
             }
             else {
                position++;
             }      
          } while (position <= sb.Length - 1);
          // Display the resulting string.
          String sbString = sb.ToString();
          int line = 0;
          do {
             int nChars = line * 80 + 79 <= sbString.Length ? 
                                 80 : sbString.Length - line * 80;
             Console.WriteLine(sbString.Substring(line * 80, nChars));
             line++;
          } while (line * 80 < sbString.Length);
       }
    }
    // The example displays the following output:
    //    Aaaa_Bbbb_Cccc_Dddd_Eeee_Ffff_Gggg_Hhhh_Iiii_Jjjj_Kkkk_Llll_Mmmm_Nnnn_Oooo_Pppp_
    //    Qqqq_Rrrr_Ssss_Tttt_Uuuu_Vvvv_Wwww_Xxxx_Yyyy_Zzzz
    
    Imports System.Text
    
    Module Example
       Public Sub Main()
          ' Create a StringBuilder object with 4 successive occurrences 
          ' of each character in the English alphabet. 
          Dim sb As New StringBuilder()
          For ctr As UShort = AscW("a") To Ascw("z")
             sb.Append(ChrW(ctr), 4)
          Next    
          ' Iterate the text to determine when a new character sequence occurs.
          Dim position As Integer = 0
          Dim current As Char = ChrW(0)
          Do
             If sb(position) <> current Then
                current = sb(position)
                sb(position) = Char.ToUpper(sb(position))
                If position > 0 Then sb.Insert(position, "_")
                position += 2
             Else
                position += 1
             End If      
          Loop While position <= sb.Length - 1
          ' Display the resulting string.
          Dim sbString As String = sb.ToString()
          Dim line As Integer = 0
          Do
             Dim nChars As Integer = If(line * 80 + 79 <= sbString.Length, 
                                        80, sbString.Length - line * 80)
             Console.WriteLine(sbString.Substring(line * 80, nChars))
             line += 1
          Loop While line * 80 < sbString.Length
       End Sub
    End Module
    ' The example displays the following output:
    '    Aaaa_Bbbb_Cccc_Dddd_Eeee_Ffff_Gggg_Hhhh_Iiii_Jjjj_Kkkk_Llll_Mmmm_Nnnn_Oooo_Pppp_
    '    Qqqq_Rrrr_Ssss_Tttt_Uuuu_Vvvv_Wwww_Xxxx_Yyyy_Zzzz
    
  • Armazene todo o texto não modificado no StringBuilder objeto, chame o StringBuilder.ToString método para converter o StringBuilder objeto em um String objeto e execute as modificações no String objeto. Você pode usar essa abordagem se tiver apenas algumas modificações; caso contrário, o custo de trabalhar com cadeias de caracteres imutáveis pode negar os benefícios de desempenho do uso de um StringBuilder objeto.

    O exemplo a seguir é idêntico à funcionalidade dos dois exemplos anteriores, mas difere na implementação. Ele cria um StringBuilder objeto, converte-o em um String objeto e usa uma expressão regular para executar todas as modificações restantes na cadeia de caracteres. O Regex.Replace(String, String, MatchEvaluator) método usa uma expressão lambda para executar a substituição em cada correspondência.

    using System;
    using System.Text;
    using System.Text.RegularExpressions;
    
    public class Example
    {
       public static void Main()
       {
          // Create a StringBuilder object with 4 successive occurrences 
          // of each character in the English alphabet. 
          StringBuilder sb = new StringBuilder();
          for (ushort ctr = (ushort)'a'; ctr <= (ushort) 'z'; ctr++)
             sb.Append(Convert.ToChar(ctr), 4);
         
          // Convert it to a string.
          String sbString = sb.ToString();
    
          // Use a regex to uppercase the first occurrence of the sequence, 
          // and separate it from the previous sequence by an underscore.
          string pattern = @"(\w)(\1+)";
          sbString = Regex.Replace(sbString, pattern, 
                                   m => (m.Index > 0 ? "_" : "") + 
                                   m.Groups[1].Value.ToUpper() + 
                                   m.Groups[2].Value);
    
          // Display the resulting string.
          int line = 0;
          do {
             int nChars = line * 80 + 79 <= sbString.Length ? 
                                 80 : sbString.Length - line * 80;
             Console.WriteLine(sbString.Substring(line * 80, nChars));
             line++;
          } while (line * 80 < sbString.Length);
       }
    }
    // The example displays the following output:
    //    Aaaa_Bbbb_Cccc_Dddd_Eeee_Ffff_Gggg_Hhhh_Iiii_Jjjj_Kkkk_Llll_Mmmm_Nnnn_Oooo_Pppp_
    //    Qqqq_Rrrr_Ssss_Tttt_Uuuu_Vvvv_Wwww_Xxxx_Yyyy_Zzzz
    
    Imports System.Text
    Imports System.Text.RegularExpressions
    
    Module Example
       Public Sub Main()
          ' Create a StringBuilder object with 4 successive occurrences 
          ' of each character in the English alphabet. 
          Dim sb As New StringBuilder()
          For ctr As UShort = AscW("a") To Ascw("z")
             sb.Append(ChrW(ctr), 4)
          Next    
          ' Convert it to a string.
          Dim sbString As String = sb.ToString()
    
          ' Use a regex to uppercase the first occurrence of the sequence, 
          ' and separate it from the previous sequence by an underscore.
          Dim pattern As String = "(\w)(\1+)"
          sbString = Regex.Replace(sbString, pattern, 
                                   Function(m) If(m.Index > 0,"_","") + 
                                               m.Groups(1).Value.ToUpper + 
                                               m.Groups(2).Value)
    
          ' Display the resulting string.
          Dim line As Integer = 0
          Do
             Dim nChars As Integer = If(line * 80 + 79 <= sbString.Length, 
                                        80, sbString.Length - line * 80)
             Console.WriteLine(sbString.Substring(line * 80, nChars))
             line += 1
          Loop While line * 80 < sbString.Length
       End Sub
    End Module
    ' The example displays the following output:
    '    Aaaa_Bbbb_Cccc_Dddd_Eeee_Ffff_Gggg_Hhhh_Iiii_Jjjj_Kkkk_Llll_Mmmm_Nnnn_Oooo_Pppp_
    '    Qqqq_Rrrr_Ssss_Tttt_Uuuu_Vvvv_Wwww_Xxxx_Yyyy_Zzzz
    

Convertendo o objeto StringBuilder em uma cadeia de caracteres

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. Você executa essa conversão chamando o StringBuilder.ToString método. Para obter uma ilustração, consulte o exemplo anterior, que chama o ToString método para converter um StringBuilder objeto em uma cadeia de caracteres para que ele possa ser passado para um método de expressão regular.

Notas aos Chamadores

No .NET Core e no .NET Framework 4.0 e versões posteriores, quando você instancia o StringBuilder objeto chamando o StringBuilder(Int32, Int32) construtor, tanto o comprimento quanto a capacidade da StringBuilder instância podem crescer além do valor de sua MaxCapacity propriedade. Isso pode ocorrer especialmente quando você chama e Append(String) AppendFormat(String, Object) os métodos para acrescentar cadeias de caracteres pequenas.

Construtores

StringBuilder()

Inicializa uma nova instância da classe StringBuilder.

StringBuilder(Int32)

Inicializa uma nova instância da classe StringBuilder usando a capacidade especificada.

StringBuilder(Int32, Int32)

Inicializa uma nova instância da classe StringBuilder que começa com uma capacidade especificada e pode crescer até um máximo especificado.

StringBuilder(String)

Inicializa uma nova instância da classe StringBuilder usando a cadeia de caracteres especificada.

StringBuilder(String, Int32)

Inicializa uma nova instância da classe StringBuilder usando a cadeia de caracteres e a capacidade especificadas.

StringBuilder(String, Int32, Int32, Int32)

Inicializa uma nova instância da classe StringBuilder da capacidade e da subcadeia de caracteres especificada.

Propriedades

Capacity

Obtém ou define o número máximo de caracteres que podem ser contidos na memória alocada pela instância atual.

Chars[Int32]

Obtém ou define o caractere na posição de caractere especificada nessa instância.

Length

Obtém ou define o tamanho do objeto atual StringBuilder.

MaxCapacity

Obtém a capacidade máxima desta instância.

Métodos

Append(Boolean)

Acrescenta a representação de cadeia de caracteres de um valor booliano especificado à essa instância.

Append(Byte)

Acrescenta a representação de cadeia de caracteres de um inteiro sem sinal de 8 bits especificado a essa instância.

Append(Char)

Acrescenta a representação de cadeia de caracteres de um objeto Char especificado à essa instância.

Append(Char*, Int32)

Acrescenta uma matriz de caracteres Unicode começando em um endereço especificado a essa instância.

Append(Char, Int32)

Acrescenta um número de cópias especificado da representação de cadeia de caracteres de um caractere Unicode a essa instância.

Append(Char[])

Acrescenta a representação de cadeia de caracteres dos caracteres Unicode em uma matriz especificada a essa instância.

Append(Char[], Int32, Int32)

Acrescenta a representação de cadeia de caracteres de uma submatriz especificada de caracteres Unicode à essa instância.

Append(Decimal)

Acrescenta a representação de cadeia de caracteres de um número decimal especificado à essa instância.

Append(Double)

Acrescenta a representação de cadeia de caracteres de um número de ponto flutuante de precisão dupla especificado a essa instância.

Append(IFormatProvider, StringBuilder+AppendInterpolatedStringHandler)

Acrescenta a cadeia de caracteres interpolada especificada a esta instância usando o formato especificado.

Append(Int16)

Acrescenta a representação de cadeia de caracteres de um inteiro com sinal de 16 bits especificado a essa instância.

Append(Int32)

Acrescenta a representação de cadeia de caracteres de um inteiro com sinal de 32 bits especificado a essa instância.

Append(Int64)

Acrescenta a representação de cadeia de caracteres de um inteiro com sinal de 64 bits especificado a essa instância.

Append(Object)

Acrescenta a representação de cadeia de caracteres de um objeto especificado à essa instância.

Append(ReadOnlyMemory<Char>)

Acrescenta a representação de cadeia de caracteres de uma região de memória do caractere somente leitura a essa instância.

Append(ReadOnlySpan<Char>)

Acrescenta a representação de cadeia de caracteres de um intervalo de caracteres somente leitura a essa instância.

Append(SByte)

Acrescenta a representação de cadeia de caracteres de um inteiro com sinal de 8 bits especificado a essa instância.

Append(Single)

Acrescenta a representação de cadeia de caracteres de um número de ponto flutuante de precisão simples especificado a essa instância.

Append(String)

Acrescenta uma cópia da cadeia de caracteres especificada a essa instância.

Append(String, Int32, Int32)

Acrescenta uma cópia de uma subcadeia de caracteres especificada a esta instância.

Append(StringBuilder)

Acrescenta a representação de cadeia de caracteres de um construtor de cadeia de caracteres especificado a essa instância.

Append(StringBuilder, Int32, Int32)

Acrescenta uma cópia de uma substring em um construtor de cadeia de caracteres especificado a essa instância.

Append(StringBuilder+AppendInterpolatedStringHandler)

Acrescenta a cadeia de caracteres interpolada especificada a esta instância.

Append(UInt16)

Acrescenta a representação de cadeia de caracteres de um inteiro sem sinal de 16 bits especificado a essa instância.

Append(UInt32)

Acrescenta a representação de cadeia de caracteres de um inteiro sem sinal de 32 bits especificado a essa instância.

Append(UInt64)

Acrescenta a representação de cadeia de caracteres de um inteiro sem sinal de 64 bits especificado a essa instância.

AppendFormat(IFormatProvider, String, Object)

Acrescenta a cadeia de caracteres retornada pelo processamento de uma cadeia de caracteres de formato composto, que contém zero ou mais itens de formato, a essa instância. Cada item de formato é substituído pela representação de cadeia de caracteres de um único argumento usando um provedor de formato especificado.

AppendFormat(IFormatProvider, String, Object, Object)

Acrescenta a cadeia de caracteres retornada pelo processamento de uma cadeia de caracteres de formato composto, que contém zero ou mais itens de formato, a essa instância. Cada item de formato é substituído pela representação de cadeia de caracteres de um de dois argumentos usando um provedor de formato especificado.

AppendFormat(IFormatProvider, String, Object, Object, Object)

Acrescenta a cadeia de caracteres retornada pelo processamento de uma cadeia de caracteres de formato composto, que contém zero ou mais itens de formato, a essa instância. Cada item de formato é substituído pela representação de cadeia de caracteres de um de três argumentos usando um provedor de formato especificado.

AppendFormat(IFormatProvider, String, Object[])

Acrescenta a cadeia de caracteres retornada pelo processamento de uma cadeia de caracteres de formato composto, que contém zero ou mais itens de formato, a essa instância. Cada item de formato é substituído pela representação de cadeia de um argumento correspondente em uma matriz de parâmetro usando um provedor de formato especificado.

AppendFormat(String, Object)

Acrescenta a cadeia de caracteres retornada pelo processamento de uma cadeia de caracteres de formato composto, que contém zero ou mais itens de formato, a essa instância. Cada item de formato é substituído pela representação de cadeia de caracteres de um único argumento.

AppendFormat(String, Object, Object)

Acrescenta a cadeia de caracteres retornada pelo processamento de uma cadeia de caracteres de formato composto, que contém zero ou mais itens de formato, a essa instância. Cada item de formato é substituído pela representação de cadeia de caracteres de um dos dois argumentos.

AppendFormat(String, Object, Object, Object)

Acrescenta a cadeia de caracteres retornada pelo processamento de uma cadeia de caracteres de formato composto, que contém zero ou mais itens de formato, a essa instância. Cada item de formato é substituído pela representação de cadeia de caracteres de um dos três argumentos.

AppendFormat(String, Object[])

Acrescenta a cadeia de caracteres retornada pelo processamento de uma cadeia de caracteres de formato composto, que contém zero ou mais itens de formato, a essa instância. Cada item de formato é substituído pela representação de cadeia de caracteres de um argumento correspondente em uma matriz de parâmetros.

AppendJoin(Char, Object[])

Concatena as representações de cadeia de caracteres dos elementos na matriz de objetos fornecida, usando o separador de caracteres especificado entre cada membro e, em seguida, acrescenta o resultado à instância atual do construtor de cadeias de caracteres.

AppendJoin(Char, String[])

Concatena as cadeias de caracteres da matriz fornecida, usando o separador de caracteres especificado entre cada cadeia de caracteres e, em seguida, acrescenta o resultado à instância atual do construtor de cadeias de caracteres.

AppendJoin(String, Object[])

Concatena as representações de cadeia de caracteres dos elementos na matriz de objetos fornecida, usando o separador especificado entre cada membro e, em seguida, acrescenta o resultado à instância atual do construtor de cadeias de caracteres.

AppendJoin(String, String[])

Concatena as cadeias de caracteres da matriz fornecida, usando o separador especificado entre cada cadeia de caracteres e, em seguida, acrescenta o resultado à instância atual do construtor de cadeias de caracteres.

AppendJoin<T>(Char, IEnumerable<T>)

Concatena e acrescenta os membros de uma coleção, usando o separador de caracteres especificado entre cada membro.

AppendJoin<T>(String, IEnumerable<T>)

Concatena e acrescenta os membros de uma coleção, usando o separador especificado entre cada membro.

AppendLine()

Acrescenta o terminador de linha padrão ao final do atual objeto StringBuilder.

AppendLine(IFormatProvider, StringBuilder+AppendInterpolatedStringHandler)

Acrescenta a cadeia de caracteres interpolada especificada usando o formato especificado, seguido pelo terminador de linha padrão, até o final do objeto StringBuilder atual.

AppendLine(String)

Acrescenta uma cópia da cadeia de caracteres especificada seguida pelo terminador de linha padrão para o fim do objeto StringBuilder atual.

AppendLine(StringBuilder+AppendInterpolatedStringHandler)

Acrescenta a cadeia de caracteres interpolada especificada seguida pelo terminador de linha padrão até o final do objeto StringBuilder atual.

Clear()

Remove todos os caracteres da instância StringBuilder atual.

CopyTo(Int32, Char[], Int32, Int32)

Copia os caracteres de um segmento especificado desta instância para um segmento especificado de uma matriz Char de destino.

CopyTo(Int32, Span<Char>, Int32)

Copia os caracteres de um segmento especificado desta instância para um intervalo Char de destino.

EnsureCapacity(Int32)

Garante que a capacidade desta instância do StringBuilder tenha pelo menos o valor especificado.

Equals(Object)

Determina se o objeto especificado é igual ao objeto atual.

(Herdado de Object)
Equals(ReadOnlySpan<Char>)

Retorna um valor que indica se os caracteres nessa instância são iguais aos caracteres em um intervalo de caracteres somente leitura especificado.

Equals(StringBuilder)

Retorna um valor que indica se a instância é igual a um objeto especificado.

GetChunks()

Retorna um objeto que pode ser usado para iterar nas partes de caracteres representadas em um ReadOnlyMemory<Char> criado usando essa instância de StringBuilder.

GetHashCode()

Serve como a função de hash padrão.

(Herdado de Object)
GetType()

Obtém o Type da instância atual.

(Herdado de Object)
Insert(Int32, Boolean)

Insere a representação de cadeia de caracteres de um valor booliano nessa instância na posição do caractere especificada.

Insert(Int32, Byte)

Insere a representação de cadeia de caracteres de um inteiro sem sinal de 8 bits especificado nessa instância na posição do caractere especificada.

Insert(Int32, Char)

Insere a representação de cadeia de caracteres de um caractere Unicode especificado nessa instância na posição do caractere especificada.

Insert(Int32, Char[])

Insere a representação de cadeia de caracteres de uma matriz de caracteres Unicode especificada nessa instância na posição do caractere especificada.

Insert(Int32, Char[], Int32, Int32)

Insere a representação de cadeia de caracteres de uma submatriz de caracteres Unicode especificada nessa instância na posição do caractere especificada.

Insert(Int32, Decimal)

Insere a representação de cadeia de caracteres de um número decimal nessa instância na posição do caractere especificada.

Insert(Int32, Double)

Insere a representação de cadeia de caracteres de um número de ponto flutuante de precisão dupla nessa instância na posição do caractere especificada.

Insert(Int32, Int16)

Insere a representação de cadeia de caracteres de um inteiro com sinal de 16 bits especificado nessa instância na posição do caractere especificada.

Insert(Int32, Int32)

Insere a representação de cadeia de caracteres de um inteiro com sinal de 32 bits especificado nessa instância na posição do caractere especificada.

Insert(Int32, Int64)

Insere a representação de cadeia de caracteres de um inteiro com sinal de 64 bits nessa instância na posição do caractere especificada.

Insert(Int32, Object)

Insere a representação de cadeia de caracteres de um objeto nessa instância na posição do caractere especificada.

Insert(Int32, ReadOnlySpan<Char>)

Insere uma sequência de caracteres nesta instância na posição de caractere especificada.

Insert(Int32, SByte)

Insere a representação de cadeia de caracteres de um inteiro com sinal de 8 bits especificado nessa instância na posição do caractere especificada.

Insert(Int32, Single)

Insere a representação de cadeia de caracteres de um número de ponto flutuante de precisão simples nessa instância na posição do caractere especificada.

Insert(Int32, String)

Insere uma cadeia de caracteres nesta instância na posição do caractere especificado.

Insert(Int32, String, Int32)

Insere uma ou mais cópias de uma cadeia de caracteres especificada nesta instância na posição do caractere especificada.

Insert(Int32, UInt16)

Insere a representação de cadeia de caracteres de um inteiro sem sinal de 16 bits nessa instância na posição do caractere especificada.

Insert(Int32, UInt32)

Insere a representação de cadeia de caracteres de um inteiro sem sinal de 32 bits nessa instância na posição do caractere especificada.

Insert(Int32, UInt64)

Insere a representação de cadeia de caracteres de um inteiro sem sinal de 64 bits nessa instância na posição do caractere especificada.

MemberwiseClone()

Cria uma cópia superficial do Object atual.

(Herdado de Object)
Remove(Int32, Int32)

Remove o intervalo especificado de caracteres dessa instância.

Replace(Char, Char)

Substitui todas as ocorrências de um caractere especificado nesta instância por outro caractere especificado.

Replace(Char, Char, Int32, Int32)

Substitui, dentro de uma subcadeia dessa instância, todas as ocorrências um caractere especificado por outro caractere especificado.

Replace(String, String)

Substitui todas as ocorrências de uma cadeia de caracteres especificada nesta instância por outra cadeia de caracteres especificada.

Replace(String, String, Int32, Int32)

Substitui, dentro de uma subcadeia dessa instância, todas as ocorrências de uma cadeia de caracteres especificada por outra cadeia de caracteres especificada.

ToString()

Converte o valor dessa instância em um String.

ToString(Int32, Int32)

Converte o valor de uma subcadeia de caracteres dessa instância em um String.

Implantações explícitas de interface

ISerializable.GetObjectData(SerializationInfo, StreamingContext)

Popula um objeto SerializationInfo com os dados necessários para desserializar o objeto StringBuilder atual.

Aplica-se a

Confira também