FBB::CSV(3) Converter for comma separated values

SYNOPSIS

#include <bobcat/csv>

Linking option: -lbobcat

DESCRIPTION

Objects of the class CSV can be used to convert series of comma separated values to the individual separated values. These values may be converted (individually or as a group) to standard integral types int, size_t, long long, etc., to floating point types (float, double, long double), or they can be accessed as std::string values.

NAMESPACE

FBB
All constructors, members, operators and manipulators, mentioned in this man-page, are defined in the namespace FBB.

INHERITS FROM

-

TYPEDEFS AND ENUMS

The enum Mode specifies how a CSV is extracted from std::istream objects:

  • TRAILINGCOMMA a series of comma-separated values ends at a final comma, which is removed from the istream by the CSV extraction operator.
  • LINE after extracting a CSV object any remaining characters on the current std::istream line are ignored (i.e., the extraction operator reads full lines of input). These enumeration values may be combined using the bit-or operator.

The enum InsertType specifies how a CSV is inserted into std::ostream objects:

  • LENGTH indicates that all specifications (i.e., the length of the type-specifications, see the member length below), are inserted into the std::ostream as a series of comma-separated values.
  • SIZE indicates that all (not ignored) comma-separated fields (i.e., the size of the fields vector, see the member size below), are inserted into the std::ostream as a series of comma-separated values.
  • COUNT indicates that all valid (i.e., the count of the valid fields, see the member count below), are inserted into the std::ostream as a series of comma-separated values.

The class CSV defines the nested classes const_iterator and const_reverse_iterator which are InputIterators, which can be used to iterate over the sequence of comma-separated values.

CONSTRUCTORS

o
CSV(std::string const &specification, Mode mode = LINE, InsertType = LENGTH):
The specification in specification defines the subsequent fields of the comma-separated value. Specifications are
  • S: the field is left as-is, and can be retrieved as a std::string.
  • I: the field represents an int value;
  • D: the field represents a double value;
  • X or -: the field is ignored and is not stored inside the CSV object. E.g., with the specification SXS two fields will actually be stored inside the CSV object: field 0 contains the first field extracted from the input stream, field 1 contains the third field extracted from the input stream.
Specifications may be separated by space or tab characters, which are ignored. The number of specification characters determines the number of fields that are stored in a CSV object. The final field may or may not be followed by a comma.
Each specification may also be followed by a positive integral value, indicating that the input at that point contains that number of comma-separated fields of the specified type.
By default the CSV extraction operator extracts complete lines from the stream from which a CSV object is extracted.
When inserting a CSV object into a std::ostream object all fields that are specified by `specification' will be inserted. Ignored fields will be inserted as single blanks. The default, copy, and move constructors are available.

OVERLOADED OPERATORS

  • std::string const &operator[](size_t index) const:
    The contents of the indicated field is returned as a std::string.
  • std::istream &operator>>(std::istream &out, CSV const &csv):
    The data fields stored within csv are inserted into out as a series of comma-separated values. The fields are inserted according to the latest InsertType specification:
  • For LENGTH all fields are inserted according to their original type specification, where 'X' and '-' fields are inserted as fields of single blank spaces;
  • For SIZE all fields that are stored inside csv are inserted `as-is';
  • For COUNT all valid fields are inserted.
    • If csv's Mode specification contains TRAILINGCOMMA then a comma is expected and extracted beyond the last field; if it contains LINE then any information that is found on the line beyond the last field (including its terminating comma, if applicable) is ignored (including the '\n' line terminator).
  • std::ostream &operator<<(std::ostream &out, CSV const &csv):
    The data fields stored within csv are inserted into out as a series of comma-separated values. The fields are inserted according to the latest InsertType specification:
  • For LENGTH all fields are inserted according to their original type specification, where 'X' and '-' fields are inserted as fields of single blank spaces;
  • For SIZE all fields that are stored inside csv are inserted `as-is';
  • For COUNT all valid fields are inserted.
    • If csv's Mode specification contains TRAILINGCOMMA then a comma is inserted beyond the last field.

The copy and move assignment operators are available.

MEMBER FUNCTIONS

  • CSV &append(char spec, std::string const &value = ""):
    A field spec, with textual representation value is added to the object's current set of fiels. A specification 'X' or '-' is added to the object's set of specifications, but does not add value to the currently stored set of values.
  • std::vector<bool> const &available() const:
    A vector of bool values indicating which of the matching data fields are valid (i.e., could be converted to its specification as defined at construction time or by setSpec) is returned.
  • CSV::const_iterator<Type> begin<Type == std::string>() const:
    This is a template member returning a CSV::const_iterator to the object's first field. When dereferencing a const_iterator the value it refers to is converted to the indicated Type. If the conversion fails, the Type's default value is returned.
  • size_t count() const:
    The number of fields that could actually be converted to their indicated types is returned. E.g., an empty field or a supposedly numeric field whose contents cannot be converted to the indicated numeric value won't be counted here.
  • std::vector<std::string> const &data() const:
    The vector of fields stored inside the CSV object is returned.
  • CSV::const_iterator<Type> end<Type == std::string>() const:
    This is a template member returning a CSV::const_iterator pointing just beyond the CSV object's last field.
  • Type field<Type = std::string>(size_t idx) const:
    This is a template member returning the contents of field idx as a value of type Type. When Type equals std::string a std::string const & is returned. For Type all integral and floating types as well as std::sting are accepted. If field idx cannot be converted to Type a std::exception is thrown.
  • Type get<Type = std::string>(size_t idx):
    This is a template member returning the contents of field idx as a value of type Type. When Type equals std::string a std::string const & is returned. For Type all integral and floating types as well as std::sting are accepted. If field idx cannot be converted to Type, the Type's default value is returned.
  • InsertType insertType() const:
    The object's current InsertType is returned.
  • size_t length() const:
    The number of specifications (defined at construction time or by the setSpec member) is returned. This count includes the number of X and - specifications.
  • CSV::Mode mode() const:
    The object's current Mode value is returned.
  • std::string const &spec() const:
    The object's current field-type specifications are returned.
  • CSV::const_reverse_iterator<Type> rbegin<Type == std::string>() const:
    This is a template member returning a CSV::const_reverse_iterator to the object's last field. When dereferencing a const_reverse_iterator the value it refers to is converted to the indicated Type. If the conversion fails, the Type's default value is returned.
  • CSV::const_iterator<Type> rend<Type == std::string>() const:
    This is a template member returning a CSV::const_reverse_iterator pointing just before the CSV object's first field.
  • void setInsertType(InsertType insertType):
    The objects InsertType is changed to insertType. This has no immediate effect, but is only interpreted with the insertion operator.
  • void setMode(Mode mode):
    The object's current Mode value is changed to mode. This has no immediate effect, but is only interpreted with the insertion and extraction operators.
  • void setSpec(std::string const &spec):
    The information stored inside the CSV object is erased, and a new field-specification is defined from spec.
  • size_t size() const:
    The number of fields is returned (the returned value equals the value returned by length not counting the X and - fields).

EXAMPLE

#include <iostream>
#include <bobcat/csv>
using namespace std;
using namespace FBB;
int main()
{
    CSV csv("I5 X2 S2 D3");
    cin >> csv;
    cout << 
        "Nr. of field specs: " << csv.length() << "\n"
        "Nr. of fields: " << csv.size() << "\n"
        "Nr. of available fields: " << csv.count() << "\n"
        "Field 2 as int via get: " << csv.get<int>(2) << "\n"
        "Field 2 as int via available: " << csv.field<int>(2) << "\n"
        "Field 3 via operator[]: " << csv[3] << "\n"
        "Field 6 as string via get: " << csv.get<string>(6) << "\n"
        "Field 6 as string via available: " << csv.field<string>(6) << "\n"
    ;
    cout << "First element as string: " << *csv.begin() << "\n";
    cout << "All elements as strings:\n";
    copy(csv.begin(), csv.end(), ostream_iterator<string>(cout, " "));
    cout << '\n';
    
    cout << "All elements as ints:\n";
    copy(csv.begin<int>(), csv.end<int>(), ostream_iterator<int>(cout, " "));
    cout << '\n';
    cout << "All elements as strings, backward:\n";
    copy(csv.rbegin(), csv.rend(), ostream_iterator<string>(cout, " "));
    cout << '\n';
    
    cout << "All elements as ints, backward:\n";
    copy(csv.rbegin<int>(), csv.rend<int>(), ostream_iterator<int>(cout, " "));
    cout << '\n';
    cout << "Insert LENGTH (default):\n" <<
            csv << '\n';
    csv.setInsertType(CSV::SIZE);
    cout << "Insert SIZE:\n" <<
            csv << '\n';
    csv.setInsertType(CSV::COUNT);
    cout << "Insert COUNT:\n" <<
            csv << '\n';
}

FILES

bobcat/csv - defines the class interface

BUGS

None Reported.

DISTRIBUTION FILES

  • bobcat_4.02.00-x.dsc: detached signature;
  • bobcat_4.02.00-x.tar.gz: source archive;
  • bobcat_4.02.00-x_i386.changes: change log;
  • libbobcat1_4.02.00-x_*.deb: debian package holding the libraries;
  • libbobcat1-dev_4.02.00-x_*.deb: debian package holding the libraries, headers and manual pages;
  • http://sourceforge.net/projects/bobcat: public archive location;

BOBCAT

Bobcat is an acronym of `Brokken's Own Base Classes And Templates'.

COPYRIGHT

This is free software, distributed under the terms of the GNU General Public License (GPL).

AUTHOR

Frank B. Brokken ([email protected]).

SEE ALSO

LAST SEARCHED