BSON_APPEND_VE...BIT_FROM_ARRAY(3)

📦
version 2.5.6 · 3 versions
, in epel 10

💅 BSON_APPEND_VECTOR_PACKED_BIT_FROM_ARRAY(3) ✨

okay so bestie, this is a page from libbson — the BSON_APPEND_VE...BIT_FROM_ARRAY one (yes the title is literally truncated with an ellipsis, that's just how the man page is named, don't come for her 💀). Sit down, hydrate, and let's get into it 🫶

✨ SYNOPSIS ✨

#define BSON_APPEND_VECTOR_PACKED_BIT_FROM_ARRAY(b, key, iter, err) \
   bson_append_vector_packed_bit_from_array (b, key, (int) strlen (key), iter, err)

bool
bson_append_vector_packed_bit_from_array (bson_t *bson,
                                          const char *key,
                                          int key_length,
                                          const bson_iter_t *iter,
                                          bson_error_t *error);

so there's a convenience macro up top that just fills in key_length for you using (int) strlen (key) — she's doing the math so you don't have to 🎀 — and then the actual real-deal function underneath. Copy those exactly, no cap.

🌸 PARAMETERS 🌸

  • bson — a bson_t. this is the doc you're appending into, the main character of the whole operation 👑
  • key — an ASCII C string holding the name of the field. keep it ASCII, bestie.
  • key_length — how long key is, in bytes. or pass -1 and she'll figure it out with strlen(). iykyk 💅
  • iter — a bson_iter_t that's referencing the array elements that are about to get converted 🔥
  • error — an optional bson_error_t where the juicy details about any conversion failure land. optional, so you can absolutely pass nothing and simply vibe in ignorance 🙈

🦋 DESCRIPTION 🦋

So what she does: she appends a new field to bson by converting an Array into a Vector of packed_bit elements. it's giving glow-up, it's giving type transformation ✨

Now for the conversion to actually succeed, every single item in the Array has to be one of these two things, periodt:

  • an integer (BSON_TYPE_INT32 or BSON_TYPE_INT64) whose value is either 0 or 1, or
  • a boolean (BSON_TYPE_BOOL).

that's the whole guest list. if any element is the wrong type or has an out-of-range value, the conversion just fails — you get an error message with the details, and here's the important bit: no changes are made to bson. none. not even a little. she's not messy, she's all-or-nothing 💀

and about that iter: it must be positioned just prior to the first element of the BSON Array. like, right before. not on it, not after it. so:

  • if your input is a bare BSON Array, set up iter using bson_iter_init() 🌈
  • if the input lives within a document field, use bson_iter_recurse() 🧚

get the positioning wrong and it's not gonna slay, sorry.

💖 RETURNS 💖

Returns true if the operation applied successfully — slay, we love to see it 🎀

On error it returns false and writes extra error info into error, all without modifying bson. The error will have a domain of BSON_ERROR_VECTOR and a code from bson_vector_error_code_t. so when you're debugging, that's exactly where you look 👑

⭐ AUTHOR ⭐

MongoDB, Inc — iconic, honestly.

2009-present, MongoDB, Inc.

bestie reminder: wrong element type or a value outside 0/1 = total failure, and bson stays untouched. that's the one thing to tattoo on your brain 🫶

k bye, this page was brought to you by libbson 2.5.6, dated Oct 09 — go forth and append responsibly, mwah 💋✨

📦 where this page comes from