Add TryReadStartElement, removed one ReadStartElement overload

Author: BigBang1112

MinimalXmlReader.Benchmarks/MiniXmlReaderExample2Benchmarks.cs

@@ -23,7 +23,7 @@ public void MiniXmlReader()
 
         r.SkipProcessingInstruction();
         r.SkipStartElement("root");
-        r.ReadStartElement("person", out var _);
+        r.TryReadStartElement("person");
         r.SkipStartElement("random");
         int.Parse(r.ReadContent());
         r.SkipEndElement("random");

MinimalXmlReader.Tests/MiniXmlReaderTests.cs

@@ -70,7 +70,7 @@ public void IntegrationTest_Random()
 
         Assert.False(r.SkipProcessingInstruction());
         Assert.True(r.SkipStartElement("root"));
-        Assert.True(r.ReadStartElement("person", out var personAtts));
+        Assert.True(r.TryReadStartElement("person", out var personAtts));
         Assert.Equal(expected: "Tierney", actual: personAtts["firstname"]);
         Assert.Equal(expected: "Shirberg", actual: personAtts["lastname"]);
         Assert.Equal(expected: "Port-au-Prince", actual: personAtts["city"]);

MinimalXmlReader/MiniXmlReader.cs

@@ -24,6 +24,7 @@ public MiniXmlReader(ReadOnlySpan<char> xml)
     /// Skips a processing instruction.
     /// </summary>
     /// <returns>True if a processing instruction was skipped; otherwise, false.</returns>
+    /// <exception cref="Exception">Something unexpected has failed.</exception>
     public bool SkipProcessingInstruction()
     {
         _ = SkipSpaces();
@@ -50,6 +51,7 @@ public bool SkipProcessingInstruction()
     /// Skips a start element.
     /// </summary>
     /// <param name="name">The name of the element to skip.</param>
+    /// <exception cref="Exception">Something unexpected has failed.</exception>
     public bool SkipStartElement(ReadOnlySpan<char> name)
     {
         _ = SkipSpaces();
@@ -108,9 +110,13 @@ public bool SkipStartElement()
     /// </summary>
     /// <param name="attributes">The attributes of the element.</param>
     /// <returns>The name of the element.</returns>
+    /// <exception cref="Exception">Not a start element or something unexpected has failed.</exception>
     public ReadOnlySpan<char> ReadStartElement(out Dictionary<string, string> attributes)
     {
-        var name = BeginReadStartElement();
+        if (!TryBeginReadStartElement(out var name))
+        {
+            throw new Exception("Not a start element");
+        }
 
         attributes = ReadAttributes();
 
@@ -121,37 +127,84 @@ public ReadOnlySpan<char> ReadStartElement(out Dictionary<string, string> attrib
     /// Reads a start element.
     /// </summary>
     /// <returns>The name of the element.</returns>
+    /// <exception cref="Exception">Not a start element or something unexpected has failed.</exception>
     public ReadOnlySpan<char> ReadStartElement()
     {
-        var name = BeginReadStartElement();
+        if (!TryBeginReadStartElement(out var name))
+        {
+            throw new Exception("Not a start element");
+        }
 
         SkipAttributes();
 
         return name;
     }
 
     /// <summary>
-    /// Reads a start element.
+    /// Tries reading a start element.
     /// </summary>
-    /// <param name="name">The name of the element to read.</param>
+    /// <param name="name">The name of the element to match.</param>
     /// <param name="attributes">The attributes of the element.</param>
     /// <returns>True if a start element was read; otherwise, false.</returns>
     /// <exception cref="Exception">Something unexpected has failed.</exception>
-    public bool ReadStartElement(ReadOnlySpan<char> name, [NotNullWhen(true)] out Dictionary<string, string>? attributes)
+    public bool TryReadStartElement(ReadOnlySpan<char> name, [NotNullWhen(true)] out Dictionary<string, string>? attributes)
     {
         SkipSpaces();
 
         var safePosition = position;
 
-        if (!SkipChar('<'))
+        if (!SkipChar('<') || !ValidateElementName(name))
         {
-            throw new Exception("Not a start element");
+            position = safePosition;
+            attributes = null;
+            return false;
         }
 
-        if (!ValidateElementName(name))
+        attributes = ReadAttributes();
+
+        return true;
+    }
+
+    /// <summary>
+    /// Tries reading a start element.
+    /// </summary>
+    /// <param name="name">The name of the element to match.</param>
+    /// <returns>True if a start element was read; otherwise, false.</returns>
+    /// <exception cref="Exception">Something unexpected has failed.</exception>
+    public bool TryReadStartElement(ReadOnlySpan<char> name)
+    {
+        SkipSpaces();
+
+        var safePosition = position;
+
+        if (!SkipChar('<') || !ValidateElementName(name))
         {
             position = safePosition;
+            return false;
+        }
+
+        SkipAttributes();
+
+        return true;
+    }
+
+    /// <summary>
+    /// Tries reading a start element.
+    /// </summary>
+    /// <param name="name">The returned name of the element.</param>
+    /// <param name="attributes">The attributes of the element.</param>
+    /// <returns>True if a start element was read; otherwise, false.</returns>
+    /// <exception cref="Exception">Something unexpected has failed.</exception>
+    public bool TryReadStartElement(out ReadOnlySpan<char> name, [NotNullWhen(true)] out Dictionary<string, string>? attributes)
+    {
+        SkipSpaces();
+
+        var safePosition = position;
+
+        if (!TryBeginReadStartElement(out name))
+        {
             attributes = null;
+            position = safePosition;
             return false;
         }
 
@@ -160,6 +213,29 @@ public bool ReadStartElement(ReadOnlySpan<char> name, [NotNullWhen(true)] out Di
         return true;
     }
 
+    /// <summary>
+    /// Tries reading a start element.
+    /// </summary>
+    /// <param name="name">The returned name of the element.</param>
+    /// <returns>True if a start element was read; otherwise, false.</returns>
+    /// <exception cref="Exception">Something unexpected has failed.</exception>
+    public bool TryReadStartElement(out ReadOnlySpan<char> name)
+    {
+        SkipSpaces();
+
+        var safePosition = position;
+
+        if (!TryBeginReadStartElement(out name))
+        {
+            position = safePosition;
+            return false;
+        }
+
+        SkipAttributes();
+
+        return true;
+    }
+
     /// <summary>
     /// Skips an end element.
     /// </summary>
@@ -239,6 +315,7 @@ public bool SkipEndElement()
     /// Reads content of an element.
     /// </summary>
     /// <returns>The content of the element.</returns>
+    /// <exception cref="Exception">Something unexpected has failed.</exception>
     public ReadOnlySpan<char> ReadContent()
     {
         SkipSpaces();
@@ -254,6 +331,7 @@ public ReadOnlySpan<char> ReadContent()
     /// Reads content of an element as a string.
     /// </summary>
     /// <returns>The content of the element as a string.</returns>
+    /// <exception cref="Exception">Something unexpected has failed.</exception>
     public string ReadContentAsString()
     {
         return ReadContent().ToString();
@@ -263,6 +341,7 @@ public string ReadContentAsString()
     /// Reads content of an element as a boolean.
     /// </summary>
     /// <returns>The content of the element as a boolean.</returns>
+    /// <exception cref="Exception">Something unexpected has failed.</exception>
     public bool ReadContentAsBoolean()
     {
         var content = ReadContent();
@@ -275,6 +354,7 @@ public bool ReadContentAsBoolean()
         };
     }
 
+    /// <exception cref="Exception">Something unexpected has failed.</exception>
     private bool ValidateElementName(ReadOnlySpan<char> name)
     {
         for (var i = 0; i < name.Length; i++)
@@ -299,6 +379,7 @@ private bool ValidateElementName(ReadOnlySpan<char> name)
         return true;
     }
 
+    /// <exception cref="Exception">Something unexpected has failed.</exception>
     private Dictionary<string, string> ReadAttributes(bool expectsProcessingInstruction = false)
     {
         SkipSpaces();
@@ -337,13 +418,15 @@ private Dictionary<string, string> ReadAttributes(bool expectsProcessingInstruct
         return attributes;
     }
 
-    private ReadOnlySpan<char> BeginReadStartElement()
+    /// <exception cref="Exception">Something unexpected has failed.</exception>
+    private bool TryBeginReadStartElement(out ReadOnlySpan<char> name)
     {
         SkipSpaces();
 
         if (!SkipChar('<'))
         {
-            throw new Exception("Not a start element");
+            name = default;
+            return false;
         }
 
         var start = position;
@@ -360,10 +443,10 @@ private ReadOnlySpan<char> BeginReadStartElement()
             Advance();
         }
 
-        var name = xml[start..position];
+        name = xml[start..position];
 
         Debug.WriteLine($"BeginReadStartElement({name})");
-        return name;
+        return true;
     }
 
     private bool SkipChar(char c)
@@ -379,6 +462,7 @@ private bool SkipChar(char c)
         return true;
     }
 
+    /// <exception cref="Exception">Something unexpected has failed.</exception>
     private void SkipUntilChar(char c, bool includeSpaces = false)
     {
         do
@@ -409,6 +493,7 @@ private bool SkipSpaces()
         return skipped;
     }
 
+    /// <exception cref="Exception">Something unexpected has failed.</exception>
     private void SkipAttributes(bool expectsProcessingInstruction = false)
     {
         SkipSpaces();
@@ -441,6 +526,7 @@ private void SkipAttributes(bool expectsProcessingInstruction = false)
         }
     }
 
+    /// <exception cref="Exception">Something unexpected has failed.</exception>
     private ReadOnlySpan<char> ReadUntilChar(char expectedChar, bool includeSpaces = false)
     {
         var start = position;
@@ -465,6 +551,7 @@ private ReadOnlySpan<char> ReadUntilChar(char expectedChar, bool includeSpaces =
         return xml[start..position];
     }
 
+    /// <exception cref="Exception">Something unexpected has failed.</exception>
     private void Advance()
     {
         if (position == xml.Length - 1)