advgetopt::validator_duration Class Reference

#include <validator_duration.h>

Inheritance diagram for advgetopt::validator_duration:

Collaboration diagram for advgetopt::validator_duration:

Classes
struct	range_t

Public Types
typedef std::uint32_t	flag_t
typedef std::shared_ptr< validator >	pointer_t
typedef std::vector< pointer_t >	vector_t

Public Member Functions
	validator_duration (string_list_t const &data)
	Initialize the duration validator.
std::string const &	get_error () const
virtual std::string	name () const override
	Return the name of this validator.
void	set_error (std::string const &msg) const
virtual bool	validate (std::string const &value) const override
	Determine whether value is a valid duration.

Static Public Member Functions
static bool	convert_string (std::string const &duration, flag_t flags, double suffix_default_factor, double &result)
	Convert a string to a double value representing a duration.
static pointer_t	create (std::string const &name, string_list_t const &data)
static pointer_t	create (std::string const &name_and_params)
	Set the validator for this option.
static void	register_validator (validator_factory const &factory)
static double	suffix_to_factor (std::string const &suffix, flag_t flags, double suffix_default_factor)
	Convert a duration suffix in a factor.

Static Public Attributes
static constexpr flag_t	VALIDATOR_DURATION_DEFAULT_FLAGS = 0x00
static constexpr flag_t	VALIDATOR_DURATION_LONG = 0x01

Private Attributes
range_t::vector_t	f_allowed_values = range_t::vector_t()
double	f_default_factor = 1.0
std::string	f_error = std::string("<error undefined>")
flag_t	f_flags = VALIDATOR_DURATION_DEFAULT_FLAGS

Detailed Description

Definition at line 49 of file validator_duration.h.

Member Typedef Documentation

flag_t

typedef std::uint32_t advgetopt::validator_duration::flag_t

Definition at line 53 of file validator_duration.h.

pointer_t

typedef std::shared_ptr<validator> advgetopt::validator::pointer_t

inherited

Definition at line 64 of file validator.h.

vector_t

typedef std::vector<pointer_t> advgetopt::validator::vector_t

inherited

Definition at line 65 of file validator.h.

Constructor & Destructor Documentation

validator_duration()

advgetopt::validator_duration::validator_duration

(

string_list_t const &

flag_list

)

The constructor accepts a string defining the acceptable durations.

The string uses the following format:

start: flag_or_range
     | start ',' flag_or_range
 
flags_and_ranges: flag
                | suffix
                | range
 
flags: 'small'
     | 'large'
 
suffix: 'd' | 'day' | 'days'
      | 'h' | 'hour' | 'hours'
      | 'm' | 'minute' | 'minutes'
            | 'month' | 'months'
      | 'mi' | 'microsecond' | 'microseconds'
      | 'ms' | 'millisecond' | 'milliseconds'
      | 'ns' | 'nanosecond' | 'nanoseconds'
      | 's' | 'second' | 'seconds'
      | 'w' | 'week' | 'weeks'
      | 'y' | 'year' | 'years'
 
range: duration
     | duration '...' duration
 
duration: [-+]?[0-9]+(.[0-9]+)?suffix?

Warning

The order in which the flags are defined do have an effect. If you first define "small" then "m", you get a default suffix of 1 minute. If instead you use "large, m" then you get 1 month. But because the default is small, using "m, large" defines the default suffix as 1 minute then changes the meaning of "m" to 1 month (30 days). Similarly, the range definitions are affected by the flags and default_suffix definitions happening beforehand.

'small' stands for small values (down to 1 second).

'large' stands for large values (so the 'm' suffix represents month, not minutes).

The default_suffix defines the default factor to the specified suffix. By default, the factor is set to 1.0 which means 1 second.

The 'small' and 'large' flags are exclusive, the last one is effective. Note that the 'm' suffix is the only one currently affected. If you want to specifically specify minutes or months you can also enter the entire word:

1minute...5minutes
3months...12months

The duration range can use any duration on the left hand side and right hand side. The whole expression cannot include any spaces.

For example, the following defines a duration range between one second and one minute:

1s...60s

If a side is omitted the default is used: the minimum of the left hand side and the maximum for the right hand side. The minimum must be smaller or equal to the maximum.

When no suffix is specified, the default suffix is used. If not changed, the default suffix is 1 second.

Note

At the moment we do not support UTF-8 for the suffixes and as a result the micro letter is not supported nor any UTF-8 spaces.

Parameters

[in]

flag_list

The flags used to define the usage of the 'm' suffix.

Definition at line 177 of file validator_duration.cpp.

References convert_string(), f_allowed_values, f_default_factor, f_flags, advgetopt::option_flags_merge(), suffix_to_factor(), and VALIDATOR_DURATION_LONG.

Member Function Documentation

convert_string()

bool advgetopt::validator_duration::convert_string ( std::string const &  value, flag_t  flags, double  suffix_default_factor, double &  result  )

static

This function is used to convert a string to a double representing a duration. The duration can be specified with one of the following suffixes:

• "ns" or "nanosecond" or "nanoseconds" – the double is multiplied by 0.0000000001
• "mi" or "microsecond" or "microseconds" – the double is multiplied by 0.0000001
• "ms" or "millisecond" or "milliseconds" – the double is multiplied by 0.0001
• "s" or "second" or "seconds" – the double is returned as is
• "m" or "minute" or "minutes" – the double is multiplied by 60
• "h" or "hour" or "hours" – the double is multiplied by 3600
• "d" or "day" or "days" – the double is multiplied by 86400
• "w" or "week" or "weeks" – the double is multiplied by 604800
• "m" or "month" or "months" – the double is multiplied by 2592000
• "y" or "year" or "years" – the double is multiplied by 31536000

The "m" suffix is interpreted as "minute" by default. The flags passed to the constructor can change that interpretation into "month" instead.

Any number of spaces can appear between the number of the suffix.

One month uses 30 days.

One year uses 365 days.

Note that the input can be a double. So you can define a duration of "1.3 seconds" or "2.25 days".

You can also write multiple values such as "3 days 2 hours 17 seconds" (with the shorthand being "3d2h17s"). The durations get added to each other and the result returned. The durations get added to each other and the result returned.

Todo:

The last multiplication doesn't verify that no overflow or underflow happens.

Warning

There is no range checks in this function since it does not have access to the ranges (i.e. it is static).

Parameters

[in]	value	The value to be converted to a duration.
[in]	flags	The flags to determine how to interpret the suffix.
[in]	suffix_default_factor	The default suffix factor. Use 1.0 for 1 second, 86400.0 for one day, etc. You can use the suffix_to_factor() function to use a name instead of a number. This value does not need to match the factor of a known suffix.
[out]	result	The resulting duration in seconds.

Returns

true if the conversion succeeded.

Definition at line 370 of file validator_duration.cpp.

References advgetopt::validator_double::convert_string(), advgetopt::option_flags_merge(), and suffix_to_factor().

Referenced by validator_duration(), and validate().

create() [1/2]

validator::pointer_t advgetopt::validator::create ( std::string const &  name, string_list_t const &  data  )

staticinherited

Definition at line 605 of file validator.cpp.

References advgetopt::validator::name(), and advgetopt::option_flags_merge().

Referenced by advgetopt::validator::create(), and advgetopt::option_info::set_validator().

create() [2/2]

validator::pointer_t advgetopt::validator::create ( std::string const &  name_and_params )

staticinherited

This function parses the specified name and optional parameters and create a corresponding validator for this option.

The name_and_params string can be defined as:

<validator-name>(<param1>, <param2>, ...)

The list of parameters is optional. There may be an empty, just one, or any number of parameters. How the parameters are parsed is left to the validator to decide.

If the input string is empty, the current validator, if one is installed, gets removed.

The complete grammar of the name_and_params name and parameters can be written as a comma separated list of function calls, we have a special case for regex which do not require the function call. thing is pretty much anything other than the few special characters (comma, space, parenthesis, and quotes). To include a special character in thing either use a string or escape the character.

validator_list: name_and_params
              | name_and_params ',' validator_list
 
name_and_params: name '(' params ')'
               | '/' ... '/'              // regex special case
 
name: [a-zA-Z_][a-zA-Z_0-9]*
 
params: (thing - [,()'" ])
      | '\'' (thing - '\'') '\''
      | '"' (thing - '"') '"'
 
thing: [^ -~]*
     | '\\' [ -~]

Parameters

[in]

name_and_params

The validator name and parameters.

Definition at line 666 of file validator.cpp.

References advgetopt::validator::create(), and advgetopt::option_flags_merge().

get_error()

std::string const & advgetopt::validator::get_error ( ) const

inherited

Definition at line 581 of file validator.cpp.

References advgetopt::validator::f_error.

name()

std::string advgetopt::validator_duration::name ( ) const

overridevirtual

This function returns "duration".

Returns

"duration".

Implements advgetopt::validator.

Definition at line 273 of file validator_duration.cpp.

register_validator()

void advgetopt::validator::register_validator ( validator_factory const &  factory )

staticinherited

Definition at line 587 of file validator.cpp.

References advgetopt::option_flags_merge().

set_error()

void advgetopt::validator::set_error ( std::string const &  msg ) const

inherited

Definition at line 575 of file validator.cpp.

References advgetopt::validator::f_error, and advgetopt::option_flags_merge().

Referenced by advgetopt::validator_double::validate(), validate(), advgetopt::validator_email::validate(), advgetopt::validator_integer::validate(), advgetopt::validator_keywords::validate(), advgetopt::validator_length::validate(), advgetopt::validator_list::validate(), advgetopt::validator_regex::validate(), and advgetopt::validator_size::validate().

suffix_to_factor()

double advgetopt::validator_duration::suffix_to_factor ( std::string const &  suffix, flag_t  flags, double  suffix_default_factor  )

static

The duration suffixes, such as "day" or "months", need to be converted to a number of seconds. This function does that conversion.

If the input string is empty, then the default factor is returned. Within a validator_duration object, the default is 1.0.

Parameters

[in]	suffix	A valid duration suffix or an empty string.
[in]	flags	The flags to determine how to interpret the suffix.
[in]	suffix_default_factor	Value returned if the suffix string is empty.

Returns

The factor representing the duration or -1.0 on an error.

Definition at line 493 of file validator_duration.cpp.

References advgetopt::option_flags_merge(), and VALIDATOR_DURATION_LONG.

Referenced by validator_duration(), and convert_string().

validate()

bool advgetopt::validator_duration::validate ( std::string const &  value ) const

overridevirtual

This function verifies that the specified value is a valid duration.

It makes sure that the value is a valid decimal number which optionally starts with a sign ([-+]?) and is optionally followed by a known duration suffix.

Parameters

[in]

value

The value to validate.

Returns

true if the value validates.

Implements advgetopt::validator.

Definition at line 291 of file validator_duration.cpp.

References convert_string(), f_allowed_values, f_default_factor, f_flags, advgetopt::option_flags_merge(), and advgetopt::validator::set_error().

Member Data Documentation

f_allowed_values

range_t::vector_t advgetopt::validator_duration::f_allowed_values = range_t::vector_t()

private

Definition at line 87 of file validator_duration.h.

Referenced by validator_duration(), and validate().

f_default_factor

double advgetopt::validator_duration::f_default_factor = 1.0

private

Definition at line 86 of file validator_duration.h.

Referenced by validator_duration(), and validate().

f_error

std::string advgetopt::validator::f_error = std::string("<error undefined>")

mutableprivateinherited

Definition at line 82 of file validator.h.

Referenced by advgetopt::validator::get_error(), and advgetopt::validator::set_error().

f_flags

flag_t advgetopt::validator_duration::f_flags = VALIDATOR_DURATION_DEFAULT_FLAGS

private

Definition at line 85 of file validator_duration.h.

Referenced by validator_duration(), and validate().

VALIDATOR_DURATION_DEFAULT_FLAGS

constexpr flag_t advgetopt::validator_duration::VALIDATOR_DURATION_DEFAULT_FLAGS = 0x00

staticconstexpr

Definition at line 55 of file validator_duration.h.

VALIDATOR_DURATION_LONG

constexpr flag_t advgetopt::validator_duration::VALIDATOR_DURATION_LONG = 0x01

staticconstexpr

Definition at line 56 of file validator_duration.h.

Referenced by validator_duration(), and suffix_to_factor().

---

The documentation for this class was generated from the following files:

• advgetopt/validator_duration.h
• advgetopt/validator_duration.cpp