smartinspectpython.silookuptable
Module: silookuptable.py
Revision History
Date | Version | Description |
---|---|---|
2023/05/30 | 3.0.0.0 | Initial Version. |
Represents a simple collection of key/value pairs.
The SILookupTable class is responsible for storing and returning values which are organized by keys. Values can be added with the Put method. To query a String value for a given key, the GetStringValue method can be used. To query and automatically convert values to types other than String, please have a look at the Get method family.
Threadsafety:
This class is not guaranteed to be thread-safe.
Adds a new element with a specified key and value to the Lookup Table.
Arguments:
- key (str): The key of the element.
- value (str): The value of the element.
Raises:
- SIArgumentNullException: The key or value argument is null.
This method adds a new element with a given key and value to the collection of key/value pairs. If an element for the given key already exists, the original element's value is not updated.
Tests if the collection contains a value for a given key.
Arguments:
- key (str): The key to test for.
Returns:
True if a value exists for the given key and false otherwise.
Raises:
- SIArgumentNullException: The key argument is null.
Returns a value of an element converted to a bool for a given key.
Arguments:
- key (str): The key whose value to return.
- defaultValue (bool): The value to return if the given key is unknown.
Returns:
Either the value converted to a bool for the given key if an element with the given key exists or defaultValue otherwise.
Raises:
- SIArgumentNullException: The key argument is null.
This method returns a bool value of true if the found value of the given key matches either "true", "1" or "yes" and false otherwise. If the supplied key is unknown, the defaultValue argument is returned.
Returns a byte array value of an element for a given key.
Arguments:
- key (str): The key whose value to return.
- size (int): The desired size in bytes of the returned byte array. If the element value does not have the expected size, it is shortened or padded automatically.
- defaultValue (bytearrau): The value to return if the given key is unknown or if the found value has an invalid format.
Returns:
Either the value converted to a byte array for the given key if an element with the given key exists and the found value has a valid format or defaultValue otherwise.
Exception:
SIArgumentNullException: The key argument is null.
The returned byte array always has the desired length as specified by the size argument. If the element value does not have the required size after conversion, it is shortened or padded (with zeros) automatically. This method returns the defaultValue argument if either the supplied key is unknown or the found value does not have a valid format (e.g. invalid characters when using hexadecimal strings).
Returns a color value of an element for a given key.
Arguments:
- key (str): The key whose value to return.
- defaultValue (SIColor): The value to return if the given key is unknown or if the found value has an invalid format.
Returns:
Either the value converted to a Color value for the given key if an element with the given key exists and the found value has a valid format or defaultValue otherwise.
Raises:
- SIArgumentNullException: The key argument is null.
- ArgumentError: The read value is not a valid color value representation.
The element value must be specified as hexadecimal string. To indicate that the element value represents a hexadecimal string, the element value must begin with "0x", "&H" or "$". A '0' nibble is appended if the hexadecimal string has an odd length.
The hexadecimal value must represent a three or four byte integer value. The hexadecimal value is handled as follows.
Bytes | Format |
---|---|
3 | RRGGBB |
4 | AARRGGBB |
Other | Ignored |
A stands for the alpha channel and R, G and B represent the red, green and blue channels, respectively. If the value is not given as hexadecimal value with a length of 6 or 8 characters excluding the hexadecimal prefix identifier or if the value does not have a valid hexadecimal format, this method returns defaultValue.
Returns a value of an element converted to an integer for a given key.
Arguments:
- (str): The key whose value to return.
- defaultValue (int): The value to return if the given key is unknown.
Returns:
Either the value converted to an integer for the given key if an element with the given key exists and the found value is a valid integer or defaultValue otherwise.
Raises:
- SIArgumentNullException: The key argument is null.
Only non-negative integer values are recognized as valid.
Returns a value of an element converted to a Level value for a given key.
Arguments:
- key (str): The key whose value to return.
- defaultValue (SILevel): The value to return if the given key is unknown.
Returns:
Either the value converted to the corresponding Level value for the given key if an element with the given key exists and the found value is a valid Level value or defaultValue otherwise.
Raises:
- SIArgumentNullException: The key argument is null.
This method returns the defaultValue argument if either the supplied key is unknown or the found value is not a valid Level value. Please see the Level enum for more information on the available values.
Returns a value of an element converted to a SIFileRotate value for a given key.
Arguments:
- key (str): The key whose value to return.
- defaultValue (SIFileRotate): The value to return if the given key is unknown.
Returns:
Either the value converted to a SIFileRotate value for the given key if an element with the given key exists and the found value is a valid SIFileRotate or defaultValue otherwise.
Raises:
- SIArgumentNullException: The key argument is null.
This method returns the defaultValue argument if either the supplied key is unknown or the found value is not a valid SIFileRotate value. Please see the SIFileRotate enum for more information on the available values.
Returns a value of an element converted to an integer for a given key. The integer value is interpreted as a byte size and it is supported to specify byte units.
Arguments:
- key (str): The key whose value to return.
- defaultValue (int): The value to return if the given key is unknown.
Returns:
Either the value converted to an integer for the given key if an element with the given key exists and the found value is a valid integer or defaultValue otherwise.
Raises:
- SIArgumentNullException: The key argument is null.
This method returns the defaultValue argument if either the supplied key is unknown or the found value is not a valid integer or ends with an unknown byte unit. Only non-negative integer values are recognized as valid.
It is possible to specify a size unit at the end of the value. If a known unit is found, this function multiplies the resulting value with the corresponding factor. For example, if the value of the element is "1KB", the return value of this function would be 1024.
The following table lists the available units together with a short description and the corresponding factor.
Unit Name / Factor | Description |
---|---|
KB / 1024 | KiloByte |
MB / 1024^2 | MegaByte |
GB / 1024^3 | GigaByte |
If no unit is specified, this function defaults to the KB unit.
Returns a string value of an element for a given key.
Arguments:
- key (str): The key whose value to return.
- defaultValue (str): The value to return if the given key is unknown.
Returns:
The value for a given key if an element with the given key exists; otherwise, the defaultValue.
Raises:
- SIArgumentNullException: The key argument is null.
Returns a value of an element converted to an integer for a given key. The integer value is interpreted as a time span and it is supported to specify time span units.
Arguments:
- key (str): The key whose value to return.
- defaultValue (int): The value to return if the given key is unknown.
Returns:
Either the value converted to an integer for the given key if an element with the given key exists and the found value is a valid integer or defaultValue otherwise. The value is returned in milliseconds.
Raises:
- SIArgumentNullException: The key argument is null.
This method returns the defaultValue argument if either the supplied key is unknown or the found value is not a valid integer or ends with an unknown time span unit.
It is possible to specify a time span unit at the end of the value. If a known unit is found, this function multiplies the resulting value with the corresponding factor. For example, if the value of the element is "1s", the return value of this function would be 1000.
The following table lists the available units together with a short description and the corresponding factor.
Unit Name / Factor | Description |
---|---|
s (seconds) | 1000 |
m (minutes) | 60*s |
h (hours) | 60*m |
d (days) | 24*h |
If no unit is specified, this function defaults to the Seconds unit. Please note that the value is always returned in milliseconds.
Checks to see if the supplied value is numeric or not.
Arguments:
- value (str): The value to check.
Returns:
True if the value is numeric; otherwise, false.
Only non-negative whole integer values are recognized as numeric.
Checks to see if the supplied value is a valid size unit or not. Valid size units are: kb, mb, and gb.
Arguments:
- value (str): The value to check.
Returns:
True if the value is valid; otherwise, false.
Checks to see if the supplied value is a valid timespan unit or not. Valid units are: s, m, h, and d.
Arguments:
- value (str): The value to check.
Returns:
True if the value is valid; otherwise, false.
Adds or updates an element with a specified key and value to the Lookup Table.
Arguments:
- key (str): The key of the element.
- value (str): The value of the element.
Raises:
- SIArgumentNullException: The key or value argument is null.
This method adds a new element with a given key and value to the collection of key/value pairs. If an element for the given key already exists, the original element's value is updated.
Removes an existing element with a given key from this lookup table.
Arguments:
- key (str): The key of the element to remove.
Raises:
- SIArgumentNullException: The key argument is null.
This method removes the element with the given key from the internal list. Nothing happens if no element with the given key can be found.