Semantica.Lib.Patterns 8.1.0

Semantica.Lib.Patterns

This package is part of the core packages of Semantica.Lib.

Summary

Contains several basic interfaces generally usable for value types or data structure classes. Also contains a collection of extensions that work on (collections of) those interfaces.

Contents

IApproximable

A struct or class can implement IApproximable when it's sometimes useful to know if different values are approximate, but other situations require a more strict concept of equality.

IArithmatic

A struct or class can implement IArithmatic when it's possible to have basic arithmatic operations on instances. .NET 7 introduced static interfaces for the same purpose, so this interface will become obsolete when .NET 6 gets deprecated.

ICanBeEmpty

A struct or class can implement ICanBeEmpty when there is some (inescapable) default value that can be thought of as empty. Because many, many simple types or data structures have this inherit empty value, having a universal method to assertain that (By implementing/using a bool IsEmpty() method) can be very useful. Also, this allows for

ICanSerialize

A struct or class can implement ICanSerialize when it can be serialized to a string without losing any relevant information. If a type also supports deserialization, use the generic ICanSerialize<TSelf>. The package Semantica.Lib.Patterns.Converters contains JsonConverters and TypeConverters that will be able to generically convert any type implementing these interfaces.

IDeterminable

A struct or class can implement IDeterminable when it has no clear undetermined state, but there is need for one. This can be particularly useful for value types when an explicit undetermined state is more clear than or functionally useful besides having a System.Nullable or null value.

Domain (key) interfaces

These interfaces should be used on simple value types (readonly structs) that represent a (unique) key of some entity. A typical simple key would be a database generated id (integer), or a guid. By wrapping your keys in a simple struct types for each of your entities, you can make your method signatures much clearer, and it will be much easier to change the key later on. The (Simple-) datastore implementations in Semantica.Lib.Storage.Data do not require these interfaces to be present on key types, but the conditions for using them are the same (having simple keys: Wiki: Unique key).

classDiagram
    IIdKey~T~ <|-- ISimpleKey~TKey~
    IIdKey~T~ <|-- "T=int" IIdentityKey
    IIdentityKey <|-- IIdentityKey_~TSelf~
    ISimpleKey~TSelf~ <|-- IIdentityKey_~TSelf~

    class IIdentityKey
    class IIdentityKey_~TSelf~
    class ISubKey~TKey~
    class IIdKey~T~ {
        T Id
    }
    class ISimpleKey~TSelf T~ {
        T?: AsNullableId()
        bool: IsEmpty()
        ISimpleKey~TSelf T~: FromNullableId(T? id)$
    }

Domain.IIdKey<T>

A struct (or class) can implement IIdKey when the key consists of one property with the name Id. The type of the property is generic, and can be any IEquatable<T> struct. While the interface obviously is unable to enforce this, the idea is that it's only used for simple keys.

Domain.IIdentityKey

A struct (or class) can implement IIdentityKey when it's an IdKey, and the type of the Id property is integer. Typically representing an auto-incrementing primary key.

Domain.ISimpleKey<T, TSelf>

A struct can implement ISimpleKey when it is the same as IdKey, but adds AsNullableId and FromNullableId conversion methods.

Domain.IIdentityKey<TSelf>

A struct (or class) can implement IIdentityKey<TSelf> when it's a ISimpleKey, and the type of the Id property is integer.

Domain.ISubKey<TKey>

A key that is a subkey has only one property, the inner key. The identity of the sub-entity is always the same as the principal, although not every key of the principal wil be a valid subkey. Subkeys are used for dependent entities with a 0..1 to 1 relationship to their principle, that have a primary key which is also the foreign key.

Extensions

Several extension method classes that provide generic functionality for types that implement the pattern interfaces.

CanBeEmptyExtensions

A set of extension methods that work for any instance of a type that implements ICanBeEmpty.

CanBeEmptyToNullable

Returns a (struct) value as a Nullable<T>, having the default (null-equivalent) value when it's empty.

IfNotEmpty

Applies a transform function to a ICanBeEmpty value, if the value is not empty. There are several overloads of this method to handle struct/class nullablity of the output types correctly.

NullOnEmpty

If the value is empty, returns null, otherwise returns the second provided value. There are several overloads of this method to handle struct/class nullablity of the output types correctly.

CanBeEmptyCollectionExtensions

A set of extension methods that work for collenctions of instances of a type that implements ICanBeEmpty.

FirstNonEmpty

For IEnumerable<T> where T implements ICanBeEmpty. Returns the first non-empty element in the enumeration.

GetValue

For IReadOnlyDictionary<TKey,TValue> where TKey implements ICanBeEmpty. Returns default(TValue) if the provided key is empty. Will attempt to retrieve the value normally from the dictionary if not. Throws if a non-empty key is not found.

WhereNotEmpty

For IEnumerable<T> where T implements ICanBeEmpty. Yields all non-empty elements in the enumeration.

---

Documentation generated from the XMLDoc:

<a name='assembly'></a>

Lib.Patterns

Contents

• CanBeEmptyCollectionExtensions
  • FirstNonEmpty``1(enumerable)
  • GetValue``2(dictionary,key)
  • WhereNotEmpty``1(enumerable)
• CanBeEmptyExtensions
  • CanBeEmptyToNullable``1(value)
  • IfNotEmpty``2(value,transformFunc)
  • IfNotEmpty``2(value,transformFunc)
  • NullOnEmpty``1(canBeEmpty,val)
  • NullOnEmpty``1(canBeEmpty,val)
• CanBeEmptyExtensionsX
  • IfNotEmpty``2(value,transformFunc)
• DeterminableCollectionExtensions
  • WhereDetermined``1(enumerable)
• DeterminableExtensions
  • DeterminableToNullable``1(value)
• IApproximable`1
  • IsApproximateTo(other)
• ICanBeEmpty
  • IsEmpty()
• ICanSerialize
  • Serialize()
• ICanSerialize`1
  • Deserialize(str)
• IDeterminable
  • IsDetermined
• ISimpleKey`2
  • AsNullableId()
  • FromNullableId(id)
• ISubKey`1

<a name='T-Semantica-Patterns-CanBeEmptyCollectionExtensions'></a>

CanBeEmptyCollectionExtensions type

Namespace

Semantica.Patterns

Summary

Provides additional functionality for collections of ICanBeEmpty elements.

<a name='M-Semantica-Patterns-CanBeEmptyCollectionExtensions-FirstNonEmpty1-System-Collections-Generic-IEnumerable{0}-'></a>

FirstNonEmpty``1(enumerable) method

Summary

Returns the first non-empty element in the enumeration.

Returns

A non-empty element from the enumeration, or default if there is no non-empty element.

Parameters

Name	Type	Description
enumerable	System.Collections.Generic.IEnumerable{``0}	An IEnumerable`1 of elements that implements ICanBeEmpty.

Generic Types

Name	Description
T	The type of elements in enumerable.

<a name='M-Semantica-Patterns-CanBeEmptyCollectionExtensions-GetValue2-System-Collections-Generic-IReadOnlyDictionary{0,1},0-'></a>

GetValue``2(dictionary,key) method

Summary

Retrieves the value for any non-empty key in a dictionary, or the default of TValue if the key is empty.

Returns

The value corresponding to key, or default of the key is empty.

Parameters

Name	Type	Description
dictionary	System.Collections.Generic.IReadOnlyDictionary{``0,``1}	A IReadOnlyDictionary`2 to perform the lookup in.
key	``0	The key to search for.

Generic Types

Name	Description
TKey	The type of keys in the read-only dictionary that implement ICanBeEmpty.
TValue	The type of values in the read-only dictionary.

Exceptions

Name	Description
System.Collections.Generic.KeyNotFoundException	When a non-empty key cannot be found in the dictionary.

<a name='M-Semantica-Patterns-CanBeEmptyCollectionExtensions-WhereNotEmpty1-System-Collections-Generic-IEnumerable{0}-'></a>

WhereNotEmpty``1(enumerable) method

Summary

Yields all non-empty elements in the enumeration.

Returns

A IEnumerable`1 what yields only the non-empty elements from enumerable.

Parameters

Name	Type	Description
enumerable	System.Collections.Generic.IEnumerable{``0}	An IEnumerable`1 of elements that implement ICanBeEmpty.

Generic Types

Name	Description
T	The type of elements in enumerable.

<a name='T-Semantica-Patterns-CanBeEmptyExtensions'></a>

CanBeEmptyExtensions type

Namespace

Semantica.Patterns

Summary

Provides additional functionality for types that implement ICanBeEmpty.

<a name='M-Semantica-Patterns-CanBeEmptyExtensions-CanBeEmptyToNullable1-0-'></a>

CanBeEmptyToNullable``1(value) method

Summary

Returns the value as a Nullable, or the default Nullable of T value if it is empty.

Returns

value as a Nullable, or the default if value is empty.

Parameters

Name	Type	Description
value	``0	The instance to evaluate.

Generic Types

Name	Description
T	The type of value implementing ICanBeEmpty.

<a name='M-Semantica-Patterns-CanBeEmptyExtensions-IfNotEmpty2-0,System-Func{0,1}-'></a>

IfNotEmpty``2(value,transformFunc) method

Summary

Applies a transform function to a ICanBeEmpty value, if the value is not empty.

Returns

A Nullable`1 with no value if the input is empty, otherwise the output of the transformation function.

Parameters

Name	Type	Description
value	``0	The value to evaluate.
transformFunc	System.Func{``0,``1}	The transformation function.

Generic Types

Name	Description
T	Any type that implements ICanBeEmpty.
TOut	The output type of the transformation.

<a name='M-Semantica-Patterns-CanBeEmptyExtensions-IfNotEmpty2-0,System-Func{0,System-Nullable{1}}-'></a>

IfNotEmpty``2(value,transformFunc) method

Summary

Applies a transform function to a ICanBeEmpty value, if the value is not empty.

Returns

A Nullable`1 with no value if the input is empty, otherwise the output of the transformation function.

Parameters

Name	Type	Description
value	``0	The value to evaluate.
transformFunc	System.Func{``0,System.Nullable{``1}}	The transformation function.

Generic Types

Name	Description
T	Any type that implements ICanBeEmpty.
TOut	The output type of the transformation.

<a name='M-Semantica-Patterns-CanBeEmptyExtensions-NullOnEmpty1-Semantica-Patterns-ICanBeEmpty,0-'></a>

NullOnEmpty``1(canBeEmpty,val) method

Summary

If canBeEmpty is empty, returns null, otherwise returns val. This overload is used when T is a class type.

Returns

null if canBeEmpty is empty; otherwise .

Parameters

Name	Type	Description
canBeEmpty	Semantica.Patterns.ICanBeEmpty	The instance to evaluate IsEmpty on.
val	``0	The value to return if canBeEmpty is not empty.

Generic Types

Name	Description
T	Return type and type of val.

<a name='M-Semantica-Patterns-CanBeEmptyExtensions-NullOnEmpty1-Semantica-Patterns-ICanBeEmpty,System-Nullable{0}-'></a>

NullOnEmpty``1(canBeEmpty,val) method

Summary

If canBeEmpty is empty, returns default, otherwise returns val. This overload is used when T is a struct type.

Returns

default if canBeEmpty is empty; otherwise .

Parameters

Name	Type	Description
canBeEmpty	Semantica.Patterns.ICanBeEmpty	The instance to evaluate IsEmpty on.
val	System.Nullable{``0}	The value to return if canBeEmpty is not empty.

Generic Types

Name	Description
T	Return type and type of val.

<a name='T-Semantica-Patterns-CanBeEmptyExtensionsX'></a>

CanBeEmptyExtensionsX type

Namespace

Semantica.Patterns

Summary

Provides additional functionality for ICanBeEmpty in electives, that cannot be part of CanBeEmptyExtensions because of signature overlap.

Remarks

The compiler doesn't acknoweledge the difference between a non-nullable struct and class in Func output types, unless they are on a separate class, so this weird thing has to exist.

<a name='M-Semantica-Patterns-CanBeEmptyExtensionsX-IfNotEmpty2-0,System-Func{0,1}-'></a>

IfNotEmpty``2(value,transformFunc) method

Summary

Applies a transform function to a ICanBeEmpty value, if the value is not empty.

Returns

A Nullable`1 with no value if the input is empty, otherwise the output of the transformation function.

Parameters

Name	Type	Description
value	``0	The value to evaluate.
transformFunc	System.Func{``0,``1}	The transformation function.

Generic Types

Name	Description
T	Any type that implements ICanBeEmpty.
TOut	The output type of the transformation.

<a name='T-Semantica-Patterns-DeterminableCollectionExtensions'></a>

DeterminableCollectionExtensions type

Namespace

Semantica.Patterns

Summary

Provides additional functionality for collections of IDeterminable elements.

<a name='M-Semantica-Patterns-DeterminableCollectionExtensions-WhereDetermined1-System-Collections-Generic-IEnumerable{0}-'></a>

WhereDetermined``1(enumerable) method

Summary

yields all determined elements in the enumeration.

Returns

Only detemined elements from enumerable

Parameters

Name	Type	Description
enumerable	System.Collections.Generic.IEnumerable{``0}	An IEnumerable`1 of elements that implement IDeterminable.

<a name='T-Semantica-Patterns-DeterminableExtensions'></a>

DeterminableExtensions type

Namespace

Semantica.Patterns

Summary

Provides additional functionality for types that implement IDeterminable.

<a name='M-Semantica-Patterns-DeterminableExtensions-DeterminableToNullable1-0-'></a>

DeterminableToNullable``1(value) method

Summary

Returns the value as a Nullable, with the value null if value is not determined.

Returns

value as a Nullable, or null if value is not determined.

Parameters

Name	Type	Description
value	``0	The instance to be evaluated.

Generic Types

Name	Description
T	The type of value.

<a name='T-Semantica-Patterns-IApproximable`1'></a>

IApproximable`1 type

Namespace

Semantica.Patterns

Summary

Provides functionality for types that represent values that can be approximately

Generic Types

Name	Description
T

<a name='M-Semantica-Patterns-IApproximable1-IsApproximateTo-0-'></a>

IsApproximateTo(other) method

Summary

Determines if other is approximate to this.

Returns

True if the value of this is approximately the same as other's value

Parameters

Name	Type	Description
other	`0	Instance to compare this to.

<a name='T-Semantica-Patterns-ICanBeEmpty'></a>

ICanBeEmpty type

Namespace

Semantica.Patterns

Summary

A struct or class can implement ICanBeEmpty when there is some (inescapable) default value that can be thought of as empty.

<a name='M-Semantica-Patterns-ICanBeEmpty-IsEmpty'></a>

IsEmpty() method

Summary

Determines whether the object is empty.

Returns

true if the represented value is empty (or default); otherwise, false.

Parameters

This method has no parameters.

Example

In most cases, the following implementation should suffice:

=> Equals(default(T))

<a name='T-Semantica-Patterns-ICanSerialize'></a>

ICanSerialize type

Namespace

Semantica.Patterns

Summary

A struct or class can implement ICanSerialize when it can be serialized to a string without losing any relevant information.

<a name='M-Semantica-Patterns-ICanSerialize-Serialize'></a>

Serialize() method

Summary

Serializes the instance to a string.

Returns

Een string-representation of the instance.

Parameters

This method has no parameters.

<a name='T-Semantica-Patterns-ICanSerialize`1'></a>

ICanSerialize`1 type

Namespace

Semantica.Patterns

Summary

A struct or class can implement ICanSerialize`1 when it can be serialized to a string without losing any relevant information.
In principal for any instance of a type implementing ICanSerialize`1 this should evaluate to true: instance.Deserialize(instance.Serialize()).Equals(instance)

Generic Types

Name	Description
T	The type deserialization returns, generally the instance type that this interface is applied to.

<a name='M-Semantica-Patterns-ICanSerialize`1-Deserialize-System-String-'></a>

Deserialize(str) method

Summary

Returns

A new instance of T, equivalent to str, or default(T) if deserialization failed.

Parameters

Name	Type	Description
str	System.String	serialized string representation of an instance of T.

<a name='T-Semantica-Patterns-IDeterminable'></a>

IDeterminable type

Namespace

Semantica.Patterns

Summary

A struct or class can implement IDeterminable when it has no clear undetermined state, but there is need for one. This can be particularly useful for value types when an explicit undetermined state is more clear than or functionally useful besides having a Nullable or null value.

<a name='P-Semantica-Patterns-IDeterminable-IsDetermined'></a>

IsDetermined property

Summary

Indicates whether the instance's value has been determined.

<a name='T-Semantica-Patterns-Domain-ISimpleKey`2'></a>

ISimpleKey`2 type

Namespace

Semantica.Patterns.Domain

Summary

A simple key is a key made from only one attribute

<a name='M-Semantica-Patterns-Domain-ISimpleKey`2-AsNullableId'></a>

AsNullableId() method

Parameters

This method has no parameters.

Example

In most cases, the following implementation should suffice:

=> IsEmpty() ? default(T?) : Id

<a name='M-Semantica-Patterns-Domain-ISimpleKey2-FromNullableId-System-Nullable{1}-'></a>

FromNullableId(id) method

Summary

Returns

Parameters

Name	Type	Description
id	System.Nullable{`1}	Nullable id parameter (typically the mapped database type for any optional foreign key.

Example

In most cases, the following implementation should suffice:

=> id.HasValue ? new(id.Value) : default

<a name='T-Semantica-Patterns-Domain-ISubKey`1'></a>

ISubKey`1 type

Namespace

Semantica.Patterns.Domain

Summary

A key that is a subkey has only one property, which is the inner key. The identity of the sub-entity is always the same as the principal, although not every key of the principal wil be a valid subkey. Use subkeys when other entities can reference the sub-entity, but are not valid for the main entity when it's not also a sub-entity.

Generic Types

Name	Description
TKey	Type of the key of the principal entity.