.. _objects-values:

******************
Objects and Values
******************

Class exposed by shiboken may be specified as either **object types**
indicated by the :ref:`object-type` XML element, or **value types** indicated
by :ref:`value-type` XML element.

The choice should follow the usage of the class in C++.

Non-copyable classes with virtual functions that form an inheritance hierarchy
should be **object types**. They are typically passed by pointer in C++ and
stored on the heap.

Classes with value semantics should be **value types**. They are typically
passed by value in C++, and stored on the function call stack. This is also a
good default for the remaining classes.

When passing **value types** to functions, shiboken will generate code to
handle implicit conversions as is done in C++. For example, in Qt, it is
possible to pass instances of **QColor** to a function taking a **QBrush**,
since **QBrush** has a constructor accepting **QColor**.

Aspects of Value Types
======================

shiboken tries to detect whether a class is default/copy constructible when
parsing the class declaration. No detection is done to for movability; it is
assumed to be enabled by default. These values can be overridden by attributes
on the :ref:`value-type` XML element in case auto-detection fails. For
non-default constructible types, it is possible to specify a default
constructor expression to work around.

shiboken assumes that copy constructible classes also have a copy assignment
operator.

Default constructibility
------------------------

Value types should be default constructible.

For generating virtual functions returning value types by value, this
is a hard requirement.

For generating bindings (passing arguments), non-default constructible types
will use pointer conversions instead of copy conversion. Implicit conversions
will then not be generated. Otherwise, it should be equivalent for passing by
value or const reference. When passing a non-default constructible type by
reference to a function that actually modifies the parameter, the modification
will affect the passed instance.

Copy constructibility
---------------------

Copy constructibility/copy assignment is required by the value converters
generated by shiboken.

For move-only types, shiboken will then insert ``std::move()`` where needed.
This will leave moved-out instances behind.
