company logo

Property :: insertKey - Insert key in collection

The function creates a name reference (key) in an ordered collection. The function can be called for ordered and unordered collections. A collection is considered as ordered, when the main index has been defined with an access key. Trying to insert a key to an ordered collection at a certain position will throw an exception.

When the collection has got super sets, the function tries to locate an instance in the super set hierarchy of the collection with the passed primary key or key value extracted from the instance. The collections in the super set hierarchy must support access via primary key. When an instance with the key value passed could be located, the instance will be inserted in the collection.

When no super set is defined or no instance could be found for the passed key value, a name reference with the primary key value is created for the collection (and all super sets).

When inserting a key to a collection, the cardinality for the collection is checked. When the collection requires unique access key, the key value is checked for duplicate. When the key could not be appended (because of duplicate key or other reasons), the function throws an exception, which provides detailed explanations for the error reason.

When terminating successfully, an instance with properly set key attributes will be provided in the property handle. The instance is located but not positioned.
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. Insert key by instance
    odaba::Property & Property  :: insertKey ( odaba::Instance &cInstance )

    Inserting a name reference by an instance creates name references for all indexes in the collection (and its super sets). Required keys are extracted from the instance passed in cInstance. In case of duplicate keys for unique indexes the function throws an exception.
    Notes:

    When adding name references to indexes that are nor unique, accessing instances in an overload object space may cause problems, since the system cannot distinguish between instances with same key value.

    • cInstance - Instance

      The instance is passed as String, which is structured as ESDF data (object interchange format).
    2. to list
  2. - internal feature (not documented)
    odaba::Property & Property  :: insertKey ( odaba::Instance &cInstance, int32 iPosition )
    • cInstance - Instance

      The instance is passed as String, which is structured as ESDF data (object interchange format).
    • iPosition - Position in collection

      The position of an element in a collection is beginning with 0 for the first element.
    3. to list
  3. Insert key by value
    odaba::Property & Property  :: insertKey ( odaba::Key vSortKey )

    The function inserts a name reference for the key with the primary key value passed in vPrimaryKey in the collection. The function does not maintain indexes for other keys. When the collection is unordered, the name reference is inserted in front of the currently located instance or at the end of collection, when no key reference has been located. In case of duplicate keys for a unique index the function throws an exception.

    When the collection has got super sets, the function tries to locate the passed key value 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 an access key (index) for the primary key.

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

    When no primary key has been defined for the data type, the function throws an exception.
    • 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
    4. to list
  4. Insert name reference by key values
    odaba::Property & Property  :: insertKey ( odaba::Key vSortKey, odaba::Key vPrimaryKey )

    The function allows inserting

    • 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
    • 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. Insert key at position
    odaba::Property & Property  :: insertKey ( odaba::Key vPrimaryKey, int32 iPosition )

    The function should be called for unordered collections, only. A collection is considered as unordered, when the currently selected index has no access key or the collection is singular. When the collection is ordered, the function throws an exception.

    When -1 is passed in iPosition, the name reference is appended at the end of collection.

    When the collection has got defined super sets, the function tries to locate the passed key value 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 an access key (index) for the primary key.

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

    When no primary key has been defined for the data type, the function throws an exception.
    • 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
    • iPosition - Position in collection

      The position of an element in a collection is beginning with 0 for the first element.
    6. to list
  6. - internal feature (not documented)
    odaba::Property & Property  :: insertKey ( odaba::Property &cProperty )
    • cProperty - Property reference

      A property handle refers to a (usually) opened property. Invalid properties may cause an exception.
    7. to list
  7. - internal feature (not documented)
    odaba::Property & Property  :: insertKey ( odaba::Property &cProperty, int32 iPosition )
    • cProperty - Property reference

      A property handle refers to a (usually) opened property. Invalid properties may cause an exception.
    • iPosition - Position in collection

      The position of an element in a collection is beginning with 0 for the first element.
    8. to list
to top previous next upper table of contents Comment