SDL_bsearch_r(3)

✨ SDL_bsearch_r(3) ✨

okay bestie, welcome to the SDL3 FUNCTIONS corner of the manual, where we're talking about SDL_bsearch_r — the binary search that lets you pass a lil userdata pointer to your compare function 🫶

---

🌸 NAME 🌸

SDL_bsearch_r — Perform a binary search on a previously sorted array, passing a userdata pointer to the compare function.

---

🎀 SYNOPSIS 🎀

#include <SDL3/SDL_stdinc.h>

void * SDL_bsearch_r(const void *key, const void *base, size_t nmemb, size_t size, SDL_CompareCallback_r compare, void *userdata);

---

💅 DESCRIPTION 💅

so like, imagine you have an array that you've already sorted (key word: already, do not skip that step, i'm serious 😭) and now you wanna find one specific thing in it. that's the whole vibe here. binary search. iconic. fast. slay.

For example:

typedef enum {
    sort_increasing,
    sort_decreasing,
} sort_method;

typedef struct {
    int key;
    const char *string;
} data;

int SDLCALL compare(const void *userdata, const void *a, const void *b)
{
    sort_method method = (sort_method)(uintptr_t)userdata;
    const data *A = (const data *)a;
    const data *B = (const data *)b;

    if (A->key < B->key) {
        return (method == sort_increasing) ? -1 : 1;
    } else if (B->key < A->key) {
        return (method == sort_increasing) ? 1 : -1;
    } else {
        return 0;
    }
}

data values[] = {
    { 1, "first" }, { 2, "second" }, { 3, "third" }
};
data key = { 2, NULL };

data *result = SDL_bsearch_r(&key, values, SDL_arraysize(values), sizeof(values[0]), compare, (const void *)(uintptr_t)sort_increasing);

see how the compare function gets that userdata pointer and just uses it to decide which direction it's sorting? that's the "_r" part bestie, that's the whole point 💖

---

🦋 FUNCTION PARAMETERS 🦋

• key — a pointer to a key equal to the element being searched for. the thing you're hunting for 🔍
• base — a pointer to the start of the array. where it all begins ✨
• nmemb — the number of elements in the array. count them, girl 💅
• size — the size of the elements in the array. yes, each one 🎀
• compare — a function used to compare elements in the array. the little matchmaker 🫶
• userdata — a pointer to pass to the compare function. your lil extra info, hand-delivered 📦

---

⭐ RETURN VALUE ⭐

Returns a pointer to the matching element in the array, or NULL if not found. so if you get NULL back... she's not there, bestie, no cap 💀

---

🔥 THREAD SAFETY 🔥

It is safe to call this function from any thread. main character energy in every thread, we love to see it 👑

---

🌈 AVAILABILITY 🌈

This function is available since SDL 3.2.0. so if you're on something older, that's a you problem, update babe 🙈

---

👑 SEE ALSO 👑

• SDL_bsearch(3)
• SDL_qsort_r(3)

---

and that's the tea, bestie 💜 this lil page came to you from Simple Directmedia Layer, serving SDL 3.4.18, and it's filed under SDL_bsearch_r(3) if you ever need to find it again. go sort something and then go find it. periodt. 🎀✨