When one sorts an array using the sort instance method of JavaScript's Array object, the sort method compares the raw values of the array's elements - unless one specifies a custom comparison function.

When one does specify a comparison function, it may be called many times to compare the same value to some other value. If it is necessary to derive a value for use in the comparison, rather than simply using the raw value for an element, then the code to derive a value to be used in the comparison might be executed redundantly many times. This can be particularly costly when sorting a large array and where the code to derive a value for comparison involves more significant processing.

To illustrate this point, consider the example of a case-insensitive sort. If one simply uses the Array object's sort instance method, then one might write the sort code as follows...

POOR PERFORMANCE

firstNames.sort (function (a,b) {return a.toLowerCase () < b.toLowerCase () ? -1 : 1});

In the above example, the toLowerCase instance method of the Array object is being used to convert both string values being compared to lower case - this ensures that the case of individual characters in the two strings has no effect on the sort order, and the sort is thereby made case-insensitive. Problem is, the toLowerCase method may be called multiple times for the same element, just because of how the sort method is implemented. This could become a very serious performance problem when sorting large arrays of very long strings using this approach. This is where the Uize.Array.Sort.sortBy method comes in. Using this method, the above example could be rewritten as follows...

IMPROVED PERFORMANCE

Uize.Array.Sort.sortBy (firstNames,'value.toLowerCase ()');

Now that we're using the Uize.Array.Sort.sortBy method, we no longer specify a comparison function. Instead, we're specifying the string 'value.toLowerCase ()' as a sort value generator expression. This expression will be used for every element of the array being sorted. The array will then be sorted using the sort values generated for each of the array's elements. Instead of using the array's element values in the comparison function, the Uize.Array.Sort.sortBy method will use the generated sort values. This means that the toLowerCase method is guaranteed to only be called once for every element of the array.

A sort value generator function is a sort value generator specified in the form of a function.

When a function is specified for the Sort Value Generator, it should expect to receive two parameters: the value for an element of the array being sorted, and the index / key for that element. The function should return the generated sort value. Generated sort values should be of a type that can be used with the boolean less than and greater than comparison operators - numbers and strings are the typical types that are appropriate for generated sort values. This is all illustrated well in the following example...

EXAMPLE

Uize.Array.Sort.sortBy (names,function (value,key) {return value.toLowerCase ()});

In the above example, the names array is an array of string values. It is being sorted in ASCIIbetical order, using a Sort Value Generator Function that renders the sort case-insensitive. The function accepts value and key parameters, using the value parameter to generate a sort value that is an element's value converted to all lower case. As you'll notice, the function is not actually using the key parameter, so it could just as well be omitted, as follows...

WITHOUT THE KEY PARAMETER

Uize.Array.Sort.sortBy (names,function (value) {return value.toLowerCase ()});

For an example of how an element's key might be used in generating sort values, see the section Using an Element's Key To Generate a Sort Value.

A sort value generator expression is a sort value generator specified in the form of an expression string.

When an expression string is specified for the Sort Value Generator, it should expect two variables to be defined in the scope of the expression's code: the value variable contains the value for an element of the array being sorted, and the key variable contains that element's index / key. The expression should produce the generated sort value. Generated sort values should be of a type that can be used with the boolean less than and greater than comparison operators - numbers and strings are the typical types that are appropriate for generated sort values. This is all illustrated well in the following example...

EXAMPLE

Uize.Array.Sort.sortBy (names,'value.toLowerCase ()');

In the above example, the names array is an array of string values. It is being sorted in ASCIIbetical order, using a Sort Value Generator Expression that renders the sort case-insensitive. The expression is using the value variable to generate a sort value that is an element's value converted to all lower case. As you'll notice, using a sort value generator expression can be more concise than using a sort value generator function. And since you're just specifying a JavaScript expression and not defining a function, there is no return statement in the expression.

You'll also notice that the expression is not using the key variable in generating the sort value. For an example of how an element's key might be used in generating sort values, see the section using an element's key to generate a sort value.

The key for an element is very seldom used when performing a sort using the Uize.Array.Sort.sortBy method, but the following hypothetical example demonstrates how it might be used...

USING THE KEY

Uize.Array.Sort.sortBy (values,'key + (key % 2 ? ' + names.length + ' : 0)');

In the above example, the values array is being "sorted" so that all even numbered elements are clumped at the beginning and all odd numbered elements are clumped at the end. So, if the contents of the values array was ['a','b','c','d','e','f','g','h'], then the sorted values would be ['a','c','e','g','b','d','f','h']. The reason this works is because the generated sort value is the key for even numbered elements, and the key plus the length of the array for odd numbered elements, achieved by using the % (mod) operator with a ternary operator expression. This preserves the order of the elements within the even numbered and odd numbered clumps of elements, but pushes all the odd numbered elements to after the even numbered elements. Generated sort values are not required to map in any way to the indexes of elements in the array being sorted, so it's ok than the sort values in this case extend beyond the length of the array, and that there are gaps between consecutive sort values.

When the values of an array's elements are not used when generating sort values, then what you're doing is more like a reordering algorithm than a sort. Of course, there's no saying you can't use both the value and the index / key for elements when generating sort values.

BEFORE

firstNames.sort (function (a,b) {return a.toLowerCase () < b.toLowerCase () ? -1 : 1});

AFTER

Uize.Array.Sort.sortBy (names,'value.toLowerCase ()');

BEFORE

table.sort (function (a,b) {return a [1] < b [1] ? -1 : 1});

AFTER

Uize.Array.Sort.sortBy (table,1);

BEFORE

records.sort (function (a,b) {return a.name < b.name ? -1 : 1});

AFTER

Uize.Array.Sort.sortBy (records,'value.name');

An array of strings can be sorted by length with a simple sort value generator expression that returns the value of the length property of a value.

EXAMPLE

Uize.Array.Sort.sortBy (strings,'value.length');

A records array, where each element is an object containing data for a person, can be sorted by last name with a simple sort value generator expression that returns the value of the lastName property of a value.

EXAMPLE

Uize.Array.Sort.sortBy (peopleRecords,'value.lastName');

A records array, where each element is an object containing data for a person, can be sorted by last name and subsorted by first name, with a sort value generator expression that concatenates the values of the lastName and firstName properties of a value.

EXAMPLE

Uize.Array.Sort.sortBy (peopleRecords,'value.lastName + "," + value.firstName');

Notice that a "," (comma character) is used as a delimiter between last name and first name. This is in order to avoid ambiguities that may arise if a first segment of one person's last name is coincidentally a last segment of someone else's first name. The comma forces a reliable split between the sort and subsort, because nobody's first or last name will contain a comma.

A rows array, where each element is an array representing a row of data in a data table, can be sorted by a specific column simply by specifying the column number for the Uize.Array.Sort.sortBy method's sortColumnINT parameter.

EXAMPLE

Uize.Array.Sort.sortBy (rows,1);

Column indexes are zero based, so specifying the value 1 in the above example will sort the rows data table array by the values in the second column.

An array of strings that are decimal formatted numbers can be sorted numerically (rather than ASCIIbetically), by specifying a simple sort value generator expression that returns an element's value coerced to a number.

EXAMPLE

Uize.Array.Sort.sortBy (numberStrings,'+value');

Coercing the string type element values to numbers is accomplished quite easily by simply prefixing the "+" (plus) operator in the expression.

An array of strings that are hexadecimal formatted numbers can be sorted numerically (rather than ASCIIbetically), by specifying a simple sort value generator expression that returns an element's value coerced to a decimal number.

EXAMPLE

Uize.Array.Sort.sortBy (hexNumberStrings,'+("0x" + value)');

It is assumed in this example that the hex formatted numbers are not prefixed with any kind of hex formatting indicator (such as "0x" for programming languages, or "#" for RGB color values in CSS). The hex numbers are coerced to decimal by prepending the "0x" and then coercing the resulting string to a number by prefixing the "+" (plus) operator in the sort value generator expression.

An array of correctly formatted date strings can be sorted into chronological order, by specifying a sort value generator expression that transforms a date string value into a number, representing the date as the number of milliseconds elapsed since January 1st, 1970 (i.e. POSIX time).

EXAMPLE

Uize.Array.Sort.sortBy (dateStrings,'+(new Date (value))');

A date string value is transformed into a POSIX time number by first using JavaScript's built-in Date object to parse the date string and create a Date object instance. The Date object instance is then coerced to a number by using the "+" (plus) operator, which invokes the Date object's valueOf Intrinsic Method.

An array of Date object instances can be sorted into chronological order, by specifying a sort value generator expression that transforms a Date object instance into a number, representing the date as the number of milliseconds elapsed since January 1st, 1970 (i.e. POSIX time).

EXAMPLE

Uize.Array.Sort.sortBy (dateObjects,'+value');

A Date object instance is transformed into a POSIX time number by simply using the "+" (plus) operator, which invokes the Date object's valueOf Intrinsic Method.

An array of objects representing geometric cubes can be sorted according to their volumes, from smallest volume to largest volume, by specifying a sort value generator expression that calculates the volume for a cube from its width, height, and depth properties.

EXAMPLE

Uize.Array.Sort.sortBy (cubes,'value.width * value.height * value.depth');

Each value of the cubes array is an object containing width, height, and depth properties that describe a cube's dimensions. A sort value generator expression can calculate the volume for an element of the cubes array by dereferencing the width, height, and depth properties on the value variable and multiplying them together.

An array of objects representing rectangles can be sorted according to their squareness, from most square to least square, by specifying a sort value generator expression that calculates an aspect ratio for a rectangle from its width and height properties.

EXAMPLE

Uize.Array.Sort.sortBy (
  rectangles,
  'Math.max (value.width,value.height) / Math.min (value.width,value.height)'
);

Each value of the rectangles array is an object containing width and height properties that describe a rectangle's dimensions. A sort value generator expression can calculate the aspect ratio for an element of the rectangles array by dereferencing the width and height properties of the value variable and dividing the maximum axis dimension by the minimum axis dimension.

According to this calculation, a perfectly square rectangle will have an aspect ratio of 1. The more unsquare a rectangle is, the higher the calculated aspect ratio value. By always dividing the maximum axis dimension by the minimum axis dimension, the aspect ratio is guaranteed to always be 1 or greater, rather than being less than 1 for rectangles whose width is smaller than their height (i.e. where orientation is landscape rather than portrait). Now, sorting the generated sort values into ascending order, the elements of the rectangles array are sorted according to how close to square they are.

An array of numbers can be sorted according to how close they are to a reference number, from closest to furthest away, by specifying a sort value generator expression that calculates for a number its absolute distance from the reference number.

EXAMPLE

Uize.Array.Sort.sortBy (numbers,'Math.abs (' + referenceNumber + ' - value)');

Because we are using a sort value generator expression rather than a sort value generator function in our example, we can fix the value of the referenceNumber variable into the expression using string concatenation. We use the Math.abs method of JavaScript's built-in Math object to ensure that the calculated distance is always positive - this ensures that numbers are sorted based on their closeness to the reference number, regardless of on which side of the reference number they fall. Now, sorting the generated sort values into ascending order, the elements of the numbers array are sorted according to how close they are to the reference number.

An array of strings can be sorted into case-insensitive ASCIIbetical order, by specifying a sort value generator expression that generates a lower case version of a string value.

EXAMPLE

Uize.Array.Sort.sortBy (names,'value.toLowerCase ()');

In this example, when the elements of the names array are sorted according to the lower case, generated sort values, the elements are effectively sorted in a case-insensitive manner, since all the letters of all the sort value strings are guaranteed to be lower case.

An array of objects representing RGB colors can be sorted according to their blackness, from blackest to whitest, by specifying a sort value generator function that calculates the distance of a color from black in three dimensional RGB color space.

EXAMPLE

Uize.Array.Sort.sortBy (
  rgbColorObjects,
  function (rgb) {
    return Math.sqrt (
      Math.pow (Math.sqrt (Math.pow (rgb.red,2) + Math.pow (rgb.green,2)),2) +
      Math.pow (rgb.blue,2)
    );
  }
);

Each value of the rgbColorObjects array is an object containing red, green, and blue properties that indicate the values of the three RGB color channels for a color. A sort value generator function can calculate a color's distance from black in three dimensional RGB color space by simply treating the color channels as dimensions like width, height, and depth.

Calculating distance in three dimensional space involves two successive hypotenuse-of-a-triangle calculations (square root of the sum of the squares) - the first calculates a distance in two of the three dimensions, and the second uses the first distance as one of the sides of a right angled triangle to calculate the final distance in three dimensional space. Our calculation in the sort value generator function is made simpler by the fact that our reference color is black, which is represented by zeros for each of the color channels, so there is no delta calculation needed for each of the color channels.

The order of the elements in an array can be randomly shuffled, by specifying a sort value generator function that generates a random number.

EXAMPLE

Uize.Array.Sort.sortBy (elements,Math.random);

Randomly shuffling the order of elements in an array is not influenced by the values of the elements, nor is this process influenced by the original order of the elements, so we use neither the value nor the key variable in our expression. Instead, we simply supply a sort value generator function that doesn't expect any input parameters and that always returns a random number. The Math.random method of JavaScript's built-in Math object fits the bill. Sorting the array using a set of randomly generated sort values has the effect of randomly shuffling the order of the elements in the array.

While the above technique works, it's worth noting that a better performing way of shuffling the elements of an array is to use the Uize.Array.Order.jumble static method of the Uize.Array.Order module.

The order of the elements in an array can be reversed, by specifying a sort value generator expression that subtracts the index for an element from the length of the array.

EXAMPLE

Uize.Array.Sort.sortBy (elements,elements.length + ' - key');

Because we are using a sort value generator expression rather than a sort value generator function in our example, we can fix the array's length into the expression using string concatenation. Reversing the order of elements in an array is not influenced by the values of the elements, so we don't use the value variable in our expression. Instead, we use the key variable and subtract that from the array's length. This results in sort values that descend in value, starting from the length of the array for the first element, and ending with the value 1 for the last element. Sorting the array using these sort values has the effect of reversing the order of the elements.

While the above technique works, it's worth noting that a better performing way of reversing the order of the elements of an array is to use the Uize.Array.Order.reverse static method of the Uize.Array.Order module, or the reverse instance method of JavaScript's built-in Array object.

It should also be noted that the order of the elements in an array can be reversed by specifying the value -1 for the Uize.Array.Sort.sortBy method's optional directionINT parameter, as follows...

Uize.Array.Sort.sortBy (elements,'key',-1);

When we use the directionINT parameter to reverse the sort direction, we no longer need to use the array's length in the sort value generator expression. Instead, we can have a simpler expression that simply returns the key / index.