FBB::CSV(3bobcat)
CSV convertor
(libbobcat-dev_4.07.00-x.tar.gz)
2005-2017
NAME
FBB::CSV - 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
- 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
SEE ALSO
bobcat(7)
BUGS
None Reported.
DISTRIBUTION FILES
- bobcat_4.07.00-x.dsc: detached signature;
- bobcat_4.07.00-x.tar.gz: source archive;
- bobcat_4.07.00-x_i386.changes: change log;
- libbobcat1_4.07.00-x_*.deb: debian package holding the
libraries;
- libbobcat1-dev_4.07.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 (f.b.brokken@rug.nl).