UTF32Encoding.GetChars 메서드

정의

네임스페이스:

System.Text

어셈블리:

System.Text.Encoding.Extensions.dll

바이트 시퀀스를 문자 집합으로 디코딩합니다.

오버로드

GetChars(Byte*, Int32, Char*, Int32)	지정한 바이트 포인터에서 시작하는 바이트 시퀀스를 지정한 문자 포인터에서 시작하여 저장되는 문자 집합으로 디코딩합니다.
GetChars(Byte[], Int32, Int32, Char[], Int32)	지정한 바이트 배열의 바이트 시퀀스를 지정한 문자 배열로 디코딩합니다.

GetChars(Byte*, Int32, Char*, Int32)

Source:

UTF32Encoding.cs

중요

이 API는 CLS 규격이 아닙니다.

지정한 바이트 포인터에서 시작하는 바이트 시퀀스를 지정한 문자 포인터에서 시작하여 저장되는 문자 집합으로 디코딩합니다.

public:
 override int GetChars(System::Byte* bytes, int byteCount, char* chars, int charCount);

[System.CLSCompliant(false)]
public override int GetChars (byte* bytes, int byteCount, char* chars, int charCount);

[<System.CLSCompliant(false)>]
override this.GetChars : nativeptr<byte> * int * nativeptr<char> * int -> int

매개 변수

bytes

Byte*

디코딩할 첫 번째 바이트를 가리키는 포인터입니다.

byteCount

Int32

디코딩할 바이트 수입니다.

chars

Char*

결과 문자 집합을 쓰기 시작할 위치를 가리키는 포인터입니다.

charCount

Int32

쓸 최대 문자 수입니다.

반환

Int32

chars가 가리키는 위치에 써지는 실제 문자 수입니다.

특성

CLSCompliantAttribute

예외

ArgumentNullException

bytes은 null입니다.

또는

chars은 null입니다.

ArgumentOutOfRangeException

byteCount 또는 charCount가 0보다 작습니다.

ArgumentException

오류 검색이 사용되고 bytes에 잘못된 바이트 시퀀스를 포함합니다.

또는

charCount가 결과 문자 수보다 작은 경우

DecoderFallbackException

대체가 발생했습니다(자세한 내용은 .NET의 문자 인코딩 참조).

및

DecoderFallback이 DecoderExceptionFallback로 설정됩니다.

설명

결과 문자를 저장하는 데 필요한 GetChars 정확한 배열 크기를 계산하려면 메서드를 호출합니다 GetCharCount . 최대 배열 크기를 계산 하려면 메서드를 호출 GetMaxCharCount 합니다. 메서드는 GetCharCount 일반적으로 메모리를 적게 할당하지만 메서드는 GetMaxCharCount 일반적으로 더 빠르게 실행됩니다.

오류 검색을 사용하면 잘못된 시퀀스로 인해 이 메서드가 을 throw합니다 ArgumentException. 오류 검색이 없으면 잘못된 시퀀스가 무시되고 예외가 throw되지 않습니다.

디코딩할 바이트 범위에 BOM(바이트 순서 표시)이 포함되고 바이트 배열이 BOM 인식이 아닌 형식의 메서드에 의해 반환된 경우 U+FFFE 문자는 이 메서드에서 반환된 문자 배열에 포함됩니다. 메서드를 호출 String.TrimStart 하여 제거할 수 있습니다.

스트림에서 읽은 데이터와 같이 변환할 데이터는 순차적 블록에서만 사용할 수 있습니다. 이 경우 애플리케이션에서는 데이터의 양이 너무 커서 작은 블록으로 나눌 필요가 있는 경우 또는 합니다 Decoder 또는 Encoder 제공한 합니다 GetDecoder 메서드 또는 GetEncoder 메서드를 각각.

추가 정보

• GetCharCount(Byte[], Int32, Int32)
• GetMaxCharCount(Int32)
• GetDecoder()
• GetString(Byte[], Int32, Int32)

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

Source:

UTF32Encoding.cs

지정한 바이트 배열의 바이트 시퀀스를 지정한 문자 배열로 디코딩합니다.

public:
 override int GetChars(cli::array <System::Byte> ^ bytes, int byteIndex, int byteCount, cli::array <char> ^ chars, int charIndex);

public override int GetChars (byte[] bytes, int byteIndex, int byteCount, char[] chars, int charIndex);

override this.GetChars : byte[] * int * int * char[] * int -> int

Public Overrides Function GetChars (bytes As Byte(), byteIndex As Integer, byteCount As Integer, chars As Char(), charIndex As Integer) As Integer

매개 변수

bytes

Byte[]

디코딩할 바이트 시퀀스를 포함하는 바이트 배열입니다.

byteIndex

Int32

디코딩할 첫 번째 바이트의 인덱스입니다.

byteCount

Int32

디코딩할 바이트 수입니다.

chars

Char[]

결과 문자 집합을 포함할 문자 배열입니다.

charIndex

Int32

결과 문자 집합을 쓰기 시작할 인덱스입니다.

반환

Int32

chars에 쓴 실제 문자 수입니다.

예외

ArgumentNullException

bytes이(가) null인 경우

또는

chars이(가) null인 경우

ArgumentOutOfRangeException

byteIndex, byteCount 또는 charIndex가 0보다 작은 경우

또는

byteindex 및 byteCount 가 bytes에서 올바른 범위를 나타내지 않습니다.

또는

charIndex가 chars의 유효한 인덱스가 아닌 경우

ArgumentException

오류 검색이 사용되고 bytes에 잘못된 바이트 시퀀스를 포함합니다.

또는

chars의 용량(charIndex ~ 배열 끝)이 부족해서 결과 문자를 수용할 수 없는 경우

DecoderFallbackException

대체가 발생했습니다(자세한 내용은 .NET의 문자 인코딩 참조).

및

DecoderFallback이 DecoderExceptionFallback로 설정됩니다.

예제

다음 예제에서는 문자열을 바이트 배열로 인코딩한 다음 바이트를 문자 배열로 디코딩합니다.

using namespace System;
using namespace System::Text;
void PrintCountsAndChars( array<Byte>^bytes, Encoding^ enc );
int main()
{
   
   // Create two instances of UTF32Encoding: one with little-endian byte order and one with big-endian byte order.
   UTF32Encoding^ u32LE = gcnew UTF32Encoding( false,true,true );
   UTF32Encoding^ u32BE = gcnew UTF32Encoding( true,true,true );
   
   // Create byte arrays from the same string containing the following characters:
   //    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)
   String^ myStr = L"za\u0306\u01FD\u03B2\xD8FF\xDCFF";
   
   // barrBE uses the big-endian byte order.
   array<Byte>^barrBE = gcnew array<Byte>(u32BE->GetByteCount( myStr ));
   u32BE->GetBytes( myStr, 0, myStr->Length, barrBE, 0 );
   
   // barrLE uses the little-endian byte order.
   array<Byte>^barrLE = gcnew array<Byte>(u32LE->GetByteCount( myStr ));
   u32LE->GetBytes( myStr, 0, myStr->Length, barrLE, 0 );
   
   // Get the char counts and decode the byte arrays.
   Console::Write( "BE array with BE encoding : " );
   PrintCountsAndChars( barrBE, u32BE );
   Console::Write( "LE array with LE encoding : " );
   PrintCountsAndChars( barrLE, u32LE );
   
   // Decode the byte arrays using an encoding with a different byte order.
   Console::Write( "BE array with LE encoding : " );
   try
   {
      PrintCountsAndChars( barrBE, u32LE );
   }
   catch ( System::ArgumentException^ e ) 
   {
      Console::WriteLine( e->Message );
   }

   Console::Write( "LE array with BE encoding : " );
   try
   {
      PrintCountsAndChars( barrLE, u32BE );
   }
   catch ( System::ArgumentException^ e ) 
   {
      Console::WriteLine( e->Message );
   }

}

void PrintCountsAndChars( array<Byte>^bytes, Encoding^ enc )
{
   
   // Display the name of the encoding used.
   Console::Write( "{0,-25} :", enc );
   
   // Display the exact character count.
   int iCC = enc->GetCharCount( bytes );
   Console::Write( " {0,-3}", iCC );
   
   // Display the maximum character count.
   int iMCC = enc->GetMaxCharCount( bytes->Length );
   Console::Write( " {0,-3} :", iMCC );
   
   // Decode the bytes and display the characters.
   array<Char>^chars = gcnew array<Char>(iCC);
   enc->GetChars( bytes, 0, bytes->Length, chars, 0 );
   Console::WriteLine( chars );
}

/* 
This code produces the following output.  The question marks take the place of characters that cannot be displayed at the console.

BE array with BE encoding : System.Text.UTF32Encoding : 7   14  :za??�?
LE array with LE encoding : System.Text.UTF32Encoding : 7   14  :za??�?
BE array with LE encoding : System.Text.UTF32Encoding :Invalid byte was found at byte index 3.
LE array with BE encoding : System.Text.UTF32Encoding :Invalid byte was found at byte index 3.

*/

using System;
using System.Text;

public class SamplesUTF32Encoding  {

   public static void Main()  {

      // Create two instances of UTF32Encoding: one with little-endian byte order and one with big-endian byte order.
      UTF32Encoding u32LE = new UTF32Encoding( false, true, true );
      UTF32Encoding u32BE = new UTF32Encoding( true, true, true );

      // Create byte arrays from the same string containing the following characters:
      //    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";

      // barrBE uses the big-endian byte order.
      byte[] barrBE = new byte[u32BE.GetByteCount( myStr )];
      u32BE.GetBytes( myStr, 0, myStr.Length, barrBE, 0 );

      // barrLE uses the little-endian byte order.
      byte[] barrLE = new byte[u32LE.GetByteCount( myStr )];
      u32LE.GetBytes( myStr, 0, myStr.Length, barrLE, 0 );

      // Get the char counts and decode the byte arrays.
      Console.Write( "BE array with BE encoding : " );
      PrintCountsAndChars( barrBE, u32BE );
      Console.Write( "LE array with LE encoding : " );
      PrintCountsAndChars( barrLE, u32LE );

      // Decode the byte arrays using an encoding with a different byte order.
      Console.Write( "BE array with LE encoding : " );
      try  {
         PrintCountsAndChars( barrBE, u32LE );
      }
      catch ( System.ArgumentException e )  {
         Console.WriteLine( e.Message );
      }

      Console.Write( "LE array with BE encoding : " );
      try  {
         PrintCountsAndChars( barrLE, u32BE );
      }
      catch ( System.ArgumentException e )  {
         Console.WriteLine( e.Message );
      }
   }

   public static void PrintCountsAndChars( byte[] bytes, Encoding enc )  {

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

      // Display the exact character count.
      int iCC  = enc.GetCharCount( bytes );
      Console.Write( " {0,-3}", iCC );

      // Display the maximum character count.
      int iMCC = enc.GetMaxCharCount( bytes.Length );
      Console.Write( " {0,-3} :", iMCC );

      // Decode the bytes and display the characters.
      char[] chars = new char[iCC];
      enc.GetChars( bytes, 0, bytes.Length, chars, 0 );
      Console.WriteLine( chars );
   }
}

Imports System.Text

Public Class SamplesUTF32Encoding   

   Public Shared Sub Main()

      ' Create two instances of UTF32Encoding: one with little-endian byte order and one with big-endian byte order.
      Dim u32LE As New UTF32Encoding(False, True, True)
      Dim u32BE As New UTF32Encoding(True, True, True)


      ' Create byte arrays from the same string containing the following characters:
      '    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)

      ' barrBE uses the big-endian byte order.
      ' NOTE: In Visual Basic, arrays contain one extra element by default.
      '       The following line creates an array with the exact number of elements required.
      Dim barrBE(u32BE.GetByteCount(myStr) - 1) As Byte
      u32BE.GetBytes(myStr, 0, myStr.Length, barrBE, 0)

      ' barrLE uses the little-endian byte order.
      ' NOTE: In Visual Basic, arrays contain one extra element by default.
      '       The following line creates an array with the exact number of elements required.
      Dim barrLE(u32LE.GetByteCount(myStr) - 1) As Byte
      u32LE.GetBytes(myStr, 0, myStr.Length, barrLE, 0)


      ' Get the char counts and decode the byte arrays.
      Console.Write("BE array with BE encoding : ")
      PrintCountsAndChars(barrBE, u32BE)
      Console.Write("LE array with LE encoding : ")
      PrintCountsAndChars(barrLE, u32LE)


      ' Decode the byte arrays using an encoding with a different byte order.
      Console.Write("BE array with LE encoding : ")
      Try
         PrintCountsAndChars(barrBE, u32LE)
      Catch e As System.ArgumentException
         Console.WriteLine(e.Message)
      End Try

      Console.Write("LE array with BE encoding : ")
      Try
         PrintCountsAndChars(barrLE, u32BE)
      Catch e As System.ArgumentException
         Console.WriteLine(e.Message)
      End Try

   End Sub


   Public Shared Sub PrintCountsAndChars(bytes() As Byte, enc As Encoding)

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

      ' Display the exact character count.
      Dim iCC As Integer = enc.GetCharCount(bytes)
      Console.Write(" {0,-3}", iCC)

      ' Display the maximum character count.
      Dim iMCC As Integer = enc.GetMaxCharCount(bytes.Length)
      Console.Write(" {0,-3} :", iMCC)

      ' Decode the bytes and display the characters.
      Dim chars(iCC) As Char
      enc.GetChars(bytes, 0, bytes.Length, chars, 0)
      Console.WriteLine(chars)

   End Sub

End Class

설명

결과 문자를 저장하는 데 필요한 GetChars 정확한 배열 크기를 계산하려면 메서드를 호출합니다 GetCharCount . 최대 배열 크기를 계산 하려면 메서드를 호출 GetMaxCharCount 합니다. 메서드는 GetCharCount 일반적으로 메모리를 적게 할당하지만 메서드는 GetMaxCharCount 일반적으로 더 빠르게 실행됩니다.

오류 검색을 사용하면 잘못된 시퀀스로 인해 이 메서드가 을 throw합니다 ArgumentException. 오류 검색이 없으면 잘못된 시퀀스가 무시되고 예외가 throw되지 않습니다.

디코딩할 바이트 범위에 BOM(바이트 순서 표시)이 포함되고 바이트 배열이 BOM 인식이 아닌 형식의 메서드에 의해 반환된 경우 U+FFFE 문자는 이 메서드에서 반환된 문자 배열에 포함됩니다. 메서드를 호출 String.TrimStart 하여 제거할 수 있습니다.

스트림에서 읽은 데이터와 같이 변환할 데이터는 순차적 블록에서만 사용할 수 있습니다. 이 경우 애플리케이션에서는 데이터의 양이 너무 커서 작은 블록으로 나눌 필요가 있는 경우 또는 합니다 Decoder 또는 Encoder 제공한 합니다 GetDecoder 메서드 또는 GetEncoder 메서드를 각각.

추가 정보

• GetCharCount(Byte[], Int32, Int32)
• GetMaxCharCount(Int32)
• GetDecoder()
• GetString(Byte[], Int32, Int32)