XmlTextReader.ReadChars(Char[], Int32, Int32) Method

Definition

Namespace:

System.Xml

Assembly:

System.Xml.ReaderWriter.dll

Source:

XmlTextReader.cs

Reads the text contents of an element into a character buffer. This method is designed to read large streams of embedded text by calling it successively.

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

Parameters

buffer

Char[]

The array of characters that serves as the buffer to which the text contents are written.

index

Int32

The position within buffer where the method can begin writing text contents.

count

Int32

The number of characters to write into buffer.

Returns

Int32

The number of characters read. This can be 0 if the reader is not positioned on an element or if there is no more text content to return in the current context.

Exceptions

ArgumentException

count is greater than the space specified in the buffer (buffer size - index).

ArgumentNullException

The buffer value is null.

ArgumentOutOfRangeException

index < 0 or count< 0.

Examples

The following example reads in XML using ReadChars.

#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

The example uses the items.xml file as input.

<?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>

Remarks

Note

Starting with the .NET Framework 2.0, we recommend that you create XmlReader instances by using the XmlReader.Create method to take advantage of new functionality.

This is the most efficient way to process very large streams of text embedded in an XML document. Rather than allocating large string objects, ReadChars returns text content a buffer at a time. This method is designed to work only on element nodes. Other node types cause ReadChars to return 0.

In the following XML, if the reader is positioned on the start tag, ReadChars returns test and positions the reader after the end tag.

<Item>test</Item>

ReadChars has the following functionality:

• This method is designed to work on element nodes only. Other node types cause ReadChars to return 0.

• This method returns the actual character content. There is no attempt to resolve entities, CDATA, or any other markup encountered. ReadChars returns everything between the start tag and the end tag, including markup.

• ReadChars ignores XML markup that is not well-formed. For example, when reading the following XML string <A>1<A>2</A>, ReadChars returns 1<A>2</A>. (It returns markup from the matching element pair and ignores others.)

• This method does not do any normalization.

• When ReadChars has reached the end of the character stream, it returns the value 0 and the reader is positioned after the end tag.

• Attribute read methods are not available while using ReadChars.

For example, using the following XML:

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

The reader is positioned on the <item> element at the end of the while loop.

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

See also

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