From 090e68e06dc3f20388237519ed6c5c7d36b58da2 Mon Sep 17 00:00:00 2001 From: Nick Le Large Date: Fri, 29 Nov 2024 10:19:26 +0100 Subject: [PATCH 1/9] Fix title casing --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f19eaaa..c53bc5e 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# UTIL CACHING +# util_caching This packages provides a utility class to simplify caching of arbitrary values. From e8759ce1b5df7c4ad79a4fc70802d7a9b4ab8eec Mon Sep 17 00:00:00 2001 From: Nick Le Large Date: Fri, 29 Nov 2024 10:19:46 +0100 Subject: [PATCH 2/9] Add some shield.io badges --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index c53bc5e..e76b9c3 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,9 @@ # util_caching This packages provides a utility class to simplify caching of arbitrary values. +[![Latest Release](https://img.shields.io/github/v/release/KIT-MRT/util_caching?color=green)](https://github.com/KIT-MRT/util_caching/releases) +[![License](https://img.shields.io/github/license/KIT-MRT/util_caching)](./LICENSE) +[![Unit Test Status](https://img.shields.io/github/actions/workflow/status/KIT-MRT/util_caching/run-unit-tests.yaml?branch=main&label=tests)](https://github.com/KIT-MRT/util_caching/actions/workflows/run-unit-tests.yaml?query=branch%3Amain) ## Usage From 72811d42b339040a266c8454b22975ea36b4b5e7 Mon Sep 17 00:00:00 2001 From: Nick Le Large Date: Fri, 29 Nov 2024 10:19:59 +0100 Subject: [PATCH 3/9] Add a list of features --- README.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index e76b9c3..8f1e408 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,28 @@ # util_caching -This packages provides a utility class to simplify caching of arbitrary values. [![Latest Release](https://img.shields.io/github/v/release/KIT-MRT/util_caching?color=green)](https://github.com/KIT-MRT/util_caching/releases) [![License](https://img.shields.io/github/license/KIT-MRT/util_caching)](./LICENSE) [![Unit Test Status](https://img.shields.io/github/actions/workflow/status/KIT-MRT/util_caching/run-unit-tests.yaml?branch=main&label=tests)](https://github.com/KIT-MRT/util_caching/actions/workflows/run-unit-tests.yaml?query=branch%3Amain) +**Cache arbitrary key-value pairs with this simple utility class.** + +- ๐Ÿท๏ธ **Flexible Key and Value Types** + Cache any data type with customizable key types. +- ๐ŸŽฏ **Exact or Approximate Matching** + Retrieve cached values with precise or tolerance-based policies. +- ๐Ÿ•‘ **Time-Based Keys** + Perfect for applications needing time-point based caching. +- โš™ **Configurable Matching Policies** + Define individual policies for value retrieval. +- ๐Ÿงช **Tested and Reliable** + Includes unit tests to ensure robustness in real-world applications. +- ๐Ÿ“ฆ **Header-Only** + Easy integration into your project โ€“ just include the headers! +- ๐Ÿ“œ **Permissive License** + Published under the MIT license to maximize your project's flexibility. + + ## Usage ### Caching with number From 8df07479c8a4dcdf8a7f9c04f919c17b200e6ebd Mon Sep 17 00:00:00 2001 From: Nick Le Large Date: Fri, 29 Nov 2024 10:20:30 +0100 Subject: [PATCH 4/9] Move the usage block into spoilers --- README.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 8f1e408..e09f1f0 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,11 @@ ## Usage -### Caching with number +To get you started, here are some examples of how to use this library. +Make sure to check out the unit tests for more detailed examples. + +
+Caching with number You could cache a value with arbitrary type (e.g. double) giving number (e.g. double) as key, first value type is for the key. @@ -64,8 +68,10 @@ Of course the value can not be recalled when the keys differ more than the thres // over threshold EXPECT_FALSE(cacheByNumber.cached(key3, approximateNumberPolicy)); ``` +
-### Caching with time point +
+Caching with time point A more practical usage is to cache values by giving time point as key: @@ -94,7 +100,7 @@ or by specifying one comparison policy and threshold (100ms for example), and re EXPECT_DOUBLE_EQ(cacheByTime.cached(time2, approximateTimePolicy).value(), 1.); ``` -More usage please check the unittest. +
## Python bindings From 3f5d0a6e6ae07de8bf42c1ee3ed5b0130badd2f2 Mon Sep 17 00:00:00 2001 From: Nick Le Large Date: Fri, 29 Nov 2024 10:20:53 +0100 Subject: [PATCH 5/9] Move the installation and development section into spoilers --- README.md | 29 +++++++++++++++++++++++------ 1 file changed, 23 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index e09f1f0..5ce77ce 100644 --- a/README.md +++ b/README.md @@ -127,7 +127,8 @@ We re-implemented all of the C++ unit tests in Python, so take a closer look at ## Installation -### Using Debian package (recommended) +
+Using Debian package (recommended) We provide a Debian package for easy installation on Debian-based distributions. Download the [latest `.deb` package](https://github.com/KIT-MRT/util_caching/releases/latest/download/libutil-caching-dev.deb) and install it with `dpkg`: @@ -136,7 +137,10 @@ Download the [latest `.deb` package](https://github.com/KIT-MRT/util_caching/rel sudo dpkg -i libutil-caching-dev.deb ``` -### Using Docker image +
+ +
+Using Docker image We provide a [`Dockerfile`](./Dockerfile) with the library already installed globally. @@ -155,8 +159,10 @@ So, it can be easily loaded with CMake: find_package(util_caching REQUIRED) ``` +
-### Building from source using CMake +
+Building from source using CMake First make sure all dependencies are installed: - [Googletest](https://github.com/google/googletest) (optional, if you want to build unit tests) @@ -174,10 +180,13 @@ cmake --build . sudo cmake --install . ``` +
+ ## Development -### Using Docker image +
+Using Docker image Follow the steps above to setup the Docker image. Then, run the development image. @@ -189,8 +198,11 @@ docker compose run --rm --build util_caching_devel This mounts the source into the container's `/home/blinky/util_caching` folder. There, you can edit the source code, compile and run the tests etc. +
+ -### Compiling unit tests using CMake +
+Compiling unit tests using CMake In order to compile with tests define `BUILD_TESTS=true` ```bash @@ -206,8 +218,11 @@ Run all unit tests: cmake --build . --target test ``` +
+ -### Using ROS 1 and catkin +
+Using ROS 1 and catkin The [`demo/Dockerfile_ros`](./demo/Dockerfile_ros) shows that how util_caching can be used in a catkin project (it uses CMake under the hood anyways): @@ -217,3 +232,5 @@ docker compose -f demo/docker-compose.ros.yaml run --rm util_caching_ros ``` See [demo/README.md](demo/README.md) for how to run the demo, showcasing the use of `util_caching` in a ROS node. + +
From 4c7f66d7fc2340f90ac2279f13c501b8dcddb56f Mon Sep 17 00:00:00 2001 From: Nick Le Large Date: Fri, 29 Nov 2024 10:24:38 +0100 Subject: [PATCH 6/9] Fix install path --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5ce77ce..378e3f0 100644 --- a/README.md +++ b/README.md @@ -152,7 +152,7 @@ docker compose build docker compose run --rm util_caching ``` -The library is installed in the Docker image under `/usr/local/include/util_caching/` and `/usr/local/lib/cmake/util_caching/`. +The library is installed in the Docker image under `/usr/include/util_caching/` and `/usr/lib/cmake/util_caching/`. So, it can be easily loaded with CMake: ```cmake From edecee6f452c41f342362a447405e690d52330a6 Mon Sep 17 00:00:00 2001 From: Nick Le Large Date: Fri, 29 Nov 2024 10:25:40 +0100 Subject: [PATCH 7/9] Small rewording in build-from-source section --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index 378e3f0..8f4a836 100644 --- a/README.md +++ b/README.md @@ -188,8 +188,7 @@ sudo cmake --install .
Using Docker image -Follow the steps above to setup the Docker image. -Then, run the development image. +To start a development container, run: ```bash docker compose run --rm --build util_caching_devel From 4e5edc4d1c7b9da613a5e2c8d1f43f7d120f923f Mon Sep 17 00:00:00 2001 From: Nick Le Large Date: Fri, 6 Dec 2024 11:17:01 +0100 Subject: [PATCH 8/9] Correct install path in docker install instructions --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8f4a836..2e816d3 100644 --- a/README.md +++ b/README.md @@ -152,7 +152,7 @@ docker compose build docker compose run --rm util_caching ``` -The library is installed in the Docker image under `/usr/include/util_caching/` and `/usr/lib/cmake/util_caching/`. +The library is installed in the Docker image under `/usr/local/include/util_caching/` and `/usr/local/lib/cmake/util_caching/`. So, it can be easily loaded with CMake: ```cmake From 636b89d89d15f40e4e9afd708e9ec2e7a6ea67ac Mon Sep 17 00:00:00 2001 From: Nick Le Large Date: Fri, 6 Dec 2024 11:58:30 +0100 Subject: [PATCH 9/9] Integrate python binding section into updated document flow --- README.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 2e816d3..3516e9f 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,8 @@ Perfect for applications needing time-point based caching. - โš™ **Configurable Matching Policies** Define individual policies for value retrieval. +- ๐Ÿ **Python Bindings** + Seamlessly use the library in Python with pybind11 bindings. - ๐Ÿงช **Tested and Reliable** Includes unit tests to ensure robustness in real-world applications. - ๐Ÿ“ฆ **Header-Only** @@ -102,7 +104,8 @@ or by specifying one comparison policy and threshold (100ms for example), and re
-## Python bindings +
+Using the Python bindings The library can be used in Python via pybind11 bindings. Since `util_caching` is a templated C++ library, @@ -124,6 +127,8 @@ cache.cache(1.0, 2.0) ``` We re-implemented all of the C++ unit tests in Python, so take a closer look at those for more advanced usage examples. +
+ ## Installation