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..fe43e46 --- /dev/null +++ b/doc/pointer_traits.qbk @@ -0,0 +1,141 @@ +[/ +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 obtains a raw pointer from a pointer and 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; + }; +} +``` + +[section Member types] + +[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 + [[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.]]]]]] + +[endsect] + +[section Member functions] + +[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 + [[Requires] + [`v` is not a null pointer.]] + [[Returns] + [A pointer of type `element_type*` that references the same location + as the argument.]]]]]] + +[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`.]]]]]] + +[endsect] + +[endsect] + +[section Acknowledgments] + +Glen Fernandes implemented `pointer_traits` with reviews and guidance from +Peter Dimov. + +[endsect] + +[endsect]