VByteArray

Esta clase proporciona un array de bytes. En JavaScript es más conveniente utilizar esta clase que usar la clase String, salvo para aquellos casos en los que tengamos que trabajar con caracteres no ASCII ni Latin-1. El uso de array de bytes ayuda a mejorar el uso de la memoria y el manejo de datos binarios. Un bytearray siempre termina con el carácter terminador \0.

Si convertimos un string en un byte array, la longitud del byte array será la del string más uno ya que en el byte array se añade el carácter nulo "\0" de terminación de cadena. Por ejemplo el string "buenas" tiene una longitud de 6, si lo convertimos en un byte array quedaría así ('b','u','e','n','a','s','\0') con una longitud de 7.

Indice de propiedades

Number length

Indice de funciones

Constructor

VByteArray( Number nSize )

VByteArray()

De contenido

VByteArray& append( VByteArray other )

arrayBuffer arrayBuffer()

void chop( Number n )

void clear()

VByteArray& fill( int ch, Number nSize = -1 )

VByteArray& fromBase64( VByteArray base64 )

VByteArray& fromHex( VByteArray hex )

VByteArray& insert( Number nPos, VByteArray other )

VByteArray& prepend( VByteArray other )

VByteArray& remove( Number nPos, Number nLen)

VByteArray& replace( Number nPos, Number nLen, VByteArray baSustituto )

void resize( Number nSize )

void setArrayBuffer( arrayBuffer )

void setText( String szText )

void truncate( Number nPos )

VByteArray& valueOf()

De compresión

VByteArray compress( Number nCompressionLevel = -1 )

VByteArray uncompress()

De conversión

VByteArray toBase64()

VByteArray toHex()

String toLatin1String()

VByteArray toLower()

VByteArray toUpper()

String toUtf8String()

De cadena

VByteArray left( Number nLen )

VByteArray mid( Number nPos, Number nLen = -1)

VByteArray repeated( Number nVeces )

VByteArray right( Number nLen )

VByteArray simplified()

VByteArray trimmed()

De comparación

Boolean contains( VByteArray other )

Number count( VByteArray other )

Boolean endsWith( VByteArray other

Boolean equals( VByteArray other )

Number indexOf( VByteArray other, Number nFrom = 0 )

Boolean isEmpty()

Boolean isNull()

Number lastIndexOf( VByteArray other, Number nFrom = 0 )

Boolean startsWith( VByteArray other )

Documentación de propiedades

length

Devuelve el número de bytes que contiene el bytearray.

Documentación de funciones

Constructor

VByteArray( Number nSize )

Crea un nuevo objeto de la clase VByteArray con el tamaño especificado.

Parámetros:

• nSize: tamaño en número de bytes que tendrá el bytearray al ser creado.

VByteArray()

Crear un nuevo objeto de la clase VByteArray vacío.

Funciones de contenido

VByteArray& append( VByteArray other )

Añade el buffer del byte array pasado en el parámetro al final de byte array sobre el que se aplica la función.

Esta función devuelve una referencia a si mismo, es decir el mismo byte array tras aplicarle la función.

Parámetros:

• other: objeto de la clase VByteArray cuyo buffer será añadido.

Ejemplo:

var x = new VByteArray();
x.setText("free");

var y = new VByteArray();
y.setText("dom");

x.append(y);
// x == "freedom"

array Buffer arrayBuffer()

Devuelve el contenido de un VByteArray en el tipo de dato arrayBuffer de JavaScript.

Esta función solamente está disponible en script que ejecutemos con el comando de instrucción de proceso Ejecutar script (filescript).

void chop( Number n )

Elimina el número de bytes especificados en el parámetro del final del buffer del byte array.

Si el número de bytes especificados en el parámetro es mayor que el tamaño del buffer, deja el byte array vacío.

Esta función no devuelve un nuevo byte array sino que aplica los cambios directamente sobre el byte array origen de la función.

Parámetros:

• n: número que indica el número de bytes a eliminar.

Ejemplo:

var ba = new VByteArray();
ba.setText("STARTTLS\r\n");
ba.chop(2);
// ba == "STARTTLS"

void clear()

Limpia el contenido del byte array y lo deja vacío.

VByteArray& fill( int ch, Number nSize = -1 )

Cambiar cada byte del array al carácter especificado en el parámetro. Si el tamaño es diferente de -1 (valor por defecto), el byte array es redimensionado al número de bytes especificado. Si no se especifica tamaño, se cambiarán todos los bytes existentes en el array.

Esta función devuelve una referencia a si mismo, es decir el mismo byte array tras aplicarle la función.

Parámetros:

• ch: código ASCII de carácter a aplicar en cada byte del array.

• nSize: número de bytes del array en los que se sustituirá el valor. Es opcional si no se indica se aplica a todos los bytes del array.

Ejemplo:

var ba = new VByteArray();
ba.setText("Istambul");

ba.fill(111);
// ba == "oooooooo"

ba.fill(120, 2);
// ba == "XX"

ba.fill("V".charCodeAt(0));
//ba == "VV"

VByteArray& fromBase64( VByteArray base64 )

Devuelve una copia del array decodificado de base64. No se verifica que el buffer sea válido. Los caracteres no válidos se omitirán continuando el proceso con los caracteres restantes.

Esta función devuelve una referencia a si mismo, es decir el mismo byte array tras aplicarle la función.

Usa la codificación Base64URL, que se utiliza principalmente en URL y en identificadores de objetos JSON. Este tipo de codificación tiene la características de que Modifica los caracteres '+' y '/' por '-' y '_', respectivamente, para evitar problemas con los navegadores y protocolos web que interpretan de manera especial los caracteres '+' y '/'.*

Parámetros:

• base64: objeto de la clase VByteArray cuyo buffer contiene el buffer codificado en base64.

Ejemplo:

var text = new VByteArray();
var cadena = new VByteArray(); 
cadena.setText("UXQgaXMgZ3JlYXQh"); // Esta es la cadena base64 para "Qt is great!"
text.fromBase64(cadena);
// text == "Qt is great!"

VByteArray& fromHex( VByteArray hex )

Devuelve una copia del array decodificado de hexadecimal. No se verifica que el buffer sea válido. Los caracteres no válidos se omitirán continuando el proceso con los caracteres restantes.

Esta función devuelve una referencia a si mismo, es decir el mismo byte array tras aplicarle la función.

Parámetros:

• hex: objeto de la clase VByteArray cuyo buffer contiene el buffer.

Ejemplo:

var text = new VByteArray();
var cadena = new VByteArray();  
cadena.setText("517420697320677265617421");
text.fromHex( cadena );
// text == "Qt is great!"

VByteArray& insert( Number nPos, VByteArray other )

Inserta el buffer del byte array pasado en el parámetro en la posición indicada del byte array sobre el que se aplica la función. La primera posición es la 0.

Esta función devuelve una referencia a si mismo, es decir el mismo byte array tras aplicarle la función.

Parámetros:

• nPos: número que indica la posición en la que se insertarán los caracteres. La primera posición es la 0.

• other: objeto de la clase VByteArray cuyo buffer será insertado.

Ejemplo:

var ba = new VByteArray();
ba.setText("Asas");
var ba2 = new VByteArray();
ba2.setText("turi");
ba.insert(2, ba2);
// ba == "Asturias"

VByteArray& prepend( VByteArray other )

Añade el buffer del byte array pasado en el parámetro antes del contenido del byte array sobre el que se aplica la función.

Esta función devuelve una referencia a si mismo, es decir el mismo byte array tras aplicarle la función.

Parámetros:

• other: objeto de la clase VByteArray cuyo buffer será añadido.

Ejemplo:

var x = new VByteArray();
x.setText("motor");

var y = VByteArray();
y.setText("ciclo");

x.prepend(y);
// x == "ciclomotor"

VByteArray& remove( Number nPos, Number nLen)

Elimina del byte array a partir de la posición indicada en el parámetro el número de bytes especificados en el parámetro longitud. La primera posición es la 0.

Esta función devuelve una referencia a si mismo, es decir el mismo byte array tras aplicarle la función.

Parámetros:

• nPos: número que indica la posición en la que se eliminarán los caracteres. La primera posición es la 0.

• nLen: número que indica los bytes a eliminar.

Ejemplo:

var ba = new VByteArray();
ba.setText("Montreal");
ba.remove(1, 4);
// ba == "Meal"

VByteArray& replace( Number nPos, Number nLen, VByteArray baSustituto )

Reemplaza en el byte array los bytes a partir de la posición indicada en el parámetro el número de bytes especificados en el parámetro longitud con el buffer indicado en el tercer parámetro. La primera posición es la 0.

Esta función devuelve una referencia a si mismo, es decir el mismo byte array tras aplicarle la función.

Parámetros:

• nPos: número que indica la posición en la que se eliminarán los caracteres. La primera posición es la 0.

• nLen: número que indica los bytes a eliminar.

• baSustituto: objeto de la clase VByteArray cuyo buffer será el sustituto de los bytes eliminados.

Ejemplo:

var x = new VByteArray();
x.setText("Say yes!");

var y = new VByteArray();
y.setText("no");

x.replace(4, 3, y);
// x == "Say no!"

void resize( Number nSize )

Fija el tamaño del byte array al número de bytes especificados en el parámetro.

Si el nuevo tamaño es mayor que el tamaño actual, los bytes se añaden al final. Los nuevos bytes no son inicializados.

Si el nuevo tamaño es menor que el tamaño actual, los bytes sobrantes desde el nuevo tamaño hasta el final serán eliminados.

Esta función no devuelve un nuevo byte array sino que aplica los cambios directamente sobre el byte array origen de la función.

void setArrayBuffer( arrayBuffer )

Establece el contenido de un byte array en base a un arrayBuffer de JavaScript.

Parámetros:

• arrayBuffer: objeto JavaScript de tipo arrayBuffer cuyo contenido queremos asignar al byte array.

Esta función solamente está disponible en script que ejecutemos con el comando de instrucción de proceso Ejecutar script (filescript).

void setText( String szText )

Sustituye el contenido del byte array por los caracteres de la cadena especifica en el parámetro.

Parámetros:

• szText: cadena cuyo contenido será incluido en el buffer del byte array.

void truncate( Number nPos )

Trunca el contenido del byte array a partir de la posición indicada en el parámetro.

Si la posición especificada es mayor que la longitud del array, no sucede nada.

Parámetros:

• nPos: posición a partir de la que se trunca el buffer del byte array. La primera posición es la 0.

Ejemplo:

var ba = new VByteArray();
ba.setText("Stockholm");
ba.truncate(5);
// ba == "Stock"

VByteArray& valueOf()

Devuelve el contenido original del buffer del byte array, sin conversión.

Esta función devuelve una referencia a si mismo, es decir el mismo byte array tras aplicarle la función.

Funciones de compresión

VByteArray compress( Number nCompressionLevel = -1 )

Comprime los datos de un objeto de la clase VByteArray y nos devuelve un nuevo objeto de la clase VByteArray con los datos comprimidos.

Los valores van de 0 (no compresión) a 9 (máxima compresión). El valor por defecto es -1 que indica que se aplicará la compresión por defecto. Hay que tener en cuenta que cuando mayor compresión configuremos más lento es el proceso y viceversa cuando menor nivel de compresión más rapidez de ejecución.

Parámetros:

• nCompressionLevel: número que indica el nivel de compresión.

VByteArray uncompress()

A partir de un objeto VByteArray comprimido nos devuelve otro objeto de la clase VByteArray con el contenido descomprimido.

Funciones de conversión

VByteArray toBase64()

Devuelve una copia del byte array, codificada a Base64.

VByteArray toHex()

Devuelve una copia del byte array, codificada en hexadecimal.

String toLatin1String()

Devuelve un string con el contenido del byte array codificado en Latin-1.

VByteArray toLower()

Devuelve una copia del byte array, convirtiendo todos los caracteres a minúsculas. Si interpreta que el byte array está codificado en Latin-1.

VByteArray toUpper()

Devuelve una copia del byte array, convirtiendo todos los caracteres a mayúsculas. Si interpreta que el byte array está codificado en Latin-1.

String toUtf8String()

Devuelve un string con el contenido del byte array codificado en UTF-8.

Funciones de cadena

VByteArray left( Number nLen )

Devuelve un nuevo byte array que contiene el número de caracteres más a la izquierda especificados en el parámetro.

Si la longitud es mayor que el tamaño de buffer del byte array se devuelve el byte array completo.

Parámetros:

• nLen: número que representa la longitud en bytes.

Ejemplo:

var x = new VByteArray();
x.setText("España");
y = x.left(4);
// y == "Espa"

VByteArray mid( Number nPos, Number nLen = -1)

Devuelve un nuevo byte array que contiene el número de bytes especificados en el parámetro longitud desde la posición de inicio indicada en el parámetro posición.

Si la longitud es -1 (valor por defect), o la posición + longitud >= tamaño del byte array, devuelve un byte array que contiene todos los bytes comenzando en la posición indicada en el parámetro hasta el final del byte array.

Parámetros:

• nPos: número que representa la posición de inicio de los bytes a extraer. La primera posición es la 0.

• nLen: número que representa la longitud en bytes. Es opcional, si no se especifica se asume hasta el final del byte array.

Ejemplo:

var x = new VByteArray();
x.setText("San Isidro");
y = x.mid(4, 3); // y == "Isi"
z = x.mid(4); // z == "Isidro"

VByteArray repeated( Number nVeces )

Devuelve un nuevo byte array cuyo buffer contiene la repetición del número de veces especificado en el parámetro del buffer del byte array sobre el que se aplica la función.

Si el parámetro nVeces es menor de 1, se devuelve un byte array vacío.

Parámetros:

• nVeces: número de veces que se repiten los caracteres.

Ejemplo:

var ba = new VByteArray();
ba.setText("ab");
ba.repeated(4); // returns "abababab"

VByteArray right( Number nLen )

Devuelve un nuevo byte array que contiene el número de caracteres más a la derecha especificados en el parámetro.

Si la longitud es mayor que el tamaño de buffer del byte array se devuelve el byte array completo.

Parámetros:

• nLen: número que representa la longitud en bytes.

Ejemplo:

var x = new VByteArray();
x.setText("Ciclomotor");
var y = x.right(5);
// y == "motor"

VByteArray simplified()

Devuelve un nuevo byte array en el que los espacios en blanco del inicio (hasta el primer carácter que no sea un espacio en blanco) y final (desde el último carácter que no sea un espacio en blanco) se eliminan y los espacios internos serán sustituidos por un único espacio en blanco.

Se considera espacio en blanco cualquier carácter que aplicado a la función isspace() en C++ devuelva verdadera. Esto incluye los caracteres ASCII '\t', '\n', '\v', '\f', '\r', and ' '.

Ejemplo:

var ba = new VByteArray();
ba.setText(" lots\t of\nwhitespace\r\n ");
ba = ba.simplified();
// ba == "lots of whitespace";

VByteArray trimmed()

Devuelve un nuevo byte array que tiene eliminados los espacios en blanco del inicio (hasta el primer carácter que no sea un espacio en blanco) o final (desde el último carácter que no sea un espacio en blanco) del buffer.

Se considera espacio en blanco cualquier carácter que aplicado a la función isspace() en C++ devuelva verdadera. Esto incluye los caracteres ASCII '\t', '\n', '\v', '\f', '\r', and ' '.

Ejemplo:

var ba = new VByteArray();
ba.setText(" lots\t of\nwhitespace\r\n ");
ba = ba.trimmed();
// ba == "lots\t of\nwhitespace";

Funciones de comparación

Boolean contains( VByteArray other )

Devuelve true si el buffer del byte array especificado en el parámetro es encontrado en el buffer del byte array sobre el que se aplica la función, en caso contrario devuelve false.

Parámetros:

• other: objeto de la clase VByteArray cuyo buffer será comparado.

Number count( VByteArray other )

Devuelve el número de ocurrencias del byte array especificado en el parámetro en el byte array sobre el que se aplica la función.

Parámetros:

• other: objeto de la clase VByteArray cuyo buffer será comparado.

Boolean endsWith( VByteArray other )

Devuelve true si el buffer del byte array sobre el que se aplica la función termina con el buffer del byte array especificado en el parámetro, en caso contrario devuelve false.

Parámetros:

• other: objeto de la clase VByteArray cuyo buffer será comparado.

Ejemplo:

var url = new VByteArray();
url.setText("http://qt.nokia.com/index.html"\);
if (url.endsWith(".html")) {
...

Boolean equals( VByteArray other )

Devuelve true si buffer del byte array sobre el que se aplica la función es igual que el buffer del byte array especificado en el parámetro, en caso contrario devuelve false.

Parámetros:

• other: objeto de la clase VByteArray cuyo buffer será comparado.

Number indexOf( VByteArray other, Number nFrom = 0 )

Devuelve la posición del índice correspondiente al byte donde comienza la primera ocurrencia del byte array especificado en el parámetro en el byte array sobre el que se aplica la función. La búsqueda comienza en el byte especificado en el segundo parámetro, como es opcional si no se especifica la búsqueda comienza desde el principio del byte array. Esta búsqueda se realiza hacia adelante, es decir desde el principio hasta el final. Devuelve -1 si no se ha encontrado.

Parámetros:

• other: objeto de la clase VByteArray cuyo buffer será comparado.

• nFrom: número de byte desde el que comienza la comparación. El primer byte es el 0.

Ejemplo:

var x = new VByteArray();
x.setText("sticky question");
var y = new VByteArray();
y.setText("sti");

x.indexOf(y); // returns 0
x.indexOf(y, 1); // returns 10
x.indexOf(y, 10); // returns 10
x.indexOf(y, 11); // returns -1

Boolean isEmpty()

Devuelve true si el byte array tiene tamaño, en caso contrario devuelve false.

Ejemplo:

var x = new VByteArray();
x.isEmpty(); // returns true
x.setText("")
x.isEmpty(); // returns true
x.setText("abc")
x.isEmpty(); // returns false

Boolean isNull()

Devuelve true si el byte array es nulo, en caso contrario devuelve false.

Ejemplo:

var x = new VByteArray();
x.isNull(); // returns true
x.setText("")
x.isNull(); // returns false
x.setText("abc")
x.isNull(); // returns false

Number lastIndexOf( VByteArray other, Number nFrom = 0 )

Devuelve la posición del índice correspondiente al byte donde comienza la primera ocurrencia del byte array especificado en el parámetro en el byte array sobre el que se aplica la función. La búsqueda comienza en el byte especificado en el segundo parámetro, como es opcional si no se especifica la búsqueda comienza desde el final del byte array. Esta búsqueda se realiza hacia atrás, es decir desde el final hasta el principio. Devuelve -1 si no se ha encontrado.

Parámetros:

• other: objeto de la clase VByteArray cuyo buffer será comparado.

• nFrom: número de byte desde el que comienza la comparación. El primer byte es el 0.

Ejemplo:

var x = new VByteArray();
x.setText("crazy azimuths");
var y = new VByteArray();
y.setText("az");
x.lastIndexOf(y); // returns 6
x.lastIndexOf(y, 6); // returns 6
x.lastIndexOf(y, 5); // returns 2
x.lastIndexOf(y, 1); // returns -1

Boolean startsWith( VByteArray other )

Devuelve true si el buffer del byte array sobre el que se aplica la función comienza con el buffer del byte array especificado en el parámetro, en caso contrario devuelve false.

Parámetros:

• other: objeto de la clase VByteArray cuyo buffer será comparado.

Ejemplo:

var url = new VByteArray();
url.setText("ftp://ftp.qt.nokia.com/");
if (url.startsWith("ftp:")) {
...

Ejemplos

1. Convertir texto en base64 a Latin-1

// --------------------------------------------------------------------------------
// Convertir texto en base64 a Latin-1
// ------------------------------------

var ba64 = new VByteArray();
ba64.setText( "UXQgaXMgZ3JlYXQh" );

var ba4 = new VByteArray();
ba4.fromBase64(ba64);

alert(  ba4.toLatin1String() );

2. En un proceso de ficha, convertir un campo objeto dibujo a base64

importClass("VImage");
importClass("VByteArray");

//Inicializamos un objeto imagen y un byteArray
var img = new VImage();
var imgByteArray = new VByteArray();

//Asignamos el campo objeto dibujo del registro al objeto imagen
img=theRegisterIn.fieldToImage("FOTO");

//Guardamos la imagen en un byteArray
imgByteArray = img.saveToData("JPG", -1);

//Convertimos la imagen a base64 y luego a cadena para poder pasarla luego a un webservice, por ejemplo
imgBase64Txt = imgByteArray.toBase64().toLatin1String();

3. Función que Devuelve una cadena con el valor de una imagen en base64

//Parámetros:
//VImage: imagen (requerido) objeto de la clase VImage con la imagen a convertir

function imagenToBase64(imagen) {

    var byteArray = new VByteArray();
    byteArray = imagen.saveToData("PNG",0);
    var imagenBase64 = byteArray.toBase64().toLatin1String();
    return imagenBase64;
}

4. Función que Devuelve una imagen a partir de una cadena en base64

//Parámetros:
//imagenBase64: cadena que contiene una imagen en formato base 64

function imagenFromBase64(imagenBase64) {

    // Convertimos el buffer en base64 en un byteArray
    var ba = new VByteArray();
    var ba64 = new VByteArray();
    ba.setText(imagenBase64);
    ba64.fromBase64(ba);

    // Intentamos obtener la imagen en 4 formatos diferentes soportados
    var imagen = new VImage();

    imagenOk = imagen.loadFromData(ba64, "PNG");
    if (imagenOk == false) { imagenOk = imagen.loadFromData(ba64, "JPG"); }
    if (imagenOk == false) { imagenOk = imagen.loadFromData(ba64, "JPEG"); }
    if (imagenOk == false) { imagenOk = imagen.loadFromData(ba64, "BMP"); }

    // Retornamos la imagen obtenida
    return imagen;
}

5. Convertir string en byte array

// --------------------------------------------------------------------------------
// Copiar un byte array
// --------------------

var ba3 = new VByteArray(ba.length);

for( var x = 0; x < ba.length; ++x) {
   ba3[x] = ba[x];
}

alert( ba3.toLatin1String() );