Nuget package

README.md

@@ -11,7 +11,7 @@ embeds data in-line in a URL. It enables you to retrieve this data and to find a
 The library makes extensive use of ReadOnlySpan<Char> and ReadOnlyMemory<Char> to build and examine the 
 content of such URIs without having to allocate a lot of temporary Strings.
 
-Read the [Project Reference](https://github.com/FolkerKinzel/Uris/blob/master/ProjectReference/1.0.0-alpha.1/FolkerKinzel.Uris.Reference.en.chm) for details.
+Read the [Project Reference](https://github.com/FolkerKinzel/Uris/blob/master/ProjectReference/1.0.0-beta.1/FolkerKinzel.Uris.Reference.en.chm) for details.
 
 > IMPORTANT: On some systems the content of the .CHM file is blocked. Before opening the file right click on the file icon, select Properties, and check the "Allow" checkbox (if it is present) in the lower right corner of the General tab in the Properties dialog.
 

src/FolkerKinzel.URIs/FolkerKinzel.URIs.csproj

@@ -10,7 +10,7 @@
     <PackageRequireLicenseAcceptance>true</PackageRequireLicenseAcceptance>
     <PackageIcon>Logo.png</PackageIcon>
     <PackageVersion>1.0.0-beta.1</PackageVersion>
-    <FileVersion>1.0.0.96</FileVersion>
+    <FileVersion>1.0.0.102</FileVersion>
     <AssemblyVersion>1.0.0.0</AssemblyVersion>
     <Description>.NET library that supports the work with URIs.</Description>
     <PackageTags>URI MIME C# .NET</PackageTags>

src/FolkerKinzel.Uris.Tests/DataUrlInfoTests.cs

@@ -29,8 +29,8 @@ public class DataUrlInfoTests
         [TestMethod]
         public void IsEmptyTest2()
         {
-            _ = DataUrl.TryParse("data:,abc", out DataUrlInfo? dataUrl);
-            Assert.IsFalse(dataUrl!.Value.IsEmpty);
+            _ = DataUrlInfo.TryParse("data:,abc", out DataUrlInfo dataUrl);
+            Assert.IsFalse(dataUrl.IsEmpty);
         }
 
         [TestMethod]
@@ -41,9 +41,9 @@ public void TryParseTest1()
 
             string test = DATA_PROTOCOL + "text/plain;charset=utf-8" + ";" + DEFAULT_ENCODING + "," + Uri.EscapeDataString(text);
 
-            Assert.IsTrue(DataUrl.TryParse(test, out DataUrlInfo? dataUri));
+            Assert.IsTrue(DataUrlInfo.TryParse(test, out DataUrlInfo dataUri));
 
-            Assert.IsTrue(dataUri!.Value.TryGetEmbeddedText(out string? outText));
+            Assert.IsTrue(dataUri.TryGetEmbeddedText(out string? outText));
             Assert.AreEqual(text, outText);
 
             outText = DataUrl.FromText(text);
@@ -78,24 +78,24 @@ public void TryParseTest2()
         [DataRow(null)]
         [DataRow("")]
         [DataRow("http://wwww.folker-kinzel.de/index.htm")]
-        public void TryParseTest3(string? value) => Assert.IsFalse(DataUrl.TryParse(value, out _));
+        public void TryParseTest3(string? value) => Assert.IsFalse(DataUrlInfo.TryParse(value, out _));
 
 
         [TestMethod()]
         public void TryParseTest4()
         {
             string test = "data:;charset=UTF-8,Text";
 
-            Assert.IsTrue(DataUrl.TryParse(test, out DataUrlInfo? dataUrl2));
+            Assert.IsTrue(DataUrlInfo.TryParse(test, out DataUrlInfo dataUrl2));
 
-            Assert.AreEqual(dataUrl2!.Value.Data.ToString(), "Text");
-            Assert.AreEqual(dataUrl2.Value.MimeType.MediaType.ToString(), "text");
-            Assert.AreEqual(dataUrl2.Value.MimeType.SubType.ToString(), "plain");
+            Assert.AreEqual(dataUrl2.Data.ToString(), "Text");
+            Assert.AreEqual(dataUrl2.MimeType.MediaType.ToString(), "text");
+            Assert.AreEqual(dataUrl2.MimeType.SubType.ToString(), "plain");
 
-            Assert.AreEqual(dataUrl2.Value.MimeType.Parameters.First().Value.ToString(), "UTF-8");
-            Assert.AreEqual(dataUrl2.Value.DataEncoding, DataEncoding.Url);
+            Assert.AreEqual(dataUrl2.MimeType.Parameters.First().Value.ToString(), "UTF-8");
+            Assert.AreEqual(dataUrl2.DataEncoding, DataEncoding.Url);
 
-            Assert.IsTrue(dataUrl2.Value.TryGetEmbeddedText(out string? outString));
+            Assert.IsTrue(dataUrl2.TryGetEmbeddedText(out string? outString));
             Assert.AreEqual("Text", outString);
         }
 
@@ -105,19 +105,19 @@ public void TryParseTest5()
             const string url = "data:application/x-octet,A%42C";
             byte[] data = new byte[] { 0x41, 0x42, 0x43 };
 
-            Assert.IsTrue(DataUrl.TryParse(url, out DataUrlInfo? dataUrl));
-            Assert.AreEqual(DataEncoding.Url, dataUrl!.Value.DataEncoding);
-            Assert.IsTrue(dataUrl.Value.ContainsEmbeddedBytes);
+            Assert.IsTrue(DataUrlInfo.TryParse(url, out DataUrlInfo dataUrl));
+            Assert.AreEqual(DataEncoding.Url, dataUrl.DataEncoding);
+            Assert.IsTrue(dataUrl.ContainsEmbeddedBytes);
 
-            Assert.IsTrue(dataUrl.Value.TryGetEmbeddedBytes(out byte[]? output));
+            Assert.IsTrue(dataUrl.TryGetEmbeddedBytes(out byte[]? output));
 
             CollectionAssert.AreEqual(data, output);
         }
 
         [DataTestMethod]
         [DataRow("data:abc")]
         //[DataRow("data:,a bc")]
-        public void TryParseTest7(string input) => Assert.IsFalse(DataUrl.TryParse(input, out _));
+        public void TryParseTest7(string input) => Assert.IsFalse(DataUrlInfo.TryParse(input, out _));
 
         [TestMethod]
         public void TryParseTest8()
@@ -130,7 +130,7 @@ public void TryParseTest8()
 #endif
             string s = $"data:;charset={isoEncoding};base64,{Convert.ToBase64String(Encoding.GetEncoding(isoEncoding).GetBytes(data))}";
 
-            Assert.IsTrue(DataUrl.TryParse(s, out DataUrlInfo? dataUrlText1));
+            Assert.IsTrue(DataUrlInfo.TryParse(s, out DataUrlInfo dataUrlText1));
         }
 
         [TestMethod]
@@ -143,9 +143,9 @@ public void TryParseTest9()
                 _ = sb.Append('%').Append(i.ToString("x2"));
             }
 
-            Assert.IsTrue(DataUrl.TryParse($"data:application/octet-stream,{sb}", out DataUrlInfo? dataUrl));
-            Assert.IsTrue(dataUrl!.Value.ContainsEmbeddedBytes);
-            Assert.IsTrue(dataUrl.Value.TryGetEmbeddedBytes(out byte[]? bytes));
+            Assert.IsTrue(DataUrlInfo.TryParse($"data:application/octet-stream,{sb}", out DataUrlInfo dataUrl));
+            Assert.IsTrue(dataUrl.ContainsEmbeddedBytes);
+            Assert.IsTrue(dataUrl.TryGetEmbeddedBytes(out byte[]? bytes));
             Assert.AreEqual(256, bytes!.Length);
 
             for (int i = 0; i < bytes!.Length; i++)
@@ -160,19 +160,19 @@ public void TryParseTest10()
             string text = "This is long Ascii text.";
             string urlString = DataUrl.FromText(text);
 
-            Assert.IsTrue(DataUrl.TryParse(urlString, out DataUrlInfo? dataUrl));
-            Assert.AreEqual(DataEncoding.Url, dataUrl!.Value.DataEncoding);
-            Assert.IsTrue(dataUrl.Value.ContainsEmbeddedText);
-            Assert.IsFalse(dataUrl.Value.ContainsEmbeddedBytes);
-            Assert.IsTrue(dataUrl.Value.TryGetEmbeddedText(out string? outText));
+            Assert.IsTrue(DataUrlInfo.TryParse(urlString, out DataUrlInfo dataUrl));
+            Assert.AreEqual(DataEncoding.Url, dataUrl.DataEncoding);
+            Assert.IsTrue(dataUrl.ContainsEmbeddedText);
+            Assert.IsFalse(dataUrl.ContainsEmbeddedBytes);
+            Assert.IsTrue(dataUrl.TryGetEmbeddedText(out string? outText));
             Assert.AreEqual(text, outText);
         }
 
         [TestMethod]
         public void GetFileTypeExtensionTest()
         {
-            Assert.IsTrue(DataUrl.TryParse("data:,abc", out DataUrlInfo? dataUrl));
-            Assert.AreEqual(".txt", dataUrl!.Value.GetFileTypeExtension());
+            Assert.IsTrue(DataUrlInfo.TryParse("data:,abc", out DataUrlInfo dataUrl));
+            Assert.AreEqual(".txt", dataUrl.GetFileTypeExtension());
         }
 
 
@@ -344,14 +344,14 @@ public void ToStringTest1()
         {
             const string input = "data:,This is unescaped ASCII text.";
 
-            Assert.IsTrue(DataUrl.TryParse(input, out DataUrlInfo? info));
-            Assert.IsTrue(info!.Value.ContainsEmbeddedText);
-            Assert.IsFalse(info.Value.ContainsEmbeddedBytes);
+            Assert.IsTrue(DataUrlInfo.TryParse(input, out DataUrlInfo info));
+            Assert.IsTrue(info.ContainsEmbeddedText);
+            Assert.IsFalse(info.ContainsEmbeddedBytes);
 
-            string output = info.Value.ToString();
+            string output = info.ToString();
 
             Assert.AreNotEqual(input, output);
-            Assert.IsTrue(DataUrl.TryParse(output, out DataUrlInfo? dataUrl2));
+            Assert.IsTrue(DataUrlInfo.TryParse(output, out DataUrlInfo dataUrl2));
             Assert.AreEqual(info, dataUrl2);
         }
 
@@ -370,17 +370,17 @@ public void EqualsTest1()
             var mime = MimeType.Parse($"text/plain; charset={encodingName}");
             string urlStr2 = DataUrl.FromBytes(bytes, in mime);
 
-            Assert.IsTrue(DataUrl.TryParse(urlStr1, out DataUrlInfo? dataUrl1));
-            Assert.IsTrue(DataUrl.TryParse(urlStr2, out DataUrlInfo? dataUrl2));
+            Assert.IsTrue(DataUrlInfo.TryParse(urlStr1, out DataUrlInfo dataUrl1));
+            Assert.IsTrue(DataUrlInfo.TryParse(urlStr2, out DataUrlInfo dataUrl2));
 
             Assert.IsTrue(dataUrl1 == dataUrl2);
             Assert.IsFalse(dataUrl1 != dataUrl2);
             Assert.AreEqual(dataUrl1.GetHashCode(), dataUrl2.GetHashCode());
 
             Assert.IsTrue(dataUrl1.Equals(dataUrl2));
 
-            object? o1 = dataUrl1!.Value;
-            object? o2 = dataUrl2!.Value;
+            object? o1 = dataUrl1;
+            object? o2 = dataUrl2;
 
             //Assert.IsTrue(dataUrl1 == o2);
             //Assert.IsFalse(o1 != o2);
@@ -396,17 +396,17 @@ public void EqualsTest2()
             string urlStr1 = $"data:application/octet-stream,{input}";
             string urlStr2 = $"data:application/octet-stream;base64,{Convert.ToBase64String(Encoding.ASCII.GetBytes(input))}";
 
-            Assert.IsTrue(DataUrl.TryParse(urlStr1, out DataUrlInfo? dataUrl1));
-            Assert.IsTrue(DataUrl.TryParse(urlStr2, out DataUrlInfo? dataUrl2));
+            Assert.IsTrue(DataUrlInfo.TryParse(urlStr1, out DataUrlInfo dataUrl1));
+            Assert.IsTrue(DataUrlInfo.TryParse(urlStr2, out DataUrlInfo dataUrl2));
 
             Assert.IsTrue(dataUrl1 == dataUrl2);
         }
 
         [TestMethod]
         public void CloneTest1()
         {
-            Assert.IsTrue(DataUrl.TryParse("data:,xyz", out DataUrlInfo? dtInfo));
-            ICloneable info = dtInfo!.Value;
+            Assert.IsTrue(DataUrlInfo.TryParse("data:,xyz", out DataUrlInfo dtInfo));
+            ICloneable info = dtInfo;
 
             object dataUrl2 = info.Clone();
 

src/FolkerKinzel.Uris/DataUrl.cs

@@ -35,7 +35,7 @@ public static class DataUrl
         internal const string Base64 = ";base64";
         internal const string DEFAULT_MEDIA_TYPE = "text/plain";
         #endregion
-        
+
 
         /// <summary>
         /// Embeds Text in a "data" URL (RFC 2397).
@@ -125,6 +125,16 @@ public static string FromBytes(byte[]? bytes, in MimeType mimeType)
         /// <exception cref="ArgumentNullException"><paramref name="filePath"/> is <c>null</c>.</exception>
         /// <exception cref="ArgumentException"><paramref name="filePath"/> is not a valid file path.</exception>
         /// <exception cref="IOException">I/O error.</exception>
+        /// 
+        ///<example>
+        /// <note type="note">
+        /// For the sake of better readability, exception handling is ommitted in the example.
+        /// </note>
+        /// <para>
+        /// Creating and parsing a "data" URL:
+        /// </para>
+        /// <code language="c#" source="./../Examples/DataUrlExample.cs"/>
+        /// </example>
         public static string FromFile(string filePath, in MimeType? mimeType = null)
         {
             byte[] bytes = LoadFile(filePath);
@@ -142,7 +152,7 @@ internal static MimeType DefaultMediaType()
             return mediaType;
         }
 
-        
+
         #region private
 
         //    private static async Task<byte[]> LoadFileAsync(string path)
@@ -221,7 +231,7 @@ private static byte[] LoadFile(string path)
                 throw new IOException(e.Message, e);
             }
         }
-        
+
         #endregion
 
 

src/FolkerKinzel.Uris/DataUrlInfo_Parse.cs

@@ -13,7 +13,7 @@ namespace FolkerKinzel.Uris
 {
     public readonly partial struct DataUrlInfo
     {
-        
+
         #region Parser
 
         /// <summary>
@@ -23,6 +23,15 @@ namespace FolkerKinzel.Uris
         /// <returns>A <see cref="DataUrlInfo"/> instance, which represents <paramref name="value"/>.</returns>
         /// <exception cref="ArgumentNullException"><paramref name="value"/> is <c>null</c>.</exception>
         /// <exception cref="ArgumentException"><paramref name="value"/> could not be parsed as <see cref="DataUrlInfo"/>.</exception>
+        /// <example>
+        /// <note type="note">
+        /// For the sake of better readability, exception handling is ommitted in the example.
+        /// </note>
+        /// <para>
+        /// Creating and parsing a "data" URL:
+        /// </para>
+        /// <code language="c#" source="./../Examples/DataUrlExample.cs"/>
+        /// </example>
         public static DataUrlInfo Parse(string value)
             => value is null
                 ? throw new ArgumentNullException(nameof(value))
@@ -160,7 +169,7 @@ static bool HasBase64Encoding(ReadOnlySpan<char> val)
             }
         }
 
-        
+
 
         #endregion
 

src/FolkerKinzel.Uris/DataUrlInfo_RetrieveData.cs

@@ -3,6 +3,7 @@
 using System.Diagnostics.CodeAnalysis;
 using System.Linq;
 using System.Net;
+using System.Runtime.CompilerServices;
 using System.Text;
 using System.Threading.Tasks;
 using FolkerKinzel.MimeTypes;
@@ -79,6 +80,16 @@ public bool TryGetEmbeddedText([NotNullWhen(true)] out string? embeddedText)
         /// <param name="embeddedBytes">If the method returns <c>true</c> the parameter contains the binary data, which was embedded in the <see cref="DataUrlInfo"/>.
         /// The parameter is passed uninitialized.</param>
         /// <returns><c>true</c> if the data embedded in the data url could be parsed as binary data, <c>false</c> otherwise.</returns>
+        /// 
+        /// <example>
+        /// <note type="note">
+        /// For the sake of better readability, exception handling is ommitted in the example.
+        /// </note>
+        /// <para>
+        /// Creating and parsing a "data" URL:
+        /// </para>
+        /// <code language="c#" source="./../Examples/DataUrlExample.cs"/>
+        /// </example>
         public bool TryGetEmbeddedBytes([NotNullWhen(true)] out byte[]? embeddedBytes)
         {
             embeddedBytes = null;
@@ -114,8 +125,18 @@ public bool TryGetEmbeddedBytes([NotNullWhen(true)] out byte[]? embeddedBytes)
         /// period (".").
         /// </summary>
         /// <returns>An appropriate file type extension for the data embedded in the <see cref="DataUrlInfo"/>.</returns>
-        ///// <remarks>The search for a file type extension can be an expensive operation. To make subsequent calls of the method faster, the
-        ///// recent file type extensions are stored in a cache. You can call <see cref="MimeType.ClearCache"/> to clear this cache.</remarks>
+        /// <remarks>This method calls <see cref="MimeType.GetFileTypeExtension()"/>.</remarks>
+        /// 
+        ///<example>
+        /// <note type="note">
+        /// For the sake of better readability, exception handling is ommitted in the example.
+        /// </note>
+        /// <para>
+        /// Creating and parsing a "data" URL:
+        /// </para>
+        /// <code language="c#" source="./../Examples/DataUrlExample.cs"/>
+        /// </example>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public string GetFileTypeExtension() => MimeType.GetFileTypeExtension();
 
 

src/FolkerKinzel.Uris/DataUrlInfo_ctor.cs

@@ -33,6 +33,16 @@ namespace FolkerKinzel.Uris
     /// </para>
     /// </note>
     /// </remarks>
+    /// 
+    /// <example>
+    /// <note type="note">
+    /// For the sake of better readability, exception handling is ommitted in the example.
+    /// </note>
+    /// <para>
+    /// Creating and parsing a "data" URL:
+    /// </para>
+    /// <code language="c#" source="./../Examples/DataUrlExample.cs"/>
+    /// </example>
     public readonly partial struct DataUrlInfo
     {
         private DataUrlInfo(in MimeType mediaType, DataEncoding dataEncoding, in ReadOnlyMemory<char> embeddedData)