stevedunn / intellenum

Type Conversions

Intellenum automatically generates type conversions to help you work with Value Objects in your code. This outline explains how these conversions work and how you can customize them.

Motivation

  • Strong Typing: Intellenum aims to maintain strong typing even when working with underlying primitive types. Casting operators (implicit or explicit) can blur this distinction, making it easier to accidentally use the underlying type directly.
  • Explicit Operations: Encouraging the use of methods like IncreaseBy for manipulating Value Objects promotes clarity and avoids potential errors.

Supported Types

Intellenum supports a wide range of underlying types for Value Objects:

  • Primitive Types: byte, sbyte, short, ushort, int, uint, long, ulong, char, string, bool
  • Common .NET Types: Guid, DateTime, DateTimeOffset, TimeSpan, DateOnly, TimeOnly
  • Custom Types: You can specify a custom type for your Value Objects. However, there are some limitations:
    • The custom type cannot be a collection.
    • It cannot be the same type as the enumeration itself.

Type Conversion Mechanisms

  • Switch Expressions: Intellenum uses switch expressions for IsDefined and FromValue methods when the underlying type is a compile-time constant or decimal. This ensures efficient and optimized code.
  • Lookup Tables: When the underlying type is not a compile-time constant or decimal, a lookup table is employed. This is necessary because the left-hand side of a switch expression must be a constant expression.

Examples

[ValueObject]
          public partial struct Score
          {
            public Score IncreaseBy(Points points) => From(_value + points.Value);
          }
          
          // Usage
          var score1 = Score.FromValue(10);
          var score2 = score1.IncreaseBy(Points.FromValue(5));
          
          // Direct Access (NOT RECOMMENDED)
          // int n = score1.Value + 10; // Avoid using the underlying value directly

Custom Conversions

If you need custom conversions that go beyond what Intellenum provides automatically, you can specify Conversions.None in your Value Object definition. This disables default conversions, allowing you to implement them manually.

Considerations

  • Performance: While switch expressions generally offer good performance, they can sometimes be slower than traditional switch statements for certain scenarios.
  • Serialization and Deserialization: Intellenum provides built-in support for serializing and deserializing Value Objects. You can customize this behavior using the Conversions enum.

Source Code


          ## Top-Level Directory Explanations
          
          <a class='local-link directory-link' data-ref="samples/" href="#samples/">samples/</a> - This directory contains example projects demonstrating the usage of Intellenum.
          
          <a class='local-link directory-link' data-ref="samples/Intellenum.Examples/" href="#samples/Intellenum.Examples/">samples/Intellenum.Examples/</a> - Contains various example projects demonstrating different aspects of Intellenum, such as serialization, conversion, syntax examples, types, typical scenarios, and more.
          
          <a class='local-link directory-link' data-ref="src/" href="#src/">src/</a> - This directory contains the source code of the Intellenum library.
          
          <a class='local-link directory-link' data-ref="src/Benchmarks/" href="#src/Benchmarks/">src/Benchmarks/</a> - Contains benchmark tests for the Intellenum library.
          
          <a class='local-link directory-link' data-ref="src/Intellenum.SharedTypes/" href="#src/Intellenum.SharedTypes/">src/Intellenum.SharedTypes/</a> - Contains shared types used across the Intellenum library.
          
          <a class='local-link directory-link' data-ref="src/Intellenum/" href="#src/Intellenum/">src/Intellenum/</a> - Contains the main source code for the Intellenum library. This directory is further divided into subdirectories for diagnostics, extensions, generators, member building, properties, rules, static constructor building, templates, and more.
          
          <a class='local-link directory-link' data-ref="tests/" href="#tests/">tests/</a> - This directory contains test projects for the Intellenum library.
          
          <a class='local-link directory-link' data-ref="tests/ConsumerTests/" href="#tests/ConsumerTests/">tests/ConsumerTests/</a> - Contains tests for consuming the Intellenum library.
          
          <a class='local-link directory-link' data-ref="tests/Intellenum.Tests/" href="#tests/Intellenum.Tests/">tests/Intellenum.Tests/</a> - Contains additional tests for the Intellenum library.
          
          <a class='local-link directory-link' data-ref="tests/SnapshotTests/" href="#tests/SnapshotTests/">tests/SnapshotTests/</a> - Contains snapshot tests for the Intellenum library.