Towel Versions Save

This release includes a lot of XML documentation updates. Also, due to https://github.com/dotnet/roslyn/issues/49568, I am forced to make the XML documentation members public instead of internal for the time being.

This release includes a lot of nullable reference syntax updates.

New Features:

• TryToRomanNumeral
• Bag data structure _{(work in progress... likely to change in near future)}

Bug Fixes:

• added more exception checks to JSON and XML delegate serialization/deserialization

Changes:

• ToCompareResult converted to an extension method on int
• ArrayJagged<T> removed _{This was a legacy type that I wanted to remove for a while and just got around to it. If I add it back in Towel in the future, it will have a different design with more modularity.}
• TryParse methods on measurement types changed from bool TryParse(string, out MEASUREMENT) to (bool, MEASUREMENT?) TryParse(string)
• added more exception checks to Towel.Mathematics.Symbolics
• added more exception checks to Towel.Measurements.Measurement

Bug Fixes:

• Towel.Mathematics.Symbolics.Parse<T>(...) bug fix while parsing operations such as "squareroot(5)"
• RedBlackTreeLinked<T, TCompare>.GetEnumerator() fixed bug when tree is empty

Changes:

• renamed Compare<TSift>(...) to CompareSift<TSift>(...) on both ISortedBinaryTree<T> to avoid naming collisions
• renamed Contains<TSift>(...) to ContainsSift<TSift>(...) on both ISortedBinaryTree<T> to avoid naming collisions
• renamed TryRemove<TSift>(...) to TryRemoveSift<TSift>(...) on both ISortedBinaryTree<T> to avoid naming collisions
• changed IAddable<T> method bool TryAdd(T, out Exception) to (bool, Exception?) TryAdd(T)
  • extension methods also adjusted
• changed IRemovable<T> method bool TryRemove(T, out Exception) to (bool, Exception?) TryRemove(T)
  • extension methods also adjusted
• removed StepperRef and StepperRefBreak methods
  • this is better handled by IFunc<T, (T, StepStatus)> than a custom method signature with ref parameters. I will likely add new methods called Mutate as a replacement in the future, but for now I just removed them. Here is a benchmark that influenced this descision: https://github.com/asc-community/dotnet-benchmarks/tree/master/Benchmarks/IterationRefParametersVsReturns.
• added T[] ToArray() to IDataStructure<T> (mainly for inheritdoc)
• added ICloneable<T> (mainly for inheritdoc)
  • there appears to be a bug in roslyn regarding this: https://github.com/dotnet/roslyn/issues/54069
• exposed Bound<T> Exists and Value getters

Bug Fixes:

• Measurement Conversion Calculation https://github.com/ZacharyPatten/Towel/commit/afd51a946c0904c372dded7575585c7b43b810cf

Changes:

• ReplaceCached [method] removed (was a stupid idea...)

Note This is the first non-preview release of the Towel package on nuget.org.

New Features:

• GetEnumerator extension methods for Tuple<...>, ValueTyple<...>, and ITuple

Changes:

• TryParseRomanNumeral parameter string->ReadOnlySpan<char>
• Extensions.IsDefined generic contraints where T : Enum => where TEnum : struct, Enum
• renamed ActionRuntime<...> to SAction<...>
  • renamed .Do(...) to .Invoke(...)
• renamed FuncRuntime<...> to SFunc<...>
  • renamed .Do(...) to .Invoke(...)
• removed unnecessary mathematics delegates

New Features:

• HeapArray<T, TCompare>->MinimumCapacity [property] added setter

Bug Fixes:

• Console.IntMenu fixed bug where a hard coded value was used instead of the invalidMessage parameter
• HeapArray<T, TCompare> added exception checks for invalid minimum capacity values

Changes:

• many Towel.DataStructures namespace interfaces, types, and methods were redesigned
  • IDataStructure<T>->void Stepper(Action<T> step) [method] removed _{handled via extension methods}
  • IDataStructure<T>->StepStatus Stepper(Func<T, StepStatus> step) [method] removed _{handled via extension methods}
  • IDataStructure<T>->StepStatus StepperBreak<TStep>(TStep step = default) [method] added
  • ISortedBinaryTree<T> [interface] added
  • IAvlTree<T> [interface] added
  • AvlTreeLinked<T> [class] removed _{converted to static factory methods}
  • IRedBlackTree<T> [interface] added
  • RedBlackTreeLinked<T> [class] removed _{converted to static factory methods}
  • TreeMap<T>->TreeMap<T, TEquate, THash> [class] generic arguments changed
  • HeapArray<T> [class] removed _{converted to static factory methods}
  • SetHashLinked<T> [class] removed _{converted to static factory methods}
  • GraphMap<T>->GraphMap<T, TEquate, THash> [class] generic arguments changed
  • MapHashLinked<T, K> [class] removed _{converted to static factory methods}
  • DataStructure.IEquating<K> removed from interface IMap<T, K> [interface]
  • IEquating<T>->IEquating<T, TEquate> [interface] generic arguments changed
  • IHashing<T>->IHashing<T, THash> [interface] generic arguments changed
  • GraphSetOmnitree<T>->GraphSetOmnitree<T, TEquate, THash> [class] generic arguments changed
    • Note: a TCompare generic argument will be added in a future version when the Omnitree rewrite is complete
  • GraphWeightedMap<V, W>->GraphWeightedMap<V, W, TEquate, THash> [class] generic arguments changed

In place of types with reduced generic parameters, "New" static factory methods were added for data structures with functional generic parameters. For example, instead of var tree = new AvlTreeLinked<T>(); you now do var tree = AvlTreeLinked.New<T>();. Static factory methods are more modular that creating custom types for purposes of defaulting generic parameters.

Multiple methods not listed above were converted to "TryXxx" patterns for better versatility and exception handling.

New Features:

• CombineRanges simplifies sequences of ranges by combining ranges without gaps
• GraphWeightedMap data structure that includes weights on the edges
• Added several members to Map
  • IEnumerable<K> GetKeys()
  • IEnumerable<(T Value, K Key)> GetPairs()
  • more overloads to Stepper, Keys and Pairs to support struct generic parameters

Bug Fixes:

• OmnitreeBoundsLinked<T, Axis1...>->Stepper(step + subspace) bug fix

Changes:

• The T Minimum method was split into three methods like the maximum method was changed previously.
  • (int Index, T Value) Minimum
  • T MinimumValue
  • int MinimumIndex
• Map->void Stepper(Action<(T Value, K Key)> step) renamed to Pairs
• Map->StepStatus Stepper(Func<(T Value, K Key), StepStatus> step) renamed to PairsBreak
• Map->void Stepper(Action<K> step) renamed to Keys
• Map->StepStatus Stepper(Func<K, StepStatus> step) renamed to KeysBreak
• Graph->void Stepper(Action<(T?, T?)> step) renamed to Edges
• Graph->StepStatus Stepper(Func<(T, T), StepStatus> step) renamed to EdgesBreak
• several stepper methods were altered to use value tuples rather that multiple parameters

New Features:

• GetXmlName (was coupled with GetDocumentation, but now it is exposed on it's own)
  • FieldInfo
  • PropertyInfo
  • EventInfo
  • ConstructorInfo
  • MethodInfo
  • Type
• GetLeast
• GetGreatest

Bug Fixes:

• CommandLine.HandleArguments: fixed minor bug where it was allowing parameters with single - characters rather than two
• QueueArray<T>.Newest: needed a - 1 on the index
• QueueArray<T>[int index]: logic operators were wrong on min/max indices

New Features:

• Choose (span overload)

Bug Fixes:

• Next (random generation methods): fixed algorithm selection calculation.

New Features:

• Next Random (exclusion overload)
• NextUnique Random Roll + Pool Tracking (exclusion overload)
• SetEquals (span)
• ContainsDuplicates (span)
• Contains (span)
• Any (span)

Bug Fixes:

• NextUnique (additional exception throwing checks)

Changes:

• NextUnique (added missing overloads)

New Features:

• Combinations
• IsReorderOf
• MapHashLinked<...>.AddOrUpdate
• MapHashLinked<...>.TryUpdate

Bug Fixes:

• QueueArray.MinimumCapacity bug fix

Changes:

• The data structure interfaces have been modified to include the _Compare generic parameter on some appropriate data structures (ex Heap, AVL Tree, and Red Black Tree)
• Added implicit casting operators from UniversalQuantification to Span/Memory types
• Stack/Queue minimum capacity properties made nullable and slight tweaks to the logic

Note: there will be similar changes to other data structure interfaces in future releasese