company logo

Property :: provide - Provide instance

The function allows positioning an instance in a property handle collection by key or position, which must not necessarily exist in the collection. The provide function checks whether the requested instance already exist ( tryGet() ). If not existing the instance is inserted in the collection (see Property::insert ).

When an error occurred or no instance could be selected (e.g. the new instance does not fulfill a filter condition), the function throws an exception.

// same as ph.provide(sKey);

  if ( !ph.tryGet(sKey) )

    ph.Insert(sKey);

Return value:  Property reference ( odaba::Property & )

A property handle refers to a (usually) opened property. Invalid properties may cause an exception.

Implementation overview

Implementation details

  1. Provide instance by key value
    odaba::Property & Property  :: provide ( odaba::Key vSortKey )

    The function tries to provide an instance with the key value passed in vSortKey . The key value must correspond to the selected access key. When no instance exist with the key value passed, the function creates an instance by key value.

    For singular collections the function will replace the currently associated instance by the new instance with the passed key.

    • vSortKey - Access key

      The sort or access key value is provided as typed string in ESDF or CSV format. Key components can be separated by '|' or ';'.

      // key: name;first_name

      Miller;Paul          // simple positioned CSV key

      "Miller";"Paul Mary" // special characters must be quoted

  2. to list
  3. Provide instance at position
    odaba::Property & Property  :: provide ( int32 iPosition )

    The function tries to provide an instance at position passed in iPosition . The function does not check filter conditions. The value passed in iPosition must be a value greater or equal to 0 . In case of an invalid position value or calling the function with a sorted collection property, the function throws an exception.

    When no instance exist at the position passed, the function creates a new instance.

    • iPosition - Position in collection

      The position of an element in a collection is beginning with 0 for the first element.

  4. to list
  5. Provide instance
    odaba::Property & Property  :: provide ( odaba::Property &cProperty )

    When passing the value for providing an instance in a collection via property handle, the function tries to provide the instance by key or index, depending on the data type defined in the property handle.

    When the property handle rProperty passes a typed instance of the same or a specialized type as the instance to be selected, the key value is extracted from the instance passed in the property handle and provide by key is called. For singular collections the function will replace the currently associated instance by the new instance.

    When passing a text value, the text data is considered as string key and provide by key is called.

    When the property handle rProperty contains a numerical value, provide by position is called. Non integer numerical values are rounded to the next lower integer number.

    • cProperty - Property reference

      A property handle refers to a (usually) opened property. Invalid properties may cause an exception.

  6. to list