From: Lady <redacted>
Date: Thu, 20 Mar 2025 03:59:56 +0000 (-0400)
Subject: Document and improve `request.h´
X-Git-Url: https://git.ladys.computer/CGirls/commitdiff_plain/259adc84f29a70aa2ba33f1eaa7f6a461bb51759?ds=sidebyside;hp=259adc84f29a70aa2ba33f1eaa7f6a461bb51759

Document and improve `request.h´

Mostly, this commit just adds documentation comments to `request.h´ to
fully explain its behaviour, including renaming some things for
stylistic reasons. How·ever, it does make one significant change:

It reverts the definition of `cgirls_mtype´ and `cgirls_vb´ back to
enums.

Previously, I thought that it might be possible to be clever and
define these as `constexpr´ strings. That would enable them to be
serialized by string value and compared by pointer value, perhaps
offering the best of both worlds. And this worked in initial tests!

Unfortunately, `constexpr´ declarations have internal linkage, which
means that a ⹐different⹑ object is created for each translation unit
(file). This renders the existence of these `constexpr´s essentially
use·less in a header file, since nobody outside of `request.c´ will
have the same pointers that `request.c´ has.

(This C “feature” is presumably to help guarantee constancy, since
anything with `extern´ linkage cannot be truly guaranteed to be
constant.)

The new approach goes back to enums but provides `static const*const´
arrays which map those enums to string values. This of course means the
enums need to be roughly sequential, and one needs to check that a
given index is actually in bounds and does not point to `nullptr´
before using its associated value. Defining the enums as
`unsigned char´ at least means they can never be negative.
---