Formato de dados do documento: BSON

Bytes brutos

Para escrever bytes brutos no buffer de bytes sem transformações, use os métodos put_byte e put_bytes. Cada método usa uma string de bytes como argumento e copia essa string para o buffer. O método put_byte impõe que o argumento é uma string de comprimento 1. put_bytes aceita qualquer comprimento de strings. As strings podem conter bytes nulos.

O seguinte código demonstra como escrever bytes brutos em um buffer de bytes:

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

Métodos de gravação de bytes digitados

Os métodos de gravação descritos nas seções a seguir gravam objetos de tipos específicos na especificação BSON. O tipo indicado pelo nome do método tem precedência sobre o tipo do argumento. Por exemplo, se um valor de ponto flutuante for passado para put_int32, ele será forçado em um número inteiro, e o driver gravará o número inteiro resultante no buffer de bytes.

Strings

Para escrever uma string UTF-8 (BSON tipo 0x02) no buffer de bytes, use o método put_string:

buffer.put_string("hello, world")

As strings JSON são sempre codificadas em UTF-8. Isso significa que o argumento para put_string deve estar em UTF-8 ou em uma codificação convertível em UTF-8 (não binária). Se o argumento estiver em uma codificação diferente de UTF-8, a string será primeiro convertida em UTF-8 e, em seguida, a versão codificada em UTF-8 será gravada no buffer. A string deve ser válida na codificação solicitada. A string pode conter bytes nulos.

A especificação BSON também define um tipo CString, que é usado, por exemplo, para chaves de documento . Para escrever CStrings no buffer, use put_cstring:

buffer.put_cstring("hello, world")

Assim como nas strings regulares, as CStrings em BSON devem ser codificadas em UTF-8. Se o argumento não estiver em UTF-8, ele será convertido em UTF-8 e a string resultante será gravada no buffer. Ao contrário de put_string, a codificação UTF-8 do argumento fornecido a put_cstring não pode ter nenhum byte nulo, pois o formato de serialização CString em BSON é terminado em nulo.

Ao contrário de put_string, put_cstring também aceita símbolos e números inteiros. Em todos os casos, o argumento é string antes de ser gravado no buffer:

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

Números

Para escrever um número inteiro de 32bits ou 64bits no buffer de bytes, use os métodos put_int32 e put_int64, respectivamente. Observe que os números inteiros Ruby podem ser arbitrariamente grandes; se o valor que está sendo gravado exceder o intervalo de um 32bits ou um número inteiro de 64bits, put_int32 e put_int64 gerarão um erro RangeError.

O seguinte código demonstra como escrever valores inteiros em um buffer de bytes:

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

Para escrever um valor de ponto flutuante de 64 bits no buffer de bytes, use put_double:

buffer.put_double(3.14159)

Converter bytes em strings

Para recuperar os dados serializados como uma string de bytes, chame to_s no buffer:

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

Métodos de UUID

Para criar um UUID BSON::Binary (subtipo binário 4) a partir de sua representação de string compatível com RFC 4122, use o 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 restringir um UUID BSON::Binary a uma representação compatível com RFC 4122, use o 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"

Você pode especificar explicitamente a representação padrão do UUID nos métodos from_uuid e to_uuid:

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

Você pode usar a representação :standard somente com um valor Binary do subtipo :uuid, não :uuid_old.

UUIDs legados

Os dados armazenados em BSON::Binary objetos de subtipo 3 (:uuid_old) podem ser persistentes em uma das três ordens de bytes diferentes, dependendo do driver que criou os dados. As ordens de bytes são legado C# , legado Java e legado Python . A ordem de bytes legado do Python é a mesma que a ordem de bytes padrão da RFC 4122. As ordens de bytes C# legado e Java legado têm alguns dos bytes em locais diferentes.

O objeto Binary que contém um UUID legado não codifica em qual formato o UUID está armazenado. Portanto, os métodos que convertem de e para o formato UUID legado utilizam o formato, ou representação, como argumento. Um aplicação pode copiar objetos legado do UUID Binary sem saber em qual ordem de bytes eles armazenam seus dados.

Os métodos a seguir para trabalhar com UUIDs legado são fornecidos para interoperabilidade com sistemas existentes que armazenam dados em formatos UUID legado . Em novos aplicativos, use somente o formato :uuid (subtipo 4), que é compatível com RFC 4122.

Para stringificar um UUID legado BSON::Binary, utilize o método to_uuid e especifique a representação desejada. As representações aceitas são :csharp_legacy, :java_legacy e :python_legacy. Um UUID BSON::Binary legado não pode ser em string sem especificar uma representação.

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 criar um UUID legado BSON::Binary a partir da representação de string do UUID, utilize o método from_uuid e especifique a representação desejada:

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...>

Você pode usar esses métodos para converter de uma representação para outra:

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

Converter vetores em binário

Você pode converter BSON::Vector e objetos de array em objetos BSON::Binary para que sejam serializados como instâncias de vetor binário BSON (subtipo 9). Use o método BSON::Binary.from_vector, conforme mostrado no código a seguir:

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

Usar o tipo BSON::Binary melhora a eficiência do armazenamento. Para saber mais, consulte a especificação BSON.

Você pode converter um BSON::Binary para um BSON::Vector utilizando o método BSON::Binary.as_vector.

BSON::Decimal128 e BigDecimal

Os métodos BigDecimal#from_bson e BigDecimal#to_bson utilizam os métodos BSON::Decimal128 equivalentes internamente. Isso leva a algumas limitações nos valores BigDecimal que podem ser serializados para BSON e aqueles que podem ser desserializados a partir de valores BSON decimal128 existentes.

A serialização de instâncias BigDecimal como instâncias BSON::Decimal128 permite mais flexibilidade ao consultar e executar agregações no MongoDB. A seguinte lista descreve as limitações no BigDecimal:

• Decimal128 tem alcance e precisão limitados, enquanto BigDecimal não tem restrições em termos de alcance e precisão. Decimal128 tem um valor máximo de aproximadamente 10^6145 e um valor mínimo de aproximadamente -10^6145, e tem um máximo de 34 bits de precisão.

• Decimal128 é capaz de aceitar valores de NaN assinados, enquanto BigDecimal não é. Todos os valores NaN assinados que são desserializados em instâncias BigDecimal não serão assinados.

• Decimal128 mantém os zeros finais ao serializar e desserializar do BSON. BigDecimal, no entanto, não mantém zeros à direita e, portanto, usar BigDecimal pode resultar em falta de precisão.

Opções, sinalizadores e modificadores

As expressões regulares Ruby e PCRE suportam modificadores. Eles também são chamados de "opções" em contextos Ruby e "sinalizadores" em contextos PCRE. O significado dos modificadores s e m difere em Ruby e PCRE das seguintes maneiras:

• Ruby não tem o modificador s. Em vez disso, o modificador Ruby m executa a mesma função que o modificador PCRE s, que é fazer com que o ponto (.) corresponda a qualquer caractere, incluindo novas linhas. A documentação Ruby refere-se ao modificador m como ativando o modo de várias linhas.

• Ruby sempre opera no equivalente do modo multilinha do PCRE, habilitado pelo modificador m em expressões regulares PCRE. Em Ruby, a âncora ^ sempre se refere ao início da linha e a âncora $ sempre se refere ao final da linha.

Ao escrever expressões regulares destinadas ao uso em ambientes Ruby e PCRE, incluindo o MongoDB Server e a maioria dos outros drivers do MongoDB , evite usar as âncoras ^ e $. As seções a seguir fornecem soluções alternativas e recomendações para a criação de expressões regulares móveis que podem ser usadas em vários contextos.

^ Anchor

Em expressões regulares Ruby, a âncora ^ sempre se refere ao início da linha. Em expressões regulares PCRE, a âncora ^ refere-se ao início da entrada por padrão, e o sinalizador m altera seu significado para o início da linha.

As expressões regulares Ruby e PCRE suportam a âncora \A para se referir ao início da entrada, independentemente dos modificadores. As seguintes sugestões permitem a você escrever expressões regulares portabilidade:

• Use a âncora \A para referir-se ao início da entrada.

• Use a âncora ^ para se referir ao início da linha se você definir o sinalizador m em expressões regulares PCRE. Como alternativa, use uma das seguintes construções que funcionam independentemente dos modificadores:

  • (?:\A|(?<=\n)): lida com LF e CR+LF extremidades de linha

  • (?:\A|(?<=[\r\n])): lida com CR, LF e CR+LF extremidades de linha

$ Anchor

Em expressões regulares Ruby, a âncora $ sempre se refere ao final da linha. Nas expressões regulares PCRE, a âncora $ refere-se ao final da entrada por padrão e o sinalizador m altera seu significado para o final da linha.

As expressões regulares Ruby e PCRE suportam a âncora \z para se referir ao final da entrada, independentemente dos modificadores.

As seguintes sugestões permitem a você escrever expressões regulares portabilidade:

• Use a âncora \z para referir-se ao final da entrada.

• Use a âncora $ para se referir ao início da linha se você definir o sinalizador m em expressões regulares PCRE. Como alternativa, use uma das seguintes construções que funcionam independentemente dos modificadores:

  • (?:\z|(?=\n)): lida com LF e CR+LF extremidades de linha

  • (?:\z|(?=[\n\n])): lida com CR, LF e CR+LF extremidades de linha