En esta página

QJniArray Class

template <typename T> class QJniArray

La clase QJniArray es una clase de plantilla que representa una matriz en Java. Más información...

Encabezado: #include <QJniArray>
CMake: find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core
Desde: Qt 6.8
Heredado de: QJniArrayBase

Tipos públicos

Funciones públicas

QJniArray()
QJniArray(Container &&container)
QJniArray(QJniArray<Other> &&other)
QJniArray(QJniArray<Other> &&other)
(since 6.9) QJniArray(QJniArrayBase::size_type size)
QJniArray(QJniObject &&object)
QJniArray(const QJniArray<Other> &other)
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>::iterator begin()
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>::iterator end()
QJniArray<T>::const_iterator end() const
QJniArray<T>::reverse_iterator rbegin()
QJniArray<T>::const_reverse_iterator rbegin() const
QJniArray<T>::reverse_iterator rend()
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)
(since 6.9) QJniArray<T>::reference operator[](QJniArrayBase::size_type i)
QJniArray<T>::const_reference operator[](QJniArrayBase::size_type i) const

Descripción detallada

QJniArray es una clase de plantilla en la que T especifica el tipo de elemento del array de Java. El tipo puede ser un tipo primitivo de JNI, como jint o jbyte, o un tipo de objeto, como jobject, jstring, o un tipo declarado con Q_DECLARE_JNI_CLASS.

La plantilla QJniArray facilita el trabajo con métodos de Java que devuelven o aceptan una matriz de Java.

Nota: Las matrices de Java pueden contener tipos primitivos y objetos. El propio array puede tratarse como un objeto Java, y el marco JNI proporciona API explícitas para trabajar con dichos arrays. Además, la biblioteca de clases de Java proporciona tipos de contenedor como List o ArrayList. Los objetos de esos tipos no pueden representarse mediante un QJniArray. En su lugar, utilice QJniObject para llamar a las funciones miembro específicas de la clase.

Para crear una instancia de QJniArray, se puede construir a partir de un contenedor de C++ correspondiente:

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

o a partir de una lista de inicializadores:

const QJniArray intArray{1, 2, 3};

QJniArray creará una nueva matriz Java y copiará en ella los datos del lado de C++.

Al llamar a funciones que devuelven una matriz a través de ` QJniObject::callMethod`, como ` char[] toCharArray() ` en la clase Java ` String `, especifica el tipo de retorno como una matriz C (jchar[] en el siguiente ejemplo):

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

La variable ` charArray ` será de tipo ` QJniArray<jchar>` y contendrá una nueva referencia global al objeto JNI ` jcharArray `.

Ten en cuenta que todas las matrices de los fragmentos de código anteriores son const. Acceder a los elementos de una matriz const es considerablemente más eficiente que operar sobre una matriz mutable.

También se puede construir un `QJniArray` a partir de un ` jarray ` o un ` QJniObject` ya existente. Sin embargo, hay que tener en cuenta que no se realiza ninguna comprobación de tipos para verificar que el ` jarray ` o el ` QJniObject ` represente efectivamente una matriz que contenga elementos del tipo especificado, y que acceder a un `QJniArray` que no coincida da lugar a un comportamiento indefinido.

Se puede acceder a los datos de un `QJniArray` elemento por elemento mediante ` at()` o ` operator[]()`, o bien iterando sobre ellos.

for (const auto &value : array)
    process(value);

Para copiar todo el array en un contenedor Qt del lado de C++, utiliza la función ` toContainer()`.

const auto bytes = object.callMethod<jbyte[]>("getBytes");
QByteArray data = bytes.toContainer();

lo cual ocurre de forma implícita en

const auto data = object.callMethod<QByteArray>("getBytes");

El tipo de retorno de ` toContainer()` depende del tipo con el que se haya instanciado `QJniArray`. Para ` QJniArray<T> `, suele ser ` QList<T>`, con las siguientes excepciones:

EspecializaciónTipo C++
QJniArray<jbyte>QByteArray
QJniArray<char>QByteArray
QJniArray<jstring>QStringList
QJniArray<QString>QStringList

También se puede crear una matriz de tamaño fijo sin ningún dato, y luego rellenarla elemento a elemento utilizando operator[]:

QJniArray<jint> intArray(size);
for (int i = 0; i < size; ++i)
    intArray[i] = i;

o un iterador mutable:

QJniArray<QString> strings(size);
int i = 0;
for (auto string : strings) // note: not 'auto &string'
    string = u"Row %1"_s.arg(i++);

Al igual que en Java, el tamaño de una matriz no se puede modificar, pero la variable de la matriz se puede asignar a otra matriz.

Nota: Las matricesde Java están limitadas a 32 bits, y el tipo de miembro size_type de QJniArray es jsize, que es un tipo entero de 32 bits. Intentar construir un QJniArray a partir de un contenedor de C++ que contenga más de 2^32 elementos provocará una aserción en tiempo de ejecución.

Documentación sobre tipos de miembros

[alias] QJniArray::const_iterator

[alias] QJniArray::iterator

Un iterador de acceso aleatorio para ` QJniArray`. /*

/*!

Un iterador const de acceso aleatorio para QJniArray.

[alias] QJniArray::const_reverse_iterator

[alias] QJniArray::reverse_iterator

Un iterador inverso para ` QJniArray`, sinónimo de ` std::reverse_iterator<iterator>`.

Nota: Para acceder al elemento del iterador inverso mediante ` operator->() ` se requiere C++20, ya que ` reverse_iterator `, de C++17, no admite iteradores que devuelvan un objeto proxy. /*

/*!

Un iterador inverso para el ` QJniArray`, sinónimo de ` std::reverse_iterator<const_iterator>`.

Nota: Para acceder al elemento del iterador inverso utilizando operator->() se requiere C++20, ya que el reverse_iterator de C++17 no admite iteradores que devuelvan un objeto proxy.

Documentación de las funciones miembro

[default] QJniArray::QJniArray()

Constructor por defecto de QJniArray. Este constructor no crea un array en el lado de Java, por lo que la instancia no será válida.

Véase también isValid.

[explicit] template <typename Container> requires if_compatible_source_container<Container> QJniArray::QJniArray(Container &&container)

Crea un objeto `QJniArray` que envuelve una matriz Java recién creada para elementos de tipo ` Container::value_type`, y rellena dicha matriz Java con los datos de ` container`.

Restricciones

Participa en la resolución de sobrecargas únicamente si ` Container ` es un contenedor que almacena elementos de tipo ` JNI type ` o de un tipo equivalente en C++, y proporciona un iterador hacia adelante.

La especialización del `QJniArray` construido depende del tipo de valor de ` container`. Para un ` Container<T> ` (como, por ejemplo, ` QList<T>`), normalmente será ` QJniArray<T>`, con las siguientes excepciones:

ContenedorEspecialización
QByteArrayQJniArray<jbyte>
QStringListQJniArray<jstring>
Container::value_typeEspecialización
QJniObjectQJniArray<jobject>

Véase también QJniArrayBase::fromContainer() y toContainer().

[noexcept] template <typename Other> requires if_convertible<Other, T> QJniArray::QJniArray(QJniArray<Other> &&other)

Crea un objeto `QJniArray` a partir de ` other`. La matriz ` other ` pasa a ser ` invalid`.

Restricciones

Participa en la resolución de sobrecargas solo si el tipo de elemento Other de other es convertible al tipo de elemento T del QJniArray que se está construyendo. Sin embargo, no se lleva a cabo ninguna conversión real.

[noexcept delete] template <typename Other> requires unless_convertible<Other, T> QJniArray::QJniArray(QJniArray<Other> &&other)

Crea por defecto una instancia de ` QJniArray`. Esta función se ha eliminado.

[explicit, since 6.9] QJniArray::QJniArray(QJniArrayBase::size_type size)

Crea un QJniArray vacío de tamaño size. Los elementos del array no se inicializan.

Esta función se introdujo en Qt 6.9.

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

Crea un QJniArray a partir de un object. El QJniObject se convierte en invalid.

Nota: Este constructor no comprueba si el objeto del lado de Java es una matriz del tipo correcto. Acceder a un `QJniArray` que no coincida da lugar a un comportamiento indefinido.

template <typename Other> requires if_convertible<Other, T> QJniArray::QJniArray(const QJniArray<Other> &other)

Crea un objeto `QJniArray` copiando ` other`. Ambos objetos `QJniArray` harán referencia al mismo objeto de matriz de Java.

Restricciones

Participa en la resolución de sobrecargas solo si el tipo de elemento Other de other es convertible al tipo de elemento T del QJniArray que se está creando. Sin embargo, no se lleva a cabo ninguna conversión real.

[delete] template <typename Other> requires unless_convertible<Other, T> QJniArray::QJniArray(const QJniArray<Other> &other)

Crea por defecto una instancia de ` QJniArray`. Esta función se ha eliminado.

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

Crea un `QJniArray` que envuelve el mismo array de Java que ` object`, creando una nueva referencia global. Para crear un `QJniArray` a partir de una referencia local ya existente, utiliza un ` QJniObject ` creado mediante ` fromLocalRef()`.

Nota: Este constructor no comprueba si el objeto del lado de Java es un array del tipo correcto. Acceder a un QJniArray que no coincida da lugar a un comportamiento indefinido.

[explicit] QJniArray::QJniArray(jarray array)

Crea un objeto `QJniArray` que envuelve la matriz del lado de Java ` array`, creando una nueva referencia global a ` array`.

Nota: Este constructor no comprueba si el objeto del lado de Java es un array del tipo correcto. Acceder a un `QJniArray` que no coincida da lugar a un comportamiento indefinido.

[implicit] QJniArray::QJniArray(std::initializer_list<T> &list)

Crea un objeto `QJniArray` que envuelve un array de Java recién creado para elementos de tipo ` T`, y rellena dicho array de Java con los datos de ` list`.

Véanse también QJniArrayBase::fromContainer() y toContainer().

[default] QJniArray::~QJniArray()

Destruye el objeto ` QJniArray ` y libera cualquier referencia que se tenga al array de Java envuelto.

auto QJniArray::arrayObject() const

Devuelve el objeto Java envuelto como el tipo adecuado jarray que coincide con el tipo del elemento T de este objeto QJniArray.

Ttipo jarray
jbytejbyteArray
jcharjcharArray
......
jobjectjobjectArray
QJniObjectjobjectArray
Q_DECLARE_JNI_CLASSjobjectArray

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

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

Devuelve el valor situado en la posición i de la matriz Java envuelta.

i Debe ser una posición de índice válida en la lista (es decir, 0 <= i < size()).

Véase también size().

[noexcept] QJniArray<T>::iterator QJniArray::begin()

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

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

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

Devuelve un iterador const al estilo STL que apunta al primer elemento de la matriz.

Si el array es de tip invalid, esta función devolverá el mismo iterador que la función correspondiente end().

Véanse también end() y rbegin().

[noexcept] QJniArray<T>::iterator QJniArray::end()

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

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

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

Devuelve un iterador de estilo STL que apunta justo después del último elemento de la lista.

Véase también begin() y rend().

[noexcept] QJniArray<T>::reverse_iterator QJniArray::rbegin()

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

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

Devuelve un iterador inverso al estilo STL que apunta al primer elemento del array, en orden inverso.

Si la matriz es de tipo ` invalid`, esta función devolverá el mismo iterador que la función correspondiente ` rend()`.

Nota: Para acceder al elemento del iterador inverso mediante ` operator->() ` se requiere C++20, ya que la función ` reverse_iterator ` de C++17 no admite iteradores que devuelvan un objeto proxy.

Véase también rend() y begin().

[noexcept] QJniArray<T>::reverse_iterator QJniArray::rend()

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

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

Devuelve un iterador inverso al estilo STL que apunta justo después del último elemento de la lista, en orden inverso.

Nota: Para acceder al elemento del iterador inverso mediante ` operator->() ` se requiere C++20, ya que la sintaxis de C++17 ` reverse_iterator ` no admite iteradores que devuelvan un objeto proxy.

Véanse también rbegin() y end().

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

Devuelve un contenedor que contiene los datos del array de Java envuelto.

Si no se proporciona ningún ` container `, el tipo del contenedor devuelto dependerá del tipo de elemento de este ` QJniArray`. Para ` QJniArray<T> `, normalmente será ` QList<T>`, con las siguientes excepciones:

Si se pasa un contenedor con nombre (un lvalue) a ` container`, dicho contenedor se rellena y se devuelve una referencia al mismo. Si se pasa un contenedor temporal (un rvalue, incluido el argumento por defecto), dicho contenedor se rellena y se devuelve por valor.

Esta función devuelve el resultado inmediatamente si el matriz es ` invalid`.

Véase también ` QJniArrayBase::fromContainer()`.

[noexcept] template <typename Other> requires if_convertible<Other, T> QJniArray<T> &QJniArray::operator=(QJniArray<Other> &&other)

Traslada « other » a « QJniArray » y devuelve una referencia a este. La matriz « other » pasa a ser « invalid ».

Restricciones

Participa en la resolución de sobrecargas únicamente si el tipo de elemento Other de other es convertible al tipo de elemento T de este QJniArray. Sin embargo, no se lleva a cabo ninguna conversión real.

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

Asigna ` other ` a este ` QJniArray` y devuelve una referencia a este. Ambos objetos ` QJniArray ` harán referencia al mismo objeto de matriz de Java.

Restricciones

Participa en la resolución de sobrecargas únicamente si el tipo de elemento Other de other es convertible al tipo de elemento T de este QJniArray. Sin embargo, no se lleva a cabo ninguna conversión real.

[since 6.9] QJniArray<T>::reference QJniArray::operator[](QJniArrayBase::size_type i)

Devuelve un objeto de referencia para el valor situado en la posición i del array Java envuelto.

i Debe ser una posición de índice válida en la lista (es decir, 0 <= i < size()).

El objeto de referencia devuelto contiene el valor en la posición i y, en la mayoría de los casos, se convertirá implícitamente en dicho valor. Al asignar un valor a la referencia devuelta, se sobrescribirá la entrada del array de Java. Sin embargo, llamar a funciones miembro mutantes sobre el objeto no modificará la entrada del array. Para llamar a una función miembro sobre el resultado de este operador, desreferencia el objeto de referencia:

QJniArray<QString> strings = object.callMethod<QString[]>("getStrings");
if (!strings.isEmpty()) {
    if (!(*array[0]).isEmpty()) {
        // ...
    }
}

No obstante, si no se pretende modificar el valor del propio array, declare el array como const o utilice at() en su lugar.

Esta función se introdujo en Qt 6.9.

Véase también ` at()` y ` size()`.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.