Add checks and logic to support sort operation for tuples at runtime

[ravinperera00]

Purpose

Currently the sort operation is not supported for tuples at runtime. It is essential to support all the operations that are supported for arrays to tuples as well since tuples are a subtype of arrays.

Fixes #43029

Approach

The method definition for the sort operation is as follows.

# Sorts an array.
# If the member type of the array is not ordered, then the `key` function
# must be specified.
# Sorting works the same as with the `sort` clause of query expressions.
#
# + arr - the array to be sorted; 
# + direction - direction in which to sort
# + key - function that returns a key to use to sort the members
# + return - new array consisting of the members of `arr` in sorted order
public isolated function sort(Type[] arr, SortDirection direction = ASCENDING,
        (isolated function(Type val) returns OrderedType)? key = ()) returns Type[] = external;

One of the major problems with enabling sorting for tuples is the handling of comparison between more than one data type during sorting. According to the definition, a key function is provided for this reason, if the members don't belong to a single orderedType.

The definition of OrderedType is as follows,

# A type of which any ordered type must be a subtype.
# Whether a type is an ordered type cannot be defined in
# terms of being a subtype of a type, so being a subtype
# of `OrderedType` is a necessary but not sufficient condition
# for a type to be an ordered type.
public type OrderedType ()|boolean|int|float|decimal|string|OrderedType[];

The sort operation should allow any member type to be present (regardless of whether the type belongs to an OrderedType or not) within the tuple as long as a key function is provided when needed (if all the members don't belong to a single OrderedType). Any error that is occurred during the operation will cause a panic. The runtime shall implement checks and logic need to verify if a given type is an OrderedType and whether the operation required a key function. Once the necessary conditions are met, the operation will sort the given tuple and provide a new sorted array with a union type that covers the types of the members in the tuple.

Samples

Example without a key function

public function main() {
    [int, int, int, int, int] tup = [1, 7, 15, 5, 46];
    int[] res = tup.sort("descending");          // [46, 15, 7, 5, 1]
}

Example with a key function

isolated function keyFunc(int|float arg1) returns int {
    if(arg1 is float) {
        return <int>arg1;
    } else if (arg1 is int) {
        return arg1;
    }
}

public function main() {
    [int, int, int, float, int] tup = [1, 7, 15, 1.5, 46];
    (int|float)[] res = tup.sort("descending", keyFunc);          // [46, 15, 7, 1.5, 1]
}

Remarks

This PR is contributing to #41431

Check List

• Read the Contributing Guide
• Updated Change Log
• Checked Tooling Support (#)
• Added necessary tests
  • Unit Tests
  • Spec Conformance Tests
  • Integration Tests
  • Ballerina By Example Tests
• Increased Test Coverage
• Added necessary documentation
  • API documentation
  • Module documentation in Module.md files
  • Ballerina By Examples

[codecov]

Codecov Report

Attention: Patch coverage is 92.53731% with 5 lines in your changes missing coverage. Please review.

Project coverage is 77.51%. Comparing base (c554de8) to head (20e8d79).
Report is 160 commits behind head on master.

Files with missing lines	Patch %	Lines
...g/ballerinalang/langlib/array/utils/SortUtils.java	90.74%	2 Missing and 3 partials ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##             master   #43290      +/-   ##
============================================
+ Coverage     77.49%   77.51%   +0.01%     
- Complexity    58576    58625      +49     
============================================
  Files          3438     3439       +1     
  Lines        219211   219299      +88     
  Branches      28913    28937      +24     
============================================
+ Hits         169880   169986     +106     
+ Misses        39914    39892      -22     
- Partials       9417     9421       +4     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[warunalakshitha]

LGTM

[HindujaB]

LGTM

[gimantha]

@ravinperera00 This change can affect the order by clause in query expression as well. So shall we add few tests for sorting tuples with query expressions as well?