mozIStorageAggregateFunction

  • Revision slug: MozIStorageAggregateFunction
  • Revision title: mozIStorageAggregateFunction
  • Revision id: 127903
  • Created:
  • Creator: sdwilsh
  • Is current revision? No
  • Comment 105 words added, 10 words removed

Revision Content

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 {{ ifmethod("mozIStorageConnection", "createAggregateFunction") }}.

{{ InterfaceStatus("mozIStorageAggregateFunction", "storage/public/mozIStorageAggregateFunction.idl", "unfrozen", "Mozilla 1.9", "yes") }}

Inherits from: {{ interface("nsISupports") }}

Method overview

void onStep(in {{ interface("mozIStorageValueArray") }} aFunctionArguments);
{{ interface("nsIVariant") }} onFinal();

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.

{{ Storage:threadsafety_callback_warning() }}

void onStep(
  in mozIStorageValueArray aFunctionArguments
);
Parameters
aFunctionArguments
A {{ interface("mozIStorageValueArray") }} holding the arguments passed in to the function.

onFinal()

This is called after all results have been obtained and notified via {{ interface("mozIStorageAggregateFunction", "onStep") }}.  The implementation should finish its calculations on the data, and return a result.

{{ Storage:threadsafety_callback_warning() }}

nsIVariant onFinal()
Return value

An {{ interface("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 {{ interface("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;
    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 });
    return Math.sqrt(total / this._numbers.length); 
  }
};

// Now, register our function with the database connection.
dbConn.createFunction("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 squareFunction : public mozIStorageFunction
{
public:
  NS_IMETHOD OnFunctionCall(mozIStorageValueArray *aArguments,
                            nsIVariant **_result)
  {
    PRInt32 value;
    nsresult rv = aArguments->GetInt32(&value);
    NS_ENSURE_SUCCESS(rv, rv);
    
    nsCOMPtr<nsIWritableVariant> result =
      do_CreateInstance("@mozilla.org/variant;1");
    NS_ENSURE_TRUE(result, NS_ERROR_OUT_OF_MEMORY);
    
    rv = result->SetAsInt64(value * value);
    NS_ENSURE_SUCCESS(rv, rv);

    NS_ADDREF(*_result = result);
    return NS_OK;
  }
};

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

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

 

Revision Source

<p>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 <a class="external" href="http://www.sqlite.org/lang_aggfunc.html" title="http://www.sqlite.org/lang_corefunc.html">number of already defined aggregate functions provided by SQLite</a>.  Objects implementing this interface can be registered with {{ ifmethod("mozIStorageConnection", "createAggregateFunction") }}.</p>
<p>{{ InterfaceStatus("mozIStorageAggregateFunction", "storage/public/mozIStorageAggregateFunction.idl", "unfrozen", "Mozilla 1.9", "yes") }}</p>
<p>Inherits from: {{ interface("nsISupports") }}</p>
<h2 name="Method_overview">Method overview</h2>
<table class="standard-table"> <tbody> <tr> <td><code>void <a href="#onStep()">onStep</a>(in {{ interface("mozIStorageValueArray") }} aFunctionArguments);</code></td> </tr> <tr> <td><code>{{ interface("nsIVariant") }} <a href="#onFinal()">onFinal</a>();</code></td> </tr> </tbody>
</table>
<h2 name="Methods">Methods</h2>
<h3 name="onStep()">onStep()</h3>
<p>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.</p>
<p>{{ Storage:threadsafety_callback_warning() }}</p>
<pre class="eval">void onStep(
  in mozIStorageValueArray aFunctionArguments
);</pre>
<h6 name="Parameters">Parameters</h6>
<dl><dt><code>aFunctionArguments</code></dt><dd>A {{ interface("mozIStorageValueArray") }} holding the arguments passed in to the function.</dd></dl>
<h3 name="onFinal()">onFinal()</h3>
<p>This is called after all results have been obtained and notified via {{ interface("mozIStorageAggregateFunction", "onStep") }}.  The implementation should finish its calculations on the data, and return a result.</p>
<p>{{ Storage:threadsafety_callback_warning() }}</p>
<pre class="eval">nsIVariant onFinal()</pre>
<h6 name="Return">Return value</h6>
<p>An {{ interface("nsIVariant") }} this is the return value of the function.</p>
<h2>Sample Code</h2>
<p>Both of the following code samples assume that the variable dbConn is an opened {{ interface("mozIStorageConnection") }}.</p>
<h3>JavaScript</h3>
<pre class="brush: js">// 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;
    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 });
    return Math.sqrt(total / this._numbers.length); 
  }
};

// Now, register our function with the database connection.
dbConn.createFunction("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();
}
</pre><h3>C++</h3>
<pre class="brush: cpp">// First, create our class that will represent our function.
class squareFunction : public mozIStorageFunction
{
public:
  NS_IMETHOD OnFunctionCall(mozIStorageValueArray *aArguments,
                            nsIVariant **_result)
  {
    PRInt32 value;
    nsresult rv = aArguments-&gt;GetInt32(&amp;value);
    NS_ENSURE_SUCCESS(rv, rv);
    
    nsCOMPtr&lt;nsIWritableVariant&gt; result =
      do_CreateInstance("@mozilla.org/variant;1");
    NS_ENSURE_TRUE(result, NS_ERROR_OUT_OF_MEMORY);
    
    rv = result-&gt;SetAsInt64(value * value);
    NS_ENSURE_SUCCESS(rv, rv);

    NS_ADDREF(*_result = result);
    return NS_OK;
  }
};

// Now, register our function with the database connection.
nsCOMPtr&lt;mozIStorageFunction&gt; func = new squareFunction();
NS_ENSURE_TRUE(func, NS_ERROR_OUT_OF_MEMORY);
nsresult rv = dbConn-&gt;CreateFunction(
  NS_LITERAL_CSTRING("square"),
  1,
  func
);
NS_ENSURE_SUCCESS(rv, rv);

// Run some query that uses the function.
nsCOMPtr&lt;mozIStorageStatement&gt; stmt;
rv = dbConn-&gt;CreateStatement(NS_LITERAL_CSTRING(
  "SELECT square(value) FROM some_table"),
  getter_AddRefs(stmt)
);
NS_ENSURE_SUCCESS(rv, rv);
PRBool hasMore;
while (NS_SUCCEEDED(stmt-&gt;ExecuteStep(&amp;hasMore)) &amp;&amp; hasMore) {
  // handle the results
}
</pre>
<p> </p>
Revert to this revision