Namespace BIscan defines a variety of fast text scanning classes and functions which eliminate the overhead found using iostreams when scanning simple text buffers for builtin types. Basically, using class BIscan::Stream is like using sscanf -- and is 3X faster for integers because of inlining. For example: More...
Classes | |
struct | BinaryParsed |
This class is a wrapper around a reference to an integer, which exists so that that operator>> can be specialized such that when a binary object is serialized, it will parse the stream for a binary integer instead of a decimal integer. More... | |
struct | HexParsed |
This class is a wrapper around a reference to an integer which exists so that that operator>> can be specialized such that when a Hex object is serialized, it will parse the stream for a hex integer instead of a decimal integer. More... | |
struct | IsIntType |
Wrapper around the member, value, which will be 1 if T is an integral type (including unsigned char but not regular char). For all other types, value will be 0. More... | |
struct | OctalParsed |
This class is a wrapper around a reference to an integer which exists so that that operator>> can be specialized such that when a Octal object is serialized, it will parse the stream for a octal integer instead of a decimal integer. More... | |
struct | SKIPSET |
An object which represents a set of characters which a Stream should ignore when parsing with operator>>. The parsed characters are discarded from the stream. At least one member of the set must appear or an error results. More... | |
class | Stream |
A Representation of a stream of bytes that can be parsed quickly. See its related operator >> functions. The Stream does not own the bytes, and so they must not be changed or destroyed while the parsing process is in effect. More... | |
struct | StreamReader |
StreamReader is a class used to parse integers out of stream. The default implementation will not allow ANY class to compile. You must use a specialization to get the code to compile. See StreamReader specializations below. We made add specializations to StreamReader later to allow other kinds of classes to be parsable. More... | |
struct | StreamReader< T, 1 > |
Decimal Integer StreamReader. More... | |
struct | StreamReader< T, 3 > |
Hexadecimal Integer StreamReader. More... | |
struct | StreamReader< T, 5 > |
Octal Integer StreamReader. More... | |
struct | StreamReader< T, 7 > |
Binary Integer StreamReader. More... | |
Functions | |
template<class IntegerType > | |
BinaryParsed< IntegerType > | Binary (IntegerType &t) |
Construct a wrapper around an integer reference to indicate to the Stream parsing logic that the integer should be parsed as binary. | |
template<class StringType > | |
bool | convertDouble (StringType const &s, double &d) |
Convert a string, possibly with leading blanks, into an double. | |
bool | convertDouble (char const *const &s, double &d) |
Convert a string, possibly with leading blanks, into an double. | |
template<class StringType > | |
bool | convertFloat (StringType const &s, float &f) |
Convert a string, possibly with leading blanks, into an float. | |
bool | convertFloat (char const *const &s, float &f) |
Convert a string, possibly with leading blanks, into an float. | |
template<class T , class StringType > | |
bool | convertInteger (StringType const &s, T &integer, int base=10, int signable=true) |
Convert a std::string, possibly with leading blanks, into an integer. | |
template<class T > | |
bool | convertInteger (char const *const &s, T &integer, int base=10, int signable=true) |
Convert a string, possibly with leading blanks, into an integer. | |
int | digitValue (char c, int base=10) |
Determine the numeric value of a character in a given base. The character and the base are assumed to be a valid combination and no error checking is done, use isValidDigit() for that. | |
template<class IntegerType > | |
HexParsed< IntegerType > | Hex (IntegerType &t) |
Construct a wrapper around an integer reference to indicate to the Stream parsing logic that the integer should be parsed as hexadecimal. | |
bool | isValidDigit (char c, int base) |
Determine if a character is a valid digit in the specified base. | |
template<class IntegerType > | |
OctalParsed< IntegerType > | Octal (IntegerType &t) |
Construct a wrapper around an integer reference to indicate to the Stream parsing logic that the integer should be parsed as octal. | |
Stream & | operator>> (Stream &s, SKIPSET const &cs) |
Verify that the specified stream contains one or more characters which is found in the specified character set. | |
template<class IntegerType > | |
Stream & | operator>> (Stream const &s, BinaryParsed< IntegerType > o) |
This overload of the Stream output operator is designed to trigger binary rather than decimal parsing of of integers from the stream. The BinaryParsed<> object which is passed in as a parameter is nothing more than a wrapper around some integer which should be parsed as hex rather than decimal. Unlike the i/o streams, there are no stream states, instead, you accomplish hex parsing like this: | |
template<class IntegerType > | |
Stream & | operator>> (Stream const &s, OctalParsed< IntegerType > o) |
This overload of the Stream output operator is designed to trigger octal rather than decimal parsing of of integers from the stream. The OctalParsed<> object which is passed in as a parameter is nothing more than a wrapper around some integer which should be parsed as hex rather than decimal. Unlike the i/o streams, there are no stream states, instead, you accomplish hex parsing like this: | |
template<class IntegerType > | |
Stream & | operator>> (Stream const &s, HexParsed< IntegerType > h) |
This overload of the Stream output operator is designed to trigger hexadecimal rather than decimal parsing of of integers from the stream. The HexParsed<> object which is passed in as a parameter is nothing more than a wrapper around some integer which should be parsed as hex rather than decimal. Unlike the i/o streams, there are no stream states, instead, you accomplish hex parsing like this: | |
Stream & | operator>> (Stream const &s, float &f) |
Skip leading blanks then parse a floating point number from the stream and store it into a float variable. | |
Stream & | operator>> (Stream const &s, double &d) |
Skip leading whitespace then parse a double precision floating point number from the stream and store it into a double variable. | |
Stream & | operator>> (Stream const &s, std::string &str) |
Parse a std::string out of the Stream. Skip leading whitespace. Does not nul terminate str. | |
Stream & | operator>> (Stream const &s, char const *skipString) |
Compare the contents of the stream to a specified string. If the stream contents exactly match all the characters in the string, in sequence, then the stream is moved passed the match. | |
template<size_t N> | |
Stream & | operator>> (Stream const &s, char(&array)[N]) |
Parse a string out of the stream and store it in an array of characters. Note that you must supply an array rather than a pointer for this to work. | |
Stream & | operator>> (Stream const &s, char &c) |
This overload of operator>> allows you to read characters out of Stream without ignoring whitespace. Its pretty sluggish though, you should probably consider using some other interface for any kind of bulk processing. See. | |
template<class IntegerType > | |
Stream & | operator>> (Stream const &s, IntegerType &variable) |
Template operator >> for the Stream class. It handles all data types for which specific overloads are not aleady defined, below. | |
template<class Iterator > | |
bool | parseDouble (Iterator &firstRef, Iterator const &last, double &d) |
Parse a double from a string. Leading blanks are ignored. | |
template<class T , class Iterator > | |
bool | parseInteger (Iterator &startRef, Iterator const &end, T &integer, int base=10, bool signable=true) |
Parse a signed or unsigned integer from a character range and store it in a integer variable. Remove leading blanks first. | |
template<class Iterator > | |
bool | parseUnsignedDecimal (Iterator &start, Iterator const &end, unsigned long long &tmp) |
A hardcoded parser for base 10 numbers which is used to speed it up parseInteger() slightly. | |
Stream | stream (char const *begin, size_t length) |
One of a family of overloaded functions that returns a stream whose type is based on its parameters. | |
template<class StringType > | |
Stream | stream (StringType const &s) |
One of a family of overloaded functions that returns a stream whose type is based on its parameters. | |
Stream | stream (char const *begin, char const *end) |
One of a family of overloaded functions that returns a stream whose type is based on its parameters. | |
Stream | stream (char const *const &p) |
One of a family of overloaded functions that returns a stream whose type is based on its parameters. |
Namespace BIscan defines a variety of fast text scanning classes and functions which eliminate the overhead found using iostreams when scanning simple text buffers for builtin types. Basically, using class BIscan::Stream is like using sscanf -- and is 3X faster for integers because of inlining. For example:
int x, y, z; stream("10 11 12") >> x >> y >> z;
With Stream, there are several operator>>() functions that actually trigger the scanning operations, though you can call the underlying parsers for even higher speeds if so desired.
There are many functions in this namespace that do not require the use of the Stream class but which let you parse numbers and streams out of character buffers directly. The Stream class is just a thin-wrapper around calls to these functions. Consider:
Stream doesn't let you parse any old data type of interest -- it is focused on integers, floats, char, character arrays, and strings. You can if you desire create your own operator>> for your own classes but the goal of the Stream class is to provide high speed conversion of builtin types.
iostreams are very powerful and flexible but also quite slow for this particular use. There is significant overhead found in constructing stringstream
from a character buffer. For example, creating a stringstream and then invoking operator>> to parse an integer is 5 times slower than using sscanf() and 15 times slower than class Stream's operator>>'s.
BIscan definitions exist to maximize flexibility and minimize overhead within the constraints of these limited goals. Many of the classes are designed such that they take iterator references as parameters and can thus be used to construct parsers of your own design even if you choose not to use the higher layers of scanners and converters in this namespace. See the functions named parse* and is*.
BinaryParsed<IntegerType> BIscan::Binary | ( | IntegerType & | t | ) |
bool BIscan::convertDouble | ( | StringType const & | s, | |
double & | d | |||
) |
bool BIscan::convertDouble | ( | char const *const & | s, | |
double & | d | |||
) |
bool BIscan::convertFloat | ( | StringType const & | s, | |
float & | f | |||
) |
bool BIscan::convertFloat | ( | char const *const & | s, | |
float & | f | |||
) |
bool BIscan::convertInteger | ( | StringType const & | s, | |
T & | integer, | |||
int | base = 10 , |
|||
int | signable = true | |||
) |
Convert a std::string, possibly with leading blanks, into an integer.
[in] | s | the nul terminated string to convert |
[out] | integer | a reference to the returned value |
[in] | base | the numeric base of the conversion (defaults to 10) |
[in] | signable | a flag indicating that the number can be negative (ie with a leading -) (defaults to true) |
Definition at line 402 of file BIscan.h.
bool BIscan::convertInteger | ( | char const *const & | s, | |
T & | integer, | |||
int | base = 10 , |
|||
int | signable = true | |||
) |
Convert a string, possibly with leading blanks, into an integer.
[in] | s | the nul terminated string to convert |
[out] | integer | a reference to the returned value |
[in] | base | the numeric base of the conversion (defaults to 10) |
[in] | signable | a flag indicating that the number can be negative (ie with a leading -) (defaults to true) |
Definition at line 375 of file BIscan.h.
int BIscan::digitValue | ( | char | c, | |
int | base = 10 | |||
) |
Determine the numeric value of a character in a given base. The character and the base are assumed to be a valid combination and no error checking is done, use isValidDigit() for that.
[in] | c | the character to be converted into a number. |
[in] | base | the numeric base of the conversion. (Defaults to 10) |
Definition at line 200 of file BIscan.h.
HexParsed<IntegerType> BIscan::Hex | ( | IntegerType & | t | ) |
bool BIscan::isValidDigit | ( | char | c, | |
int | base | |||
) |
Determine if a character is a valid digit in the specified base.
[in] | c | the character of interest. |
[in] | base | the numeric base of interest. |
Definition at line 174 of file BIscan.h.
OctalParsed<IntegerType> BIscan::Octal | ( | IntegerType & | t | ) |
Stream& BIscan::operator>> | ( | Stream & | s, | |
SKIPSET const & | cs | |||
) |
Verify that the specified stream contains one or more characters which is found in the specified character set.
Consume all matching characters from the stream. The stream must contain at least one matching character or the conversion is determined to have failed.
Leading whitespace is not skipped unless defined in the character set.
[in,out] | s | The stream of interest. |
[in] | cs | The characterset to match against. |
Note to skip whitespace, declare a character set containing " \r\n\t\b\a"
Definition at line 1670 of file BIscan.h.
Stream& BIscan::operator>> | ( | Stream const & | s, | |
BinaryParsed< IntegerType > | o | |||
) |
This overload of the Stream output operator is designed to trigger binary rather than decimal parsing of of integers from the stream. The BinaryParsed<> object which is passed in as a parameter is nothing more than a wrapper around some integer which should be parsed as hex rather than decimal. Unlike the i/o streams, there are no stream states, instead, you accomplish hex parsing like this:
int decimal, int binary; stream("10 10") >> decimal >> BIscan::Binary(binary); // decimal should be 10 and hex should be 2;
Definition at line 1589 of file BIscan.h.
Stream& BIscan::operator>> | ( | Stream const & | s, | |
OctalParsed< IntegerType > | o | |||
) |
This overload of the Stream output operator is designed to trigger octal rather than decimal parsing of of integers from the stream. The OctalParsed<> object which is passed in as a parameter is nothing more than a wrapper around some integer which should be parsed as hex rather than decimal. Unlike the i/o streams, there are no stream states, instead, you accomplish hex parsing like this:
int decimal, int octal; stream("10 10") >> decimal >> Octal(octal); // decimal should be 10 and hex should be 8;
[in] | s | The stream from which to parse the octal number. |
[out] | o | The OctalParsed<> wrapper defining the number to parse as octal. |
If an octal number is not found in the stream, the returned stream will be marked as bad.
If the above line of code fails to compile, it is because your
Definition at line 1478 of file BIscan.h.
Stream& BIscan::operator>> | ( | Stream const & | s, | |
HexParsed< IntegerType > | h | |||
) |
This overload of the Stream output operator is designed to trigger hexadecimal rather than decimal parsing of of integers from the stream. The HexParsed<> object which is passed in as a parameter is nothing more than a wrapper around some integer which should be parsed as hex rather than decimal. Unlike the i/o streams, there are no stream states, instead, you accomplish hex parsing like this:
int decimal, int hex; stream("10 10") >> decimal >> Hex(hex); // decimal should be 10 and hex should be 16.
[in] | s | The stream from which to parse the hex number. |
[out] | h | The HexParsed<> wrapper defining the number to parse as hex. |
If a hexadecimal number is not found in the stream, the returned stream will be marked as bad.
If the above line of code fails to compile, it is because your
Definition at line 1369 of file BIscan.h.
Stream& BIscan::operator>> | ( | Stream const & | s, | |
float & | f | |||
) |
Skip leading blanks then parse a floating point number from the stream and store it into a float variable.
[in] | s | The stream |
[out] | f | The floating point value to to received the parsed data. |
The returned string is set to bad if no number is available.
Definition at line 1278 of file BIscan.h.
Stream& BIscan::operator>> | ( | Stream const & | s, | |
double & | d | |||
) |
Skip leading whitespace then parse a double precision floating point number from the stream and store it into a double variable.
[in] | s | The stream |
[out] | d | The double precision floating point value to to received the parsed data. |
The returned string is set to bad if no number is available.
Definition at line 1250 of file BIscan.h.
Stream& BIscan::operator>> | ( | Stream const & | s, | |
std::string & | str | |||
) |
Parse a std::string out of the Stream. Skip leading whitespace. Does not nul terminate str.
[in] | s | The stream |
[out] | str | The string to received the parsed data. |
The returned string is set to bad if no string is available.
Definition at line 1226 of file BIscan.h.
Stream& BIscan::operator>> | ( | Stream const & | s, | |
char const * | skipString | |||
) |
Compare the contents of the stream to a specified string. If the stream contents exactly match all the characters in the string, in sequence, then the stream is moved passed the match.
Matching characters are discarded.
[in,out] | s | The stream of interest. |
[in] | skipString | The text to match. |
If the string is not found in the stream, the stream is marked as bad.
Note: leading whitespace is skipped in teh stream before processing begins. So a skipString should not contain leading whitespace.
Definition at line 1193 of file BIscan.h.
Stream& BIscan::operator>> | ( | Stream const & | s, | |
char(&) | array[N] | |||
) |
Parse a string out of the stream and store it in an array of characters. Note that you must supply an array rather than a pointer for this to work.
Leading blanks are discarded prior to parsing.
The output data will be nul terminated so the maximum string length returned is the size of the array minus 1.
Definition at line 1170 of file BIscan.h.
Stream& BIscan::operator>> | ( | Stream const & | s, | |
char & | c | |||
) |
This overload of operator>> allows you to read characters out of Stream without ignoring whitespace. Its pretty sluggish though, you should probably consider using some other interface for any kind of bulk processing. See.
Definition at line 1134 of file BIscan.h.
Stream& BIscan::operator>> | ( | Stream const & | s, | |
IntegerType & | variable | |||
) |
Template operator >> for the Stream class. It handles all data types for which specific overloads are not aleady defined, below.
Only integer types are actually supported.
If the above line of code fails to compile, it is because your
Definition at line 1108 of file BIscan.h.
bool BIscan::parseDouble | ( | Iterator & | firstRef, | |
Iterator const & | last, | |||
double & | d | |||
) |
Parse a double from a string. Leading blanks are ignored.
[in,out] | firstRef | Defines the start of the string buffer to parse. |
[in] | last | Defines the end of the character range. |
[out] | d | Specifies the variable to receive the data. |
Definition at line 430 of file BIscan.h.
bool BIscan::parseInteger | ( | Iterator & | startRef, | |
Iterator const & | end, | |||
T & | integer, | |||
int | base = 10 , |
|||
bool | signable = true | |||
) |
Parse a signed or unsigned integer from a character range and store it in a integer variable. Remove leading blanks first.
[in,out] | startRef | start of character buffer where string resides |
[in] | end | end of buffer |
[out] | integer | the output value |
[in] | base | a number in the range 2-10 or 16. Defines the base of the conversion (10 is the default). |
[in] | signable | a flag indicating that this number can be signed -- true by default |
Definition at line 274 of file BIscan.h.
bool BIscan::parseUnsignedDecimal | ( | Iterator & | start, | |
Iterator const & | end, | |||
unsigned long long & | tmp | |||
) |
A hardcoded parser for base 10 numbers which is used to speed it up parseInteger() slightly.
[in,out] | start | An interator to the first byte of the digit string. |
[in] | end | An interator to the first byte not in the string. |
[out] | tmp | A reference to the output value. |
Definition at line 234 of file BIscan.h.
Stream stream | ( | char const * | begin, | |
size_t | length | |||
) |
One of a family of overloaded functions that returns a stream whose type is based on its parameters.
The Stream returned does not have a copy of the stream data, only a pointer to it. You must not destruct or change the input pointer's data until parsing is complete.
This function converts a character byte range into a Stream
Stream stream | ( | StringType const & | s | ) |
One of a family of overloaded functions that returns a stream whose type is based on its parameters.
The Stream returned does not have a copy of the stream data, only a pointer to it. You must not destruct or change the input pointer's data until parsing is complete.
This function converts an stl style string into a Stream.
Stream stream | ( | char const * | begin, | |
char const * | end | |||
) |
One of a family of overloaded functions that returns a stream whose type is based on its parameters.
The Stream returned does not have a copy of the stream data, only a pointer to it. You must not destruct or change the input pointer's data until parsing is complete.
This function converts a character byte range into a Stream
Stream stream | ( | char const *const & | p | ) |
One of a family of overloaded functions that returns a stream whose type is based on its parameters.
The Stream returned does not have a copy of the stream data, only a pointer to it. You must not destruct or change the input pointer's data until parsing is complete.
This function converts a C style string into a Stream.