[#BloombergLP-ball-StreamObserver]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/ball.adoc[ball]::StreamObserver
:relfileprefix: ../../
:mrdocs:

This class provides a concrete implementation of the `Observer` protocol. The `publish` method of this class outputs the log records that it receives to an instance of `bsl::ostream` supplied at construction.

== Synopsis

Declared in `<ball_streamobserver.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class StreamObserver
    : public xref:BloombergLP/ball/Observer.adoc[Observer]
----

== Base Classes

[cols="1,4"]
|===
| Name| Description
| `xref:BloombergLP/ball/Observer.adoc[Observer]`
| This class provides a protocol for receiving and processing log record output.
|===

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/ball/StreamObserver/RecordFormatFunctor.adoc[`RecordFormatFunctor`] 
| Alias for the record formatting functor type.
| xref:BloombergLP/ball/StreamObserver/RecordFormatter.adoc[`RecordFormatter`] 
| `LogRecordFunctor` is an alias for the type of the functor used for formatting log records to a stream.
| xref:BloombergLP/ball/StreamObserver/allocator_type.adoc[`allocator_type`] 
| This `typedef` is an alias for the allocator used by this object.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/ball/StreamObserver/2constructor.adoc[`StreamObserver`]         [.small]#[constructor]#
| Create a stream observer that transmits log records to the specified `stream`. Optionally specify an `allocator` (e.g., the address of a `bslma::Allocator` object) to supply memory; otherwise, the default allocator is used. Note that a default record format is in effect for stream logging (see `logRecordDefault`).
| xref:BloombergLP/ball/StreamObserver/2destructor.adoc[`~StreamObserver`] [.small]#[destructor]# [.small]#[virtual]#
| Destroy this stream observer.
| xref:BloombergLP/ball/StreamObserver/disablePublishInLocalTime.adoc[`disablePublishInLocalTime`] 
| Disable publishing of the timestamp attribute of records in local time by this stream observer; henceforth, timestamps will be in UTC time. This method has no effect if publishing in local time is not enabled.
| xref:BloombergLP/ball/StreamObserver/enablePublishInLocalTime.adoc[`enablePublishInLocalTime`] 
| Enable publishing of the timestamp attribute of records in local time by this stream observer. By default, timestamps are published in UTC time. Note that this method also affects timestamps for formatters that use them.
| xref:BloombergLP/ball/StreamObserver/getFormat.adoc[`getFormat`] 
| Return the format config of the last successful `setFormat` call.
| xref:BloombergLP/ball/StreamObserver/isPublishInLocalTimeEnabled.adoc[`isPublishInLocalTimeEnabled`] 
| Return `true` if this observer writes the timestamp attribute of records that it publishes in local time by default, and `false` otherwise (in which case timestamps are written by default in UTC time).
| xref:BloombergLP/ball/StreamObserver/publish-03.adoc[`publish`] 
| `publish` overloads
| xref:BloombergLP/ball/StreamObserver/releaseRecords.adoc[`releaseRecords`]  [.small]#[virtual]#
| Discard any shared reference to a `Record` object that was supplied to the `publish` method, and is held by this observer. Note that this operation should be called if resources underlying the previously provided shared‐pointers must be released. This method intentionally does nothing as such resources are held, we publish all records immediately.
| xref:BloombergLP/ball/StreamObserver/setFormat.adoc[`setFormat`] 
| Set the formatting functor used when writing records to the stream of this stream observer to a log file functor created according to the specified, possibly URI‐like scheme tagged, `format`. Return zero if the setup with the specified arguments was successful and also save the `format` to be later retrievable using `getFormat`. Otherwise (if no matching scheme could be found or the configuration is invalid) return a non‐zero value and do not change the log record formatter used by this object. Note that a default format ("n%d %p %t %s %f %l %c %m %un") is in effect until this method or `setRecordFormatFunctor` is called. Also, notice that the observer emits newline characters at the beginning and at the end of a log record by (the) default (format), so the user needs to add them explicitly to (text) format strings to preserve that behavior.
| xref:BloombergLP/ball/StreamObserver/setRecordFormatFunctor.adoc[`setRecordFormatFunctor`] 
| Set the formatting functor used when writing records to the stream of this stream observer to the specified `formatter` functor. Note that a default format ("n%d %p %t %s %f %l %c %m %un") is in effect until this method or `setFormat` is called (see `ball_recordstringformatter`). Also note that the observer emits newline characters at the beginning and at the end of a log record by default, so the user needs to add them explicitly to the format string to preserve this behavior. Note that this method is not able to communicate the timezone default settings to the `formatter`, prefer `setFormat`.
|===


== Using Declarations

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/ball/StreamObserver/publish-0dd.adoc[`publish`] 
| Import the base‐class `publish` overloads.
|===



[.small]#Created with https://www.mrdocs.com[MrDocs]#