XmlTextReader.ReadChars(Char[], Int32, Int32) 方法

定義

命名空間:

System.Xml

組件:

System.Xml.ReaderWriter.dll

Source:

XmlTextReader.cs

將項目的文字內容讀入字元緩衝區中。 這個方法設計可藉由連續呼叫來讀取內嵌文字的大量資料流。

public:
 int ReadChars(cli::array <char> ^ buffer, int index, int count);

public int ReadChars (char[] buffer, int index, int count);

member this.ReadChars : char[] * int * int -> int

Public Function ReadChars (buffer As Char(), index As Integer, count As Integer) As Integer

參數

buffer

Char[]

做為寫入文字內容之緩衝區的字元陣列。

index

Int32

buffer 中這個方法可以開始寫入文字內容的位置。

count

Int32

要寫入 buffer 的字元數。

傳回

Int32

已讀取的字元數。 如果讀取器不在項目上，或者目前內容中沒有其他可傳回的文字內容，則這個數目可為 0。

例外狀況

ArgumentException

count 大於 buffer 中指定的空間 (緩衝區大小 - index)。

ArgumentNullException

buffer 值為 null。

ArgumentOutOfRangeException

index< 0 或 count< 0。

範例

下列範例會使用 ReadChars 在 XML 中讀取 。

#using <System.Xml.dll>

using namespace System;
using namespace System::Xml;

// Reads an XML document using ReadChars
int main()
{
   XmlTextReader^ reader = nullptr;
   String^ filename = "items.xml";
   try
   {
      
      // Declare variables used by ReadChars
      array<Char>^buffer;
      int iCnt = 0;
      int charbuffersize;
      
      // Load the reader with the data file.  Ignore white space.
      reader = gcnew XmlTextReader( filename );
      reader->WhitespaceHandling = WhitespaceHandling::None;
      
      // Set variables used by ReadChars.
      charbuffersize = 10;
      buffer = gcnew array<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:{0}", iCnt );
         Console::WriteLine( "  Buffer: [{0}]", gcnew String( buffer,0,iCnt ) );
         
         // Clear the buffer.
         Array::Clear( buffer, 0, charbuffersize );
      }
   }
   finally
   {
      if ( reader != nullptr )
            reader->Close();
   }

}

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

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

該範例使用 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: A</Item>
  <!-- Fourteen chars in this element.-->
  <Item>1234567890ABCD</Item>
</Items>

備註

注意

從 .NET Framework 2.0 開始，建議您使用 XmlReader.Create 方法來建立 XmlReader 實例，以利用新功能。

這是處理內嵌在 XML 檔中的非常大型文字串流的最有效率方式。 不配置大型字串物件， ReadChars 而是一次傳回緩衝區的文字內容。 這個方法的設計目的是只在專案節點上運作。 其他節點類型會導致 ReadChars 傳回 0 。

在下列 XML 中，如果讀取器位於開始標籤上， ReadChars 則會傳回 test 並放置讀取器在結束標籤之後。

<Item>test</Item>

ReadChars 具有下列功能：

• 這個方法的設計目的是只在專案節點上運作。 其他節點類型會導致 ReadChars 傳回 0。

• 這個方法會傳回實際的字元內容。 不會嘗試解析實體、CDATA 或任何其他遇到的標記。 ReadChars 會傳回開始標籤與結束標籤之間的一切，包括標記。

• ReadChars 忽略格式不正確之 XML 標記。 例如，讀取下列 XML 字串 <A>1<A>2</A> 時， ReadChars 會傳 1<A>2</A> 回 。 (它會從相符的專案組傳回標記，並忽略 others.)

• 這個方法不會進行任何正規化。

• 當 ReadChars 到達字元資料流的結尾時，它會傳回值 0，而且讀取器位於結束標記之後。

• 使用 ReadChars 時無法使用屬性讀取方法。

例如，使用下列 XML：

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

讀取器位於 <item> while 迴圈結尾的 元素上。

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

另請參閱

• ReadBase64(Byte[], Int32, Int32)
• ReadBinHex(Byte[], Int32, Int32)
• XmlReader