Sorts the specified vector according to the order induced by the keys generated for each element by the specified key subquery. The keys are compared as described in compare() function.

Effectively, the element comparator that determines the order of the vector may be expressed as the following:


compare (keyQuery(elem1), keyQuery(elem2))

Parameters:

v

The vector to be sorted.
elemVar
The reference to the variable to which the element is assigned to pass it to the key subquery so as to generate the element's sorting key.

The variable reference must be produced using '@' operator (see examples below).

keyQuery
Specifies the subquery to be executed for each vector element so as the result produced by the subquery to be used as the element's sorting key.

The subquery should be prepared using FlexQuery() function (see examples below).

unique
Specifies whether the result vector must contain only elements with the unique keys.

If true all elements with the repeating (according to compare() function) keys will be removed; if false all original elements will be present in the result vector.

When this parameter is omitted, it is assumed to be false.

Returns:

The same vector object received in the function parameter with the elements in the new-sorted order. No new vector is created!

Note: If the passed vector object is null, the function does nothing and returns null.

See Also:

compare(), FlexQuery(), reverseVector(), filterVector()

Example 1:

The following expression sorts a vector containing string representations of numbers according to the number values and prints the result vector to the system console:


// the original vector
v = Vector ("5", "103", "12", "1");

// sorting the vector
v.sortVector (
  @elem, 
  FlexQuery (toNumber(elem))
);

echo (v) // print the result vector

Example 2:

The original vector contains strings each of which is started with a certain letter followed by a certain number. We want to sort those strings so as the letter parts are ordered lexicographically and numbers parts as numbers.

The following expression does such a sorting and prints the result vector to the system console:


// the original vector
v = Vector ("B5", "C103", "C12", "A1", "B5");

// sorting the vector
v.sortVector (
  @elem,
  FlexQuery ({
    s = toString(elem);
    Array (
      s.charAt(0), 
      s.substring(1).toNumber()
    )
  }),
  true
);

// print the result vector, which will be:
// { "A1", "B5", "C12", "C103" }

echo (v)