smartinspectpython.silookuptable

Module: silookuptable.py

Revision History

Date Version Description
2023/05/30 3.0.0.0 Initial Version.

@export
class SILookupTable:

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.

SILookupTable()

Initializes a new instance of the class.

Count: int

Returns the number of key/value pairs of this collection.

def Add(self, key: str, value: str) -> None:

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.

def Clear(self) -> None:

Removes all key/value pairs of the collection.

def Contains(self, key: str) -> bool:

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.
def GetBooleanValue(self, key: str, defaultValue: bool) -> bool:

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.

def GetBytesValue(self, key: str, size: int, defaultValue: bytearray) -> bytearray:

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).

def GetColorValue( self, key: str, defaultValue: smartinspectpython.sicolor.SIColor) -> smartinspectpython.sicolor.SIColor:

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.

def GetIntegerValue(self, key: str, defaultValue: int) -> int:

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.

def GetLevelValue( self, key: str, defaultValue: smartinspectpython.silevel.SILevel) -> smartinspectpython.silevel.SILevel:

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.

def GetSizeValue(self, key: str, defaultValue: int) -> int:

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.

def GetStringValue(self, key: str, defaultValue: str) -> str:

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.
def GetTimespanValue(self, key: str, defaultValue: int) -> int:

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.

@staticmethod
def IsValidInteger(value: str) -> bool:

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.

@staticmethod
def IsValidSizeUnit(value: str) -> bool:

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.

@staticmethod
def IsValidTimespanUnit(value: str) -> bool:

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.

def Put(self, key: str, value: str) -> None:

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.

def Remove(self, key: str) -> None:

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.