Encoding.GetMaxByteCount(Int32) Método

Definição

Quando substituído em uma classe derivada, calcula o número máximo de bytes produzidos pela codificação do número especificado de caracteres.When overridden in a derived class, calculates the maximum number of bytes produced by encoding the specified number of characters.

public:
 abstract int GetMaxByteCount(int charCount);
public abstract int GetMaxByteCount (int charCount);
abstract member GetMaxByteCount : int -> int
Public MustOverride Function GetMaxByteCount (charCount As Integer) As Integer

Parâmetros

charCount
Int32

O número de caracteres a ser codificado.The number of characters to encode.

Retornos

Int32

O número máximo de bytes produzidos pela codificação do número de caracteres especificado.The maximum number of bytes produced by encoding the specified number of characters.

Exceções

charCount é menor que zero.charCount is less than zero.

Ocorreu um fallback (saiba mais em Codificação de caracteres no .NET)A fallback occurred (for more information, see Character Encoding in .NET)

-e--and-

EncoderFallback é definido como EncoderExceptionFallback.EncoderFallback is set to EncoderExceptionFallback.

Exemplos

O exemplo a seguir determina o número de bytes necessários para codificar uma matriz de caracteres, codifica os caracteres e exibe os bytes resultantes.The following example determines the number of bytes required to encode a character array, encodes the characters, and displays the resulting bytes.

using namespace System;
using namespace System::Text;
void PrintCountsAndBytes( array<Char>^chars, Encoding^ enc );
void PrintHexBytes( array<Byte>^bytes );
int main()
{
   
   // The characters to encode:
   //    Latin Small Letter Z (U+007A)
   //    Latin Small Letter A (U+0061)
   //    Combining Breve (U+0306)
   //    Latin Small Letter AE With Acute (U+01FD)
   //    Greek Small Letter Beta (U+03B2)
   //    a high-surrogate value (U+D8FF)
   //    a low-surrogate value (U+DCFF)
   array<Char>^myChars = gcnew array<Char>{
      L'z','a',L'\u0306',L'\u01FD',L'\u03B2',L'\xD8FF',L'\xDCFF'
   };
   
   // Get different encodings.
   Encoding^ u7 = Encoding::UTF7;
   Encoding^ u8 = Encoding::UTF8;
   Encoding^ u16LE = Encoding::Unicode;
   Encoding^ u16BE = Encoding::BigEndianUnicode;
   Encoding^ u32 = Encoding::UTF32;
   
   // Encode the entire array, and print out the counts and the resulting bytes.
   PrintCountsAndBytes( myChars, u7 );
   PrintCountsAndBytes( myChars, u8 );
   PrintCountsAndBytes( myChars, u16LE );
   PrintCountsAndBytes( myChars, u16BE );
   PrintCountsAndBytes( myChars, u32 );
}

void PrintCountsAndBytes( array<Char>^chars, Encoding^ enc )
{
   
   // Display the name of the encoding used.
   Console::Write( "{0,-30} :", enc );
   
   // Display the exact byte count.
   int iBC = enc->GetByteCount( chars );
   Console::Write( " {0,-3}", iBC );
   
   // Display the maximum byte count.
   int iMBC = enc->GetMaxByteCount( chars->Length );
   Console::Write( " {0,-3} :", iMBC );
   
   // Encode the array of chars.
   array<Byte>^bytes = enc->GetBytes( chars );
   
   // Display all the encoded bytes.
   PrintHexBytes( bytes );
}

void PrintHexBytes( array<Byte>^bytes )
{
   if ( (bytes == nullptr) || (bytes->Length == 0) )
      Console::WriteLine( "<none>" );
   else
   {
      for ( int i = 0; i < bytes->Length; i++ )
         Console::Write( "{0:X2} ", bytes[ i ] );
      Console::WriteLine();
   }
}

/* 
This code produces the following output.

System.Text.UTF7Encoding       : 18  23  :7A 61 2B 41 77 59 42 2F 51 4F 79 32 50 2F 63 2F 77 2D
System.Text.UTF8Encoding       : 12  24  :7A 61 CC 86 C7 BD CE B2 F1 8F B3 BF
System.Text.UnicodeEncoding    : 14  16  :7A 00 61 00 06 03 FD 01 B2 03 FF D8 FF DC
System.Text.UnicodeEncoding    : 14  16  :00 7A 00 61 03 06 01 FD 03 B2 D8 FF DC FF
System.Text.UTF32Encoding      : 24  32  :7A 00 00 00 61 00 00 00 06 03 00 00 FD 01 00 00 B2 03 00 00 FF FC 04 00

*/
using System;
using System.Text;

public class SamplesEncoding  {

   public static void Main()  {

      // The characters to encode:
      //    Latin Small Letter Z (U+007A)
      //    Latin Small Letter A (U+0061)
      //    Combining Breve (U+0306)
      //    Latin Small Letter AE With Acute (U+01FD)
      //    Greek Small Letter Beta (U+03B2)
      //    a high-surrogate value (U+D8FF)
      //    a low-surrogate value (U+DCFF)
      char[] myChars = new char[] { 'z', 'a', '\u0306', '\u01FD', '\u03B2', '\uD8FF', '\uDCFF' };

      // Get different encodings.
      Encoding  u7    = Encoding.UTF7;
      Encoding  u8    = Encoding.UTF8;
      Encoding  u16LE = Encoding.Unicode;
      Encoding  u16BE = Encoding.BigEndianUnicode;
      Encoding  u32   = Encoding.UTF32;

      // Encode the entire array, and print out the counts and the resulting bytes.
      PrintCountsAndBytes( myChars, u7 );
      PrintCountsAndBytes( myChars, u8 );
      PrintCountsAndBytes( myChars, u16LE );
      PrintCountsAndBytes( myChars, u16BE );
      PrintCountsAndBytes( myChars, u32 );
   }

   public static void PrintCountsAndBytes( char[] chars, Encoding enc )  {

      // Display the name of the encoding used.
      Console.Write( "{0,-30} :", enc.ToString() );

      // Display the exact byte count.
      int iBC  = enc.GetByteCount( chars );
      Console.Write( " {0,-3}", iBC );

      // Display the maximum byte count.
      int iMBC = enc.GetMaxByteCount( chars.Length );
      Console.Write( " {0,-3} :", iMBC );

      // Encode the array of chars.
      byte[] bytes = enc.GetBytes( chars );

      // Display all the encoded bytes.
      PrintHexBytes( bytes );
   }

   public static void PrintHexBytes( byte[] bytes )  {

      if (( bytes == null ) || ( bytes.Length == 0 ))
        {
            Console.WriteLine( "<none>" );
        }
        else  {
         for ( int i = 0; i < bytes.Length; i++ )
            Console.Write( "{0:X2} ", bytes[i] );
         Console.WriteLine();
      }
   }
}


/* 
This code produces the following output.

System.Text.UTF7Encoding       : 18  23  :7A 61 2B 41 77 59 42 2F 51 4F 79 32 50 2F 63 2F 77 2D
System.Text.UTF8Encoding       : 12  24  :7A 61 CC 86 C7 BD CE B2 F1 8F B3 BF
System.Text.UnicodeEncoding    : 14  16  :7A 00 61 00 06 03 FD 01 B2 03 FF D8 FF DC
System.Text.UnicodeEncoding    : 14  16  :00 7A 00 61 03 06 01 FD 03 B2 D8 FF DC FF
System.Text.UTF32Encoding      : 24  32  :7A 00 00 00 61 00 00 00 06 03 00 00 FD 01 00 00 B2 03 00 00 FF FC 04 00

*/
Imports System.Text

Public Class SamplesEncoding   

   Public Shared Sub Main()

      ' The characters to encode:
      '    Latin Small Letter Z (U+007A)
      '    Latin Small Letter A (U+0061)
      '    Combining Breve (U+0306)
      '    Latin Small Letter AE With Acute (U+01FD)
      '    Greek Small Letter Beta (U+03B2)
      '    a high-surrogate value (U+D8FF)
      '    a low-surrogate value (U+DCFF)
      Dim myChars() As Char = {"z"c, "a"c, ChrW(&H0306), ChrW(&H01FD), ChrW(&H03B2), ChrW(&HD8FF), ChrW(&HDCFF)}
 

      ' Get different encodings.
      Dim u7 As Encoding = Encoding.UTF7
      Dim u8 As Encoding = Encoding.UTF8
      Dim u16LE As Encoding = Encoding.Unicode
      Dim u16BE As Encoding = Encoding.BigEndianUnicode
      Dim u32 As Encoding = Encoding.UTF32

      ' Encode the entire array, and print out the counts and the resulting bytes.
      PrintCountsAndBytes(myChars, u7)
      PrintCountsAndBytes(myChars, u8)
      PrintCountsAndBytes(myChars, u16LE)
      PrintCountsAndBytes(myChars, u16BE)
      PrintCountsAndBytes(myChars, u32)

   End Sub


   Public Shared Sub PrintCountsAndBytes(chars() As Char, enc As Encoding)

      ' Display the name of the encoding used.
      Console.Write("{0,-30} :", enc.ToString())

      ' Display the exact byte count.
      Dim iBC As Integer = enc.GetByteCount(chars)
      Console.Write(" {0,-3}", iBC)

      ' Display the maximum byte count.
      Dim iMBC As Integer = enc.GetMaxByteCount(chars.Length)
      Console.Write(" {0,-3} :", iMBC)

      ' Encode the array of chars.
      Dim bytes As Byte() = enc.GetBytes(chars)

      ' Display all the encoded bytes.
      PrintHexBytes(bytes)

   End Sub


   Public Shared Sub PrintHexBytes(bytes() As Byte)

      If bytes Is Nothing OrElse bytes.Length = 0 Then
         Console.WriteLine("<none>")
      Else
         Dim i As Integer
         For i = 0 To bytes.Length - 1
            Console.Write("{0:X2} ", bytes(i))
         Next i
         Console.WriteLine()
      End If

   End Sub

End Class


'This code produces the following output.
'
'System.Text.UTF7Encoding       : 18  23  :7A 61 2B 41 77 59 42 2F 51 4F 79 32 50 2F 63 2F 77 2D
'System.Text.UTF8Encoding       : 12  24  :7A 61 CC 86 C7 BD CE B2 F1 8F B3 BF
'System.Text.UnicodeEncoding    : 14  16  :7A 00 61 00 06 03 FD 01 B2 03 FF D8 FF DC
'System.Text.UnicodeEncoding    : 14  16  :00 7A 00 61 03 06 01 FD 03 B2 D8 FF DC FF
'System.Text.UTF32Encoding      : 24  32  :7A 00 00 00 61 00 00 00 06 03 00 00 FD 01 00 00 B2 03 00 00 FF FC 04 00

Comentários

O charCount parâmetro, na verdade, especifica o número de Char objetos que representam os caracteres Unicode a serem codificados, pois o .NET usa o UTF-16 internamente para representar caracteres Unicode.The charCount parameter actually specifies the number of Char objects that represent the Unicode characters to encode, because .NET internally uses UTF-16 to represent Unicode characters. Consequentemente, a maioria dos caracteres Unicode pode ser representada por um Char objeto, mas um caractere Unicode representado por um par alternativo, por exemplo, requer dois Char objetos.Consequently, most Unicode characters can be represented by one Char object, but a Unicode character represented by a surrogate pair, for example, requires two Char objects.

Para calcular o tamanho exato da matriz exigido pelo GetBytes para armazenar os bytes resultantes, você deve usar o GetByteCount método.To calculate the exact array size required by GetBytes to store the resulting bytes, you should use the GetByteCount method. Para calcular o tamanho máximo da matriz, use o GetMaxByteCount método.To calculate the maximum array size, use the GetMaxByteCount method. O GetByteCount método geralmente permite a alocação de menos memória, enquanto o GetMaxByteCount método geralmente é executado mais rapidamente.The GetByteCount method generally allows allocation of less memory, while the GetMaxByteCount method generally executes faster.

GetMaxByteCountRecupera um número pior, incluindo a pior hipótese para o selecionado no momento EncoderFallback .GetMaxByteCount retrieves a worst-case number, including the worst case for the currently selected EncoderFallback. Se um fallback for escolhido com uma cadeia de caracteres potencialmente grande, GetMaxByteCount o recuperará valores grandes, especialmente em casos em que a pior hipótese da codificação envolve a alternância de modos para cada caractere.If a fallback is chosen with a potentially large string, GetMaxByteCount retrieves large values, particularly in cases where the worst case for the encoding involves switching modes for every character. Por exemplo, isso pode ocorrer para ISO-2022-JP.For example, this can happen for ISO-2022-JP. Para obter mais informações, consulte a postagem no blog "o que é com Encoding. GetMaxByteCount () e Encoding. GetMaxCharCount ()?.For more information, see the blog post "What's with Encoding.GetMaxByteCount() and Encoding.GetMaxCharCount()?.

Na maioria dos casos, esse método recupera valores razoáveis para cadeias de caracteres pequenas.In most cases, this method retrieves reasonable values for small strings. Para cadeias de caracteres grandes, talvez seja necessário escolher entre o uso de buffers muito grandes e a captura de erros no caso raro, quando um buffer mais razoável for muito pequeno.For large strings, you might have to choose between using very large buffers and catching errors in the rare case when a more reasonable buffer is too small. Talvez você também queira considerar uma abordagem diferente usando o GetByteCount ou o Encoder.Convert .You might also want to consider a different approach using GetByteCount or Encoder.Convert.

Ao usar GetMaxByteCount o, você deve alocar o buffer de saída com base no tamanho máximo do buffer de entrada.When using GetMaxByteCount, you should allocate the output buffer based on the maximum size of the input buffer. Se o buffer de saída for restrito em tamanho, você poderá usar o Convert método.If the output buffer is constrained in size, you might use the Convert method.

Observe que GetMaxByteCount o considera substitutos restantes em potencial de uma operação de decodificador anterior.Note that GetMaxByteCount considers potential leftover surrogates from a previous decoder operation. Devido ao decodificador, passar um valor de 1 para o método recupera 2 para uma codificação de byte único, como ASCII.Because of the decoder, passing a value of 1 to the method retrieves 2 for a single-byte encoding, such as ASCII. Você deve usar a IsSingleByte propriedade se essas informações forem necessárias.You should use the IsSingleByte property if this information is necessary.

Observação

GetMaxByteCount(N)Não é necessariamente o mesmo valor que N* GetMaxByteCount(1) .GetMaxByteCount(N) is not necessarily the same value as N* GetMaxByteCount(1).

Notas aos Implementadores

Todas as Encoding implementações devem garantir que nenhuma exceção de estouro de buffer ocorra se os buffers forem dimensionados de acordo com os resultados dos cálculos desse método.All Encoding implementations must guarantee that no buffer overflow exceptions occur if buffers are sized according to the results of this method's calculations.

Aplica-se a

Confira também