BSON_STEAL(3)

💅 BSON_STEAL(3) — the libbson glow-up transfer 💅

okay bestie, so this is page BSON_STEAL(3) from the libbson manual, and honestly? it's giving "give me your whole personality" but in a polite, memory-safe way. no cap. 🦋

---

✨ SYNOPSIS ✨

bool
bson_steal (bson_t *dst, bson_t *src);

that's it. that's the whole function signature. iconic. 🎀

---

🌸 PARAMETERS 🌸

• dst — an uninitialized bson_t. like, it has to be a blank slate, a fresh-faced baby, nothing in it yet. 🐣
• src — a bson_t. a real one. an actual filled-in bson document.

---

💖 DESCRIPTION 💖

the way that this function efficiently transfers the contents of src to dst and then destroys src… obsessed. it's a full-on move-out, no forwarding address, src is gone. 💀

⚠️ okay so before you call this, listen up: src must be initialized and dst must be uninitialized. that's the whole vibe check. after this function returns successfully, src is destroyed, and dst is initialized and must be freed with bson_destroy(). don't forget that part, bestie, that's how you get leaks. 😭

for example — say you have a higher-level structure that wraps a bson_t, and you wanna use bson_steal to transfer BSON data into it. main character energy:

typedef struct {
   bson_t bson;
} bson_wrapper_t;

bson_wrapper_t *
wrap_bson (bson_t *b)
{
   bson_wrapper_t *wrapper = bson_malloc (sizeof (bson_wrapper_t));

   if (bson_steal (&wrapper->bson, b)) {
      return wrapper;
   }

   bson_free (wrapper);
   return NULL;
}

void
bson_wrapper_destroy (bson_wrapper_t *wrapper)
{
   bson_destroy (&wrapper->bson);
   bson_free (wrapper);
}

int
main (int argc, char *argv[])
{
   bson_t bson = BSON_INITIALIZER;
   bson_wrapper_t *wrapper;

   BSON_APPEND_UTF8 (&bson, "key", "value");

   /* now "bson" is destroyed */
   wrapper = wrap_bson (&bson);

   /* clean up */
   bson_wrapper_destroy (wrapper);
}

see how the comment literally says /* now "bson" is destroyed */? not me being dramatic, that's just the truth. 🔥

---

🫶 RETURNS 🫶

returns true if src was successfully moved to dst. slay. 💅

returns false if src is invalid, or was statically initialized, or another error occurred. in that case, no move, no party. 🙈

SEE ALSO:

• bson_destroy_with_steal() — a lower-level function that returns the raw contents of a bson_t. iykyk, this one's the deep lore. 👑

---

👑 AUTHOR 👑

MongoDB, Inc — yes, that MongoDB. royalty. 🌈

---

⭐ COPYRIGHT ⭐

2009-present, MongoDB, Inc. — all rights reserved, all vibes reserved. 🍓

---

and that's the whole page, bestie! 💜 cute little sign-off for you: this was libbson version 2.5.6, dated Oct 09, 2026, and it lives at BSON_STEAL(3). go forth and steal (bson contents, legally) 🧚✨