Table of Contents

Sort Fields

Routines to sort and compare fields within records.


  • func user_sort(integer custom_compare, sequence data, object userdata)   Sort a sequence using a user-defined comparision function.
  • func compare_fields (object RecordA, object RecordB, object Compare_Defn)   Compares two records based on a set of comparison definitions.
  • func multi_sort (sequence Data, object Sort_Defn)   Sorts a list of records by fields.


    Table of Contents

    [func]
    user_sort
    (integer custom_compare, sequence data, object userdata)

    Sort a sequence using a user-defined comparision function.

    Returns: SEQUENCE: The sorted version of data

    Category: Sort Fields

    customer_compare is the routine_id of a user defined function that returns -1, 0, or 1 to indicate the result of comparing any two elements in data. The user defined function is called as many times as required by user_sort() to order the elements in data.
    data is the sequence to sort. It contain anything and the user defined comparision function is assumed to be able to compare any two elements in the data.
    userdata is some data that is passed to the user-defined function on each call to it. It is passed unchanged as user_sort does not look at it in any way. This is used to pass some meaningful information to the user defined routine.

    Notes:

  • This sort is not "stable". That is to say, elements that are considered equal might change position relative to each other.
  • This is based directly on the sort() function supplied with Euphoria

    Example:

      sorted = user_sort(routine_id("compare_fields"), pData, "Case Insensitive")
    

    See Also: compare_fields , multi_sort



    Table of Contents

    [func]
    compare_fields
    (object RecordA, object RecordB, object Compare_Defn)

    Compares two records based on a set of comparison definitions.

    Returns: INTEGER: -1 if RecordA is 'less than' RecordB, +1 if 'greater than' and 0 if they are equal.

    Category: Sort Fields

    RecordA and RecordB are normally a sequence of fields, but this routine will handle records that are not sequences by treating them as if they were a one-field sequence.

    Compare_Defn is either a single field number or a list of field comparision definitions. Each field comparision definition is a 2-element sequence of the format {fieldnumber, fieldtype}. If fieldnumber is negative the field is compared in descending order. If fieldnumber is zero the definition is ignored. If fieldnumber is positive the field is compared in ascending sequence.
    The fieldtype can be "I" to do a case-insensitive comparision, or "N" to treat text as numeric, in which case fields are converted to numbers before comparing. If a field cannot be converted to a number it is compared as a string.

    Example:

      integer Result
    

    -- Field 2, case-sensitive text Result = compare_fields( CustA, CustB, 2) -- Field 1, case-insensitive Result = compare_fields( CustA, CustB,{ {1,"I"} }) -- Field 3, case-insensitive, then field 4, numerics, then field 2 descending Result = compare_fields( CustA, CustB,{ {3,"I"}, {4,"N"}, -2 }) -- Field 3, descending, case-insensitive Result = compare_fields( CustA, CustB,{ {-3,"I"} })

    See Also: user_sort, multi_sort



    Table of Contents

    [func]
    multi_sort
    (sequence Data, object Sort_Defn)

    Sorts a list of records by fields.

    Returns: SEQUENCE: The sorted records.

    Category: Sort Fields

    Data is the list of records to be sorted. Each record is normally a sequence of fields, but this routine will handle records that are not sequences by treating them as if they were a one-element sequence.

    Sort_Defn is either a single field number or a list of field sorting definitions. Each field sorting definition is a 2-element sequence of the format {fieldnumber, fieldtype}. If fieldnumber is negative the field is sorted in descending sequence. If fieldnumber is zero the sort definition is ignored. If fieldnumber is positive the field is sorted in ascending sequence.
    The fieldtype can be "I" to do a case-insensitive sort, or "N" to treat text as numeric, in which case fields are converted to numbers before comparing. If a field cannot be converted to a number it is compared as a string.

    Example:

      sequence sorted
    

    -- Field 2, case-sensitive text sorted = multi_sort( unsorted, 2) -- Field 1, case-insensitive sorted = multi_sort( unsorted,{ {1,"I"} }) -- Field 3, case-insensitive, then field 4, numerics, then field 2 descending sorted = multi_sort( unsorted,{ {3,"I"}, {4,"N"}, -2 }) -- Field 3, descending, case-insensitive sorted = multi_sort( unsorted,{ {-3,"I"} })

    See Also: user_sort, compare_fields