|    |
  __|   __|  |   |  __|  |
 (     (     |   |  |    |
\___| \___| \__,_| \__| _|

   ccutl Core Utilities
          v0.3.2

About

ccutl is a C++ utilities library focused on flexibility and expressibility.

This is a standalone-header-only library; each header may be included independently.

Development will follow these guidelines:

• Limit API verbosity while maintaining clarity and specificity
• Enable compile-time abstractions wherever possible
• Maximally constrain templates to prevent runtime errors

Essentially, ccutl aims to decrease development time without sacrificing runtime performance.

Migration Notice

Many features have changed since 0.2.1. Please view the CHANGELOG before updating.

Requirements

• C++20 (developed using the GNU ISO C++ library v10.2.0)

Setup

Include the include/ directory or directly copy any of the headers contained within it.

All features are pasted into include/ctl/ccutl.h.
Directly copying this file is the easiest way to use the library.

wget https://raw.githubusercontent.com/jpcx/ccutl/master/include/ctl/ccutl.h

As a CMake interface library (target ccutl):

• use add_subdirectory or FetchContent
• use the CMake install target to install the interface

note:
Preprocessor version checks are provided for each feature. Multiple versions of ccutl may be used in a single translation unit, but only if the individual feature dependencies do not overlap.

Usage

All features are namespaced under ctl::; #define CCUTL_NAMESPACE to modify.

Synopsis

note: each include/ header is independent; use the raw links for direct download

Feature	About	Links
ccutl.arg	returns the passed arg by index, preserving reference qualifier	[?] [raw]
ccutl.different	describes a set of types with at least one variation	[?] [raw]
ccutl.exists	defines templates that are specializable by Ts...	[?] [raw]
ccutl.exists_concept	creates a concept for specialization validity	[?] [raw]
ccutl.found	checks if a value is found within a range	[?] [raw]
ccutl.found_if	checks if a predicate is true for any value in a range	[?] [raw]
ccutl.fwd	shorthand for std::forward	[?] [raw]
ccutl.highest	expands to the highest value of a given arithmetic type	[?] [raw]
ccutl.icmp	performs a three-way comparison of two integrals of any sign	[?] [raw]
ccutl.lowest	expands to the lowest value of a given arithmetic type	[?] [raw]
ccutl.mv	shorthand for std::move	[?] [raw]
ccutl.rmcv	shorthand for std::remove_cv_t	[?] [raw]
ccutl.rmcvref	shorthand for std::remove_cvref_t	[?] [raw]
ccutl.rmref	shorthand for std::remove_reference_t	[?] [raw]
ccutl.same	describes a set of types with no variation	[?] [raw]
ccutl.streq	equality comparison of stringlike objects	[?] [raw]
ccutl.targ	represents the passed type-template-arg by index	[?] [raw]
ccutl.type_pack	A transformable template type arg container	[?] [raw]
ccutl.typeof	defines types that are template<class...> specializations	[?] [raw]
ccutl.typeof_concept	creates a template spec-detection concept	[?] [raw]
ccutl.value_pack	A transformable template nontype arg container	[?] [raw]

Examples

#include <array>
#include <iostream>
#include <vector>

#include <ctl/typeof.h>
#include <ctl/typeof_concept.h>

// use the provided `typeof` concept that defines `<class...>` specializations
template <ctl::typeof<std::vector> T>
void print_size(T &&r) {
  std::cout << "[std::vector]: size " << v.size() << '\n'; 
}

// creates a concept `typesize_typeof` that defines `<class, size_t>` specializations
CTL_TYPEOF_CONCEPT(typesize_typeof, (class T, size_t N), (T, N));

template <typesize_typeof<std::array> T>
void print_size(T &&v) {
  std::cout << "[std::array]: size " << v.size() << '\n'; 
}

template <typesize_typeof<std::span> T>
void print_size(T &&v) {
  std::cout << "[std::span]: size " << v.size() << '\n'; 
}

#include <ctl/exists.h>

template <template <class...> class Template>
requires ctl::exists<Template, int>
using specialize_with_int = Template<int>;

#include <utility>

#include <ctl/type_pack.h>

using intpair = ctl::type_pack<>       // type_pack<>
                   ::push_back<int>    // type_pack<int>
                   ::push_front<int>   // type_pack<int, int>
                   ::push_front<float> // type_pack<float, int, int>
                   ::slice<1>          // type_pack<int, int>
                   ::to<std::pair>;    // std::pair<int, int>

Testing

All API features are tested using jpcx/cctest [embedded]

Run make test to test on your system.

note: Testing is performed on post-buildsystem preprocessed headers

Contributing

Contribution is welcome! Please make a pull request. C++ is an extremely versatile language; I'd like to make it even more so! If you have any suggestions, please let me know at m@jpcx.dev or file a bug report. Make sure to update the submodules and run npm i -d in the bs directory in order to begin development.

For general development contributions, read the guide below:

• Any .h files created in the src/ctl directory should work with the existing build system.
• Place detail files in the src/ctl/detail directory.
  • These files are not built as standalone units; they are only included if depended on
• #pragma once must be used for source files due to version guards
• Each feature must directly or indirectly include src/ctl/detail/config.h
• src include directories are -I. ,-Iinclude, and one for each libs/ library
  • This is for additional error checking, but the downside is that make must be called to see the changes reflected.
• All headers must have the same license text structure directly underneath the include guard
• Embedded libraries are allowed; place them in libs/ and add the appropriate -I statement to the Makefile
  • Embedded libraries must be header-only
• Each file in src/ must have a complementary test in test/src/.

Documentation

Project documentation is generated by Doxygen and is hosted by GitHub Pages.

License

Copyright (C) 2020, 2021 Justin Collier

  This program is free software: you can redistribute it and/or modify
  it under the terms of the GNU 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 internalied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.