CloudMesh.Variant 2.0.99

There is a newer version of this package available.
See the version list below for details.
dotnet add package CloudMesh.Variant --version 2.0.99
                    
NuGet\Install-Package CloudMesh.Variant -Version 2.0.99
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="CloudMesh.Variant" Version="2.0.99" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="CloudMesh.Variant" Version="2.0.99" />
                    
Directory.Packages.props
<PackageReference Include="CloudMesh.Variant" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add CloudMesh.Variant --version 2.0.99
                    
#r "nuget: CloudMesh.Variant, 2.0.99"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package CloudMesh.Variant@2.0.99
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=CloudMesh.Variant&version=2.0.99
                    
Install as a Cake Addin
#tool nuget:?package=CloudMesh.Variant&version=2.0.99
                    
Install as a Cake Tool

CloudMesh.Variant

A boxing-free discriminated union for .NET — carry any primitive, Guid, DateTime, enum, small struct, null, or reference in one fixed-size Value, and read it back out with zero heap allocations.

When you gather heterogeneous values into an object?[], every value type gets boxed — a heap allocation per element. In hot paths (parsing JSON, staging rows for a bulk loader, buffering columnar data) that is millions of allocations and constant GC pressure, purely to shuttle ints and bools around. Value stores those inline in an overlapped struct field instead, so nothing boxes.

  • Targets: .NET 8, 9, 10 — License: MIT
  • A Value is a readonly struct of 24 bytes on 64-bit (an 8-byte object reference plus a 16-byte inline union); a Value[] is a flat array with no per-element heap objects.
  • As<T>() / TryGetValue<T>() round-trips honour Nullable<T> — a stored int reads back as int?, a stored null reads back as any nullable/reference type.

Install

dotnet add package CloudMesh.Variant

The problem it solves

object?[] values = new object?[3];
values[0] = 4;     // int   → boxed (heap allocation)
values[1] = null;  // null  → no boxing
values[2] = true;  // bool  → boxed (heap allocation)

Two allocations, just to hold two value types. With Value:

using CloudMesh.Variant;

Value[] values = new Value[3];
values[0] = 4;     // int   → no boxing (implicit conversion)
values[1] = null;  // null  → no boxing
values[2] = true;  // bool  → no boxing

Zero allocations. The array is a contiguous block of 16-byte structs.

Reading values back

Use As<T>() (throws on mismatch) or TryGetValue<T>() (returns false):

Value v = 42;

int i  = v.As<int>();                 // 42
int? n = v.As<int?>();                // 42  — Nullable<T> round-trips
bool ok = v.TryGetValue<int>(out i);  // true
bool no = v.TryGetValue<long>(out _); // false — no implicit widening; the stored type must match

// Explicit conversion operators exist for the built-in types too:
var back = (int)v;                    // 42

Nulls and reference types behave as you'd expect:

Value empty = null;
empty.IsNull;                    // true
empty.TryGetValue<string>(out var s);   // true, s == null
empty.TryGetValue<int?>(out var maybe); // true, maybe == null
empty.TryGetValue<int>(out _);          // false — a plain int can't be null

Inspect what's inside with Type:

Value g = Guid.NewGuid();
g.Type;   // typeof(System.Guid)  — reports the real type, not the internal storage type

What stores without boxing

Category Examples
Primitives bool, byte, sbyte, char, short/ushort, int/uint, long/ulong, float, double
Nullable primitives int?, bool?, double?, … (all of the above)
Date/time DateTime, DateTimeOffset (UTC and common quarter-hour offsets are packed inline)
Identifiers & enums Guid, any enum
Buffers ArraySegment<byte>, ArraySegment<char>
Small unmanaged structs any struct with no references that fits in the inline union
Anything else reference types & large/managed structs — held as a plain object reference (no extra allocation)

Values whose type is only known generically go through Value.Create<T>(value), which picks the inline representation automatically:

static Value Wrap<T>(T item) => Value.Create(item);   // no boxing for the inline-eligible types above

Use cases

  • Columnar / bulk-load staging — parse a record's fields into a Value[], reorder to match the loader's column order, and emit, all without boxing a single scalar.
  • Generic buffers & message payloads — pass arbitrary scalar payloads through a generic pipeline without an object box per message. (CloudMesh.DataBlocks uses Value internally for exactly this.)
  • Interpreters / dynamic values — a compact cell type for a stack or register file that mixes numeric, boolean, and reference values.

Gotchas

  • Exact-type match on read. TryGetValue<T> does not widen or convert — a stored int is not readable as long or double. Read it as the type you stored (optionally its Nullable<T>), then convert yourself.
  • As<T>() throws InvalidCastException on a mismatch; use TryGetValue<T> when a miss is expected.
  • decimal is stored inline — it is a 16-byte unmanaged value that fits the inline union (exactly like Guid), so storing a decimal (or decimal?) does not box.
  • ArraySegment vs array. A segment stores the backing array plus offset/count inline; reading it back as the bare array type is intentionally rejected so a segment can't silently masquerade as the whole array.

MIT © Jessie Wadman. Part of CloudMesh.

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (2)

Showing the top 2 NuGet packages that depend on CloudMesh.Variant:

Package Downloads
CloudMesh.DataBlocks

Lightweight building blocks for creating complex message processing pipelines

Primodel.Sdk

Contracts for authoring Primodel plugins.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
2.0.108 0 11/21/2026
2.0.107 832 11/14/2026
2.0.105 765 11/12/2026
2.0.104 366 11/9/2026
2.0.103 2,664 9/25/2026
2.0.101 181 8/29/2026
2.0.100 3,449 8/3/2026
2.0.99 151 7/14/2026
2.0.98 156 7/14/2026
2.0.97 599 7/14/2026
2.0.96 145 6/28/2026
2.0.95 143 6/28/2026
2.0.94 145 6/28/2026
2.0.93 180 6/27/2026
2.0.92 149 6/23/2026
2.0.89 341 12/18/2025
2.0.87-preview 237 8/11/2025
2.0.85-preview 162 1/29/2025
2.0.76-preview 172 1/15/2025
2.0.75-preview 171 1/15/2025
Loading failed