Patterns in static

Apophenia

Functions
Queries

Functions

int apop_query (const char *fmt,...)
 
apop_dataapop_query_to_text (const char *fmt,...)
 
apop_dataapop_query_to_data (const char *fmt,...)
 
gsl_matrix * apop_query_to_matrix (const char *fmt,...)
 
gsl_vector * apop_query_to_vector (const char *fmt,...)
 
double apop_query_to_float (const char *fmt,...)
 
apop_dataapop_query_to_mixed_data (const char *typelist, const char *fmt,...)
 

Detailed Description

These functions query the database, and most return a value for use on the C-side.

In all cases, your query may be in printf form. For example:

char tabname[] = "demographics";
char colname[] = "heights";
int min_height = 175;
apop_query("select %s from %s where %s > %i", colname, tabname, colname, min_height);

Function Documentation

int apop_query ( const char *  fmt,
  ... 
)

Send a query to the database that returns no data.

  • As with the apop_query_to_... functions, the query can include printf-style format specifiers, such as apop_query("create table %s(id, name, age);", tablename).
Parameters
fmtA printf-style SQL query.
Returns
0 on success, 1 on failure.
apop_data* apop_query_to_data ( const char *  fmt,
  ... 
)

Queries the database, and dumps the result into an apop_data set.

  • If apop_opts.db_name_column is set (it defaults to being "row_names"), and the name of a column matches the name, then the row names are read from that column.
  • As with the other apop_query_to_... functions, the query can include printf-style format specifiers, such as apop_query_to_data("select age from %s where id=%i;", tablename, id_number).
Returns
If no rows are returned, NULL; else an apop_data set with the data in place. Most data will be in the matrix element of the output. Column names are appropriately placed. If apop_opts.db_name_column matches one of the fields in your query's output, then that column will be used for row names (and therefore will not appear in the matrix).
Parameters
fmtA printf-style SQL query.
Exceptions
out->error=='q'Query error. A valid query that returns no rows is not an error; in that case, you get NULL.
double apop_query_to_float ( const char *  fmt,
  ... 
)

Queries the database, and dumps the result into a single double-precision floating point number.

  • This calls apop_query_to_data and returns the (0,0)th element of the returned matrix. Thus, if your query returns multiple lines, you will get no warning, and the function will return the first in the list (which is not always well-defined; maybe use an order by clause in your query if you expect multiple lines).
  • If apop_opts.db_name_column is set, then I'll ignore that column. It gets put into the names of the apop_data set, and then thrown away when I look at only the gsl_matrix element of that set.
  • If the query returns no rows at all, the function returns NAN.
  • If the query produces a blank table, returns NAN, and if apop_opts.verbose>=2, prints an error.
  • As with the other apop_query_to_... functions, the query can include printf-style format specifiers, such as apop_query_to_float("select age from %s where id=%i;", tablename, id_number).
  • If the query produces an error, returns NAN, and if apop_opts.verbose>=0, prints an error. If you need to distinguish between blank tables, NaNs in the data, and query errors, use apop_query_to_data.
Parameters
fmtA printf-style SQL query.
Returns
A double, actually.
gsl_matrix* apop_query_to_matrix ( const char *  fmt,
  ... 
)

Queries the database, and dumps the result into a matrix.

Uses apop_query_to_data and returns just the matrix part; see that function for notes.

  • If apop_opts.db_name_column is set, then I'll ignore that column. It gets put into the names of the apop_data set, and then thrown away when I return only the gsl_matrix part of that set.
  • As with the other apop_query_to_... functions, the query can include printf-style format specifiers, such as apop_query_to_matrix("select age from %s where id=%i;", tablename, id_number).
Deprecated:
Use apop_query_to_data
Parameters
fmtA printf-style SQL query.
Returns
A gsl_matrix.
Exceptions
out->error=='q'Query error. A valid query that returns no rows is not an error; in that case, you get NULL.
apop_data* apop_query_to_mixed_data ( const char *  typelist,
const char *  fmt,
  ... 
)

Query data to an apop_data set, but a mix of names, vectors, matrix elements, and text.

If you are querying to a matrix and maybe a name, use apop_query_to_data (and set apop_opts.db_name_column if desired). But if your data is a mix of text and numbers, use this.

The first argument is a character string consisting of the letters nvmtw, one for each column of the SQL output, indicating whether the column is a name, vector, matrix column, text column, or weight vector. You can have only one n, v, and w.

If the query produces more columns than there are elements in the column specification, then the remainder are dumped into the text section. If there are fewer columns produced than given in the spec, the additional elements will be allocated but not filled (i.e., they are uninitialized and will have garbage).

  • As with the other apop_query_to_... functions, the query can include printf-style format specifiers, such as apop_query_to_mixed_data("tv", "select name, age from %s where id=%i", tablename, id_number).
Parameters
typelistA string consisting of the letters nvmtw. For example, if your query columns should go into a text column, the vector, the weights, and two matrix columns, this would be "tvwmm".
fmtA printf-style SQL query.
Exceptions
out->error=='d'Dimension error. Your count of matrix parts didn't match what the query returned.
out->error=='q'Query error. A valid query that returns no rows is not an error; in that case, you get NULL.
apop_data* apop_query_to_text ( const char *  fmt,
  ... 
)

Dump the results of a query into an array of strings.

Returns
An apop_data structure with the text element filled.
Parameters
fmtA printf-style SQL query.
  • If apop_opts.db_name_column matches a column of the output table, then that column is used for row names, and therefore will not be included in the text.
  • query_output->text is always a 2-D array of strings, even if the query returns a single column. In that case, use returned_tab->text[i][0] (or equivalently, *returned_tab->text[i]) to refer to row i.
  • If an element in the database is NULL, the corresponding cell in the output table will be filled with the text given by apop_opts.nan_string. The default is "NaN", but you can set apop_opts.nan_string = "whatever you like" to change the text to whatever you like.
  • Returns NULL if your query is valid but returns zero rows.
  • As with the other apop_query_to_... functions, the query can include printf-style format specifiers, such as apop_query_to_text("select name from %s where id=%i;", tablename, id_number).

For example, the following function will list the tables in an SQLite database (much like you could do from the command line using sqlite3 dbname.db ".table").

Exceptions
out->error=='q'The database engine was unable to run the query (e.g., invalid SQL syntax). Again, a valid query that returns zero rows is not an error, and NULL is returned.
out->error=='d'Database error.
#include <apop.h>
void print_table_list(char *db_file){
apop_db_open(db_file);
apop_data *tab_list= apop_query_to_text("select name "
"from sqlite_master where type=='table'");
for(int i=0; i< tab_list->textsize[0]; i++)
printf("%s\n", tab_list->text[i][0]);
}
int main(int argc, char **argv){
if (argc == 1){
printf("Give me a database name, and I will print out "
"the list of tables contained therein.\n");
return 0;
}
print_table_list(argv[1]);
}
gsl_vector* apop_query_to_vector ( const char *  fmt,
  ... 
)

Queries the database, and dumps the first column of the result into a gsl_vector.

  • Uses apop_query_to_data internally, then throws away all but the first column of the matrix.
  • If apop_opts.db_name_column is set, then I'll ignore that column. It gets put into the names of the apop_data set, and then thrown away when I look at only the gsl_matrix part of that set.
  • If the query returns zero rows of data or no columns, the function returns NULL.
  • As with the other apop_query_to_... functions, the query can include printf-style format specifiers, such as apop_query_to_vector("select age from %s where id=%i;", tablename, id_number).
Returns
A gsl_vector holding the first column of the returned matrix. Thus, if your query returns multiple lines, you will get no warning, and the function will return the first in the list.
Parameters
fmtA printf-style SQL query.
Exceptions
out->error=='q'Query error. A valid query that returns no rows is not an error; in that case, you get NULL.

Autogenerated by doxygen on Sun Oct 26 2014 (Debian 0.999b+ds3-2).