[#BloombergLP-balm-MetricSample]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/balm.adoc[balm]::MetricSample
:relfileprefix: ../../
:mrdocs:

This class provides an _in‐core_ value‐semantic representation of a sample of metric values. The class contains a collection of addresses to (external) `MetricRecord` objects holding the values for their respective metrics (aggregated over some period of time). The metric records contained by a sample are broken into a series of groups, which are represented by `MetricSampleGroup` objects. Each group contains a sequence of records and an elapsed time value, indicating the period of time over which those records were taken. This class also provides a timestamp value, used to indicate when the sample was collected. The class provides a method, `appendGroups`, that appends a group of metric records to the sample. Arrays supplied using `appendGroups` must be valid for the productive lifetime of the `MetricSample` object or until they are removed by calling `removeAllRecords`.

== Synopsis

Declared in `<balm_metricsample.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class MetricSample;
----

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/balm/MetricSample/const_iterator.adoc[`const_iterator`] 
| A `const_iterator` is an alias for an iterator over the non‐modifiable sample groups contained in a `MetricSample`.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/balm/MetricSample/2constructor-0f.adoc[`MetricSample`]         [.small]#[constructor]#
| Constructors
| xref:BloombergLP/balm/MetricSample/2destructor.adoc[`~MetricSample`] [.small]#[destructor]#
| Destroy this metric sample.
| xref:BloombergLP/balm/MetricSample/operator_assign.adoc[`operator=`] 
| Assign to this sample the value of the specified `rhs` sample and return a reference to this modifiable sample. Note that copying the `MetricSampleGroup` objects contained in `rhs` copies only the pointers to their respective `MetricRecord` arrays, and does not copy records themselves; hence, these record arrays must remain valid for the productive lifetimes of all copied objects or until records are removed by calling `removeAllRecords`.
| xref:BloombergLP/balm/MetricSample/appendGroup-0c.adoc[`appendGroup`] 
| `appendGroup` overloads
| xref:BloombergLP/balm/MetricSample/begin.adoc[`begin`] 
| Return an iterator positioned at the beginning of the sequence of `MetricSampleGroup` objects contained by this object. Note that the iterator will remain valid until this sample is modified by invoking either `appendGroups` or `removeAllRecords()`.
| xref:BloombergLP/balm/MetricSample/end.adoc[`end`] 
| Return an iterator positioned one one past the final `MetricSampleGroup` object in the sequence of sample groups contained by this object. Note that the iterator will remain valid until this sample is modified by invoking `appendGroup` or `removeAllRecords()`.
| xref:BloombergLP/balm/MetricSample/numGroups.adoc[`numGroups`] 
| Return the number of record groups (i.e., `MetricSampleGroup` objects) that are contained in this object.
| xref:BloombergLP/balm/MetricSample/numRecords.adoc[`numRecords`] 
| Return the total number of records in this sample (i.e., the sum of the lengths of all the appended record groups).
| xref:BloombergLP/balm/MetricSample/print.adoc[`print`] 
| Format this object to the specified output `stream` at the (absolute value of) the optionally specified indentation `level` and return a reference to `stream`. If `level` is specified, optionally specify `spacesPerLevel`, the number of spaces per indentation level for this and all of its nested objects. If `level` is negative, suppress indentation of the first line. If `spacesPerLevel` is negative, format the entire output on one line, suppressing all but the initial indentation (as governed by `level`). If `stream` is not valid on entry, this operation has no effect.
| xref:BloombergLP/balm/MetricSample/removeAllRecords.adoc[`removeAllRecords`] 
| Remove all metric records from this sample.
| xref:BloombergLP/balm/MetricSample/sampleGroup.adoc[`sampleGroup`] 
| Return a reference to the non‐modifiable `MetricSampleGroup` object at the specified `index` in this sample. The behavior is undefined unless `0 <= index < numGroups()`. Note that the returned reference will remain valid until this sample is modified by invoking `appendGroup` or `removeAllRecords()`.
| xref:BloombergLP/balm/MetricSample/setTimeStamp.adoc[`setTimeStamp`] 
| Set the timestamp (used to indicate when the sample was taken) to the specified `timeStamp`.
| xref:BloombergLP/balm/MetricSample/timeStamp.adoc[`timeStamp`] 
| Return a reference to the non‐modifiable timestamp for this sample.
| xref:BloombergLP/balm/MetricSample/2conversion.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<MetricSample, UsesBslmaAllocator>`] 
| Declare that this type uses a `bslma` allocator.
|===


== Friends

[cols="1,4"]
|===
| Name| Description
| `xref:BloombergLP/balm/operator_eq-0d.adoc[BloombergLP::balm::operator==]`
| Return `true` if the specified `lhs` and `rhs` samples have the same value, and `false` otherwise. Two samples have the same value if they have the same timestamp value, contain the same number of record groups, and if the respective groups of records at each index position have the same value.
|===

== Non-Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/balm/operator_not_eq-0d.adoc[`operator!=`]
| Return `true` if the specified `lhs` and `rhs` samples do not have the same value, and `false` otherwise. Two samples do not have the same value if they have different values for their timestamps, or number of record groups, or if any of the groups of records at corresponding indices have different values.
|===


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