Updated Examples and Recipes (markdown)

Examples-and-Recipes.md

@@ -29,6 +29,7 @@ This page contains examples and recipes contributed by community members. Feel f
 - [Print out a compact calendar for the year](#calendar)
 - [Parsing unambiguous date time inside daylight transition](#parse_daylight_transition)
 - [`microfortnights`?!  Are you serious?](#microfortnights)
+- [Find UNIX download folder thanks to xdg-user-dir](#set_install_with_xdg_user_dir)
 
 ***
 
@@ -1656,6 +1657,65 @@ Now you can just blindly add `microfortnights{35}` to your year/month/day hh::mi
 
 If this library can do this so easily with something as crazy as `microfortnights`, it can handle your crazy time problem.
 
+
+<a name="set_install_with_xdg_user_dir"></a>
+### Find UNIX download folder thanks to xdg-user-dir
+(by [Coin²](https://github.com/coin-au-carre))
+
+The library uses the path `~/Downloads` by default. What if you use a different path for your download directory such as `~/Téléchargements` or `~/Завантаження` and you want your program to automatically find this path ? A solution is to use [xdg_user_dir](https://freedesktop.org/wiki/Software/xdg-user-dirs/). The following code shows you how you can do it : 
+
+```
+#include "date.h"
+#include "tz.h"
+
+#include <regex>
+#include <iostream>
+
+// Execute command, use a pipe and get the output of it (we cannot grab the output with std::system)
+std::string exec_and_get_output(const char* cmd) 
+{
+    std::array<char, 128> buffer;
+    std::string output;
+    FILE *pipe(popen(cmd, "r"));
+    if (!pipe) 
+        throw std::runtime_error("Cannot execute command");
+    while (!feof(pipe)) 
+    {
+        if (fgets(buffer.data(), 128, pipe) != nullptr)
+            output += buffer.data();
+    }
+    pclose(pipe);
+    return output;
+}
+
+std::string get_xdg_download_folder(const std::string& suffix = "tzdata_alt") {
+    std::string download_folder = "~/Downloads";  // common download folder by default
+    std::string xdg_command = "xdg-user-dir DOWNLOAD";
+    std::string xdg_download_folder = exec_and_get_output(xdg_command.c_str());
+    xdg_download_folder.erase // remove unnecessary new lines
+    (
+        std::remove(xdg_download_folder.begin(), xdg_download_folder.end(), '\n'), 
+        xdg_download_folder.end()
+    ); 
+    // Verify that output from command is a folder so we can use it
+    if (std::regex_match(xdg_download_folder, std::regex("^(/[^/ ]*)+/?$"))) 
+    {
+        download_folder = xdg_download_folder; 
+    }
+    return download_folder + '/' + suffix;
+}
+
+int main() 
+{
+    auto download_folder = get_xdg_download_folder();
+    date::set_install(download_folder);
+
+    // Your code which uses tz
+}
+```
+
+Do not forget to set `-DAUTO_DOWNLOAD=1` so that you download the tzdata in the first use.
+
 ***
 
 ![CC BY Logo](http://mirrors.creativecommons.org/presskit/buttons/80x15/svg/by.svg) _This work is licensed under a [Creative Commons Attribution 4.0 International License](http://creativecommons.org/licenses/by/4.0/)._