/*
 * Copyright 2010 Nathan Phillip Brink
 *
 * This file is a part of DistRen.
 *
 * DistRen is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * DistRen is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with DistRen.  If not, see <http://www.gnu.org/licenses/>.
 */

#ifndef _DISTREN_CSV_H
#define _DISTREN_CSV_H

#include <list.h>
#include <stdlib.h>

/**
 * \brief
 *   A single row in a CSV.
 */
struct csv_row
{
  /**
   * \brief
   *   An array of NULL-terminated strings representing each column of
   *   a row in a CSV
   *
   * There are num_cols indexes to this array.
   */
  char **cols;
  size_t num_cols;
};
/**
 * \brief
 *   A row handle.
 */
typedef struct csv_row *csv_row_t;

/**
 * \brief
 *   Initialize a row handle.
 * \param columns
 *   The number of columns this row handle shall have.
 */
csv_row_t csv_row_init(size_t columns);

/**
 * \brief
 *   Parses a CSV file with a predetermined number of columns.
 *
 * If a line of the CSV file contains fewer columns than passed in by
 * the columns parameter, then the missing columns are just set to
 * instances of the empty string. If a line of the CSV file contains
 * more columns than specified by the columns parameter, then the
 * extra columns of the input are silently ignored.
 *
 * \param inbuf
 *   A NULL-terminated string to parse as CSV.
 * \param columns
 *   The number of columns the result should have.
 *
 * \return
 *   A list of csv_row_t handles.
 */
list_t csv_parse(const char *inbuf, size_t columns);

/**
 * \brief
 *   Frees a row allocated by csv_parse() or csv_row()
 *
 * You may use this in conjunction with list_free() to free an entire
 * CSV. Use list_free(csv_row_list,
 * (list_dealloc_func_t)&csv_row_free);
 *
 * \param row
 *   The row to free.
 */
void csv_row_free(csv_row_t row);

#endif /* _DISTREN_CSV_H */