[#BloombergLP-bsltf-StdStatefulAllocator]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bsltf.adoc[bsltf]::StdStatefulAllocator
:relfileprefix: ../../
:mrdocs:

This allocator implements the minimal interface to comply with section 17.6.3.5 ([allocator.requirements]) of the C++11 standard, while maintaining a distinct object state ‐ in this case a wrapped pointer to a `bslma::Allocator`. The template is configurable to control its allocator propagation properties, but does not support the BDE "scoped" allocator model, as scoped allocators should never propagate. Instances of this allocator delegate their operations to the wrapped allocator that constitutes its state. Note that while we define the various traits used by the C++11 allocator traits facility, they actually mean very little for this component, as it is the consumer of the allocator's responsibility to check and apply the traits correctly, typically by using `bsl::allocator_traits` to perform all memory allocation tasks rather than using the allocator directly. The `PROPAGATE_ON_CONTAINER_COPY_CONSTRUCTION` flag is consumed directly though, in the static member function `select_on_container_copy_construction`.

== Synopsis

Declared in `<bsltf_stdstatefulallocator.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template<
    class TYPE,
    bool PROPAGATE_ON_CONTAINER_COPY_CONSTRUCTION = true,
    bool PROPAGATE_ON_CONTAINER_COPY_ASSIGNMENT = true,
    bool PROPAGATE_ON_CONTAINER_SWAP = true,
    bool PROPAGATE_ON_CONTAINER_MOVE_ASSIGNMENT = true,
    bool IS_ALWAYS_EQUAL = false>
class StdStatefulAllocator;
----

== Types

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bsltf/StdStatefulAllocator/rebind.adoc[`rebind`] 
| This nested `struct` template, parameterized by some `BDE_OTHER_TYPE`, provides a namespace for an `other` type alias, which is an allocator type following the same template as this one but that allocates elements of `BDE_OTHER_TYPE`. Note that this allocator type is convertible to and from `other` for any `BDE_OTHER_TYPE` including `void`.
|===


== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bsltf/StdStatefulAllocator/const_pointer.adoc[`const_pointer`] 
| Alias for a pointer to `const TYPE`.
| xref:BloombergLP/bsltf/StdStatefulAllocator/difference_type.adoc[`difference_type`] 
| Alias for `std::ptrdiff_t`.
| xref:BloombergLP/bsltf/StdStatefulAllocator/is_always_equal.adoc[`is_always_equal`] 
| Alias for an `allocator_traits` equality trait reflecting the `IS_ALWAYS_EQUAL` template parameter.
| xref:BloombergLP/bsltf/StdStatefulAllocator/pointer.adoc[`pointer`] 
| Alias for a pointer to `TYPE`.
| xref:BloombergLP/bsltf/StdStatefulAllocator/propagate_on_container_copy_assignment.adoc[`propagate_on_container_copy_assignment`] 
| Alias for an `allocator_traits` propagation trait reflecting the `PROPAGATE_ON_CONTAINER_COPY_ASSIGNMENT` template parameter.
| xref:BloombergLP/bsltf/StdStatefulAllocator/propagate_on_container_move_assignment.adoc[`propagate_on_container_move_assignment`] 
| Alias for an `allocator_traits` propagation trait reflecting the `PROPAGATE_ON_CONTAINER_MOVE_ASSIGNMENT` template parameter.
| xref:BloombergLP/bsltf/StdStatefulAllocator/propagate_on_container_swap.adoc[`propagate_on_container_swap`] 
| Alias for an `allocator_traits` propagation trait reflecting the `PROPAGATE_ON_CONTAINER_SWAP` template parameter.
| xref:BloombergLP/bsltf/StdStatefulAllocator/size_type.adoc[`size_type`] 
| Alias for `std::size_t`.
| xref:BloombergLP/bsltf/StdStatefulAllocator/value_type.adoc[`value_type`] 
| Alias for the allocated `TYPE`.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bsltf/StdStatefulAllocator/2constructor-00.adoc[`StdStatefulAllocator`]         [.small]#[constructor]#
| Constructors
| xref:BloombergLP/bsltf/StdStatefulAllocator/allocate.adoc[`allocate`] 
| Allocate enough (properly aligned) space for the specified `numElements` of the (template parameter) type `TYPE`. If the underlying `bslma::Allocator` is unable to fulfill the allocation request, an exception (typically `bsl::bad_alloc`) will be thrown.
| xref:BloombergLP/bsltf/StdStatefulAllocator/allocator.adoc[`allocator`] 
| Return the address of the allocator wrapped by this object.
| xref:BloombergLP/bsltf/StdStatefulAllocator/construct.adoc[`construct`] 
| Construct an object of the (template parameter) `ELEMENT_TYPE`, by forwarding the specified (variable number of) `arguments` to the corresponding constructor of `ELEMENT_TYPE`, at the specified uninitialized memory `address`. The behavior is undefined unless `address` is properly aligned for objects of `ELEMENT_TYPE`.
| xref:BloombergLP/bsltf/StdStatefulAllocator/deallocate.adoc[`deallocate`] 
| Return memory previously allocated at the specified `address` for `numElements` back to this allocator. The `numElements` argument is ignored by this allocator type. The behavior is undefined unless `address` was allocated using this allocator object and has not already been deallocated.
| xref:BloombergLP/bsltf/StdStatefulAllocator/destroy.adoc[`destroy`] 
| Invoke the `ELEMENT_TYPE` destructor for the object at the specified `address`.
| xref:BloombergLP/bsltf/StdStatefulAllocator/max_size.adoc[`max_size`] 
| Return the maximum number of elements of type `TYPE` that can be allocated using this allocator in a single call to the `allocate` method. Note that there is no guarantee that attempts at allocating less elements than the value returned by `max_size` will not throw. *** DO NOT RELY ON THE CONTINUING PRESENT OF THIS METHOD *** THIS METHOD WILL BE REMOVED ONCE `bslstl::allocator_traits` PROPERLY DEDUCES AN IMPLEMENTATION FOR THIS FUNCTION WHEN NOT SUPPLIED BY THE ALLOCATOR DIRECTLY.
| xref:BloombergLP/bsltf/StdStatefulAllocator/select_on_container_copy_construction.adoc[`select_on_container_copy_construction`] 
| Return a copy of this object if the `bool` template parameter `PROPAGATE_ON_CONTAINER_COPY_CONSTRUCTION` is true, and a copy of a `StdStatefulAllocator` object wrapping the default allocator otherwise.
| xref:BloombergLP/bsltf/StdStatefulAllocator/2conversion.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<StdStatefulAllocator, IsStdAllocator>`] 
| Declare `StdStatefulAllocator` as a standard allocator.
|===


== Non-Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bsltf/operator_not_eq-0c.adoc[`operator!=`]
| Return `true` if the specified `lhs` and `rhs` have different underlying test allocators, and `false` otherwise.
| xref:BloombergLP/bsltf/operator_eq-04d.adoc[`operator==`]
| Return `true` if the specified `lhs` and `rhs` have the same underlying test allocator, and `false` otherwise.
|===


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