company logo

Property :: append - Append instance to collection

The function supports appending an instance to an unordered collection. The function can be called for unordered collections, only. Trying to append an instance to an ordered collection will throw an exception. In this regard a collection is unordered, when the currently selected index has no access key or the collection is singular.

When appending an instance to a collection, the cardinality for the collection is checked. When the collection requires unique access key, the access key value (primary key) is checked.

When appending an instance to an owning collection, a new database instance will be created. When terminating successfully the instance appended to the collection is selected in the property handle.

When the instance could not be appended (duplicate key, inverse reference error or others), the function throws an exception, which provides detailed explanations for the error reason.
Notes:

When a filter has been set for the collection, no instance will be selected in the property handle, when the instance created does not match the filter condition.

Instead of append(), insert() could be used passing the instance count as preferred position. Since append() throws an exception when the collection is ordered, calling the function may fail when changing the object model (from unordered to ordered). Hence, it is suggested using insert() rather than append().

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. Create and append new instance
    odaba::Property & Property  :: append (  )

    The function creates a new instance in an unordered collection. The instance is appended to the end of collection.
    2. to list
  2. Append initialized instance
    odaba::Property & Property  :: append ( bool bInstance )

    The function appends an initialized instance to the collection. The function should not be called, when a super set has been defined for the collection, in which case a key value is required.

    The instance in the property handle can be initialized before calling append() by calling initializeInstance() and setting initial property values. In order to avoid reinitializing the instance, the bInstance option must be set to true. In order to initialize the instance, the application may also overload the doBeforeInitialize() event handler in the type context class.

    • bInstance - Use internal instance

      The option forces the function to use the internal instance area without reinitializing is. When not being set, the internal instance is reinitialized before the operation is executed.

    3. to list
  3. Append instance to collection
    odaba::Property & Property  :: append ( odaba::Instance &cInstance )

    This function is used to append an instance to an unordered collection. The instance data is passed as OIF string in vInstance. The function appends the instance at end of collection.
    • cInstance - Instance

      The instance is passed as String, which is structured as ESDF data (object interchange format).
    4. to list
  4. Append instance to unique collection
    odaba::Property & Property  :: append ( odaba::Key vPrimaryKey )

    When the collection has got super sets, the function tries to locate an instance in the super set hierarchy of the collection with the primary key value passed in vPrimaryKey. The collections in the super set hierarchy must support access key for the primary key.

    When no super set is defined or no instance could be found, a new instance with the given primary key value (vPrimaryKey) will be created.

    When no primary key has been defined for the data type, the key value in vPrimaryKey will be ignored.
    • vPrimaryKey - Primary key value

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

      In order to pass no key value, an empty string ( String() ) can be passed.

      // key: name;first_name

      Miller;Paul          // simple positioned CSV key

      "Miller";"Paul Mary" // special characters must be quoted
    5. to list
  5. Append selected instance
    odaba::Property & Property  :: append ( odaba::Property &cProperty )

    This function is used to append the instance selected in the property handle passed in cProperty to an unordered collection. The instance has to inherit from the type selected in the target collection. The function stores the instance at end of collection.
    • cProperty - Property reference

      A property handle refers to a (usually) opened property. Invalid properties may cause an exception.
    6. to list
to top next upper table of contents Comment