Formato de datos BSON

Bytes crudos

Para guardar bytes en bruto en el búfer de bytes sin transformaciones, utilice los métodos put_byte y put_bytes. Cada método toma una byte string como argumento y copia esta string en el búfer. El método put_byte aplica que el argumento sea un string de longitud 1. put_bytes acepta cualquier longitud de cadenas. Las cadenas pueden contener bytes nulos.

El siguiente código demuestra cómo guardar bytes sin procesar en un búfer de bytes:

buffer.put_byte("\x00")
buffer.put_bytes("\xff\xfe\x00\xfd")

Métodos de guardar bytes tipificados

Los métodos de guardar descritos en las siguientes secciones guardan objetos de tipos particulares en la especificación BSON. El tipo indicado por el nombre del método tiene prioridad sobre el tipo del argumento. Por ejemplo, si se pasa un valor de punto flotante a put_int32, se convierte en un entero y el driver escribe el entero resultante en el búfer de bytes.

Strings

Para escribir una string UTF-8 (tipo BSON 0x02) en el búfer de bytes, utiliza el método put_string:

buffer.put_string("hello, world")

Las cadenas BSON siempre se codifican en UTF-8. Esto significa que el argumento de put_string debe estar en UTF-8 o en una codificación convertible a UTF-8 (no binaria). Si el argumento está en una codificación distinta de UTF-8, la string se convierte primero a UTF-8 y luego, la versión codificada en UTF-8 se escribe en el búfer. La string debe ser válida en la codificación que se indica. La string puede contener bytes nulos.

La especificación BSON también define un tipo CString, que se utiliza, por ejemplo, para claves de documentos. Para guardar CStrings en el buffer, utiliza put_cstring:

buffer.put_cstring("hello, world")

Al igual que con las cadenas regulares, las CStrings en BSON deben estar codificadas en UTF-8. Si el argumento no se encuentra en UTF-8, será convertido a UTF-8 y la string resultante se escribirá en el buffer. A diferencia de put_string, la codificación UTF-8 del argumento proporcionado a put_cstring no puede contener ningún byte nulo, ya que el formato de serialización CString en BSON está terminado en nulo.

A diferencia de put_string, put_cstring también acepta símbolos y enteros. En todos los casos, el argumento se convierte en cadena antes de ser escrito en el búfer:

buffer.put_cstring(:hello)
buffer.put_cstring(42)

Números

Para guardar un entero de 32bits o de 64bits en el búfer de bytes, usa los métodos put_int32 y put_int64, respectivamente. Ten en cuenta que los enteros Ruby pueden ser arbitrariamente grandes; si el valor que se escribe excede el rango de un entero de 32bits o de 64bits, put_int32 y put_int64 lanzan un error RangeError.

El siguiente código demuestra cómo se pueden guardar valores enteros en un búfer de bytes:

buffer.put_int32(12345)
buffer.put_int64(123456789012345)

Para guardar un valor de punto flotante de 64 bits en el búfer de bytes, utiliza put_double:

buffer.put_double(3.14159)

Convertir bytes en cadenas

Para recuperar los datos serializados como una cadena de bytes, llama a to_s en el buffer:

buffer = BSON::ByteBuffer.new
buffer.put_string('testing')
socket.write(buffer.to_s)

Métodos UUID

Para crear un UUID BSON::Binary (subtipo binario 4) a partir de su representación string compatible con RFC 4122, utiliza el método from_uuid:

uuid_str = "00112233-4455-6677-8899-aabbccddeeff"
BSON::Binary.from_uuid(uuid_str)
# => <BSON::Binary:0x46986653612880 type=uuid data=0x0011223344556677...>

Para convertir un UUID BSON::Binary en una representación compatible con RFC 4122, utiliza el método to_uuid:

binary = BSON::Binary.new("\x00\x11\x22\x33\x44\x55\x66\x77\x88\x99\xAA\xBB\xCC\xDD\xEE\xFF".force_encoding('BINARY'), :uuid)
# => <BSON::Binary:0x46942046606480 type=uuid data=0x0011223344556677...>
binary.to_uuid
# => "00112233-4455-6677-8899aabbccddeeff"

Puedes especificar explícitamente la representación estándar de UUID en los métodos from_uuid y to_uuid:

binary = BSON::Binary.from_uuid(uuid_str, :standard)
binary.to_uuid(:standard)

Puede usar la representación :standard solo con un valor Binary de subtipo :uuid, no :uuid_old.

UUIDs heredados

Los datos almacenados en objetos BSON::Binary de subtipo 3 (:uuid_old) pueden persistirse en alguno de los tres diferentes órdenes de bytes, dependiendo del controlador que los creó. Los órdenes de bytes son heredado de CSharp, heredado de Java y heredado de Python. El orden de bytes heredado de Python es el mismo que el orden de bytes estándar de la RFC 4122. Los órdenes de bytes heredados de CSharp y Java tienen algunos bytes en ubicaciones diferentes.

El objeto Binary que contiene un UUID heredado no codifica en qué formato se almacena el UUID. Por lo tanto, los métodos que convierten hacia y desde el formato UUID heredado toman el formato deseado, o representación, como su argumento. Una aplicación puede copiar objetos UUID heredados Binary sin saber en qué orden de bytes almacenan sus datos.

Se proporcionan los siguientes métodos para trabajar con UUIDs antiguos para garantizar la interoperabilidad con implementaciones existentes que almacenan datos en formatos antiguos de UUIDs. En nuevas aplicaciones, utiliza solo el formato :uuid (subtipo 4), que cumple con RFC 4122.

Para serializar un UUID heredado BSON::Binary, utiliza el método to_uuid y especifica la representación deseada. Las representaciones aceptadas son :csharp_legacy, :java_legacy y :python_legacy. Un UUID heredado BSON::Binary no puede convertirse a texto sin especificar una representación.

binary = BSON::Binary.new("\x00\x11\x22\x33\x44\x55\x66\x77\x88\x99\xAA\xBB\xCC\xDD\xEE\xFF".force_encoding('BINARY'), :uuid_old)
# => <BSON::Binary:0x46942046606480 type=uuid data=0x0011223344556677...>
binary.to_uuid
# => ArgumentError (Representation must be specified for BSON::Binary objects of type :uuid_old)
binary.to_uuid(:csharp_legacy)
# => "33221100-5544-7766-8899aabbccddeeff"
binary.to_uuid(:java_legacy)
# => "77665544-3322-1100-ffeeddccbbaa9988"
binary.to_uuid(:python_legacy)
# => "00112233-4455-6677-8899aabbccddeeff"

Para crear un UUID heredado BSON::Binary a partir de la representación en string del UUID, utiliza el método from_uuid y especifica la representación deseada:

uuid_str = "00112233-4455-6677-8899-aabbccddeeff"
BSON::Binary.from_uuid(uuid_str, :csharp_legacy)
# => <BSON::Binary:0x46986653650480 type=uuid_old data=0x3322110055447766...>
BSON::Binary.from_uuid(uuid_str, :java_legacy)
# => <BSON::Binary:0x46986653663960 type=uuid_old data=0x7766554433221100...>
BSON::Binary.from_uuid(uuid_str, :python_legacy)
# => <BSON::Binary:0x46986653686300 type=uuid_old data=0x0011223344556677...>

Puede utilizar estos métodos para convertir de una representación a otra:

BSON::Binary.from_uuid('77665544-3322-1100-ffeeddccbbaa9988',:java_legacy).to_uuid(:csharp_legacy)
# => "33221100-5544-7766-8899aabbccddeeff"

Convertir vectores a binario

Puede convertir BSON::Vector y objetos de arreglo a objetos BSON::Binary para que se serialicen como instancias binarias de vector BSON (subtipo 9). Utiliza el método BSON::Binary.from_vector, como se muestra en el siguiente código:

vector = BSON::Vector.new([ -0.0016261312, -0.028070757, -0.011342932 ], :float32)
BSON::Binary.from_vector(vector)

Usar el tipo BSON::Binary mejora la eficiencia de almacenamiento. Para obtener más información, consulta la especificación BSON.

Puedes convertir un BSON::Binary en un BSON::Vector utilizando el método BSON::Binary.as_vector.

BSON::Decimal128 y BigDecimal

Los métodos BigDecimal#from_bson y BigDecimal#to_bson utilizan internamente los métodos equivalentes BSON::Decimal128. Esto lleva a algunas limitaciones en los valores de BigDecimal que se pueden serializar a BSON y en aquellos que se pueden deserializar a partir de valores de BSON decimal128 existentes.

Serializar instancias de BigDecimal como instancias de BSON::Decimal128 permite una mayor flexibilidad al realizar consultas y agregaciones en MongoDB. La siguiente lista describe las limitaciones en BigDecimal:

• Decimal128 tiene un rango y precisión limitados, mientras que BigDecimal no tiene restricciones en cuanto a rango y precisión. Decimal128 tiene un valor máximo de aproximadamente 10^6145 y un valor mínimo de aproximadamente -10^6145, y tiene un máximo de 34 bits de precisión.

• Decimal128 puede aceptar valores firmados de NaN, mientras que BigDecimal no. Todos los valores NaN firmados que se deserialicen en instancias BigDecimal serán sin signo.

• Decimal128 mantiene los ceros finales al serializar a BSON y deserializar desde BSON. BigDecimal, sin embargo, no mantiene ceros finales y por lo tanto usar BigDecimal puede resultar en una falta de precisión.

Opciones, banderas y modificadores

Tanto las expresiones regulares de Ruby como las de PCRE admiten modificadores. Estos también se llaman "opciones" en contextos de Ruby y "banderas" en contextos de PCRE. El significado de los modificadores s y m difiere en Ruby y PCRE de las siguientes maneras:

• Ruby no tiene el modificador s. En cambio, el modificador m de Ruby cumple la misma función que el modificador s de PCRE, que es hacer que el punto (.) coincida con cualquier carácter, incluidas las nuevas líneas. La documentación de Ruby se refiere al modificador m como habilitador del modo multilínea.

• Ruby siempre opera en el equivalente del modo multinea de PCRE, activado por el modificador m en expresiones regulares PCRE. En Ruby, el ancla ^ siempre se refiere al comienzo de línea y el ancla $ siempre se refiere al final de línea.

Cuando escriba expresiones regulares destinadas a utilizarse tanto en entornos Ruby como en entornos PCRE, incluidos el Servidor MongoDB y la mayoría de los demás controladores de MongoDB, evite utilizar los anclajes ^ y $. Las siguientes secciones proporcionan soluciones alternativas y recomendaciones para elaborar expresiones regulares portátiles que puedan utilizarse en múltiples contextos.

^ Ancla

En las expresiones regulares de Ruby, el ancla ^ siempre se refiere al principio de la línea. En las expresiones regulares de PCRE, el anclaje ^ se refiere al principio de la entrada por defecto, y la bandera m cambia su significado al principio de la línea.

Tanto las expresiones regulares de Ruby como las de PCRE admiten el ancla \A para referirse al principio de la entrada, independientemente de los modificadores. Las siguientes sugerencias permiten escribir expresiones regulares portátiles:

• Usa el ancla \A para referirse al inicio de la entrada.

• Utiliza el anclaje ^ para hacer referencia al inicio de la línea si estableces el indicador m en las expresiones regulares de PCRE. Alternativamente, utiliza uno de los siguientes constructos que funcionan independientemente de los modificadores:

  • (?:\A|(?<=\n)): gestiona LF y CR+LF finales de línea

  • (?:\A|(?<=[\r\n]))Gestiona los finales de línea CR, LF y CR+LF

$ Ancla

En las expresiones regulares de Ruby, el ancla $ siempre se refiere al final de la línea. En expresiones regulares PCRE, el ancla $ se refiere al final de la entrada por defecto y la bandera m cambia su significado al final de la línea.

Tanto las expresiones regulares de Ruby como las de PCRE admiten el ancla \z para referirse al final de la entrada, independientemente de los modificadores.

Las siguientes sugerencias le permiten escribir expresiones regulares portátiles:

• Utilice el \z ancla para referirse al final de la entrada.

• Utiliza el anclaje $ para hacer referencia al inicio de la línea si estableces el indicador m en las expresiones regulares de PCRE. Alternativamente, utiliza uno de los siguientes constructos que funcionan independientemente de los modificadores:

  • (?:\z|(?=\n)): gestiona LF y CR+LF finales de línea

  • (?:\z|(?=[\n\n]))Gestiona los finales de línea CR, LF y CR+LF