SDL_clamp(3)

📦
version 3.4.18 · 9 versions
, in fedora 43, fedora 44

💖 SDL_clamp — the manual page, but make it make sense 💖

okay bestie, welcome to the SDL3 FUNCTIONS corner of the docs, where today's main character is SDL_clamp(3). she's small, she's a macro, and she's lowkey carrying every "keep this number in range" moment in your codebase. let's get into it 🫶

✨ NAME ✨

SDL_clamp — Return a value clamped to a range.

like, she takes your number and squishes it into the box you gave her. that's the whole vibe. 💅

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_stdinc.h>

#define SDL_clamp(x, a, b) (((x) < (a)) ? (a) : (((x) > (b)) ? (b) : (x)))

no cap, that's the entire macro right there. three params, two comparisons, one little nested ternary doing her absolute best. ✨

🦋 DESCRIPTION 🦋

so here's the tea: if x is outside the range of values between a and b, the value you get back will be a or b, whichever one is appropriate for the situation. and if x is already chilling inside that range? then you just get x back. she didn't need to change a thing. queen behavior. 👑

⚠️ but listen — this macro will produce incorrect results if b is less than a. like, that's not a vibe, that's a bug generator. don't do it. fr fr. 💀

this is a helper macro, and the reason she exists is that she might be more clear than writing out the comparisons directly by hand. she works with any type that can be compared with the < and > operators — so she's flexible, she's inclusive, she's for everybody. 🌈

however — and this is the part you need to hear — she double-evaluates all her parameters. so do not use expressions with side-effects here. no i++, no function calls that change stuff, none of that. she'll run them twice and you'll be sitting there like 🙈 wondering why your counter jumped by two. side effects stay OUT of the macro. periodt.

🎀 MACRO PARAMETERS 🎀

  • x — the value to compare. this is your girl, the one getting checked. 🍓
  • a — the low end value. the floor. the "at minimum" energy.
  • b — the high end value. the ceiling. the "no further than this" boundary.

💜 RETURN VALUE 💜

Returns x, clamped between a and b. that's it, that's the whole return. she comes back with a number, and that number is inside your range, guaranteed (as long as b ≥ a, bestie, we covered this 😭).

🧚 THREAD SAFETY 🧚

It is safe to call this macro from any thread. go wild, spawn those threads, she does not care, she is not here for drama. 🫶

⭐ AVAILABILITY ⭐

This macro is available since SDL 3.2.0. if you're on something older, sorry babe, she hadn't been born yet. 💅

and that's the whole page!! short, sweet, iconic, ate and left no crumbs. go clamp something responsibly. 🌸💖✨

— with love from the Simple Directmedia Layer girlies, SDL 3.4.18, SDL_clamp(3) out 🎀🦋💜

📦 where this page comes from