Core: fix typos, translate to english

Doxense.Core/Collections/Cola/ColaOrderedDictionary.cs

@@ -195,7 +195,7 @@ public bool AddOrUpdate(TKey key, TValue value)
 			return true;
 		}
 
-		/// <summary>Try to add an entry with the specified key and value to the sorted dictionary, if it does not already exists.</summary>
+		/// <summary>Try to add an entry with the specified key and value to the sorted dictionary, if it does not already exist.</summary>
 		/// <param name="key">The key of the entry to add.</param>
 		/// <param name="value">The value of the entry to add.</param>
 		/// <param name="actualValue">Receives the previous value if <paramref name="key"/> already exists, or <paramref name="value"/> if it was inserted</param>
@@ -235,7 +235,7 @@ public bool ContainsValue(TValue value)
 
 		/// <summary>Determines whether this dictionary contains a specified key.</summary>
 		/// <param name="equalKey">The key to search for.</param>
-		/// <param name="actualKey">The matching key located in the dictionary if found, or equalkey if no match is found.</param>
+		/// <param name="actualKey">The matching key located in the dictionary if found, or <paramref name="equalKey"/> if no match is found.</param>
 		/// <returns>true if a match for <paramref name="equalKey"/> is found; otherwise, false.</returns>
 		public bool TryGetKey(TKey equalKey, out TKey actualKey)
 		{
@@ -334,9 +334,8 @@ public int RemoveRange(IEnumerable<TKey> keys)
 
 		public IEnumerable<TKey> IterateAndRemoveRange(TKey begin, bool beginEqual, TKey end, bool endEqual)
 		{
-			// c'est le pire opérateur pour un COLA!
-			// l'opération actuelle est SUPER LENTE!
-			// => il faudrait l'optimiser mais pour ca il faudrait touche directement les levels
+			// This is the worst case scenario for COLA: this operation is VERY SLOW!
+			// => It should be optimized, but for this it would need to modify the levels directly
 
 			var kvNext = new KeyValuePair<TKey, TValue>(begin, default!);
 			var cmp = m_keyComparer;
@@ -352,7 +351,10 @@ public IEnumerable<TKey> IterateAndRemoveRange(TKey begin, bool beginEqual, TKey
 
 				yield return candidate.Key;
 				m_items.RemoveAt(level, offset);
-				if (!endEqual && p == 0) break; // on évite un search de trop!
+				if (!endEqual && p == 0)
+				{ // prevent one extra search operation!
+					break;
+				}
 			}
 			while (true);
 		}

Doxense.Core/Collections/Cola/ColaOrderedSet.cs

@@ -143,13 +143,12 @@ public bool TryRemove(T value, out T actualValue)
 
 		public bool Remove(T value)
 		{
-			T _;
 			return TryRemove(value, out _);
 		}
 
 		public T RemoveAt(int arrayIndex)
 		{
-			if (arrayIndex < 0 || arrayIndex >= m_items.Count) throw new ArgumentOutOfRangeException("arrayIndex", "Index is outside the array");
+			if (arrayIndex < 0 || arrayIndex >= m_items.Count) throw new ArgumentOutOfRangeException(nameof(arrayIndex), "Index is outside the array");
 
 			int level = ColaStore.MapOffsetToLocation(m_items.Count, arrayIndex, out var offset);
 			Contract.Debug.Assert(level >= 0 && offset >= 0 && offset < 1 << level);
@@ -163,17 +162,14 @@ public T RemoveAt(int arrayIndex)
 		/// <returns>true if the set contains the specified value; otherwise, false.</returns>
 		public bool Contains(T value)
 		{
-			int _;
-			T __;
-			return m_items.Find(value, out _, out __) >= 0;
+			return m_items.Find(value, out _, out _) >= 0;
 		}
 
 		/// <summary>Find an element </summary>
 		/// <param name="value"></param>
 		/// <returns>The zero-based index of the first occurrence of <paramref name="value"/> within the entire list, if found; otherwise, –1.</returns>
 		public int IndexOf(T value)
 		{
-			T _;
 			int level = m_items.Find(value, out var offset, out _);
 			if (level >= 0)
 			{
@@ -188,7 +184,6 @@ public int IndexOf(T value)
 		/// <returns>A value indicating whether the search was successful.</returns>
 		public bool TryGetValue(T value, out T actualValue)
 		{
-			int _;
 			return m_items.Find(value, out _, out actualValue) >= 0;
 		}
 

Doxense.Core/Collections/Cola/ColaRangeDictionary.cs

@@ -87,7 +87,7 @@ public override string ToString()
 			}
 
 			[MethodImpl(MethodImplOptions.AggressiveInlining)]
-			public void Desconstruct(out TKey? begin, out TKey? end, out TValue? value)
+			public void Deconstruct(out TKey? begin, out TKey? end, out TValue? value)
 			{
 				begin = this.Begin;
 				end = this.End;
@@ -282,7 +282,7 @@ public void Remove(TKey begin, TKey end, TKey offset, Func<TKey?, TKey, TKey> ap
 				var comparer = m_keyComparer;
 				if (!iterator.Seek(entry, true))
 				{
-					//on ne trouve pas l'item exacte, on prends le premier.
+					// could not find an exact match, use the first one instead.
 					iterator.SeekFirst();
 				}
 				var cursor = iterator.Current!;
@@ -341,7 +341,7 @@ public void Remove(TKey begin, TKey end, TKey offset, Func<TKey?, TKey, TKey> ap
 						// ------[
 						if (c3 <= 0)
 						{
-							//on set cursor pour que la translation soit faite correctement
+							// set cursor so that the translation can be done properly
 							cursor = entry;
 							break;
 						}
@@ -520,39 +520,42 @@ public void Remove(TKey begin, TKey end, TKey offset, Func<TKey?, TKey, TKey> ap
 		private void TranslateAfter(Entry? lastOk, TKey offset, Func<TKey?, TKey, TKey> applyKeyOffset)
 		{
 			var iterator = m_items.GetIterator();
-			//null il faut tout décaller
+
 			if (lastOk == null)
-			{
+			{ // null => we need to shift everything
 				if (!iterator.SeekFirst()) return;
 			}
 			else
 			{
 				if (!iterator.Seek(lastOk, true))
 				{
-					//l'element passé en parametre à été supprimé
-					//on cherche l'élément suivant
-					//si tout à été supprimé on sort.
+					// the item passed has parameter has been deleted
+					// - search for the next item
+					// - if everything has been deleted, we exit early.
 					if (!iterator.SeekFirst()) return;
 					var c = m_keyComparer.Compare(lastOk.End, iterator.Current!.Begin);
 					while (c > 0 && iterator.Next())
 					{
 						c = m_keyComparer.Compare(lastOk.End, iterator.Current!.Begin);
 					}
 				}
-				//on veut décaller les suivants de celui passé en parametre
-				else iterator.Next();
+				else
+				{
+					// we want to shift the item that follow the one passed as parameter
+					iterator.Next();
+				}
 			}
 			do
 			{
 				var cursor = iterator.Current;
-				//dans le cas ou tout à été supprimé après le lastOK l'iterator est déjà au bout quand on arrive ici...
+				// in the case where everything has been deleted after lastOK, the iterator is already passed the end when we reach here
 				if (cursor == null) break;
 
 				cursor.Begin = applyKeyOffset(cursor.Begin, offset);
 				cursor.End = applyKeyOffset(cursor.End, offset);
 			}
 			while (iterator.Next());
-			//on décalle les bounds correctement
+			// shift the bounds if required
 			if (iterator.SeekFirst()) m_bounds.Begin = iterator.Current!.Begin;
 			if (iterator.SeekLast()) m_bounds.End = iterator.Current!.End;
 		}
@@ -563,7 +566,7 @@ public void Mark(TKey begin, TKey end, TValue value)
 
 			// adds a new interval to the dictionary by overwriting or splitting any previous interval
 			// * if there are no interval, or the interval is disjoint from all other intervals, it is inserted as-is
-			// * if the new interval completly overwrites one or more intervals, they will be replaced by the new interval
+			// * if the new interval completely overwrites one or more intervals, they will be replaced by the new interval
 			// * if the new interval partially overlaps with one or more intervals, they will be split into chunks, and the new interval will be inserted between them
 
 			// Examples:
@@ -848,7 +851,7 @@ public void Mark(TKey begin, TKey end, TValue value)
 								{ // there was no previous entry, but still check the next one
 									var next = iterator.Current;
 									if (next != null && cmp.Compare(next.Begin, end) == 0 && m_valueComparer.Equals(next.Value, value))
-									{ // the next one is contigious and with the same value, it can be merged!
+									{ // the next one is contiguous and with the same value, it can be merged!
 
 										//   x        [=====)..
 										// + x[=======)
@@ -1007,7 +1010,7 @@ public void Mark(TKey begin, TKey end, TValue value)
 								if (!inserted)
 								{ // use that slot to insert ourselves
 									cursor.Set(entry);
-									//get the reference to be able to eventually merge it afterwards
+									// get the reference to be able to eventually merge it afterward
 									entry = cursor;
 									inserted = true;
 								}

Doxense.Core/Collections/Cola/ColaRangeSet.cs

@@ -24,7 +24,7 @@
 // SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 #endregion
 
-// enables consitency checks after each operation to the set
+// enables consistency checks after each operation to the set
 #define ENFORCE_INVARIANTS
 
 namespace Doxense.Collections.Generic
@@ -292,7 +292,7 @@ public void Mark(TKey begin, TKey end)
 							}
 						}
 						else
-						{ // we havent inserted the key yet, so in case of conflict, we will use the next segment's slot
+						{ // we haven't inserted the key yet, so in case of conflict, we will use the next segment's slot
 							if (Resolve(cursor, entry))
 							{
 								//Console.WriteLine("  > merged in place: " + cursor);

Doxense.Core/Collections/Cola/ColaStore.cs

@@ -197,7 +197,7 @@ internal static int BinarySearch<T>(T[] array, int offset, int count, T value, I
 		{
 			Contract.Debug.Assert(array != null && offset >= 0 && count >= 0 && comparer != null);
 
-			// Instead of starting from the midle we will exploit the fact that, since items are usually inserted in order, the value is probably either to the left or the right of the segment.
+			// Instead of starting from the middle we will exploit the fact that, since items are usually inserted in order, the value is probably either to the left or the right of the segment.
 			// Also, since most activity happens in the top levels, the search array is probably very small (size 1, 2 or 4)
 
 			if (count == 0)
@@ -269,7 +269,7 @@ internal static void MergeSimple<T>(T[] segment, T left, T right, IComparer<T> c
 		}
 
 		/// <summary>Replace a value in a segment with another value, while keeping it sorted</summary>
-		/// <param name="segment">Segment that will received the new value</param>
+		/// <param name="segment">Segment that will receive the new value</param>
 		/// <param name="offset">Offset of replaced value in the segment</param>
 		/// <param name="value">New value to insert into the segment</param>
 		/// <param name="comparer">Comparer to use</param>
@@ -364,8 +364,8 @@ internal static void MergeSort<T>(T[] output, T[] left, T[] right, IComparer<T>
 			Contract.Debug.Requires(left.Length > 0 && output.Length == left.Length * 2 && right.Length == left.Length);
 
 			int c, n = left.Length;
-			// note: The probality to merge an array of size N is rougly 1/N (with N being a power of 2),
-			// which means that we will spend roughly half the time merging arrays of size 1 into an array of size 2..
+			// note: The probability to merge an array of size N is roughly 1/N (with N being a power of 2),
+			// which means that we will spend roughly half the time merging arrays of size 1 into an array of size 2...
 
 			if (n == 1)
 			{ // Most frequent case (p=0.5)
@@ -729,12 +729,12 @@ internal static IEnumerable<T> IterateOrdered<T>(int count, T[][] inputs, ICompa
 			Contract.Debug.Requires(count >= 0 && inputs != null && comparer != null);
 
 			// We will use a list of N cursors, set to the start of their respective levels.
-			// A each turn, look for the smallest key referenced by the cursors, return that one, and advance its cursor.
+			// At each turn, look for the smallest key referenced by the cursors, return that one, and advance its cursor.
 			// Once a cursor is past the end of its level, it is set to -1 and is ignored for the rest of the operation
 
 			if (count > 0)
 			{
-				// setup the cursors, with the empty levels already marked as completed
+				// set up the cursors, with the empty levels already marked as completed
 				var cursors = new int[inputs.Length];
 				for (int i = 0; i < cursors.Length; i++)
 				{
@@ -744,7 +744,7 @@ internal static IEnumerable<T> IterateOrdered<T>(int count, T[][] inputs, ICompa
 					}
 				}
 
-				// pre compute the first/last active level
+				// pre-compute the first/last active level
 				int min = LowestBit(count);
 				int max = HighestBit(count);
 

Doxense.Core/Collections/Cola/ColaStore`1.cs

@@ -308,7 +308,7 @@ public int Find(T value, out int offset, out T actualValue)
 			if ((m_count & 1) != 0)
 			{
 				// If someone gets the last inserted key, there is a 50% change that it is in the root
-				// (if not, it will the the last one of the first non-empty level)
+				// (if not, it will the last one of the first non-empty level)
 				if (m_comparer.Compare(value, m_root[0]) == 0)
 				{
 					offset = 0;
@@ -426,7 +426,7 @@ public T GetAt(int level, int offset)
 			return segment[offset];
 		}
 
-		/// <summary>Store a value at a specific location in the arrayh</summary>
+		/// <summary>Store a value at a specific location in the array</summary>
 		/// <param name="arrayIndex">Absolute index in the vector-array</param>
 		/// <param name="value">Value to store</param>
 		/// <returns>Previous value at that location</returns>
@@ -484,7 +484,7 @@ public void Clear()
 		/// <summary>Add a value to the array</summary>
 		/// <param name="value">Value to add to the array</param>
 		/// <param name="overwriteExistingValue">If <paramref name="value"/> already exists in the array and <paramref name="overwriteExistingValue"/> is true, it will be overwritten with <paramref name="value"/></param>
-		/// <returns>If the value did not  if the value was been added to the array, or false if it was already there.</returns>
+		/// <returns><c>true</c>if the value was added to the array, or <c>false</c> if it was already there.</returns>
 		public bool SetOrAdd(T value, bool overwriteExistingValue)
 		{
 			int level = Find(value, out var offset, out _);
@@ -725,11 +725,11 @@ public T RemoveAt(int level, int offset)
 			else
 			{
 				// we are missing a spot in out modified segment, that need to fill
-				// > we will take the first non empty segment, and break it in pieces
+				// > we will take the first non-empty segment, and break it in pieces
 				//  > its last item will be used to fill the empty spot
 				//  > the rest of its items will be spread to all the previous empty segments
 
-				// find the first non empty segment that can be broken
+				// find the first non-empty segment that can be broken
 				int firstNonEmptyLevel = ColaStore.LowestBit(m_count);
 
 				if (firstNonEmptyLevel == level)
@@ -951,7 +951,7 @@ public T Max()
 		/// <summary>Returns the smallest and largest element in the store</summary>
 		/// <param name="min">Receives the value of the smallest element (or default(T) is the store is Empty)</param>
 		/// <param name="max">Receives the value of the largest element (or default(T) is the store is Empty)</param>
-		/// <remarks>If the store contains only one element, than min and max will be equal</remarks>
+		/// <remarks>If the store contains only one element, then min and max will be equal</remarks>
 		public bool TryGetBounds([MaybeNullWhen(false)] out T min, [MaybeNullWhen(false)] out T max)
 		{
 			switch (m_count)
@@ -1153,8 +1153,8 @@ public sealed class Iterator
 			private T? m_current;
 			private int m_currentLevel;
 			private int m_direction;
-#if DEBUG
-			private ColaStore<T> m_parent; // usefull when troubleshooting to have the pointer to the parent!
+#if FULL_DEBUG
+			private ColaStore<T> m_parent; // useful when troubleshooting to have the pointer to the parent!
 #endif
 
 			internal Iterator(ColaStore<T> store)
@@ -1165,7 +1165,7 @@ internal Iterator(ColaStore<T> store)
 				m_comparer = store.m_comparer;
 
 				m_cursors = ColaStore.CreateCursors(m_count, out m_min);
-#if DEBUG
+#if FULL_DEBUG
 				m_parent = store;
 #endif
 			}
@@ -1287,7 +1287,7 @@ public bool SeekLast()
 			/// <param name="orEqual">When <see cref="item"/> exists: if <c>true</c>, then seek to this item. If <c>false</c>, seek to the previous entry.</param>
 			public bool Seek(T item, bool orEqual)
 			{
-				// Goal: we want to find the item key itself (if it exists and orEqual==true), or the max key that is stricly less than item
+				// Goal: we want to find the item key itself (if it exists and orEqual==true), or the max key that is strictly less than item
 				// We can use BinarySearch to look in each segment for where that key would be, but we have to compensate for the fact that BinarySearch looks for the smallest key that is greater than or equal to the search key.
 
 				// Also, the iterator can be used to move:
@@ -1359,7 +1359,7 @@ public bool Seek(T item, bool orEqual)
 				return maxLevel >= 0;
 			}
 
-			/// <summary>Move the cursor the the smallest value that is greater than the current value</summary>
+			/// <summary>Move the cursor the smallest value that is greater than the current value</summary>
 			public bool Next()
 			{
 				// invalid position, or no more values
@@ -1422,7 +1422,7 @@ public bool Next()
 				return minLevel >= 0;
 			}
 
-			/// <summary>Move the cursor the the largest value that is smaller than the current value</summary>
+			/// <summary>Move the cursor the largest value that is smaller than the current value</summary>
 			public bool Previous()
 			{
 				// invalid position, or no more values