Revert removal, and mark obsolete/deprecated.

Although issue #406 says to **remove** these classes, start the process by deprecating them instead.

Author: timyhac

src/libplctag/DataTypes/BoolPlcMapper.cs

@@ -0,0 +1,74 @@
+// Copyright (c) libplctag.NET contributors
+// https://github.com/libplctag/libplctag.NET
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+using libplctag.DataTypes.Extensions;
+using System;
+using System.Linq;
+
+namespace libplctag.DataTypes
+{
+
+    [Obsolete("see - https://github.com/libplctag/libplctag.NET/issues/406")]
+    public class BoolPlcMapper : IPlcMapper<bool>, IPlcMapper<bool[]>, IPlcMapper<bool[,]>, IPlcMapper<bool[,,]>
+    {
+        public int? ElementSize => 1;
+
+        public PlcType PlcType { get; set; }
+        public int[] ArrayDimensions { get; set; }
+
+        public int? GetElementCount()
+        {
+            if (ArrayDimensions == null)
+                return null;
+
+            //TODO: Test -> I'm not confident that the overall bool count is packed as a 1D array and not packed by dimension.
+            //Multiply dimensions for total elements
+            var totalElements = ArrayDimensions.Aggregate(1, (x, y) => x * y);
+            return (int)Math.Ceiling((double)totalElements / 32.0);
+        }
+
+        public int? SetArrayLength(int? elementCount) => (int)Math.Ceiling((double)elementCount.Value / 32.0);
+
+        virtual protected bool[] DecodeArray(Tag tag)
+        {
+            if (ElementSize is null)
+                throw new ArgumentNullException($"{nameof(ElementSize)} cannot be null for array decoding");
+
+            var buffer = new bool[tag.ElementCount.Value * 32];
+            for (int ii = 0; ii < tag.ElementCount.Value * 32; ii++)
+            {
+                buffer[ii] = tag.GetBit(ii);
+            }
+            return buffer;
+        }
+
+        virtual protected void EncodeArray(Tag tag, bool[] values)
+        {
+            for (int ii = 0; ii < tag.ElementCount.Value * 32; ii++)
+            {
+                tag.SetBit(ii, values[ii]);
+            }
+        }
+
+        bool IPlcMapper<bool>.Decode(Tag tag) => tag.GetUInt8(0) != 0;
+
+        void IPlcMapper<bool>.Encode(Tag tag, bool value) => tag.SetUInt8(0, value == true ? (byte)255 : (byte)0);
+
+        bool[] IPlcMapper<bool[]>.Decode(Tag tag) => DecodeArray(tag);
+
+        void IPlcMapper<bool[]>.Encode(Tag tag, bool[] value) => EncodeArray(tag, value);
+
+        bool[,] IPlcMapper<bool[,]>.Decode(Tag tag) => DecodeArray(tag).To2DArray(ArrayDimensions[0], ArrayDimensions[1]);
+
+        void IPlcMapper<bool[,]>.Encode(Tag tag, bool[,] value) => EncodeArray(tag, value.To1DArray());
+
+        bool[,,] IPlcMapper<bool[,,]>.Decode(Tag tag) => DecodeArray(tag).To3DArray(ArrayDimensions[0], ArrayDimensions[1], ArrayDimensions[2]);
+
+        void IPlcMapper<bool[,,]>.Encode(Tag tag, bool[,,] value) => EncodeArray(tag, value.To1DArray());
+
+    }
+}

src/libplctag/DataTypes/DintPlcMapper.cs

@@ -0,0 +1,22 @@
+// Copyright (c) libplctag.NET contributors
+// https://github.com/libplctag/libplctag.NET
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+using System;
+
+namespace libplctag.DataTypes
+{
+    [Obsolete("see - https://github.com/libplctag/libplctag.NET/issues/406")]
+    public class DintPlcMapper : PlcMapperBase<int>
+    {
+        public override int? ElementSize => 4;
+
+        override public int Decode(Tag tag, int offset) => tag.GetInt32(offset);
+
+        override public void Encode(Tag tag, int offset, int value) => tag.SetInt32(offset, value);
+
+    }
+}

src/libplctag/DataTypes/Extensions/ArrayExtensions.cs

@@ -0,0 +1,119 @@
+// Copyright (c) libplctag.NET contributors
+// https://github.com/libplctag/libplctag.NET
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+using System;
+using System.Collections.Generic;
+using System.Text;
+
+namespace libplctag.DataTypes.Extensions
+{
+    [Obsolete("see - https://github.com/libplctag/libplctag.NET/issues/406")]
+    public static class ArrayExtensions
+    {
+        /// <summary>
+        /// Extension method to flatten a 2D array to a 1D array
+        /// </summary>
+        /// <typeparam name="T">Array Type</typeparam>
+        /// <param name="input">2D array to be flattened</param>
+        /// <returns>1D array</returns>
+        public static T[] To1DArray<T>(this T[,] input)
+        {
+            // Step 1: get total size of 2D array, and allocate 1D array.
+            int size = input.Length;
+            T[] result = new T[size];
+
+            // Step 2: copy 2D array elements into a 1D array.
+            int write = 0;
+            for (int i = 0; i <= input.GetUpperBound(0); i++)
+            {
+                for (int z = 0; z <= input.GetUpperBound(1); z++)
+                {
+                    result[write++] = input[i, z];
+                }
+            }
+            // Step 3: return the new array.
+            return result;
+        }
+
+        /// <summary>
+        /// Extension method to flatten a 3D array to a 1D array
+        /// </summary>
+        /// <typeparam name="T">Array Type</typeparam>
+        /// <param name="input">3D array to be flattened</param>
+        /// <returns>1D array</returns>
+        public static T[] To1DArray<T>(this T[,,] input)
+        {
+            // Step 1: get total size of 3D array, and allocate 1D array.
+            int size = input.Length;
+            T[] result = new T[size];
+
+            // Step 2: copy 3D array elements into a 1D array.
+            int write = 0;
+            for (int i = 0; i <= input.GetUpperBound(0); i++)
+            {
+                for (int j = 0; j <= input.GetUpperBound(1); j++)
+                {
+                    for (int k = 0; k < input.GetUpperBound(2); k++)
+                    {
+                        result[write++] = input[i, j, k];
+                    }
+                }
+            }
+            // Step 3: return the new array.
+            return result;
+        }
+
+        /// <summary>
+        /// Extension method to reshape a 1D array into a 2D array
+        /// </summary>
+        /// <typeparam name="T">Array Type</typeparam>
+        /// <param name="input">1D array to be reshaped</param>
+        /// <param name="height">Desired height (first index) of 2D array</param>
+        /// <param name="width">Desired width (second index) of 2D array</param>
+        /// <returns>2D array</returns>
+        public static T[,] To2DArray<T>(this T[] input, int height, int width)
+        {
+            T[,] output = new T[height, width];
+
+            for (int i = 0; i < height; i++)
+            {
+                for (int j = 0; j < width; j++)
+                {
+                    output[i, j] = input[i * width + j];
+                }
+            }
+            return output;
+        }
+
+        /// <summary>
+        /// Extension method to reshape a 1D array into a 3D array
+        /// </summary>
+        /// <typeparam name="T">Array Type</typeparam>
+        /// <param name="input">1D array to be reshaped</param>
+        /// <param name="height">Desired height (first index) of 3D array</param>
+        /// <param name="width">Desired width (second index) of 3D array</param>
+        /// <param name="length">Desired length (third index) of 3D array</param>
+        /// <returns>#D array</returns>
+        public static T[,,] To3DArray<T>(this T[] input, int height, int width, int length)
+        {
+            T[,,] output = new T[height, width, length];
+
+            for (int i = 0; i < height; i++)
+            {
+                for (int j = 0; j < width; j++)
+                {
+                    for (int k = 0; k < length; k++)
+                    {
+                        output[i, j, k] = input[i * height * width + j * width + k];
+                    }
+                }
+            }
+            return output;
+        }
+
+    }
+}

src/libplctag/DataTypes/IPlcMapper.cs

@@ -0,0 +1,57 @@
+// Copyright (c) libplctag.NET contributors
+// https://github.com/libplctag/libplctag.NET
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+using System;
+
+namespace libplctag.DataTypes
+{
+    [Obsolete("see - https://github.com/libplctag/libplctag.NET/issues/406")]
+    public interface IPlcMapper<T>
+    {
+        /// <summary>
+        /// You can define different marshalling behaviour for different types
+        /// The PlcType is injected during PlcMapper instantiation, and
+        /// will be available to you in your marshalling logic
+        /// </summary>
+        PlcType PlcType { get; set; }
+
+
+        /// <summary>
+        /// Provide an integer value for ElementSize if you
+        /// want to pass this into the tag constructor
+        /// </summary>
+        int? ElementSize { get; }
+
+        /// <summary>
+        /// The dimensions of the array. Null if not an array.
+        /// </summary>
+        int[] ArrayDimensions { get; set; }
+
+        /// <summary>
+        /// This is used to convert the number of array elements
+        /// into the raw element count, which is used by the library.
+        /// Most of the time, this will be the dimensions multiplied, but occasionally
+        /// it is not (e.g. BOOL arrays).
+        /// </summary>
+        int? GetElementCount();
+
+        /// <summary>
+        /// This is the method that reads/unpacks the underlying value of the tag
+        /// and returns it as a C# type
+        /// </summary>
+        /// <param name="tag">Tag to be Decoded</param>
+        /// <returns>C# value of tag</returns>
+        T Decode(Tag tag);
+
+        /// <summary>
+        /// This is the method that transforms the C# type into the underlying value of the tag
+        /// </summary>
+        /// <param name="tag">Tag to be encoded to</param>
+        /// <param name="value">C# value to be transformed</param>
+        void Encode(Tag tag, T value);
+    }
+}

src/libplctag/DataTypes/IntPlcMapper.cs

@@ -0,0 +1,22 @@
+// Copyright (c) libplctag.NET contributors
+// https://github.com/libplctag/libplctag.NET
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+using System;
+
+namespace libplctag.DataTypes
+{
+    [Obsolete("see - https://github.com/libplctag/libplctag.NET/issues/406")]
+    public class IntPlcMapper : PlcMapperBase<short>
+    {
+        public override int? ElementSize => 2;
+
+        override public short Decode(Tag tag, int offset) => tag.GetInt16(offset);
+
+        override public void Encode(Tag tag, int offset, short value) => tag.SetInt16(offset, value);
+
+    }
+}

src/libplctag/DataTypes/LintPlcMapper.cs

@@ -0,0 +1,22 @@
+// Copyright (c) libplctag.NET contributors
+// https://github.com/libplctag/libplctag.NET
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+using System;
+
+namespace libplctag.DataTypes
+{
+    [Obsolete("see - https://github.com/libplctag/libplctag.NET/issues/406")]
+    public class LintPlcMapper : PlcMapperBase<long>
+    {
+        public override int? ElementSize => 8;
+
+        override public long Decode(Tag tag, int offset) => tag.GetInt64(offset);
+
+        override public void Encode(Tag tag, int offset, long value) => tag.SetInt64(offset, value);
+
+    }
+}

src/libplctag/DataTypes/LrealPlcMapper.cs

@@ -0,0 +1,22 @@
+// Copyright (c) libplctag.NET contributors
+// https://github.com/libplctag/libplctag.NET
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+using System;
+
+namespace libplctag.DataTypes
+{
+    [Obsolete("see - https://github.com/libplctag/libplctag.NET/issues/406")]
+    public class LrealPlcMapper : PlcMapperBase<double>
+    {
+
+        override public int? ElementSize => 8;
+
+        override public double Decode(Tag tag, int offset) => tag.GetFloat64(offset);
+
+        override public void Encode(Tag tag, int offset, double value)=> tag.SetFloat64(offset, value);
+    }
+}