Skip to content

Commit 42a34a9

Browse files
bruxismabruxisma
committed
Add missing type traits
Add an endian neutral implementation of MurmurHash2. Add copy_until to algorithms Add array component documentation Change string_view to use MurmurHash2 Begin documentation cleanup and reorganization
1 parent 16a8c23 commit 42a34a9

File tree

10 files changed

+1008
-313
lines changed

10 files changed

+1008
-313
lines changed

‎docs/any.rst

+89-88
Original file line numberDiff line numberDiff line change
@@ -1,116 +1,117 @@
1-
.. |any| replace:: :class:`any <core::any>`
2-
3-
.. _core-any-component:
4-
51
Any Component
62
=============
73

8-
The |any| component is currently available in Boost (and has been for
9-
quite some time). The |any| component follows the Library Technical
4+
.. namespace:: core
5+
6+
The :any:`any` component is currently available in Boost (and has been for
7+
quite some time). The :any:`any` component follows the Library Technical
108
Specification to the letter, and even performs the *small object optimization*.
11-
This means that for types whose size are less than (or equal to) a ``void*``,
12-
no allocation will take place.
9+
This means that for types whose size are less than (or equal to) a
10+
:cxx:`void*`, no allocation will take place.
1311

14-
The any component resides in ``<core/any.hpp>``.
12+
The any component resides in :file:`<core/any.hpp>`.
1513

16-
.. namespace:: core
14+
This component is unavailable if :c:macro:`CORE_NO_RTTI` is defined.
1715

1816
.. class:: bad_any_cast
1917

2018
:inherits: std::bad_cast
2119

22-
This is the exception thrown when :func:`any_cast` fails.
23-
It inherits from ``std::bad_cast``.
20+
This is the exception thrown when :any:`any_cast` fails. It inherits from
21+
:cxx:`std::bad_cast`.
2422

25-
.. function:: char const* bad_any_cast::what () const noexcept
23+
This type is unavailable if :c:macro:`CORE_NO_EXCEPTIONS` is defined.
2624

27-
Returns the string "bad any cast". At some point in the future a more
28-
descriptive error may be given.
25+
.. function:: char const* what () const noexcept
26+
27+
Returns the string "bad any cast". If :cxx:`typeid(T).name()` was
28+
standardized, this would be added to the error message
2929

3030
.. class:: any
3131

32-
.. function:: any::any (any const&)
33-
any::any (any&&) noexcept
34-
any::any () noexcept
35-
36-
.. versionadded:: 1.2
37-
38-
The behavior regarding the move constructor has changed to follow
39-
the specification. It will now construct a value of the same type
40-
as contained in the incoming |any| and use the move constructor of
41-
the type. If the incoming |any| is empty, the newly constructed
42-
|any| will be as well. Before 1.2, the move constructor would simply
43-
result in a state change.
44-
45-
The default set of constructors work as one might imagine. The copy
46-
constructor is not marked as noexcept as the underlying type *may*
47-
throw an exception, and due to the type erasure performed, the |any| has
48-
no way of enforcing this at compile time.
49-
50-
.. function:: any::any (ValueType&& value)
51-
52-
When constructing an |any| with a given :cxx:`ValueType`, it will perform a
53-
series of compile time checks to see whether it should perform the small
54-
object optimization. If the object is deemed small enough, it will not
55-
allocate memory. Otherwise, a new :cxx:`ValueType` will be allocated via
56-
:cxx:`operator new`, and constructed with the given *value*.
57-
58-
:raises: Any exceptions thrown by the copy or move constructor
59-
of the given ValueType.
60-
61-
.. function:: any& any::operator = (any const&)
62-
any& any::operator = (any&&) noexcept
63-
64-
Assigns the contents of the incoming |any| to ``*this``.
65-
66-
.. function:: any& any::operator = (ValueType&& value)
67-
68-
Assigns *value* to ``*this``. If ``*this`` already manages a contained
69-
object, it will be destroyed after *value* is assigned.
70-
71-
.. versionadded:: 1.1
72-
73-
This function was unfortunately omitted from the 1.0 release.
74-
75-
.. function:: void any::swap (any&) noexcept
76-
77-
Swaps the object contained within the given |any| with the one contained
78-
within ``*this``.
79-
80-
.. function:: std::type_info const& any::type () const noexcept
81-
82-
Returns the :cxx:`std::type_info` for the type contained within. If the
83-
|any| is empty, it will return :cxx:`typeid(void)`.
84-
85-
.. function:: bool any::empty () const noexcept
86-
87-
If the |any| does not contain any data (i.e.
88-
:func:`type() <core::any::type>` returns :cxx:`typeid(void)`), it will
89-
return true.
90-
91-
.. function:: void any::clear () noexcept
92-
93-
:postcondition: :func:`empty() <core::any::empty>` == true
94-
95-
Destroys the object contained within the |any|.
96-
32+
.. function:: any (any const&)
33+
any (any&&) noexcept
34+
any () noexcept
35+
36+
.. versionadded:: 1.2
37+
38+
The behavior regarding the move constructor has changed to follow
39+
the specification. It will now construct a value of the same type
40+
as contained in the incoming :any:`any` and use the move constructor
41+
of the type. If the incoming :any:`any` is empty, the newly
42+
constructed :any:`any` will be as well. Before 1.2, the move
43+
constructor would simply result in a state change.
44+
45+
The default set of constructors work as one might imagine. The copy
46+
constructor is not marked as noexcept as the underlying type *may*
47+
throw an exception, and due to the type erasure performed, the :any:`any`
48+
has no way of enforcing this at compile time.
49+
50+
.. function:: any (ValueType&& value)
51+
52+
When constructing an :any:`any` with a given *ValueType*, it will perform
53+
a series of compile time checks to see whether it should perform the
54+
small object optimization. If the object is deemed small enough, it will
55+
not allocate memory. Otherwise, a new *ValueType* will be allocated via
56+
:cxx:`operator new`, and constructed with the given *value*.
57+
58+
:raises: Any exceptions thrown by the copy or move constructor
59+
of the given ValueType.
60+
61+
.. function:: any& operator = (any const&)
62+
any& operator = (any&&) noexcept
63+
64+
Assigns the contents of the incoming :any:`any` to :cxx:`*this`.
65+
66+
.. function:: any& operator = (ValueType&& value)
67+
68+
Assigns *value* to :cxx:`*this`. If :cxx:`*this` already manages a
69+
contained object, it will be destroyed after *value* is assigned.
70+
71+
.. versionadded:: 1.1
72+
73+
This function was unfortunately omitted from the 1.0 release.
74+
75+
.. function:: void swap (any&) noexcept
76+
77+
Performs a simple state change with the incoming :any:`any`.
78+
79+
.. note:: Previous versions of the documentation for this function gave
80+
the impression that an actual swap operation took place. However,
81+
a *state* change results in calling swap on the internal storage
82+
type used by :any:`any`.
83+
84+
.. function:: std::type_info const& type () const noexcept
85+
86+
Returns the :cxx:`std::type_info` for the type contained within. If the
87+
:any:`any` is empty, it will return :cxx:`typeid(void)`.
88+
89+
.. function:: bool empty () const noexcept
90+
91+
If the :any:`any` does not contain any data (i.e. :any:`type` returns
92+
:cxx:`typeid(void)`), it will return :cxx:`true`.
93+
94+
.. function:: void clear () noexcept
95+
96+
:postcondition: :any:`empty` == true
97+
98+
Destroys the object contained within the :any:`any`.
9799

98100
.. function:: ValueType any_cast (any const& operand)
99101
ValueType any_cast (any&& operand)
100102
ValueType any_cast (any& operand)
101103

102104
Given a type *ValueType*, it will attempt to extract the value stored within
103-
the given |any|. *ValueType* may be either concrete or a reference type.
104-
If ``typeid(remove_reference_t<ValueType>)`` is not equal to the value
105-
returned by :func:`type() <core::any::type>`, :class:`bad_any_cast` is
106-
thrown.
105+
the given :any:`any`. *ValueType* may be either concrete or a reference
106+
type. If :cxx:`typeid(remove_reference_t<ValueType>)` is not equal to the
107+
value returned by :any:`type`, :any:`bad_any_cast` is thrown.
107108

108-
:returns: ``*any_cast<add_const_t<remove_reference_t<ValueType>>(&operand)``
109-
for the first :func:`any_cast` signature. For the other overloads,
109+
:returns: :cxx:`*any_cast<add_const_t<remove_reference_t<T>>(&operand)`
110+
for the first :any:`any_cast` signature. For the other overloads,
110111
the return type is
111-
``*any_cast<remove_reference_t<ValueType>>(&operand)``.
112+
:cxx:`*any_cast<remove_reference_t<T>>(&operand)`.
112113

113-
:raises: :class:`bad_any_cast`
114+
:raises: :any:`bad_any_cast`
114115

115116
:example:
116117
.. code-block:: cpp

‎docs/array.rst

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
Array Component
2+
===============
3+
4+
.. namespace:: core
5+
6+
The array component currently provides two helper functions for working with
7+
:cxx:`std::array` in the C++ standard library. Specifically, this component
8+
provides an implementation of `N4315`_. This component can be found in the
9+
``<core/array.hpp>`` header.
10+
11+
.. function:: constexpr std::array<T, N> make_array (Args&&... args)
12+
13+
Given a parameter pack *args*, return a :cxx:`std::array` with the
14+
:cxx:`common_type_t<Args...>`. Additionally, a type can be given explicitly.
15+
This function is *does not* participate in overload resolution if any of the
16+
elements in *args* are a :cxx:`std::reference_wrapper`.
17+
18+
:example:
19+
20+
.. code-block:: cpp
21+
22+
auto a1 = make_array(1, 2, 3, 4);
23+
using type1 = decltype(a1)::value_type;
24+
static_assert(std::is_same<type1, int>::value, "");
25+
26+
auto a2 = make_array<long>(1, 2L, 3L, 4);
27+
using type2 = decltype(a2)::value_type;
28+
static_assert(std::is_same<type2, long>::value, "");
29+
30+
.. function:: constexpr std::array<T, N> to_array (T (&array)[N])
31+
32+
Given a C array of type *T* with a defined length of *N*, creates a
33+
:cxx:`std::array` with the same length and size.
34+
35+
.. note:: This function will copy initialize each *T*
36+
37+
.. _N4315: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4315.html

‎docs/conf.py

+7
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
# -*- coding: utf-8 -*-
12
import alabaster as theme
23
import os
34

@@ -7,6 +8,8 @@
78
version = '1.2'
89
release = '1.2'
910

11+
needs_sphinx = '1.3'
12+
1013
html_static_path = ['static']
1114
html_theme_path = [theme.get_path()]
1215
html_theme = 'alabaster'
@@ -27,6 +30,10 @@
2730
rst_prolog = '''
2831
.. role:: cxx(code)
2932
:language: cpp
33+
34+
.. role:: cmake(code)
35+
:language: cmake
36+
3037
'''
3138

3239
extensions = ['sphinx.ext.todo', 'alabaster']

‎docs/index.rst

+3-3
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,8 @@ be included in C++14 and beyond. A majority of the components of MNMLSTC Core
66
can also be found in Boost. However, there are distinct behaviorial differences
77
that are outlined and discussed in this documentation.
88

9-
It is recommended that new users read the section on :ref:`using-mnmlstc-core`.
10-
The documentation is ordered according to the augmented library components,
11-
rather than by feature.
9+
It is recommended that new users read :doc:`usage`. The documentation is
10+
ordered according to the augmented library components, rather than by feature.
1211

1312
.. toctree::
1413
:maxdepth: 1
@@ -17,6 +16,7 @@ rather than by feature.
1716
Type Traits <type-traits>
1817
Functional Utilities <functional>
1918
Algorithms <algorithm>
19+
Arrays <array>
2020
Iterator Utilities <iterator>
2121
Optional Types <optional>
2222
Numeric Algorithms <numeric>

0 commit comments

Comments
 (0)