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

This class provides a mechanism for describing a metric. A `MetricDescription` holds the category to which the metric belongs, and a null‐terminated string containing the name of the metric.

== Synopsis

Declared in `<balm_metricdescription.h>`

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

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/balm/MetricDescription/UserDataKey.adoc[`UserDataKey`] 
| A key used to refer to a data value associated with a metric. Note that a `UserDataKey` can be used by clients of `balm` to associate additional information with a metric. See `balm_metricregistry` for information on obtaining a unique key.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/balm/MetricDescription/2constructor.adoc[`MetricDescription`]         [.small]#[constructor]#
| Create a metric description for the specified `category` and the specified `name`. Optionally specify a `basicAllocator` used to supply memory. If `basicAllocator` is 0, the currently installed default allocator is used. The initial value for `preferredPublicationType` is `e_UNSPECIFIED`, and the initial value for `format` is 0. The behavior is undefined unless `name` and `category` remain valid, and the contents of `name` remain unmodified, for the lifetime of this object.
| xref:BloombergLP/balm/MetricDescription/category.adoc[`category`] 
| Return the address of the non‐modifiable category object indicating the category of the metric described by this object.
| xref:BloombergLP/balm/MetricDescription/format.adoc[`format`] 
| Return a shared pointer to the non‐modifiable format for this metric description. Note that the returned shared pointer _may_ _be_ _null_ if a format has not been provided for the described metric.
| xref:BloombergLP/balm/MetricDescription/name.adoc[`name`] 
| Return the address of the non‐modifiable, null‐terminated string containing the name of the described metric.
| xref:BloombergLP/balm/MetricDescription/preferredPublicationType.adoc[`preferredPublicationType`] 
| Return the preferred publication type of this metric. The preferred publication type of this metric indicates the preferred aggregate to publish for this metric, or `PublicationType::UNSPECIFIED` if there is no preference. Note that there is no uniform definition for how publishers will interpret this value; an `UNSPECIFIED` value generally indicates that the all the collected aggregates (total, count, minimum, and maximum value) should be published.
| xref:BloombergLP/balm/MetricDescription/print.adoc[`print`] 
| Print the category and name of this metric description to the specified output `stream` in some single‐line human‐readable form, and return a reference to the modifiable `stream`.
| xref:BloombergLP/balm/MetricDescription/printDescription.adoc[`printDescription`] 
| Print the properties of this metric description to the specified output `stream` in some single‐line human‐readable form, and return a reference to the modifiable `stream`.
| xref:BloombergLP/balm/MetricDescription/setCategory.adoc[`setCategory`] 
| Set the category of this metric description to the object at the specified `category` address. The behavior is undefined unless `category` remains valid for the lifetime of this object.
| xref:BloombergLP/balm/MetricDescription/setFormat.adoc[`setFormat`] 
| Set the format for this metric description to the specified `format`.
| xref:BloombergLP/balm/MetricDescription/setName.adoc[`setName`] 
| Set the name of this metric description to the specified `name`. The behavior is undefined unless the contents of `name` remains valid and unmodified for the lifetime of this object.
| xref:BloombergLP/balm/MetricDescription/setPreferredPublicationType.adoc[`setPreferredPublicationType`] 
| Set the preferred publication type of this metric to the specified `type`. The preferred publication type of this metric indicates the preferred aggregate to publish for this metric, or `PublicationType::UNSPECIFIED` if there is no preference. Note that there is no uniform definition for how publishers will interpret this value; an `UNSPECIFIED` value generally indicates that all the collected aggregates (total, count, minimum, and maximum value) should be published.
| xref:BloombergLP/balm/MetricDescription/setUserData.adoc[`setUserData`] 
| Associate the specified `value` with the specified data `key`. The behavior is undefined unless `key >= 0`. Note that this method allows clients of `balm` to associate (opaque) application‐specific information with a metric.
| xref:BloombergLP/balm/MetricDescription/userData.adoc[`userData`] 
| Return the non‐modifiable value associated with the specified user‐data `key`. If the data for `key` has not been set, a value of 0 is returned, which is indistinguishable from a valid `key` with a 0 value. The behavior is undefined unless `key >= 0`. Note that this method allows clients of `balm` to access the (opaque) application‐specific information that they have previously associated with a metric (via `setUserData`).
|===



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