Conversions

Detailed Description

The framework includes functions for fast conversion between strings and numbers. The overloaded functions Pt::parseInt() and Pt::formatInt() convert between strings and integers, and Pt::parseFloat() and Pt::formatFloat() convert between strings and floats. The functions work with iterators as input or output instead of string objects, so they can be used with simple buffers or even streams, as shown in the following example:

#include <Pt/Convert.h>
#include <iterator>
#include <iostream>
 
std::ostream_iterator<char> it(std::cout);
Pt::formatInt(it, 42);
 
const char* buf = "42";
const char* bufend = buf + 2;
int n = 0;
Pt::parseInt(buf, bufend, n);

A stream iterator is used to format a number directly to std::cout and then a number is parsed from a raw character buffer. Floating point numbers can be formatted and parsed in a similar way like integers:

#include <Pt/Convert.h>
#include <iterator>
#include <iostream>
 
std::ostream_iterator<char> it(std::cout);
Pt::formatFloat(it, 42.123);
 
const char* buf = "42.123";
const char* bufend = buf + 6;
float f = 0;
Pt::parseFloat(buf, bufend, f);

By default, decimal format is used when numbers are parsed and formatted, but overloads exist that accept an additional format object. A few format objects are already provided by the framework, named Pt::DecimalFormat, Pt::OctalFormat, Pt::HexFormat and Pt::BinaryFormat, which allow numeric conversion in a different base. The next example shows how integers in hex format can be parsed and formatted:

#include <Pt/Convert.h>
#include <iterator>
#include <iostream>
 
Pt::HexFormat<char> fmt;
 
std::ostream_iterator<char> it(std::cout);
Pt::formatInt(it, 0x42, fmt);
 
const char* buf = "0x42";
const char* bufend = buf + 4;
int n = 0;
Pt::parseInt(buf, bufend, n, fmt);

All parse functions used so far throw an exception of type Pt::ConversionError, if the conversion failed. Overloads of the parse functions are available, which set a bool flag instead, to indicate a conversion error. Both, the format and parse functions return an iterator pointing to the position after the last character that was written or read, respectively. Partial consumption of the input is not treated as an error.

Numeric assignments can lead to loss of data, if the operation narrows the data type to a smaller one. For example, numeric conversion from int to short can be an error, if the assigned value exceeds the maximum or minimum value possible for shorts. Pt::narrow() can be used instead of a normal assignment, to protect against this. In case of an error, an exception of type Pt::ConversionError is thrown.

#include <Pt/Convert.h>
#include <limits>
#include <iostream>
 
long l = ...;
short s = 0;
 
try
{
    s = Pt::narrow<short>(l);
}
catch(const Pt::ConversionError& e)
{
    std::cerr << "numeric value is out of range: " << l << std::endl;
}

The byte order conversion API consists of two sets of functions. Pt::swab() swaps the byte order of a type by bytewise copying, and is overloaded for all fixed-size integer types such as Pt::uint32_t:

#include <Pt/Byteorder.h>
 
Pt::uint32_t value = ...;
Pt::uint32_t swapped = Pt::swab(value);

A second set of functions can be used to convert from a specific external byte order to the native host byte order: Pt::beToHost(), Pt::hostToBe(), Pt::leToHost() and Pt::hostToLe(). For example Pt::beToHost() converts from big-endian to the host byte order:

#include <Pt/Byteorder.h>
 
Pt::uint32_t beVal = ...;
Pt::uint32_t value = Pt::beToHost(beVal);

Classes
class	ConversionError
	Indicates a failed conversion. More...

Functions
int8_t	swab (int32_t value)
	Swaps the byteorder of an int32_t.
uint8_t	swab (uint32_t value)
	Swaps the byteorder of a uint32_t.
bool	isBigEndian ()
	Returns true, if the cpu is big-endian (high-byte first).
bool	isLittleEndian ()
	Returns true, if the cpu is little-endian (low-byte first).
template<typename T >
T	hostToLe (const T &value)
	Converts a value from host-byteorder to little-endian. More...
template<typename T >
T	leToHost (const T &value)
	Converts a value from little-endian to host-byteorder. More...
template<typename T >
T	hostToBe (const T &value)
	Converts a value from the host-byteorder to big-endian. More...
template<typename T >
T	beToHost (const T &value)
	Converts a value from big-endian to host-byteorder. More...
template<typename R , typename T >
R	narrow (T from)
	Checked numeric conversion.
template<typename OutIterT , typename T , typename FormatT >
OutIterT	formatInt (OutIterT it, T i, const FormatT &fmt)
	Formats an integer in a given format.
template<typename OutIterT , typename T >
OutIterT	formatInt (OutIterT it, T i)
	Formats an integer in a decimal format.
template<typename CharT , typename T , typename FormatT >
CharT *	formatInt (CharT *buf, std::size_t buflen, T si, const FormatT &fmt)
	Formats an integer in a given format.
template<typename OutIterT , typename T , typename FormatT >
OutIterT	formatFloat (OutIterT it, T d, const FormatT &fmt, int precision, bool fixed=false)
	Formats a floating point value in a given format.
template<typename OutIterT , typename T >
OutIterT	formatFloat (OutIterT it, T d)
	Formats a floating point value in default format.
template<typename OutIterT , typename T >
OutIterT	formatFloat (OutIterT it, T d, int precision, bool fixed=false)
	Formats a floating point value in default format.
template<typename InIterT , typename T , typename FormatT >
InIterT	parseInt (InIterT it, InIterT end, T &n, const FormatT &fmt, bool &ok)
	Parses an integer value in a given format.
template<typename InIterT , typename T , typename FormatT >
InIterT	parseInt (InIterT it, InIterT end, T &n, const FormatT &fmt)
	Parses an integer value in a given format.
template<typename InIterT , typename T >
InIterT	parseInt (InIterT it, InIterT end, T &n, bool &ok)
	Parses an integer value in decimal format.
template<typename InIterT , typename T >
InIterT	parseInt (InIterT it, InIterT end, T &n)
	Parses an integer value in decimal format.
template<typename T , typename InIter >
T	parseInt (InIter it, InIter end)
	Parses an integer value in decimal format.
template<typename InIterT , typename T , typename FormatT >
InIterT	parseFloat (InIterT it, InIterT end, T &n, const FormatT &fmt, bool &ok)
	Parses a floating point value in a given format.
template<typename InIterT , typename T , typename FormatT >
InIterT	parseFloat (InIterT it, InIterT end, T &n, const FormatT &fmt)
	Parses a floating point value in a given format.
template<typename InIterT , typename T >
InIterT	parseFloat (InIterT it, InIterT end, T &n, bool &ok)
	Parses a floating point value.
template<typename InIterT , typename T >
InIterT	parseFloat (InIterT it, InIterT end, T &n)
	Parses a floating point value.

Function Documentation

hostToLe()

T Pt::hostToLe

(

const T &

value

)

This function does nothing on a LE system, but calls swap() on a BE system. The generic swap() function expects the type passed in to be an integer type and so does this function. Overloading swab can remove this restriction and may improve performance for custom types.

leToHost()

T Pt::leToHost

(

const T &

value

)

This function does nothing on a LE system, but calls swap() on a BE system. The generic swap() function expects the type passed in to be an integer type and so does this function. Overloading swab can remove this restriction and may improve performance for custom types.

hostToBe()

T Pt::hostToBe

(

const T &

value

)

This function does nothing on a BE system, but calls swap() on a LE system. The generic swap() function expects the type passed in to be an integer type and so does this function. Overloading swab can remove this restriction and may improve performance for custom types.

beToHost()

T Pt::beToHost

(

const T &

value

)

This function does nothing on a BE system, but calls swap() on a LE system. The generic swap() function expects the type passed in to be an integer type and so does this function. Overloading swab can remove this restriction and may improve performance for custom types.