Enable unexternalization of fundamental types with identification.
More...
Detailed Description
- Outline
-
-
- Purpose:
- Enable unexternalization of fundamental types with identification.
-
- Classes:
-
-
- Macros:
| BSLX_TESTINSTREAM_EXCEPTION_TEST_BEGIN | macro to begin testing exceptions |
| BSLX_TESTINSTREAM_EXCEPTION_TEST_END | macro to end testing exceptions |
- See also:
- Component bslx_testoutstream, Component bslx_byteinstream
-
- Description:
- This component implements a byte-array-based input stream class,
bslx::TestInStream, that provides platform-independent input methods ("unexternalization") on values, and arrays of values, of fundamental types, and on bsl::string. bslx::TestInStream also verifies, for these types, that the type of data requested from the stream matches what was written to the stream. bslx::TestInStream is meant for testing only.
- The
bslx::TestInStream type reads from a user-supplied buffer directly, with no data copying or assumption of ownership. The user must therefore make sure that the lifetime and visibility of the buffer is sufficient to satisfy the needs of the input stream.
- This component is intended to be used in conjunction with the
bslx_testoutstream externalization component. Each input method of bslx::TestInStream reads either a value or a homogeneous array of values of a fundamental type, in a format that was written by the corresponding bslx::TestOutStream method. In general, the user of this component cannot rely on being able to read data that was written by any mechanism other than bslx::TestOutStream.
- The supported types and required content are listed in the
bslx package-level documentation under "Supported Types".
- Note that input streams can be invalidated explicitly and queried for validity and emptiness. Reading from an initially invalid stream has no effect. Attempting to read beyond the end of a stream will automatically invalidate the stream. Whenever an inconsistent value is detected, the stream should be invalidated explicitly.
-
- Input Limit:
- If exceptions are enabled at compile time, the test input stream can be configured to throw an exception after a specified number of input requests is exceeded. If the input limit is less than zero (default), then the stream never throws an exception. Note that a non-negative input limit is decremented after each input attempt, and throws only when the current input limit transitions from 0 to -1; no additional exceptions will be thrown until the input limit is again reset to a non-negative value.
- The input limit is set using the
setInputLimit manipulator.
-
- Exception Test Macros:
- This component also provides a pair of macros:
-
- These macros can be used for testing exception-safety of classes and their methods when BDEX streaming is involved. A reference to an object of type
bslx::TestInStream must be supplied as an argument to the *_BEGIN macro. Note that if exception-handling is disabled (i.e., if -DBDE_BUILD_TARGET_EXC was not supplied at compile time), then the macros simply print the following: BSLX EXCEPTION TEST -- (NOT ENABLED) --
-DBDE_BUILD_TARGET_EXC was supplied at compile time), the *_BEGIN macro will set the input limit of the supplied instream to 0, try the code being tested, catch any TestInstreamExceptions that are thrown, and keep increasing the input limit until the code being tested completes successfully.
-
- Usage:
- This section illustrates intended use of this component.
-
- Example 1: Basic Unexternalization Test:
- Suppose we wish to implement a (deliberately simple)
MyPerson class as a value-semantic object that supports BDEX externalization and unexternalization. In addition to whatever data and methods that we choose to put into our design, we must supply three methods having specific names and signatures in order to comply with the BDEX protocol: a class method maxSupportedBdexVersion, an accessor (i.e., a const method) bdexStreamOut, and a manipulator (i.e., a non-'const' method) bdexStreamIn. This example shows how to implement those three methods.
- In this example we will not worry overly about "good design" of the
MyPerson component, and we will declare but not implement illustrative methods and free operators, except for the three required BDEX methods, which are implemented in full. In particular, we will not make explicit use of bslma allocators; a more complete design would do so:
- First, we implement
MyPerson: class MyPerson {
bsl::string d_firstName;
bsl::string d_lastName;
int d_age;
friend bool operator==(const MyPerson&, const MyPerson&);
public:
static int maxSupportedBdexVersion(int versionSelector);
MyPerson();
MyPerson(const char *firstName, const char *lastName, int age);
MyPerson(const MyPerson& original);
~MyPerson();
MyPerson& operator=(const MyPerson& rhs);
template <class STREAM>
STREAM& bdexStreamIn(STREAM& stream, int version);
const bsl::string& firstName() const;
const bsl::string& lastName() const;
int age() const;
template <class STREAM>
STREAM& bdexStreamOut(STREAM& stream, int version) const;
};
bool operator==(const MyPerson& lhs, const MyPerson& rhs);
bool operator!=(const MyPerson& lhs, const MyPerson& rhs);
bsl::ostream& operator<<(bsl::ostream& stream, const MyPerson& person);
inline
int MyPerson::maxSupportedBdexVersion(int ) {
return 1;
}
inline
MyPerson::MyPerson()
: d_firstName("")
, d_lastName("")
, d_age(0)
{
}
inline
MyPerson::MyPerson(const char *firstName, const char *lastName, int age)
: d_firstName(firstName)
, d_lastName(lastName)
, d_age(age)
{
}
inline
MyPerson::~MyPerson()
{
}
template <class STREAM>
STREAM& MyPerson::bdexStreamIn(STREAM& stream, int version)
{
if (stream) {
switch (version) {
case 1: {
stream.getString(d_firstName);
if (!stream) {
d_firstName = "stream error";
return stream;
}
stream.getString(d_lastName);
if (!stream) {
d_lastName = "stream error";
return stream;
}
stream.getInt32(d_age);
if (!stream) {
d_age = 999;
return stream;
}
} break;
default: {
stream.invalidate();
}
}
}
return stream;
}
template <class STREAM>
STREAM& MyPerson::bdexStreamOut(STREAM& stream, int version) const
{
switch (version) {
case 1: {
stream.putString(d_firstName);
stream.putString(d_lastName);
stream.putInt32(d_age);
} break;
default: {
stream.invalidate();
} break;
}
return stream;
}
MyPerson value-semantic class by externalizing and reconstituting an object. First, create a MyPerson janeSmith and a bslx::TestOutStream outStream: MyPerson janeSmith("Jane", "Smith", 42);
bslx::TestOutStream outStream(20131127);
const int VERSION = 1;
outStream.putVersion(VERSION);
janeSmith.bdexStreamOut(outStream, VERSION);
assert(outStream.isValid());
MyPerson janeCopy initialized to the default value, and assert that janeCopy is different from janeSmith: MyPerson janeCopy;
assert(janeCopy != janeSmith);
bslx::TestInStream inStream initialized with the buffer from the bslx::TestOutStream object outStream and unexternalize this data into janeCopy: bslx::TestInStream inStream(outStream.data(), outStream.length());
int version;
inStream.getVersion(version);
janeCopy.bdexStreamIn(inStream, version);
assert(inStream.isValid());
assert the obtained values are as expected and display the results to bsl::stdout: assert(version == VERSION);
assert(janeCopy == janeSmith);
if (janeCopy == janeSmith) {
bsl::cout << "Successfully serialized and de-serialized Jane Smith:"
<< "\n\tFirstName: " << janeCopy.firstName()
<< "\n\tLastName : " << janeCopy.lastName()
<< "\n\tAge : " << janeCopy.age() << bsl::endl;
}
else {
bsl::cout << "Serialization unsuccessful. 'janeCopy' holds:"
<< "\n\tFirstName: " << janeCopy.firstName()
<< "\n\tLastName : " << janeCopy.lastName()
<< "\n\tAge : " << janeCopy.age() << bsl::endl;
}
Define Documentation
| #define BSLX_TESTINSTREAM_EXCEPTION_TEST_BEGIN |
( |
|
testInStream |
) |
|
Value:{ \
static int firstTime = 1; \
if (verbose && firstTime) { \
bsl::cout << "### BSLX EXCEPTION TEST -- (NOT ENABLED) --" << '\n'; \
firstTime = 0; \
} \
}
| #define BSLX_TESTINSTREAM_EXCEPTION_TEST_END |
