# Dataset

group `harp_dataset`

  The HARP harp_dataset module contains everything regarding HARP datasets.

  A Dataset contains a list of references to HARP products together with optional metadata on each product. The primary reference to a product is the value of the ‘source_product’ global attribute of a HARP product.

  Typedefs

  typedef struct harp_dataset_struct `harp_dataset`

    HARP Dataset typedef

  Functions

  int `harp_dataset_new`(harp_dataset **new_dataset)

    Create new HARP dataset. The metadata will be intialized with zero product metadata elements.

    Return
      - `0`, Success.
      - `-1`, Error occurred (check harp_errno).
    Parameters
      - `new_dataset`: Pointer to the C variable where the new HARP product metadata will be stored.
  void `harp_dataset_delete`(harp_dataset *dataset)

    Delete HARP dataset.

    Parameters
      - `dataset`: Pointer to the dataset to free.
  void `harp_dataset_print`(harp_dataset *dataset, int (*print)(const char *, ...))

    Print HARP dataset.

    Parameters
      - `dataset`: Pointer to the dataset to print.
      - `print`: Pointer to the function that should be used for printing.
  int `harp_dataset_import`(harp_dataset *dataset, const char *path, const char *options)

    Import metadata for products into the dataset. If path is a directory then all files (recursively) from that directory are added to the dataset. If path references a .pth file then the file paths from that text file (one per line) are imported. These file paths can be absolute or relative and can point to files, directories, or other .pth files. If path references a product file then that file is added to the dataset. Trying to add a file that is not supported by HARP will result in an error.

    Note that datasets cannot have multiple entries with the same ‘source_product’ value. Therefore, for each product where the dataset already contained an entry with the same ‘source_product’ value, the metadata of that entry is replaced with the new metadata (instead of adding a new entry to the dataset or raising an error).

    Return
      - `0`, Success.
      - `-1`, Error occurred (check harp_errno).
    Parameters
      - `dataset`: Dataset into which to import the metadata.
      - `path`: Path to either a directory containing product files, a .pth file, or a single product file.
      - `options`: Ingestion module specific options (optional); should be specified as a semi-colon separated string of key=value pair; only used for product files that are not already in HARP format.
  int `harp_dataset_get_index_from_source_product`(harp_dataset *dataset, const char *source_product, long *index)

    Lookup the index of source_product in the given dataset.

    Return
      - `0`, Success.
      - `-1`, Error occurred (check harp_errno).
    Parameters
      - `dataset`: Dataset to get index in.
      - `source_product`: Source product reference.
      - `index`: Pointer to the C variable where the index in the dataset for the product is returned.
  int `harp_dataset_has_product`(harp_dataset *dataset, const char *source_product)

    Test if dataset contains an entry with the specified source product reference.

    Return
      - `0`, Dataset does not contain a product with the specific source reference.
      - `1`, Dataset contains a product with the specific source reference.
    Parameters
      - `dataset`: Dataset in which to find the product.
      - `source_product`: Source product reference.
  int `harp_dataset_add_product`(harp_dataset *dataset, const char *source_product, harp_product_metadata *metadata)

    Add a product reference to a dataset.

    Return
      - `0`, Success.
      - `-1`, Error occurred (check harp_errno).
    Parameters
      - `dataset`: Dataset in which to add a new entry.
      - `source_product`: The source product reference of the new entry.
      - `metadata`: The product metadata of the new entry (can be NULL); the dataset is the new owner of metadata.
  struct `harp_dataset_struct`
    #include <harp.h>

    HARP Dataset struct