- Generated by
1.9.8
|
BDE 4.14.0 Production release
|
Facilitate uniform externalization of user and fundamental types.
This component provides a namespace, bslx::OutStreamFunctions, that facilitates uniform support for BDEX externalization across all BDEX-compliant user-defined types, including template types and containers, as well as those fundamental types (and bsl::string and bsl::vector) for which the BDEX protocol provides direct support.
The namespace bslx::OutStreamFunctions facilitates client externalization of objects in a uniform, type-independent manner. It contains the bdexStreamOut function that externalizes objects of all BDEX-compliant types. This function externalizes the specified object in the specified version. The bdexStreamOut function is overloaded for fundamental types, enumeration types, bsl::string, and bsl::vector. Note that, excluding bsl::vector, version information is never written to the stream while externalizing these types.
By default, objects of enumeration type are streamed out as 32-bit int values. Users can override this behavior by providing overloads of the OutStreamFunctions::bdexStreamOut function in the enumeration's namespace for their enumeration types. The general form of this overload is:
For value-semantic types that support the BDEX protocol, the free function bdexStreamOut calls the bdexStreamOut member function for that type.
bslx_outstreamfunctions is an integral part of the BDEX externalization contract. The BDEX contract is at least in part "collaborative", which is to say that each developer of a given kind of component (e.g., a stream or a value-semantic container) must comply with the relevant portions of the contract to ensure that the "system as a whole" works for everybody. bslx_outstreamfunctions plays several related but different roles in helping various developers to produce BDEX-compliant components. In this section we briefly highlight how and why bslx_outstreamfunctions is helpful (or required) for these different developers. By discussing different aspects of usage, we convey the general design goals of this component, and, to a certain extent, the overall BDEX contract. See the bslx package-level documentation for a full specification of the BDEX contract.
The author of a non-template value-semantic type has full knowledge of the details of the "value" of that type, and may choose to use the appropriate output stream put methods directly when implementing the required bdexStreamOut method for that type. However, if one or more aspects of the value are of template parameter type, then the author cannot in general know how to stream the value using the put methods. For example, if a type has as its value one int data member:
then the implementation of the bdexStreamOut method can contain:
However, if the data member is of (template parameter) TYPE:
then the implementation of the bdexStreamOut method must rely on the bslx::OutStreamFunctions implementation to output the value:
This call will resolve to the correct sequence of put calls no matter whether TYPE is a fundamental type, a BDEX-compliant enum, or a proper BDEX-compliant class. In the latter two cases, the explicit specification of the version format (in this case, 1) guarantees the stable operation of this method whether or not TYPE is provided additional version formats.
This section illustrates intended use of this component.
In this example we illustrate the primary intended use of the parameterized methods of this component, as well as a few trivial invocations just to show the syntax clearly. To accomplish this, we exhibit two separate example "components": a value-semantic point object, and an enum. In all cases, the component designs are very simple, with much of the implied functionality omitted, in order to focus attention on the key aspects of the functionality of this component.
First, consider an enum Color that enumerates a set of colors:
Next, we consider a very special-purpose point that has as a data member its color. Such a point provides an excellent opportunity for factoring, but since we are interested in highlighting BDEX streaming of various types, we will present a simple and unfactored design here. In a real-world problem, the mypoint component would be implemented differently.
Note that the MyPoint class in this example represents its coordinates as short integer values; this is done to make the BDEX stream output byte pattern somewhat easier for the reader of this example to recognize when the output buffer is printed.
Representative (inline) implementations of these methods are shown below:
Then, we will implement an extremely simple output stream that supports the BDEX documentation-only protocol. For simplicity, we will use a fixed-size buffer (usually a bad idea in any event, and more so here since the implementation knows the buffer size, but makes no effort to prevent overwriting that buffer), and will only show a few methods needed for this example. See other bslx stream components for examples of properly-designed BDEX streams.
The relevant (inline) implementations are as follows.
Finally, use the above enum, point class, and output stream to illustrate bslx::OutStreamFunctions functionality. This test code does not attempt to do anything more useful than writing known values to a stream and confirming that the expected byte pattern was in fact written.
1.9.8