Export (0) Print
Expand All

XmlTextReader.ReadChars Method

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.

Namespace:  System.Xml
Assembly:  System.Xml (in System.Xml.dll)

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

Parameters

buffer
Type: System.Char[]

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

index
Type: System.Int32

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

count
Type: System.Int32

The number of characters to write into buffer.

Return Value

Type: System.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.

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

NoteNote

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

The following example reads in XML using ReadChars.

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

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: &#65;</Item>
  <!-- Fourteen chars in this element.-->
  <Item>1234567890ABCD</Item>
</Items>

.NET Framework

Supported in: 4.5.2, 4.5.1, 4.5, 4, 3.5, 3.0, 2.0, 1.1, 1.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Show:
© 2014 Microsoft