azulC library functions are always like: "SYNOPSIS. This function converts foos into bars depending on the user locale. ARGUMENTS. src and dest pointers must be distinct; it is undefined behavior if they are not QPU-aligned. RETURN VALUE. Returns the number of foos converted. A zero value indicates failure, or that zero foos were converted. A negative value indicates that the final foo was only partially converted (function got tired). Check this global variable to find out why."
Billy O'Neal@typeswitch @thephd You forgot "flags is a bit mask of 22 bits some of which can be used together and some of which can not which make this function do totally different things"
Sean Murthy@smurthys @typeswitch @thephd The best part is that this isn't even really much of a straw man. https://learn.microsoft.com/en-us/windows/win32/api/stringapiset/nf-stringapiset-widechartomultibyte
@malwareminigun @typeswitch @thephd The beloved `dwFlags` parameter. These two gems on that page, are just 😗:
The function performs more quickly when none of these flags is set.
If all three values are not provided, some results will be missing.
Pär Björklund@malwareminigun @smurthys @typeswitch @thephd the win32 is pretty great, the size of it all means it contains just about every API design issue one can think of, now, in hindsight 😀
I do actually like it overall though
@Paxxi I didn't intend to rip on Win32 specifically here; lots of C APIs are horrible. And I'll take a lot of these to one fork(). An API that looks basic but has far-reaching implications, makes accurate memory use tracking impossible, and generally creates cross cutting costs against the whole system. Whereas these examples are contained to only their immediate callers.
@malwareminigun I totally agree, and as I said I generally like the win32 api 😀
dominic → @@malwareminigun @typeswitch @thephd a personal favorite is "given this flag, the type of parameter 3 changes from T* to T**"