Encoding.GetBytes メソッド

定義

名前空間:

System.Text

アセンブリ:

mscorlib.dll

派生クラスでオーバーライドされると、文字のセットをバイト シーケンスにエンコードします。

オーバーロード

名前	説明
GetBytes(Char[])	派生クラスでオーバーライドされると、指定した文字配列内のすべての文字をバイト シーケンスにエンコードします。
GetBytes(String)	派生クラスでオーバーライドされると、指定した文字列内のすべての文字をバイト シーケンスにエンコードします。
GetBytes(Char[], Int32, Int32)	派生クラスでオーバーライドされると、指定した文字配列の文字セットをバイトシーケンスにエンコードします。
GetBytes(Char*, Int32, Byte*, Int32)	派生クラスでオーバーライドされると、指定した文字ポインターから始まる一連の文字を、指定したバイト ポインターから始めて格納されるバイトシーケンスにエンコードします。
GetBytes(Char[], Int32, Int32, Byte[], Int32)	派生クラスでオーバーライドされると、指定した文字配列の文字セットを、指定したバイト配列にエンコードします。
GetBytes(String, Int32, Int32, Byte[], Int32)	派生クラスでオーバーライドされると、指定した文字列から指定したバイト配列に一連の文字をエンコードします。

GetBytes(Char[])

派生クラスでオーバーライドされると、指定した文字配列内のすべての文字をバイト シーケンスにエンコードします。

public:
 virtual cli::array <System::Byte> ^ GetBytes(cli::array <char> ^ chars);

public virtual byte[] GetBytes(char[] chars);

abstract member GetBytes : char[] -> byte[]
override this.GetBytes : char[] -> byte[]

Public Overridable Function GetBytes (chars As Char()) As Byte()

パラメーター

chars

Char[]

エンコードする文字を含む文字配列。

返品

Byte[]

指定した文字セットをエンコードした結果を含むバイト配列。

例外

ArgumentNullException

chars は nullです。

EncoderFallbackException

フォールバックが発生しました (詳細については、「 .NET での文字エンコード」を参照してください)

および

EncoderFallback は EncoderExceptionFallback に設定されます。

例

次の例では、文字配列をエンコードするために必要なバイト数を決定し、文字をエンコードして、結果のバイトを表示します。

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

注釈

変換するデータが連続したブロックでのみ使用できる場合 (ストリームから読み取られるデータなど)、またはデータの量が非常に大きくて小さいブロックに分割する必要がある場合は、派生クラスの Decoder メソッドまたは Encoder メソッドによって提供されるGetDecoderまたはGetEncoderをそれぞれ使用する必要があります。

GetByteCountメソッドは、Unicode 文字のセットをエンコードする結果のバイト数を決定し、GetBytes メソッドは実際のエンコードを実行します。 GetBytes メソッドでは、1 つの入力ストリームで複数の変換を処理する Encoder.GetBytes メソッドとは異なり、個別の変換が必要です。

複数のバージョンの GetByteCount と GetBytes がサポートされています。 これらのメソッドの使用に関するプログラミング上の考慮事項を次に示します。

• アプリでは、コード ページに多くの入力文字をエンコードし、複数の呼び出しを使用して文字を処理する必要がある場合があります。 この場合は、使用されている Encoder オブジェクトによって保持される状態を考慮して、呼び出し間の状態を維持する必要がある可能性があります。 (たとえば、サロゲート ペアを含む文字シーケンスは、上位サロゲートで終わる場合があります。 Encoder は、次の呼び出しの開始時に低サロゲートと組み合わせることができるように、高いサロゲートを覚えています。 Encoding は状態を維持できないため、文字は EncoderFallbackに送信されます)。

• アプリが文字列入力を処理する場合は、 GetBytes メソッドの文字列バージョンを呼び出す必要があります。

• GetBytes(Char*, Int32, Byte*, Int32)の Unicode 文字バッファー バージョンを使用すると、特に、Encoder オブジェクトを使用して複数の呼び出しを行ったり、既存のバッファーに挿入したりして、いくつかの高速な手法を使用できます。 ただし、ポインターが必要なため、このメソッドバージョンは安全でない場合があることに注意してください。

• アプリで大量のデータを変換する必要がある場合は、出力バッファーを再利用する必要があります。 この場合、バイト配列をサポートする GetBytes バージョンが最適な選択肢です。

• GetByteCountの代わりにEncoder.Convertメソッドを使用することを検討してください。 変換メソッドは可能な限り多くのデータを変換し、出力バッファーが小さすぎる場合は例外をスローします。 ストリームの連続エンコードでは、多くの場合、この方法が最適な選択肢です。

こちらもご覧ください

• GetEncoder()
• GetByteCount(Char[])
• GetMaxByteCount(Int32)

GetBytes(String)

派生クラスでオーバーライドされると、指定した文字列内のすべての文字をバイト シーケンスにエンコードします。

public:
 virtual cli::array <System::Byte> ^ GetBytes(System::String ^ s);

public virtual byte[] GetBytes(string s);

abstract member GetBytes : string -> byte[]
override this.GetBytes : string -> byte[]

Public Overridable Function GetBytes (s As String) As Byte()

パラメーター

s

String

エンコードする文字を含む文字列。

返品

Byte[]

指定した文字セットをエンコードした結果を含むバイト配列。

例外

ArgumentNullException

s は nullです。

EncoderFallbackException

フォールバックが発生しました (詳細については、「 .NET での文字エンコード」を参照してください)

および

EncoderFallback は EncoderExceptionFallback に設定されます。

例

次の例では、文字列または文字列内の範囲をエンコードするために必要なバイト数を決定し、文字をエンコードして、結果のバイトを表示します。

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)
      String myStr = "za\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 string, and print out the counts and the resulting bytes.
      Console.WriteLine( "Encoding the entire string:" );
      PrintCountsAndBytes( myStr, u7 );
      PrintCountsAndBytes( myStr, u8 );
      PrintCountsAndBytes( myStr, u16LE );
      PrintCountsAndBytes( myStr, u16BE );
      PrintCountsAndBytes( myStr, u32 );

      Console.WriteLine();

      // Encode three characters starting at index 4, and print out the counts and the resulting bytes.
      Console.WriteLine( "Encoding the characters from index 4 through 6:" );
      PrintCountsAndBytes( myStr, 4, 3, u7 );
      PrintCountsAndBytes( myStr, 4, 3, u8 );
      PrintCountsAndBytes( myStr, 4, 3, u16LE );
      PrintCountsAndBytes( myStr, 4, 3, u16BE );
      PrintCountsAndBytes( myStr, 4, 3, u32 );
   }

   public static void PrintCountsAndBytes( String s, Encoding enc )  {

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

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

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

      // Encode the entire string.
      byte[] bytes = enc.GetBytes( s );

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

   public static void PrintCountsAndBytes( String s, int index, int count, Encoding enc )  {

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

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

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

      // Encode a range of characters in the string.
      byte[] bytes = new byte[iBC];
      enc.GetBytes( s, index, count, bytes, bytes.GetLowerBound(0) );

      // 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.

Encoding the entire string:
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

Encoding the characters from index 4 through 6:
System.Text.UTF7Encoding       : 10  11  :2B 41 37 4C 59 2F 39 7A 2F 2D
System.Text.UTF8Encoding       : 6   12  :CE B2 F1 8F B3 BF
System.Text.UnicodeEncoding    : 6   8   :B2 03 FF D8 FF DC
System.Text.UnicodeEncoding    : 6   8   :03 B2 D8 FF DC FF
System.Text.UTF32Encoding      : 8   16  :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 myStr As String = "za" & 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 string, and print out the counts and the resulting bytes.
      Console.WriteLine("Encoding the entire string:")
      PrintCountsAndBytes(myStr, u7)
      PrintCountsAndBytes(myStr, u8)
      PrintCountsAndBytes(myStr, u16LE)
      PrintCountsAndBytes(myStr, u16BE)
      PrintCountsAndBytes(myStr, u32)

      Console.WriteLine()

      ' Encode three characters starting at index 4, and print out the counts and the resulting bytes.
      Console.WriteLine("Encoding the characters from index 4 through 6:")
      PrintCountsAndBytes(myStr, 4, 3, u7)
      PrintCountsAndBytes(myStr, 4, 3, u8)
      PrintCountsAndBytes(myStr, 4, 3, u16LE)
      PrintCountsAndBytes(myStr, 4, 3, u16BE)
      PrintCountsAndBytes(myStr, 4, 3, u32)

   End Sub


   Overloads Public Shared Sub PrintCountsAndBytes(s As String, 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(s)
      Console.Write(" {0,-3}", iBC)

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

      ' Encode the entire string.
      Dim bytes As Byte() = enc.GetBytes(s)

      ' Display all the encoded bytes.
      PrintHexBytes(bytes)

   End Sub


   Overloads Public Shared Sub PrintCountsAndBytes(s As String, index As Integer, count As Integer, 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(s.ToCharArray(), index, count)
      Console.Write(" {0,-3}", iBC)

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

      ' Encode a range of characters in the string.
      ' NOTE: In VB.NET, arrays contain one extra element by default.
      '       The following line creates the array with the exact number of elements required.
      Dim bytes(iBC - 1) As Byte
      enc.GetBytes(s, index, count, bytes, bytes.GetLowerBound(0))

      ' 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.
'
'Encoding the entire string:
'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
'
'Encoding the characters from index 4 through 6:
'System.Text.UTF7Encoding       : 10  11  :2B 41 37 4C 59 2F 39 7A 2F 2D
'System.Text.UTF8Encoding       : 6   12  :CE B2 F1 8F B3 BF
'System.Text.UnicodeEncoding    : 6   8   :B2 03 FF D8 FF DC
'System.Text.UnicodeEncoding    : 6   8   :03 B2 D8 FF DC FF
'System.Text.UTF32Encoding      : 8   16  :B2 03 00 00 FF FC 04 00

注釈

変換するデータが連続したブロックでのみ使用できる場合 (ストリームから読み取られるデータなど)、またはデータの量が非常に大きくて小さいブロックに分割する必要がある場合は、派生クラスの Decoder メソッドまたは Encoder メソッドによって提供されるGetDecoderまたはGetEncoderをそれぞれ使用する必要があります。

GetByteCountメソッドは、Unicode 文字のセットをエンコードする結果のバイト数を決定し、GetBytes メソッドは実際のエンコードを実行します。 Encoding.GetBytes メソッドでは、1 つの入力ストリームで複数の変換を処理する Encoder.GetBytes メソッドとは異なり、個別の変換が必要です。

複数のバージョンの GetByteCount と GetBytes がサポートされています。 これらのメソッドの使用に関するプログラミング上の考慮事項を次に示します。

• アプリでは、コード ページに多くの入力文字をエンコードし、複数の呼び出しを使用して文字を処理する必要がある場合があります。 この場合は、使用されている Encoder オブジェクトによって保持される状態を考慮して、呼び出し間の状態を維持する必要がある可能性があります。 (たとえば、サロゲート ペアを含む文字シーケンスは、上位サロゲートで終わる場合があります。 Encoder は、次の呼び出しの開始時に低サロゲートと組み合わせることができるように、高いサロゲートを覚えています。 Encoding は状態を維持できないため、文字は EncoderFallbackに送信されます)。

• アプリが文字列入力を処理する場合は、文字列バージョンの GetBytesを使用する必要があります。

• GetBytes(Char*, Int32, Byte*, Int32)の Unicode 文字バッファー バージョンを使用すると、特に、Encoder オブジェクトを使用して複数の呼び出しを行ったり、既存のバッファーに挿入したりして、いくつかの高速な手法を使用できます。 ただし、ポインターが必要なため、このメソッドバージョンは安全でない場合があることに注意してください。

• アプリで大量のデータを変換する必要がある場合は、出力バッファーを再利用する必要があります。 この場合、バイト配列をサポートする GetBytes バージョンが最適な選択肢です。

• GetByteCountの代わりにEncoder.Convertメソッドを使用することを検討してください。 変換メソッドは可能な限り多くのデータを変換し、出力バッファーが小さすぎる場合は例外をスローします。 ストリームの連続エンコードでは、多くの場合、この方法が最適な選択肢です。

こちらもご覧ください

• GetEncoder()
• GetByteCount(Char[])
• GetMaxByteCount(Int32)

GetBytes(Char[], Int32, Int32)

派生クラスでオーバーライドされると、指定した文字配列の文字セットをバイトシーケンスにエンコードします。

public:
 virtual cli::array <System::Byte> ^ GetBytes(cli::array <char> ^ chars, int index, int count);

public virtual byte[] GetBytes(char[] chars, int index, int count);

abstract member GetBytes : char[] * int * int -> byte[]
override this.GetBytes : char[] * int * int -> byte[]

Public Overridable Function GetBytes (chars As Char(), index As Integer, count As Integer) As Byte()

パラメーター

chars

Char[]

エンコードする文字のセットを含む文字配列。

index

Int32

エンコードする最初の文字のインデックス。

count

Int32

エンコードする文字数。

返品

Byte[]

指定した文字セットをエンコードした結果を含むバイト配列。

例外

ArgumentNullException

chars は nullです。

ArgumentOutOfRangeException

index または count が 0 未満です。

-または-

index および count は、 chars内の有効な範囲を示していません。

EncoderFallbackException

フォールバックが発生しました (詳細については、「 .NET での文字エンコード」を参照してください)

および

EncoderFallback は EncoderExceptionFallback に設定されます。

例

次の例では、文字配列から 3 文字をエンコードするために必要なバイト数を決定し、文字をエンコードして、結果のバイトを表示します。

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 three characters starting at index 4, and print out the counts and the resulting bytes.
      PrintCountsAndBytes( myChars, 4, 3, u7 );
      PrintCountsAndBytes( myChars, 4, 3, u8 );
      PrintCountsAndBytes( myChars, 4, 3, u16LE );
      PrintCountsAndBytes( myChars, 4, 3, u16BE );
      PrintCountsAndBytes( myChars, 4, 3, u32 );
   }

   public static void PrintCountsAndBytes( char[] chars, int index, int count, 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, index, count );
      Console.Write( " {0,-3}", iBC );

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

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

      // The following is an alternative way to encode the array of chars:
      // byte[] bytes = new byte[iBC];
      // enc.GetBytes( chars, index, count, bytes, bytes.GetLowerBound(0) );

      // 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       : 10  11  :2B 41 37 4C 59 2F 39 7A 2F 2D
System.Text.UTF8Encoding       : 6   12  :CE B2 F1 8F B3 BF
System.Text.UnicodeEncoding    : 6   8   :B2 03 FF D8 FF DC
System.Text.UnicodeEncoding    : 6   8   :03 B2 D8 FF DC FF
System.Text.UTF32Encoding      : 8   16  :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 three characters starting at index 4, and print out the counts and the resulting bytes.
      PrintCountsAndBytes(myChars, 4, 3, u7)
      PrintCountsAndBytes(myChars, 4, 3, u8)
      PrintCountsAndBytes(myChars, 4, 3, u16LE)
      PrintCountsAndBytes(myChars, 4, 3, u16BE)
      PrintCountsAndBytes(myChars, 4, 3, u32)

   End Sub


   Public Shared Sub PrintCountsAndBytes(chars() As Char, index As Integer, count As Integer, 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, index, count)
      Console.Write(" {0,-3}", iBC)

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

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

      ' The following is an alternative way to encode the array of chars:
      ' NOTE: In VB.NET, arrays contain one extra element by default.
      '       The following line creates the array with the exact number of elements required.
      ' Dim bytes(iBC - 1) As Byte
      ' enc.GetBytes( chars, index, count, bytes, bytes.GetLowerBound(0) )

      ' 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       : 10  11  :2B 41 37 4C 59 2F 39 7A 2F 2D
'System.Text.UTF8Encoding       : 6   12  :CE B2 F1 8F B3 BF
'System.Text.UnicodeEncoding    : 6   8   :B2 03 FF D8 FF DC
'System.Text.UnicodeEncoding    : 6   8   :03 B2 D8 FF DC FF
'System.Text.UTF32Encoding      : 8   16  :B2 03 00 00 FF FC 04 00

注釈

変換するデータが連続したブロックでのみ使用できる場合 (ストリームから読み取られるデータなど)、またはデータの量が非常に大きくて小さいブロックに分割する必要がある場合は、派生クラスの Decoder メソッドまたは Encoder メソッドによって提供されるGetDecoderまたはGetEncoderをそれぞれ使用する必要があります。

GetByteCountメソッドは、Unicode 文字のセットをエンコードする結果のバイト数を決定し、GetBytes メソッドは実際のエンコードを実行します。 Encoding.GetBytes メソッドでは、1 つの入力ストリームで複数の変換を処理する Encoder.GetBytes メソッドとは異なり、個別の変換が必要です。

複数のバージョンの GetByteCount と GetBytes がサポートされています。 これらのメソッドの使用に関するプログラミング上の考慮事項を次に示します。

• アプリでは、コード ページに多くの入力文字をエンコードし、複数の呼び出しを使用して文字を処理する必要がある場合があります。 この場合は、使用されている Encoder オブジェクトによって保持される状態を考慮して、呼び出し間の状態を維持する必要がある可能性があります。 (たとえば、サロゲート ペアを含む文字シーケンスは、上位サロゲートで終わる場合があります。 Encoder は、次の呼び出しの開始時に低サロゲートと組み合わせることができるように、高いサロゲートを覚えています。 Encoding は状態を維持できないため、文字は EncoderFallbackに送信されます)。

• アプリが文字列入力を処理する場合は、文字列バージョンの GetBytesを使用する必要があります。

• GetBytes(Char*, Int32, Byte*, Int32)の Unicode 文字バッファー バージョンを使用すると、特に、Encoder オブジェクトを使用して複数の呼び出しを行ったり、既存のバッファーに挿入したりして、いくつかの高速な手法を使用できます。 ただし、ポインターが必要なため、このメソッドバージョンは安全でない場合があることに注意してください。

• アプリで大量のデータを変換する必要がある場合は、出力バッファーを再利用する必要があります。 この場合、バイト配列をサポートする GetBytes バージョンが最適な選択肢です。

• GetByteCountの代わりにEncoder.Convertメソッドを使用することを検討してください。 変換メソッドは可能な限り多くのデータを変換し、出力バッファーが小さすぎる場合は例外をスローします。 ストリームの連続エンコードでは、多くの場合、この方法が最適な選択肢です。

こちらもご覧ください

• GetEncoder()
• GetByteCount(Char[])
• GetMaxByteCount(Int32)

GetBytes(Char*, Int32, Byte*, Int32)

重要

この API は CLS 準拠ではありません。

派生クラスでオーバーライドされると、指定した文字ポインターから始まる一連の文字を、指定したバイト ポインターから始めて格納されるバイトシーケンスにエンコードします。

public:
 virtual int GetBytes(char* chars, int charCount, System::Byte* bytes, int byteCount);

[System.CLSCompliant(false)]
[System.Security.SecurityCritical]
[System.Runtime.InteropServices.ComVisible(false)]
public virtual int GetBytes(char* chars, int charCount, byte* bytes, int byteCount);

[<System.CLSCompliant(false)>]
[<System.Security.SecurityCritical>]
[<System.Runtime.InteropServices.ComVisible(false)>]
abstract member GetBytes : nativeptr<char> * int * nativeptr<byte> * int -> int
override this.GetBytes : nativeptr<char> * int * nativeptr<byte> * int -> int

パラメーター

chars

Char*

エンコードする最初の文字へのポインター。

charCount

Int32

エンコードする文字数。

bytes

Byte*

結果のバイト シーケンスの書き込みを開始する位置へのポインター。

byteCount

Int32

書き込む最大バイト数。

返品

Int32

bytes パラメーターによって示される場所に書き込まれた実際のバイト数。

属性

CLSCompliantAttribute SecurityCriticalAttribute ComVisibleAttribute

例外

ArgumentNullException

chars は nullです。

-または-

bytes は nullです。

ArgumentOutOfRangeException

charCount または byteCount が 0 未満です。

ArgumentException

byteCount が結果のバイト数より小さい。

EncoderFallbackException

フォールバックが発生しました (詳細については、「 .NET での文字エンコード」を参照してください)

および

EncoderFallback は EncoderExceptionFallback に設定されます。

注釈

結果のバイト GetBytes 格納するために必要な正確な配列サイズを計算するには、 GetByteCount メソッドを呼び出します。 配列の最大サイズを計算するには、 GetMaxByteCount メソッドを呼び出します。 一般に、 GetByteCount メソッドではメモリの割り当てが少なくなりますが、 GetMaxByteCount メソッドの実行速度は一般的に速くなります。

変換するデータがシーケンシャル ブロックでのみ使用できる場合 (ストリームから読み取られるデータなど)、またはデータの量が非常に大きくて小さいブロックに分割する必要がある場合は、派生クラスのGetDecoderまたはGetEncoder メソッドによって提供されるDecoderまたはEncoder オブジェクトをそれぞれ使用する必要があります。

GetByteCountメソッドは、Unicode 文字のセットをエンコードする結果のバイト数を決定し、GetBytes メソッドは実際のエンコードを実行します。 GetBytes メソッドでは、1 つの入力ストリームで複数の変換を処理する Encoder.GetBytes メソッドとは異なり、個別の変換が必要です。

複数のバージョンの GetByteCount と GetBytes がサポートされています。 これらのメソッドの使用に関するプログラミング上の考慮事項を次に示します。

• アプリでは、コード ページに多くの入力文字をエンコードし、複数の呼び出しを使用して文字を処理する必要がある場合があります。 この場合は、使用されている Encoder オブジェクトによって保持される状態を考慮して、呼び出し間の状態を維持する必要がある可能性があります。 (たとえば、サロゲート ペアを含む文字シーケンスは、上位サロゲートで終わる場合があります。 Encoder は、次の呼び出しの開始時に低サロゲートと組み合わせることができるように、高いサロゲートを覚えています。 Encoding は状態を維持できないため、文字は EncoderFallbackに送信されます)。

• アプリが文字列入力を処理する場合は、文字列バージョンの GetBytesを使用する必要があります。

• GetBytes(Char*, Int32, Byte*, Int32)の Unicode 文字バッファー バージョンを使用すると、特に、Encoder オブジェクトを使用して複数の呼び出しを行ったり、既存のバッファーに挿入したりして、いくつかの高速な手法を使用できます。 ただし、ポインターが必要なため、このメソッドバージョンは安全でない場合があることに注意してください。

• アプリで大量のデータを変換する必要がある場合は、出力バッファーを再利用する必要があります。 この場合、バイト配列をサポートする GetBytes バージョンが最適な選択肢です。

• GetByteCountの代わりにEncoder.Convertメソッドを使用することを検討してください。 変換メソッドは可能な限り多くのデータを変換し、出力バッファーが小さすぎる場合は例外をスローします。 ストリームの連続エンコードでは、多くの場合、この方法が最適な選択肢です。

こちらもご覧ください

• GetEncoder()
• GetByteCount(Char[])
• GetMaxByteCount(Int32)

GetBytes(Char[], Int32, Int32, Byte[], Int32)

派生クラスでオーバーライドされると、指定した文字配列の文字セットを、指定したバイト配列にエンコードします。

public:
 abstract int GetBytes(cli::array <char> ^ chars, int charIndex, int charCount, cli::array <System::Byte> ^ bytes, int byteIndex);

public abstract int GetBytes(char[] chars, int charIndex, int charCount, byte[] bytes, int byteIndex);

abstract member GetBytes : char[] * int * int * byte[] * int -> int

Public MustOverride Function GetBytes (chars As Char(), charIndex As Integer, charCount As Integer, bytes As Byte(), byteIndex As Integer) As Integer

パラメーター

chars

Char[]

エンコードする文字のセットを含む文字配列。

charIndex

Int32

エンコードする最初の文字のインデックス。

charCount

Int32

エンコードする文字数。

bytes

Byte[]

結果のバイト シーケンスを格納するバイト配列。

byteIndex

Int32

結果のバイト シーケンスの書き込みを開始する位置のインデックス。

返品

Int32

bytesに書き込まれた実際のバイト数。

例外

ArgumentNullException

chars は nullです。

-または-

bytes は nullです。

ArgumentOutOfRangeException

charIndex または charCount または byteIndex が 0 未満です。

-または-

charIndex および charCount は、 chars内の有効な範囲を示していません。

-または-

byteIndex は、 bytesの有効なインデックスではありません。

ArgumentException

bytes は、結果のバイトに対応するために、 byteIndex から配列の末尾まで十分な容量を持っていません。

EncoderFallbackException

フォールバックが発生しました (詳細については、「 .NET での文字エンコード」を参照してください)

および

EncoderFallback は EncoderExceptionFallback に設定されます。

例

次の例では、文字配列から 3 文字をエンコードするために必要なバイト数を決定し、文字をエンコードして、結果のバイトを表示します。

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 three characters starting at index 4, and print out the counts and the resulting bytes.
      PrintCountsAndBytes( myChars, 4, 3, u7 );
      PrintCountsAndBytes( myChars, 4, 3, u8 );
      PrintCountsAndBytes( myChars, 4, 3, u16LE );
      PrintCountsAndBytes( myChars, 4, 3, u16BE );
      PrintCountsAndBytes( myChars, 4, 3, u32 );
   }

   public static void PrintCountsAndBytes( char[] chars, int index, int count, 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, index, count );
      Console.Write( " {0,-3}", iBC );

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

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

      // The following is an alternative way to encode the array of chars:
      // byte[] bytes = new byte[iBC];
      // enc.GetBytes( chars, index, count, bytes, bytes.GetLowerBound(0) );

      // 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       : 10  11  :2B 41 37 4C 59 2F 39 7A 2F 2D
System.Text.UTF8Encoding       : 6   12  :CE B2 F1 8F B3 BF
System.Text.UnicodeEncoding    : 6   8   :B2 03 FF D8 FF DC
System.Text.UnicodeEncoding    : 6   8   :03 B2 D8 FF DC FF
System.Text.UTF32Encoding      : 8   16  :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 three characters starting at index 4, and print out the counts and the resulting bytes.
      PrintCountsAndBytes(myChars, 4, 3, u7)
      PrintCountsAndBytes(myChars, 4, 3, u8)
      PrintCountsAndBytes(myChars, 4, 3, u16LE)
      PrintCountsAndBytes(myChars, 4, 3, u16BE)
      PrintCountsAndBytes(myChars, 4, 3, u32)

   End Sub


   Public Shared Sub PrintCountsAndBytes(chars() As Char, index As Integer, count As Integer, 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, index, count)
      Console.Write(" {0,-3}", iBC)

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

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

      ' The following is an alternative way to encode the array of chars:
      ' NOTE: In VB.NET, arrays contain one extra element by default.
      '       The following line creates the array with the exact number of elements required.
      ' Dim bytes(iBC - 1) As Byte
      ' enc.GetBytes( chars, index, count, bytes, bytes.GetLowerBound(0) )

      ' 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       : 10  11  :2B 41 37 4C 59 2F 39 7A 2F 2D
'System.Text.UTF8Encoding       : 6   12  :CE B2 F1 8F B3 BF
'System.Text.UnicodeEncoding    : 6   8   :B2 03 FF D8 FF DC
'System.Text.UnicodeEncoding    : 6   8   :03 B2 D8 FF DC FF
'System.Text.UTF32Encoding      : 8   16  :B2 03 00 00 FF FC 04 00

注釈

結果のバイトを格納するために GetBytes に必要な正確な配列サイズを計算するには、 GetByteCount メソッドを呼び出す必要があります。 配列の最大サイズを計算するには、 GetMaxByteCount メソッドを呼び出します。 一般に、 GetByteCount メソッドではメモリの割り当てが少なくなりますが、 GetMaxByteCount メソッドの実行速度は一般的に速くなります。

変換するデータが連続したブロックでのみ使用できる場合 (ストリームから読み取られるデータなど)、またはデータの量が非常に大きくて小さいブロックに分割する必要がある場合は、派生クラスの Decoder メソッドまたは Encoder メソッドによって提供されるGetDecoderまたはGetEncoderをそれぞれ使用する必要があります。

GetByteCountメソッドは、Unicode 文字のセットをエンコードする結果のバイト数を決定し、GetBytes メソッドは実際のエンコードを実行します。 Encoding.GetBytes メソッドでは、1 つの入力ストリームで複数の変換を処理する Encoder.GetBytes メソッドとは異なり、個別の変換が必要です。

複数のバージョンの GetByteCount と GetBytes がサポートされています。 これらのメソッドの使用に関するプログラミング上の考慮事項を次に示します。

• アプリでは、コード ページに多くの入力文字をエンコードし、複数の呼び出しを使用して文字を処理する必要がある場合があります。 この場合は、使用されている Encoder オブジェクトによって保持される状態を考慮して、呼び出し間の状態を維持する必要がある可能性があります。 (たとえば、サロゲート ペアを含む文字シーケンスは、上位サロゲートで終わる場合があります。 Encoder は、次の呼び出しの開始時に低サロゲートと組み合わせることができるように、高いサロゲートを覚えています。 Encoding は状態を維持できないため、文字は EncoderFallbackに送信されます)。

• アプリが文字列入力を処理する場合は、文字列バージョンの GetBytesを使用する必要があります。

• GetBytes(Char*, Int32, Byte*, Int32)の Unicode 文字バッファー バージョンを使用すると、特に、Encoder オブジェクトを使用して複数の呼び出しを行ったり、既存のバッファーに挿入したりして、いくつかの高速な手法を使用できます。 ただし、ポインターが必要なため、このメソッドバージョンは安全でない場合があることに注意してください。

• アプリで大量のデータを変換する必要がある場合は、出力バッファーを再利用する必要があります。 この場合、バイト配列をサポートする GetBytes バージョンが最適な選択肢です。

• GetByteCountの代わりにEncoder.Convertメソッドを使用することを検討してください。 変換メソッドは可能な限り多くのデータを変換し、出力バッファーが小さすぎる場合は例外をスローします。 ストリームの連続エンコードでは、多くの場合、この方法が最適な選択肢です。

こちらもご覧ください

• GetEncoder()
• GetByteCount(Char[])
• GetMaxByteCount(Int32)

GetBytes(String, Int32, Int32, Byte[], Int32)

派生クラスでオーバーライドされると、指定した文字列から指定したバイト配列に一連の文字をエンコードします。

public:
 virtual int GetBytes(System::String ^ s, int charIndex, int charCount, cli::array <System::Byte> ^ bytes, int byteIndex);

public virtual int GetBytes(string s, int charIndex, int charCount, byte[] bytes, int byteIndex);

abstract member GetBytes : string * int * int * byte[] * int -> int
override this.GetBytes : string * int * int * byte[] * int -> int

Public Overridable Function GetBytes (s As String, charIndex As Integer, charCount As Integer, bytes As Byte(), byteIndex As Integer) As Integer

パラメーター

s

String

エンコードする文字のセットを含む文字列。

charIndex

Int32

エンコードする最初の文字のインデックス。

charCount

Int32

エンコードする文字数。

bytes

Byte[]

結果のバイト シーケンスを格納するバイト配列。

byteIndex

Int32

結果のバイト シーケンスの書き込みを開始する位置のインデックス。

返品

Int32

bytesに書き込まれた実際のバイト数。

例外

ArgumentNullException

s は nullです。

-または-

bytes は nullです。

ArgumentOutOfRangeException

charIndex または charCount または byteIndex が 0 未満です。

-または-

charIndex および charCount は、 s内の有効な範囲を示していません。

-または-

byteIndex は、 bytesの有効なインデックスではありません。

ArgumentException

bytes は、結果のバイトに対応するために、 byteIndex から配列の末尾まで十分な容量を持っていません。

EncoderFallbackException

フォールバックが発生しました (詳細については、「 .NET での文字エンコード」を参照してください)

および

EncoderFallback は EncoderExceptionFallback に設定されます。

例

次の例では、文字列または文字列内の範囲をエンコードするために必要なバイト数を決定し、文字をエンコードして、結果のバイトを表示します。

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)
      String myStr = "za\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 string, and print out the counts and the resulting bytes.
      Console.WriteLine( "Encoding the entire string:" );
      PrintCountsAndBytes( myStr, u7 );
      PrintCountsAndBytes( myStr, u8 );
      PrintCountsAndBytes( myStr, u16LE );
      PrintCountsAndBytes( myStr, u16BE );
      PrintCountsAndBytes( myStr, u32 );

      Console.WriteLine();

      // Encode three characters starting at index 4, and print out the counts and the resulting bytes.
      Console.WriteLine( "Encoding the characters from index 4 through 6:" );
      PrintCountsAndBytes( myStr, 4, 3, u7 );
      PrintCountsAndBytes( myStr, 4, 3, u8 );
      PrintCountsAndBytes( myStr, 4, 3, u16LE );
      PrintCountsAndBytes( myStr, 4, 3, u16BE );
      PrintCountsAndBytes( myStr, 4, 3, u32 );
   }

   public static void PrintCountsAndBytes( String s, Encoding enc )  {

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

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

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

      // Encode the entire string.
      byte[] bytes = enc.GetBytes( s );

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

   public static void PrintCountsAndBytes( String s, int index, int count, Encoding enc )  {

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

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

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

      // Encode a range of characters in the string.
      byte[] bytes = new byte[iBC];
      enc.GetBytes( s, index, count, bytes, bytes.GetLowerBound(0) );

      // 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.

Encoding the entire string:
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

Encoding the characters from index 4 through 6:
System.Text.UTF7Encoding       : 10  11  :2B 41 37 4C 59 2F 39 7A 2F 2D
System.Text.UTF8Encoding       : 6   12  :CE B2 F1 8F B3 BF
System.Text.UnicodeEncoding    : 6   8   :B2 03 FF D8 FF DC
System.Text.UnicodeEncoding    : 6   8   :03 B2 D8 FF DC FF
System.Text.UTF32Encoding      : 8   16  :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 myStr As String = "za" & 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 string, and print out the counts and the resulting bytes.
      Console.WriteLine("Encoding the entire string:")
      PrintCountsAndBytes(myStr, u7)
      PrintCountsAndBytes(myStr, u8)
      PrintCountsAndBytes(myStr, u16LE)
      PrintCountsAndBytes(myStr, u16BE)
      PrintCountsAndBytes(myStr, u32)

      Console.WriteLine()

      ' Encode three characters starting at index 4, and print out the counts and the resulting bytes.
      Console.WriteLine("Encoding the characters from index 4 through 6:")
      PrintCountsAndBytes(myStr, 4, 3, u7)
      PrintCountsAndBytes(myStr, 4, 3, u8)
      PrintCountsAndBytes(myStr, 4, 3, u16LE)
      PrintCountsAndBytes(myStr, 4, 3, u16BE)
      PrintCountsAndBytes(myStr, 4, 3, u32)

   End Sub


   Overloads Public Shared Sub PrintCountsAndBytes(s As String, 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(s)
      Console.Write(" {0,-3}", iBC)

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

      ' Encode the entire string.
      Dim bytes As Byte() = enc.GetBytes(s)

      ' Display all the encoded bytes.
      PrintHexBytes(bytes)

   End Sub


   Overloads Public Shared Sub PrintCountsAndBytes(s As String, index As Integer, count As Integer, 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(s.ToCharArray(), index, count)
      Console.Write(" {0,-3}", iBC)

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

      ' Encode a range of characters in the string.
      ' NOTE: In VB.NET, arrays contain one extra element by default.
      '       The following line creates the array with the exact number of elements required.
      Dim bytes(iBC - 1) As Byte
      enc.GetBytes(s, index, count, bytes, bytes.GetLowerBound(0))

      ' 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.
'
'Encoding the entire string:
'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
'
'Encoding the characters from index 4 through 6:
'System.Text.UTF7Encoding       : 10  11  :2B 41 37 4C 59 2F 39 7A 2F 2D
'System.Text.UTF8Encoding       : 6   12  :CE B2 F1 8F B3 BF
'System.Text.UnicodeEncoding    : 6   8   :B2 03 FF D8 FF DC
'System.Text.UnicodeEncoding    : 6   8   :03 B2 D8 FF DC FF
'System.Text.UTF32Encoding      : 8   16  :B2 03 00 00 FF FC 04 00

注釈

結果のバイトを格納するために GetBytes に必要な正確な配列サイズを計算するには、 GetByteCount メソッドを呼び出す必要があります。 配列の最大サイズを計算するには、 GetMaxByteCount メソッドを呼び出します。 一般に、 GetByteCount メソッドではメモリの割り当てが少なくなりますが、 GetMaxByteCount メソッドの実行速度は一般的に速くなります。

変換するデータが連続したブロックでのみ使用できる場合 (ストリームから読み取られるデータなど)、またはデータの量が非常に大きくて小さいブロックに分割する必要がある場合は、派生クラスの Decoder メソッドまたは Encoder メソッドによって提供されるGetDecoderまたはGetEncoderをそれぞれ使用する必要があります。

GetByteCountメソッドは、Unicode 文字のセットをエンコードする結果のバイト数を決定し、GetBytes メソッドは実際のエンコードを実行します。 Encoding.GetBytes メソッドでは、1 つの入力ストリームで複数の変換を処理する Encoder.GetBytes メソッドとは異なり、個別の変換が必要です。

複数のバージョンの GetByteCount と GetBytes がサポートされています。 これらのメソッドの使用に関するプログラミング上の考慮事項を次に示します。

• アプリでは、コード ページに多くの入力文字をエンコードし、複数の呼び出しを使用して文字を処理する必要がある場合があります。 この場合は、使用されている Encoder オブジェクトによって保持される状態を考慮して、呼び出し間の状態を維持する必要がある可能性があります。 (たとえば、サロゲート ペアを含む文字シーケンスは、上位サロゲートで終わる場合があります。 Encoder は、次の呼び出しの開始時に低サロゲートと組み合わせることができるように、高いサロゲートを覚えています。 Encoding は状態を維持できないため、文字は EncoderFallbackに送信されます)。

• アプリが文字列入力を処理する場合は、文字列バージョンの GetBytesを使用する必要があります。

• GetBytes(Char*, Int32, Byte*, Int32)の Unicode 文字バッファー バージョンを使用すると、特に、Encoder オブジェクトを使用して複数の呼び出しを行ったり、既存のバッファーに挿入したりして、いくつかの高速な手法を使用できます。 ただし、ポインターが必要なため、このメソッドバージョンは安全でない場合があることに注意してください。

• アプリで大量のデータを変換する必要がある場合は、出力バッファーを再利用する必要があります。 この場合、バイト配列をサポートする GetBytes バージョンが最適な選択肢です。

• GetByteCountの代わりにEncoder.Convertメソッドを使用することを検討してください。 変換メソッドは可能な限り多くのデータを変換し、出力バッファーが小さすぎる場合は例外をスローします。 ストリームの連続エンコードでは、多くの場合、この方法が最適な選択肢です。

こちらもご覧ください

• GetEncoder()
• GetByteCount(Char[])
• GetMaxByteCount(Int32)