Added an API for handling strings from a char ndarray

- Added Shape.IsContagious
- Minor perf-ops

Author: Nucs

src/NumSharp.Core/Backends/NDArray.String.cs

@@ -0,0 +1,123 @@
+using System;
+using System.Diagnostics;
+using System.Linq;
+using System.Runtime.CompilerServices;
+using System.Threading.Tasks;
+using NumSharp.Backends;
+using NumSharp.Backends.Unmanaged;
+
+namespace NumSharp
+{
+    public partial class NDArray
+    {
+        /// <summary>
+        ///     Converts a string to a vector ndarray of bytes.
+        /// </summary>
+        /// <param name="str"></param>
+        /// <returns></returns>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static NDArray FromString(string str) => np.array(str);
+
+        /// <summary>
+        ///     Converts the entire <see cref="NDArray"/> to a string.
+        /// </summary>
+        /// <remarks>Performs a copy due to String .net-framework limitations.</remarks>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static string AsString(NDArray arr)
+        {
+            unsafe
+            {
+                Debug.Assert(arr.typecode == NPTypeCode.Char);
+                return new string((char*)arr.Address, 0, arr.size);
+            }
+        }
+
+        /// <summary>
+        ///     Get a string out of a vector of chars.
+        /// </summary>
+        /// <param name="indices"></param>
+        /// <returns></returns>
+        /// <remarks>Performs a copy due to String .net-framework limitations.</remarks>
+        public string GetString(params int[] indices)
+        {
+            unsafe
+            {
+                if (Shape.dimensions.Length - 1 != indices.Length)
+                    throw new ArgumentOutOfRangeException(nameof(indices), "GetString(int[]) can only accept coordinates that point to a vector of chars.");
+
+                Debug.Assert(typecode == NPTypeCode.Char);
+
+                UnmanagedStorage arr = Storage.GetData(indices);
+                Debug.Assert(arr.Shape.NDim == 1);
+
+                if (!Shape.IsContagious)
+                {
+                    //this works faster than cloning.
+                    var ret = new string('\0', arr.Count);
+                    fixed (char* retChars = ret)
+                    {
+                        var dst = new UnmanagedStorage(new ArraySlice<char>(new UnmanagedMemoryBlock<char>(retChars, ret.Length)), arr.Shape.Clean());
+                        MultiIterator.Assign(dst, arr);
+                    }
+
+                    return ret;
+                }
+
+                //new string always performs a copy, there is no need to keep reference to arr's unmanaged storage.
+                return new string((char*)arr.Address, 0, arr.Count);
+            }
+        }
+
+        public void SetString(string value, params int[] indices)
+        {
+            Debug.Assert(typecode == NPTypeCode.Char);
+
+            // ReSharper disable once ReplaceWithStringIsNullOrEmpty
+            if (value == null || value.Length == 0)
+                throw new ArgumentException("Value cannot be null or empty.", nameof(value));
+
+            if (Shape.dimensions.Length - 1 != indices.Length)
+                throw new ArgumentOutOfRangeException(nameof(indices), "SetString(string, int[] indices) can only accept coordinates that point to a vector of chars.");
+
+            unsafe
+            {
+                if (Shape.IsContagious)
+                {
+                    var dst = (char*)Address + Shape.GetOffset(indices);
+                    fixed (char* strChars = value)
+                    {
+                        var src = strChars;
+                        Parallel.For(0, value.Length, i => *(dst + i) = *(src + i));
+                    }
+                }
+                else
+                {
+                    fixed (char* strChars = value)
+                    {
+                        SetData(new ArraySlice<char>(new UnmanagedMemoryBlock<char>(strChars, value.Length)), indices);
+                    }
+                }
+            }
+        }
+
+        /// <summary>
+        ///     Get a string out of a vector of chars.
+        /// </summary>
+        /// <remarks>Performs a copy due to String .net-framework limitations.</remarks>
+        public string GetStringAt(int offset)
+        {
+            Debug.Assert(typecode == NPTypeCode.Char);
+            Debug.Assert(offset < Array.Count);
+
+            return GetString(Shape.GetCoordinates(offset));
+        }
+
+        public void SetStringAt(string value, int offset)
+        {
+            Debug.Assert(typecode == NPTypeCode.Char);
+            Debug.Assert(offset < Array.Count);
+
+            SetString(value, Shape.GetCoordinates(offset));
+        }
+    }
+}

src/NumSharp.Core/Creation/np.array.cs

@@ -1,6 +1,7 @@
 using System;
 using System.Linq;
 using System.Runtime.CompilerServices;
+using NumSharp.Backends;
 using NumSharp.Backends.Unmanaged;
 using NumSharp.Utilities;
 
@@ -9,10 +10,7 @@ namespace NumSharp
     public static partial class np
     {
         [MethodImpl((MethodImplOptions)768)]
-        public static NDArray array(NDArray nd, bool copy = false)
-        {
-            return copy ? new NDArray(nd.Storage.Clone()) : new NDArray(nd.Storage);
-        }
+        public static NDArray array(NDArray nd, bool copy = false) => copy ? new NDArray(nd.Storage.Clone()) : new NDArray(nd.Storage);
 
         public static NDArray array(Array array, Type dtype = null, int ndmin = 1, bool copy = true, char order = 'C')
         {
@@ -49,15 +47,27 @@ public static NDArray array(Array array, Type dtype = null, int ndmin = 1, bool
         }
 
 
-        public static NDArray array<T>(params T[] data) where T : unmanaged
+        public static NDArray array<T>(params T[] data) where T : unmanaged => new NDArray(ArraySlice.FromArray(data), Shape.Vector(data.Length));
+
+        /// <summary>
+        ///     Create a vector ndarray of type <see cref="char"/>.
+        /// </summary>
+        /// <param name="chars"></param>
+        /// <returns></returns>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static NDArray array(string chars)
         {
-            return new NDArray(ArraySlice.FromArray(data), new Shape(data.Length));
+            if (chars == null)
+                throw new ArgumentNullException(nameof(chars));
+            if (chars.Length==0)
+                return new NDArray(NPTypeCode.Char);
+            return new NDArray(ArraySlice.FromArray(chars.ToArray()), Shape.Vector(chars.Length));
         }
 
         public static NDArray array<T>(T[][] data)
         {
             var array = data.SelectMany(inner => inner).ToArray(); //todo! not use selectmany.
-            return new NDArray(array, new Shape(data.Length, data[0].Length));
+            return new NDArray(array, Shape.Matrix(data.Length, data[0].Length));
         }
 
         public static NDArray array<T>(T[][][] data)

src/NumSharp.Core/View/Shape.cs

@@ -25,6 +25,15 @@ public bool IsSliced
             get => ViewInfo != null;
         }
 
+        /// <summary>
+        ///     Does this Shape represents a non-sliced and non-broadcasted hence contagious unmanaged memory?
+        /// </summary>
+        public bool IsContagious
+        {
+            [MethodImpl(MethodImplOptions.AggressiveInlining)]
+            get => !IsSliced && !IsBroadcasted;
+        }
+
         /// <summary>
         ///     Is this Shape a recusive view? (deeper than 1 view)
         /// </summary>

test/NumSharp.UnitTest/Backends/Unmanaged/StringApiTests.cs

@@ -0,0 +1,51 @@
+using System;
+using System.Linq;
+using FluentAssertions;
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+using NumSharp.UnitTest.Utilities;
+
+namespace NumSharp.UnitTest.Backends.Unmanaged
+{
+    [TestClass]
+    public class StringApiTests
+    {
+        private static string hello = "hello";
+
+        [TestMethod]
+        public void FromString()
+        {
+            var str = NDArray.FromString(hello);
+            str.Should().BeOfType<char>().And.BeShaped(5).And.BeOfValues('h', 'e', 'l', 'l', 'o');
+        }
+
+        [TestMethod]
+        public void AsString()
+        {
+            var str = np.array('h', 'e', 'l', 'l', 'o');
+            str.Should().BeOfType<char>().And.BeShaped(5).And.BeOfValues('h', 'e', 'l', 'l', 'o');
+            NDArray.AsString(str).Should().Be(hello);
+        }
+
+        [TestMethod]
+        public void GetString()
+        {
+            var str = np.repeat(np.array('h', 'e', 'l', 'l', 'o'), 5);
+            str.Should().BeOfType<char>().And.BeShaped(5 * 5);
+            str = str.reshape(5, 5);
+            str.GetString(3).Should().Be("lllll");
+            new Action(() => { var _ = str.GetString(3, 1); }).Should().Throw<ArgumentOutOfRangeException>();
+        }
+
+        [TestMethod]
+        public void SetString()
+        {
+            var str = np.repeat(np.array('h', 'e', 'l', 'l', 'o'), 5);
+            str.Should().BeOfType<char>().And.BeShaped(5 * 5);
+            str = str.reshape(5, 5);
+
+            str.SetData(hello, 3);
+            str.GetString(3).Should().Be(hello);
+            new Action(() => { str.SetString(hello, 3, 1); }).Should().Throw<ArgumentOutOfRangeException>();
+        }
+    }
+}