You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
361 lines
11 KiB
C++
361 lines
11 KiB
C++
// Copyright (C) 2003 Davis E. King (davis@dlib.net)
|
|
// License: Boost Software License See LICENSE.txt for the full license.
|
|
#undef DLIB_ARRAY_KERNEl_ABSTRACT_
|
|
#ifdef DLIB_ARRAY_KERNEl_ABSTRACT_
|
|
|
|
#include "../interfaces/enumerable.h"
|
|
#include "../serialize.h"
|
|
#include "../algs.h"
|
|
|
|
namespace dlib
|
|
{
|
|
|
|
template <
|
|
typename T,
|
|
typename mem_manager = default_memory_manager
|
|
>
|
|
class array : public enumerable<T>
|
|
{
|
|
|
|
/*!
|
|
REQUIREMENTS ON T
|
|
T must have a default constructor.
|
|
|
|
REQUIREMENTS ON mem_manager
|
|
must be an implementation of memory_manager/memory_manager_kernel_abstract.h or
|
|
must be an implementation of memory_manager_global/memory_manager_global_kernel_abstract.h or
|
|
must be an implementation of memory_manager_stateless/memory_manager_stateless_kernel_abstract.h
|
|
mem_manager::type can be set to anything.
|
|
|
|
POINTERS AND REFERENCES TO INTERNAL DATA
|
|
front(), back(), swap(), max_size(), set_size(), and operator[]
|
|
functions do not invalidate pointers or references to internal data.
|
|
All other functions have no such guarantee.
|
|
|
|
INITIAL VALUE
|
|
size() == 0
|
|
max_size() == 0
|
|
|
|
ENUMERATION ORDER
|
|
The enumerator will iterate over the elements of the array in the
|
|
order (*this)[0], (*this)[1], (*this)[2], ...
|
|
|
|
WHAT THIS OBJECT REPRESENTS
|
|
This object represents an ordered 1-dimensional array of items,
|
|
each item is associated with an integer value. The items are
|
|
numbered from 0 though size() - 1 and the operator[] functions
|
|
run in constant time.
|
|
|
|
Also note that unless specified otherwise, no member functions
|
|
of this object throw exceptions.
|
|
!*/
|
|
|
|
public:
|
|
|
|
typedef T type;
|
|
typedef T value_type;
|
|
typedef mem_manager mem_manager_type;
|
|
|
|
array (
|
|
);
|
|
/*!
|
|
ensures
|
|
- #*this is properly initialized
|
|
throws
|
|
- std::bad_alloc or any exception thrown by T's constructor
|
|
!*/
|
|
|
|
explicit array (
|
|
size_t new_size
|
|
);
|
|
/*!
|
|
ensures
|
|
- #*this is properly initialized
|
|
- #size() == new_size
|
|
- #max_size() == new_size
|
|
- All elements of the array will have initial values for their type.
|
|
throws
|
|
- std::bad_alloc or any exception thrown by T's constructor
|
|
!*/
|
|
|
|
~array (
|
|
);
|
|
/*!
|
|
ensures
|
|
- all memory associated with *this has been released
|
|
!*/
|
|
|
|
array(
|
|
array&& item
|
|
);
|
|
/*!
|
|
ensures
|
|
- move constructs *this from item. Therefore, the state of item is
|
|
moved into *this and #item has a valid but unspecified state.
|
|
!*/
|
|
|
|
array& operator=(
|
|
array&& item
|
|
);
|
|
/*!
|
|
ensures
|
|
- move assigns *this from item. Therefore, the state of item is
|
|
moved into *this and #item has a valid but unspecified state.
|
|
- returns a reference to #*this
|
|
!*/
|
|
|
|
void clear (
|
|
);
|
|
/*!
|
|
ensures
|
|
- #*this has its initial value
|
|
throws
|
|
- std::bad_alloc or any exception thrown by T's constructor
|
|
if this exception is thrown then the array object is unusable
|
|
until clear() is called and succeeds
|
|
!*/
|
|
|
|
const T& operator[] (
|
|
size_t pos
|
|
) const;
|
|
/*!
|
|
requires
|
|
- pos < size()
|
|
ensures
|
|
- returns a const reference to the element at position pos
|
|
!*/
|
|
|
|
T& operator[] (
|
|
size_t pos
|
|
);
|
|
/*!
|
|
requires
|
|
- pos < size()
|
|
ensures
|
|
- returns a non-const reference to the element at position pos
|
|
!*/
|
|
|
|
void set_size (
|
|
size_t size
|
|
);
|
|
/*!
|
|
requires
|
|
- size <= max_size()
|
|
ensures
|
|
- #size() == size
|
|
- any element with index between 0 and size - 1 which was in the
|
|
array before the call to set_size() retains its value and index.
|
|
All other elements have undetermined (but valid for their type)
|
|
values. (e.g. this object might buffer old T objects and reuse
|
|
them without reinitializing them between calls to set_size())
|
|
- #at_start() == true
|
|
throws
|
|
- std::bad_alloc or any exception thrown by T's constructor
|
|
may throw this exception if there is not enough memory and
|
|
if it does throw then the call to set_size() has no effect
|
|
!*/
|
|
|
|
size_t max_size(
|
|
) const;
|
|
/*!
|
|
ensures
|
|
- returns the maximum size of *this
|
|
!*/
|
|
|
|
void set_max_size(
|
|
size_t max
|
|
);
|
|
/*!
|
|
ensures
|
|
- #max_size() == max
|
|
- #size() == 0
|
|
- #at_start() == true
|
|
throws
|
|
- std::bad_alloc or any exception thrown by T's constructor
|
|
may throw this exception if there is not enough
|
|
memory and if it does throw then max_size() == 0
|
|
!*/
|
|
|
|
void swap (
|
|
array<T>& item
|
|
);
|
|
/*!
|
|
ensures
|
|
- swaps *this and item
|
|
!*/
|
|
|
|
void sort (
|
|
);
|
|
/*!
|
|
requires
|
|
- T must be a type with that is comparable via operator<
|
|
ensures
|
|
- for all elements in #*this the ith element is <= the i+1 element
|
|
- #at_start() == true
|
|
throws
|
|
- std::bad_alloc or any exception thrown by T's constructor
|
|
data may be lost if sort() throws
|
|
!*/
|
|
|
|
void resize (
|
|
size_t new_size
|
|
);
|
|
/*!
|
|
ensures
|
|
- #size() == new_size
|
|
- #max_size() == max(new_size,max_size())
|
|
- for all i < size() && i < new_size:
|
|
- #(*this)[i] == (*this)[i]
|
|
(i.e. All the original elements of *this which were at index
|
|
values less than new_size are unmodified.)
|
|
- for all valid i >= size():
|
|
- #(*this)[i] has an undefined value
|
|
(i.e. any new elements of the array have an undefined value)
|
|
throws
|
|
- std::bad_alloc or any exception thrown by T's constructor.
|
|
If an exception is thrown then it has no effect on *this.
|
|
!*/
|
|
|
|
|
|
const T& back (
|
|
) const;
|
|
/*!
|
|
requires
|
|
- size() != 0
|
|
ensures
|
|
- returns a const reference to (*this)[size()-1]
|
|
!*/
|
|
|
|
T& back (
|
|
);
|
|
/*!
|
|
requires
|
|
- size() != 0
|
|
ensures
|
|
- returns a non-const reference to (*this)[size()-1]
|
|
!*/
|
|
|
|
void pop_back (
|
|
T& item
|
|
);
|
|
/*!
|
|
requires
|
|
- size() != 0
|
|
ensures
|
|
- #size() == size() - 1
|
|
- swaps (*this)[size()-1] into item
|
|
- All elements with an index less than size()-1 are
|
|
unmodified by this operation.
|
|
!*/
|
|
|
|
void pop_back (
|
|
);
|
|
/*!
|
|
requires
|
|
- size() != 0
|
|
ensures
|
|
- #size() == size() - 1
|
|
- All elements with an index less than size()-1 are
|
|
unmodified by this operation.
|
|
!*/
|
|
|
|
void push_back (
|
|
T& item
|
|
);
|
|
/*!
|
|
ensures
|
|
- #size() == size()+1
|
|
- swaps item into (*this)[#size()-1]
|
|
- #back() == item
|
|
- #item has some undefined value (whatever happens to
|
|
get swapped out of the array)
|
|
throws
|
|
- std::bad_alloc or any exception thrown by T's constructor.
|
|
If an exception is thrown then it has no effect on *this.
|
|
!*/
|
|
|
|
void push_back (T&& item) { push_back(item); }
|
|
/*!
|
|
enable push_back from rvalues
|
|
!*/
|
|
|
|
typedef T* iterator;
|
|
typedef const T* const_iterator;
|
|
|
|
iterator begin(
|
|
);
|
|
/*!
|
|
ensures
|
|
- returns an iterator that points to the first element in this array or
|
|
end() if the array is empty.
|
|
!*/
|
|
|
|
const_iterator begin(
|
|
) const;
|
|
/*!
|
|
ensures
|
|
- returns a const iterator that points to the first element in this
|
|
array or end() if the array is empty.
|
|
!*/
|
|
|
|
iterator end(
|
|
);
|
|
/*!
|
|
ensures
|
|
- returns an iterator that points to one past the end of the array.
|
|
!*/
|
|
|
|
const_iterator end(
|
|
) const;
|
|
/*!
|
|
ensures
|
|
- returns a const iterator that points to one past the end of the
|
|
array.
|
|
!*/
|
|
|
|
private:
|
|
|
|
// restricted functions
|
|
array(array<T>&); // copy constructor
|
|
array<T>& operator=(array<T>&); // assignment operator
|
|
|
|
};
|
|
|
|
template <
|
|
typename T
|
|
>
|
|
inline void swap (
|
|
array<T>& a,
|
|
array<T>& b
|
|
) { a.swap(b); }
|
|
/*!
|
|
provides a global swap function
|
|
!*/
|
|
|
|
template <
|
|
typename T
|
|
>
|
|
void serialize (
|
|
const array<T>& item,
|
|
std::ostream& out
|
|
);
|
|
/*!
|
|
provides serialization support
|
|
!*/
|
|
|
|
template <
|
|
typename T
|
|
>
|
|
void deserialize (
|
|
array<T>& item,
|
|
std::istream& in
|
|
);
|
|
/*!
|
|
provides deserialization support
|
|
!*/
|
|
|
|
}
|
|
|
|
#endif // DLIB_ARRAY_KERNEl_ABSTRACT_
|
|
|