Este artículo se tradujo automáticamente. Para ver el artículo en inglés, active la casilla Inglés. Además, puede mostrar el texto en inglés en una ventana emergente si mueve el puntero del mouse sobre el texto.
Traducción
Inglés

Clase StringBuilder

 

Publicado: octubre de 2016

Representa una cadena de caracteres mutable. Esta clase no puede heredarse.

Para examinar el código fuente de .NET Framework para este tipo, vea la Reference Source.

Espacio de nombres:   System.Text
Ensamblado:  mscorlib (en mscorlib.dll)

System.Object
  System.Text.StringBuilder

[SerializableAttribute]
[ComVisibleAttribute(true)]
public sealed class StringBuilder : ISerializable

NombreDescripción
System_CAPS_pubmethodStringBuilder()

Inicializa una nueva instancia de la clase StringBuilder.

System_CAPS_pubmethodStringBuilder(Int32)

Inicializa una nueva instancia de la clase StringBuilder con la capacidad especificada.

System_CAPS_pubmethodStringBuilder(Int32, Int32)

Inicializa una nueva instancia de la clase StringBuilder que empieza con una capacidad concreta y puede aumentar hasta un máximo especificado.

System_CAPS_pubmethodStringBuilder(String)

Inicializa una nueva instancia de la clase StringBuilder con la cadena especificada.

System_CAPS_pubmethodStringBuilder(String, Int32)

Inicializa una nueva instancia de la clase StringBuilder con la capacidad y la cadena especificadas.

System_CAPS_pubmethodStringBuilder(String, Int32, Int32, Int32)

Inicializa una nueva instancia de la clase StringBuilder a partir de la subcadena y la capacidad especificadas.

NombreDescripción
System_CAPS_pubpropertyCapacity

Obtiene o establece el número máximo de caracteres que puede contener la memoria asignada por la instancia en uso.

System_CAPS_pubpropertyChars[Int32]

Obtiene o establece el carácter en la posición de carácter especificada en la instancia.

System_CAPS_pubpropertyLength

Obtiene o establece la longitud del objeto StringBuilder actual.

System_CAPS_pubpropertyMaxCapacity

Obtiene la capacidad máxima de la instancia.

NombreDescripción
System_CAPS_pubmethodAppend(Boolean)

Anexa a esta instancia la representación en forma de cadena de un valor booleano especificado.

System_CAPS_pubmethodAppend(Byte)

Anexa a esta instancia la representación en forma de cadena de un entero sin signo de 8 bits especificado.

System_CAPS_pubmethodAppend(Char)

Anexa a esta instancia la representación en forma de cadena de un objeto Char especificado.

System_CAPS_pubmethodAppend(Char*, Int32)

Anexa a esta instancia una matriz de caracteres Unicode a partir de una dirección especificada.

System_CAPS_pubmethodAppend(Char, Int32)

Anexa a esta instancia un número especificado de copias de la representación en forma de cadena de un carácter Unicode.

System_CAPS_pubmethodAppend(Char[])

Anexa a esta instancia la representación en forma de cadena de los caracteres Unicode de una matriz especificada.

System_CAPS_pubmethodAppend(Char[], Int32, Int32)

Anexa a esta instancia la representación en forma de cadena de una submatriz de caracteres Unicode especificada.

System_CAPS_pubmethodAppend(Decimal)

Anexa a esta instancia la representación en forma de cadena de un número decimal especificado.

System_CAPS_pubmethodAppend(Double)

Anexa a esta instancia la representación en forma de cadena de un número de punto flotante de precisión doble especificado.

System_CAPS_pubmethodAppend(Int16)

Anexa a esta instancia la representación en forma de cadena de un entero con signo de 16 bits especificado.

System_CAPS_pubmethodAppend(Int32)

Anexa a esta instancia la representación en forma de cadena de un entero con signo de 32 bits especificado.

System_CAPS_pubmethodAppend(Int64)

Anexa a esta instancia la representación en forma de cadena de un entero con signo de 64 bits especificado.

System_CAPS_pubmethodAppend(Object)

Anexa a esta instancia la representación en forma de cadena de un objeto especificado.

System_CAPS_pubmethodAppend(SByte)

Anexa a esta instancia la representación en forma de cadena de un entero con signo de 8 bits especificado.

System_CAPS_pubmethodAppend(Single)

Anexa a esta instancia la representación en forma de cadena de un número de punto flotante de precisión sencilla especificado.

System_CAPS_pubmethodAppend(String)

Anexa a esta instancia una copia de la cadena especificada.

System_CAPS_pubmethodAppend(String, Int32, Int32)

Anexa a esta instancia una copia de una subcadena especificada.

System_CAPS_pubmethodAppend(UInt16)

Anexa a esta instancia la representación en forma de cadena de un entero sin signo de 16 bits especificado.

System_CAPS_pubmethodAppend(UInt32)

Anexa a esta instancia la representación en forma de cadena de un entero sin signo de 32 bits especificado.

System_CAPS_pubmethodAppend(UInt64)

Anexa a esta instancia la representación en forma de cadena de un entero sin signo de 64 bits especificado.

System_CAPS_pubmethodAppendFormat(IFormatProvider, String, Object)

Anexa a esta instancia la cadena que se devuelve al procesar una cadena con formato compuesto, que contiene cero o más elementos de formato. Cada elemento de formato se reemplaza por la representación en forma de cadena de un único argumento utilizando un proveedor de formato especificado.

System_CAPS_pubmethodAppendFormat(IFormatProvider, String, Object, Object)

Anexa a esta instancia la cadena que se devuelve al procesar una cadena con formato compuesto, que contiene cero o más elementos de formato. Cada elemento de formato se reemplaza por la representación de cadena de dos argumentos utilizando un proveedor de formato especificado.

System_CAPS_pubmethodAppendFormat(IFormatProvider, String, Object, Object, Object)

Anexa a esta instancia la cadena que se devuelve al procesar una cadena con formato compuesto, que contiene cero o más elementos de formato. Cada elemento de formato se reemplaza por la representación de cadena de tres argumentos utilizando un proveedor de formato especificado.

System_CAPS_pubmethodAppendFormat(IFormatProvider, String, Object[])

Anexa a esta instancia la cadena que se devuelve al procesar una cadena con formato compuesto, que contiene cero o más elementos de formato. Cada elemento de formato se reemplaza con la representación de cadena del argumento correspondiente de una matriz de parámetros, utilizando el proveedor de formato especificado.

System_CAPS_pubmethodAppendFormat(String, Object)

Anexa a esta instancia la cadena que se devuelve al procesar una cadena con formato compuesto, que contiene cero o más elementos de formato. Cada elemento de formato se reemplaza por la representación en forma de cadena de un único argumento.

System_CAPS_pubmethodAppendFormat(String, Object, Object)

Anexa a esta instancia la cadena que se devuelve al procesar una cadena con formato compuesto, que contiene cero o más elementos de formato. Cada elemento de formato se reemplaza por la representación en forma de cadena de uno de dos argumentos.

System_CAPS_pubmethodAppendFormat(String, Object, Object, Object)

Anexa a esta instancia la cadena que se devuelve al procesar una cadena con formato compuesto, que contiene cero o más elementos de formato. Cada elemento de formato se reemplaza por la representación en forma de cadena de uno de tres argumentos.

System_CAPS_pubmethodAppendFormat(String, Object[])

Anexa a esta instancia la cadena que se devuelve al procesar una cadena con formato compuesto, que contiene cero o más elementos de formato. Cada elemento de formato se reemplaza por la representación de cadena del argumento correspondiente de una matriz de parámetros.

System_CAPS_pubmethodAppendLine()

Anexa el terminador de línea predeterminado al final del objeto StringBuilder actual.

System_CAPS_pubmethodAppendLine(String)

Anexa una copia de la cadena especificada seguida del terminador de línea predeterminado al final del objeto StringBuilder actual.

System_CAPS_pubmethodClear()

Quita todos los caracteres de la instancia de StringBuilder actual.

System_CAPS_pubmethodCopyTo(Int32, Char[], Int32, Int32)

Copia los caracteres de un segmento especificado de esta instancia al segmento especificado de una matriz Char de destino.

System_CAPS_pubmethodEnsureCapacity(Int32)

Garantiza que la capacidad de la instancia de StringBuilder corresponde como mínimo al valor especificado.

System_CAPS_pubmethodEquals(Object)

Determina si el objeto especificado es igual al objeto actual.(Heredado de Object).

System_CAPS_pubmethodEquals(StringBuilder)

Devuelve un valor que indica si esta instancia equivale a un objeto especificado.

System_CAPS_pubmethodGetHashCode()

Sirve como la función hash predeterminada.(Heredado de Object).

System_CAPS_pubmethodGetType()

Obtiene el Type de la instancia actual.(Heredado de Object).

System_CAPS_pubmethodInsert(Int32, Boolean)

Inserta en la instancia la representación en forma de cadena de un valor booleano en la posición del carácter que se haya especificado.

System_CAPS_pubmethodInsert(Int32, Byte)

Inserta en la instancia la representación en forma de cadena de un entero de 8 bits sin signo, en la posición del carácter que se haya especificado.

System_CAPS_pubmethodInsert(Int32, Char)

Inserta en la instancia la representación en forma de cadena de un carácter Unicode concreto en la posición del carácter que se haya especificado.

System_CAPS_pubmethodInsert(Int32, Char[])

Inserta en la instancia la representación en forma de cadena de una matriz concreta de caracteres Unicode en la posición del carácter que se haya especificado.

System_CAPS_pubmethodInsert(Int32, Char[], Int32, Int32)

Inserta en la instancia la representación en forma de cadena de una submatriz concreta de caracteres Unicode en la posición del carácter que se haya especificado.

System_CAPS_pubmethodInsert(Int32, Decimal)

Inserta en la instancia la representación en forma de cadena de un número decimal en la posición del carácter que se haya especificado.

System_CAPS_pubmethodInsert(Int32, Double)

Inserta en la instancia la representación en forma de cadena de un número de punto flotante de doble precisión en la posición del carácter que se haya especificado.

System_CAPS_pubmethodInsert(Int32, Int16)

Inserta en la instancia la representación en forma de cadena de un entero de 16 bits con signo especificado, en la posición del carácter que se haya indicado.

System_CAPS_pubmethodInsert(Int32, Int32)

Inserta en la instancia la representación en forma de cadena de un entero de 32 bits con signo especificado, en la posición del carácter que se haya indicado.

System_CAPS_pubmethodInsert(Int32, Int64)

Inserta en la instancia la representación en forma de cadena de un entero de 64 bits con signo, en la posición del carácter que se haya especificado.

System_CAPS_pubmethodInsert(Int32, Object)

Inserta en la instancia la representación en forma de cadena de un objeto en la posición del carácter que se haya especificado.

System_CAPS_pubmethodInsert(Int32, SByte)

Inserta en la instancia la representación en forma de cadena de un entero de 8 bits con signo especificado, en la posición del carácter que se haya indicado.

System_CAPS_pubmethodInsert(Int32, Single)

Inserta en la instancia la representación en forma de cadena de un número de punto flotante de precisión sencilla, en la posición del carácter que se haya especificado.

System_CAPS_pubmethodInsert(Int32, String)

Inserta una cadena en la instancia en la posición del carácter que se haya especificado.

System_CAPS_pubmethodInsert(Int32, String, Int32)

Inserta en la instancia una o más copias de una cadena concreta en la posición del carácter que se haya especificado.

System_CAPS_pubmethodInsert(Int32, UInt16)

Inserta en la instancia la representación en forma de cadena de un entero de 16 bits sin signo, en la posición del carácter que se haya especificado.

System_CAPS_pubmethodInsert(Int32, UInt32)

Inserta en la instancia la representación en forma de cadena de un entero de 32 bits sin signo, en la posición del carácter que se haya especificado.

System_CAPS_pubmethodInsert(Int32, UInt64)

Inserta en la instancia la representación en forma de cadena de un entero de 64 bits sin signo, en la posición del carácter que se haya especificado.

System_CAPS_pubmethodRemove(Int32, Int32)

Quita de la instancia el intervalo de caracteres especificado.

System_CAPS_pubmethodReplace(Char, Char)

Reemplaza todas las apariciones de un carácter en la instancia por otro carácter especificado.

System_CAPS_pubmethodReplace(Char, Char, Int32, Int32)

En una subcadena de la instancia, reemplaza todas las apariciones de un carácter especificado por otro carácter especificado.

System_CAPS_pubmethodReplace(String, String)

Reemplaza todas las apariciones de una cadena especificada en la instancia por otra cadena especificada.

System_CAPS_pubmethodReplace(String, String, Int32, Int32)

En una subcadena de la instancia, reemplaza todas las apariciones de una cadena especificada por otra cadena especificada.

System_CAPS_pubmethodToString()

Convierte el valor de la instancia en un objeto String.(Invalida Object.ToString()).

System_CAPS_pubmethodToString(Int32, Int32)

Convierte el valor de una subcadena de la instancia en un objeto String.

NombreDescripción
System_CAPS_pubinterfaceSystem_CAPS_privmethodISerializable.GetObjectData(SerializationInfo, StreamingContext)

Esta API admite la infraestructura producto y no está diseñada para usarse directamente desde el código. Rellena un objeto System.Runtime.Serialization.SerializationInfo con los datos necesarios para deserializar el objeto StringBuilder actual.

System_CAPS_noteNota

Para ver el código fuente de .NET Framework para este tipo, consulte el Reference Source. Puede examinar el código fuente en línea, descargue la referencia para verla sin conexión y recorrer (incluidas las revisiones y actualizaciones) durante la depuración; see instructions.

Esta clase representa un objeto de cadena cuyo valor es una secuencia de caracteres mutable.

En esta sección:

Aunque StringBuilder y String los dos representan secuencias de caracteres, se implementan de forma diferente. String es un tipo inmutable. Es decir, cada operación que aparece para modificar un String objeto realmente crea una nueva cadena.

Por ejemplo, la llamada a la String.Concat aparece el método en el siguiente ejemplo de C# cambiar el valor de una variable de cadena denominada value. De hecho, el Concat método devuelve un value objeto que tiene un valor diferente y una dirección de la value objeto que se pasó al método. Tenga en cuenta que el ejemplo se debe compilar utilizando el /unsafe opción del 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 las rutinas que realizan la manipulación de cadenas amplia (por ejemplo, las aplicaciones que modifican una cadena varias veces en un bucle), modificar una cadena repetidamente puede suponer una importante penalización del rendimiento. La alternativa consiste en utilizar StringBuilder, que es una clase de cadena mutable. Mutabilidad significa que una vez creada una instancia de la clase, puede modificar por anexar, eliminar, reemplazar o insertar caracteres. Un StringBuilder objeto mantiene un búfer para alojar las expansiones de la cadena. Nuevos datos se anexan al búfer si hay espacio disponible; de lo contrario, se asigna un nuevo búfer más grande, datos del búfer original se copian en el nuevo búfer y, a continuación, se anexan los nuevos datos al nuevo búfer.

System_CAPS_importantImportante

Aunque la StringBuilder clase generalmente ofrece un mejor rendimiento que el String (clase), no debe automáticamente sustituir String con StringBuilder siempre que desee para manipular las cadenas. El rendimiento depende del tamaño de la cadena, la cantidad de memoria a asignar para la nueva cadena, el sistema en el que se ejecuta la aplicación y el tipo de operación. Debe estar preparado para probar la aplicación para determinar si StringBuilder realmente ofrece una mejora considerable del rendimiento.

Considere el uso de la String clase bajo estas condiciones:

  • Cuando el número de cambios que hará que la aplicación en una cadena es pequeño. En estos casos, StringBuilder podría oferta insignificante o ninguna mejora de rendimiento sobre String.

  • Cuando se realiza un número fijo de las operaciones de concatenación, especialmente con literales de cadena. En este caso, el compilador podría combinar las operaciones de concatenación en una sola operación.

  • Cuando tenga que realizar operaciones de búsqueda más amplias mientras se crea la cadena. El StringBuilder carece de clase como métodos de búsqueda IndexOf o StartsWith. Tendrá que convertir el StringBuilder de objeto a un String para estas operaciones y esto pueden invalidar la ventaja de rendimiento de uso StringBuilder. Para obtener más información, consulte el Buscar el texto en un objeto StringBuilder sección.

Considere el uso de la StringBuilder clase bajo estas condiciones:

  • Cuando se espera la aplicación para realizar un número desconocido de cambios en una cadena en tiempo de diseño (por ejemplo, cuando se usa un bucle para concatenar un número aleatorio de cadenas que contienen proporcionados por el usuario).

  • Cuando se espera la aplicación para realizar un número significativo de cambios en una cadena.

El StringBuilder.Length propiedad indica el número de caracteres del StringBuilder objeto contiene actualmente. Si se agregan caracteres a la StringBuilder del objeto, su longitud aumenta hasta que sea igual que el tamaño de la StringBuilder.Capacity propiedad, que define el número de caracteres que puede contener el objeto. Si el número de caracteres agregados hace que la longitud de la StringBuilder objeto supere su capacidad actual, la nueva memoria se asigna el valor de la Capacity se duplica la propiedad, se agregan nuevos caracteres a la StringBuilder objeto y su Length se ajusta la propiedad. Memoria adicional para la StringBuilder objeto se asigna dinámicamente hasta que alcanza el valor definido por el StringBuilder.MaxCapacity propiedad. Cuando se alcanza la capacidad máxima, no se puede asignar ninguna memoria adicional para la StringBuilder objeto y este intentando agregar caracteres o expanda más allá de su capacidad máxima produce un ArgumentOutOfRangeException o un OutOfMemoryException excepción.

En el ejemplo siguiente se muestra cómo un StringBuilder objeto asigna memoria nueva y aumenta dinámicamente su capacidad como se expande la cadena asignada al objeto. El código crea un StringBuilder objeto llamando a su constructor (sin parámetros) de forma predeterminada. La capacidad predeterminada de este objeto es 16 caracteres, y su capacidad máxima es de más de 2 millones de caracteres. Anexa la cadena "Es una frase". da como resultado una nueva asignación de memoria, porque la longitud de cadena (19 caracteres) supera la capacidad predeterminada de la StringBuilder objeto. La capacidad del objeto se duplica a 32 caracteres, se agrega la nueva cadena y la longitud del objeto iguala 19 caracteres. El código, anexa la cadena "Es una frase adicional". en el valor de la StringBuilder objeto 11 veces. Cada vez que hace que la longitud de la operación de anexado el StringBuilder se duplica el objeto supere su capacidad, su capacidad existente y la Append operación se realiza correctamente.

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

La capacidad predeterminada de un StringBuilder objeto es 16 caracteres y su capacidad máxima de predeterminada es Int32.MaxValue. Estos valores predeterminados se utilizan si se llama a la StringBuilder() y StringBuilder(String) constructores.

Puede definir explícitamente la capacidad inicial de un StringBuilder objeto de las maneras siguientes:

  • Al llamar a cualquiera de los StringBuilder constructores que incluye un capacity parámetro cuando se crea el objeto.

  • Asignando explícitamente un valor nuevo a la StringBuilder.Capacity propiedad para expandir una existente StringBuilder objeto. Tenga en cuenta que la propiedad produce una excepción si la nueva capacidad es menor que el existente capacidad o mayor que el StringBuilder máximo del objeto.

  • Al llamar a la StringBuilder.EnsureCapacity método con la nueva capacidad. La nueva capacidad no debe ser mayor que el StringBuilder máximo del objeto. Sin embargo, a diferencia de una asignación a la Capacity propiedad EnsureCapacity no produce una excepción si la nueva capacidad deseada es menor que la capacidad existente; en este caso, la llamada al método no tiene ningún efecto.

Si la longitud de la cadena asignada a la StringBuilder objeto en la llamada al constructor supera la capacidad predeterminada o la capacidad especificada, el Capacity propiedad se establece en la longitud de la cadena especificada con el value parámetro.

Puede definir explícitamente la capacidad máxima de un StringBuilder objeto mediante una llamada a la StringBuilder(Int32, Int32) constructor. No se puede cambiar la capacidad máxima asignando un nuevo valor para el MaxCapacity propiedad, porque es de sólo lectura.

La sección anterior se muestra, siempre que la capacidad existente es inadecuado, más memoria se asigna y la capacidad de un StringBuilder objeto dobles hasta el valor definido por el MaxCapacity propiedad.

En general, la capacidad predeterminada y la capacidad máxima son adecuados para la mayoría de las aplicaciones. Se puede establecer estos valores en las siguientes condiciones:

  • Si el tamaño final de la StringBuilder objeto es probable que crezca extremadamente grande, normalmente más de varios megabytes. En este caso, puede haber alguna ventaja de rendimiento de la configuración inicial Capacity propiedad en un valor alto significativamente para eliminar la necesidad de demasiados reasignaciones de memoria.

  • Si la aplicación se ejecuta en un sistema con memoria limitada. En este caso, puede considerar la configuración del MaxCapacity propiedad a menos de Int32.MaxValue Si su aplicación está administrando grandes cadenas que pueden provocar que se ejecutan en un entorno con restricciones de memoria.

Crear instancias de un StringBuilder objeto llamando a uno de sus seis constructores de clase sobrecargada que se enumeran en la tabla siguiente. Crear tres de los constructores de instancias de un StringBuilder objeto cuyo valor es una cadena vacía, pero establecer su Capacity y MaxCapacity valores de forma diferente. Definen los tres constructores restantes un StringBuilder objeto que tiene un valor de cadena específico y la capacidad. Dos de los tres constructores usan la capacidad máxima predeterminada de Int32.MaxValue, mientras que el tercero le permite establecer la capacidad máxima.

Constructor

Valor de cadena

Capacidad

Capacidad máxima

StringBuilder()

String.Empty

16

Int32.MaxValue

StringBuilder(Int32)

String.Empty

Definido por el capacity parámetro

Int32.MaxValue

StringBuilder(Int32, Int32)

String.Empty

Definido por el capacity parámetro

Definido por el maxCapacity parámetro

StringBuilder(String)

Definido por el value parámetro

16 o value. Length, lo que sea mayor

Int32.MaxValue

StringBuilder(String, Int32)

Definido por el value parámetro

Definido por el capacity parámetro o value. Length, lo que sea mayor.

Int32.MaxValue

StringBuilder(String, Int32, Int32, Int32)

Definido por value. Substring(startIndex, length)

Definido por el capacity parámetro o value. Length, lo que sea mayor.

Definido por el maxCapacity parámetro

En el ejemplo siguiente se utiliza tres de estas sobrecargas del constructor para crear instancias de 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

La mayoría de los métodos que modifican la cadena en un StringBuilder instancia devuelven una referencia a esa misma instancia. Esto le permite llamar a StringBuilder métodos de dos maneras:

  • Puede realizar llamadas a métodos individuales y omitir el valor devuelto, como en el ejemplo siguiente.

    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.
    
  • Puede realizar una serie de llamadas de método en una sola instrucción. Esto puede ser conveniente si desea escribir una sola instrucción que se vincula a las operaciones sucesivas. En el ejemplo siguiente, se consolida tres llamadas al método del ejemplo anterior en una sola línea 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.
    

Puede utilizar los métodos de la StringBuilder clase para recorrer en iteración, agregar, eliminar o modificar caracteres en un StringBuilder objeto.

Puede tener acceso a los caracteres de un StringBuilder objeto usando el StringBuilder.Chars propiedad. En C#, Chars es un indizador; en Visual Basic, es la propiedad predeterminada de la StringBuilder clase. Esto le permite establecer o recuperar los caracteres individuales utilizando su índice únicamente, sin hacer referencia explícita a la Chars propiedad. Los caracteres de un StringBuilder objeto comienzan en el índice 0 (cero) y continuar indizar Length - 1.

En el ejemplo siguiente se muestra el Chars propiedad. Anexa diez números aleatorios a una StringBuilder de objetos y, a continuación, recorre en iteración cada carácter. Si la categoría del carácter Unicode es UnicodeCategory.DecimalDigitNumber, se reduce el número 1 (o cambia el número 9 si su valor es 0). En el ejemplo se muestra el contenido de la StringBuilder objeto ambos antes y después de que se han cambiado los valores de caracteres individuales.

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

La StringBuilder clase incluye los siguientes métodos para expandir el contenido de una StringBuilder objeto:

  • El Append método anexa una cadena, una subcadena, una matriz de caracteres, una parte de una matriz de caracteres, un carácter individual se repite varias veces, o el tipo de representación de cadena de datos primitivos para un StringBuilder objeto.

  • El AppendLine método anexa un terminador de línea o una cadena junto con un terminador de línea en un StringBuilder objeto.

  • El AppendFormat método anexa una a una StringBuilder objeto. Las representaciones de cadena de objetos incluidos en la cadena de resultado pueden reflejar las convenciones de formato de la referencia cultural actual del sistema o una referencia cultural especificada.

  • El Insert método inserta una cadena, una subcadena, varias repeticiones de una cadena, una matriz de caracteres, una parte de una matriz de caracteres o la representación de cadena de datos primitivos que se escriba en una posición especificada en el StringBuilder objeto. La posición se define mediante un índice de base cero.

En el ejemplo siguiente se usa el Append, AppendLine, AppendFormat, y Insert métodos para expandir el texto de un 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            <

La StringBuilder clase incluye métodos que pueden reducir el tamaño del actual StringBuilder instancia. El Clear método quita todos los caracteres y establece el Length propiedad en cero. El Remove método elimina un número especificado de caracteres a partir de una posición de índice determinada. Además, se pueden quitar caracteres del final de una StringBuilder objeto estableciendo su Length propiedad a un valor que es menor que la longitud de la instancia actual.

El ejemplo siguiente quita la parte del texto de un StringBuilder objeto, muestra su capacidad resultante, capacidad máxima y valores de propiedad de longitud y, a continuación, llama el Clear método para quitar todos los caracteres desde la 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

El StringBuilder.Replace método reemplaza todas las apariciones de un carácter o una cadena en toda la StringBuilder objeto o en un intervalo de caracteres determinado. En el ejemplo siguiente se usa el Replace método para reemplazar todos los signos de exclamación (!) con signos de interrogación (?) en el 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?

La StringBuilder clase incluye métodos similares a los String.Contains, String.IndexOf, y String.StartsWith métodos proporcionados por la String (clase), que le permiten buscar el objeto de un determinado carácter o una subcadena. Determinar la presencia o la posición de carácter de una subcadena inicial requiere que buscar un String valor mediante un método de búsqueda de cadena o un método de expresión regular. Hay cuatro maneras de implementar dichas búsquedas, como se muestra en la tabla siguiente.

Técnica

Profesionales de TI

Desventajas

Buscar valores de cadena antes de agregarlos a la StringBuilder objeto.

Es útil para determinar si existe una subcadena.

No se puede utilizar cuando la posición de índice de una subcadena es importante.

Llame a ToString y busque el valor devuelto String objeto.

Fácil de usar si asigna todo el texto a un StringBuilder de objetos y, a continuación, comenzar a modificarlo.

Complicado en llamar repetidamente a ToString si debe realizar modificaciones antes de que todo el texto se agrega a la StringBuilder objeto.

Debe recordar trabajar desde el final de la StringBuilder texto objeto si está realizando cambios.

Utilice la Chars propiedad que se va a buscar un intervalo de caracteres de forma secuencial.

Resulta útil si está preocupado por los caracteres individuales o una subcadena pequeño.

Complicado si el número de caracteres que se va a buscar es grande o si la lógica de búsqueda es compleja.

Convertir el StringBuilder de objeto a una String de objetos y realizar modificaciones en el String objeto.

Resulta útil si el número de modificaciones es pequeño.

Niega la ventaja de rendimiento de la StringBuilder clase si la cantidad de modificaciones es grande.

Vamos a examinar estas técnicas más detalladamente.

  • Si es el objetivo de la búsqueda determinar si una subcadena determinada existe (es decir, si no está interesado en la posición de la subcadena), puede buscar cadenas antes de almacenarlos en el StringBuilder objeto. En el ejemplo siguiente se proporciona una implementación posible. Define un StringBuilderFinder clase cuyo constructor se pasa una referencia a un StringBuilder objeto y la subcadena que se va a buscar en la cadena. En este caso, el ejemplo intenta determinar si las temperaturas grabadas en grados Fahrenheit o Celsius y el texto de introducción adecuado se agrega al principio de la StringBuilder objeto. Un generador de números aleatorios se utiliza para seleccionar una matriz que contiene los datos en grados centígrados o grados 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
    
  • Llame a la StringBuilder.ToString método para convertir el StringBuilder de objeto para un String objeto. Puede buscar la cadena con métodos como String.LastIndexOf o String.StartsWith, o puede utilizar expresiones regulares y la Regex clase para buscar patrones. Dado que ambos StringBuilder y String objetos utilizan la codificación para almacenar caracteres, las posiciones de índice de caracteres, subcadenas, UTF-16 y coincidencias de expresiones regulares son los mismos en ambos objetos. Esto le permite usar StringBuilder métodos para realizar cambios en la misma posición en la que se encuentra ese texto en el String objeto.

    System_CAPS_noteNota

    Si adopta este enfoque, debe trabajar desde el final de la StringBuilder objeto en sus comienzos, por lo que no tiene que convertir repetidamente la StringBuilder objeto en una cadena.

    En el ejemplo siguiente se muestra este enfoque. Almacena cuatro instancias de cada letra del alfabeto inglés en un StringBuilder objeto. A continuación, convierte el texto a un String de objetos y utiliza una expresión regular para identificar la posición inicial de cada secuencia de cuatro caracteres. Por último, agrega un carácter de subrayado antes de cada secuencia de cuatro caracteres, excepto la primera secuencia y convierte el primer carácter de la secuencia de letras mayú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
    
  • Utilice la StringBuilder.Chars propiedad secuencialmente buscar un intervalo de caracteres en un StringBuilder objeto. Este enfoque puede no resultar práctico si el número de caracteres que se va a buscar es grande o la lógica de búsqueda es especialmente compleja.

    El ejemplo siguiente es idéntico en funcionalidad al ejemplo anterior, pero difiere en implementación. Usa el Chars propiedad para detectar cuándo ha cambiado un valor de carácter, inserta un carácter de subrayado en esa posición y convierte el primer carácter en la nueva secuencia a mayú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
    
  • Almacenar todo el texto sin modificaciones en el StringBuilder de objeto, llame a la StringBuilder.ToString método para convertir el StringBuilder objeto un String de objetos y realizar las modificaciones en el String objeto. Puede utilizar este enfoque si dispone de unas pocas modificaciones; de lo contrario, el costo de trabajar con cadenas inmutable puede anular las ventajas de rendimiento de usar un StringBuilder objeto.

    El ejemplo siguiente es idéntico en funcionalidad a los dos ejemplos anteriores, pero difiere en implementación. Crea un StringBuilder de objeto, lo convierte en un String de objetos y, a continuación, se utiliza una expresión regular para realizar todas las demás modificaciones en la cadena. El Regex.Replace(String, String, MatchEvaluator) método utiliza una expresión lambda para realizar el reemplazo en cada coincidencia.

    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
    

Debe convertir la StringBuilder objeto un String objeto antes de pasar la cadena representada por la StringBuilder objeto a un método que tiene un String parámetro o mostrarlo en la interfaz de usuario. Realizar esta conversión mediante una llamada a la StringBuilder.ToString (método). Para ver una ilustración, vea el ejemplo anterior, que llama a la ToString método para convertir un StringBuilder objeto en una cadena para que se puede pasar a un método de expresión regular.

Notas para llamadores:

En el.NET Framework 4 y la .NET Framework 4.5, al crear instancias de la StringBuilder objeto mediante una llamada a la StringBuilder(Int32, Int32) constructor, la longitud y la capacidad de la StringBuilder instancia puede crecer más allá del valor de su MaxCapacity propiedad. Esto puede ocurrir especialmente cuando se llama a la Append y AppendFormat métodos para anexar cadenas pequeñas.

En el ejemplo siguiente se muestra cómo llamar a muchos de los métodos definidos por el StringBuilder clase.

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

Plataforma universal de Windows
Disponible desde 8
.NET Framework
Disponible desde 1.1
Biblioteca de clases portable
Se admite en: plataformas portátiles de .NET
Silverlight
Disponible desde 2.0
Windows Phone Silverlight
Disponible desde 7.0
Windows Phone
Disponible desde 8.1

Cualquier miembro ( Compartido en Visual Basic) estático público de este tipo es seguro para subprocesos. No se garantiza que los miembros de instancia sean seguros para subprocesos.

Volver al principio
Mostrar: