mozIStorageValueArray

  • Revision slug: mozIStorageValueArray
  • Revision title: mozIStorageValueArray
  • Revision id: 137629
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment fix grammar and formatting

Revision Content

{{template.Fx_minversion_header(2)}} mozIStorageValueArray wraps an array of SQL values, such as a single database row.

You can get the type of a value by calling getTypeOfIndex(), which returns the type of the specified column.


{{template.InterfaceStatus("mozIStorageValueArray", "storage/public/mozIStorageValueArray.idl", "unfrozen", "Mozilla 1.8", "yes")}}

Inherits from: nsISupports

{{template.Note("Be careful! SQLite is not a typed database. Any type can be put into any cell, regardless of the type declared for the column. If you request the data be returned as a different type, SQLite will do its best to convert it, and will return some default value if no conversion is possible. Therefore, while you can\'t get type errors you may get unexpected data out.")}}

Method overview

long getTypeOfIndex(in unsigned long aIndex);
long getInt32(in unsigned long aIndex);
long long getInt64(in unsigned long aIndex);
double getDouble(in unsigned long aIndex);
AUTF8String getUTF8String(in unsigned long aIndex);
AString getString(in unsigned long aIndex);
void getBlob(in unsigned long aIndex, out unsigned long aDataSize, {{mediawiki.external('array,size_is(aDataSize)')}} out octet aData);
boolean getIsNull(in unsigned long aIndex);

Attributes

Attribute Type Description
numEntries unsigned long The number of entries in the array (each corresponding to a column in the database row).

Constants

Constant Value Description
VALUE_TYPE_NULL 0 Null data type.
VALUE_TYPE_INTEGER 1 INTEGER data type.
VALUE_TYPE_FLOAT 2 FLOAT data type.
VALUE_TYPE_TEXT 3 TEXT data type.
VALUE_TYPE_BLOB 4 BLOB data type.

Methods

getTypeOfIndex()

Returns the type of the value at the given column index; one of VALUE_TYPE_NULL, VALUE_TYPE_INTEGER, VALUE_TYPE_FLOAT, VALUE_TYPE_TEXT, or VALUE_TYPE_BLOB.

 long getTypeOfIndex(
   in unsigned long aIndex
 );
Parameters
<tt>aIndex</tt>
The index of the column whose type you wish to determine.
Return value

One of VALUE_TYPE_NULL, VALUE_TYPE_INTEGER, VALUE_TYPE_FLOAT, VALUE_TYPE_TEXT, or VALUE_TYPE_BLOB.

getInt32()

Returns an Int32 value for the given entry (column) index. Due to SQLite's type conversion rules, any of these are valid for any column regardless of the column's data type. However, if the specific type matters, call getTypeOfIndex() first to identify the column type, and then the appropriate get method should be called.

 long getInt32(
   in unsigned long aIndex
 );
Parameters
<tt>aIndex</tt>
The index of the column whose value is to be returned.
Return value

Returns an Int32 value for the given entry (column) index.

getInt64()

Returns an Int64 value for the given entry (column) index. Due to SQLite's type conversion rules, any of these are valid for any column regardless of the column's data type. However, if the specific type matters, call getTypeOfIndex() first to identify the column type, and then the appropriate get method should be called.

 long long getInt64(
   in unsigned long aIndex
 );
Parameters
<tt>aIndex</tt>
The index of the column whose data should be retrieved.
Return value

Returns an Int64 value for the given entry (column) index.

getDouble()

Returns a Double value for the given entry (column) index. Due to SQLite's type conversion rules, any of these are valid for any column regardless of the column's data type. However, if the specific type matters, call getTypeOfIndex() first to identify the column type, and then the appropriate get method should be called.

 double getDouble(
   in unsigned long aIndex
 );
Parameters
<tt>aIndex</tt>
The column's index.
Return value

Returns a Double value for the given entry (column) index.

getUTF8String()

Returns an AUTF8String value for the given entry (column) index. Due to SQLite's type conversion rules, any of these are valid for any column regardless of the column's data type. However, if the specific type matters, call getTypeOfIndex() first to identify the column type, and then the appropriate get method should be called.

If you ask for a string value for a NULL column, you will get an empty string with IsVoid set to distinguish it from an explicitly set empty string.

AUTF8String getUTF8String(in unsigned long aIndex);
Parameters
<tt>aIndex</tt>
The column's index.
Return value

Returns an AUTF8String value for the given entry (column) index.

getString()

Returns a String value for the given entry (column) index. Due to SQLite's type conversion rules, any of these are valid for any column regardless of the column's data type. However, if the specific type matters, call getTypeOfIndex() first to identify the column type, and then the appropriate get method should be called.

If you ask for a string value for a NULL column, you will get an empty string with IsVoid set to distinguish it from an explicitly set empty string.

 AString getString(
   in unsigned long aIndex
 );
Parameters
<tt>aIndex</tt>
The column's index.
Return value

Returns an AString value for the given entry (column) index.

getBlob()

Retrieves unformatted data from the column specified by the given index. The returned data is NULL if dataSize = 0.

 void getBlob(
   in unsigned long aIndex,
   out unsigned long aDataSize,
   [array,size_is(aDataSize)] out octet aData
 );
Parameters
<tt>aIndex</tt>
The column's index.
<tt>aDataSize</tt>
The size of the returned data.
<tt>aData</tt>
The returned data.

getIsNull()

Checks if given column index is NULL or not.

 boolean getIsNull(
   in unsigned long aIndex
 );
Parameters
<tt>aIndex</tt>
The column's index.
Return value

Returns true or false depending on whether or not the data in the column specified by aIndex is null.

Example: Using get functions to retrieve values

C++

PRBool hasMoreData;
while (NS_SUCCEEDED(statement->ExecuteStep(&hasMoreData)) && hasMoreData) {
  PRInt32 value = statement->AsInt32(0);
  // use the value...
}

JavaScript

while (statement.executeStep()) {
  var value = statement.getInt32(0);
  // use the value...
}

Revision Source

<p>
{{template.Fx_minversion_header(2)}}
<code>mozIStorageValueArray</code> wraps an array of SQL values, such as a single database row.
</p><p>You can get the type of a value by calling <code><a href="#getTypeOfIndex.28.29">getTypeOfIndex()</a></code>, which returns the type of the specified column. 
</p><p><br>
{{template.InterfaceStatus("mozIStorageValueArray", "storage/public/mozIStorageValueArray.idl", "unfrozen", "Mozilla 1.8", "yes")}}
</p><p>Inherits from: <a href="en/NsISupports">nsISupports</a>
</p><p>{{template.Note("Be careful! SQLite is not a typed database. Any type can be put into any cell, regardless of the type declared for the column. If you request the data be returned as a different type, SQLite will do its best to convert it, and will return some default value if no conversion is possible. Therefore, while you can\'t get type errors you may get unexpected data out.")}}
</p>
<h2 name="Method_overview">Method overview</h2>
<table class="standard-table">

<tbody><tr>
<td> <code>long <a href="#getTypeOfIndex.28.29">getTypeOfIndex</a>(in unsigned long aIndex);</code>
</td></tr>
<tr>
<td> <code>long <a href="#getInt32.28.29">getInt32</a>(in unsigned long aIndex);</code>
</td></tr>
<tr>
<td> <code>long long <a href="#getInt64.28.29">getInt64</a>(in unsigned long aIndex);</code>
</td></tr>
<tr>
<td> <code>double <a href="#getDouble.28.29">getDouble</a>(in unsigned long aIndex);</code>
</td></tr>
<tr>
<td> <code>AUTF8String <a href="#getUTF8String.28.29">getUTF8String</a>(in unsigned long aIndex);</code>
</td></tr>
<tr>
<td> <code>AString <a href="#getString.28.29">getString</a>(in unsigned long aIndex);</code>
</td></tr>
<tr>
<td> <code>void <a href="#getBlob.28.29">getBlob</a>(in unsigned long aIndex, out unsigned long aDataSize, {{mediawiki.external('array,size_is(aDataSize)')}} out octet aData);</code>
</td></tr>
<tr>
<td> <code>boolean <a href="#getIsNull.28.29">getIsNull</a>(in unsigned long aIndex);</code>
</td></tr>
</tbody></table>
<h2 name="Attributes">Attributes</h2>
<table class="standard-table">

<tbody><tr>
<td class="header">Attribute
</td><td class="header">Type
</td><td class="header">Description
</td></tr>

<tr>
<td><code>numEntries</code>
</td><td><code>unsigned long</code>
</td><td> The number of entries in the array (each corresponding to a column in the database row).
</td></tr>
</tbody></table>
<h2 name="Constants">Constants</h2>
<table class="standard-table">

<tbody><tr>
<td class="header">Constant
</td><td class="header">Value
</td><td class="header">Description
</td></tr>

<tr>
<td><code>VALUE_TYPE_NULL</code>
</td><td> 0
</td><td>Null data type.
</td></tr>
<tr>
<td><code>VALUE_TYPE_INTEGER</code>
</td><td> 1
</td><td><code>INTEGER</code> data type.
</td></tr>
<tr>
<td><code>VALUE_TYPE_FLOAT</code>
</td><td> 2
</td><td><code>FLOAT</code> data type.
</td></tr>
<tr>
<td><code>VALUE_TYPE_TEXT</code>
</td><td> 3
</td><td><code>TEXT</code> data type.
</td></tr>
<tr>
<td><code>VALUE_TYPE_BLOB</code>
</td><td> 4
</td><td><code>BLOB</code> data type.
</td></tr>
</tbody></table>
<h2 name="Methods">Methods</h2>
<h3 name="getTypeOfIndex.28.29"> getTypeOfIndex() </h3>
<p>Returns the type of the value at the given column index; one of <code>VALUE_TYPE_NULL</code>, <code>VALUE_TYPE_INTEGER</code>, <code>VALUE_TYPE_FLOAT</code>, <code>VALUE_TYPE_TEXT</code>, or <code>VALUE_TYPE_BLOB</code>.
</p>
<pre class="eval"> long getTypeOfIndex(
   in unsigned long aIndex
 );
</pre>
<h6 name="Parameters">Parameters</h6>
<dl><dt><tt>aIndex</tt>
</dt><dd>The index of the column whose type you wish to determine.
</dd></dl>
<h6 name="Return_value">Return value</h6>
<p>One of <code>VALUE_TYPE_NULL</code>, <code>VALUE_TYPE_INTEGER</code>, <code>VALUE_TYPE_FLOAT</code>, <code>VALUE_TYPE_TEXT</code>, or <code>VALUE_TYPE_BLOB</code>.
</p>
<h3 name="getInt32.28.29"> getInt32() </h3>
<p>Returns an <code>Int32</code> value for the given entry (column) index. Due to SQLite's type conversion rules, any of these are valid for any column regardless of the column's data type. However, if the specific type matters, call <code><a href="#getTypeOfIndex.28.29">getTypeOfIndex()</a></code> first to identify the column type, and then the appropriate get method should be called.
</p>
<pre class="eval"> long getInt32(
   in unsigned long aIndex
 );
</pre>
<h6 name="Parameters_2">Parameters</h6>
<dl><dt><tt>aIndex</tt>
</dt><dd>The index of the column whose value is to be returned.
</dd></dl>
<h6 name="Return_value_2">Return value</h6>
<p>Returns an <code>Int32</code> value for the given entry (column) index.
</p>
<h3 name="getInt64.28.29"> getInt64() </h3>
<p>Returns an <code>Int64</code> value for the given entry (column) index. Due to SQLite's type conversion rules, any of these are valid for any column regardless of the column's data type. However, if the specific type matters, call <code><a href="#getTypeOfIndex.28.29">getTypeOfIndex()</a></code> first to identify the column type, and then the appropriate get method should be called.
</p>
<pre class="eval"> long long getInt64(
   in unsigned long aIndex
 );
</pre>
<h6 name="Parameters_3">Parameters</h6>
<dl><dt><tt>aIndex</tt>
</dt><dd>The index of the column whose data should be retrieved.
</dd></dl>
<h6 name="Return_value_3">Return value</h6>
<p>Returns an <code>Int64</code> value for the given entry (column) index.
</p>
<h3 name="getDouble.28.29"> getDouble() </h3>
<p>Returns a <code>Double</code> value for the given entry (column) index. Due to SQLite's type conversion rules, any of these are valid for any column regardless of the column's data type. However, if the specific type matters, call <code><a href="#getTypeOfIndex.28.29">getTypeOfIndex()</a></code> first to identify the column type, and then the appropriate get method should be called.
</p>
<pre class="eval"> double getDouble(
   in unsigned long aIndex
 );
</pre>
<h6 name="Parameters_4">Parameters</h6>
<dl><dt><tt>aIndex</tt>
</dt><dd>The column's index.
</dd></dl>
<h6 name="Return_value_4">Return value</h6>
<p>Returns a <code>Double</code> value for the given entry (column) index.
</p>
<h3 name="getUTF8String.28.29"> getUTF8String() </h3>
<p>Returns an <code><a href="en/AUTF8String">AUTF8String</a></code> value for the given entry (column) index. Due to SQLite's type conversion rules, any of these are valid for any column regardless of the column's data type. However, if the specific type matters, call <code><a href="#getTypeOfIndex.28.29">getTypeOfIndex()</a></code> first to identify the column type, and then the appropriate get method should be called.
</p><p>If you ask for a string value for a <code>NULL</code> column, you will get an empty string with <code>IsVoid</code> set to distinguish it from an explicitly set empty string.
</p>
<pre class="eval">AUTF8String getUTF8String(in unsigned long aIndex);
</pre>
<h6 name="Parameters_5">Parameters</h6>
<dl><dt><tt>aIndex</tt>
</dt><dd>The column's index.
</dd></dl>
<h6 name="Return_value_5">Return value</h6>
<p>Returns an <code>AUTF8String</code> value for the given entry (column) index.
</p>
<h3 name="getString.28.29"> getString() </h3>
<p>Returns a <code>String</code> value for the given entry (column) index. Due to SQLite's type conversion rules, any of these are valid for any column regardless of the column's data type. However, if the specific type matters, call <code><a href="#getTypeOfIndex.28.29">getTypeOfIndex()</a></code> first to identify the column type, and then the appropriate get method should be called.
</p><p>If you ask for a string value for a <code>NULL</code> column, you will get an empty string with <code>IsVoid</code> set to distinguish it from an explicitly set empty string.
</p>
<pre class="eval"> AString getString(
   in unsigned long aIndex
 );
</pre>
<h6 name="Parameters_6">Parameters</h6>
<dl><dt><tt>aIndex</tt>
</dt><dd>The column's index.
</dd></dl>
<h6 name="Return_value_6">Return value</h6>
<p>Returns an <code><a href="en/AString">AString</a></code> value for the given entry (column) index.
</p>
<h3 name="getBlob.28.29"> getBlob() </h3>
<p>Retrieves unformatted data from the column specified by the given index.  The returned data is <code>NULL</code> if <code>dataSize = 0</code>.
</p>
<pre class="eval"> void getBlob(
   in unsigned long aIndex,
   out unsigned long aDataSize,
   [array,size_is(aDataSize)] out octet aData
 );
</pre>
<h6 name="Parameters_7">Parameters</h6>
<dl><dt><tt>aIndex</tt>
</dt><dd>The column's index.
</dd><dt><tt>aDataSize</tt>
</dt><dd>The size of the returned data.
</dd><dt><tt>aData</tt>
</dt><dd>The returned data.
</dd></dl>
<h3 name="getIsNull.28.29"> getIsNull() </h3>
<p>Checks if given column index is <code>NULL</code> or not.
</p>
<pre class="eval"> boolean getIsNull(
   in unsigned long aIndex
 );
</pre>
<h6 name="Parameters_8">Parameters</h6>
<dl><dt><tt>aIndex</tt>
</dt><dd>The column's index.
</dd></dl>
<h6 name="Return_value_7">Return value</h6>
<p>Returns <code>true</code> or <code>false</code> depending on whether or not the data in the column specified by <code>aIndex</code> is null.
</p>
<h3 name="Example:_Using_get_functions_to_retrieve_values">Example: Using get functions to retrieve values</h3>
<h4 name="C.2B.2B">C++</h4>
<pre>PRBool hasMoreData;
while (NS_SUCCEEDED(statement-&gt;ExecuteStep(&amp;hasMoreData)) &amp;&amp; hasMoreData) {
  PRInt32 value = statement-&gt;AsInt32(0);
  // use the value...
}
</pre>
<h4 name="JavaScript">JavaScript</h4>
<pre>while (statement.executeStep()) {
  var value = statement.getInt32(0);
  // use the value...
}

</pre>
Revert to this revision