From 83c3ee2662b39354f41561cc9fad67e5763ac4e1 Mon Sep 17 00:00:00 2001 From: "Italo F. Capasso B." <44873757+edwood-grant@users.noreply.github.com> Date: Mon, 3 Mar 2025 12:25:38 -0500 Subject: [PATCH 1/2] Fixing incorrect enum information and add alternatives --- .../04-02-enums-and-flags.rst | 49 +++++++++++++++++-- 1 file changed, 46 insertions(+), 3 deletions(-) diff --git a/source/developer-guides/bindings/writing-a-vapi-manually/04-00-recognizing-vala-semantics-in-c-code/04-02-enums-and-flags.rst b/source/developer-guides/bindings/writing-a-vapi-manually/04-00-recognizing-vala-semantics-in-c-code/04-02-enums-and-flags.rst index 3204d9aa..f69df12e 100644 --- a/source/developer-guides/bindings/writing-a-vapi-manually/04-00-recognizing-vala-semantics-in-c-code/04-02-enums-and-flags.rst +++ b/source/developer-guides/bindings/writing-a-vapi-manually/04-00-recognizing-vala-semantics-in-c-code/04-02-enums-and-flags.rst @@ -65,9 +65,45 @@ There is also a common tendency to use combinable bit patterns. These are conver } -In Vala, enums and flags may have member functions. In particular, ``strerr``-like functions are best converted to member functions. +In Vala, enums and flags may have member functions and properties. In particular, ``strerr``-like functions are best converted to member functions. -Enums may also inherit, so if one set of flags is a superset of another, but they are logically separate, this can be done using inheritance. +The default function ``to_string()`` can cause problems if the enum has aliases (the C error ``duplicate case`` will trigger). So to solve this, +you can create additional constants after the enum has been declared to add this missing enum aliases. + +For example this enum: + +.. code-block:: c + + typedef enum { + BAR_A, + BAR_B, + BAR_C, + BAR_D, + BAR_FIRST = BAR_A, + BAR_LAST = BAR_D, + } bar_e; + +Will become: + +.. code-block:: vala + + [CCode (cname = "bar_e", cprefix = "BAR_", has_type_id = false)] + public enum Bar { + A, + B, + C; + + [CCode (cname = "BAR_")] + public const Bar FIRST; + + [CCode (cname = "BAR_")] + public const Bar LAST; + } + +If one set of flags is a superset of another, but they are logically separate, You can create a different set of enums that refer to the same enum +or defines. + +For example: .. code-block:: c @@ -80,10 +116,17 @@ Enums may also inherit, so if one set of flags is a superset of another, but the /* takes any FOO_ value */ void do_something_else(int); +Can become this: + .. code-block:: vala [CCode (cname = "int", cprefix = "FOO_", has_type_id = false)] public enum Foo { A, B } [CCode (cname = "int", cprefix = "FOO_", has_type_id = false)] - public enum FooExtended : Foo { C, D } + public enum FooExtended { C, D } + +You can then cast one enum to another: + +.. code.block:: vala +var foo_enum = (Foo) FooExtended.C; From 872e827d8f12976231dcbedeba33b49aa098e9b3 Mon Sep 17 00:00:00 2001 From: "Italo F. Capasso B." <44873757+edwood-grant@users.noreply.github.com> Date: Mon, 17 Mar 2025 10:42:19 -0500 Subject: [PATCH 2/2] Restructured enum text to adress PR reqeusts. --- .../04-02-enums-and-flags.rst | 75 +++++++++++-------- 1 file changed, 42 insertions(+), 33 deletions(-) diff --git a/source/developer-guides/bindings/writing-a-vapi-manually/04-00-recognizing-vala-semantics-in-c-code/04-02-enums-and-flags.rst b/source/developer-guides/bindings/writing-a-vapi-manually/04-00-recognizing-vala-semantics-in-c-code/04-02-enums-and-flags.rst index f69df12e..d0f539b0 100644 --- a/source/developer-guides/bindings/writing-a-vapi-manually/04-00-recognizing-vala-semantics-in-c-code/04-02-enums-and-flags.rst +++ b/source/developer-guides/bindings/writing-a-vapi-manually/04-00-recognizing-vala-semantics-in-c-code/04-02-enums-and-flags.rst @@ -64,11 +64,51 @@ There is also a common tendency to use combinable bit patterns. These are conver CREATE } +Supersets +--------- -In Vala, enums and flags may have member functions and properties. In particular, ``strerr``-like functions are best converted to member functions. +If one set of enums or flags is a superset of another, but they are logically separate, You can create a different set of enums that refer to the same enum +or defines. + +For example: + +.. code-block:: c + + #define FOO_A 1 + #define FOO_B 2 + #define FOO_C 3 + #define FOO_D 4 + /* takes FOO_A or B only */ + void do_something(int); + /* takes any FOO_ value */ + void do_something_else(int); + +Can become this: + +.. code-block:: vala + + [CCode (cname = "int", cprefix = "FOO_", has_type_id = false)] + public enum Foo { A, B } + [CCode (cname = "int", cprefix = "FOO_", has_type_id = false)] + public enum FooExtended { C, D } + +You can then cast one enum to another: + +.. code-block:: vala + + var foo_enum = (Foo) FooExtended.C; + +Member functions and constants +------------------------------ + +In Vala, enums and flags may have member functions and constants. +In particular, ``strerr``-like functions are best converted to member functions. + +Enum aliases and ``to_string()`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The default function ``to_string()`` can cause problems if the enum has aliases (the C error ``duplicate case`` will trigger). So to solve this, -you can create additional constants after the enum has been declared to add this missing enum aliases. +you can create additional constants after the enum has been declared to add the missing enum aliases. For example this enum: @@ -99,34 +139,3 @@ Will become: [CCode (cname = "BAR_")] public const Bar LAST; } - -If one set of flags is a superset of another, but they are logically separate, You can create a different set of enums that refer to the same enum -or defines. - -For example: - -.. code-block:: c - - #define FOO_A 1 - #define FOO_B 2 - #define FOO_C 3 - #define FOO_D 4 - /* takes FOO_A or B only */ - void do_something(int); - /* takes any FOO_ value */ - void do_something_else(int); - -Can become this: - -.. code-block:: vala - - [CCode (cname = "int", cprefix = "FOO_", has_type_id = false)] - public enum Foo { A, B } - [CCode (cname = "int", cprefix = "FOO_", has_type_id = false)] - public enum FooExtended { C, D } - -You can then cast one enum to another: - -.. code.block:: vala - -var foo_enum = (Foo) FooExtended.C;