NAME¶
FBB::CSV - Convertor 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:
- o
- TRAILINGCOMMA a series of comma-separated values ends at a final
comma, which is removed from the istream by the CSV
extraction operator.
- o
- 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:
- o
- 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.
- o
- 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.
- o
- 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
- o
- S: the field is left as-is, and can be retrieved as a
std::string.
- o
- I: the field represents an int value;
- o
- D: the field represents a double value;
- o
- 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¶
- o
- std::string const &operator[](size_t index) const:
The contents of the indicated field is returned as a
std::string.
- o
- 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:
- o
- For LENGTH all fields are inserted according to their original type
specification, where ’X’ and ’-’
fields are inserted as fields of single blank spaces;
- o
- For SIZE all fields that are stored inside csv are inserted
`as-is’;
- o
- 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).
- o
- 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:
- o
- For LENGTH all fields are inserted according to their original type
specification, where ’X’ and ’-’
fields are inserted as fields of single blank spaces;
- o
- For SIZE all fields that are stored inside csv are inserted
`as-is’;
- o
- 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¶
- o
- 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.
- o
- 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.
- o
- 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.
- o
- 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.
- o
- std::vector<std::string> const &data() const:
The vector of fields stored inside the CSV object is returned.
- o
- 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.
- o
- 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.
- o
- 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.
- o
- InsertType insertType() const:
The object’s current InsertType is returned.
- o
- 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.
- o
- CSV::Mode mode() const:
The object’s current Mode value is returned.
- o
- std::string const &spec() const:
The object’s current field-type specifications are returned.
- o
- 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.
- o
- 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.
- o
- void setInsertType(InsertType insertType):
The objects InsertType is changed to insertType. This has no
immediate effect, but is only interpreted with the insertion
operator.
- o
- 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.
- o
- void setSpec(std::string const &spec):
The information stored inside the CSV object is erased, and a new
field-specification is defined from spec.
- o
- 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
SEE ALSO¶
bobcat(7)
BUGS¶
None Reported.
DISTRIBUTION FILES¶
- o
- bobcat_3.23.01-x.dsc: detached signature;
- o
- bobcat_3.23.01-x.tar.gz: source archive;
- o
- bobcat_3.23.01-x_i386.changes: change log;
- o
- libbobcat1_3.23.01-x_*.deb: debian package holding the
libraries;
- o
- libbobcat1-dev_3.23.01-x_*.deb: debian package holding the
libraries, headers and manual pages;
- o
- 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 (
f.b.brokken@rug.nl).