Skip to content

Latest commit

 

History

History
178 lines (124 loc) · 7.28 KB

README.md

File metadata and controls

178 lines (124 loc) · 7.28 KB
Raw
GitHub Workflow Status (with event) GitHub Release Date - Published_At GitHub Github

Extra Templated Library for modern C++ development

Table of Contents

Etl

Etl contains classes that rely on C++ >= 17 to solve common programming problems that the language does not technically have built in support for. This library has zero external dependencies and was born out of my frustration at work and personal projects, as I constantly had to come up with custom solutions to fix the common problems I ran into, I finally put them all together in this BSD-Clause-3 licensed single header templated library. Hopefully they solve some of your problems, and speed up your development.

What does this library contain?

Please checkout the unit-tests and example code for use cases and implementations, also don't be afraid to read the source code, its a single header file, at roughly 500 lines of code. A nice and easy read with descriptive comments.

  1. etl::Result<T, E>

  • Don't like or don't want to use C++'s exception handling paradigm for errors? Cool, then you don't have to, the Result<OkType, ErrType> attempts to be as close to the Rust langauges implementation as possible, and may be just what your looking for to ditch those try/catch error handling blocks.

  • One current catch with the Result<T, E> type is if you have a move only type you will need to hi-jack the etl namespace and create a template specialization for it, but don't worry it's easy. I have provided an example here which you can copy and paste, (Just replace the name of the the class with your own).

  1. etl::EnumerationIterator<IteratorName, IteratorBegin, IteratorEnd>
  • Want to use modern C++'s ranged for loops to iterate over an enum safely? There is a templated class for that.
  1. etl::TaggedFundamentalType<Tag, FundamentalType>
  • Do you have many parameters to a function or constructor of the same type contiguously (common when representing geometrical objects such as a Rectangle)? This can result in programmer error by accidently passing in values for the wrong parameter, a common solution is to tag your types. Etl makes the process generic, quick and easy.
  1. etl::Error

  • A basic error class that supports source code location in your errors, using the function, line, and file macros. This makes it much easier to provide usefull runtime error information as it captures the above information through use of a custom SourceCodeLocation macro which the Error class supports, and can easily be returned in the afore-mentioned Result<T, E> object for more Rust like behaviour.

  • etl::Error implements etl::IError, so if you want to make your own custom errors that play nicely with Result<T, E>, as well as return a polymorphic error like so auto someFunction(std::string const &param) -> etl::Result<std::int32_t, std::shared_ptr<etl::IError>> well you can do that.

Integration

Copy the single header file into your project.

Or you can download the etl.hpp file from the latest Releases

Install globally on your system

Will install the single header file and Cmake configuration modules, which find_package can use.

make install

# Example output
-- Install configuration: "Release"
-- Up-to-date: /usr/local/include
-- Up-to-date: /usr/local/include/etl.hpp
-- Installing: /usr/local/share/pkgconfig/etl.pc
-- Installing: /usr/local/share/cmake/etl/etlConfigVersion.cmake
-- Installing: /usr/local/share/cmake/etl/etlConfig.cmake
-- Installing: /usr/local/share/cmake/etl/etlTargets.cmake

To remove on linux (relies on xargs)

make uninstall

Cmake

Find Package

find_package(etl 0.7.0 REQUIRED)

# Your Application linking cmake code
target_link_libraries(
  your_awesome_project
  PRIVATE etl::etl)

CPM (The package manager way)

Please check out how to use CPM it is dead simple.

cpmaddpackage(
  NAME
  etl
  GITHUB_REPOSITORY
  thebashpotato/extra-template-library
  VERSION
  0.7.0)

if(etl_ADDED)
  message(STATUS "Extra Template Library added")
  add_library(etl::etl INTERFACE IMPORTED)
  target_include_directories(etl::etl INTERFACE ${etl_SOURCE_DIR}/etl/include)
endif()


# Your Application linking cmake code
target_link_libraries(
  your_awesome_project
  PRIVATE etl::etl)

Package Config

Cmake

find_package(PkgConfig REQUIRED IMPORTED_TARGET GLOBAL)
pkg_check_modules(Etl REQUIRED etl)

# Your Application linking cmake code
target_link_libraries(your_awesome_project PUBLIC PkgConfig::Etl)
target_include_directories(your_awesome_project PUBLIC ${Etl_INCLUDE_DIRS})

Bare Makefile

If you are using bare Makefiles, you can use pkg-config to generate the include flags that point to where the library is installed.

pkg-config etl --clfags

Usage

Please see the unit tests for bite size examples for each class. Please see for an example blackjack program utilizing etl to solve real world problems. Please see for an example for a Result<T, E> move only class template specialization.

#include <etl.hpp>

Maintainers

@thebashpotato

Contributing

Do you have an idea for something usefull that other C++ programmers would need? Please open an issue, or a Pull Request.

Small note: If editing the README, please conform to the standard-readme specification.

License

BSD-Clause-3 © 2024 Matt Williams