xtd::collections::generic::queue< type_t, allocator_t > Class Template Reference

Inheritance diagram for xtd::collections::generic::queue< type_t, allocator_t >:

Definition

template<class type_t, class allocator_t = xtd::collections::generic::helpers::allocator<type_t>>
class xtd::collections::generic::queue< type_t, allocator_t >

Represents a first-in, first-out collection of objects.

Definition

template<class type_t, class allocator_t = xtd::collections::generic::helpers::allocator<type_t>>
class queue : public xtd::object, public xtd::collections::generic::icollection<type_t>;

Header

#include <xtd/collections/generic/queue>

Namespace

xtd::collections::generic

Library

xtd.core

Remarks

This class implements a generic queue as a circular array. Objects stored in a xtd::collections::generic::queue <type_t> are inserted at one end and removed from the other. Queues and stacks are useful when you need temporary storage for information; that is, when you might want to discard an element after retrieving its value. Use xtd::collections::generic::queue <type_t> if you need to access the information in the same order that it is stored in the collection. Use xtd::collections::generic::stack <type_t> if you need to access the information in reverse order. Use xtd::collections::generic::concurrent_queue <type_t> or xtd::collections::generic::concurrent_stack <type_t> if you need to access the collection from multiple threads concurrently.

Three main operations can be performed on a xtd::collections::generic::queue <type_t> and its elements:

• xtd::collections::generic::queue::enqueue adds an element to the end of the xtd::collections::generic::queue <type_t>.
• xtd::collections::generic::queue::dequeue removes the oldest element from the start of the xtd::collections::generic::queue <type_t>.
• xtd::collections::generic::queue::peek peek returns the oldest element that is at the start of the xtd::collections::generic::queue <type_t> but does not remove it from the xtd::collections::generic::queue <type_t>.

The capacity of a xtd::collections::generic::queue <type_t> is the number of elements the xtd::collections::generic::queue <type_t> can hold. As elements are added to a xtd::collections::generic::queue <type_t>, the capacity is automatically increased as required by reallocating the internal array. The capacity can be decreased by calling xtd::collections::generic::queue::trim_excess.

xtd::collections::generic::queue <type_t> allows duplicate elements.

Examples

The following code example demonstrates several methods of the xtd::collections::generic::queue <type_t> generic class. The code example creates a queue of strings with default capacity and uses the xtd::collections::generic::queue::enqueue method to queue five strings. The elements of the queue are enumerated, which does not change the state of the queue. The xtd::collections::generic::queue::dequeue method is used to dequeue the first string. The xtd::collections::generic::queue::peek method is used to look at the next item in the queue, and then the xtd::collections::generic::queue::dequeue method is used to dequeue it. The xtd::collections::generic::queue::to_array method is used to create an array and copy the queue elements to it, then the array is passed to the xtd::collections::generic::queue <type_t> constructor that takes xtd::collections::generic::ienumerable <type_t>, creating a copy of the queue. The elements of the copy are displayed. An array twice the size of the queue is created, and the xtd::collections::generic::queue::copy_to method is used to copy the array elements beginning at the middle of the array. The xtd::collections::generic::queue <type_t> constructor is used again to create a second copy of the queue containing three null elements at the beginning. The xtd::collections::generic::queue::contains method is used to show that the string "four" is in the first copy of the queue, after which the Clear method clears the copy and the xtd::collections::generic::queue::count property shows that the queue is empty.

#include <xtd/xtd>
 
namespace examples {
  class program {
  public:
    static void main() {
      auto numbers = queue<string> {};
      numbers.enqueue("one");
      numbers.enqueue("two");
      numbers.enqueue("three");
      numbers.enqueue("four");
      numbers.enqueue("five");
      
      // A queue can be enumerated without disturbing its contents.
      for (auto number : numbers )
        console::write_line(number);
      
      console::write_line("\nDequeuing '{0}'", numbers.dequeue());
      console::write_line("Peek at next item to dequeue: {0}", numbers.peek());
      console::write_line("Dequeuing '{0}'", numbers.dequeue());
      
      // Create a copy of the queue, using the to_array method and the constructor that accepts an ienumerable<type_t>.
      auto queue_copy = queue<string>(numbers.to_array());
      
      console::write_line("\nContents of the first copy:");
      for(auto number : queue_copy )
        console::write_line(number);
      
      // Create an array twice the size of the queue and copy the elements of the queue, starting at the middle of the array.
      auto array2 = array<string>(numbers.count() * 2);
      numbers.copy_to(array2, numbers.count());
      
      // Create a second queue, using the constructor that accepts an ienumerable(Of type_t).
      auto queue_copy2 = queue<string>(array2);
      
      console::write_line("\nContents of the second copy, with duplicates and empty:");
      for(auto number : queue_copy2 )
        console::write_line(number);
      
      console::write_line("\nqueue_copy.contains(\"four\") = {}", queue_copy.contains("four"));
      
      console::write_line("\nqueue_copy.clear()");
      queue_copy.clear();
      console::write_line("\nqueue_copy.count() = {}", queue_copy.count());
    }
  };
}
 
startup_(examples::program::main);
 
// This code can produce the following output :
//
// one
// two
// three
// four
// five
//
// Dequeuing 'one'
// Peek at next item to dequeue: two
// Dequeuing 'two'
//
// Contents of the first copy:
// three
// four
// five
//
// Contents of the second copy, with duplicates and empty:
//
//
//
// three
// four
// five
// 
// queue_copy.contains("four") = true
//
// queue_copy.clear()
//
// queue_copy.count() = 0

Public Aliases
using	value_type
	Represents the list value type.
using	base_type
	Represents the list base type.
using	size_type
	Represents the list size type (usually xtd::size).
using	reference
	Represents the reference of list value type.
using	const_reference
	Represents the const reference of list value type.

Public Constructors
	queue ()=default
	Initializes a new instance of the xtd::collections::generic::queue <type_t> class that is empty and has the default initial capacity.
	queue (queue &&queue)=default
	Move constructor with specified queue.
	queue (const queue &queue)=default
	Default copy constructor with specified queue.
	queue (std::queue< type_t > &&queue)
	Move constructor with specified queue.
	queue (const std::queue< type_t > &queue)
	Default copy constructor with specified queue.
	queue (const ienumerable< value_type > &collection)
	Initializes a new instance of the xtd::collections::generic::queue <type_t> class that contains elements copied from the specified collection and has sufficient capacity to accommodate the number of elements copied.
	queue (size_type capacity)
	Initializes a new instance of the xtd::collections::generic::queue <type_t> class that is empty and has the specified initial capacity.
	queue (std::initializer_list< type_t > il)
	Constructs the container with the contents of the specified initializer list, and allocator.
template<std::input_iterator input_iterator_t>
	queue (input_iterator_t first, input_iterator_t last)
	Constructs the container with the contents of the range [first, last).

Public Properties
auto	capacity () const noexcept -> size_type
	Gets the total numbers of elements the internal data structure can hold without resizing.
auto	count () const noexcept -> size_type override
	Gets the number of nodes actually contained in the xtd::collections::generic::queue <type_t>.
std::queue< type_t >	items () const
	Gets a std::queue<type_t>.

Public Methods
auto	clear () -> void override
	Removes all elements from the xtd::collections::generic::queue <type_t>.
auto	contains (const_reference value) const noexcept -> bool override
	Determines whether an element is in the xtd::collections::generic::queue <type_t>.
auto	copy_to (xtd::array< type_t > &array, size_type array_index) const -> void override
	Copies the entire xtd::colllections::generic::linked_list <type_t> to a compatible one-dimensional array, starting at the specified index of the target array.
auto	dequeue () -> value_type
	Removes and returns the object at the beginning of the xtd::collections::generic::queue <type_t>.
auto	enqueue (const_reference value) -> void
	Adds an object to the end of the xtd::collections::generic::queue <type_t>.
auto	ensure_capacity (size_type capacity) -> size_type
	Ensures that the capacity of this queue is at least the specified capacity. If the current capacity is less than capacity, it is increased to at least the specified capacity.
enumerator< value_type >	get_enumerator () const noexcept override
	Returns an enumerator that iterates through the xtd::collections::generic::queue <type_t>.
auto	peek () const -> value_type
	Returns the object at the beginning of the xtd::collections::generic::queue <type_t> without removing it.
auto	to_array () const -> xtd::array< value_type >
	Copies the xtd::collections::generic::queue <type_t> elements to a new array.
auto	to_string () const noexcept -> string override
	Returns a xtd::string that represents the current object.
auto	trim_excess () -> void
	Sets the capacity to the actual number of elements in the xtd::collections::generic::queue <type_t>, if that number is less than 90 percent of current capacity.
auto	trim_excess (size_type capacity) -> void
	Sets the capacity of a xtd::collections::generic::queue <type_t> object to the specified number of entries.
auto	try_dequeue (value_type &result) noexcept -> bool
	Removes the object at the beginning of the xtd::collections::generic::queue <type_t>, and copies it to the result parameter.
auto	try_peek (value_type &result) const noexcept -> bool
	Returns a value that indicates whether there is an object at the beginning of the xtd::collections::generic::queue <type_t>, and if one is present, copies it to the result parameter. The object is not removed from the xtd::collections::generic::queue <type_t>.

Public Operators
	operator std::queue< type_t > () const
	Gets a std::queue<type_t>.

Additional Inherited Members
	object ()=default
	Create a new instance of the ultimate base class object.
virtual bool	equals (const object &obj) const noexcept
	Determines whether the specified object is equal to the current object.
virtual xtd::size	get_hash_code () const noexcept
	Serves as a hash function for a particular type.
virtual type_object	get_type () const noexcept
	Gets the type of the current instance.
template<class object_t>
xtd::unique_ptr_object< object_t >	memberwise_clone () const
	Creates a shallow copy of the current object.
template<class object_a_t, class object_b_t>
static bool	equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
	Determines whether the specified object instances are considered equal.
template<class object_a_t, class object_b_t>
static bool	reference_equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
	Determines whether the specified object instances are the same instance.

Member Typedef Documentation

value_type

template<class type_t, class allocator_t = xtd::collections::generic::helpers::allocator<type_t>>

using xtd::collections::generic::queue< type_t, allocator_t >::value_type

Represents the list value type.

base_type

template<class type_t, class allocator_t = xtd::collections::generic::helpers::allocator<type_t>>

using xtd::collections::generic::queue< type_t, allocator_t >::base_type

Represents the list base type.

size_type

template<class type_t, class allocator_t = xtd::collections::generic::helpers::allocator<type_t>>

using xtd::collections::generic::queue< type_t, allocator_t >::size_type

Represents the list size type (usually xtd::size).

reference

template<class type_t, class allocator_t = xtd::collections::generic::helpers::allocator<type_t>>

using xtd::collections::generic::queue< type_t, allocator_t >::reference

Represents the reference of list value type.

const_reference

template<class type_t, class allocator_t = xtd::collections::generic::helpers::allocator<type_t>>

using xtd::collections::generic::queue< type_t, allocator_t >::const_reference

Represents the const reference of list value type.

Constructor & Destructor Documentation

queue() [1/9]

template<class type_t, class allocator_t = xtd::collections::generic::helpers::allocator<type_t>>

xtd::collections::generic::queue< type_t, allocator_t >::queue ( )

default

Initializes a new instance of the xtd::collections::generic::queue <type_t> class that is empty and has the default initial capacity.

queue() [2/9]

template<class type_t, class allocator_t = xtd::collections::generic::helpers::allocator<type_t>>

xtd::collections::generic::queue< type_t, allocator_t >::queue ( queue< type_t, allocator_t > && queue )

default

Move constructor with specified queue.

Parameters

queue

The xtd::collections::generic::queue <type_t> which elements will be moved from.

queue() [3/9]

template<class type_t, class allocator_t = xtd::collections::generic::helpers::allocator<type_t>>

xtd::collections::generic::queue< type_t, allocator_t >::queue ( const queue< type_t, allocator_t > & queue )

default

Default copy constructor with specified queue.

Parameters

queue

The xtd::collections::generic::queue <type_t> which elements will be inserted from.

queue() [4/9]

template<class type_t, class allocator_t = xtd::collections::generic::helpers::allocator<type_t>>

xtd::collections::generic::queue< type_t, allocator_t >::queue ( std::queue< type_t > && queue )

inline

Move constructor with specified queue.

Parameters

queue

The std::queue <type_t> which elements will be moved from.

queue() [5/9]

template<class type_t, class allocator_t = xtd::collections::generic::helpers::allocator<type_t>>

xtd::collections::generic::queue< type_t, allocator_t >::queue ( const std::queue< type_t > & queue )

inline

Default copy constructor with specified queue.

Parameters

queue

The std::queue <type_t> which elements will be inserted from.

queue() [6/9]

template<class type_t, class allocator_t = xtd::collections::generic::helpers::allocator<type_t>>

xtd::collections::generic::queue< type_t, allocator_t >::queue ( const ienumerable< value_type > & collection )

inline

Initializes a new instance of the xtd::collections::generic::queue <type_t> class that contains elements copied from the specified collection and has sufficient capacity to accommodate the number of elements copied.

Parameters

collection

The collection whose elements are copied to the new xtd::collections::generic::queue <type_t>.

queue() [7/9]

template<class type_t, class allocator_t = xtd::collections::generic::helpers::allocator<type_t>>

xtd::collections::generic::queue< type_t, allocator_t >::queue ( size_type capacity )

inline

Initializes a new instance of the xtd::collections::generic::queue <type_t> class that is empty and has the specified initial capacity.

Parameters

capacity

The initial number of elements that the xtd::collections::generic::queue <type_t> can contain.

queue() [8/9]

template<class type_t, class allocator_t = xtd::collections::generic::helpers::allocator<type_t>>

xtd::collections::generic::queue< type_t, allocator_t >::queue ( std::initializer_list< type_t > il )

inline

Constructs the container with the contents of the specified initializer list, and allocator.

Parameters

items

The initializer list to initialize the elements of the container with.

queue() [9/9]

template<class type_t, class allocator_t = xtd::collections::generic::helpers::allocator<type_t>>

template<std::input_iterator input_iterator_t>

xtd::collections::generic::queue< type_t, allocator_t >::queue ( input_iterator_t first, input_iterator_t last )

inline

Constructs the container with the contents of the range [first, last).

Parameters

first	The first iterator the range to copy the elements from.
last	The last iterator the range to copy the elements from.

Member Function Documentation

capacity()

template<class type_t, class allocator_t = xtd::collections::generic::helpers::allocator<type_t>>

auto xtd::collections::generic::queue< type_t, allocator_t >::capacity ( ) const -> size_type

inlinenoexcept

Gets the total numbers of elements the internal data structure can hold without resizing.

Returns

The total numbers of elements the internal data structure can hold without resizing.

count()

template<class type_t, class allocator_t = xtd::collections::generic::helpers::allocator<type_t>>

auto xtd::collections::generic::queue< type_t, allocator_t >::count ( ) const -> size_type

inlinenodiscardoverridenoexcept

Gets the number of nodes actually contained in the xtd::collections::generic::queue <type_t>.

Returns

The number of nodes actually contained in the xtd::collections::generic::queue <type_t>.

Remarks

Retrieving the value of this property is an O(1) operation.

items()

template<class type_t, class allocator_t = xtd::collections::generic::helpers::allocator<type_t>>

std::queue< type_t > xtd::collections::generic::queue< type_t, allocator_t >::items ( ) const

inline

Gets a std::queue<type_t>.

Returns

A std::queue<type_t>.

clear()

template<class type_t, class allocator_t = xtd::collections::generic::helpers::allocator<type_t>>

auto xtd::collections::generic::queue< type_t, allocator_t >::clear ( ) -> void

inlineoverride

Removes all elements from the xtd::collections::generic::queue <type_t>.

Remarks

Count is set to zero, and references to other objects from elements of the collection are also released.

The capacity remains unchanged. To reset the capacity of the xtd::collections::generic::queue <type_t>, call xtd::collections::generic::queue::trim_excess. Trimming an empty xtd::collections::generic::queue <type_t> sets the capacity of the xtd::collections::generic::queue <type_t> to the default capacity.

This method is an O(n) operation, where n is Count.

contains()

template<class type_t, class allocator_t = xtd::collections::generic::helpers::allocator<type_t>>

auto xtd::collections::generic::queue< type_t, allocator_t >::contains ( const_reference value ) const -> bool

inlineoverridenoexcept

Determines whether an element is in the xtd::collections::generic::queue <type_t>.

Parameters

item	The object to locate in the xtd::collections::generic::queue <type_t>.

Returns

true if item is found in the xtd::collections::generic::queue <type_t>; otherwise, false.

copy_to()

template<class type_t, class allocator_t = xtd::collections::generic::helpers::allocator<type_t>>

auto xtd::collections::generic::queue< type_t, allocator_t >::copy_to ( xtd::array< type_t > & array, size_type array_index ) const -> void

inlineoverride

Copies the entire xtd::colllections::generic::linked_list <type_t> to a compatible one-dimensional array, starting at the specified index of the target array.

Parameters

array	The one-dimensional Array that is the destination of the elements copied from xtd::colllections::generic::linked_list <type_t>. The Array must have zero-based indexing.
array_index	The zero-based index in array at which copying begins.

Exceptions

xtd::argument_out_of_range_exception

The number of elements in the source xtd::colllections::generic::linked_list <type_t> is greater than the available space from arrayIndex to the end of the destination array.

Remarks

This method uses xtd::array::copy to copy the elements.

The elements are copied to the xtd::array in the same order in which the enumerator iterates through the xtd::colllections::generic::linked_list <type_t>.

This method is an O(n) operation, where n is xtd::colllections::generic::linked_list::count.

dequeue()

template<class type_t, class allocator_t = xtd::collections::generic::helpers::allocator<type_t>>

auto xtd::collections::generic::queue< type_t, allocator_t >::dequeue ( ) -> value_type

inline

Removes and returns the object at the beginning of the xtd::collections::generic::queue <type_t>.

Returns

The object that is removed from the beginning of the xtd::collections::generic::queue <type_t>.

Exceptions

xtd::invalid_operation_exception

The xtd::collections::generic::queue <type_t> is empty.

enqueue()

template<class type_t, class allocator_t = xtd::collections::generic::helpers::allocator<type_t>>

auto xtd::collections::generic::queue< type_t, allocator_t >::enqueue ( const_reference value ) -> void

inline

Adds an object to the end of the xtd::collections::generic::queue <type_t>.

Parameters

item	The object to add to the xtd::collections::generic::queue <type_t>. The value can be null for reference types.

ensure_capacity()

template<class type_t, class allocator_t = xtd::collections::generic::helpers::allocator<type_t>>

auto xtd::collections::generic::queue< type_t, allocator_t >::ensure_capacity ( size_type capacity ) -> size_type

inline

Ensures that the capacity of this queue is at least the specified capacity. If the current capacity is less than capacity, it is increased to at least the specified capacity.

Parameters

capacity

The minimum capacity to ensure.

Returns

The new capacity of this queue.

get_enumerator()

template<class type_t, class allocator_t = xtd::collections::generic::helpers::allocator<type_t>>

enumerator< value_type > xtd::collections::generic::queue< type_t, allocator_t >::get_enumerator ( ) const

inlineoverridenoexcept

Returns an enumerator that iterates through the xtd::collections::generic::queue <type_t>.

Returns

A xtd::collections::generic::.enumerator for the xtd::collections::generic::queue <type_t>.

peek()

template<class type_t, class allocator_t = xtd::collections::generic::helpers::allocator<type_t>>

auto xtd::collections::generic::queue< type_t, allocator_t >::peek ( ) const -> value_type

inlinenodiscard

Returns the object at the beginning of the xtd::collections::generic::queue <type_t> without removing it.

Returns

The object at the beginning of the xtd::collections::generic::queue <type_t>.

Exceptions

xtd::invalid_operation_exception

The xtd::collections::generic::queue <type_t> is empty.

to_array()

template<class type_t, class allocator_t = xtd::collections::generic::helpers::allocator<type_t>>

auto xtd::collections::generic::queue< type_t, allocator_t >::to_array ( ) const -> xtd::array<value_type>

inline

Copies the xtd::collections::generic::queue <type_t> elements to a new array.

Returns

A new array containing elements copied from the xtd::collections::generic::queue <type_t>.

to_string()

template<class type_t, class allocator_t = xtd::collections::generic::helpers::allocator<type_t>>

auto xtd::collections::generic::queue< type_t, allocator_t >::to_string ( ) const -> string

inlineoverridevirtualnoexcept

Returns a xtd::string that represents the current object.

Returns

A string that represents the current object.

Reimplemented from xtd::object.

trim_excess() [1/2]

template<class type_t, class allocator_t = xtd::collections::generic::helpers::allocator<type_t>>

auto xtd::collections::generic::queue< type_t, allocator_t >::trim_excess ( ) -> void

inline

Sets the capacity to the actual number of elements in the xtd::collections::generic::queue <type_t>, if that number is less than 90 percent of current capacity.

Remarks

This method can be used to minimize a collection's memory overhead if no new elements will be added to the collection. The cost of reallocating and copying a large xtd::collections::generic::queue <type_t> can be considerable, however, so the xtd::collections::generic::queue::trim_excess method does nothing if the list is at more than 90 percent of capacity. This avoids incurring a large reallocation cost for a relatively small gain.

This method is an O(n) operation, where n is xtd::collections::generic::queue::count.

To reset a xtd::collections::generic::queue <type_t> to its initial state, call the xtd::collections::generic::queue::clear method before calling xtd::collections::generic::queue::trim_excess method. Trimming an empty xtd::collections::generic::queue <type_t> sets the capacity of the xtd::collections::generic::queue <type_t> to the default capacity.

trim_excess() [2/2]

template<class type_t, class allocator_t = xtd::collections::generic::helpers::allocator<type_t>>

auto xtd::collections::generic::queue< type_t, allocator_t >::trim_excess ( size_type capacity ) -> void

inline

Sets the capacity of a xtd::collections::generic::queue <type_t> object to the specified number of entries.

Parameters

capacity

The new capacity.

Exceptions

xtd::argument_out_of_range_exception

Passed capacity is lower than entries count.

try_dequeue()

template<class type_t, class allocator_t = xtd::collections::generic::helpers::allocator<type_t>>

auto xtd::collections::generic::queue< type_t, allocator_t >::try_dequeue ( value_type & result ) -> bool

inlinenodiscardnoexcept

Removes the object at the beginning of the xtd::collections::generic::queue <type_t>, and copies it to the result parameter.

Parameters

The	removed object.

Returns

true if the object is successfully removed; false if the xtd::collections::generic::queue <type_t> is empty.

try_peek()

template<class type_t, class allocator_t = xtd::collections::generic::helpers::allocator<type_t>>

auto xtd::collections::generic::queue< type_t, allocator_t >::try_peek ( value_type & result ) const -> bool

inlinenodiscardnoexcept

Returns a value that indicates whether there is an object at the beginning of the xtd::collections::generic::queue <type_t>, and if one is present, copies it to the result parameter. The object is not removed from the xtd::collections::generic::queue <type_t>.

Parameters

If	present, the object at the beginning of the xtd::collections::generic::queue <type_t>; otherwise, the default value of type_t.

Returns

true if there is an object at the beginning of the xtd::collections::generic::queue <type_t>; false if the xtd::collections::generic::queue <type_t> is empty.

operator std::queue< type_t >()

template<class type_t, class allocator_t = xtd::collections::generic::helpers::allocator<type_t>>

xtd::collections::generic::queue< type_t, allocator_t >::operator std::queue< type_t > ( ) const

inline

Gets a std::queue<type_t>.

Returns

A std::queue<type_t>.

---

The documentation for this class was generated from the following file:

• xtd.core/include/xtd/collections/generic/queue.hpp