csv.h

Go to the documentation of this file.
00001 /*
00002  * csv.h
00003  *
00004  * Copyright (C) 2007,2008  Thomas A. Vaughan
00005  * All rights reserved.
00006  *
00007  *
00008  * Redistribution and use in source and binary forms, with or without
00009  * modification, are permitted provided that the following conditions are met:
00010  *     * Redistributions of source code must retain the above copyright
00011  *       notice, this list of conditions and the following disclaimer.
00012  *     * Redistributions in binary form must reproduce the above copyright
00013  *       notice, this list of conditions and the following disclaimer in the
00014  *       documentation and/or other materials provided with the distribution.
00015  *     * Neither the name of the <organization> nor the
00016  *       names of its contributors may be used to endorse or promote products
00017  *       derived from this software without specific prior written permission.
00018  *
00019  * THIS SOFTWARE IS PROVIDED BY THOMAS A. VAUGHAN ''AS IS'' AND ANY
00020  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00021  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00022  * DISCLAIMED. IN NO EVENT SHALL THOMAS A. VAUGHAN BE LIABLE FOR ANY
00023  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00024  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00025  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
00026  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
00027  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00028  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00029  *
00030  */
00031 
00032 #ifndef WAVEPACKET_UTIL_CSV_H__
00033 #define WAVEPACKET_UTIL_CSV_H__
00034 
00035 
00036 // includes --------------------------------------------------------------------
00037 #include "common/common.h"
00038 
00039 #include <iostream>
00040 
00041 
00042 /// \ingroup util
00043 /*@{*/
00044 
00045 
00046 /**
00047  * \defgroup csv Comma Separated Values
00048  *
00049  * Wrapper for comma-separated-value (csv) files.
00050  *
00051  * This is for special files where:
00052  *   1) columns are delimited by commas (duh),
00053  *   2) the first row defines the column names (and column names are unique!),
00054  *   3) all subsequent rows have the same number of columns
00055  *
00056  * NOTE: the csv parser respects the orders of the input column names!
00057  * If you specify the ordering as "A,B,C", you'll receive that order in the
00058  *   callback vector, even if the data is actually ordered as "C,A,B".
00059  * Put another way: applications can assume that data is ordered in the
00060  *   callback data array in the exact same column order that was passed in
00061  *   to the parseCsvStream() call.
00062  */
00063 /*@{*/
00064 
00065 ////////////////////////////////////////////////////////////////////////////////
00066 //
00067 //      csv parsing API
00068 //
00069 ////////////////////////////////////////////////////////////////////////////////
00070 
00071 // col_data_t : for a given column, contains name and value
00072 struct col_data_t {
00073         const char *    col_name;
00074         const char *    value;
00075 };
00076 
00077 /// vector of values provided to callback
00078 typedef std::vector<col_data_t> vec_col_t;
00079 
00080 /// callback for parseCsvStream()
00081 typedef void (*csv_callback_fn)(IN void * context,
00082                                 IN const vec_col_t& data);
00083 
00084 
00085 /// parse a stream of lines containing comma-separated values.
00086 ///
00087 /// The caller must provide:
00088 ///  - the input stream
00089 ///  - a vector of the desired fields they would like
00090 ///  - a callback routine
00091 ///
00092 /// This routine will:
00093 ///  - parse the first line as column headers
00094 ///  - parse each remaining line as comma-separated values
00095 ///  - based on the header line, find the values the caller asked for
00096 ///  - put the values in the order the caller asked for
00097 ///  - call the callback with the values
00098 void parseCsvStream(IN std::istream& in,
00099                                 IN const VecString& columns,
00100                                 IN csv_callback_fn callback,
00101                                 IN void * context);
00102                                 
00103 
00104 #endif  // WAVEPACKET_UTIL_CSV_H__
00105