company logo

PropertyHandle :: Provide - Provide instance

The Provide() function allows selecting an instance in a property handle collection by key or position that must not necessarily exist in the collection. The provide function checks whether the instance exists in the collection (Get()). If not existing the instance is created in the collection (-> Add()) and selected.
Return value:  Instance area ( ::Instance  )

Instances do have the type of the referenced property handle (collection type). The instance contains a pointer to a properly structured instance area.

You can use the !-operator or the GetData() function to check whether the instance refers to data or not.

Implementation overview

Implementation details

  1. Provide instance by key value
    ::Instance PropertyHandle  :: Provide ( ::Key sort_key )

    The function tries to provide an instance with the passed sort key (or identing key for unordered collections). When no instance exist with the key passed in sort_key, the function creates an instance by key value (-> Add(): "Add Instance by key value").
    • sort_key - - internal feature (not documented)
    2. to list
  2. Provide instance at position
    ::Instance PropertyHandle  :: Provide ( int32 set_pos0_w=AUTO )

    The function tries to provide an instance at a certain position. When no instance exist at the location passed in set_pos_w, the function creates an instance by position (-> Add(): "Create Instance at position").
    • set_pos0_w - Position in collection

      The position of an instance in a collection depends on the selected index. if the collection is unsorted the position is the only way for accessing the instance.

      For sorted collections the position is determined according to the instance key. If is a contradiction between position and key value the position will be ignored.

      Special positions are

      CUR_INSTANCE (-1) refers to the currently selected instance. If no instance is selected it refers to the first instance.

      FIRST_INSTANCE (0) refers to the first instance in a collection according to the selected index (sort order).

      FIRST_INSTANCE (0x7fffffff) refers to the last instance in a collection according to the selected index (sort order).

             Default: AUTO
    3. to list
  3. Provide instance by property
    ::Instance PropertyHandle  :: Provide ( PropertyHandle &cprop_hdl )

    The function checks whether the property handle passes a numerical value or not. When passing a numerical value the function provides an instance at the position according to the number passed in the property handle (-> "Provide instance at position"). When the property handle contains text data, the value in the property handle is interpreted as string key, which will be converted into key and provides an instance by key value (-> "Provide instance by key value").

    When the property handle refers to a complex instance of the same type or a base type of the current type in the property handle, the instance key in the passed property handle is used for locating the key.
    • cprop_hdl - Property Handle
    4. to list
to top previous next upper table of contents Comment