Description

Typed value tagged with a state and a time stamp.

Definition at line 488 of file resources.H.

#include "resources.H"

Public Member Functions
	CRcValueState (ERcType _type)
	for initializing type, but without setting value

Set value and attributes (general methods) ...
General methods to clear and set the object. Unless specified otherwise, all 'Set...' methods clear or set all attributes (i.e. the state and the time stamp). The time stamp is always cleared.
void	Clear ()
	Clear value, set state to 'rcsUnknown', and leave type unchanged.

void	Clear (ERcType _type, ERcState _state=rcsUnknown)
	Clear to default value: More...

void	Set (const CRcValueState *vs2)

Setting special values for @ref CRcDriver::DriveValue() methods ...
These methods may be used by drivers to steer the implicit reporting done after a driver's DriveValue() method has been called. Note: Some of these values (particularly the combination of no type and a state != rcsUnknown) are only allowed in this context and usually forbidden.
void	SetToReportBusy ()
	Modify object to auto-report a busy state.

void	SetToReportBusyOldVal ()
	Modify object to auto-report a busy state with no value change. Note: Only for use in CRcDriver::DriveValue()! Normally, the combination of no type and a state != rcsUnknown are forbidden.

void	SetToReportBusyNewVal ()
	Modify object to auto-report a busy state together with a value. This is to be used in CRcDriver::DriveValue(). If the value is not set explicitly, the current value to drive will be reported back.

void	SetToReportNothing ()
	Modify object to not auto-report anything.

Set value and state (multi-type capable setters) ...
Multi-type capable setters for setting values. The name indicates the input type. As the target type ('_type'), any type is allowed, and conversion is done as good as possible. For example, floating point values may be rounded to integers, or numbers are converted to 'true' if and only if they are != 0. With the exception of SetGenericString(), this never fails.
void	SetGenericInt (int _val, ERcType _type, ERcState _state=rcsValid)
	Set from integer or boolean.

void	SetGenericFloat (float _val, ERcType _type, ERcState _state=rcsValid)
	Set from float.

bool	SetGenericString (const char *_val, ERcType _type, ERcState _state=rcsValid)
	Set from string. On syntax error, a warning is emitted, the state is set to rcsUnknown, and 'false' is returned.

Set value and and state (single-type setters) ...
void	SetBool (bool _val, ERcState _state=rcsValid)

void	SetInt (int _val, ERcState _state=rcsValid)

void	SetFloat (float _val, ERcState _state=rcsValid)

bool	SetString (const char *_val, ERcState _state=rcsValid)

void	SetTime (TTicks _val, ERcState _state=rcsValid)

void	SetTrigger (int _val=1, ERcState _state=rcsValid)

bool	SetMutex (const char *_val, ERcState _state=rcsValid)

void	SetUnitInt (ERcType type, int _val, ERcState _state=rcsValid)

void	SetUnitFloat (ERcType type, float _val, ERcState _state=rcsValid)

void	SetEnum (ERcType type, int _val, ERcState _state=rcsValid)

Get value (strict typing) ...
Get the value with strict typing. An incorrect type leads to a run-time error. The state is not considered. These are the most efficient methods. Use these methods for local/self-defined resources. The strict type checking will help you to discover bugs. Int() and Float() tolerate compatible types (trigger, unit, enum).
int	GenericInt () const

float	GenericFloat () const

const char *	GenericString () const

bool	Bool () const

int	Int () const

float	Float () const

const char *	String () const

TTicks	Time () const

int	Trigger () const

const char *	Mutex () const

int	UnitInt (ERcType _type) const

float	UnitFloat (ERcType _type) const

int	EnumIdx () const

Get value (relaxed typing)...
Get the value with relaxed typing. A type mismatch inside the same type class is silently tolerated. The state is considered, and 'rcsUnknown' is returned if either the state is 'rcsUnknown', the type does not match or 'this == NULL'. No runtime errors will be thrown. Use these methods for remote resources. The relaxed typing will help to avoid run-time errors. Note: These methods may invoke Convert() for the target type and thus modify the object.
ERcState	GetValue (bool *retBool)

ERcState	GetValue (int *retInt)

ERcState	GetValue (float *retFloat)

ERcState	GetValue (CString *retString)

ERcState	GetValue (TTicks *retTime)

Get value (relaxed typing with auto-correction) ...
Get the value with relaxed typing and auto-correction. These methods always return a valid value of the respective type. If 'GetValue' would return 'rcsUnknown', the default value is returned. 'this == NULL' is tolerated. Returned strings are only accessible as long as 'this' remains live and unchanged! Note: These methods may invoke Convert() for the target type and thus modify the object.
bool	ValidBool (bool defaultVal=false)

int	ValidInt (int defaultVal=0)

float	ValidFloat (float defaultVal=0.0)

const char *	ValidString (const char *defaultVal=CString::emptyStr)

TTicks	ValidTime (TTicks defaultVal=0)

int	ValidTrigger (int defaultVal=0)

const char *	ValidMutex (const char *defaultVal=CString::emptyStr)

int	ValidUnitInt (ERcType _type, int defaultVal=0) const

float	ValidUnitFloat (ERcType _type, float defaultVal=0.0) const

int	ValidEnumIdx (ERcType _type, int defaultVal=0) const

Attributes ...
void	SetType (ERcType _type)
	Change type in a hard way; implies resetting the state to 'rcsUnkown'.

void	SetState (ERcState _state)

void	SetTimeStamp (TTicks _timeStamp)

ERcType	Type () const

ERcState	State () const

TTicks	TimeStamp () const

bool	IsValid () const
	State is `rcsValid`, neither `rcsBusy` nor `rcsUnknown`.

bool	IsBusy () const
	State is `rcsBusy`, neither `rcsValid` nor `rcsUnknown`.

bool	IsKnown () const
	State is either `rcsValid` or `rcsBusy`; In other words: the value can be retrieved.

bool	Equals (const CRcValueState *vs2) const
	Strict comparison: state, type and value must match exactly; time stamps are not compared.

bool	ValueEquals (const CRcValueState *vs2) const
	Relaxed comparison: type and value must match exactly; state and time stamps are not compared.

Type conversion ...
bool	Convert (ERcType _type)
	Try to convert the current value to a new type. If a conversion is not possible, 'false' is returned and the object remains unchanged.

Stringification ...
const char *	ToStr (CString *ret, bool withType=false, bool withTimeStamp=false, bool precise=false, int stringChars=20) const
	Output the object contents as a string according to the synax described for 'SetFromStr'. More...

bool	SetFromStr (const char *str)
	Set the value and state based on textual information. More...

bool	SetFromStrFast (const char *str, bool warn=true)
	Set the object based on textual information (fast version). More...

Miscellaneous ...
void	ToHuman (char *retBuf, int retBufSize)
	Output a human-readable string representation for UIs. More...

Protected Attributes
TTicks	timeStamp
	time of last value/state change or trigger

Friends
class	CResource

Member Function Documentation

◆ Clear()

void CRcValueState::Clear	(	ERcType	_type,
		ERcState	_state = `rcsUnknown`
	)

Clear to default value:

rctBool: false
rctInt / rctTrigger: 0
rctFloat: 0.0
rctString / rctMutex: "" (NULL)

◆ ToStr()

const char * CRcValueState::ToStr	(	CString *	ret,
		bool	withType = `false`,
		bool	withTimeStamp = `false`,
		bool	precise = `false`,
		int	stringChars = `20`
	)		const

Output the object contents as a string according to the synax described for 'SetFromStr'.

If 'withType' is set, the type information is prepended. If 'precise' is set, the output is in a format that allows a transportation without information loss, but potentially not human-readable. 'stringChars' is the maximum number of characters printed for a value of type 'rctString' (including elipses). 'precise = true' implies 'stringChars = INT_MAX'. If 'withTimeStamp' is set AND the time stamp is > 0, the time stamp is appended to the output.

◆ SetFromStr()

bool CRcValueState::SetFromStr ( const char * str )

Set the value and state based on textual information.

Syntax:

["("<type>")"] [!]<value>|? [@<timestamp>]

Syntax of <value>:

<bool>    ::= [0fF] | [1tT+]                  : boolean value
<int>     ::= [-][0-9]+                       : integer value
<float>   ::= [-][0-9]*[.[0-9]+][E[+/-][0-9]+]: floating-point value
<precise> ::= $[0-9a-f]{8}                    : float value encoded as a 8-digit hex value
<string>  ::= [0-9a-zA-Z\]+ | \0              : string (\-escaped, UTF8 encoding); terminating 0 is optional except for the emtpy string (= "\0")
<time>    ::= <time>                          : absolute time value; see TicksFromString() for syntax
<unit>    ::= [<float>|<int>]<unit>           : unit value (<unit> is the unit string)
<enum>    ::= [_a-zA-Z][_a-zA-Z0-9]+          : enumeration value

A value starting with '!' indicates the state 'rcsBusy', a value of '?' the state 'rcsUnknown'. In all other cases, the state is 'rcsValid'.

On error, a warning is emitted, the default value at a state of 'rcsUnknown' is set (see 'Clear'), and 'false' is returned. If 'str' contains type information, the 'type' field is set accordingly. If not, and the current type is 'rctNone', the type is auto-detected. In all other cases, 'type' is not changed and must match the given <value>.

Whitespaces are tolerated and stripped away internally.

◆ SetFromStrFast()

bool CRcValueState::SetFromStrFast	(	const char *	str,
		bool	warn = `true`
	)

Set the object based on textual information (fast version).

This is a variant of SetFromStr() which does not copy 'str' internally and may be faster, especially for long strings. This method cannot not interpret type and timestamp information. Also, leading/trailing whitespaces are not tolerated.

◆ ToHuman()

void CRcValueState::ToHuman	(	char *	retBuf,
		int	retBufSize
	)

Output a human-readable string representation for UIs.

Unlike ToStr(), the output is not necessarily machine-readable. The method generates an output with at most 'retBufSize' -1 characters and does its best make it human-readable.

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

resources/resources.H