Skip to content

Add documentation for language-supplied == and != on unions #28957

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
bradcray wants to merge 1 commit into
base: main
Choose a base branch
from
+63 −29
Open

Add documentation for language-supplied == and != on unions #28957

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 63 additions & 29 deletions doc/rst/language/spec/unions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,25 +19,6 @@ an unset state so that no field contains data.
Unions are currently unstable and may change in ways that will break
their current uses.

.. index::
single: types; unions
single: union types
.. _Union_Types:

Union Types
-----------

The syntax of a union type is summarized as follows:

.. code-block:: syntax

union-type:
identifier

The union type is specified by the name of the union type. This
simplification from class and record types is possible because generic
unions are not supported.

.. index::
single: union
single: declarations; union
Expand Down Expand Up @@ -69,6 +50,25 @@ for type and field resolution, but no corresponding backend definition
is generated. It is presumed that the definition of an external union
type is supplied by a library or the execution environment.

.. index::
single: types; unions
single: union types
.. _Union_Types:

Union Types
~~~~~~~~~~~

The syntax of a union type is summarized as follows:

.. code-block:: syntax

union-type:
identifier

The union type is specified by the name of the union type. This

@DanilaFe DanilaFe Jun 10, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it would help me to know that union-type is part of the type expression grammar. Because "union type is specified" is rough, and to me seems a little too close to "defined". I think perhaps we can adjust the opening paragraph of this section to say "The syntax of a union type expression is summarized as follows"?

@bradcray bradcray Jun 10, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is pre-existing (it just got moved), but I agree with the notion of improving it while I'm here.

simplification from class and record types is possible because generic
unions are not supported.

.. index::
single: unions; fields
.. _Union_Fields:
Expand Down Expand Up @@ -148,6 +148,50 @@ the field name as a member of the union type.

Union fields should not be specified with initialization expressions.


Common Operations
-----------------

.. index::
single: unions; assignment
.. _Union_Assignment:

Union Assignment
~~~~~~~~~~~~~~~~

Union assignment is by value. The active field of the union on the
right-hand side of the assignment is assigned to same field of the
union on the left-hand side, and this field is made active.

.. index::
single: unions; equality
single: unions; inequality
single: unions; ==
single: unions; !=
single: == (union)
single: != (union)
.. _Union_Comparison_Operators:

Default Comparison Operators
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Default comparison operators are defined for unions such that if no
more specific comparison is found, these defaults will be used. These
default comparisons are defined using the following signatures:

.. code-block:: chapel

operator ==(a: union, b: union) : bool
operator !=(a: union, b: union) : bool

When these comparisons are applied to two union values of distinct
types, a compiler error is generated.

These default comparisons consider two union values to be equal if (a)
both union have the same active field and (b) those fields are
Comment thread
bradcray marked this conversation as resolved.

@DanilaFe DanilaFe Jun 10, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

bit of a nit, since it's clear what you mean, but "those fieldS" is mismatched with "same active field". Consider: "the respective values of this active field are..."

considered equal via `==`. Otherwise they are considered not equal.


.. index::
single: unions; pattern matching
.. _Union_Pattern_Matching:
Expand Down Expand Up @@ -243,16 +287,6 @@ conditionals.

x is active with value 3

.. index::
single: unions; assignment
.. _Union_Assignment:

Union Assignment
----------------

Union assignment is by value. The field set by the union on the
right-hand side of the assignment is assigned to the union on the
left-hand side of the assignment and this same field is marked as set.

.. index::
single: unions; methods
Expand Down