Table of Contents

Class PhoneNumber

Namespace
Trellis.Primitives
Assembly
Trellis.Primitives.dll

Represents a phone number value object with E.164 format validation. Ensures that phone numbers follow international standards for telephony.

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

Examples

Basic usage:

var phone = PhoneNumber.TryCreate("+14155551234");
// Returns: Success(PhoneNumber("+14155551234"))

var invalid = PhoneNumber.TryCreate("555-1234");
// Returns: Failure(Error.InvalidInput with detail "Phone number must be in E.164 format (e.g., +14155551234).")

Remarks

PhoneNumber is a domain primitive that encapsulates phone number validation and provides:

  • E.164 format validation (international phone number standard)
  • Type safety preventing mixing of phone numbers with other strings
  • Immutability ensuring phone numbers cannot be changed after creation
  • IParsable implementation for .NET parsing conventions
  • JSON serialization support for APIs and persistence
  • Activity tracing for monitoring and diagnostics

E.164 format rules:

  • Starts with a '+' sign
  • Country code (1-3 digits)
  • Subscriber number (up to 12 digits)
  • Maximum total length: 15 digits (excluding the '+' sign)
  • Minimum total length: 8 digits (excluding the '+' sign)

Common use cases:

  • Contact information in entities
  • SMS notification recipients
  • Two-factor authentication
  • Customer support systems

Note: Opinionated Implementation - If you need different phone number formats (e.g., with extensions like +1-415-555-1234 ext. 123), create your own PhoneNumber value object using the ScalarValueObject<TSelf, T> base class.

Methods

GetCountryCode()

Gets the country calling code portion of the phone number, if the prefix matches a known ITU-T E.164 country calling code.

public Maybe<string> GetCountryCode()

Returns

Maybe<string>

From<T>(T?) wrapping the country calling code (digits after + and before the subscriber number) when the prefix is recognized; None when the prefix does not match any assigned ITU-T country calling code. TryCreate(string?, string?) validates only E.164 shape, not assigned-code membership, so a phone number that passes TryCreate can legitimately resolve to None here (unassigned ranges, codes added after this library shipped, or malformed input that happens to satisfy E.164 length/character rules).

Parse(string?, IFormatProvider?)

Parses the string representation of a phone number to its PhoneNumber equivalent.

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

Parameters

s string
provider IFormatProvider

Returns

PhoneNumber

TryCreate(string?, string?)

Attempts to create a PhoneNumber from the specified string. If fieldName is not provided, validation errors use "phoneNumber" as the field name.

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

Parameters

value string

The phone number string to validate.

fieldName string

Optional field name for validation error messages. If not provided, defaults to "phoneNumber".

Returns

Result<PhoneNumber>

Success with the PhoneNumber if the string is in E.164 format; otherwise Failure with Error.InvalidInput.

TryParse(string?, IFormatProvider?, out PhoneNumber)

Tries to parse a string into a PhoneNumber.

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

Parameters

s string
provider IFormatProvider
result PhoneNumber

Returns

bool