From e1a055bd736cc63394f3659d8fa80f30be46b248 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Wed, 7 Mar 2018 16:58:40 -0500 Subject: [PATCH] qobject: Explain how QNum works, and why Backports commit f90cb2846a0b167d47131ba4600dcc816bccb1c6 from qemu --- qemu/include/qapi/qmp/qnum.h | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/qemu/include/qapi/qmp/qnum.h b/qemu/include/qapi/qmp/qnum.h index 946387fe..94b5f853 100644 --- a/qemu/include/qapi/qmp/qnum.h +++ b/qemu/include/qapi/qmp/qnum.h @@ -23,6 +23,27 @@ typedef enum { QNUM_DOUBLE } QNumKind; +/* + * QNum encapsulates how our dialect of JSON fills in the blanks left + * by the JSON specification (RFC 7159) regarding numbers. + * + * Conceptually, we treat number as an abstract type with three + * concrete subtypes: floating-point, signed integer, unsigned + * integer. QNum implements this as a discriminated union of double, + * int64_t, uint64_t. + * + * The JSON parser picks the subtype as follows. If the number has a + * decimal point or an exponent, it is floating-point. Else if it + * fits into int64_t, it's signed integer. Else if it fits into + * uint64_t, it's unsigned integer. Else it's floating-point. + * + * Any number can serve as double: qnum_get_double() converts under + * the hood. + * + * An integer can serve as signed / unsigned integer as long as it is + * in range: qnum_get_try_int() / qnum_get_try_uint() check range and + * convert under the hood. + */ struct QNum { QObject base; QNumKind kind;