Comparison functions

Description

Comparison functions can be used to compare data in storage. This is used for various operations, including replace, delete and others.

When doing one of these operations, a comparison function can be specified using the $listutils.function listutils.in score. This score corresponds to the ID of the function.

Default functions

By default, there are a few comparison functions already included in List Utils. These are located in the listutils.custom/functions/compare/functions/built_in directory:

ID	Function	Description
0	compare_equal	Compares two data elements and determines if they are equal.
1	compare_subset	Determines if one element is a subset of another (only works with compounds).
2	compare_data_get	Compares two data elements based on their data get value.
3	compare_longs	Compares two long data elements.
4	compare_floats	Compares two float or double data elements.

NOTE: IDs 0 to 99 should be reserverd for comparison functions native to the List Utils datapack, in case more functions are included in the future.

Custom functions

Users can create custom comparison functions for their own needs. These functions should adhere to the return values below. For more information, see the Custom functions page.

Parameters

Comparison functions compare Root.DataL and Root.DataR elements in the listutils.private:compare storage. Root.DataR always contains either the input data from the listutils:in storage or the current result value. Root.DataL always contains the element at the current index in the iteration.

Return values

The return value should be stored in the $listutils.compare.result listutils.out score. The return value of the comparison functions should depend on which data element is smaller:

Return value	Condition
0	DataL == DataR
-1	DataL < DataR
1	DataL > DataR

For functions such as compare_equal and compare_subset, the return value is 0 when the comparison returns true, and 1 otherwise.

Different return values are used in different operations. The following operations only use the return value 0 to determine if data matches:

• Contains
• Count
• Delete
• IndexOf
• Replace

The following operations use all return values -1, 0 and 1 to compare data elements:

• Sort
• Min
• Max