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.
(in System.Xml.dll)
Visual Basic (Declaration)
Public Function ReadChars ( _
buffer As Char(), _
index As Integer, _
count As Integer _
) As Integer
Dim instance As XmlTextReader
Dim buffer As Char()
Dim index As Integer
Dim count As Integer
Dim returnValue As Integer
returnValue = instance.ReadChars(buffer, _
index, count)
public int ReadChars(
char[] buffer,
int index,
int count
)
public:
int ReadChars(
array<wchar_t>^ buffer,
int index,
int count
)
public function ReadChars(
buffer : char[],
index : int,
count : int
) : int
Parameters
- buffer
- Type: array<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..::.Int32The 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.
.gif) Note: |
|---|
In the .NET Framework version 2.0 release, the recommended practice is to create XmlReader instances using the XmlReader..::.Create method. This allows you to take full advantage of the new features introduced in this release. For more information, see Creating XML Readers. |
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.
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.
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
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
#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();
}
}
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>
Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98, Windows CE, Windows Mobile for Smartphone, Windows Mobile for Pocket PC, Xbox 360, Zune
The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.
.NET Framework
Supported in: 3.5, 3.0, 2.0, 1.1, 1.0
.NET Compact Framework
Supported in: 3.5, 2.0, 1.0
XNA Framework
Supported in: 3.0, 2.0, 1.0
Reference
Other Resources