stevedunn / intellenum

Safety

This section outlines the rationale and implementation details behind the “Safety” aspects of the Intellenums codebase.

Motivation

The primary goal of Intellenums is to provide a mechanism for creating strongly typed enums that prevent common errors associated with traditional enum usage. This is achieved by employing a combination of compiler-generated code and runtime validation.

Key Design Principles

  • Immutability: All Intellenums values are immutable, guaranteeing their integrity and consistency. This ensures that once an Intellenums value is created, its underlying state cannot be altered.
  • Validation: Intellenums enforces validation rules at creation time, rejecting invalid values. This helps to prevent errors from propagating through the codebase, leading to more robust and reliable applications.
  • Strongly Typed Operations: Intellenums offers strongly typed operations like TryFromName and TryFromValue which ensure type-safety and prevent accidental misuse of enum values.

Implementation Details

  • ValueObject Attribute: The ValueObject attribute is the foundation of Intellenums. It marks a type as a ValueObject, instructing the code generator to create the necessary code for validation, conversion, and other features.
  • Underlying Type: The underlyingType parameter of the ValueObject attribute specifies the primitive type that the ValueObject wraps. By default, this is set to int.
  • Customizations: The customizations parameter allows developers to fine-tune the generated code by enabling features like string comparison, specific casting behaviors, and generation of IParsable implementations.
  • Validation: Validation rules are defined within the ValueObject class using the Validate method. This method takes the underlying primitive value as input and returns a Validation result, indicating whether the value is valid or not.
  • Lookup Tables: For underlying types that are not compile-time constants (e.g., decimal, double), Intellenums utilizes lookup tables to achieve efficient performance during switch statements.
  • Runtime Performance: The goal of Intellenums is to offer a performance advantage over traditional enums. This is achieved by leveraging a combination of techniques like compiler-generated code, minimal reflection, and lookup tables.

Usage Examples

// Define a CustomerId ValueObject
          [ValueObject(typeof(int))]
          public partial struct CustomerId
          {
          }
          
          // Create a CustomerId instance
          var customerId = CustomerId.From(42);
          
          // Use the CustomerId value in a method signature
          public void DoSomething(CustomerId customerId) 
          {
              // ...
          }

Benchmarks

Intellenums consistently outperforms traditional enums and other enum-related libraries in terms of performance. The following table summarizes the benchmark results:

Library Mean (ns) Error (ns) StdDev (ns)
StandardEnums 123.937 0.5615 0.4977
EnumGenerators 9.067 0.0523 0.0489
SmartEnums 30.719 0.4043 0.3782
Intellenums 11.460 0.2545 0.2380

Code Files

  • src/Benchmarks/Program.cs
  • src/Intellenum/Extensions/IMethodSymbolExtensions.cs
  • src/Intellenum/Generators/ValueObjectGenerator.cs
  • src/Intellenum/ValueObject.cs

Documentation Links


          ## 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="samples/WebApplication/" href="#samples/WebApplication/">samples/WebApplication/</a> - Contains a sample web application that uses Intellenum.
          
          <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/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/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/Shared/" href="#tests/Shared/">tests/Shared/</a> - Contains shared test files.
          
          <a class='local-link directory-link' data-ref="tests/SnapshotTests/" href="#tests/SnapshotTests/">tests/SnapshotTests/</a> - Contains snapshot tests for the Intellenum library.
          
          <a class='local-link directory-link' data-ref="tests/Testbench/" href="#tests/Testbench/">tests/Testbench/</a> - Contains a test bench for the Intellenum library.