src/libastrodb/astrodb.h

   1 /*
   2  *  This library is free software; you can redistribute it and/or
   3  *  modify it under the terms of the GNU Lesser General Public
   4  *  License as published by the Free Software Foundation; either
   5  *  version 2 of the License, or (at your option) any later version.
   6  *
   7  *  This library is distributed in the hope that it will be useful,
   8  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
   9  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  10  *  Lesser General Public License for more details.
  11  *
  12  *  You should have received a copy of the GNU General Public License
  13  *  along with this program; if not, write to the Free Software
  14  *  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  15  *
  16  *  Copyright (C) 2005 Liam Girdwood
  17  */
  18
  19 /*! \mainpage libastrodb
  20 * <A>General Purpose Astronomical Database</A>
  21 *
  22 * \section intro Introduction
  23 * Libncat is a general purpose astronomical database designed to give very fast
  24 * access to <A href="http://cdsweb.u-strasbg.fr/">CDS</A> catalog data. It is designed to be independent of any underlying
  25 * catalog data formatting and will import most data records providing the
  26 * catalog ships with a "ReadMe" file that follows the CDS <A href="http://vizier.u-strasbg.fr/doc/catstd.htx">formatting specifications</A>.
  27 * Libncat provides a simple database backend and exposes a C API for catalog access.
  28 *
  29 * The intended audience of libastrodb is C / C++ programmers, astronomers and anyone working with large astronomical catalogs.
  30 *
  31 * Libncat will be the database backend used by the <A href="http://nova.sf.net">Nova</A>
  32 * and <A href="http://astro.corlan.net/gcx/">GCX</A> projects and most importantly, is free software.
  33 *
  34 * \section features Features
  35 * The current release of libastrodb supports:-
  36 *
  37 * - Parsing of important fields in CDS ReadMe files
  38 * - Downloading catalog data from CDS to a local library
  39 * - Importing selected catalog object data and object fields into machine formats.
  40 * - Fast access to catalog data based on :-
  41 *               - position
  42 *               - position and magnitude
  43 *               - hashed object ID's
  44 *               - distance (near sky catalogs)
  45 * - Progress feedback.
  46 * - Powerfull catalog searching on any combinations of fields.
  47 *
  48 * \section docs Documentation
  49 * API documentation for libastrodb is included in the source. It can also be found in this website and an offline tarball is available <A href="http://libnovacat.sf.net/libastrodbdocs.tar.gz">here</A>.
  50 *
  51 * \section download Download
  52 * The latest release is 0.1 and is available <A href="http://sourceforge.net/project/showfiles.php?group_id=133878">here.</A>
  53 *
  54 * \section cvs CVS
  55 * The latest CVS version of libastrodb is available via CVS <A href="http://sf.net/cvs/?group_id=133878">here.</A>
  56 *
  57 * \section licence Licence
  58 * libastrodb is released under the <A href="http://www.gnu.org">GNU</A> LGPL.
  59 *
  60 * \section authors Authors
  61 * libastrodb is maintained by <A href="mailto:liam@gnova.org">Liam Girdwood</A>
  62 *
  63 * \section thanks Thanks
  64 * Thanks to Sourceforge for hosting this project. <A href="http://sourceforge.net"> <IMG src="http://sourceforge.net/sflogo.php?group_id=133878&amp;type=5" width="210" height="62" border="0" alt="SourceForge Logo"></A>
  65 */
  66
  67 #ifndef __LIBNCAT_H
  68 #define __LIBNCAT_H
  69
  70 #include <libnova/libnova.h>
  71
  72 #ifdef __cplusplus
  73 extern "C" {
  74 #endif
  75
  76 /*
  77  * Dataset initialization flags
  78  */
  79 #define ADB_MEM         0x1     /*!< Preload the whole dataset into memory */
  80 #define ADB_FILE        0x2     /*!< Store the whole dataset in local disk in binary format */
  81 #define ADB_REFRESH     0x4     /*!< Refresh the dataset with online repo */
  82
  83 /*
  84  * Error codes
  85  */
  86 #define ADB_EOK         0               /*!< Status OK, no error */
  87 #define ADB_EIDSET      -1              /*!< Invalid dataset */
  88 #define ADB_EICAT       -2              /*!< Invalid catalog */
  89 #define ADB_EIREADME    -3              /*!< Invalid CDS ReadMe */
  90 #define ADB_ENOFILE     -4              /*!< No such file or directory */
  91 #define ADB_ENOMEM      -5              /*!< No memory */
  92 #define ADB_ENOCATDIR   -6              /*!< Could not create catalog cache dirs */
  93 #define ADB_ENOINS      -7              /*!< No valid object insert found */
  94 #define ADB_ENOFIELD    -8              /*!< Field not valid or found */
  95 #define ADB_ENOFUNC     -9              /*!< Invalid function */
  96 #define ADB_ECMD        -10             /*!< Command failed */
  97 #define ADB_ESRCH       -11             /*!< Invalid search */
  98 #define ADB_ENOOP       -12             /*!< Invalid search operator */
  99 #define ADB_ENOCOMP     -13             /*!< Invalid search comparator */
 100 #define ADB_ENOGET      -14             /*!< Invalid object get */
 101 #define ADB_EINV        -15             /*!< Invalid parameter */
 102 #define ADB_EIMPL       -1000           /*!< Not implemented */
 103
 104 #define astrodb_offset(x,y) (long)(&((x*)0)->y)                 /* offset in struct */
 105 #define astrodb_sizeof(x,y) sizeof(((x*)0)->y)          /* size in struct */
 106 #define astrodb_size(x) (sizeof(x)/sizeof(x[0]))                /* array size */
 107
 108 /* convenience index constructors */
 109 #define astrodb_member(lname, lsymbol, lagg, latom, ltype, lunits, lgposn, linsert) \
 110         {.name = lname, .symbol = lsymbol, .s_offset = astrodb_offset(lagg, latom), \
 111          .s_size = astrodb_sizeof(lagg, latom), .units = lunits, .type = ltype, \
 112          .units = lunits, .g_posn = lgposn, .insert = linsert,}
 113 #define astrodb_gmember(lname, lsymbol, lagg, latom, ltype, lunits, lgposn, linsert) \
 114         {.name = lname, .symbol = lsymbol, .s_offset = astrodb_offset(lagg, latom), \
 115          .s_size = astrodb_sizeof(lagg, latom), .units = lunits, .type = ltype, \
 116          .units = lunits, .insert = linsert, .g_posn = lgposn, .g_offset = astrodb_offset(lagg, latom),}
 117
 118 struct astrodb_library;
 119 struct astrodb_db;
 120 struct astrodb_table;
 121 struct astrodb_search;
 122 struct astrodb_slist;
 123 struct astrodb_dlist;
 124
 125 /*! \typedef enum astrodb_ctype
 126  * \ingroup dataset
 127  *
 128  * C type of ASCII dataset field
 129  */
 130 typedef enum {
 131         CT_INT,                 /*!< int */
 132         CT_SHORT,               /*!< short */
 133         CT_DOUBLE,              /*!< double */
 134         CT_FLOAT,               /*!< float */
 135         CT_STRING,              /*!< string */
 136         CT_SIGN,                /*!< sign + or - */
 137         CT_DOUBLE_HMS_HRS,      /*!< degrees Hours (HMS)*/
 138         CT_DOUBLE_HMS_MINS,     /*!< degrees Minutes  (HMS)*/
 139         CT_DOUBLE_HMS_SECS,     /*!< degrees Seconds (HMS)*/
 140         CT_DOUBLE_DMS_DEGS,     /*!< degrees (DMS) */
 141         CT_DOUBLE_DMS_MINS,     /*!< degrees Minutes (DMS) */
 142         CT_DOUBLE_DMS_SECS,     /*!< degrees Seconds (DMS) */
 143         CT_DOUBLE_MPC,          /*!< Minor planet centre date format */
 144         CT_NULL,                /*!< NULL */
 145 } astrodb_ctype;
 146
 147 /*
 148  * Object tile status flags
 149  */
 150 #define ADB_SMEM                0x1     /*!< Memory */
 151 #define ADB_SCACHE              0x2     /*!< Disk cache */
 152 #define ADB_SLOCAL              0x4     /*!< Local (raw) */
 153 #define ADB_SONLINE             0x8     /*!< Online (raw) */
 154 #define ADB_SUSED               0x10    /*!< Used by last get */
 155
 156
 157 /*! \typedef enum astrodb_operator
 158  * \ingroup search
 159  *
 160  * Search operators
 161  */
 162 enum astrodb_operator {
 163         ADB_OP_AND,     /*!< AND */
 164         ADB_OP_OR       /*!< OR */
 165 };
 166
 167 /*! \typedef enum astrodb_comparator
 168  * \ingroup search
 169  *
 170  * Search field comparators
 171  */
 172 enum astrodb_comparator {
 173         ADB_COMP_LT,    /*!< less than */
 174         ADB_COMP_GT,    /*!< greater than */
 175         ADB_COMP_EQ,    /*!< equal to */
 176         ADB_COMP_NE     /*!< not equal to */
 177 };
 178
 179 /*! \typedef enum astrodb_msg_level
 180  * \ingroup Library
 181  *
 182  * AstroDB message level.
 183  */
 184 enum astrodb_msg_level {
 185         ADB_MSG_INFO    = 1,
 186         ADB_MSG_WARN    = 2,
 187         ADB_MSG_DEBUG   = 3,
 188 };
 189
 190 /*! \typedef void (*astrodb_func)(void* data, void* user)
 191  * \brief Function
 192  */
 193 typedef int (*astrodb_func)(void* data, void* user);
 194
 195 /*! \typedef astrodb_object_status
 196  * \brief Dataset tile status
 197  * \ingroup dataset
 198  */
 199 struct astrodb_tile_status {
 200         unsigned int flags;     /* source status */
 201         unsigned int size;      /* number of elements in tile */
 202 };
 203
 204 struct astrodb_slist {
 205         struct astrodb_slist *tail;
 206         void* data;
 207 };
 208
 209 struct astrodb_dlist {
 210         struct astrodb_dlist *head;
 211         struct astrodb_dlist *tail;
 212         void* data;
 213 };
 214
 215 #define OBJECT_ID_SIZE          12
 216 #define OBJECT_NAME_SIZE        12
 217
 218
 219 struct astrodb_posn_mag {
 220         double ra;
 221         double dec;
 222         float Vmag;
 223 };
 224
 225 struct astrodb_posn_size {
 226         double ra;
 227         double dec;
 228         float size;
 229 };
 230
 231 struct astrodb_posn_type {
 232         double ra;
 233         double dec;
 234         unsigned int type;
 235 };
 236
 237 struct astrodb_size_type {
 238         double minor_size;
 239         double major_size;
 240         unsigned int type;
 241 };
 242
 243
 244 /*! \struct astrodb_object
 245  * \brief Astro object.
 246  *
 247  * Most objects in are derived from this object.
 248  * It contains the following object information:-
 249  *
 250  * <ul>
 251  * <li><b>  Type</b>            <i>Object type (char)</i></li>
 252  * <li><b>  Oclass</b>          <i>Object class (char)</i></li>
 253  * <li><b>  Reserved</b>        <i>Reserved (short)</i></li>
 254  * <li><b>  ID</b>              <i>ID (12 char)</i></li>
 255  * <li><b>  Name</b>            <i>Name (12 char)</i></li>
 256  * </ul>
 257  */
 258 struct astrodb_object {
 259         union {
 260                 unsigned long id;
 261                 char designation[OBJECT_NAME_SIZE];
 262         };
 263         union {
 264                 struct astrodb_posn_mag posn_mag;
 265                 struct astrodb_posn_size posn_size;
 266                 struct astrodb_posn_type posn_type;
 267                 struct astrodb_size_type size_type;
 268         };
 269 };
 270
 271 /*! \struct astrodb_table_info
 272  * \brief Dataset information.
 273  *
 274  * Describes a dataset from a CDS catalog ReadMe file.
 275  *
 276  * <ul>
 277  * <li><b>  Name</b>            <i>Dataset name</i></li>
 278  * <li><b>  Records</b>         <i>Number of records in dataset</i></li>
 279  * <li><b>  Length</b>          <i>Length of dataset records</i></li>
 280  * <li><b>  Title</b>           <i>Dataset title</i></li>
 281  * <li><b>  Byte Desc</b>       <i>Dataset byte description (in dlist)</i></li>
 282  * </ul>
 283  */
 284 struct astrodb_table_info {
 285         char* name;                     /*!< filename dos 8.3 */
 286         int records;                    /*!< number of records */
 287         int length;                     /*!< maximum line length */
 288         char* title;                    /*!< short title (80 chars max) */
 289         struct astrodb_dlist* byte_description; /*!< Byte by byte desc 9c */
 290 };
 291
 292
 293 /*! \struct astrodb_table_column_info
 294  * \brief Dataset byte description.
 295  *
 296  * Describes a field from a CDS dataset.
 297  *
 298  * <ul>
 299  * <li><b>  Start</b>           <i>Field start pos</i></li>
 300  * <li><b>  End</b>             <i>Field end pos</i></li>
 301  * <li><b>  Type</b>            <i>Field type</i></li>
 302  * <li><b>  Units</b>           <i>Units</i></li>
 303  * <li><b>  Label</b>           <i>CDS label</i></li>
 304  * <li><b>  Explanation</b>     <i>Explanation</i></li>
 305  * </ul>
 306  */
 307 struct astrodb_table_column_info {
 308         short start;        /*!< start byte */
 309         short end;          /*!< end byte */
 310         char *type;         /*!< field type */
 311         char *units;        /*!< field units */
 312         char *label;        /*!< field label */
 313         char *explanation;  /*!< field explanation */
 314 };
 315
 316 #define ADB_SCHEMA_NAME_SIZE            32
 317 #define ADB_SCHEMA_SYMBOL_SIZE          8
 318 #define ADB_SCHEMA_UNITS_SIZE           8
 319
 320 /*! \struct astrodb_schema_object
 321  * \ingroup dataset
 322  *
 323  * Represents a field within a dfataset structure.
 324  */
 325 struct astrodb_schema_object {
 326         char name[ADB_SCHEMA_NAME_SIZE];                /*!< field name */
 327         char symbol[ADB_SCHEMA_SYMBOL_SIZE];            /*!< field symbol */
 328         int s_offset;           /*!< struct offset */
 329         int s_size;             /*!< struct size */
 330         int g_offset;           /*!< group offset, -1 if atomic */
 331         int g_posn;             /*!< group posn, lowest is first */
 332         int l_size;             /*!< line size */
 333         int l_offset;           /*! line offset */
 334         astrodb_ctype type;             /*!< field type */
 335         char units[ADB_SCHEMA_UNITS_SIZE];              /*!< field units */
 336         astrodb_func insert;    /* custom insert method */
 337 };
 338
 339 /*! \fn astrodb_library* astrodb_open_library(char *remote, char* local);
 340  * \brief Create a library
 341  * \ingroup library
 342  */
 343 void astrodb_set_msg_level(enum astrodb_msg_level level);
 344
 345 /*! \fn astrodb_library* astrodb_open_library(char *remote, char* local);
 346  * \brief Create a library
 347  * \ingroup library
 348  */
 349 struct astrodb_library* astrodb_open_library(char *remote, char* local);
 350
 351 /*! \fn void astrodb_close_library(astrodb_library* lib);
 352  * \brief Free the library resources
 353  * \ingroup library
 354  */
 355 void astrodb_close_library(struct astrodb_library *lib);
 356
 357 /*! \fn astrodb_db* astrodb_create_db(astrodb_library* lib, char* cclass, char* cnum,
 358         double ra_min, double ra_max,double dec_min, double dec_max,
 359         double mag_faint, double mag_bright, int flags);
 360  * \brief Create a new catalog
 361  * \ingroup catalog
 362  */
 363 struct astrodb_db* astrodb_create_db(struct astrodb_library *lib,
 364                                 char* cat_class, char* cat_num,
 365                                 double ra_min, double ra_max, double dec_min,
 366                                 double dec_max, double mag_faint,
 367                                 double mag_bright, int flags);
 368
 369 /*! \fn astrodb_dlist* astrodb_db_get_tables(astrodb_db* cat);
 370  * \ingroup catalog
 371  * \brief Query the datasets in the catalog
 372  */
 373 struct astrodb_dlist* astrodb_db_get_tables(struct astrodb_db *db);
 374
 375 /*! \fn void astrodb_db_free (astrodb_db* cat);
 376  * \brief Destroys catalog and frees resources
 377  * \ingroup catalog
 378  */
 379 void astrodb_db_free(struct astrodb_db *db);
 380
 381 /*! \fn const char* astrodb_get_version(void);
 382  * \brief Get the libastrodb version number.
 383  * \ingroup misc
 384  */
 385 const char *astrodb_get_version(void);
 386
 387 /*! \fn const char* astrodb_get_last_err_msg(void);
 388  * \brief Get the text of the last error.
 389  * \ingroup misc
 390  */
 391 const char* astrodb_get_err_str(int err);
 392
 393 /*! \fn int astrodb_table_register_schema(astrodb_table *table, astrodb_schema_object* idx,
 394                                         int idx_size);
 395  * \brief Register a new astro object type
 396  * \ingroup catalog
 397  */
 398 int astrodb_table_register_schema(struct astrodb_table *table,
 399                                         struct astrodb_schema_object *schema,
 400                                         int schema_size, int object_size);
 401
 402 /*! \fn astrodb_table* astrodb_table_create(astrodb_db* cat, char *table_name,
 403                                         unsigned int flags);
 404  * \brief Create a new dataset
 405  * \ingroup dataset
 406  */
 407 struct astrodb_table* astrodb_table_create(struct astrodb_db *db,
 408                                         char* table_name,
 409                                         unsigned int create_flags);
 410
 411 /*! \fn astrodb_table_open(astrodb_table *table, astrodb_progress progress, int ra,
 412                         int dec, int mag)
 413  * \brief Initialise new dataset.
 414  * \ingroup dataset
 415  */
 416 int astrodb_table_open(struct astrodb_table *table,
 417                         int ra, int dec, int mag);
 418
 419 /*! \fn void astrodb_table_close(astrodb_table *table);
 420  * \brief Free's dataset and it's resources
 421  * \ingroup dataset
 422  */
 423 void astrodb_table_close(struct astrodb_table *table);
 424
 425 #if 0
 426 /*! \fn int astrodb_dset_add_custom_field(astrodb_table *table, char* field);
 427 * \brief Add a custom field to the dataset for importing
 428 * \ingroup dataset
 429 */
 430 int astrodb_dset_add_custom_field(astrodb_table *table, char* field);
 431 #endif
 432
 433 /*! \fn int astrodb_table_hash_key(astrodb_table *table, char* field);
 434 * \brief Add a custom field to the dataset for importing
 435 * \ingroup dataset
 436 */
 437 int astrodb_table_hash_key(struct astrodb_table *table, char *key);
 438
 439 /*! \fn int astrodb_table_alt_column(astrodb_table *table, char* field, char* alt,
 440                                         int flags);
 441 * \brief Set an alternative field if another field is blank
 442 * \ingroup dataset
 443 */
 444 int astrodb_table_alt_column(struct astrodb_table *table,
 445                                 char *field, char *alt, int flags);
 446
 447 /*! \fn void astrodb_table_clip_on_position (astrodb_table *table, double min_ra,
 448                                         double min_dec, double max_ra,
 449                                         double max_dec, double faint_mag,
 450                                         double bright_mag);
 451  * \brief Set dataset clipping area based on position
 452  * \ingroup dataset
 453  */
 454 void astrodb_table_clip_on_position(struct astrodb_table *table,
 455                                 double min_ra, double min_dec,
 456                                 double max_ra, double max_dec,
 457                                 double faint_mag, double bright_mag);
 458
 459 /*! \fn void astrodb_table_clip_on_distance (astrodb_table *table, double min_AU,
 460                                 double max_AU);
 461  * \brief Set dataset clipping area based on distance
 462  * \ingroup dataset
 463  */
 464 void astrodb_table_clip_on_distance(struct astrodb_table *table,
 465                                 double min_AU, double max_AU);
 466
 467 /*! \fn void astrodb_table_clip_on_fov (astrodb_table *table, double ra, double dec,
 468                                         double fov, double faint_mag,
 469                                         double bright_mag);
 470  * \brief Set dataset clipping area based on field of view
 471  * \ingroup dataset
 472  */
 473 void astrodb_table_clip_on_fov(struct astrodb_table *table,
 474                                 double ra, double dec,
 475                                 double fov, double faint_mag,
 476                                 double bright_mag);
 477
 478 /*! \fn void astrodb_table_unclip (astrodb_table *table);
 479  * \brief Unclip dataset clipping area to full boundaries
 480  * \ingroup dataset
 481  */
 482 void astrodb_table_unclip(struct astrodb_table *table);
 483
 484 /*! \fn int astrodb_table_get_objects (astrodb_table *table, astrodb_progress progress,
 485                                         astrodb_slist **results, unsigned int src);
 486  * \brief Get objects from catalog based on clipping area
 487  * \return number of objects, or negative for failed
 488  * \ingroup dataset
 489  */
 490 int astrodb_table_get_objects(struct astrodb_table *table,
 491                                 struct astrodb_slist **results,
 492                                 unsigned int src);
 493
 494 /*! \fn void astrodb_table_put_objects (astrodb_slist *results);
 495  * \brief Release slist memory from astrodb_table_get_objects()
 496  * \ingroup dataset
 497  */
 498 void astrodb_table_put_objects(struct astrodb_slist *results);
 499
 500 /*! \fn void* astrodb_table_get_object (astrodb_table *table, char *id, char *field);
 501  * \brief Get object from catalog based on ID
 502  * \return pointer to object or NULL
 503  * \ingroup dataset
 504  */
 505 void* astrodb_table_get_object(struct astrodb_table *table,
 506                                 char *id, char *field);
 507
 508 /* some catalog management functionality to manage memory and access */
 509
 510 /*! \fn int astrodb_table_prune(astrodb_table *table);
 511  * \brief free all old sectors.
 512  * \return bytes free'd
 513  * \ingroup dataset
 514  */
 515 int astrodb_table_prune(struct astrodb_table *table);
 516
 517 /*! \fn int astrodb_table_get_size(astrodb_table *table);
 518  * \brief Get dataset cache size.
 519  * \return size in bytes
 520  * \ingroup dataset
 521  */
 522 int astrodb_table_get_size(struct astrodb_table *table);
 523
 524 /*! \fn int astrodb_table_get_row_size(astrodb_table *table);
 525  * \brief Get dataset object size.
 526  * \return size in bytes
 527  * \ingroup dataset
 528  */
 529 int astrodb_table_get_row_size(struct astrodb_table *table);
 530
 531 #if 0
 532 /*! \fn void astrodb_dset_set_status_posn(astrodb_table *table, double min_ra,
 533                 double min_dec, double max_ra, double max_dec,
 534                 double faint_mag,double bright_mag, unsigned int status);
 535  * \brief set sector status based upon area
 536  * \ingroup dataset
 537  */
 538 void astrodb_dset_set_status_posn(astrodb_table *table, double min_ra, double min_dec,
 539                                 double max_ra, double max_dec, double faint_mag,
 540                                  double bright_mag, unsigned int status);
 541
 542 /*! \fn void astrodb_dset_set_status_dist(astrodb_table *table, double min_AU,
 543                                         double max_AU, unsigned int status);
 544  * \brief set sector status based upon area
 545  * \ingroup dataset
 546  */
 547 void astrodb_dset_set_status_dist(astrodb_table *table, double min_AU, double max_AU,
 548                                 unsigned int status);
 549
 550 /*! \fn astrodb_tile_status astrodb_dset_get_status_posn(astrodb_table *table,
 551                                         double ra, double dec, double mag);
 552  * \brief get sector status
 553  * \ingroup dataset
 554  */
 555 astrodb_tile_status astrodb_dset_get_status_posn(astrodb_table *table, double ra,
 556                                                 double dec, double mag);
 557
 558 /*! \fn astrodb_tile_status astrodb_dset_get_status_dist (astrodb_table *table, double AU);
 559  * \brief get sector status
 560  * \ingroup dataset
 561  */
 562 astrodb_tile_status astrodb_dset_get_status_dist(astrodb_table *table, double AU);
 563 #endif
 564 /*! \fn astrodb_ctype astrodb_table_get_column_type(astrodb_table *table, char* field);
 565  * \brief Get field type in struct
 566  * \ingroup dataset
 567  */
 568 astrodb_ctype astrodb_table_get_column_type(struct astrodb_table *table,
 569                                         char* field);
 570
 571 /*! \fn int astrodb_table_get_column_offset(astrodb_table *table, char* field);
 572  * \brief Get field offset in struct
 573  * \ingroup dataset
 574  */
 575 int astrodb_table_get_column_offset(struct astrodb_table *table, char* field);
 576
 577 /*! \fn int astrodb_table_for_search_results_do(astrodb_slist* res,
 578                 void(*func)(void* object, void* data), void* data)
 579  * \brief Do func for every object in result
 580  * \ingroup dataset
 581  */
 582 int astrodb_table_for_search_results_do(struct astrodb_slist* res,
 583                                 void(*func)(void* object, void* data),
 584                                 void* data);
 585
 586 /*! \typedef int (*astrodb_custom_comparator)(void* object);
 587  *
 588  * A customised object search comarator.
 589  */
 590 typedef int (*astrodb_custom_comparator)(void* object);
 591
 592  /*! \fn astrodb_search* astrodb_search_create(astrodb_table *table);
 593  * \brief Creates an new search object
 594  * \ingroup search
 595  */
 596 struct astrodb_search* astrodb_search_create(struct astrodb_table *table);
 597
 598 /*! \fn void astrodb_search_free(astrodb_search* search);
 599  * \brief Free's a search and it resources
 600  * \ingroup search
 601  */
 602 void astrodb_search_free(struct astrodb_search* search);
 603
 604 /*! \fn int astrodb_search_add_operator(astrodb_search* search, astrodb_operator op);
 605  * \brief Add an operation in RPN to the search
 606  * \ingroup search
 607  */
 608 int astrodb_search_add_operator(struct astrodb_search *search,
 609                                 enum astrodb_operator op);
 610
 611 /*! \fn int astrodb_search_add_comparator(astrodb_search* search, char* field,
 612                                         astrodb_comparator comp, char* value);
 613  * \brief Add a comparator in RPN to the search
 614  * \ingroup search
 615  */
 616 int astrodb_search_add_comparator(struct astrodb_search* search, char* field,
 617                                 enum astrodb_comparator comp, char* value);
 618
 619 /*! \fn int astrodb_search_add_custom_comparator(astrodb_search* search,
 620                                                 astrodb_custom_comparator comp);
 621  * \brief Add a comparator in RPN to the search
 622  * \ingroup search
 623  */
 624 int astrodb_search_add_custom_comparator(struct astrodb_search* search,
 625                                         astrodb_custom_comparator comp);
 626
 627 /*! \fn int astrodb_search_get_results(astrodb_search* search, astrodb_progress progress,
 628                                         astrodb_slist **result, unsigned int src);
 629  * \brief Execute a search
 630  * \ingroup search
 631  */
 632 int astrodb_search_get_results(struct astrodb_search* search,
 633                                 struct astrodb_slist **result, unsigned int src);
 634
 635 /*! \fn void astrodb_search_put_results (astrodb_slist *results);
 636  * \brief Release the search results
 637  * \ingroup search
 638  */
 639 void astrodb_search_put_results(struct astrodb_slist *results);
 640
 641 /*! \fn int astrodb_search_get_hits(astrodb_search* search);
 642  * \brief Get the number of search hits.
 643  * \ingroup search
 644  */
 645 int astrodb_search_get_hits(struct astrodb_search* search);
 646
 647 /*! \fn int astrodb_search_get_tests(astrodb_search* search);
 648  * \brief Get the number of search tests
 649  * \ingroup search
 650  */
 651 int astrodb_search_get_tests(struct astrodb_search* search);
 652
 653 /*! \fn astrodb_slist* astrodb_slist_prepend(astrodb_slist* s, void* object);
 654  * \brief Prepend an object to a slist
 655  * \ingroup list
 656  */
 657 struct astrodb_slist* astrodb_slist_prepend(struct astrodb_slist* s, void* object);
 658
 659 /*! \fn astrodb_slist* astrodb_slist_append(astrodb_slist* s, void* object);
 660  * \brief Append an object to a slist
 661  * \ingroup list
 662  */
 663 struct astrodb_slist* astrodb_slist_append(struct astrodb_slist* s, void* object);
 664
 665 /*! \def astrodb_slist_next(s);
 666  * \ingroup list
 667  *
 668  * Get the next node in the slist \a s
 669  */
 670 #define astrodb_slist_next(s) s->tail
 671
 672 /*! \def astrodb_dlist_next(d);
 673  * \ingroup list
 674  *
 675  * Get the next node in the dlist \a d
 676  */
 677 #define astrodb_dlist_next(d) d->tail
 678
 679 /*! \def astrodb_dlist_prev(d);
 680  * \ingroup list
 681  *
 682  * Get the prevoius node in the dlist \a d
 683  */
 684 #define astrodb_dlist_prev(d) d->head
 685
 686 /*! \fn void astrodb_slist_foreach(astrodb_slist* sl , astrodb_func func, void* user);
 687  * \brief Call a function for every item in slist
 688  * \ingroup list
 689  */
 690 void astrodb_slist_foreach(struct astrodb_slist* sl , astrodb_func func, void* user);
 691
 692 /*! \fn void astrodb_slist_foreach_free(astrodb_slist* sl , astrodb_func func, void* user);
 693  * \brief Call a function for every item in slist and then free item
 694  * \ingroup list
 695  */
 696 void astrodb_slist_foreach_free(struct astrodb_slist* sl , astrodb_func func, void* user);
 697
 698 /*! \fn astrodb_dlist* astrodb_dlist_prepend(astrodb_dlist* d, void* object);
 699  * \brief Prepend an object to a dlist
 700  * \ingroup list
 701  */
 702 struct astrodb_dlist* astrodb_dlist_prepend(struct astrodb_dlist* d, void* object);
 703
 704 /*! \fn astrodb_dlist* astrodb_dlist_append(astrodb_dlist* d, void* object);
 705  * \brief Append an object to a dlist
 706  * \ingroup list
 707  */
 708 struct astrodb_dlist* astrodb_dlist_append(struct astrodb_dlist* d, void* object);
 709
 710 /*! \fn astrodb_dlist* astrodb_dlist_head(astrodb_dlist* d);
 711  * \brief Get the head of a dlist
 712  * \ingroup list
 713  */
 714 struct astrodb_dlist* astrodb_dlist_head(struct astrodb_dlist* d);
 715
 716 /*! \fn astrodb_dlist* astrodb_dlist_free_object(astrodb_dlist* d, void* object);
 717  * \brief Free an object from a dlist
 718  * \ingroup list
 719  */
 720 struct astrodb_dlist* astrodb_dlist_free_object(struct astrodb_dlist* d, void* object);
 721
 722 /*! \fn void astrodb_dlist_foreach(astrodb_dlist* dl , astrodb_func func, void* user);
 723  * \brief Call a function for every item in dlist
 724  * \ingroup list
 725  */
 726 void astrodb_dlist_foreach(struct astrodb_dlist* dl , astrodb_func func, void* user);
 727
 728 /*! \fn void astrodb_dlist_foreach_free(astrodb_dlist* dl , astrodb_func func, void* user);
 729  * \brief Call a function for every item in dlist and the free item
 730  * \ingroup list
 731  */
 732 void astrodb_dlist_foreach_free(struct astrodb_dlist* dl , astrodb_func func, void* user);
 733
 734
 735 #ifdef __cplusplus
 736 };
 737 #endif
 738
 739 #endif