Merge branch 'refs/heads/develop' into publish/v2.0.2

# Conflicts:
#	Jenkinsfile

Author: EvilBeaver

src/OneScript.StandardLibrary/Collections/ArrayImpl.cs

@@ -5,16 +5,21 @@ This Source Code Form is subject to the terms of the
 at http://mozilla.org/MPL/2.0/.
 ----------------------------------------------------------*/
 
-using System.Collections.Generic;
 using OneScript.Contexts;
 using OneScript.Exceptions;
 using OneScript.Types;
 using OneScript.Values;
 using ScriptEngine.Machine;
 using ScriptEngine.Machine.Contexts;
+using System.Collections.Generic;
 
 namespace OneScript.StandardLibrary.Collections
 {
+    /// <summary>
+    /// Коллекция элементов произвольного типа.
+    /// Возможно обращение к значениям элементов по числовому индексу (нумерация начинается с 0).
+    /// Доступен обход в цикле <c>Для Каждого Из</c>.
+    /// </summary>
     [ContextClass("Массив", "Array")]
     public class ArrayImpl : AutoCollectionContext<ArrayImpl, IValue>, IValueArray
     {
@@ -24,6 +29,11 @@ public ArrayImpl()
         {
             _values = new List<IValue>();
         }
+        
+        public ArrayImpl(int capacity)
+        {
+            _values = new List<IValue>(capacity);
+        }
 
         public ArrayImpl(IEnumerable<IValue> values)
         {
@@ -56,16 +66,23 @@ public override void SetIndexedValue(IValue index, IValue val)
                 Set((int)index.AsNumber(), val);
             else
                 base.SetIndexedValue(index, val);
-        }
-
+        }
+
         #region ICollectionContext Members
-        
+
+        /// <summary>
+        /// Получает количество элементов в массиве
+        /// </summary>
+        /// <returns>Количество элементов массива</returns>
         [ContextMethod("Количество", "Count")]
         public override int Count()
         {
             return _values.Count;
-        }
-
+        }
+
+        /// <summary>
+        /// Удаляет все элементы из массива
+        /// </summary>
         [ContextMethod("Очистить", "Clear")]
         public void Clear()
         {
@@ -82,19 +99,27 @@ public override IEnumerator<IValue> GetEnumerator()
             {
                 yield return item;
             }
-        }
-
+        }
+
         #endregion
-
+
+        /// <summary>
+        /// Добавляет элемент в конец массива
+        /// </summary>
+        /// <param name="value">Произвольный: Добавляемое значение. Если не указано, то добавляется Неопределено</param>
         [ContextMethod("Добавить", "Add")]
         public void Add(IValue value = null)
         {
-            if (value == null)
-                _values.Add(ValueFactory.Create());
-            else 
-                _values.Add(value);
-        }
-
+           _values.Add(value ?? ValueFactory.Create());
+        }
+
+        /// <summary>
+        /// Вставляет значение в массив по указанному индексу
+        /// </summary>
+        /// <param name="index">Число: Индекс вставляемого значения.
+        /// Если индекс превышает размер массива, то массив дополняется элементами Неопределено до указанного индекса.
+        /// Если индекс отрицательный, то выбрасывается исключение</param>
+        /// <param name="value">Произвольный: Вставляемое значение. Если не указано, то вставляется Неопределено</param>
         [ContextMethod("Вставить", "Insert")]
         public void Insert(int index, IValue value = null)
         {
@@ -104,26 +129,27 @@ public void Insert(int index, IValue value = null)
             if (index > _values.Count)
                 Extend(index - _values.Count);
 
-            if (value == null)
-                _values.Insert(index, ValueFactory.Create());
-            else
-                _values.Insert(index, value);
+            _values.Insert(index, value ?? ValueFactory.Create());
         }
 
+        /// <summary>
+        /// Выполняет поиск элемента в массиве
+        /// </summary>
+        /// <param name="what">Произвольный: Искомое значение</param>
+        /// <returns>Если элемент найден, возвращается его индекс, иначе Неопределено</returns>
         [ContextMethod("Найти", "Find")]
         public IValue Find(IValue what)
         {
             var idx = _values.FindIndex(x => x.StrictEquals(what));
-            if(idx < 0)
-            {
-                return ValueFactory.Create();
-            }
-            else
-            {
-                return ValueFactory.Create(idx);
-            }
-        }
-
+            return idx>=0 ? ValueFactory.Create(idx) : ValueFactory.Create();    
+        }
+
+        /// <summary>
+        /// Удаляет значение из массива
+        /// </summary>
+        /// <param name="index">Число: Индекс удаляемого элемента.
+        /// Если индекс находится за границами массива, то выбрасывается исключение
+        /// </param>
         [ContextMethod("Удалить", "Delete")]
         public void Remove(int index)
         {
@@ -133,21 +159,39 @@ public void Remove(int index)
             _values.RemoveAt(index);
         }
 
+        /// <summary>
+        /// Получает наибольший индекс элемента массива
+        /// </summary>
+        /// <returns>Наибольший индекс в массиве. Если количество элементов массива равно 0, возвращает -1</returns>
         [ContextMethod("ВГраница", "UBound")]
         public int UpperBound()
         {
             return _values.Count - 1;
-        }
-
+        }
+
+        /// <summary>
+        /// Получает значение из массива по индексу
+        /// </summary>
+        /// <param name="index">Число: Индекс элемента.
+        /// Если индекс находится за границами массива, то выбрасывается исключение
+        /// </param>
+        /// <returns>Значение элемента массива</returns>
         [ContextMethod("Получить", "Get")]
         public IValue Get(int index)
         {
             if (index < 0 || index >= _values.Count)
                 throw RuntimeException.IndexOutOfRange();
 
             return _values[index];
-        }
-
+        }
+
+        /// <summary>
+        /// Устанавливает значение в массиве по индексу
+        /// </summary>
+        /// <param name="index">Число: Индекс элемента.
+        /// Если индекс находится за границами массива, то выбрасывается исключение
+        /// </param>
+        /// <param name="value">Произвольный: Устанавливаемое значение</param>
         [ContextMethod("Установить", "Set")]
         public void Set(int index, IValue value)
         {
@@ -165,20 +209,22 @@ private void Extend(int count)
             }
         }
 
-        private static void FillArray(ArrayImpl currentArray, int bound)
+        private static ArrayImpl CreateArray(int bound)
         {
+            var array = new ArrayImpl(bound);
             for (int i = 0; i < bound; i++)
             {
-                currentArray._values.Add(ValueFactory.Create());
+                array._values.Add(ValueFactory.Create());
             }
+            return array;
         }
 
-        private static IValue CloneArray(ArrayImpl cloneable)
+        private static ArrayImpl CloneArray(ArrayImpl cloneable)
         {
-            ArrayImpl clone = new ArrayImpl();
+            ArrayImpl clone = new ArrayImpl(cloneable._values.Count);
             foreach (var item in cloneable._values)
             {
-                clone._values.Add(item ?? ValueFactory.Create());
+                clone._values.Add(item is ArrayImpl arr ? CloneArray(arr) : item );
             }
             return clone;
         }
@@ -198,35 +244,37 @@ public static ArrayImpl Constructor()
         public static ArrayImpl Constructor(IValue[] dimensions)
         {
             if (dimensions.Length == 1 && dimensions[0] is FixedArrayImpl fa)
-            {
-                return Constructor(fa);
+            { 
+                    return Constructor(fa);
             }
-            
-            ArrayImpl cloneable = null;
-            for (int dim = dimensions.Length - 1; dim >= 0; dim--)
+
+            // fail fast
+            int size = 0;
+            for (int dim = 0; dim < dimensions.Length; dim++)
             {
                 if (dimensions[dim] == null)
-                    throw RuntimeException.InvalidNthArgumentType(dim + 1);
-
-                int bound = (int)dimensions[dim].AsNumber();
-                if (bound <= 0)
+                    throw RuntimeException.InvalidNthArgumentType(dim + 1);
+
+                size = (int)dimensions[dim].AsNumber();
+                if (size <= 0)
                     throw RuntimeException.InvalidNthArgumentValue(dim + 1);
-
-                var newInst = new ArrayImpl();
-                FillArray(newInst, bound);
-                if(cloneable != null)
-                {
-                    for (int i = 0; i < bound; i++)
-                    {
-                        newInst._values[i] = CloneArray(cloneable);
-                    }
-                }
-                cloneable = newInst;
-                
+            }
+
+            var newInst = CreateArray(size); // длина по последней размерности
+
+            for (int dim = dimensions.Length - 2; dim >= 0; dim--) // если размерность >= 2
+            {
+                ArrayImpl nested = newInst;
+                int bound = (int)dimensions[dim].AsNumber();
+ 
+                newInst = new ArrayImpl(bound);
+                for (int i = 0; i < bound; i++)
+                {
+                    newInst._values.Add(CloneArray(nested));
+                }
             }
 
-            return cloneable;
-
+            return newInst;
         }
 
         [ScriptConstructor(Name = "На основании фиксированного массива")]