Make parsing and formatting utility method naming more accurate and c…

…onsistent (#925)

* Rename NumUtils parsing/formatting methods to follow expected .NET API patterns

* Also makes them more consistent with RespRead/WriteUtils naming
* Revamp xmldoc comments.
* Includes some adjustments in consumption of these methods, no behavioral changes.

* Add Try -prefix and use .NET naming method naming convetions in RespRead/WriteUtils.

* This makes it the assumptions of the method much more visible to callers.

* Remove unnecessary try-catch logic from integer/double validation

* NumUtils.TryReadDouble/Int64 has no (sane) situatioin it would throw on here.

* More wrapper utility methods to follow the proposed naming for consistency.

Add exception throwing xmldoc details to TryRead methods

* fix typo

* More RespReadUtils xmldoc

* fix merge

---------

Co-authored-by: Tal Zaccai <[email protected]>

benchmark/BDN.benchmark/Cluster/ClusterContext.cs

@@ -49,8 +49,8 @@ public void AddSlotRange(List<(int, int)> slotRanges)
             foreach (var slotRange in slotRanges)
             {
                 var clusterAddSlotsRange = Encoding.ASCII.GetBytes($"*4\r\n$7\r\nCLUSTER\r\n$13\r\nADDSLOTSRANGE\r\n" +
-                    $"${NumUtils.NumDigits(slotRange.Item1)}\r\n{slotRange.Item1}\r\n" +
-                    $"${NumUtils.NumDigits(slotRange.Item2)}\r\n{slotRange.Item2}\r\n");
+                    $"${NumUtils.CountDigits(slotRange.Item1)}\r\n{slotRange.Item1}\r\n" +
+                    $"${NumUtils.CountDigits(slotRange.Item2)}\r\n{slotRange.Item2}\r\n");
                 fixed (byte* req = clusterAddSlotsRange)
                     _ = session.TryConsumeMessages(req, clusterAddSlotsRange.Length);
             }
@@ -68,27 +68,27 @@ public void CreateGetSet(int keySize = 8, int valueSize = 32, int batchSize = 10
                 benchUtils.RandomBytes(ref pairs[i].Item2);
             }
 
-            var setByteCount = batchSize * ("*2\r\n$3\r\nSET\r\n"u8.Length + 1 + NumUtils.NumDigits(keySize) + 2 + keySize + 2 + 1 + NumUtils.NumDigits(valueSize) + 2 + valueSize + 2);
+            var setByteCount = batchSize * ("*2\r\n$3\r\nSET\r\n"u8.Length + 1 + NumUtils.CountDigits(keySize) + 2 + keySize + 2 + 1 + NumUtils.CountDigits(valueSize) + 2 + valueSize + 2);
             var setReq = new Request(setByteCount);
             var curr = setReq.ptr;
             var end = curr + setReq.buffer.Length;
             for (var i = 0; i < batchSize; i++)
             {
-                _ = RespWriteUtils.WriteArrayLength(3, ref curr, end);
-                _ = RespWriteUtils.WriteBulkString("SET"u8, ref curr, end);
-                _ = RespWriteUtils.WriteBulkString(pairs[i].Item1, ref curr, end);
-                _ = RespWriteUtils.WriteBulkString(pairs[i].Item2, ref curr, end);
+                _ = RespWriteUtils.TryWriteArrayLength(3, ref curr, end);
+                _ = RespWriteUtils.TryWriteBulkString("SET"u8, ref curr, end);
+                _ = RespWriteUtils.TryWriteBulkString(pairs[i].Item1, ref curr, end);
+                _ = RespWriteUtils.TryWriteBulkString(pairs[i].Item2, ref curr, end);
             }
 
-            var getByteCount = batchSize * ("*2\r\n$3\r\nGET\r\n"u8.Length + 1 + NumUtils.NumDigits(keySize) + 2 + keySize + 2);
+            var getByteCount = batchSize * ("*2\r\n$3\r\nGET\r\n"u8.Length + 1 + NumUtils.CountDigits(keySize) + 2 + keySize + 2);
             var getReq = new Request(getByteCount);
             curr = getReq.ptr;
             end = curr + getReq.buffer.Length;
             for (var i = 0; i < batchSize; i++)
             {
-                _ = RespWriteUtils.WriteArrayLength(2, ref curr, end);
-                _ = RespWriteUtils.WriteBulkString("GET"u8, ref curr, end);
-                _ = RespWriteUtils.WriteBulkString(pairs[i].Item1, ref curr, end);
+                _ = RespWriteUtils.TryWriteArrayLength(2, ref curr, end);
+                _ = RespWriteUtils.TryWriteBulkString("GET"u8, ref curr, end);
+                _ = RespWriteUtils.TryWriteBulkString(pairs[i].Item1, ref curr, end);
             }
             singleGetSet = [getReq, setReq];
         }
@@ -105,31 +105,31 @@ public void CreateMGetMSet(int keySize = 8, int valueSize = 32, int batchSize =
                 benchUtils.RandomBytes(ref pairs[i].Item2);
             }
 
-            var mGetHeaderSize = 1 + NumUtils.NumDigits(1 + batchSize) + 2 + "$4\r\nMGET\r\n"u8.Length;
-            var getRespSize = 1 + NumUtils.NumDigits(keySize) + 2 + keySize + 2;
+            var mGetHeaderSize = 1 + NumUtils.CountDigits(1 + batchSize) + 2 + "$4\r\nMGET\r\n"u8.Length;
+            var getRespSize = 1 + NumUtils.CountDigits(keySize) + 2 + keySize + 2;
             var mGetByteCount = mGetHeaderSize + (batchSize * getRespSize);
             var mGetReq = new Request(mGetByteCount);
 
             var curr = mGetReq.ptr;
             var end = curr + mGetReq.buffer.Length;
-            _ = RespWriteUtils.WriteArrayLength(1 + batchSize, ref curr, end);
-            _ = RespWriteUtils.WriteBulkString("MGET"u8, ref curr, end);
+            _ = RespWriteUtils.TryWriteArrayLength(1 + batchSize, ref curr, end);
+            _ = RespWriteUtils.TryWriteBulkString("MGET"u8, ref curr, end);
             for (var i = 0; i < batchSize; i++)
-                _ = RespWriteUtils.WriteBulkString(pairs[i].Item1, ref curr, end);
+                _ = RespWriteUtils.TryWriteBulkString(pairs[i].Item1, ref curr, end);
 
-            var mSetHeaderSize = 1 + NumUtils.NumDigits(1 + (batchSize * 2)) + 2 + "$4\r\nMSET\r\n"u8.Length;
-            var setRespSize = 1 + NumUtils.NumDigits(keySize) + 2 + keySize + 2 + 1 + NumUtils.NumDigits(valueSize) + 2 + valueSize + 2;
+            var mSetHeaderSize = 1 + NumUtils.CountDigits(1 + (batchSize * 2)) + 2 + "$4\r\nMSET\r\n"u8.Length;
+            var setRespSize = 1 + NumUtils.CountDigits(keySize) + 2 + keySize + 2 + 1 + NumUtils.CountDigits(valueSize) + 2 + valueSize + 2;
             var mSetByteCount = mSetHeaderSize + (batchSize * setRespSize);
             var mSetReq = new Request(mSetByteCount);
 
             curr = mSetReq.ptr;
             end = curr + mSetReq.buffer.Length;
-            _ = RespWriteUtils.WriteArrayLength(1 + (batchSize * 2), ref curr, end);
-            _ = RespWriteUtils.WriteBulkString("MSET"u8, ref curr, end);
+            _ = RespWriteUtils.TryWriteArrayLength(1 + (batchSize * 2), ref curr, end);
+            _ = RespWriteUtils.TryWriteBulkString("MSET"u8, ref curr, end);
             for (var i = 0; i < batchSize; i++)
             {
-                _ = RespWriteUtils.WriteBulkString(pairs[i].Item1, ref curr, end);
-                _ = RespWriteUtils.WriteBulkString(pairs[i].Item2, ref curr, end);
+                _ = RespWriteUtils.TryWriteBulkString(pairs[i].Item1, ref curr, end);
+                _ = RespWriteUtils.TryWriteBulkString(pairs[i].Item2, ref curr, end);
             }
             singleMGetMSet = [mGetReq, mSetReq];
         }
@@ -145,18 +145,18 @@ public void CreateCTXNSET(int keySize = 8, int batchSize = 100)
                 benchUtils.RandomBytes(ref keys[i], startOffset: keyTag.Length);
             }
 
-            var ctxnsetByteCount = "*9\r\n$7\r\nCTXNSET\r\n"u8.Length + (8 * (1 + NumUtils.NumDigits(keySize) + 2 + keySize + 2));
+            var ctxnsetByteCount = "*9\r\n$7\r\nCTXNSET\r\n"u8.Length + (8 * (1 + NumUtils.CountDigits(keySize) + 2 + keySize + 2));
             var ctxnsetReq = new Request(batchSize * ctxnsetByteCount);
             var curr = ctxnsetReq.ptr;
             var end = curr + ctxnsetReq.buffer.Length;
 
             for (var i = 0; i < batchSize; i++)
             {
-                _ = RespWriteUtils.WriteArrayLength(9, ref curr, end);
-                _ = RespWriteUtils.WriteBulkString("CTXNSET"u8, ref curr, end);
+                _ = RespWriteUtils.TryWriteArrayLength(9, ref curr, end);
+                _ = RespWriteUtils.TryWriteBulkString("CTXNSET"u8, ref curr, end);
                 for (var j = 0; j < 8; j++)
                 {
-                    _ = RespWriteUtils.WriteBulkString(keys[j], ref curr, end);
+                    _ = RespWriteUtils.TryWriteBulkString(keys[j], ref curr, end);
                 }
             }
 

benchmark/BDN.benchmark/Cluster/ClusterMigrate.cs

@@ -69,19 +69,19 @@ public void GlobalSetup()
         private void SetSlot(int slot, string state, string nodeId)
         {
             var reqBytes = "*5\r\n"u8.Length + 4 + "CLUSTER\r\n"u8.Length + 4 + "SETSLOT\r\n"u8.Length +
-                1 + NumUtils.NumDigits(slot.ToString().Length) + 2 + slot.ToString().Length + 2 +
-                1 + NumUtils.NumDigits(state.Length) + 2 + state.Length + 2 +
-                1 + NumUtils.NumDigits(nodeId.Length) + 2 + nodeId.Length + 2;
+                1 + NumUtils.CountDigits(slot.ToString().Length) + 2 + slot.ToString().Length + 2 +
+                1 + NumUtils.CountDigits(state.Length) + 2 + state.Length + 2 +
+                1 + NumUtils.CountDigits(nodeId.Length) + 2 + nodeId.Length + 2;
 
             var setSlotReq = new Request(reqBytes);
             var curr = setSlotReq.ptr;
             var end = curr + setSlotReq.buffer.Length;
-            _ = RespWriteUtils.WriteArrayLength(5, ref curr, end);
-            _ = RespWriteUtils.WriteBulkString("CLUSTER"u8, ref curr, end);
-            _ = RespWriteUtils.WriteBulkString("SETSLOT"u8, ref curr, end);
-            _ = RespWriteUtils.WriteIntegerAsBulkString(slot, ref curr, end);
-            _ = RespWriteUtils.WriteBulkString(Encoding.ASCII.GetBytes(state), ref curr, end);
-            _ = RespWriteUtils.WriteBulkString(Encoding.ASCII.GetBytes(nodeId), ref curr, end);
+            _ = RespWriteUtils.TryWriteArrayLength(5, ref curr, end);
+            _ = RespWriteUtils.TryWriteBulkString("CLUSTER"u8, ref curr, end);
+            _ = RespWriteUtils.TryWriteBulkString("SETSLOT"u8, ref curr, end);
+            _ = RespWriteUtils.TryWriteInt32AsBulkString(slot, ref curr, end);
+            _ = RespWriteUtils.TryWriteBulkString(Encoding.ASCII.GetBytes(state), ref curr, end);
+            _ = RespWriteUtils.TryWriteBulkString(Encoding.ASCII.GetBytes(nodeId), ref curr, end);
             cc.Consume(setSlotReq.ptr, setSlotReq.buffer.Length);
         }
 

benchmark/BDN.benchmark/Parsing/DoubleToResp.cs

@@ -44,7 +44,7 @@ public bool WriteDoubleAsBulkString(double value)
         public bool WriteDoubleAsBulkStringByTranscoding(double value)
         {
             var startPtr = _bufferPtr;
-            return RespWriteUtils.WriteAsciiBulkString(value.ToString(CultureInfo.InvariantCulture), ref startPtr, _bufferPtr + _buffer.Length);
+            return RespWriteUtils.TryWriteAsciiBulkString(value.ToString(CultureInfo.InvariantCulture), ref startPtr, _bufferPtr + _buffer.Length);
         }
 
         public static double[] TestDoubles => [

benchmark/BDN.benchmark/Parsing/IntegerToResp.cs

@@ -35,23 +35,23 @@ public void GlobalSetup()
         public bool WriteInt32(int value)
         {
             var startPtr = _bufferPtr;
-            return RespWriteUtils.WriteInteger(value, ref startPtr, _bufferPtr + _buffer.Length);
+            return RespWriteUtils.TryWriteInt32(value, ref startPtr, _bufferPtr + _buffer.Length);
         }
 
         [Benchmark]
         [ArgumentsSource(nameof(SignedInt64Values))]
         public bool WriteInt64(long value)
         {
             var startPtr = _bufferPtr;
-            return RespWriteUtils.WriteInteger(value, ref startPtr, _bufferPtr + _buffer.Length);
+            return RespWriteUtils.TryWriteInt64(value, ref startPtr, _bufferPtr + _buffer.Length);
         }
 
         [Benchmark]
         [ArgumentsSource(nameof(SignedInt32Values))]
         public bool WriteInt32AsBulkString(int value)
         {
             var startPtr = _bufferPtr;
-            return RespWriteUtils.WriteIntegerAsBulkString(value, ref startPtr, _bufferPtr + _buffer.Length);
+            return RespWriteUtils.TryWriteInt32AsBulkString(value, ref startPtr, _bufferPtr + _buffer.Length);
         }
 
         [Benchmark]
@@ -60,7 +60,7 @@ public void WriteInt32_AllAsciiLengths()
             for (int i = 0; i < SignedInt32MultiplesOfTen.Length; i++)
             {
                 var startPtr = _bufferPtr;
-                RespWriteUtils.WriteInteger(SignedInt32MultiplesOfTen[i], ref startPtr, _bufferPtr + _buffer.Length);
+                RespWriteUtils.TryWriteInt32(SignedInt32MultiplesOfTen[i], ref startPtr, _bufferPtr + _buffer.Length);
             }
         }
 
@@ -70,7 +70,7 @@ public void WriteInt64_AllAsciiLengths()
             for (int i = 0; i < SignedInt64MultiplesOfTen.Length; i++)
             {
                 var startPtr = _bufferPtr;
-                RespWriteUtils.WriteInteger(SignedInt64MultiplesOfTen[i], ref startPtr, _bufferPtr + _buffer.Length);
+                RespWriteUtils.TryWriteInt64(SignedInt64MultiplesOfTen[i], ref startPtr, _bufferPtr + _buffer.Length);
             }
         }
 
@@ -80,7 +80,7 @@ public void WriteInt32BulkString_AllAsciiLengths()
             for (int i = 0; i < SignedInt32MultiplesOfTen.Length; i++)
             {
                 var startPtr = _bufferPtr;
-                RespWriteUtils.WriteIntegerAsBulkString(SignedInt32MultiplesOfTen[i], ref startPtr, _bufferPtr + _buffer.Length);
+                RespWriteUtils.TryWriteInt32AsBulkString(SignedInt32MultiplesOfTen[i], ref startPtr, _bufferPtr + _buffer.Length);
             }
         }
 

benchmark/BDN.benchmark/Parsing/RespToInteger.cs

@@ -20,7 +20,7 @@ public int ReadLengthHeader(AsciiTestCase testCase)
             fixed (byte* inputPtr = testCase.Bytes)
             {
                 var start = inputPtr;
-                RespReadUtils.ReadSignedLengthHeader(out var value, ref start, start + testCase.Bytes.Length);
+                RespReadUtils.TryReadSignedLengthHeader(out var value, ref start, start + testCase.Bytes.Length);
                 return value;
             }
         }
@@ -32,7 +32,7 @@ public long ReadInt64(AsciiTestCase testCase)
             fixed (byte* inputPtr = testCase.Bytes)
             {
                 var start = inputPtr;
-                RespReadUtils.Read64Int(out var value, ref start, start + testCase.Bytes.Length);
+                RespReadUtils.TryReadInt64(out var value, ref start, start + testCase.Bytes.Length);
                 return value;
             }
         }
@@ -44,7 +44,7 @@ public int ReadIntWithLengthHeader(AsciiTestCase testCase)
             fixed (byte* inputPtr = testCase.Bytes)
             {
                 var start = inputPtr;
-                RespReadUtils.ReadIntWithLengthHeader(out var value, ref start, start + testCase.Bytes.Length);
+                RespReadUtils.TryReadInt32WithLengthHeader(out var value, ref start, start + testCase.Bytes.Length);
                 return value;
             }
         }
@@ -56,7 +56,7 @@ public long ReadLongWithLengthHeader(AsciiTestCase testCase)
             fixed (byte* inputPtr = testCase.Bytes)
             {
                 var start = inputPtr;
-                RespReadUtils.ReadLongWithLengthHeader(out var value, ref start, start + testCase.Bytes.Length);
+                RespReadUtils.TryReadInt64WithLengthHeader(out var value, ref start, start + testCase.Bytes.Length);
                 return value;
             }
         }
@@ -68,7 +68,7 @@ public ulong ReadULongWithLengthHeader(AsciiTestCase testCase)
             fixed (byte* inputPtr = testCase.Bytes)
             {
                 var start = inputPtr;
-                RespReadUtils.ReadULongWithLengthHeader(out var value, ref start, start + testCase.Bytes.Length);
+                RespReadUtils.TryReadUInt64WithLengthHeader(out var value, ref start, start + testCase.Bytes.Length);
                 return value;
             }
         }

benchmark/Resp.benchmark/ReqGen.cs

@@ -169,12 +169,12 @@ private void ProcessArgs(int i, byte[] buffer)
             fixed (byte* buf = buffer)
             {
                 byte* ptr = buf;
-                RespReadUtils.ReadUnsignedArrayLength(out int count, ref ptr, buf + buffer.Length);
-                RespReadUtils.ReadStringWithLengthHeader(out var cmd, ref ptr, buf + buffer.Length);
+                RespReadUtils.TryReadUnsignedArrayLength(out int count, ref ptr, buf + buffer.Length);
+                RespReadUtils.TryReadStringWithLengthHeader(out var cmd, ref ptr, buf + buffer.Length);
 
                 for (int j = 0; j < count - 1; j++)
                 {
-                    RespReadUtils.ReadStringWithLengthHeader(out var arg, ref ptr, buf + buffer.Length);
+                    RespReadUtils.TryReadStringWithLengthHeader(out var arg, ref ptr, buf + buffer.Length);
                     flatRequestBuffer[i].Add(arg);
                 }
             }