DoNetExtensions 0.0.7

Please check the project GitHub for full description. This is a trimmed version due to length limit. Make sure use command "Install-Package DoNetExtensions" to get the latest version.

Initial Release

This initial release includes several extensions for arrays and collections as shown below. Currently all methods are under the same namespace as the classes they extend. Therefore, the usage is to just add reference to the extension library, import the namespace like "System.Collections" as usual, and then benefit from the added methods.

Each method may have multiple overloads. We are unable to present them one by one here, but these methods are very intuitive and have full XML documentation. We carefully tag AggressiveInlining attribute to "short" extensions to avoid impacting performance. We present chosen features of this extensions.

1. Consistent Containment Check -- The "In" Method

Instead of "a.Contains(b)", we provide an alternative "b.In(a)". If "a" is a collection, the the method checks if "b" is an element in "a"; if "a" is a dictionary, then the method checks if "b" is a key in "a". This "In" method is somewhat "python" style, shorter and more consistent; besides that, it returns false for null reference.

var arr = new[] {1,2,3};
if (1.In(arr)) // equivalent to arr.Contains(1)
  Do something...

var dict = new Dictionary<string, int> { { "a", 1 } };
if ("a".In(dict)) // equivalent to dict.ContainsKey("a")
  Do something...

arr = null;
1.In(arr); // returns false

dict = null;
"a".In(dict); // returns false

In: returns true if the element to check is contained in an array/list/collection, or a key of a dictionary.

2. Collection to Array Conversion

var list = new List<int>();
var arr = list.ToArrayOrNull(); // returns a null reference
list.Add(1);
list.Add(2);
arr = list.ToArrayOrNull(); // returns an array [1,2]
arr = list.ToArrayThenClear(); // returns an array [1,2] and clears the list
arr = list.ToArrayOrNull(); // returns a null reference because list has been cleared.

ToArrayOrNull: returns a null reference if the collection is empty (rather than returns an empty array by the build-in ToArray() method), or otherwise works like build-in ToArray() method.

ToArrayThenClear: works like the build-in ToArray() method, but clears the collection after the elements are output to the array.

ToArrayOrNullThenClear: works like the ToArrayOrNull() method, but clears the collection after the elements are output to the array.

3. Consistent Emptiness Check

Although incredibly useful, the emptiness of an array or a collection has to be checked in a clumsy way, even for today after 10 years.

var arr = new int[] {1,2,3};
if (arr != null && arr.Length != 0) // NOTE: the new syntax "arr?.Length != 0" will not do the check as desired!
  Do something...
  
var list = new List<int> {1,2,3};
if (list != null && arr.Count != 0) // NOTE: have to use a different property "Count"
  Do something...

Now with the extension, above can be greatly simplified and more readable. The method is added to both arrays and collections.

var arr = new int[] {1,2,3};
if (arr.IsNotNullOrEmpty())
  Do something...
  
var list = new List<int> { 1,2,3};
if (list.IsNotNullOrEmpty())
  Do something...
  
var dict = new Dictionary<string, int> { { "a", 1 } };
if (dict.IsNotNullOrEmpty())
  Do something...

IsNullOrEmpty: Returns true if a collection is a null reference or is an empty collection.

IsNotNullOrEmpty: Returns true if a collection is not a null reference or is not an empty collection.

IsEmpty: Returns true if a collection is an empty collection (throws an NullReferenceException if it is a null reference).

IsNotEmpty: Returns true if a collection is not an empty collection (throws an NullReferenceException if it is a null reference).

4. Convenient IndexOf

Adds extension methods that dummpy the Array.IndexOf and static Array.IndexOf methods. Also adds support for searches of subarrays.

var arr = new [] {1, 2, 3, 4};
arr.IndexOf(2); //returns 1, equivalent to Array.IndexOf(arr, 2)
arr.IndexOf(2, 2); // searches for 2 starting at position 2 of the array, so returns -1
arr.IndexOf(4, 1, 2); // searches for 4 starting at position 1 of the array, and only compares 2 elements afterwards, so returns -1
arr.IndexOf(4, 1, 3); // return 3

arr.IndexOf(new[] {3, 4}); // searches the subarray and returns 2.

5. Collection to Concatenated String

var arr = new int[] {1,2,3};
arr.ToConcatString(','); // returns "1,2,3"
arr.ToConcatString("--"); // returns "1--2--3"

6. Array Updating Operations

It is not uncommon that we might need to just add/remove one specified item to/from an array, and return a new array with the item added/removed (for example, such addition/removal is rarely used by the client, and it is not desirable to complicate the code design with other data structure like list or linked list).

var arr = new int[] {1,2,3};
var arr2 = arr.Remove(2); // returns a new array instance [1,3]
var arr3 = arr.RemoveAt(2); // returns a new array instance [1,2]
var arr4 = arr.AddFirst(0); // returns a new array instance [0,1,2,3]
var arr5 = arr.AddLast(4); // returns a new array instance [1,2,3,4]
var arr6 = arr.Insert(18, index:2); // returns a new array [1,2,18,3], with 18 inserted at position 2
var arr7 = arr.Insert(arr, index:2); // returns a new array [1,2,1,2,3,3], with "1,2,3" inserted at position 2

var merged = (new[] { arr, arr2, arr3, arr4, arr5, arr6, arr7}).Merge(); // merges all above arrays into on single array.

7. Convenient Swap & Bit Operations

Swapping two values have been an annoying issue that disrupts code readability. The following extensions address this problem. It is implemented by efficient bit operations when possible.

var a = 1;
var b = 2;
a.Swap(ref b);
Console.WriteLine(a); // prints 2
Console.WriteLine(b); // prints 1

var t1 = DateTime.Now;
var t2 = new DateTime(2010, 10, 22);
t1.Swap(ref t2);
Console.WriteLine(t1); // prints "[10/22/2010 12:00:00 AM]"
Console.WriteLine(t2); // prints the recorded time

In this category, we also provide convenient extensions to retrieve higer bits or lower bits of a value of type long/ulong, int/uint, short/ushort or byte. Following gives two examples, for full description see the method XML documentation.

int a = 100;
var a_high = a.High(); // gets the higher 16 bits of this 32-bit integer, represented by a 16-bit unsigned integer, which is 0 in this case.

byte b = 100;
var b_low = b.Low(); // Gets the lower 4 bits of _b_. The returned value is a byte, and the lower 4 bits of _b_ is positioned at the lower half of the returned byte. For example, the bits of this case is _01100100_, and it returns _00000100_.
var b_high = b.High(); // Gets the higher 4 bits of _b_. The returned value is a byte, and the higher 4 bits of _b_ is positioned at the LOWER half of the returned byte. For example, the bits of this case is _01100100_, and it returns _00000110_.

Swap: Swaps the current value of struct types with another value.

High: Returns the higher-half bits (the left half if you write the value as a 0-1 string) of a supported value.

Low: Returns the lower-half bits (the right half if you write the value as a 0-1 string) of a supported value.