XmlTextReader.ReadChars メソッド

2008-03-28

要素のテキストの内容を文字バッファに読み取ります。このメソッドは、連続して呼び出すことによって埋め込みテキストの大量のストリームを読み取るように設計されています。

Public Function ReadChars( _
   ByVal buffer() As Char, _   ByVal index As Integer, _   ByVal count As Integer _) As Integer
[C#]
public int ReadChars(char[] buffer,intindex,intcount);
[C++]
public: int ReadChars(__wchar_tbuffer __gc[],intindex,intcount);
[JScript]
public function ReadChars(
   buffer : Char[],index : int,count : int) : int;

パラメータ

buffer
テキストの内容が書き込まれるバッファとして機能する文字の配列。
index
メソッドがテキストの内容の書き込みを開始できる buffer 内の位置。
count
buffer に書き込む文字数。

戻り値

読み取った文字数。リーダーが要素に配置されていない場合、または返す対象となるテキストの内容が現在のコンテキスト内にこれ以上ない場合は、0 になる場合があります。

例外

例外の種類	条件
ArgumentException	count が buffer (バッファサイズ - index) で指定した値を超えています。
ArgumentNullException	buffer 値が null 参照 (Visual Basic では Nothing) です。
ArgumentOutOfRangeException	index < 0 または count < 0。

解説

XML ドキュメントに埋め込まれたテキストの大量のストリームを処理するには、これが最も効率的な方法です。 ReadChars は、大きな文字列オブジェクトを割り当てるのではなく、一度に 1 つのバッファにテキストの内容を返します。このメソッドは、要素ノードだけで機能するように設計されています。他のノード型では、 ReadChars は 0 を返します。

リーダーを開始タグに配置すると、 ReadChars が test を返し、リーダーを終了タグの後ろに配置する XML を次に示します。

<Item>test</Item>

ReadChars には次の機能があります。

このメソッドは、要素ノードだけで機能するように設計されています。他のノード型では、 ReadChars は 0 を返します。
このメソッドは、実際の文字の内容を返します。検出したエンティティ、CDATA、または他のマークアップの解決は試行されません。 ReadChars は、開始タグと終了タグの間の、マークアップを含むすべての内容を返します。
ReadChars は、整形式でない XML マークアップを無視します。たとえば、次の XML 文字列 <A>1<A>2</A> を読み取ると、 ReadChars は 1<A>2</A> を返します。一致する要素ペアからマークアップを返し、それ以外を無視します。
このメソッドはどのような正規化も行いません。
ReadChars は、文字ストリームの末尾に到達すると値 0 を返し、リーダーは終了タグの後ろに配置されます。
ReadChars の使用中は、属性読み取りメソッドは使用できません。

たとえば、次の XML を使用します。

<thing>
 some text
</thing>
<item>
</item>

リーダーは、while ループの末尾の <item> 要素に配置されます。

if (XmlNodeType.Element == reader.NodeType && "thing" == reader.Name)
{
 while( 0 != reader.ReadChars(buffer, 0, 1)
 {
 // Do something.
 // Attribute values are not available at this point. 
 }
}

使用例

[Visual Basic, C#, C++] ReadChars を使用して XML で読み取る例を次に示します。

 
Imports System
Imports System.Xml

' Reads an XML document using ReadChars
Public Class Sample
    Private Const filename As String = "items.xml"
    
    Public Shared Sub Main()
        Dim reader As XmlTextReader = Nothing
        
        Try
            ' Declare variables used by ReadChars
            Dim buffer() As Char
            Dim iCnt As Integer = 0
            Dim charbuffersize As Integer
            
            ' Load the reader with the data file.  Ignore white space.
            reader = New XmlTextReader(filename)
            reader.WhitespaceHandling = WhitespaceHandling.None
            
            ' Set variables used by ReadChars.
            charbuffersize = 10
            buffer = New Char(charbuffersize) {}
            
            ' Parse the file.  Read the element content  
            ' using the ReadChars method.
            reader.MoveToContent()
            iCnt = reader.ReadChars(buffer,0,charbuffersize)
            while (iCnt > 0)
              ' Print out chars read and the buffer contents.
              Console.WriteLine("  Chars read to buffer:" & iCnt)
              Console.WriteLine("  Buffer: [{0}]", New String(buffer, 0, iCnt))
              ' Clear the buffer.
              Array.Clear(buffer, 0, charbuffersize)
              iCnt = reader.ReadChars(buffer,0,charbuffersize)
           end while

        Finally
            If Not (reader Is Nothing) Then
                reader.Close()
            End If
        End Try
    End Sub 
End Class 

[C#] 
using System;
using System.Xml;

// Reads an XML document using ReadChars

public class Sample {

  private const String filename = "items.xml";

  public static void Main() {
  
    XmlTextReader reader = null;

    try {
          
      // Declare variables used by ReadChars
      Char []buffer;
      int iCnt = 0;
      int charbuffersize;
     
      // Load the reader with the data file.  Ignore white space.
      reader = new XmlTextReader(filename);
      reader.WhitespaceHandling = WhitespaceHandling.None;

      // Set variables used by ReadChars.
      charbuffersize = 10;
      buffer = new Char[charbuffersize];

      // Parse the file.  Read the element content
      // using the ReadChars method.
      reader.MoveToContent();
      while ( (iCnt = reader.ReadChars(buffer,0,charbuffersize)) > 0 ) {
        // Print out chars read and the buffer contents.
        Console.WriteLine ("  Chars read to buffer:" + iCnt);
        Console.WriteLine ("  Buffer: [{0}]", new String(buffer,0,iCnt));
        // Clear the buffer.
        Array.Clear(buffer,0,charbuffersize);
      }
       
    }
    finally {
      if (reader!=null)
        reader.Close();
    }
  }

} // End class

[C++] 
#using <mscorlib.dll>
#using <System.Xml.dll>
using namespace System;
using namespace System::Xml;

// Reads an XML document using ReadChars

int main() {

   XmlTextReader* reader = 0;
   String* filename = S"items.xml";

   try {

      // Declare variables used by ReadChars
      Char buffer[];
      int iCnt = 0;
      int charbuffersize;

      // Load the reader with the data file.  Ignore white space.
      reader = new XmlTextReader(filename);
      reader->WhitespaceHandling = WhitespaceHandling::None;

      // Set variables used by ReadChars.
      charbuffersize = 10;
      buffer = new Char[charbuffersize];

      // Parse the file.  Read the element content
      // using the ReadChars method.
      reader->MoveToContent();
      while ( (iCnt = reader->ReadChars(buffer,0,charbuffersize)) > 0 ) {
         // Print out chars read and the buffer contents.
         Console::WriteLine (S"  Chars read to buffer:{0}", __box(iCnt));
         Console::WriteLine (S"  Buffer: [{0}]", new String(buffer,0,iCnt));
         // Clear the buffer.
         Array::Clear(buffer,0,charbuffersize);
      }

   }
   __finally {
      if (reader!=0)
         reader->Close();
   }
}

[Visual Basic, C#, C++] この例では、入力として items.xml というファイルを使用しています。

<?xml version="1.0"?>
<!-- This is a sample XML document -->
<!DOCTYPE Items [<!ENTITY number "123">]>
<Items>
  <Item>Test with an entity: &number;</Item>
  <Item>test with a child element <more/> stuff</Item>
  <Item>test with a CDATA section <![CDATA[<456>]]> def</Item>
  <Item>Test with an char entity: &#65;</Item>
  <!-- Fourteen chars in this element.-->
  <Item>1234567890ABCD</Item>
</Items>

[JScript] JScript のサンプルはありません。Visual Basic、C#、および C++ のサンプルを表示するには、このページの左上隅にある言語のフィルタボタンをクリックします。

必要条件

プラットフォーム: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 ファミリ, .NET Compact Framework - Windows CE .NET, Common Language Infrastructure (CLI) Standard

参照

XmlTextReader クラス | XmlTextReader メンバ | System.Xml 名前空間 | ReadBase64 | ReadBinHex

次の方法で共有

XmlTextReader.ReadChars メソッド

パラメータ

戻り値

例外

解説

使用例

必要条件

参照

その他のリソース