Implicit conversion of a property value from one data type to another

When an application gets the value of a property, the value can be converted by XMS into another data type. Many rules govern which conversions are supported and how XMS performs the conversions.

A property of an object has a name and a value; the value has an associated data type, where the value of a property is also referred to as the property type.

An application uses the methods of the PropertyContext class to get and set the properties of objects. In order to get the value of a property, an application calls the method that is appropriate for the property type. For example, to get the value of an integer property, an application typically calls the GetIntProperty method.

However, when an application gets the value of a property, the value can be converted by XMS into another data type. For example, to get the value of an integer property, an application can call the GetStringProperty method, which returns the value of the property as a string. The conversions supported by XMS are shown in Table 1.

Property type Supported target data types
System.String System.Boolean, System.Double, System.Float, System.Int32, System.Int64, System.SByte, System.Int16
System.Boolean System.String, System.SByte, System.Int32, System.Int64, System.Int16
System.Char System.String
System.Double System.String
System.Float System.String, System.Double
System.Int32 System.String, System.Int64
System.Int64 System.String
System.SByte System.String, System.Int32, System.Int64, System.Int16
System.SByte array System.String
System.Int16 System.String, System.Int32, System.Int64
The following general rules govern the supported conversions:

  • Numeric property values can be converted from one data type to another provided no data is lost during the conversion. For example, the value of a property with data type System.Int32 can be converted into a value with data type System.Int64, but it cannot be converted into a value with data type System.Int16.
  • A property value of any data type can be converted into a string.
  • A string property value can be converted to any other data type provided the string is formatted correctly for the conversion. If an application attempts to convert a string property value that is not formatted correctly, XMS may return errors.
  • If an application attempts a conversion that is not supported, XMS may return an error.

The following rules apply when a property value is converted from one data type to another:

  • When converting a boolean property value to a string, the value true is converted to the string true, and the value false is converted to the string false.
  • When converting a boolean property value to a numeric data type, including System.SByte, the value true is converted to 1, and the value false is converted to 0.
  • When converting a string property value to a boolean value, the string true (not case-sensitive) or 1 is converted to true, and the string false (not case-sensitive) or 0 is converted to false. All other strings cannot be converted.
  • When converting a string property value to a value with data type System.Int32, System.Int64, System.SByte, or System.Int16, the string must have the following format:

    • [blanks][sign]digits

    The string components are defined as follows:

      blanks
      Optional leading blank characters.

      sign
      An optional plus sign (+) or minus sign (-) character.

      digits
      A contiguous sequence of digit characters (0-9). At least one digit character must be present.

    After the sequence of digit characters, the string can contain other characters that are not digit characters, but the conversion stops as soon as the first of these characters is reached. The string is assumed to represent a decimal integer.

    XMS may return an error if the string is not formatted correctly.

  • When converting a string property value to a value with data type System.Double or System.Float, the string must have the following format:

    • [blanks][sign][digits][point[d_digits]][e_char[e_sign]e_digits]

    The string components are defined as follows:

      blanks
      (Optional) Leading blank characters.

      sign
      (Optional) Plus sign (+) or minus sign (-) character.

      digits
      A contiguous sequence of digit characters (0-9). At least one digit character must be present in either digits or d_digits.

      point
      (Optional) Decimal point (.).

      d_digits
      A contiguous sequence of digit characters (0-9). At least one digit character must be present in either digits or d_digits.

      e_char
      An exponent character, which is either E or e.

      e_sign
      (Optional) Plus sign (+) or minus sign (-) character for the exponent.

      e_digits
      A contiguous sequence of digit characters (0-9) for the exponent. At least one digit character must be present if the string contains an exponent character.

    After the sequence of digit characters, or the optional characters representing an exponent, the string can contain other characters that are not digit characters, but the conversion stops as soon as the first of these characters is reached. The string is assumed to represent a decimal floating point number with an exponent that is a power of 10.

    XMS may return an error if the string is not formatted correctly.

  • When converting a numeric property value to a string, including a property value with data type System.SByte, the value is converted to the string representation of the value as a decimal number, not the string containing the ASCII character for that value. For example, the integer 65 is converted to the string 65, not the string A.
  • When converting a byte array property value to a string, each byte is converted to the 2 hexadecimal characters that represent the byte. For example, the byte array {0xF1, 0x12, 0x00, 0xFF} is converted to the string F11200FF.

Conversions from a property type to other data types are supported by the methods of both the Property and the PropertyContext classes.

Parent topic: Writing XMS applications