From 480b7a56a44c02e1fc37af786bb5b8c085ea8f45 Mon Sep 17 00:00:00 2001 From: q66 Date: Tue, 4 Apr 2017 19:28:01 +0200 Subject: [PATCH] more documentation --- ostd/ext/sdl_rwops.hh | 47 ++++++++++++++++++++++++++++++++----- ostd/string.hh | 7 ++---- ostd/unordered_map.hh | 42 +++++++++++++++++++++++++++++++-- ostd/vector.hh | 54 +++++++++++++++++++++++++++++++++++++------ 4 files changed, 130 insertions(+), 20 deletions(-) diff --git a/ostd/ext/sdl_rwops.hh b/ostd/ext/sdl_rwops.hh index c07f2ac..1326c2b 100644 --- a/ostd/ext/sdl_rwops.hh +++ b/ostd/ext/sdl_rwops.hh @@ -1,6 +1,23 @@ -/* SDL RWops integration. +/** @addtogroup Extensions * - * This file is part of OctaSTD. See COPYING.md for futher information. + * @brief Various extensions including integration of OctaSTD with other libs. + * + * @{ + */ + +/** @file sdl_rwops.hh + * + * @brief Integration of OctaSTD streams with SDL RWops. + * + * This provides integration of OctaSTD streams with SDL RWops so that + * various APIs that provide a generic RWops interface to deal with + * files can use OctaSTD streams. + * + * Supports both SDL1 and SDL2, with SDL2 being default. If you want to + * use SDL1 compatibility, define `OSTD_EXT_SDL_USE_SDL1` at build time + * or before including this header. + * + * @copyright See COPYING.md in the project tree for further information. */ #ifndef OSTD_EXT_SDL_RWOPS_HH @@ -17,13 +34,27 @@ namespace ostd { namespace sdl { +/** @addtogroup Extensions + * @{ + */ + +/** @brief Create an `SDL_RWops` using an OctaSTD stream. + * + * The resulting RWops object is created using `SDL_AllocRW()`. + * + * The `size`, `seek`, `read`, `write` and `close` callbacks are set up, + * but `close` will not actually close the stream, as the RWops object + * does not take ownership. + * + * @returns The RWops object or `nullptr` on failure. + */ +inline SDL_RWops *stream_to_rwops(stream &s) noexcept { #ifdef OSTD_EXT_SDL_USE_SDL1 -using sdl_rwops_off_t = int; + using sdl_rwops_off_t = int; #else -using sdl_rwops_off_t = int64_t; + using sdl_rwops_off_t = int64_t; #endif -inline SDL_RWops *stream_to_rwops(stream &s) { SDL_RWops *rwr = SDL_AllocRW(); if (!rwr) { return nullptr; @@ -46,7 +77,7 @@ inline SDL_RWops *stream_to_rwops(stream &s) { auto &is = *static_cast(rw->hidden.unknown.data1); try { if (!pos && whence == SEEK_CUR) { - return static_cast(is.tell()); } if (is->seek((stream_off_t(pos), stream_seek(whence)))) { return static_cast(is.tell()); @@ -89,4 +120,8 @@ inline SDL_RWops *stream_to_rwops(stream &s) { } } +/** @} */ + #endif + +/** @} */ diff --git a/ostd/string.hh b/ostd/string.hh index a34617e..19785d8 100644 --- a/ostd/string.hh +++ b/ostd/string.hh @@ -354,13 +354,10 @@ template< inline std::basic_string make_string(R range, A const &alloc = A{}) { std::basic_string ret{alloc}; using C = range_category_t; - if constexpr(std::is_convertible_v) { - /* finite random access or contiguous */ - auto h = range.half(); + if constexpr(std::is_convertible_v) { ret.reserve(range.size()); - ret.insert(ret.end(), h, h + range.size()); + ret.insert(ret.end(), range.data(), range.data() + range.size()); } else { - /* infinite random access and below */ for (; !range.empty(); range.pop_front()) { ret.push_back(range.front()); } diff --git a/ostd/unordered_map.hh b/ostd/unordered_map.hh index fe55793..57627f3 100644 --- a/ostd/unordered_map.hh +++ b/ostd/unordered_map.hh @@ -1,6 +1,14 @@ -/* OctaSTD extensions for std::unordered_map. +/** @addtogroup Containers + * @{ + */ + +/** @file unordered_map.hh * - * This file is part of OctaSTD. See COPYING.md for futher information. + * @brief Extensions for std::unordered_map. + * + * This file provides extensions for the standard std::unordered_map container. + * + * @copyright See COPYING.md in the project tree for further information. */ #ifndef OSTD_UNORDERED_MAP_HH @@ -13,6 +21,10 @@ namespace ostd { +/** @addtogroup Containers + * @{ + */ + namespace detail { template std::integral_constant< @@ -26,6 +38,23 @@ namespace detail { constexpr bool is_2tuple_like = decltype(tuple2_like_test(0))::value; } +/** @brief Creates an unordered map using a range. + * + * The range's value type must be either an std::pair or an std::tuple + * with 2 elements, additionally the key and value types must be constructible + * using the tuple or pair's first and second element respectively. + * + * You need to manually specify the key and value types for this overload. + * + * @param[in] range The range. + * @param[in] bcount The initial bucket count. + * @param[in] hash The hash function. + * @param[in] kequal The key equality comparison function. + * @param[in] alloc The allocator. + * + * @tparam K The key type. + * @tparam V The value type. + */ template< typename K, typename T, typename H = std::hash, typename E = std::equal_to, @@ -72,6 +101,11 @@ inline std::unordered_map make_unordered_map( return ret; } +/** @brief Creates an unordered map using a range. + * + * Calls into make_unordered_map() using the range value type's first and + * second element types as key and value respectively. + */ template< typename R, typename H = std::hash::first_type>, @@ -98,6 +132,10 @@ inline std::unordered_map< >(std::forward(range), bcount, hash, kequal, alloc); } +/** @} */ + } /* namespace ostd */ #endif + +/** @} */ diff --git a/ostd/vector.hh b/ostd/vector.hh index d18c731..1698520 100644 --- a/ostd/vector.hh +++ b/ostd/vector.hh @@ -1,6 +1,26 @@ -/* OctaSTD extensions for std::vector. +/** @defgroup Containers * - * This file is part of OctaSTD. See COPYING.md for futher information. + * @brief New containers and extensions to standard containers. + * + * OctaSTD adds various new utilities for standard containers that allow + * besides other things construction of those containers from ranges. + * + * Integration of ranges for iteration is however not necessary because + * there is already a fully generic integration for anything that provides + * an iterator interface. + * + * New containers will also be implemented where necessary. + * + * @{ + */ + +/** @file vector.hh + * + * @brief Extensions for std::vector. + * + * This file provides extensions for the standard std::vector container. + * + * @copyright See COPYING.md in the project tree for further information. */ #ifndef OSTD_VECTOR_HH @@ -14,17 +34,28 @@ namespace ostd { +/** @addtogroup Containers + * @{ + */ + +/** @brief Creates a vector using a range. + * + * Given a range `range` and optionally an allocator, this constructs + * an std::vector, adding each item of the given range to it. + * + * You have to manually specify the type of the vector's values. There + * is also another version with the type decided from the range. + * + * @tparam T The value type of the vector. + */ template, typename R> inline std::vector make_vector(R range, A const &alloc = A{}) { std::vector ret{alloc}; using C = range_category_t; - if constexpr(std::is_convertible_v) { - /* finite random access or contiguous */ - auto h = range.half(); + if constexpr(std::is_convertible_v) { ret.reserve(range.size()); - ret.insert(ret.end(), h, h + range.size()); + ret.insert(ret.end(), range.data(), range.data() + range.size()); } else { - /* infinite random access and below */ for (; !range.empty(); range.pop_front()) { ret.push_back(range.front()); } @@ -32,6 +63,11 @@ inline std::vector make_vector(R range, A const &alloc = A{}) { return ret; } +/** @brief Creates a vector using a range. + * + * Calls into make_vector() using the range value type as the vector + * value type. + */ template>> inline std::vector, A> make_vector( R &&range, A const &alloc = A{} @@ -39,6 +75,10 @@ inline std::vector, A> make_vector( return make_vector, A>(std::forward(range), alloc); } +/** @} */ + } /* namespace ostd */ #endif + +/** @} */