Add binary data converters

doc/topics/features.md

@@ -10,7 +10,7 @@ uid: urn:topics:features
 
 <p />
 
-The framework has built-in support for working with tabular fields as values of the following types:
+The framework has built-in support for interpreting tabular fields as values of the following types:
 
 <p />
 
@@ -45,20 +45,28 @@ The framework has built-in support for working with tabular fields as values of
 
 <p />
 
-Any generated record handler also supports type members of the `System.Nullable<T>` type with any supported value type as the underlying type. To map a type member of the `System.Byte[]` type for a generated record handler, one of the available value converters must be specified explicitly:
+To work with binary data fields, the corresponding value converter must be specified explicitly:
 
 <p />
 
-- [TabularBase16BinaryConverter](xref:Addax.Formats.Tabular.Converters.TabularBase16BinaryConverter)
-- [TabularBase64BinaryConverter](xref:Addax.Formats.Tabular.Converters.TabularBase64BinaryConverter)
+- [TabularBase16ArrayConverter](xref:Addax.Formats.Tabular.Converters.TabularBase16ArrayConverter)
+- [TabularBase64ArrayConverter](xref:Addax.Formats.Tabular.Converters.TabularBase64ArrayConverter)
+- [TabularBase16MemoryConverter](xref:Addax.Formats.Tabular.Converters.TabularBase16MemoryConverter)
+- [TabularBase64MemoryConverter](xref:Addax.Formats.Tabular.Converters.TabularBase64MemoryConverter)
+- [TabularBase16ReadOnlyMemoryConverter](xref:Addax.Formats.Tabular.Converters.TabularBase16ReadOnlyMemoryConverter)
+- [TabularBase64ReadOnlyMemoryConverter](xref:Addax.Formats.Tabular.Converters.TabularBase64ReadOnlyMemoryConverter)
+
+<p />
+
+Any generated record handler also supports type members of the `Nullable<T>` type with any supported value type as the underlying type. 
 
 <p />
 
 ### Tabular Records
 
 <p />
 
-The framework has built-in support for working with tabular records as single-dimensional arrays `T[]` or `System.Nullable<T>[]` of any supported type (except `System.Byte[]`). For example, tabular records of any file can be interpreted as string arrays, even if they have different number of fields:
+The framework has built-in support for interpreting tabular records as single-dimensional arrays `T[]` or `Nullable<T>[]` of any supported type (except binary data). For example, tabular records of any file can be interpreted as string arrays, even if the number of fields is not fixed:
 
 <p />
 

src/Addax.Formats.Tabular.Analyzers.CSharp.UnitTests/Assets/TypeMemberHasUnsupportedTypeWithConverter.cs

@@ -7,10 +7,10 @@ namespace MyNamespace;
 public struct MyType
 {
     [TabularFieldOrder(0)]
-    [TabularConverter(typeof(TabularBase16BinaryConverter))]
+    [TabularConverter(typeof(TabularBase16ArrayConverter))]
     public byte[]? MyValue0;
 
     [TabularFieldOrder(1)]
-    [TabularConverter(typeof(TabularBase64BinaryConverter))]
+    [TabularConverter(typeof(TabularBase64ArrayConverter))]
     public byte[]? MyValue1;
 }

src/Addax.Formats.Tabular/Converters/TabularBase16ArrayConverter.cs

@@ -0,0 +1,28 @@
+// (c) Oleksandr Kozlenko. Licensed under the MIT license.
+
+using System.Diagnostics.CodeAnalysis;
+
+namespace Addax.Formats.Tabular.Converters;
+
+/// <summary>Converts binary data encoded with "base16" ("hex") encoding from or to a character sequence.</summary>
+public class TabularBase16ArrayConverter : TabularConverter<byte[]?>
+{
+    internal static readonly TabularBase16ArrayConverter Instance = new();
+
+    /// <summary>Initializes a new instance of the <see cref="TabularBase16ArrayConverter" /> class.</summary>
+    public TabularBase16ArrayConverter()
+    {
+    }
+
+    /// <inheritdoc />
+    public override bool TryFormat(byte[]? value, Span<char> destination, IFormatProvider? provider, out int charsWritten)
+    {
+        return TabularBinary.TryFormatBase16(value, destination, out charsWritten);
+    }
+
+    /// <inheritdoc />
+    public override bool TryParse(ReadOnlySpan<char> source, IFormatProvider? provider, [NotNullWhen(true)] out byte[]? value)
+    {
+        return TabularBinary.TryParseBase16(source, out value);
+    }
+}

src/Addax.Formats.Tabular/Converters/TabularBase16MemoryConverter.cs

@@ -0,0 +1,33 @@
+// (c) Oleksandr Kozlenko. Licensed under the MIT license.
+
+namespace Addax.Formats.Tabular.Converters;
+
+/// <summary>Converts binary data encoded with "base16" ("hex") encoding from or to a character sequence.</summary>
+public class TabularBase16MemoryConverter : TabularConverter<Memory<byte>>
+{
+    /// <summary>Initializes a new instance of the <see cref="TabularBase16MemoryConverter" /> class.</summary>
+    public TabularBase16MemoryConverter()
+    {
+    }
+
+    /// <inheritdoc />
+    public override bool TryFormat(Memory<byte> value, Span<char> destination, IFormatProvider? provider, out int charsWritten)
+    {
+        return TabularBinary.TryFormatBase16(value.Span, destination, out charsWritten);
+    }
+
+    /// <inheritdoc />
+    public override bool TryParse(ReadOnlySpan<char> source, IFormatProvider? provider, out Memory<byte> value)
+    {
+        if (TabularBinary.TryParseBase16(source, out var array))
+        {
+            value = array;
+
+            return true;
+        }
+
+        value = default;
+
+        return false;
+    }
+}

src/Addax.Formats.Tabular/Converters/TabularBase16ReadOnlyMemoryConverter.cs

@@ -0,0 +1,33 @@
+// (c) Oleksandr Kozlenko. Licensed under the MIT license.
+
+namespace Addax.Formats.Tabular.Converters;
+
+/// <summary>Converts binary data encoded with "base16" ("hex") encoding from or to a character sequence.</summary>
+public class TabularBase16ReadOnlyMemoryConverter : TabularConverter<ReadOnlyMemory<byte>>
+{
+    /// <summary>Initializes a new instance of the <see cref="TabularBase16ReadOnlyMemoryConverter" /> class.</summary>
+    public TabularBase16ReadOnlyMemoryConverter()
+    {
+    }
+
+    /// <inheritdoc />
+    public override bool TryFormat(ReadOnlyMemory<byte> value, Span<char> destination, IFormatProvider? provider, out int charsWritten)
+    {
+        return TabularBinary.TryFormatBase16(value.Span, destination, out charsWritten);
+    }
+
+    /// <inheritdoc />
+    public override bool TryParse(ReadOnlySpan<char> source, IFormatProvider? provider, out ReadOnlyMemory<byte> value)
+    {
+        if (TabularBinary.TryParseBase16(source, out var array))
+        {
+            value = array;
+
+            return true;
+        }
+
+        value = default;
+
+        return false;
+    }
+}

src/Addax.Formats.Tabular/Converters/TabularBase64ArrayConverter.cs

@@ -0,0 +1,28 @@
+// (c) Oleksandr Kozlenko. Licensed under the MIT license.
+
+using System.Diagnostics.CodeAnalysis;
+
+namespace Addax.Formats.Tabular.Converters;
+
+/// <summary>Converts binary data encoded with "base64" encoding from or to a character sequence.</summary>
+public class TabularBase64ArrayConverter : TabularConverter<byte[]?>
+{
+    internal static readonly TabularBase64ArrayConverter Instance = new();
+
+    /// <summary>Initializes a new instance of the <see cref="TabularBase64ArrayConverter" /> class.</summary>
+    public TabularBase64ArrayConverter()
+    {
+    }
+
+    /// <inheritdoc />
+    public override bool TryFormat(byte[]? value, Span<char> destination, IFormatProvider? provider, out int charsWritten)
+    {
+        return TabularBinary.TryFormatBase64(value, destination, out charsWritten);
+    }
+
+    /// <inheritdoc />
+    public override bool TryParse(ReadOnlySpan<char> source, IFormatProvider? provider, [NotNullWhen(true)] out byte[]? value)
+    {
+        return TabularBinary.TryParseBase64(source, out value);
+    }
+}

src/Addax.Formats.Tabular/Converters/TabularBase64MemoryConverter.cs

@@ -0,0 +1,33 @@
+// (c) Oleksandr Kozlenko. Licensed under the MIT license.
+
+namespace Addax.Formats.Tabular.Converters;
+
+/// <summary>Converts binary data encoded with "base64" encoding from or to a character sequence.</summary>
+public class TabularBase64MemoryConverter : TabularConverter<Memory<byte>>
+{
+    /// <summary>Initializes a new instance of the <see cref="TabularBase64MemoryConverter" /> class.</summary>
+    public TabularBase64MemoryConverter()
+    {
+    }
+
+    /// <inheritdoc />
+    public override bool TryFormat(Memory<byte> value, Span<char> destination, IFormatProvider? provider, out int charsWritten)
+    {
+        return TabularBinary.TryFormatBase64(value.Span, destination, out charsWritten);
+    }
+
+    /// <inheritdoc />
+    public override bool TryParse(ReadOnlySpan<char> source, IFormatProvider? provider, out Memory<byte> value)
+    {
+        if (TabularBinary.TryParseBase64(source, out var array))
+        {
+            value = array;
+
+            return true;
+        }
+
+        value = default;
+
+        return false;
+    }
+}

src/Addax.Formats.Tabular/Converters/TabularBase64ReadOnlyMemoryConverter.cs

@@ -0,0 +1,33 @@
+// (c) Oleksandr Kozlenko. Licensed under the MIT license.
+
+namespace Addax.Formats.Tabular.Converters;
+
+/// <summary>Converts binary data encoded with "base64" encoding from or to a character sequence.</summary>
+public class TabularBase64ReadOnlyMemoryConverter : TabularConverter<ReadOnlyMemory<byte>>
+{
+    /// <summary>Initializes a new instance of the <see cref="TabularBase64ReadOnlyMemoryConverter" /> class.</summary>
+    public TabularBase64ReadOnlyMemoryConverter()
+    {
+    }
+
+    /// <inheritdoc />
+    public override bool TryFormat(ReadOnlyMemory<byte> value, Span<char> destination, IFormatProvider? provider, out int charsWritten)
+    {
+        return TabularBinary.TryFormatBase64(value.Span, destination, out charsWritten);
+    }
+
+    /// <inheritdoc />
+    public override bool TryParse(ReadOnlySpan<char> source, IFormatProvider? provider, out ReadOnlyMemory<byte> value)
+    {
+        if (TabularBinary.TryParseBase64(source, out var array))
+        {
+            value = array;
+
+            return true;
+        }
+
+        value = default;
+
+        return false;
+    }
+}