Table of Contents

Class Percentage

Namespace
Trellis.Primitives
Assembly
Trellis.Primitives.dll

Represents a percentage value object (value between 0 and 100 inclusive). Ensures that percentage values are within the valid range for percentage calculations.

[JsonConverter(typeof(ParsableJsonConverter<Percentage>))]
public class Percentage : ScalarValueObject<Percentage, decimal>, IComparable<ValueObject>, IEquatable<ValueObject>, IConvertible, IScalarValue<Percentage, decimal>, IParsable<Percentage>
Inheritance
Percentage
Implements
Inherited Members
Extension Methods

Examples

Basic usage:

var discount = Percentage.TryCreate(15.5m);
// Returns: Success(Percentage(15.5))

var full = Percentage.TryCreate(100m);
// Returns: Success(Percentage(100))

var zero = Percentage.TryCreate(0m);
// Returns: Success(Percentage(0))

var invalidHigh = Percentage.TryCreate(150m);
// Returns: Failure(ValidationError("Percentage must be between 0 and 100."))

var invalidNegative = Percentage.TryCreate(-5m);
// Returns: Failure(ValidationError("Percentage must be between 0 and 100."))

Using helper methods:

var percentage = Percentage.TryCreate(20m).Value;
var amount = 100m;

// Convert to fraction (0.2)
var fraction = percentage.AsFraction();

// Calculate percentage of a value
var result = percentage.Of(amount); // Returns 20m

Remarks

Percentage is a domain primitive that encapsulates percentage validation and provides:

  • Validation ensuring value is between 0 and 100 inclusive
  • Type safety preventing mixing of percentages with other decimals
  • Immutability ensuring values cannot be changed after creation
  • IParsable implementation for .NET parsing conventions
  • JSON serialization support for APIs and persistence
  • Activity tracing for monitoring and diagnostics
  • Helper methods for percentage calculations

Common use cases:

  • Discount percentages
  • Tax rates
  • Commission rates
  • Progress indicators
  • Interest rates
  • Any value representing a percentage

Properties

Full

Gets a Percentage representing 100%.

public static Percentage Full { get; }

Property Value

Percentage

Zero

Gets a Percentage representing 0%.

public static Percentage Zero { get; }

Property Value

Percentage

Methods

AsFraction()

Returns the percentage as a fraction (0.0 to 1.0).

public decimal AsFraction()

Returns

decimal

The percentage value divided by 100.

FromFraction(decimal, string?)

Creates a Percentage from a fraction (0.0 to 1.0).

public static Result<Percentage> FromFraction(decimal fraction, string? fieldName = null)

Parameters

fraction decimal

The fraction value (0.0 to 1.0).

fieldName string

Optional field name to use in validation error messages.

Returns

Result<Percentage>

Success with the Percentage; otherwise Failure with a ValidationError.

Of(decimal)

Calculates this percentage of the specified amount.

public decimal Of(decimal amount)

Parameters

amount decimal

The amount to calculate the percentage of.

Returns

decimal

The percentage of the amount.

Parse(string?, IFormatProvider?)

Parses the string representation of a decimal to its Percentage equivalent.

public static Percentage Parse(string? s, IFormatProvider? provider)

Parameters

s string
provider IFormatProvider

Returns

Percentage

ToString()

Returns a string representation of the percentage with a % suffix.

public override string ToString()

Returns

string

TryCreate(decimal, string?)

Attempts to create a Percentage from the specified decimal.

public static Result<Percentage> TryCreate(decimal value, string? fieldName = null)

Parameters

value decimal

The decimal value to validate (0-100).

fieldName string

Optional field name to use in validation error messages.

Returns

Result<Percentage>

Success with the Percentage if the value is between 0 and 100; otherwise Failure with a ValidationError.

TryCreate(decimal?, string?)

Attempts to create a Percentage from the specified nullable decimal.

public static Result<Percentage> TryCreate(decimal? value, string? fieldName = null)

Parameters

value decimal?

The nullable decimal value to validate (0-100).

fieldName string

Optional field name to use in validation error messages.

Returns

Result<Percentage>

Success with the Percentage if the value is between 0 and 100; otherwise Failure with a ValidationError.

TryParse(string?, IFormatProvider?, out Percentage)

Tries to parse a string into a Percentage.

public static bool TryParse(string? s, IFormatProvider? provider, out Percentage result)

Parameters

s string
provider IFormatProvider
result Percentage

Returns

bool

Operators

explicit operator Percentage(decimal)

Explicitly converts a decimal to a Percentage.

public static explicit operator Percentage(decimal value)

Parameters

value decimal

Returns

Percentage
Edit this page