org.apache.poi.ss.formula.functions

Class Match

java.lang.Object

org.apache.poi.ss.formula.functions.Match

All Implemented Interfaces:

Function, Function2Arg, Function3Arg

public final class Match
extends java.lang.Object

Implementation for the MATCH() Excel function.

Syntax:
MATCH(lookup_value, lookup_array, match_type)

Returns a 1-based index specifying at what position in the lookup_array the specified lookup_value is found.

Specific matching behaviour can be modified with the optional match_type parameter.

match_type parameter description

Value	Matching Behaviour
1	(default) find the largest value that is less than or equal to lookup_value. The lookup_array must be in ascending order*.
0	find the first value that is exactly equal to lookup_value. The lookup_array can be in any order.
-1	find the smallest value that is greater than or equal to lookup_value. The lookup_array must be in descending order*.

* Note regarding order - For the match_type cases that require the lookup_array to be ordered, MATCH() can produce incorrect results if this requirement is not met. Observed behaviour in Excel is to return the lowest index value for which every item after that index breaks the match rule.
The (ascending) sort order expected by MATCH() is:
numbers (low to high), strings (A to Z), boolean (FALSE to TRUE)
MATCH() ignores all elements in the lookup_array with a different type to the lookup_value. Type conversion of the lookup_array elements is never performed.

Constructor Summary

Constructors

Constructor and Description
Match()

Method Summary

Modifier and Type	Method and Description
ValueEval	evaluate(int srcRowIndex, int srcColumnIndex, ValueEval arg0, ValueEval arg1) see Function.evaluate(ValueEval[], int, int)
ValueEval	evaluate(int srcRowIndex, int srcColumnIndex, ValueEval arg0, ValueEval arg1, ValueEval arg2) see Function.evaluate(ValueEval[], int, int)
ValueEval	evaluate(ValueEval[] args, int srcRowIndex, int srcColumnIndex)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Match

public Match()

Method Detail

evaluate

public ValueEval evaluate(int srcRowIndex,
                          int srcColumnIndex,
                          ValueEval arg0,
                          ValueEval arg1)

Description copied from interface: Function2Arg

see Function.evaluate(ValueEval[], int, int)

evaluate

public ValueEval evaluate(int srcRowIndex,
                          int srcColumnIndex,
                          ValueEval arg0,
                          ValueEval arg1,
                          ValueEval arg2)

Description copied from interface: Function3Arg

see Function.evaluate(ValueEval[], int, int)

evaluate

public final ValueEval evaluate(ValueEval[] args,
                                int srcRowIndex,
                                int srcColumnIndex)

Specified by:

evaluate in interface Function

Parameters:

args - the evaluated function arguments. Empty values are represented with BlankEval or MissingArgEval, never null.

srcRowIndex - row index of the cell containing the formula under evaluation

srcColumnIndex - column index of the cell containing the formula under evaluation

Returns:

The evaluated result, possibly an ErrorEval, never null. Note - Excel uses the error code #NUM! instead of IEEE NaN, so when numeric functions evaluate to Double.NaN be sure to translate the result to ErrorEval.NUM_ERROR.