BIscan Namespace Reference

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.
Streamoperator>> (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 >
Streamoperator>> (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 >
Streamoperator>> (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 >
Streamoperator>> (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:
Streamoperator>> (Stream const &s, float &f)
 Skip leading blanks then parse a floating point number from the stream and store it into a float variable.
Streamoperator>> (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.
Streamoperator>> (Stream const &s, std::string &str)
 Parse a std::string out of the Stream. Skip leading whitespace. Does not nul terminate str.
Streamoperator>> (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>
Streamoperator>> (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.
Streamoperator>> (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 >
Streamoperator>> (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.

Detailed Description

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*.

Note:
You can define operator>> for classes of your own design in much the same way that you design them for iostreams. This can lead to code duplicate though -- one specialization for iostreams and another for Stream -- unless you make your operator>> be templatized on the stream type.
Warning:
When you use BIscan::Stream to extract a character, you will get a character not an eight bit signed integer. An unsigned char, however is treated as a number, not a character.

Function Documentation

BinaryParsed<IntegerType> BIscan::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.

Returns:
BinaryParsed<IntegerType>
Parameters:
[in,out] t The integer to be parsed as binary from the the stream.

Definition at line 1571 of file BIscan.h.

bool BIscan::convertDouble ( StringType const &  s,
double &  d 
)

Convert a string, possibly with leading blanks, into an double.

Returns:
true if the conversion is successful
Parameters:
[in] s the nul terminated string to convert
[out] d a reference to the returned value

Definition at line 502 of file BIscan.h.

Here is the call graph for this function:

bool BIscan::convertDouble ( char const *const &  s,
double &  d 
)

Convert a string, possibly with leading blanks, into an double.

Returns:
true if the conversion is successful
Parameters:
[in] s the nul terminated string to convert
[out] d a reference to the returned value

Definition at line 484 of file BIscan.h.

Here is the call graph for this function:

bool BIscan::convertFloat ( StringType const &  s,
float &  f 
)

Convert a string, possibly with leading blanks, into an float.

Returns:
true if the conversion is successful
Parameters:
[in] s the nul terminated string to convert
[out] f a reference to the returned value

Definition at line 543 of file BIscan.h.

Here is the call graph for this function:

bool BIscan::convertFloat ( char const *const &  s,
float &  f 
)

Convert a string, possibly with leading blanks, into an float.

Returns:
true if the conversion is successful
Parameters:
[in] s the nul terminated string to convert
[out] f a reference to the returned value

Definition at line 518 of file BIscan.h.

Here is the call graph for this function:

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.

Returns:
true if the conversion is successful
Parameters:
[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)
Note:
This function only accepts bases in the range: 2-10 and 16.

Definition at line 402 of file BIscan.h.

Here is the call graph for this function:

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.

Returns:
true if the conversion is successful
Parameters:
[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)
Note:
This function only accepts bases in the range: 2-10 and 16.

Definition at line 375 of file BIscan.h.

Here is the call graph for this function:

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.

Returns:
a number in the range 0 - base-1.
Parameters:
[in] c the character to be converted into a number.
[in] base the numeric base of the conversion. (Defaults to 10)
Warning:
base may only take on the following values: 2-10 and 16. No error detection is made by this routine.

Definition at line 200 of file BIscan.h.

Here is the caller graph for this function:

HexParsed<IntegerType> BIscan::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.

Returns:
HexParsed<IntegerType>
Parameters:
[in,out] t The integer to be parsed as hex from the the stream.

Definition at line 1351 of file BIscan.h.

bool BIscan::isValidDigit ( char  c,
int  base 
)

Determine if a character is a valid digit in the specified base.

Returns:
true if c is a valid digit.
Parameters:
[in] c the character of interest.
[in] base the numeric base of interest.
Note:
Base may only take on values of 2-10 and 16. Other values treated as silent errors and no character will match those bases.

Definition at line 174 of file BIscan.h.

Here is the caller graph for this function:

OctalParsed<IntegerType> BIscan::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.

Returns:
OctalParsed<IntegerType>
Parameters:
[in,out] t The integer to be parsed as octal from the the stream.

Definition at line 1460 of file BIscan.h.

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.

Returns:
A stream which no longer contains matching characters.
Parameters:
[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.

Here is the call graph for this function:

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.

Here is the call graph for this function:

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;
Parameters:
[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.

Here is the call graph for this function:

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.
Parameters:
[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.

Here is the call graph for this function:

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.

Returns:
The stream minus the parsed number.
Parameters:
[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.

Here is the call graph for this function:

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.

Returns:
The stream minus the parsed number.
Parameters:
[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.

Here is the call graph for this function:

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.

Returns:
The stream minus the parsed string.
Parameters:
[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.

Here is the call graph for this function:

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.

Returns:
The stream without the matching string.
Parameters:
[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.

Here is the call graph for this function:

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.

Here is the call graph for this function:

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.

Here is the call graph for this function:

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.

Here is the call graph for this function:

bool BIscan::parseDouble ( Iterator &  firstRef,
Iterator const &  last,
double &  d 
)

Parse a double from a string. Leading blanks are ignored.

Returns:
true to indicate success.
Parameters:
[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.

Here is the caller graph for this function:

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.

Returns:
true if the parsing was successfull.
Parameters:
[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
Note:
: the input character start value is modified only if the parsing was successful.

Definition at line 274 of file BIscan.h.

Here is the call graph for this function:

Here is the caller graph for this function:

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.

Returns:
true if the text found between start and end is a valid unsigned decimal integer. Note that leading white space is NOT removed prior to the conversion!
Parameters:
[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.

Here is the caller graph for this function:

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

Definition at line 1729 of file BIscan.h.

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.

Definition at line 1746 of file BIscan.h.

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

Definition at line 1713 of file BIscan.h.

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.

Definition at line 1698 of file BIscan.h.

Generated on Wed Feb 29 22:52:18 2012 for CXXUtilities by  doxygen 1.6.3