Add ArraySortEx/SortADTArray natives and new sort method Sort_Random (bug 5494, r=Nextra)

Former-commit-id: 1ff337d9801e2fbd9ad210bc1285d31679b3029e

plugins/include/cellarray.inc

@@ -252,3 +252,44 @@ native ArrayDestroy(&Array:which);
  * Note that unlike the sorting.inc versions, the array passed to the callback is not in mid-sorted state.
  */
 native ArraySort(Array:array, const comparefunc[], data[]="", data_size=0);
+
+/**
+ * A faster version of ArraySort. 
+ * The sorting algorithm then uses your comparison function to sort the data.
+ *
+ * The advantage of this native is that the Array elements being compared are 
+ * directly passed into your function, instead of the item indexes that are passed by ArraySort. 
+ * This removes the need for calling ArrayGet[Cell|String|Array] every time before being 
+ * able to compare the elements.
+ * 
+ * For Arrays with a cellsize of 1 (used for storing integers and floats), 
+ * the function is called in the following manner:
+ * 
+ * public MySortFunc(Array:array, elem1, elem2, const data[], data_size)
+ *
+ *  array			- Array handle in its current un-sorted state.
+ *  elem1, elem2	- Current element pair being compared
+ *  data[]			- Extra data array you passed to the sort func.
+ *  data_size		- Size of extra data you passed to the sort func.
+ *
+ * For Arrays with a cellsize larger than 1 (used for storing arrays and strings),
+ * the function is called in the following manner:
+ *
+ * public MySortFunc(Array:array, elem1[], elem2[], const data[], data_size)
+ *
+ *  array				- Array handle in its current un-sorted state.
+ *  elem1[], elem2[]	- Current element pair being compared
+ *  data[]				- Extra data array you passed to the sort func.
+ *  data_size			- Size of extra data you passed to the sort func.
+ *
+ *
+ * In both cases your function should return:
+ *  -1 if elem1 should go before elem2
+ *   0 if elem1 and elem2 are equal
+ *   1 if elem1 should go after elem2
+ *
+ * Note that the parameters after elem2 are all optional and you do not need to specify them.
+ *
+ * Note that unlike the sorting.inc versions, the array passed to the callback is not in mid-sorted state.
+ */
+native ArraySortEx(Array:array, const comparefunc[], data[]="", data_size=0);

plugins/include/sorting.inc

@@ -1,4 +1,4 @@
-/* Sorting functions.
+	/* Sorting functions.
  *
  * by the AMX Mod X Development Team
  *
@@ -14,12 +14,25 @@
 #endif
 #define _sorting_included
 
+/**
+ * Contains sorting orders.
+ */
 enum SortMethod
 {
 	Sort_Ascending = 0,
-	Sort_Descending = 1,
+	Sort_Descending,
+	Sort_Random,
 };
 
+/**
+ * Data types for ADT Array Sorts
+ */
+enum SortType
+{
+	Sort_Integer = 0,
+	Sort_Float,
+ 	Sort_String,
+};
 /**
  * Basic sorting functions below.
  */
@@ -74,3 +87,13 @@ native SortCustom1D(array[], array_size, const comparefunc[], data[]="", data_si
  * Note that the parameters after elem2[] are all optional and you do not need to specify them.
  */
 native SortCustom2D(array[][], array_size, const comparefunc[], data[]="", data_size=0);
+
+/**
+ * Sort an ADT Array. Specify the type as Integer, Float, or String.
+ *
+ * @param array			Array Handle to sort
+ * @param order			Sort order to use, same as other sorts.
+ * @param type			Data type stored in the ADT Array
+ * @noreturn
+ */
+native SortADTArray(Array:array, SortMethod:order, SortType:type);