stevedunn / intellenum

Conversions

Intellenum supports conversions between enums and other data types. This outline details how conversions are handled and the various conversion mechanisms available.

TypeConverter

The TypeConverter implementation is integral to converting enum values to and from strings. This conversion is especially useful for scenarios where you need to represent enum values in a user-friendly way, like displaying them in a user interface or storing them in a database.

Example:

[ValueObject]
          public partial struct Score
          {
            public Score IncreaseBy(Points points) => From(_value + points.Value);
          }

In this example, Score is a ValueObject struct, and its IncreaseBy method demonstrates how to use the TypeConverter to convert enum values to and from strings.

Conversions Enum

The Conversions enum defines various options for configuring conversions:

**Option Description**
None No converters are created for the value object.
Default Uses the default converters for the value object. This includes the TypeConverter and SystemTextJson converter.
TypeConverter Creates a TypeConverter for converting from the value object to and from a string.
NewtonsoftJson Creates a Newtonsoft.Json.JsonConverter for serializing the value object to its primitive value.
SystemTextJson Creates a System.Text.Json.Serialization.JsonConverter for serializing the value object to its primitive value.
EfCoreValueConverter Creates an EF Core Value Converter for extracting the primitive value.
DapperTypeHandler Creates a Dapper TypeHandler for converting to and from the type.
LinqToDbValueConverter Creates a LinqToDb ValueConverter for converting to and from the type.

Example:

[Intellenum(conversions: Conversions.NewtonsoftJson | Conversions.SystemTextJson)]
          [Member("Standard", 1)]
          [Member("Gold", 2)]
          public partial class CustomerType;

This example defines a CustomerType enum and specifies that it should generate converters for Newtonsoft.Json and System.Text.Json.

Database Conversions

Intellenum provides converters and serializers for databases, including:

  • Dapper
  • EFCore
  • LINQ to DB

These converters are controlled by the Conversions enum.

Example:

[Intellenum(conversions: Conversions.NewtonsoftJson | Conversions.SystemTextJson)]
          [Member("Standard", 1)]
          [Member("Gold", 2)]
          public partial class CustomerType;

If you don’t want any conversions, specify Conversions.None. If you need to implement your own conversions, specify Conversions.None and implement them yourself, just like any other type.

Lookup Table

For underlying types that are not compile-time constants (byte, int16, int32, int64, string, decimal), a lookup table is used. This is necessary because the left-hand side of a switch expression must be a constant expression.

Example:

var r = f();
          member = r.Item1;
          return r.Item2;
          }

Note: If you have ideas on how to improve performance, please let us know!

JSON Serialization and Deserialization

Vogen can automatically generate the code required for serializing and deserializing value objects. It supports:

  • System.Text.Json (STJ)
  • Newtonsoft.Json (NSJ)
  • ServiceStack.Text

Example:

[ValueObject(conversions: Conversions.None)]
          public readonly partial struct Celsius { }

This example defines a Celsius struct without specifying any conversions. This means that Vogen will not generate any code for serializing and deserializing the Celsius struct.

Custom Conversions

If you need custom conversions that are not provided by Intellenum, you can implement them yourself. You can then use the Conversions.None option to prevent Vogen from generating its own conversions.

Example:

// Custom converter for Celsius
          public class CelsiusConverter : System.Text.Json.Serialization.JsonConverter<Celsius>
          {
            // Implement custom logic for serialization and deserialization
          }
          
          // Define Celsius struct without conversions
          [ValueObject(conversions: Conversions.None)]
          public readonly partial struct Celsius { }

Source Files:

  • docs/site/Writerside/topics/tutorials/Casting.md
  • docs/site/Writerside/topics/discussions/Overview.md
  • docs/site/Writerside/topics/reference/Integration.md
  • README.md
  • docs/site/Writerside/topics/tutorials/Working-with-databases.md
  • docs/site/Writerside/topics/discussions/Overview.md
  • docs/site/Writerside/topics/tutorials/Using-with-JSON.md
  • README.md
  • docs/site/Writerside/topics/discussions/Overview.md
  • src/Intellenum/Intellenum.csproj
  • src/Intellenum/Templates/Decimal/Decimal_TypeConverter.cs

          ## 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/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/AnalyzerTests/" href="#tests/AnalyzerTests/">tests/AnalyzerTests/</a> - Contains unit tests for the Intellenum analyzer.
          
          <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/SnapshotTests/" href="#tests/SnapshotTests/">tests/SnapshotTests/</a> - Contains snapshot tests for the Intellenum library.