Anyone except @hoisagen who has tried this? There is a new release on the horizon and I'm contemplating adding this new API to the library itself. But not without some solid real-world experience proving its adequacy. @siiky @peterlinux2010?

And now it occurs to me that maybe Result.bytes() may itself make a copy..?

No, it does not.

So you are trying to avoid one copy of at most a few hundred bytes? May I ask why? I can assure you that this copy operation is completely dwarfed by the amount of copying and general CPU utilization that is required to come to the point where you have this result.

Does your zxing_read_barcode function use stbi_load... to decode the jpeg internally? May I have a look at the implementation of that function?

I'm running now a comparison benchmark between -std=c++17 and -std=c++20.

Can you let me know the compiler error message and how you fixed it?

The error message:

zxing-c.cpp: In function ‘zxing_BarcodeFormats zxing_BarcodeFormatsFromString(const char*)’:
zxing-c.cpp:50:59: error: dereferencing type-punned pointer will break strict-aliasing rules [-Werror=strict-aliasing]
   50 |                 return static_cast<zxing_BarcodeFormats>(*reinterpret_cast<BarcodeFormat*>(&format));
      |                                                           ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The diff:

diff --git a/wrappers/c/zxing-c.cpp b/wrappers/c/zxing-c.cpp
index befb8b77..c80e16d4 100644
--- a/wrappers/c/zxing-c.cpp
+++ b/wrappers/c/zxing-c.cpp
@@ -46,8 +46,9 @@ zxing_BarcodeFormats zxing_BarcodeFormatsFromString(const char* str)
        if (!str)
                return {};
        try {
-               auto format = BarcodeFormatsFromString(str);
-               return static_cast<zxing_BarcodeFormats>(*reinterpret_cast<BarcodeFormat*>(&format));
+               BarcodeFormats formats = BarcodeFormatsFromString(str);
+               BarcodeFormat * format = reinterpret_cast<BarcodeFormat*>(&formats);
+               return static_cast<zxing_BarcodeFormats>(*format);
        } catch (...) {
                return zxing_BarcodeFormat_Invalid;
        }

So you are trying to avoid one copy of at most a few hundred bytes? May I ask why? I can assure you that this copy operation is completely dwarfed by the amount of copying and general CPU utilization that is required to come to the point where you have this result.

I know, but I have nothing to lose here, and I already had the code anyway.

Does your zxing_read_barcode function use stbi_load... to decode the jpeg internally? May I have a look at the implementation of that function?

zxing_Result * zxing_read_barcode (const void * jpeg, unsigned int len, const char * fmt)
{
	zxing_Result * ret = NULL;
	zxing_ImageView * iv = NULL;

	int width = 0;
	int height = 0;
	uint8_t * buf = (uint8_t *) jpeg_decode(jpeg, len, &width, &height, JPEG_RGB);
	if (!buf) return NULL;

	zxing_DecodeHints * hints = zxing_DecodeHints_new();
	if (!hints) goto free_buf;

	zxing_DecodeHints_setEanAddOnSymbol(hints, zxing_EanAddOnSymbol_Ignore);
	zxing_DecodeHints_setFormats(hints, zxing_BarcodeFormatFromString(fmt));
	zxing_DecodeHints_setTryRotate(hints, true);
	zxing_DecodeHints_setReturnErrors(hints, false);
	zxing_DecodeHints_setMaxNumberOfSymbols(hints, 1);

	iv = zxing_ImageView_new(buf, width, height, zxing_ImageFormat_RGB, 0, 0);
	if (!iv) goto free_hints;

	ret = zxing_ReadBarcode(iv, hints);

	zxing_ImageView_delete(iv);

free_hints:
	zxing_DecodeHints_delete(hints);

free_buf:
	jpeg_free(buf);

	return ret;
}

There's no significant difference in memory usage between C++17 and C++20. At lower resolutions there's barely any difference at all (1~2MB). At the highest resolution there's a tiny bit more noise but the difference is still very small (10~15MB, with C++20 being more stable and generally using less).

Feedback:

• returnErrors is set to false by default
• setMaxNumberOfSymbols(1) is implicit if you use the ReadBarcode (as opposed to ReadBarcodes) function
• If you can, you should try asking your jpeg decoder to return greyscale (or Yuv) pixels and then use ImageFormat::Lum, this will save you a multitude in memcopies and cpu cycles of what you save by avoiding the Result::bytes() copy.

Regarding the memory usage: so c++20 is not responsible for your noticed increase. Any other hint what might have caused it?

Hey, sorry again for the long silence.

Thanks for the grayscale tip -- I had already looked for it in ImageFormat but didn't realize it was Lum.

I don't have any more ideas as of now about the memory use increase. If I learn anything new about this I'll let you know!

I added some more functions (getters for ReaderOptions and a zxing_free() to free the memory allocated internally for all the char * stuff. I also included the wrapper code directly into the main library (when BUILD_C_API=ON is configured). But this is still not released, so the API may still without notice.

The opaque API has the advantage that it's harder to break (may not be so much of a problem in Rust; don't know about .NET), even if more verbose. You have more leeway in what you can do internally without breaking the external API (I'm probably preaching to choir here, you know better about this stuff than me for sure :).

If you want to keep the compactness of bitfields you might want to experiment with some bit fiddling. However, because ReaderOptions is not all bitfields I can only think of something like this, which is not very user-friendly.

enum { TRY_HARDER_NO, TRY_HARDER_YES = 1<<0 };
enum { TRY_ROTATE_NO, TRY_ROTATE_YES = 1<<1 };
enum { TRY_INVERT_NO, TRY_INVERT_YES = 1<<2 };
/* ... */

(ReaderOptions){
  .bitfields=TRY_HARDER_YES|TRY_ROTATE_YES|TRY_INVERT_NO,
  .maxNumberOfSymbols=123,
  .formats=zxing_BarcodeFormat_QRCode,
  /* ... */
}

I just wonder if it's worth all the effort, assuming that .NET can call C procedures (Rust can do this for sure).

You are right about the increased ABI stability and yes, I certainly know enough about this stuff to be concerned. I don't see too much of a benefit in this case because the c-ABI version is tied to the c++ ABI version (SONAME) because they are part of the same binary. So if I change something on the c++ side and increase the SONAME that means the c-clients will need to be re-compiled anyway even if the c-ABI did not change at all. This is in and of itself not really a beneficial feature but I don't know how to prevent that other than distributing the c-API in a separate library, which I'd rather not because of the increased complexity.

If ImageView and ReaderOptions where anything like a mutable, stateful object (e.g. like the struct sqlite3) I would definitively stick to the opaque pointer. But they are actually just two collections of function parameters that are mainly there to allow to define a set of default values that don't have to be provided by the caller. In the Python API, the ReaderOptions struct does not exist because the language itself allows to selectively set optional parameters (like read_barcodes(image, format=QRCode, tryHarder=true)).

If the API would look like void read_barcodes(char* data, int size, format_t format, bool return errors); I would definitively not think about introducing a heap-allocated struct to pass the enum and the bool to the function via a pointer. And conceptually this is the same situation.

And don't worry, the manual bitfield manipulation via enum flags is not going to happen. That would be kind of the worst of both worlds.

@gitlost have you ever regretted that struct zint_symbol is a transparent struct? How do you deal with ABI breaking changes?

Actually I was thinking more from the perspective of the C API user/wrapper implementer. Recompiling is still less work than recompiling and having to fix code because the public API has changed.

If you go the transparent C struct route, any time you change the struct, you (likely) have also to change the wrappers to use the new fields or w.e.
If you keep the opaque C struct, you at most have to add/remove public procedures, everything else stays the same, even if you have to recompile code to use the new library version.

(btw I'm neutral here, just playing devil's advocate, both options have their merits)

Working on the .NET wrapper and its struct marshalling characteristics and @gitlost's comment about intermixing header files convinced me that keeping more boilerplate is indeed the better option (at least for now).

Related to this is the question of what to do with zxing_ReadBarcode() (singular)? It also returns NULL on both error and not-found conditions. It would also be possible to return a default constructed Barcode, where zxing_Barcode_isValid() returns false. But that I don't like at all. Having one function return an empty list but the other NULL instead of 'empty Barcode' is also making me gringe inside. I'm inclined to simply remove the singular version. On the c++-side it is there mostly because it has been there for ever / backward compatibility. The ios/Android/Rust/dotnet wrappers all don't have that version.

Is anyone really interested in keeping that function? Note: it is obviously possible to write a little helper function on the client side that provides the current functionality based on zxing_ReadBarcodes().

Update: I removed the function today (before publicly releasing the C-API as part of the 2.3.0 release).

Apart from the prefix, the rest of the naming is strictly following the C++ symbol names using _ to replace wither :: or .. So in that sense the prefix should be ZXing_ to replace the ZXing c++ namespace. ZXing::ReaderOptions::tryHarder becomes ZXing_ReaderOptions_tryHarder. For lack of other suggestions, this is where I'll go then.

af I totally forgot to reply to this
I vote on either zxing or ZXing for being shorter; your reasoning about the ZXing makes sense, SGTM!