This is an interface that must be implemented by consumers.  It allows consumers to add  aggregate functions that are available to SQL queries and triggers.  An aggregate function is a function that returns one value from a series of values.  There are a number of already defined aggregate functions provided by SQLite.  Objects implementing this interface can be registered with mozIStorageConnection.createAggregateFunction().

Inherits from: nsISupports

Method overview

Methods

onStep()

This is called for each row of results returned by the query.  The implementation should store or perform some work to prepare to return a value.

void onStep(
  in mozIStorageValueArray aFunctionArguments
);

Parameters

aFunctionArguments

A mozIStorageValueArray holding the arguments passed in to the function.

onFinal()

This is called after all results have been obtained and notified via mozIStorageAggregateFunction.  The implementation should finish its calculations on the data, and return a result.

nsIVariant onFinal()

Return value

An nsIVariant this is the return value of the function.

Sample Code

Both of the following code samples assume that the variable dbConn is an opened mozIStorageConnection.

JavaScript

// First, create our object that will represent our function.
var standardDeviationFunc = {
  _numbers: [],
  onStep: function(aArguments) {
    this._numbers.push(aArguments.getInt32(0));
  },
  onFinal: function() {
    let total = 0;
    let iLength = this._numbers.length;
    this._numbers.forEach(function(elt) { total += elt });
    let mean = total / this._numbers.length;
    let data = this._numbers.map(function(elt) {
      let value = elt - mean;
      return value * value;
    });
    total = 0;
    data.forEach(function(elt) { total += elt });
    this._numbers = [];
    return Math.sqrt(total / iLength);
  }
};

// Now, register our function with the database connection.
dbConn.createAggregateFunction("stdDev", 1, standardDeviationFunc);

// Run some query that uses the function.
let stmt = dbConn.createStatement("SELECT stdDev(value) FROM some_table");
try {
  while (stmt.executeStep()) {
    // handle the results
  }
}
finally {
  stmt.reset();
}

C++

// First, create our class that will represent our function.
class standardDeviationFunc : public mozIStorageAggregateFunction
{
public:
  NS_IMETHOD OnStep(mozIStorageValueArray *aArguments)
  {
    PRInt32 value;
    nsresult rv = aArguments->GetInt32(&value);
    NS_ENSURE_SUCCESS(rv, rv);

    mNumbers.AppendElement(value);
  }

  NS_IMETHOD OnFinal(nsIVariant **_result)
  {
    PRInt64 total = 0;
    for (PRUint32 i = 0; i < mNumbers.Length(); i++)
      total += mNumbers[i];
    PRInt32 mean = total / mNumbers.Length();

    nsTArray<PRInt64> data(mNumbers);
    for (PRUint32 i = 0; i < data.Length(); i++) {
      PRInt32 value = data[i] - mean;
      data[i] = value * value;
    }

    total = 0;
    for (PRUint32 i = 0; i < data.Length(); i++)
      total += data[i];

    nsCOMPtr<nsIWritableVariant> result =
      do_CreateInstance("@mozilla.org/variant;1");
    NS_ENSURE_TRUE(result, NS_ERROR_OUT_OF_MEMORY);

    rv = result->SetAsDouble(sqrt(double(total) / double(data.Length())));
    NS_ENSURE_SUCCESS(rv, rv);

    NS_ADDREF(*_result = result);
    return NS_OK;
  }
private:
  nsTArray<PRInt32> mNumbers;
};

// Now, register our function with the database connection.
nsCOMPtr<mozIStorageFunction> func = new standardDeviationFunc();
NS_ENSURE_TRUE(func, NS_ERROR_OUT_OF_MEMORY);
nsresult rv = dbConn->CreateFunction(
  NS_LITERAL_CSTRING("stdDev"),
  1,
  func
);
NS_ENSURE_SUCCESS(rv, rv);

// Run some query that uses the function.
nsCOMPtr<mozIStorageStatement> stmt;
rv = dbConn->CreateStatement(NS_LITERAL_CSTRING(
  "SELECT stdDev(value) FROM some_table"),
  getter_AddRefs(stmt)
);
NS_ENSURE_SUCCESS(rv, rv);
PRBool hasMore;
while (NS_SUCCEEDED(stmt->ExecuteStep(&hasMore)) && hasMore) {
  // handle the results
}