From 6f30abde8fb44d4a921a9eb088923530f0bb89e1 Mon Sep 17 00:00:00 2001 From: Christos Choutouridis Date: Sun, 4 Oct 2020 21:53:09 +0300 Subject: [PATCH] WIP: Documentation --- Doxyfile | 111 ++++++------ include/utl/core/crtp.h | 30 ++-- include/utl/core/impl.h | 32 ++-- include/utl/core/types.h | 36 ++-- include/utl/core/version.h | 84 ++++++---- include/utl/dev/dev_iterators.h | 1 + include/utl/meta/{integral.h => basic.h} | 68 ++++---- include/utl/meta/detection.h | 97 ++++++----- include/utl/meta/invoke.h | 98 +++++------ include/utl/meta/meta.h | 36 ++-- include/utl/meta/operations.h | 204 +++++++++++------------ include/utl/meta/selection.h | 45 +++-- include/utl/meta/sfinae.h | 41 +++-- include/utl/meta/typelist.h | 54 +++--- include/utl/meta/useif.h | 48 +++--- 15 files changed, 487 insertions(+), 498 deletions(-) rename include/utl/meta/{integral.h => basic.h} (65%) diff --git a/Doxyfile b/Doxyfile index 71f1db0..c886e6e 100644 --- a/Doxyfile +++ b/Doxyfile @@ -1,4 +1,4 @@ -# Doxyfile 1.8.14 +# Doxyfile 1.8.13 # This file describes the settings to be used by the documentation system # doxygen (www.doxygen.org) for a project. @@ -20,8 +20,8 @@ # This tag specifies the encoding used for all characters in the config file # that follow. The default is UTF-8 which is also the encoding used for all text # before the first occurrence of this tag. Doxygen uses libiconv (or the iconv -# built into libc) for the transcoding. See -# https://www.gnu.org/software/libiconv/ for the list of possible encodings. +# built into libc) for the transcoding. See http://www.gnu.org/software/libiconv +# for the list of possible encodings. # The default value is: UTF-8. DOXYFILE_ENCODING = UTF-8 @@ -58,7 +58,7 @@ PROJECT_LOGO = # entered, it will be relative to the location where doxygen was started. If # left blank the current directory will be used. -OUTPUT_DIRECTORY = W:\Work\Software\Libraries\utl\doc +OUTPUT_DIRECTORY = doc # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub- # directories (in 2 levels) under the output directory of each output format and @@ -150,7 +150,7 @@ INLINE_INHERITED_MEMB = NO # shortest path that makes the file name unique will be used # The default value is: YES. -FULL_PATH_NAMES = YES +FULL_PATH_NAMES = NO # The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path. # Stripping is only done if one of the specified strings matches the left-hand @@ -337,7 +337,7 @@ BUILTIN_STL_SUPPORT = YES CPP_CLI_SUPPORT = NO # Set the SIP_SUPPORT tag to YES if your project consists of sip (see: -# https://www.riverbankcomputing.com/software/sip/intro) sources only. Doxygen +# http://www.riverbankcomputing.co.uk/software/sip/intro) sources only. Doxygen # will parse them like normal C++ but will assume all classes use public instead # of private inheritance when no explicit protection keyword is present. # The default value is: NO. @@ -360,14 +360,14 @@ IDL_PROPERTY_SUPPORT = YES # all members of a group must be documented explicitly. # The default value is: NO. -DISTRIBUTE_GROUP_DOC = NO +DISTRIBUTE_GROUP_DOC = YES # If one adds a struct or class to a group and this option is enabled, then also # any nested class or struct is added to the same group. By default this option # is disabled and one has to add nested compounds explicitly via \ingroup. # The default value is: NO. -GROUP_NESTED_COMPOUNDS = NO +GROUP_NESTED_COMPOUNDS = YES # Set the SUBGROUPING tag to YES to allow class member groups of the same type # (for instance a group of public functions) to be put as a subgroup of that @@ -397,7 +397,7 @@ INLINE_GROUPED_CLASSES = NO # Man pages) or section (for LaTeX and RTF). # The default value is: NO. -INLINE_SIMPLE_STRUCTS = NO +INLINE_SIMPLE_STRUCTS = YES # When TYPEDEF_HIDES_STRUCT tag is enabled, a typedef of a struct, union, or # enum is documented as struct, union, or enum with the name of the typedef. So @@ -408,7 +408,7 @@ INLINE_SIMPLE_STRUCTS = NO # types are typedef'ed and only the typedef is referenced, never the tag name. # The default value is: NO. -TYPEDEF_HIDES_STRUCT = NO +TYPEDEF_HIDES_STRUCT = YES # The size of the symbol lookup cache can be set using LOOKUP_CACHE_SIZE. This # cache is used to resolve symbols given their name and scope. Since this can be @@ -435,7 +435,7 @@ LOOKUP_CACHE_SIZE = 0 # normally produced when WARNINGS is set to YES. # The default value is: NO. -EXTRACT_ALL = YES +EXTRACT_ALL = NO # If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will # be included in the documentation. @@ -447,7 +447,7 @@ EXTRACT_PRIVATE = YES # scope will be included in the documentation. # The default value is: NO. -EXTRACT_PACKAGE = YES +EXTRACT_PACKAGE = NO # If the EXTRACT_STATIC tag is set to YES, all static members of a file will be # included in the documentation. @@ -469,7 +469,7 @@ EXTRACT_LOCAL_CLASSES = YES # included. # The default value is: NO. -EXTRACT_LOCAL_METHODS = YES +EXTRACT_LOCAL_METHODS = NO # If this flag is set to YES, the members of anonymous namespaces will be # extracted and appear in the documentation as a namespace called @@ -486,7 +486,7 @@ EXTRACT_ANON_NSPACES = NO # section is generated. This option has no effect if EXTRACT_ALL is enabled. # The default value is: NO. -HIDE_UNDOC_MEMBERS = NO +HIDE_UNDOC_MEMBERS = YES # If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all # undocumented classes that are normally visible in the class hierarchy. If set @@ -494,7 +494,7 @@ HIDE_UNDOC_MEMBERS = NO # has no effect if EXTRACT_ALL is enabled. # The default value is: NO. -HIDE_UNDOC_CLASSES = NO +HIDE_UNDOC_CLASSES = YES # If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend # (class|struct|union) declarations. If set to NO, these declarations will be @@ -508,14 +508,14 @@ HIDE_FRIEND_COMPOUNDS = NO # blocks will be appended to the function's detailed documentation block. # The default value is: NO. -HIDE_IN_BODY_DOCS = NO +HIDE_IN_BODY_DOCS = YES # The INTERNAL_DOCS tag determines if documentation that is typed after a # \internal command is included. If the tag is set to NO then the documentation # will be excluded. Set it to YES to include the internal documentation. # The default value is: NO. -INTERNAL_DOCS = NO +INTERNAL_DOCS = YES # If the CASE_SENSE_NAMES tag is set to NO then doxygen will only generate file # names in lower-case letters. If set to YES, upper-case letters are also @@ -607,7 +607,7 @@ SORT_GROUP_NAMES = NO # list. # The default value is: NO. -SORT_BY_SCOPE_NAME = NO +SORT_BY_SCOPE_NAME = YES # If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to do proper # type resolution of all parameters of a function it will reject a match between @@ -708,7 +708,7 @@ LAYOUT_FILE = # The CITE_BIB_FILES tag can be used to specify one or more bib files containing # the reference definitions. This must be a list of .bib files. The .bib # extension is automatically appended if omitted. This requires the bibtex tool -# to be installed. See also https://en.wikipedia.org/wiki/BibTeX for more info. +# to be installed. See also http://en.wikipedia.org/wiki/BibTeX for more info. # For LaTeX the style of the bibliography can be controlled using # LATEX_BIB_STYLE. To use this feature you need bibtex and perl available in the # search path. See also \cite for info how to create references. @@ -790,12 +790,12 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = +INPUT = . # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses # libiconv (or the iconv built into libc) for the transcoding. See the libiconv -# documentation (see: https://www.gnu.org/software/libiconv/) for the list of +# documentation (see: http://www.gnu.org/software/libiconv) for the list of # possible encodings. # The default value is: UTF-8. @@ -1043,7 +1043,7 @@ SOURCE_TOOLTIPS = YES # If the USE_HTAGS tag is set to YES then the references to source code will # point to the HTML generated by the htags(1) tool instead of doxygen built-in # source browser. The htags tool is part of GNU's global source tagging system -# (see https://www.gnu.org/software/global/global.html). You will need version +# (see http://www.gnu.org/software/global/global.html). You will need version # 4.8.6 or higher. # # To use it do the following: @@ -1079,7 +1079,7 @@ VERBATIM_HEADERS = YES # generated with the -Duse-libclang=ON option for CMake. # The default value is: NO. -CLANG_ASSISTED_PARSING = NO +CLANG_ASSISTED_PARSING = YES # If clang assisted parsing is enabled you can provide the compiler with command # line options that you would normally use when invoking the compiler. Note that @@ -1089,17 +1089,6 @@ CLANG_ASSISTED_PARSING = NO CLANG_OPTIONS = -# If clang assisted parsing is enabled you can provide the clang parser with the -# path to the compilation database (see: -# http://clang.llvm.org/docs/HowToSetupToolingForLLVM.html) used when the files -# were built. This is equivalent to specifying the "-p" option to a clang tool, -# such as clang-check. These options will then be pased to the parser. -# Note: The availability of this option depends on whether or not doxygen was -# generated with the -Duse-libclang=ON option for CMake. -# The default value is: 0. - -CLANG_COMPILATION_DATABASE_PATH= 0 - #--------------------------------------------------------------------------- # Configuration options related to the alphabetical class index #--------------------------------------------------------------------------- @@ -1218,7 +1207,7 @@ HTML_EXTRA_FILES = # The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen # will adjust the colors in the style sheet and background images according to # this color. Hue is specified as an angle on a colorwheel, see -# https://en.wikipedia.org/wiki/Hue for more information. For instance the value +# http://en.wikipedia.org/wiki/Hue for more information. For instance the value # 0 represents red, 60 is yellow, 120 is green, 180 is cyan, 240 is blue, 300 # purple, and 360 is red again. # Minimum value: 0, maximum value: 359, default value: 220. @@ -1254,17 +1243,6 @@ HTML_COLORSTYLE_GAMMA = 80 HTML_TIMESTAMP = NO -# If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML -# documentation will contain a main index with vertical navigation menus that -# are dynamically created via Javascript. If disabled, the navigation index will -# consists of multiple levels of tabs that are statically embedded in every HTML -# page. Disable this option to support browsers that do not have Javascript, -# like the Qt help browser. -# The default value is: YES. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_DYNAMIC_MENUS = YES - # If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML # documentation will contain sections that can be hidden and shown after the # page has loaded. @@ -1288,12 +1266,12 @@ HTML_INDEX_NUM_ENTRIES = 100 # If the GENERATE_DOCSET tag is set to YES, additional index files will be # generated that can be used as input for Apple's Xcode 3 integrated development -# environment (see: https://developer.apple.com/tools/xcode/), introduced with +# environment (see: http://developer.apple.com/tools/xcode/), introduced with # OSX 10.5 (Leopard). To create a documentation set, doxygen will generate a # Makefile in the HTML output directory. Running make will produce the docset in # that directory and running make install will install the docset in # ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find it at -# startup. See https://developer.apple.com/tools/creatingdocsetswithdoxygen.html +# startup. See http://developer.apple.com/tools/creatingdocsetswithdoxygen.html # for more information. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. @@ -1409,7 +1387,7 @@ QCH_FILE = # The QHP_NAMESPACE tag specifies the namespace to use when generating Qt Help # Project output. For more information please see Qt Help Project / Namespace -# (see: http://doc.qt.io/qt-4.8/qthelpproject.html#namespace). +# (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#namespace). # The default value is: org.doxygen.Project. # This tag requires that the tag GENERATE_QHP is set to YES. @@ -1417,7 +1395,8 @@ QHP_NAMESPACE = org.doxygen.Project # The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating Qt # Help Project output. For more information please see Qt Help Project / Virtual -# Folders (see: http://doc.qt.io/qt-4.8/qthelpproject.html#virtual-folders). +# Folders (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#virtual- +# folders). # The default value is: doc. # This tag requires that the tag GENERATE_QHP is set to YES. @@ -1425,21 +1404,23 @@ QHP_VIRTUAL_FOLDER = doc # If the QHP_CUST_FILTER_NAME tag is set, it specifies the name of a custom # filter to add. For more information please see Qt Help Project / Custom -# Filters (see: http://doc.qt.io/qt-4.8/qthelpproject.html#custom-filters). +# Filters (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom- +# filters). # This tag requires that the tag GENERATE_QHP is set to YES. QHP_CUST_FILTER_NAME = # The QHP_CUST_FILTER_ATTRS tag specifies the list of the attributes of the # custom filter to add. For more information please see Qt Help Project / Custom -# Filters (see: http://doc.qt.io/qt-4.8/qthelpproject.html#custom-filters). +# Filters (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom- +# filters). # This tag requires that the tag GENERATE_QHP is set to YES. QHP_CUST_FILTER_ATTRS = # The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this # project's filter section matches. Qt Help Project / Filter Attributes (see: -# http://doc.qt.io/qt-4.8/qthelpproject.html#filter-attributes). +# http://qt-project.org/doc/qt-4.8/qthelpproject.html#filter-attributes). # This tag requires that the tag GENERATE_QHP is set to YES. QHP_SECT_FILTER_ATTRS = @@ -1532,7 +1513,7 @@ EXT_LINKS_IN_WINDOW = NO FORMULA_FONTSIZE = 10 -# Use the FORMULA_TRANSPARENT tag to determine whether or not the images +# Use the FORMULA_TRANPARENT tag to determine whether or not the images # generated for formulas are transparent PNGs. Transparent PNGs are not # supported properly for IE 6.0, but are supported on all modern browsers. # @@ -1544,7 +1525,7 @@ FORMULA_FONTSIZE = 10 FORMULA_TRANSPARENT = YES # Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see -# https://www.mathjax.org) which uses client side Javascript for the rendering +# http://www.mathjax.org) which uses client side Javascript for the rendering # instead of using pre-rendered bitmaps. Use this if you do not have LaTeX # installed or if you want to formulas look prettier in the HTML output. When # enabled you may also need to install MathJax separately and configure the path @@ -1571,7 +1552,7 @@ MATHJAX_FORMAT = HTML-CSS # MATHJAX_RELPATH should be ../mathjax. The default value points to the MathJax # Content Delivery Network so you can quickly see the result without installing # MathJax. However, it is strongly recommended to install a local copy of -# MathJax from https://www.mathjax.org before deployment. +# MathJax from http://www.mathjax.org before deployment. # The default value is: http://cdn.mathjax.org/mathjax/latest. # This tag requires that the tag USE_MATHJAX is set to YES. @@ -1633,7 +1614,7 @@ SERVER_BASED_SEARCH = NO # # Doxygen ships with an example indexer (doxyindexer) and search engine # (doxysearch.cgi) which are based on the open source search engine library -# Xapian (see: https://xapian.org/). +# Xapian (see: http://xapian.org/). # # See the section "External Indexing and Searching" for details. # The default value is: NO. @@ -1646,7 +1627,7 @@ EXTERNAL_SEARCH = NO # # Doxygen ships with an example indexer (doxyindexer) and search engine # (doxysearch.cgi) which are based on the open source search engine library -# Xapian (see: https://xapian.org/). See the section "External Indexing and +# Xapian (see: http://xapian.org/). See the section "External Indexing and # Searching" for details. # This tag requires that the tag SEARCHENGINE is set to YES. @@ -1833,7 +1814,7 @@ LATEX_SOURCE_CODE = NO # The LATEX_BIB_STYLE tag can be used to specify the style to use for the # bibliography, e.g. plainnat, or ieeetr. See -# https://en.wikipedia.org/wiki/BibTeX and \cite for more info. +# http://en.wikipedia.org/wiki/BibTeX and \cite for more info. # The default value is: plain. # This tag requires that the tag GENERATE_LATEX is set to YES. @@ -2016,9 +1997,9 @@ DOCBOOK_PROGRAMLISTING = NO #--------------------------------------------------------------------------- # If the GENERATE_AUTOGEN_DEF tag is set to YES, doxygen will generate an -# AutoGen Definitions (see http://autogen.sourceforge.net/) file that captures -# the structure of the code including all documentation. Note that this feature -# is still experimental and incomplete at the moment. +# AutoGen Definitions (see http://autogen.sf.net) file that captures the +# structure of the code including all documentation. Note that this feature is +# still experimental and incomplete at the moment. # The default value is: NO. GENERATE_AUTOGEN_DEF = NO @@ -2231,7 +2212,7 @@ HIDE_UNDOC_RELATIONS = YES # http://www.graphviz.org/), a graph visualization toolkit from AT&T and Lucent # Bell Labs. The other options in this section have no effect if this option is # set to NO -# The default value is: NO. +# The default value is: YES. HAVE_DOT = NO @@ -2387,7 +2368,9 @@ DIRECTORY_GRAPH = YES # Note: If you choose svg you need to set HTML_FILE_EXTENSION to xhtml in order # to make the SVG files visible in IE 9+ (other browsers do not have this # requirement). -# Possible values are: png, jpg, gif, svg, png:gd, png:gd:gd, png:cairo, +# Possible values are: png, png:cairo, png:cairo:cairo, png:cairo:gd, png:gd, +# png:gd:gd, jpg, jpg:cairo, jpg:cairo:gd, jpg:gd, jpg:gd:gd, gif, gif:cairo, +# gif:cairo:gd, gif:gd, gif:gd:gd, svg, png:gd, png:gd:gd, png:cairo, # png:cairo:gd, png:cairo:cairo, png:cairo:gdiplus, png:gdiplus and # png:gdiplus:gdiplus. # The default value is: png. diff --git a/include/utl/core/crtp.h b/include/utl/core/crtp.h index fff7b67..37d257a 100644 --- a/include/utl/core/crtp.h +++ b/include/utl/core/crtp.h @@ -1,21 +1,19 @@ /*! - * \file /utl/impl/crtp.h + * \file utl/impl/crtp.h * \brief CRTP idiom support header * - * Copyright (C) 2018 Christos Choutouridis - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Lesser General Public License as - * published by the Free Software Foundation, either version 3 - * of the License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Lesser General Public License for more details. - * - * You should have received a copy of the GNU Lesser General Public License - * along with this program. If not, see . + * \copyright + * Copyright (C) 2018 Christos Choutouridis \n + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License as + * published by the Free Software Foundation, either version 3 + * of the License, or (at your option) any later version.\n + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License for more details.\n + * You should have received a copy of the GNU Lesser General Public License + * along with this program. If not, see . * */ #ifndef __utl_impl_crtp_h__ @@ -25,7 +23,7 @@ /*! * \defgroup crtp CRTP idiom support header - * \ingroup impl + * \ingroup core * * utl supports both CRTP idiom and dynamic polymorphism. By default * CRTP is the preferred way. If the user need virtuals then instead of diff --git a/include/utl/core/impl.h b/include/utl/core/impl.h index 7715154..3c3e1d4 100644 --- a/include/utl/core/impl.h +++ b/include/utl/core/impl.h @@ -1,30 +1,32 @@ /*! - * \file /utl/core/impl.h + * \file utl/core/impl.h * \brief Implementation detail main forward header * - * Copyright (C) 2018 Christos Choutouridis - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Lesser General Public License as - * published by the Free Software Foundation, either version 3 - * of the License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Lesser General Public License for more details. - * - * You should have received a copy of the GNU Lesser General Public License - * along with this program. If not, see . + * \copyright + * Copyright (C) 2018 Christos Choutouridis \n + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License as + * published by the Free Software Foundation, either version 3 + * of the License, or (at your option) any later version.\n + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License for more details.\n + * You should have received a copy of the GNU Lesser General Public License + * along with this program. If not, see . * */ #ifndef __utl_core_impl_h__ #define __utl_core_impl_h__ +//! \defgroup core Core +//! Provide compiler feature support macros, uTL version, +//! global types etc... // FWD include implementation details once #include #include +#include #endif /* __utl_core_impl_h__ */ diff --git a/include/utl/core/types.h b/include/utl/core/types.h index 4bce78f..79010c2 100644 --- a/include/utl/core/types.h +++ b/include/utl/core/types.h @@ -1,23 +1,21 @@ /*! - * \file /utl/core/types.h + * \file utl/core/types.h * \brief Basic type alias support * - * Copyright (C) 2018 Christos Choutouridis - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Lesser General Public License as - * published by the Free Software Foundation, either version 3 - * of the License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Lesser General Public License for more details. - * - * You should have received a copy of the GNU Lesser General Public License - * along with this program. If not, see . - * + * \copyright + * Copyright (C) 2018 Christos Choutouridis \n + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License as + * published by the Free Software Foundation, either version 3 + * of the License, or (at your option) any later version.\n + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License for more details.\n + * You should have received a copy of the GNU Lesser General Public License + * along with this program. If not, see . */ + #ifndef __utl_core_types_h__ #define __utl_core_types_h__ @@ -27,13 +25,15 @@ //#include namespace utl { - //! @{ \name byte and word types + //! \name byte and word types + //! @{ using byte_t = uint8_t; //!< 8 bits wide using word_t = uint16_t; //!< 16 bits wide using dword_t = uint32_t; //!< 32 bits wide //! @} - //! @{ \name size and index + //! \name size and index + //! @{ using size_t = std::size_t; using index_t = size_t; //!< index_t and size_t mend to be interchangeable diff --git a/include/utl/core/version.h b/include/utl/core/version.h index 8df226e..7b70d01 100644 --- a/include/utl/core/version.h +++ b/include/utl/core/version.h @@ -1,46 +1,58 @@ /*! - * \file /utl/core/version.h - * \brief version and cpp version checks + * \file utl/core/version.h + * \brief utl version and cpp version checks * - * Copyright (C) 2018-2019 Christos Choutouridis - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Lesser General Public License as - * published by the Free Software Foundation, either version 3 - * of the License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Lesser General Public License for more details. - * - * You should have received a copy of the GNU Lesser General Public License - * along with this program. If not, see . + * \copyright + * Copyright (C) 2018 Christos Choutouridis \n + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License as + * published by the Free Software Foundation, either version 3 + * of the License, or (at your option) any later version.\n + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License for more details.\n + * You should have received a copy of the GNU Lesser General Public License + * along with this program. If not, see . * */ #ifndef __utl_core_version_h__ #define __utl_core_version_h__ -//!\defgroup version version -//! Definitions of the utl version +//!\addtogroup core +//! @{ + +//! \defgroup version Version +//! Definitions of the utl version and compiler features //!@{ -//! utl version +//! utl version as string #define UTL_VERSION "0.1.0" #define UTL_VERSION_MAJOR 0 #define UTL_VERSION_MINOR 1 #define UTL_VERSION_PATCH 0 + +//! utl version as integer +//! +//! This can be used in the user files to check for uTL versions. +//! The version number is constructed using:\n +//! ver = (Maj*10000 + Min*100 + Patch) #define UTL_VERSION_VALUE ( (UTL_VERSION_MAJOR * 10000) \ + (UTL_VERSION_MINOR * 100) \ + UTL_VERSION_PATCH) -//! C++ versions -#define CXX_VER __cplusplus -#define CXX_VER_STD_11 201103L -#define CXX_VER_STD_14 201402L -#define CXX_VER_STD_17 201703L +//!@} + +//! \name Compiler and feature checks +//! These checks are used inside uTL, but the user is free to use the as well. +//! @{ +#define CXX_VER __cplusplus //!< Current compiler's version +#define CXX_VER_STD_11 201103L //!< C++11 +#define CXX_VER_STD_14 201402L //!< C++14 +#define CXX_VER_STD_17 201703L //!< C++17 -//! Check for variable templates +//! \def CXX_VARIABLE_TEMPLATES +//! Check for variable templates (Non-zero if available) #ifndef CXX_VARIABLE_TEMPLATES #ifdef __cpp_variable_templates #define CXX_VARIABLE_TEMPLATES __cpp_variable_templates @@ -49,7 +61,8 @@ #endif #endif -//! Check concepts +//! \def CXX_CONCEPTS +//! Check for concepts (Non-zero if available) #ifndef CXX_CONCEPTS #ifdef __cpp_concepts #define CXX_CONCEPTS __cpp_concepts @@ -58,7 +71,8 @@ #endif #endif -//! Check for inline variables +//! \def CXX_INLINE_VARIABLES +//! Check for inline variables (Non-zero if available) #ifndef CXX_INLINE_VARIABLES #ifdef __cpp_inline_variables #define CXX_INLINE_VARIABLES __cpp_inline_variables @@ -67,6 +81,8 @@ #endif #endif +//! \def CXX_FOLD_EXPRESSIONS +//! Check for fold expressions (Non-zero if available) #ifndef CXX_FOLD_EXPRESSIONS #ifdef __cpp_fold_expressions #define CXX_FOLD_EXPRESSIONS __cpp_fold_expressions @@ -75,19 +91,23 @@ #endif #endif -/* - * Workaround inspections - */ +//! @} + + +//! \name Workaround inspections +//! @{ + #if defined(__GNUC__) && (__GNUC__ < 5) // https://wg21.link/cwg1558 #define UTL_WORKAROUND_CWG_1558 #endif - //! Base library requirement #if CXX_VER < CXX_VER_STD_14 #error "uTL requires C++14" #endif -//!@} +//! @} + +//! @} #endif /* #ifndef __utl_core_version_h__ */ diff --git a/include/utl/dev/dev_iterators.h b/include/utl/dev/dev_iterators.h index f24cf14..09e64ff 100644 --- a/include/utl/dev/dev_iterators.h +++ b/include/utl/dev/dev_iterators.h @@ -23,6 +23,7 @@ #include #include +#include namespace utl { diff --git a/include/utl/meta/integral.h b/include/utl/meta/basic.h similarity index 65% rename from include/utl/meta/integral.h rename to include/utl/meta/basic.h index efc63a8..8c6e7c2 100644 --- a/include/utl/meta/integral.h +++ b/include/utl/meta/basic.h @@ -1,24 +1,23 @@ /*! - * \file integralconstant.h - * \brief Template meta-programming integral constant + * \file utl/meta/basic.h + * \brief Template meta-programming basic definitions * - * Copyright (C) 2018-2019 Christos Choutouridis + * \copyright + * Copyright (C) 2018 Christos Choutouridis \n + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License as + * published by the Free Software Foundation, either version 3 + * of the License, or (at your option) any later version.\n + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License for more details.\n + * You should have received a copy of the GNU Lesser General Public License + * along with this program. If not, see . * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Lesser General Public License as - * published by the Free Software Foundation, either version 3 - * of the License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Lesser General Public License for more details. - * - * You should have received a copy of the GNU Lesser General Public License - * along with this program. If not, see . */ -#ifndef __utl_meta_integralconstant_h__ -#define __utl_meta_integralconstant_h__ +#ifndef __utl_meta_basic_h__ +#define __utl_meta_basic_h__ #include #include @@ -26,8 +25,8 @@ /*! * \ingroup meta - * \defgroup integral - * integral constant support header + * \defgroup basic Basic + * Basic definitions */ //! @{ @@ -35,30 +34,39 @@ namespace utl { namespace meta { /*! - * Empty type + * meta's empty type + * * utl::meta's nil type is not pure nil. It's a recursive "de-referencable nil. - * Each time someone applies ::type to it, he gets back nil_. This way we can prevent + * Each time someone applies \c \::type to it, he gets back nil_. This way we can prevent * a lot of compilation errors in a wrong meta:: handling. */ struct nil_ { using type = nil_; }; - //! Type alias for \p Tp::type. Used to evaluate/extract return type of metafunctions + //! Type alias for \c Tp::type. Used to evaluate/extract return type of metafunctions template using eval = typename Tp::type; - //! integral_ - //! Integral Constant is a holder class for a compile-time value of an integral type. - //! Every Integral Constant is also a null-ary Metafunction, returning itself. + //! Type alias for \c Tp::type. Used to evaluate/extract return value of metafunctions + template + using eval_t = typename Tp::type; + + //! Type alias for \c Tp::type. Used to evaluate/extract return type of metafunctions + template + using eval_v = typename Tp::value; + + //! + //! integral_ is a holder class for a compile-time value of an integral type. + //! + //! Every Integral Constant is also a null-ary Metafunction, returning itself.\n //! An integral constant object is implicitly convertible to the corresponding //! run-time value of the wrapped integral type - //! @{ template using integral_ = std::integral_constant; - //! @} - //! Wrappers for basic types + + //! \name Wrappers for basic types //! @{ //! bool_ type: integral constant wrapper for bool @@ -123,7 +131,7 @@ namespace meta { //! The last position we can express for indexing using Npos = size_; - //! integer sequence + //! \name integer sequence //! @{ template< class Tp, Tp... Ints > using integer_sequence = std::integer_sequence; @@ -148,4 +156,4 @@ namespace meta { //!@} -#endif /* __utl_meta_integralconstant_h__ */ +#endif /* __utl_meta_basic_h__ */ diff --git a/include/utl/meta/detection.h b/include/utl/meta/detection.h index 305f245..e9f653d 100644 --- a/include/utl/meta/detection.h +++ b/include/utl/meta/detection.h @@ -1,23 +1,21 @@ /*! * \file detection.h - * \brief Detection idiom based on WG21's N4502 [\ref 1] from Walter E. Brown + * \brief Detection idiom based on WG21's \ref N4502 from Walter E. Brown * - * Copyright (C) 2018-2019 Christos Choutouridis + * \copyright + * Copyright (C) 2018 Christos Choutouridis \n + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License as + * published by the Free Software Foundation, either version 3 + * of the License, or (at your option) any later version.\n + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License for more details.\n + * You should have received a copy of the GNU Lesser General Public License + * along with this program. If not, see . * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Lesser General Public License as - * published by the Free Software Foundation, either version 3 - * of the License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Lesser General Public License for more details. - * - * You should have received a copy of the GNU Lesser General Public License - * along with this program. If not, see . - * - * \anchor [1]: www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/n4502.pdf + * \anchor N4502 www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/n4502.pdf */ #ifndef __utl_meta_detection_h__ #define __utl_meta_detection_h__ @@ -37,7 +35,7 @@ namespace utl { namespace meta { /*! - * void_t meta-function that maps a sequence of any types to the type void + * \name void_t implementation */ //! @{ #if defined(UTL_WORKAROUND_CWG_1558) @@ -47,18 +45,18 @@ namespace meta { }; //! void_t type alias template - using void_t = eval>; + using void_t = eval_t>; #else - //! void_ type alias + //! void_ meta-function that maps a sequence of any types to the type void template using void_ = void; - //! void_t type alias + //! void_t meta-function that maps a sequence of any types to the type void template using void_t = void; #endif //! @} /*! * Not a type to use in detected idiom. This type can - * not be constructed, destructed or copied + * not be constructed, destructed or copied. */ struct nat_ { nat_() = delete; @@ -67,9 +65,9 @@ namespace meta { void operator = (nat_ const&) = delete; }; - //! Detector for detection idiom + //! \name Detector for detection idiom //! @{ - namespace detail { + namespace details { template class Op, typename... Args> @@ -89,24 +87,23 @@ namespace meta { template class Op, typename... Args> using detected_or = detector; - } // namespace detail + } // namespace details //! @} /*! - * detection interface + * \name detection interface */ //! @{ /*! * Checks if Op is a valid expression without evaluating it. * - * \tparam Op a meta-callback function to pass Args... - * \tparam Args... types to pass to Op for checking + * \tparam Op a meta-callback function to pass Args... + * \tparam Args... types to pass to Op for checking * \return status of the operation [bool_] * \arg true_ if Op is valid expression * \arg false_ if Op is not valid * - * \example * \code * // archetypal alias for a copy assignment operation * template< class T > using copy_assign_t = decltype( declval() = declval() ); @@ -115,7 +112,7 @@ namespace meta { * \endcode */ template class Op, typename... Args> - using is_detected = typename detail::detector::detected; + using is_detected = typename details::detector::detected; //! Detection predicate template< template class Op, typename... Args> @@ -124,12 +121,12 @@ namespace meta { /*! * Detection tool that evaluates to Op if it's valid and to nat_ if not * - * \param Op metafunction detector - * \param Args... The arguments to pass to \p Op and check if is well formed + * \tparam Op metafunction detector + * \tparam Args... The arguments to pass to \p Op and check if is well formed * \return The result type * \arg Op if is well formed * \arg nat_ if Op is ill formed - * \example + * * \code * template using try_type = typename T::type; // detector * template using try_ppT = decltype (++(std::declval())); // detector @@ -141,20 +138,20 @@ namespace meta { * \endcode */ template class Op, typename... Args> - using detected_t = eval < - detail::detector + using detected_t = eval_t < + details::detector >; /*! * Detection tool that evaluates to Op if it's valid and to \p Default if not * - * \param Default The resulting type if detection fail - * \param Op metafunction detector - * \param Args... The arguments to pass to \p Op and check if is well formed + * \tparam Default The resulting type if detection fail + * \tparam Op metafunction detector + * \tparam Args... The arguments to pass to \p Op and check if is well formed * \return The result type * \arg Op if is well formed * \arg Default if Op is ill formed - * \example + * * \code * template using try_type = typename T::type; // detector * template using try_ppT = decltype (++(std::declval())); // detector @@ -167,21 +164,21 @@ namespace meta { */ template class Op, typename... Args> - using detected_or_t = eval < - detail::detected_or + using detected_or_t = eval_t < + details::detected_or >; /*! * Detection tool that evaluates to true_ if evaluation of Op * is \p Expected and to false_ if not * - * \param Expected The expected resulting type if detection succeed - * \param Op metafunction detector - * \param Args... The arguments to pass to \p Op and check if is well formed + * \tparam Expected The expected resulting type if detection succeed + * \tparam Op metafunction detector + * \tparam Args... The arguments to pass to \p Op and check if is well formed * \return The result type * \arg true_ if Op is well formed and evaluate to Expected * \arg false_ Any other case - * \example + * * \code * template using try_type = typename T::type; // detector * template using try_ppT = decltype (++(std::declval())); // detector @@ -194,7 +191,7 @@ namespace meta { */ template class Op, typename... Args > - using is_detected_exact = eval < + using is_detected_exact = eval_t < same_> >; @@ -207,13 +204,13 @@ namespace meta { * Detection tool that evaluates to true_ if evaluation of Op is convertible * to \p To and to false_ if not * - * \param To The to convert to if detection succeed - * \param Op metafunction detector - * \param Args... The arguments to pass to \p Op and check if is well formed + * \tparam To The to convert to if detection succeed + * \tparam Op metafunction detector + * \tparam Args... The arguments to pass to \p Op and check if is well formed * \return The result type * \arg true_ if Op is well formed and convertible to To * \arg false_ Any other case - * \example + * * \code * template using try_type = typename T::type; // detector * template using try_ppT = decltype (++(std::declval())); // detector @@ -226,7 +223,7 @@ namespace meta { */ template class Op, typename... Args > - using is_detected_convertible = eval < + using is_detected_convertible = eval_t < std::is_convertible< detected_t, To > >; diff --git a/include/utl/meta/invoke.h b/include/utl/meta/invoke.h index 5c58f27..38711e4 100644 --- a/include/utl/meta/invoke.h +++ b/include/utl/meta/invoke.h @@ -2,54 +2,47 @@ * \file invoke.h * \brief Template meta-programming utilities for callables * - * Copyright (C) 2018 Christos Choutouridis - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Lesser General Public License as - * published by the Free Software Foundation, either version 3 - * of the License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Lesser General Public License for more detail. - * - * You should have received a copy of the GNU Lesser General Public License - * along with this program. If not, see . + * \copyright + * Copyright (C) 2018 Christos Choutouridis \n + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License as + * published by the Free Software Foundation, either version 3 + * of the License, or (at your option) any later version.\n + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License for more details.\n + * You should have received a copy of the GNU Lesser General Public License + * along with this program. If not, see . */ #ifndef __utl_meta_invoke_h__ #define __utl_meta_invoke_h__ #include -#include +#include #include #include /*! * \ingroup meta * \defgroup invoke + * A meta-programming invoke() analogous. A \c meta::invocable shall contain a nested + * template type named \b apply which is bind to actual invocable meta-function. * + * - We can use \c wrap<> or even better \c quote<> in order to wrap a metafunction to a type (metafunction class) + * - We can pass these wrapped types to other metafunctions + * - We can \c invoke<> the inner \c apply from a wrapped metafunction class. */ //! @{ namespace utl { namespace meta{ /*! - * \name meta::invoke - * - * A meta-programming invoke() analogous. A \c meta::invocable shall contain a nested - * template type named \b apply which is bind to actual invocable meta-function. - * - * - We can use \c wrap<> or even better \c quote<> in order to wrap a metafunction to a type (metafunction class) - * - We can pass these wrapped types to other metafunctions - * - We can \c invoke<> the inner \c apply from a wrapped metafunction class. + * \name identity implementation */ //! @{ - /*! - * identity, identity_t. - */ - //! @{ + //! Identity is a metafunction always return the input type template struct identity { #if defined (UTL_WORKAROUND_CWG_1558) @@ -69,7 +62,7 @@ namespace meta{ //! @} /*! - * invoke, invoke_t + * name invoke, invoke_t */ //! @{ /*! @@ -88,7 +81,7 @@ namespace meta{ using invoke_t = eval< invoke >; //! @} - //! wrap + //! \name wrap //! @{ /*! * wrap is a higher-order primitive that wraps an n-ary Metafunction @@ -111,9 +104,9 @@ namespace meta{ }; //! @} - //! Is applicable trait + //! \name Is applicable trait //! @{ - namespace detail { + namespace details { template class F, typename... T> struct is_applicable_ { @@ -159,26 +152,25 @@ namespace meta{ //! check if we can instantiate \p F with parameters \p T template class F, typename... T> using is_applicable_t = eval< - detail::is_applicable_ + details::is_applicable_ >; //! check if we can invoke \p Q with parameters \p T template using is_applicable_qt = eval < - detail::is_applicable_q_ + details::is_applicable_q_ >; //! check if we can instantiate \p F with parameters \p Is of type \p T template class F, T... Is> using is_applicable_it = eval< - detail::is_applicable_i_ + details::is_applicable_i_ >; //! @} - //! defer + //! \name defer //! @{ - namespace detail { - //! @{ + namespace details { template class F, typename... Ts> struct defer_ { using type = F; @@ -194,34 +186,33 @@ namespace meta{ //! template class F, typename... Ts> //! using defer_ = F; //! - //! The use of struct here is due to Core issue 1430 [\ref link1 1] and is used - //! as suggested by Roy Crihfield in [\ref link2 2]. + //! The use of struct here is due to Core issue 1430 \ref link1 and is used + //! as suggested by Roy Crihfield in \ref link2. //! In short, this is due to language's inability to expand Ts... into //! a fixed parameter list of an alias template. //! - //! \anchor link1 [1]: https://wg21.link/cwg1430 - //! \anchor link2 [2]: https://gcc.gnu.org/bugzilla/show_bug.cgi?id=59498 - //! @} + //! \anchor link1 https://wg21.link/cwg1430 + //! \anchor link2 https://gcc.gnu.org/bugzilla/show_bug.cgi?id=59498 } //! defer alias template for F template class F, class... Ts> using defer = if_< - detail::is_applicable_, - detail::defer_, + details::is_applicable_, + details::defer_, nil_ //!< Safe, nil_ is dereferencable >; //! defer_i alias template for F template class F, T... Is> using defer_i = if_ < - detail::is_applicable_i_, - detail::defer_i_, + details::is_applicable_i_, + details::defer_i_, nil_ //!< Safe, nil_ is dereferencable >; //! @} - //! quote + //! \name quote //! @{ /*! * quote deferred is a higher-order primitive that wraps an n-ary Metafunction @@ -249,9 +240,9 @@ namespace meta{ }; //! @} - //! compose + //! \name compose //! @{ - namespace detail { + namespace details { template