From 1d9c6bd14693123fab5fcbdd18f9f2c627226633 Mon Sep 17 00:00:00 2001
From: Ray <sympatheticfire@gmail.com>
Date: Wed, 28 Aug 2024 20:16:58 +0100
Subject: [PATCH] Added doc comments for array

---
 src/extensions/array.js | 60 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/src/extensions/array.js b/src/extensions/array.js
index 6c383dd..e551376 100644
--- a/src/extensions/array.js
+++ b/src/extensions/array.js
@@ -1,3 +1,8 @@
+/**
+ * Check is array empty.
+ * @param {Array} value Array.
+ * @returns Boolean True, if array is empty or not an array type.
+ */
 Array.isEmpty = function(value) {
   const dataType = Object.getDataType(value);
   if (dataType != "array") {
@@ -7,6 +12,12 @@ Array.isEmpty = function(value) {
   return (value.length <= 0);
 };
 
+/**
+ * Create a linear/one-dimension array of objects from an object's property.
+ * @param {*} sourceArray Source array.
+ * @param {*} propName Property name.
+ * @param {*} destArray Destination array.
+ */
 Array.toFlatten = function (sourceArray, propName, destArray) {
   for (let i=0; i<sourceArray.length; i++) {
     destArray.push(sourceArray[i]);
@@ -36,6 +47,12 @@ Array.prototype.addRange = function (array) {
   return this;
 };
 
+/**
+ * Check all match property value.
+ * @param {String} propName Property name.
+ * @param {Object} value Property value.
+ * @returns Boolean True, if all objects of property name match value.
+ */
 Array.prototype.all = function (propName, value) {
   for (let i = 0; i < this.length; i++) {
     if (propName == null) {
@@ -54,6 +71,12 @@ Array.prototype.all = function (propName, value) {
   return true;
 };
 
+/**
+ * Check any match property value.
+ * @param {String} propName Property name.
+ * @param {Object} value Property value.
+ * @returns Boolean True, if any objects of property name match value.
+ */
 Array.prototype.any = function (propName, value) {
   for (let i = 0; i < this.length; i++) {
     if (propName == null) {
@@ -72,10 +95,20 @@ Array.prototype.any = function (propName, value) {
   return false;
 };
 
+/**
+ * Create deep copy of array.
+ * @returns Array
+ */
 Array.prototype.copy = function () {
   return JSON.parse(JSON.stringify(this));
 };
 
+/**
+ * Count of objects in array with the property value.
+ * @param {*} propName Property name.
+ * @param {*} value Property value.
+ * @returns Integer Number of matches.
+ */
 Array.prototype.count = function (propName, value) {
   let result = 0;
 
@@ -96,6 +129,11 @@ Array.prototype.count = function (propName, value) {
   return result;
 };
 
+/**
+ * Count of objects in array with many matches.
+ * @param  {Object} filters Array of matches [{propName, value}].
+ * @returns Integer Number of matches.
+ */
 Array.prototype.countMany = function (...filters) {
   let result = 0;
 
@@ -122,6 +160,11 @@ Array.prototype.create = function (length, value) {
   return result
 };
 
+/**
+ * Convert this array of objects to a linear/one-dimensional array using a property.
+ * @param {*} propName Property name.
+ * @returns Array Array.
+ */
 Array.prototype.flatten = function (propName) {
   let result = [];
 
@@ -130,6 +173,23 @@ Array.prototype.flatten = function (propName) {
   return result;
 };
 
+/**
+ * Get element at index.
+ * @param {Object} index Index of element.
+ * @returns Object Element.
+ */
+Array.prototype.get = function (index) {
+  if (index < 0) {
+    return "";
+  }
+
+  if (index >= this.length) {
+    return "";
+  }
+
+  return this[index];
+};
+
 /**
  * Find index of first occurrence of value in property.
  * @param {string} propName Property name.