How to serialize enum types as strings instead of numbers in Iguana?

You need to define a full specialization template in the iguana namespace with an array of enum values, as shown in the README example for the Status enum. This allows handling enums as strings during JSON parsing.

Iguana vs nlohmann/json for C++ JSON serialization?

Iguana offers multi-format support and compile-time reflection for better performance, but nlohmann/json is more mature and easier for pure JSON tasks. Choose Iguana if you need JSON along with XML, YAML, or Protobuf in a unified API.

Is Iguana thread-safe for concurrent use?

No, it's not thread-safe yet, as per the FAQ. You must use locks before calling serialization functions like from_json or to_json in multi-threaded environments to avoid issues.

Can I use Iguana with raw pointers in my structs?

No, Iguana does not support raw pointers for serialization. The FAQ mentions that smart pointer support is planned for the future, but currently, you'll need to avoid raw pointers or work around them.

How to handle unicode file paths with Iguana JSON?

Iguana parses JSON as UTF-8, so for unicode paths, use std::filesystem::u8path in C++17 to convert the string for file operations, as explained in the README's example on solving unicode path problems.

What compilers and C++ versions does Iguana support?

Iguana requires C++17 or C++20, and it's tested with GCC, Clang, and MSVC on Linux, macOS, and Windows. Pre-C++20 compilers need the YLT_REFL macro for reflection, adding some boilerplate.

Open-Awesome

iguana

Apache-2.0C++1.1.0

A universal serialization engine for C++ using compile-time reflection to convert objects to/from JSON, XML, YAML, and Protobuf.

GitHub

1.3k stars241 forks0 contributors

What is iguana?

Iguana is a universal serialization engine for C++ that uses compile-time reflection to convert C++ objects to and from various data formats like JSON, XML, YAML, and Protobuf. It solves the problem of data interchange in C++ applications by providing a single, efficient library for multiple serialization needs without runtime overhead.

Target Audience

C++ developers working on applications that require serialization for data storage, network communication, or configuration files, especially those using modern C++17/C++20 features.

Value Proposition

Developers choose Iguana for its compile-time reflection approach, which ensures high performance and type safety, combined with support for multiple formats through a simple and consistent API, reducing the need for multiple serialization libraries.

Overview

universal serialization engine

Use Cases

Best For

Serializing C++ objects to JSON for web APIs
Converting configuration files between XML, YAML, and JSON
Implementing Protobuf-like serialization without external dependencies
Handling complex nested structures with vectors and maps
Building cross-platform C++ applications with data interchange needs
Optimizing serialization performance with compile-time metadata

Not Ideal For

Projects stuck on C++14 or earlier compilers, as it requires C++17/20 features
Codebases heavily reliant on raw pointers for serialization, since support is not included
High-concurrency applications demanding built-in thread safety without manual locking
Simple use cases needing only one data format where a specialized library like nlohmann/json might be lighter

Pros & Cons

Pros

Zero-Cost Serialization

Uses compile-time reflection to avoid runtime overhead, ensuring high performance and type safety, as highlighted in the README's emphasis on no runtime costs.

Unified Multi-Format API

Provides consistent functions like to_json/from_json for JSON, XML, YAML, and Protobuf, simplifying code across different serialization needs without switching libraries.

Cross-Platform Support

Works on Linux, macOS, and Windows with GCC, Clang, and MSVC compilers, demonstrated by the CI badges in the README showing active testing.

Handles Complex Types

Supports nested objects, containers (e.g., vectors, maps), enums, and optional types out of the box, as shown in the complicated examples with structs like composit_t.

Cons

No Raw Pointer Support

Explicitly stated in the FAQ that raw pointers are not supported, which limits compatibility with legacy C++ codebases that rely on them.

Thread Safety Issues

Not yet thread-safe, requiring manual locking before calls like from_json or to_json, which adds complexity for concurrent applications.

Compiler Dependency

Requires C++17 or C++20 compilers, excluding projects on older standards, and pre-C++20 needs extra YLT_REFL macro boilerplate.

Frequently Asked Questions

Related Projects

ProtoBuf

Protocol Buffers - Google's data interchange format

FlatBuffers: Memory Efficient Serialization Library

Stars25,841

Forks3,551

Last commit10 days ago

Cap'n Proto

Cap'n Proto serialization/RPC system - core tools and C++ library

Stars13,000

Forks1,047

Last commit4 days ago

nanopb

Protocol Buffers with small code size

Stars5,344

Forks1,005

Last commit21 days ago

Community-curated · Updated weekly · 100% open source

Found a gem we're missing?

Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.

Submit a project Star on GitHub