BSON_APPEND_SYMBOL(3)

💅 BSON_APPEND_SYMBOL(3) 💅

okay so bestie, welcome to the libbson manual, page BSON_APPEND_SYMBOL(3) — yes the title is a whole mouthful, but honestly it's giving "tiny convenience macro with a big job" energy and we're gonna get through it together 💖

---

✨ SYNOPSIS ✨

here's the whole thing, exactly as it lives in the header, no cap:

#define BSON_APPEND_SYMBOL(b, key, val) \
   bson_append_symbol (b, key, (int) strlen (key), val, (int) strlen (val))

bool
bson_append_symbol (bson_t *bson,
                    const char *key,
                    int key_length,
                    const char *value,
                    int length);

so the macro is literally just a lil' wrapper that does the strlen() math for you so you don't have to, and the real grown-up function underneath is bson_append_symbol(). slay 🎀

---

🦋 PARAMETERS 🦋

okay so the cast of characters, let's meet them:

• bson — A bson_t. that's the document you're stuffing stuff into, she's the main character here 👑
• key — An ASCII C string containing the name of the field. like the label on the lil' box 🏷️
• key_length — The length of key in bytes, or -1 to determine the length with strlen(). so -1 is the "girl math it for me" option 💅
• value — The symbol. this is the actual thing going in 📦
• length — A length of symbol in bytes, or -1 to determine the length with strlen(). same deal, -1 means let strlen() handle it ✨

---

🌸 DESCRIPTION 🌸

so what does she do? Appends a new field to bson of type BSON_TYPE_SYMBOL. simple enough right?

⚠️ but bestie, listen to me: This BSON type is deprecated and should not be used in new code. like, she's iconic but she's also retired. we respect her legacy from a distance 🙈

now here's the messy part. Due to legacy behavior, passing NULL for value appends a null value, not a symbol value. yeah. I know. 😭 it's giving plot twist. so if what you actually want is a null value, please just do the normal thing — To append a null value directly, prefer using bson_append_null(). cleaner, safer, no weird legacy surprises 🫶

---

⭐ RETURNS ⭐

Returns true if the operation was applied successfully 💖

but note — The function will fail if appending the value grows bson larger than INT32_MAX. so like, don't try to be extra with it, there's a size limit and she means it 💀

---

🧚 AUTHOR 🧚

MongoDB, Inc — the legends themselves 😌

---

🌈 COPYRIGHT 🌈

2009-present, MongoDB, Inc. all the rights, reserved, periodt ✨

---

okay that's the whole page!! you made it, I'm so proud 🥹 this was libbson version 2.5.6, dated Oct 09, 2026, signing off — go forth and don't use deprecated symbol types, mwah 💋💜