Add string_compare function and support integer return type in array_…

…sort function (#1374)

* Add string_compare function

* Support integer return type in array_sort closure

* Add string_compare_ic function

src/main/java/com/laytonsmith/core/functions/ArrayHandling.java

@@ -1828,9 +1828,12 @@ private CArray merge(CArray left, CArray right, CClosure closure, Target t) {
 						} else {
 							value = -1;
 						}
+					} else if(c.isInstanceOf(CInt.TYPE)) {
+						long longVal = ((CInt) c).getInt();
+						value = (longVal > 0 ? 1 : (longVal < 0 ? -1 : 0));
 					} else {
 						throw new CRECastException("The custom closure did not return a value (or returned an invalid"
-								+ " type). It must always return true, false, or null.", t);
+								+ " type). It must always return true, false, null, or an integer.", t);
 					}
 					if(value <= 0) {
 						result.push(left.get(0, t), t);
@@ -1882,10 +1885,10 @@ public String docs() {
 					+ " operation. Due to this, it has slightly different behavior than array_normalize, which could"
 					+ " have also been implemented in place.\n\nIf the sortType is a closure, it will perform a"
 					+ " custom sort type, and the array may contain any values, including sub array values. The closure"
-					+ " should accept two values, @left and @right, and should return true if the left value is larger"
-					+ " than the right, and false if the left value is smaller than the right, and null if they are"
-					+ " equal. The array will then be re-ordered using a merge sort, using your custom comparator to"
-					+ " determine the sort order.";
+					+ " should accept two values, @left and @right, and should return true or a positive integer if the"
+					+ " left value is larger than the right, and false or a negative integer if the left value is"
+					+ " smaller than the right, and null or 0 if they are equal. The array will then be re-ordered"
+					+ " using a merge sort, using your custom comparator to determine the sort order.";
 		}
 
 		@Override

src/main/java/com/laytonsmith/core/functions/StringHandling.java

@@ -2298,6 +2298,104 @@ public ExampleScript[] examples() throws ConfigCompileException {
 
 	}
 
+	@api
+	public static class string_compare extends AbstractFunction {
+
+		@Override
+		@SuppressWarnings("unchecked")
+		public Class<? extends CREThrowable>[] thrown() {
+			return new Class[]{};
+		}
+
+		@Override
+		public boolean isRestricted() {
+			return false;
+		}
+
+		@Override
+		public Boolean runAsync() {
+			return null;
+		}
+
+		@Override
+		public Mixed exec(Target t, Environment environment, Mixed... args) throws ConfigRuntimeException {
+			return new CInt(args[0].val().compareTo(args[1].val()), t);
+		}
+
+		@Override
+		public String getName() {
+			return "string_compare";
+		}
+
+		@Override
+		public Integer[] numArgs() {
+			return new Integer[]{2};
+		}
+
+		@Override
+		public String docs() {
+			return "int {string s1, string s2} Compares two strings lexicographically."
+					+ " The comparison is based on the Unicode value of each character in the strings."
+					+ " Returns 0 if s1 is equal to s2, a negative value if s1 is lexographically less than s2,"
+					+ " and a positive value if s1 is lexigraphically greater than s2."
+					+ " The magnitude of non-zero return values is the difference between the char values at the first"
+					+ " index at which a different char was found in both strings."
+					+ " If all chars match but the strings differ in length, then the magnitude is this difference.";
+		}
+
+		@Override
+		public Version since() {
+			return MSVersion.V3_3_5;
+		}
+
+		@Override
+		public ExampleScript[] examples() throws ConfigCompileException {
+			return new ExampleScript[]{
+				new ExampleScript("", "string_compare('axx', 'bxx')"),
+				new ExampleScript("", "string_compare('xbx', 'xax')"),
+				new ExampleScript("", "string_compare('abc', 'abc')"),
+				new ExampleScript("", "string_compare('abc', 'abcde')")
+			};
+		}
+	}
+
+	@api
+	public static class string_compare_ic extends string_compare {
+
+		@Override
+		public Mixed exec(Target t, Environment environment, Mixed... args) throws ConfigRuntimeException {
+			return new CInt(args[0].val().compareToIgnoreCase(args[1].val()), t);
+		}
+
+		@Override
+		public String getName() {
+			return "string_compare_ic";
+		}
+
+		@Override
+		public String docs() {
+			return "int {string s1, string s2} Compares two strings lexicographically ignoring casing."
+					+ " The comparison is based on the Unicode value of each character in the strings."
+					+ " Returns 0 if s1 is equal to s2, a negative value if s1 is lexographically less than s2,"
+					+ " and a positive value if s1 is lexigraphically greater than s2."
+					+ " The magnitude of non-zero return values is the difference between the char values at the first"
+					+ " index at which a different char was found in both strings."
+					+ " If all chars match but the strings differ in length, then the magnitude is this difference.";
+		}
+
+		@Override
+		public ExampleScript[] examples() throws ConfigCompileException {
+			return new ExampleScript[]{
+				new ExampleScript("", "string_compare_ic('axx', 'bxx')"),
+				new ExampleScript("", "string_compare_ic('Axx', 'bxx')"),
+				new ExampleScript("", "string_compare_ic('axx', 'Bxx')"),
+				new ExampleScript("", "string_compare_ic('xbx', 'xax')"),
+				new ExampleScript("", "string_compare_ic('abc', 'abc')"),
+				new ExampleScript("", "string_compare_ic('abc', 'abcde')")
+			};
+		}
+	}
+
 	@api
 	public static class string_multiply extends AbstractFunction {