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

This class provides a container to hold the name and threshold levels of a category. Instances of `Category` are created and manipulated by `CategoryManager`. All threshold levels are integral values in the range `[0 .. 255]`.

== Synopsis

Declared in `<ball_category.h>`

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

== Description

Implementation Note: The `d_ruleThreshold` and `d_relevantRuleMask` serve as a cache for logging rule evaluation (see `ball_attributecontext`). They are not meant to be modified by users of the logging system, and may be modified by `const` operations of the logging system.

== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/ball/Category/2constructor.adoc[`Category`]         [.small]#[constructor]#
| Create a category having the specified `categoryName` and the specified `recordLevel`, `passLevel`, `triggerLevel`, and `triggerAllLevel` threshold values, respectively. Optionally specify a `basicAllocator` used to supply memory. If `basicAllocator` is 0, the currently installed default allocator is used. The behavior is undefined unless each of the specified threshold levels is in the range `[0 .. 255]`.
| xref:BloombergLP/ball/Category/categoryName.adoc[`categoryName`] 
| Return the name of this category.
| xref:BloombergLP/ball/Category/isEnabled.adoc[`isEnabled`] 
| Return `true` if logging at the specified `level` is enabled for this category, and `false` otherwise. Logging is enabled if `level` is numerically less than or equal to any of the four threshold levels of this category.
| xref:BloombergLP/ball/Category/maxLevel.adoc[`maxLevel`] 
| Return the numerical maximum of the four levels of this category.
| xref:BloombergLP/ball/Category/passLevel.adoc[`passLevel`] 
| Return the pass level of this category.
| xref:BloombergLP/ball/Category/recordLevel.adoc[`recordLevel`] 
| Return the record level of this category.
| xref:BloombergLP/ball/Category/relevantRuleMask.adoc[`relevantRuleMask`] 
| Return a reference to the non‐modifiable relevant rule mask for this category. The returned `RuleSet::MaskType` value is a bit‐mask, where each bit is a boolean value indicating whether the rule at the corresponding index (in the rule set of the category manager that owns this category) applies at this category. Note that a rule applies to this category if the rule's pattern matches the name returned by `categoryName`.
| xref:BloombergLP/ball/Category/ruleThreshold.adoc[`ruleThreshold`] 
| Return the current maximum threshold (i.e., the lowest severity) for any logging rule associated with this category. Note that the rule having this threshold may not be active given the current thread's logging context (see `ball::AttributeContext`); this value caches the lowest possible severity where the currently rules need to be evaluated (log records below this threshold do not need any rule evaluation).
| xref:BloombergLP/ball/Category/setLevels.adoc[`setLevels`] 
| Set the threshold levels of this category to the specified `recordLevel`, `passLevel`, `triggerLevel`, and `triggerAllLevel` values, respectively, if each of the specified values is in the range `[0 .. 255]`. Return 0 on success, and a non‐zero value otherwise (with no effect on the threshold levels of this category).
| xref:BloombergLP/ball/Category/threshold.adoc[`threshold`] 
| Return the current maximum threshold (i.e., the lowest severity) between the `recordLevel`, `passLevel`, `triggerLevel`, and `triggerAllLevel`. Note that this is the threshold at which a log record having this severity will need to be acted upon.
| xref:BloombergLP/ball/Category/thresholdLevels.adoc[`thresholdLevels`] 
| Return the aggregate threshold levels of this category.
| xref:BloombergLP/ball/Category/triggerAllLevel.adoc[`triggerAllLevel`] 
| Return the trigger‐all level of this category.
| xref:BloombergLP/ball/Category/triggerLevel.adoc[`triggerLevel`] 
| Return the trigger level of this category.
| xref:BloombergLP/ball/Category/2conversion.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<Category, UsesBslmaAllocator>`] 
| Declare that this type uses a `bslma` allocator.
|===


== Static Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/ball/Category/areValidThresholdLevels.adoc[`areValidThresholdLevels`] 
| Return `true` if each of the specified `recordLevel`, `passLevel`, `triggerLevel` and `triggerAllLevel` threshold values are in the range `[0 .. 255]`, and `false` otherwise.
|===


== Friends

[cols="1,4"]
|===
| Name| Description
| `xref:BloombergLP/ball/CategoryManagerImpUtil.adoc[BloombergLP::ball::CategoryManagerImpUtil]`
| This class provides a suite of free functions used to help implement a manager of categories and category holders.
|===


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