From 87dd2883b81235b5fcf84ee311cb17428a1ac934 Mon Sep 17 00:00:00 2001 From: Glen Fernandes Date: Sat, 20 May 2017 09:29:01 -0400 Subject: [PATCH 1/3] Add pointer_traits documentation --- doc/core.qbk | 1 + doc/pointer_traits.qbk | 133 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 134 insertions(+) create mode 100644 doc/pointer_traits.qbk diff --git a/doc/core.qbk b/doc/core.qbk index 1f2bcf8..5382bf6 100644 --- a/doc/core.qbk +++ b/doc/core.qbk @@ -49,6 +49,7 @@ criteria for inclusion is that the utility component be: [include no_exceptions_support.qbk] [include noncopyable.qbk] [include null_deleter.qbk] +[include pointer_traits.qbk] [include ref.qbk] [include scoped_enum.qbk] [include swap.qbk] diff --git a/doc/pointer_traits.qbk b/doc/pointer_traits.qbk new file mode 100644 index 0000000..703eb16 --- /dev/null +++ b/doc/pointer_traits.qbk @@ -0,0 +1,133 @@ +[/ +Copyright 2017 Glen Joseph Fernandes +(glenjofe@gmail.com) + +Distributed under the Boost Software License, Version 1.0. +(http://www.boost.org/LICENSE_1_0.txt) +] + +[section:pointer_traits pointer_traits] + +[simplesect Authors] + +* Glen Fernandes + +[endsimplesect] + +[section Overview] + +The header provides the class template +`boost::pointer_traits` to facilitate use of pointer-like types. The C++11 +standard library introduced `std::pointer_traits` along with an allocator +model which supported pointer-like types in addition to plain raw pointers. +This implementation also supports C++98, and adds additional functionality +for obtaining raw pointers from pointers. + +[endsect] + +[section Examples] + +The following function template can obtaining a raw pointer from a pointer, +which works with null pointers and also is well defined when the pointer +aliases storage that has no object constructed in it. + +``` +template +inline typename boost::pointer_traits::element_type* +to_raw_pointer(T v) noexcept +{ + return boost::pointer_traits::to_address(v); +} +``` + +[endsect] + +[section Reference] + +``` +namespace boost { + template struct pointer_traits { + typedef T pointer; + typedef ``['see below]`` element_type; + typedef ``['see below]`` difference_type; + + template struct rebind_to { typedef ``['see below]`` type; }; + template using rebind = typename rebind_to::type; + + static pointer pointer_to(``['see below]`` v); + static element_type* to_address(pointer v) noexcept; + }; + + template struct pointer_traits { + typedef T* pointer; + typedef T element_type; + typedef std::ptrdiff_t difference_type; + + template struct rebind_to { typedef U* type; }; + template using rebind = typename rebind_to::type; + + static pointer pointer_to(``['see below]`` v) noexcept; + static element_type* to_address(pointer v) noexcept; + }; +} +``` + +[heading Member types] + +[ordered_list + [`typedef` ['see below] `element_type;` + [variablelist + [[Type] + [`T::element_type` if such a type exists; otherwise `U` if `T` is a + class template instantiation of the form `Pointer`, where + `Args` is zero or more type arguments; otherwise the specialization + is ill-formed.]]]] + [`typedef` ['see below] `difference_type;` + [variablelist + [[Type] + [`T::difference_type` if such a type exists; otherwise + `std::ptrdiff_t`.]]]] + [`template struct rebind_to { typedef` ['see below] `type; };` + [variablelist + [[Type] + [`type` is `T::rebind` if such a type exists; otherwise, + `Pointer` if `T` is a class template instantiation of the + form `Pointer`, where `Args` is zero or more type + arguments; otherwise, the instantiation of `rebind_to` is + ill-formed.]]]]] + +[heading Member functions] + +[ordered_list + [`static pointer pointer_traits::pointer_to(`['see below] `v);` + [variablelist + [[Remark] + [If `element_type` is a void type, the type of `v` is unspecified; + otherwise, it is `element_type&`.]] + [[Returns] + [A pointer to `v` obtained by calling `T::pointer_to(v)`.]]]] + [`static pointer pointer_traits::pointer_to(`['see below] `v) noexcept;` + [variablelist + [[Remark] + [If `element_type` is a void type, the type of `v` is unspecified; + otherwise, it is `element_type&`.]] + [[Returns] + [The result of `std::addressof(v)`.]]]] + [`static element_type* pointer_traits::to_address(pointer v) noexcept;` + [variablelist + [[Returns] + [A plain pointer of type `element_type*` obtained by calling + `pointer_traits::to_address` on the value of `v.operator->()`.]]]] + [`static element_type* pointer_traits::to_address(pointer v) noexcept;` + [variablelist [[Returns] [The value of `v`.]]]]] + +[endsect] + +[section Acknowledgments] + +Glen Fernandes implemented `pointer_traits` with reviews and guidance from +Peter Dimov. + +[endsect] + +[endsect] From 89b17927249734a6f02737c066af4981f2bb9708 Mon Sep 17 00:00:00 2001 From: Glen Fernandes Date: Sun, 28 May 2017 20:29:56 -0400 Subject: [PATCH 2/3] Corrections to pointer_traits documentation --- doc/pointer_traits.qbk | 40 +++++++++++++++++++++++++++------------- 1 file changed, 27 insertions(+), 13 deletions(-) diff --git a/doc/pointer_traits.qbk b/doc/pointer_traits.qbk index 703eb16..bddea9b 100644 --- a/doc/pointer_traits.qbk +++ b/doc/pointer_traits.qbk @@ -27,9 +27,9 @@ for obtaining raw pointers from pointers. [section Examples] -The following function template can obtaining a raw pointer from a pointer, -which works with null pointers and also is well defined when the pointer -aliases storage that has no object constructed in it. +The following function template obtains a raw pointer from a pointer and is +well defined when the pointer aliases storage that has no object constructed +in it. ``` template @@ -72,7 +72,9 @@ namespace boost { } ``` -[heading Member types] +[section Member types] + +[heading `pointer_traits`] [ordered_list [`typedef` ['see below] `element_type;` @@ -96,33 +98,45 @@ namespace boost { arguments; otherwise, the instantiation of `rebind_to` is ill-formed.]]]]] -[heading Member functions] +[endsect] + +[section Member functions] + +[heading `pointer_traits`] [ordered_list - [`static pointer pointer_traits::pointer_to(`['see below] `v);` + [`static pointer pointer_to(`['see below] `v);` [variablelist [[Remark] [If `element_type` is a void type, the type of `v` is unspecified; otherwise, it is `element_type&`.]] [[Returns] [A pointer to `v` obtained by calling `T::pointer_to(v)`.]]]] - [`static pointer pointer_traits::pointer_to(`['see below] `v) noexcept;` + [`static element_type* to_address(pointer v) noexcept;` + [variablelist + [[Requires] + [`v` is not a null pointer.]] + [[Returns] + [A pointer of type `element_type*` that references the same location + as the argument.]]]]] + +[heading `pointer_traits`] + +[ordered_list + [`static pointer pointer_to(`['see below] `v) noexcept;` [variablelist [[Remark] [If `element_type` is a void type, the type of `v` is unspecified; otherwise, it is `element_type&`.]] [[Returns] [The result of `std::addressof(v)`.]]]] - [`static element_type* pointer_traits::to_address(pointer v) noexcept;` - [variablelist - [[Returns] - [A plain pointer of type `element_type*` obtained by calling - `pointer_traits::to_address` on the value of `v.operator->()`.]]]] - [`static element_type* pointer_traits::to_address(pointer v) noexcept;` + [`static element_type* to_address(pointer v) noexcept;` [variablelist [[Returns] [The value of `v`.]]]]] [endsect] +[endsect] + [section Acknowledgments] Glen Fernandes implemented `pointer_traits` with reviews and guidance from From f76116405de93e521a27e48e3f362a9ede91171a Mon Sep 17 00:00:00 2001 From: Glen Fernandes Date: Sun, 28 May 2017 21:36:52 -0400 Subject: [PATCH 3/3] Minor formatting changes in pointer_traits documentation --- doc/pointer_traits.qbk | 52 +++++++++++++++++++----------------------- 1 file changed, 23 insertions(+), 29 deletions(-) diff --git a/doc/pointer_traits.qbk b/doc/pointer_traits.qbk index bddea9b..fe43e46 100644 --- a/doc/pointer_traits.qbk +++ b/doc/pointer_traits.qbk @@ -74,64 +74,58 @@ namespace boost { [section Member types] -[heading `pointer_traits`] - -[ordered_list - [`typedef` ['see below] `element_type;` - [variablelist +[variablelist + [[`typedef` ['see below] `element_type;`] + [[variablelist [[Type] [`T::element_type` if such a type exists; otherwise `U` if `T` is a class template instantiation of the form `Pointer`, where `Args` is zero or more type arguments; otherwise the specialization - is ill-formed.]]]] - [`typedef` ['see below] `difference_type;` - [variablelist + is ill-formed.]]]]] + [[`typedef` ['see below] `difference_type;`] + [[variablelist [[Type] [`T::difference_type` if such a type exists; otherwise - `std::ptrdiff_t`.]]]] - [`template struct rebind_to { typedef` ['see below] `type; };` - [variablelist + `std::ptrdiff_t`.]]]]] + [[`template struct rebind_to { typedef` ['see below] `type; };`] + [[variablelist [[Type] [`type` is `T::rebind` if such a type exists; otherwise, `Pointer` if `T` is a class template instantiation of the form `Pointer`, where `Args` is zero or more type arguments; otherwise, the instantiation of `rebind_to` is - ill-formed.]]]]] + ill-formed.]]]]]] [endsect] [section Member functions] -[heading `pointer_traits`] - -[ordered_list - [`static pointer pointer_to(`['see below] `v);` - [variablelist +[variablelist pointer_traits + [[`static pointer pointer_to(`['see below] `v);`] + [[variablelist [[Remark] [If `element_type` is a void type, the type of `v` is unspecified; otherwise, it is `element_type&`.]] [[Returns] - [A pointer to `v` obtained by calling `T::pointer_to(v)`.]]]] - [`static element_type* to_address(pointer v) noexcept;` - [variablelist + [A pointer to `v` obtained by calling `T::pointer_to(v)`.]]]]] + [[`static element_type* to_address(pointer v) noexcept;`] + [[variablelist [[Requires] [`v` is not a null pointer.]] [[Returns] [A pointer of type `element_type*` that references the same location - as the argument.]]]]] + as the argument.]]]]]] -[heading `pointer_traits`] - -[ordered_list - [`static pointer pointer_to(`['see below] `v) noexcept;` - [variablelist +[variablelist pointer_traits + [[`static pointer pointer_to(`['see below] `v) noexcept;`] + [[variablelist [[Remark] [If `element_type` is a void type, the type of `v` is unspecified; otherwise, it is `element_type&`.]] [[Returns] - [The result of `std::addressof(v)`.]]]] - [`static element_type* to_address(pointer v) noexcept;` - [variablelist [[Returns] [The value of `v`.]]]]] + [The result of `std::addressof(v)`.]]]]] + [[`static element_type* to_address(pointer v) noexcept;`] + [[variablelist [[Returns] [The value of `v`.]]]]]] [endsect]