{"id":3126,"date":"2018-08-30T19:45:12","date_gmt":"2018-08-30T17:45:12","guid":{"rendered":"https:\/\/mariusbancila.ro\/blog\/?p=3126"},"modified":"2018-08-30T13:27:12","modified_gmt":"2018-08-30T11:27:12","slug":"croncpp-a-cpp-library-for-cron-expressions","status":"publish","type":"post","link":"https:\/\/mariusbancila.ro\/blog\/2018\/08\/30\/croncpp-a-cpp-library-for-cron-expressions\/","title":{"rendered":"croncpp – a C++ library for CRON expressions"},"content":{"rendered":"

A CRON expression is a string composed of six fields (in some implementation seven), separated by a whites space, representing a time schedule. CRON expressions are used in various job schedulers (such as the Linux job scheduler, the Quartz scheduler, Azure scheduler for functions, etc.). Recently, I have written a C++ library for parsing such expressions and determining the next occurrence of the scheduled time. The library is called croncpp<\/strong>. It is written in C++17, is header-only, open-source and cross-platform, and can be found on GitHub<\/a>.<\/p>\n

<\/p>\n

CRON expressions<\/h3>\n

The general form of a CRON expression is the following (with the\u00a0years<\/code>\u00a0being optional):<\/p>\n

<seconds> <minutes> <hours> <days of month> <months> <days of week> <years><\/pre>\n
The following values are allowed for these fields:<\/p>\n\n\n\n\n\n\n\n\n\n\n\n
Field<\/th>\nRequired<\/th>\nAllowed value *<\/th>\nAllowed value (alternative 1) **<\/th>\nAllowed value (alternative 2) ***<\/th>\nAllowed special characters<\/th>\n<\/tr>\n<\/thead>\n
seconds<\/td>\nyes<\/td>\n0-59<\/td>\n0-59<\/td>\n0-59<\/td>\n*<\/tt>\u00a0,<\/tt>\u00a0-<\/tt><\/td>\n<\/tr>\n
minutes<\/td>\nyes<\/td>\n0-59<\/td>\n0-59<\/td>\n0-59<\/td>\n*<\/tt>\u00a0,<\/tt>\u00a0-<\/tt><\/td>\n<\/tr>\n
hours<\/td>\nyes<\/td>\n0-23<\/td>\n0-23<\/td>\n0-23<\/td>\n*<\/tt>\u00a0,<\/tt>\u00a0-<\/tt><\/td>\n<\/tr>\n
days of month<\/td>\n1-31<\/td>\n1-31<\/td>\n1-31<\/td>\n1-31<\/td>\n*<\/tt>\u00a0,<\/tt>\u00a0-<\/tt>\u00a0?<\/tt>\u00a0L<\/tt>\u00a0W<\/tt><\/td>\n<\/tr>\n
months<\/td>\nyes<\/td>\n1-12<\/td>\n0-11<\/td>\n1-12<\/td>\n*<\/tt>\u00a0,<\/tt>\u00a0-<\/tt><\/td>\n<\/tr>\n
days of week<\/td>\nyes<\/td>\n0-6<\/td>\n1-7<\/td>\n1-7<\/td>\n*<\/tt>\u00a0,<\/tt>\u00a0-<\/tt>\u00a0?<\/tt>\u00a0L<\/tt>\u00a0#<\/tt><\/td>\n<\/tr>\n
years<\/td>\nno<\/td>\n1970-2099<\/td>\n1970-2099<\/td>\n1970-2099<\/td>\n*<\/tt>\u00a0,<\/tt>\u00a0-<\/tt><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
* – As described on Wikipedia\u00a0Cron<\/a><\/p>\n
** – As described on Oracle\u00a0Role Manager Integration Guide – A Cron Expressions<\/a><\/p>\n
*** – As described for the Quartz scheduler\u00a0CronTrigger Tutorial<\/a><\/p>\n
The special characters have the following meaning:<\/p>\n\n\n\n\n\n\n\n\n\n\n\n\n
Special character<\/th>\nMeaning<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
*<\/tt><\/td>\nall values<\/td>\nselects all values within a field<\/td>\n<\/tr>\n
?<\/tt><\/td>\nno specific value<\/td>\nspecify one field and leave the other unspecified<\/td>\n<\/tr>\n
-<\/tt><\/td>\nrange<\/td>\nspecify ranges<\/td>\n<\/tr>\n
,<\/tt><\/td>\ncomma<\/td>\nspecify additional values<\/td>\n<\/tr>\n
\/<\/tt><\/td>\nslash<\/td>\nspeficy increments<\/td>\n<\/tr>\n
L<\/tt><\/td>\nlast<\/td>\nlast day of the month or last day of the week<\/td>\n<\/tr>\n
W<\/tt><\/td>\nweekday<\/td>\nthe weekday nearest to the given day<\/td>\n<\/tr>\n
#<\/tt><\/td>\nnth<\/td>\nspecify the Nth day of the month<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
Examples:<\/p>\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
CRON<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
* * * * * *<\/td>\nEvery second<\/td>\n<\/tr>\n
*\/5 * * * * ?<\/td>\nEvery 5 seconds<\/td>\n<\/tr>\n
0 *\/5 *\/2 * * ?<\/td>\nEvery 5 minutes, every 2 hours<\/td>\n<\/tr>\n
0 *\/2 *\/2 ? *\/2 *\/2<\/td>\nEvery 2 minutes, every 2 hours, every 2 days of the week, every 2 months<\/td>\n<\/tr>\n
0 15 10 * * ? *<\/td>\n10:15 AM every day<\/td>\n<\/tr>\n
0 0\/5 14 * * ?<\/td>\nEvery 5 minutes starting at 2 PM and ending at 2:55 PM, every day<\/td>\n<\/tr>\n
0 10,44 14 ? 3 WED<\/td>\n2:10 PM and at 2:44 PM every Wednesday of March<\/td>\n<\/tr>\n
0 15 10 ? * MON-FRI<\/td>\n10:15 AM every Monday, Tuesday, Wednesday, Thursday and Friday<\/td>\n<\/tr>\n
0 15 10 L * ?<\/td>\n10:15 AM on the last day of every month<\/td>\n<\/tr>\n
0 0 12 1\/5 * ?<\/td>\n12 PM every 5 days every month, starting on the first day of the month<\/td>\n<\/tr>\n
0 11 11 11 11 ?<\/td>\nEvery November 11th at 11:11 AM<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
croncpp library<\/h3>\n
There are two main functionalities provided by the library: parsing a CRON expression and computing the next occurence of the scheduled time.<\/p>\n
To parse a CRON expression use make_cron()<\/tt> as follows:<\/p>\n
try\r\n{\r\n   auto cron = cron::make_cron(\"* 0\/5 * * * ?\");\r\n}\r\ncatch (cron::bad_cronexpr const & ex)\r\n{\r\n   std::cerr << ex.what() << '\\n';\r\n}<\/pre>\n
make_cron()<\/tt> returns an object of the type cronexpr<\/tt>. The actual content of this object is not of real interest and, in fact, all its details are private. You can consider this as an implementation detail object that contains the necessary information for a CRON expression, in order to compute the next occurence of the time schedule, which is the actual important operation we are interested in.<\/p>\n
To get the next occurence of the time schedule use the cron_next()<\/tt> function as follows:<\/p>\n
try\r\n{\r\n   auto cron = cron::make_cron(\"* 0\/5 * * * ?\");\r\n   \r\n   std::time_t now = std::time(0);\r\n   std::time_t next = cron::cron_next(cron, now);   \r\n}\r\ncatch (cron::bad_cronexpr const & ex)\r\n{\r\n   std::cerr << ex.what() << '\\n';\r\n}<\/pre>\n
Alternatively, you can use std::tm<\/tt> instead of std::time_t<\/tt>:<\/p>\n
try\r\n{\r\n   auto cron = cron::make_cron(\"* 0\/5 * * * ?\");\r\n   \r\n   std::tm time = cron::utils::to_tm(\"2018-08-08 20:30:45\");\r\n   std::tm next = cron::cron_next(cron, time);\r\n}\r\ncatch (cron::bad_cronexpr const & ex)\r\n{\r\n   std::cerr << ex.what() << '\\n';\r\n}<\/pre>\n
When you use these functions as shown above you implicitly use the standard supported values for the fields, as described in the first section. However, you can use any other settings. The ones provided with the library are called cron_standard_traits<\/tt>, cron_oracle_traits<\/tt> and cron_quartz_traits<\/tt> (coresponding to the aforementioned settings).<\/p>\n
try\r\n{\r\n   auto cron = cron::make_cron<cron_quartz_traits>(\"* 0\/5 * * * ?\");\r\n   \r\n   std::time_t now = std::time(0);\r\n   std::time_t next = cron::cron_next<cron_quartz_traits>(cron, now);   \r\n}\r\ncatch (cron::bad_cronexpr const & ex)\r\n{\r\n   std::cerr << ex.what() << '\\n';\r\n}<\/pre>\n
Performance<\/h3>\n
I tried to see how the library performs, both on Windows and Mac, although the machines I used for testing were pretty different. I used the following:<\/p>\n
VC++ 15.7.4 running on:<\/p>\n