- Qt 6.8
- Qt Core
- C++ Classes
- QJniArray
- Qt 6.8.3 Reference Documentation

# QJniArray Class

The QJniArray class is a template class that represents an array in Java. More...

Header: | `#include <QJniArray>`
CMake: | `find_package(Qt6 REQUIRED COMPONENTS Core)` `target_link_libraries(mytarget PRIVATE Qt6::Core)`
qmake: | `QT += core`
Since: | Qt 6.8
Inherits: | QJniArrayBase

- List of all members, including inherited members

## Public Types

| const_iterator
| const_reverse_iterator

## Public Functions

| QJniArray()
| QJniArray(Container &&container)
| QJniArray(QJniArray<Other> &&other)
| QJniArray(QJniObject &&object)
| QJniArray(const QJniArray<Other> &other)
| QJniArray(const QJniObject &object)
| QJniArray(jarray array)
| QJniArray(std::initializer_list<T> &list)
| ~QJniArray()
auto | arrayObject() const
QJniArray<T>::const_reference | at(QJniArrayBase::size_type i) const
QJniArray<T>::const_iterator | begin() const
QJniArray<T>::const_iterator | cbegin() const
QJniArray<T>::const_iterator | cend() const
QJniArray<T>::const_iterator | constBegin() const
QJniArray<T>::const_iterator | constEnd() const
QJniArray<T>::const_reverse_iterator | crbegin() const
QJniArray<T>::const_reverse_iterator | crend() const
QJniArray<T>::const_iterator | end() const
QJniArray<T>::const_reverse_iterator | rbegin() const
QJniArray<T>::const_reverse_iterator | rend() const
Container | toContainer(Container &&container = {}) const
QJniArray<T> & | operator=(QJniArray<Other> &&other)
QJniArray<T> & | operator=(const QJniArray<Other> &other)
QJniArray<T>::const_reference | operator[](QJniArrayBase::size_type i) const

## Detailed Description

The QJniArray template makes it easy to work with arrays when interfacing with Java methods that return or take a Java array.

Note: Java arrays can hold primitive types and objects. The array itself can be treated like a Java Object, and the JNI framework provides explicit APIs to work with such arrays. In addition, the Java class library provides container types such as `List` or `ArrayList`. Objects of those types can not be represented by a QJniArray. Instead, use QJniObject to call the class-specific member functions.

To create a QJniArray instance, either construct it from a corresponding C++ container:

     QList<int> intList;
     QJniArray intArray = QJniArray(intList);

or from an initializer list:

     QJniArray intArray{1, 2, 3};

QJniArray will create a new Java array and copy the C++-side data into it.

When calling functions that return an array via QJniObject::callMethod, such as `char[] toCharArray()` in the Java `String` class, specify the return type as a C array (`jchar[]` in the following):

     auto charArray = stringObject.callMethod<jchar[]>("toCharArray");

The `charArray` variable will be of type `QJniArray<jchar>`, and hold a new global reference to the `jcharArray` JNI object.

Lastly, a QJniArray can be constructed from an existing `jarray` or QJniObject. However, note that no type checking is performed to verify that the `jarray` or QJniObject indeed represents an array holding elements of the specified type, and accessing a mismatching QJniArray results in undefined behavior.

The data in a QJniArray can either be accessed element by element using at() or operator[](), iterated over, or copied into a suitable C++ container via the toContainer() function.

     QList<jchar> characters = charArray.toContainer();

The return type of toContainer() depends on the type that QJniArray has been instantiated with. For `QJniArray<T>` this will typically be `QList<T>`, with the following exceptions:

Specialization | C++ type
--- | ---
QJniArray<jbyte> | QByteArray
QJniArray<char> | QByteArray
QJniArray<jstring> | QStringList
QJniArray<QString> | QStringList

The elements in the QJniArray cannot be modified through QJniArray APIs, and there is no mutating iterator.

Note: Java arrays are limited to 32 bits, and the `size_type` member type of QJniArray is `jsize`, which is a 32bit integer type. Trying to construct a QJniArray from a C++ container that holds more than 2^32 elements will cause a runtime assertion.

## Member Type Documentation

### `[alias]` QJniArray::const_iterator

A random-access, const iterator for QJniArray.

### `[alias]` QJniArray::const_reverse_iterator

A reverse iterator for the QJniArray, synonym for `std::reverse_iterator<const_iterator>`.

## Member Function Documentation

### `[noexcept]` QJniArray<T>::const_iterator QJniArray::begin() const

### `[noexcept]` QJniArray<T>::const_iterator QJniArray::cbegin() const

### `[noexcept]` QJniArray<T>::const_iterator QJniArray::constBegin() const

Returns an STL-style iterator pointing to the first item in the array.

If the array is invalid, then this will return the same iterator as the corresponding end() function.

See also end() and rbegin().

### `[noexcept]` QJniArray<T>::const_iterator QJniArray::cend() const

### `[noexcept]` QJniArray<T>::const_iterator QJniArray::constEnd() const

### `[noexcept]` QJniArray<T>::const_iterator QJniArray::end() const

Returns an STL-style iterator pointing just after the last item in the list.

See also begin() and rend().

### `[noexcept]` QJniArray<T>::const_reverse_iterator QJniArray::crbegin() const

### `[noexcept]` QJniArray<T>::const_reverse_iterator QJniArray::rbegin() const

Returns an STL-style reverse iterator pointing to the first item in the array, in reverse order.

If the array is invalid, then this will return the same iterator as the corresponding rend() function.

See also rend() and begin().

### `[noexcept]` QJniArray<T>::const_reverse_iterator QJniArray::crend() const

### `[noexcept]` QJniArray<T>::const_reverse_iterator QJniArray::rend() const

Returns an STL-style reverse iterator pointing just after the last item in the list, in reverse order.

See also rbegin() and end().

### QJniArray<T>::const_reference QJniArray::at(QJniArrayBase::size_type i) const

### QJniArray<T>::const_reference QJniArray::operator[](QJniArrayBase::size_type i) const

Returns the value at position i in the wrapped Java array.

i must be a valid index position in the list (i.e., 0 <= i < size()).

See also size().

### QJniArray::QJniArray()

Default constructor of QJniArray. This does not create a Java-side array, and the instance will be invalid.

See also isValid.

### `[explicit]` template <typename Container, QJniArrayBase::if_compatible_source_container<Container> = true> QJniArray::QJniArray(Container &&container)

Constructs a QJniArray that wraps a newly-created Java array for elements of type `Container::value_type`, and populates the Java array with the data from container.

This function only participates in overload resolution if `Container` is a container that stores elements of a JNI type or equivalent C++ type, and provides a forward iterator.

The specialization of the constructed QJniArray depends on the value type of the container. For a `Container<T>` (such as e.g. `QList<T>`) it will typically be `QJniArray<T>`, with the following exceptions:

Container | Specialization
--- | ---
QByteArray | QJniArray<jbyte>
QStringList | QJniArray<jstring>
Container::value_type | Specialization
QJniObject | QJniArray<jobject>

See also QJniArrayBase::fromContainer() and toContainer().

### `[noexcept]` template <typename Other, QJniArrayBase::if_convertible<Other, T> = true> QJniArray::QJniArray(QJniArray<Other> &&other)

Constructs a QJniArray by moving from other. The other array becomes invalid.

This constructor only participates in overload resolution if the element type `Other` of other is convertible to the element type `T` of the QJniArray being constructed. However, no actual conversion takes place.

### `[explicit noexcept]` QJniArray::QJniArray(QJniObject &&object)

Constructs a QJniArray by moving from object. The QJniObject becomes invalid.

Note: This constructor does not perform any validation of whether the Java-side object is an array of the correct type. Accessing a mismatching QJniArray results in undefined behavior.

### template <typename Other, QJniArrayBase::if_convertible<Other, T> = true> QJniArray::QJniArray(const QJniArray<Other> &other)

Constructs a QJniArray by copying other. Both QJniArray objects will reference the same Java array object.

This constructor only participates in overload resolution if the element type `Other` of other is convertible to the element type `T` of the QJniArray being constructed. However, no actual conversion takes place.

### `[explicit]` QJniArray::QJniArray(const QJniObject &object)

Constructs a QJniArray that wraps the same Java array as object, creating a new global reference. To construct a QJniArray from an existing local reference, use a QJniObject constructed via fromLocalRef().

Note: This constructor does not perform any validation of whether the Java-side object is an array of the correct type. Accessing a mismatching QJniArray results in undefined behavior.

### `[explicit]` QJniArray::QJniArray(jarray array)

Constructs a QJniArray that wraps the Java-side array array, creating a new global reference to array.

Note: This constructor does not perform any validation of whether the Java-side object is an array of the correct type. Accessing a mismatching QJniArray results in undefined behavior.

### `[default]` QJniArray::QJniArray(std::initializer_list<T> &list)

Constructs a QJniArray that wraps a newly-created Java array for elements of type `T`, and populates the Java array with the data from list.

See also QJniArrayBase::fromContainer() and toContainer().

### QJniArray::~QJniArray()

Destroys the QJniArray object and releases any references held to the wrapped Java array.

### auto QJniArray::arrayObject() const

Returns the wrapped Java object as the suitable `jarray` type that matches the element type `T` of this QJniArray object.

T | jarray type
--- | ---
jbyte | jbyteArray
jchar | jcharArray
... | ...
jobject | jobjectArray
QJniObject | jobjectArray
Q_DECLARE_JNI_CLASS | jobjectArray

### template <typename Container = QJniArrayBase::ToContainerType<T>, QJniArrayBase::if_compatible_target_container<T, Container> = true> Container QJniArray::toContainer(Container &&container = {}) const

Returns a container populated with the data in the wrapped Java array.

If no container is provided, then the type of the container returned depends on the element type of this QJniArray. For `QJniArray<T>` this will typically be `QList<T>`, with the following exceptions:

Specialization | C++ type
--- | ---
QJniArray<jbyte> | QByteArray
QJniArray<char> | QByteArray
QJniArray<jstring> | QStringList
QJniArray<QString> | QStringList

If you pass in a named container (an lvalue) for container, then that container is filled, and a reference to it is returned. If you pass in a temporary container (an rvalue, incl. the default argument), then that container is filled, and returned by value.

This function returns immediately if the array is invalid.

See also QJniArrayBase::fromContainer().

### `[noexcept]` template <typename Other, QJniArrayBase::if_convertible<Other, T> = true> QJniArray<T> &QJniArray::operator=(QJniArray<Other> &&other)

Moves other into this QJniArray, and returns a reference to this. The other array becomes invalid.

This operator only participates in overload resolution if the element type `Other` of other is convertible to the element type `T` of this QJniArray. However, no actual conversion takes place.

### template <typename Other, QJniArrayBase::if_convertible<Other, T> = true> QJniArray<T> &QJniArray::operator=(const QJniArray<Other> &other)

Assigns other to this QJniArray, and returns a reference to this. Both QJniArray objects will reference the same Java array object.

This operator only participates in overload resolution if the element type `Other` of other is convertible to the element type `T` of this QJniArray. However, no actual conversion takes place.