update README.md, add document comments

itn3000 · itn3000 · commit 0c5665496047 · 2022-02-10T13:54:40.000+09:00
diff --git a/PooledStream.sln b/PooledStream.sln
@@ -1,13 +1,18 @@
-Microsoft Visual Studio Solution File, Format Version 12.0
-# Visual Studio Version 16
-VisualStudioVersion = 16.0
+Microsoft Visual Studio Solution File, Format Version 12.00
+# Visual Studio Version 17
+VisualStudioVersion = 17.0.32002.185
 MinimumVisualStudioVersion = 10.0.40219.1
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "PooledStream.Benchmark", "PooledStream.Benchmark\PooledStream.Benchmark.csproj", "{41130469-5601-4C78-87DC-14574AD1EB0F}"
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "PooledStream.Test", "PooledStream.Test\PooledStream.Test.csproj", "{DA3F4EB2-D0F8-49C3-8A34-C86412EFC151}"
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "PooledStream", "PooledStream\PooledStream.csproj", "{3C446344-2FF5-45F9-9010-3227F715B8A9}"
 EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{180A5C83-F82B-40F0-BCAF-F240679667EC}"
+	ProjectSection(SolutionItems) = preProject
+		README.md = README.md
+	EndProjectSection
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|AnyCPU = Debug|AnyCPU
@@ -27,4 +32,10 @@ Global
 		{3C446344-2FF5-45F9-9010-3227F715B8A9}.Release|AnyCPU.ActiveCfg = Debug|Any CPU
 		{3C446344-2FF5-45F9-9010-3227F715B8A9}.Release|AnyCPU.Build.0 = Debug|Any CPU
 	EndGlobalSection
+	GlobalSection(SolutionProperties) = preSolution
+		HideSolutionNode = FALSE
+	EndGlobalSection
+	GlobalSection(ExtensibilityGlobals) = postSolution
+		SolutionGuid = {F11B0785-81AF-4F25-9079-8A1432151A79}
+	EndGlobalSection
 EndGlobal
diff --git a/PooledStream/PooledBufferWriter.cs b/PooledStream/PooledBufferWriter.cs
@@ -22,31 +22,55 @@ void Reallocate(int sizeHint)
             }
             _currentBuffer = nar;
         }
+        /// <summary>
+        /// use shared instance and preallocatedSize = 1024
+        /// </summary>
         public PooledMemoryBufferWriter() : this(ArrayPool<T>.Shared)
         {
 
         }
+        /// <summary>
+        /// use shared instance, use preallocateSize as reserved buffer length
+        /// </summary>
+        /// <param name="preallocateSize">initial reserved buffer size</param>
         public PooledMemoryBufferWriter(int preallocateSize) : this(ArrayPool<T>.Shared, preallocateSize)
         {
 
         }
+        /// <summary>
+        /// use pool for memory pool
+        /// </summary>
+        /// <param name="pool">memory pool</param>
         public PooledMemoryBufferWriter(ArrayPool<T> pool) : this(pool, DefaultSize)
         {
         }
+        /// <summary>
+        /// </summary>
+        /// <param name="pool">memory pool</param>
+        /// <param name="preallocateSize">initial reserved buffer size</param>
         public PooledMemoryBufferWriter(ArrayPool<T> pool, int preallocateSize)
         {
+            if(pool == null)
+            {
+                throw new ArgumentNullException(nameof(pool));
+            }
+            if(preallocateSize < 0)
+            {
+                throw new ArgumentOutOfRangeException(nameof(preallocateSize), "size must be greater than 0");
+            }
             _Pool = pool;
             _currentBuffer = null;
             _Position = 0;
             _Length = 0;
             Reallocate(preallocateSize);
         }
+        /// <inheritdoc/>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public void Advance(int count)
         {
             if (_Position + count > _currentBuffer.Length)
             {
-                throw new IndexOutOfRangeException("advance too many(" + count.ToString() + ")");
+                throw new ArgumentOutOfRangeException("advance too many(" + count.ToString() + ")");
             }
             _Position += count;
             if (_Length < _Position)
@@ -55,6 +79,7 @@ public void Advance(int count)
             }
         }
 
+        /// <summary>return buffer to pool and reset buffer status</summary>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public void Dispose()
         {
@@ -67,9 +92,14 @@ public void Dispose()
             }
         }
 
+        /// <inheritdoc/>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public Memory<T> GetMemory(int sizeHint = 0)
         {
+            if (sizeHint < 0)
+            {
+                throw new ArgumentOutOfRangeException("sizeHint", "size must be greater than 0");
+            }
             if (sizeHint == 0)
             {
                 sizeHint = DefaultSize;
@@ -80,10 +110,14 @@ public Memory<T> GetMemory(int sizeHint = 0)
             }
             return _currentBuffer.AsMemory(_Position, sizeHint);
         }
-
+        /// <inheritdoc/>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public Span<T> GetSpan(int sizeHint = 0)
         {
+            if (sizeHint < 0)
+            {
+                throw new ArgumentOutOfRangeException("sizeHint", "size must be greater than 0");
+            }
             if (sizeHint == 0)
             {
                 sizeHint = DefaultSize;
@@ -94,23 +128,37 @@ public Span<T> GetSpan(int sizeHint = 0)
             }
             return _currentBuffer.AsSpan(_Position, sizeHint);
         }
+        /// <summary>expose current buffer as Span</summary>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public ReadOnlySpan<T> ToSpanUnsafe()
         {
             return _currentBuffer.AsSpan(0, _Length);
         }
+        /// <summary>expose current buffer as Memory</summary>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public ReadOnlyMemory<T> ToMemoryUnsafe()
         {
             return _currentBuffer.AsMemory(0, _Length);
         }
+        /// <summary>reset buffer status, buffer will be reallocated</summary>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void Reset(int preallocateSize = DefaultSize)
+        public void Reset(int preallocateSize)
         {
+            if(preallocateSize < 0)
+            {
+                throw new ArgumentOutOfRangeException("preallocateSize", "size must be greater than 0");
+            }
             _Pool.Return(_currentBuffer);
             _currentBuffer = _Pool.Rent(preallocateSize);
             _Length = 0;
             _Position = 0;
         }
+        /// <summary>reset buffer status, buffer will be reused</summary>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public void Reset()
+        {
+            _Length = 0;
+            _Position = 0;
+        }
     }
 }
diff --git a/PooledStream/PooledStream.csproj b/PooledStream/PooledStream.csproj
@@ -4,13 +4,13 @@
     <TargetFrameworks>netstandard2.1;netstandard1.1</TargetFrameworks>
     <!-- <TargetFramework>netstandard2.1</TargetFramework> -->
     <PackageId>PooledStream</PackageId>
-    <PackageVersion>0.2.1.2</PackageVersion>
+    <PackageVersion>0.3.0</PackageVersion>
     <Authors>itn3000</Authors>
     <Description>Efficient MemoryStream powered by System.Buffers.ArrayPool</Description>
     <PackageRequireLicenseAcceptance>false</PackageRequireLicenseAcceptance>
-    <PackageReleaseNotes>add netstandard2.1 to TargetFramework</PackageReleaseNotes>
+    <PackageReleaseNotes>add PooledMemoryBufferWriter</PackageReleaseNotes>
     <Copyright>Copyright(c) 2017 itn3000. All rights reserved</Copyright>
-    <PackageTags>MemoryStream</PackageTags>
+    <PackageTags>MemoryStream;ArrayPool</PackageTags>
     <PackageProjectUrl>https://github.com/itn3000/PooledStream/</PackageProjectUrl>
     <RepositoryUrl>https://github.com/itn3000/PooledStream/</RepositoryUrl>
     <PackageLicenseFile>LICENSE.md</PackageLicenseFile>
diff --git a/README.md b/README.md

Original file line number	Diff line number	Diff line change
`@@ -22,31 +22,55 @@ void Reallocate(int sizeHint)`
`22`	`22`	`}`
`23`	`23`	`_currentBuffer = nar;`
`24`	`24`	`}`
	`25`	`+ /// <summary>`
	`26`	`+ /// use shared instance and preallocatedSize = 1024`
	`27`	`+ /// </summary>`
`25`	`28`	`public PooledMemoryBufferWriter() : this(ArrayPool<T>.Shared)`
`26`	`29`	`{`
`27`	`30`
`28`	`31`	`}`
	`32`	`+ /// <summary>`
	`33`	`+ /// use shared instance, use preallocateSize as reserved buffer length`
	`34`	`+ /// </summary>`
	`35`	`+ /// <param name="preallocateSize">initial reserved buffer size</param>`
`29`	`36`	`public PooledMemoryBufferWriter(int preallocateSize) : this(ArrayPool<T>.Shared, preallocateSize)`
`30`	`37`	`{`
`31`	`38`
`32`	`39`	`}`
	`40`	`+ /// <summary>`
	`41`	`+ /// use pool for memory pool`
	`42`	`+ /// </summary>`
	`43`	`+ /// <param name="pool">memory pool</param>`
`33`	`44`	`public PooledMemoryBufferWriter(ArrayPool<T> pool) : this(pool, DefaultSize)`
`34`	`45`	`{`
`35`	`46`	`}`
	`47`	`+ /// <summary>`
	`48`	`+ /// </summary>`
	`49`	`+ /// <param name="pool">memory pool</param>`
	`50`	`+ /// <param name="preallocateSize">initial reserved buffer size</param>`
`36`	`51`	`public PooledMemoryBufferWriter(ArrayPool<T> pool, int preallocateSize)`
`37`	`52`	`{`
	`53`	`+ if(pool == null)`
	`54`	`+ {`
	`55`	`+ throw new ArgumentNullException(nameof(pool));`
	`56`	`+ }`
	`57`	`+ if(preallocateSize < 0)`
	`58`	`+ {`
	`59`	`+ throw new ArgumentOutOfRangeException(nameof(preallocateSize), "size must be greater than 0");`
	`60`	`+ }`
`38`	`61`	`_Pool = pool;`
`39`	`62`	`_currentBuffer = null;`
`40`	`63`	`_Position = 0;`
`41`	`64`	`_Length = 0;`
`42`	`65`	`Reallocate(preallocateSize);`
`43`	`66`	`}`
	`67`	`+ /// <inheritdoc/>`
`44`	`68`	`[MethodImpl(MethodImplOptions.AggressiveInlining)]`
`45`	`69`	`public void Advance(int count)`
`46`	`70`	`{`
`47`	`71`	`if (_Position + count > _currentBuffer.Length)`
`48`	`72`	`{`
`49`		`- throw new IndexOutOfRangeException("advance too many(" + count.ToString() + ")");`
	`73`	`+ throw new ArgumentOutOfRangeException("advance too many(" + count.ToString() + ")");`
`50`	`74`	`}`
`51`	`75`	`_Position += count;`
`52`	`76`	`if (_Length < _Position)`
`@@ -55,6 +79,7 @@ public void Advance(int count)`
`55`	`79`	`}`
`56`	`80`	`}`
`57`	`81`
	`82`	`+ /// <summary>return buffer to pool and reset buffer status</summary>`
`58`	`83`	`[MethodImpl(MethodImplOptions.AggressiveInlining)]`
`59`	`84`	`public void Dispose()`
`60`	`85`	`{`
`@@ -67,9 +92,14 @@ public void Dispose()`
`67`	`92`	`}`
`68`	`93`	`}`
`69`	`94`
	`95`	`+ /// <inheritdoc/>`
`70`	`96`	`[MethodImpl(MethodImplOptions.AggressiveInlining)]`
`71`	`97`	`public Memory<T> GetMemory(int sizeHint = 0)`
`72`	`98`	`{`
	`99`	`+ if (sizeHint < 0)`
	`100`	`+ {`
	`101`	`+ throw new ArgumentOutOfRangeException("sizeHint", "size must be greater than 0");`
	`102`	`+ }`
`73`	`103`	`if (sizeHint == 0)`
`74`	`104`	`{`
`75`	`105`	`sizeHint = DefaultSize;`
`@@ -80,10 +110,14 @@ public Memory<T> GetMemory(int sizeHint = 0)`
`80`	`110`	`}`
`81`	`111`	`return _currentBuffer.AsMemory(_Position, sizeHint);`
`82`	`112`	`}`
`83`		`-`
	`113`	`+ /// <inheritdoc/>`
`84`	`114`	`[MethodImpl(MethodImplOptions.AggressiveInlining)]`
`85`	`115`	`public Span<T> GetSpan(int sizeHint = 0)`
`86`	`116`	`{`
	`117`	`+ if (sizeHint < 0)`
	`118`	`+ {`
	`119`	`+ throw new ArgumentOutOfRangeException("sizeHint", "size must be greater than 0");`
	`120`	`+ }`
`87`	`121`	`if (sizeHint == 0)`
`88`	`122`	`{`
`89`	`123`	`sizeHint = DefaultSize;`
`@@ -94,23 +128,37 @@ public Span<T> GetSpan(int sizeHint = 0)`
`94`	`128`	`}`
`95`	`129`	`return _currentBuffer.AsSpan(_Position, sizeHint);`
`96`	`130`	`}`
	`131`	`+ /// <summary>expose current buffer as Span</summary>`
`97`	`132`	`[MethodImpl(MethodImplOptions.AggressiveInlining)]`
`98`	`133`	`public ReadOnlySpan<T> ToSpanUnsafe()`
`99`	`134`	`{`
`100`	`135`	`return _currentBuffer.AsSpan(0, _Length);`
`101`	`136`	`}`
	`137`	`+ /// <summary>expose current buffer as Memory</summary>`
`102`	`138`	`[MethodImpl(MethodImplOptions.AggressiveInlining)]`
`103`	`139`	`public ReadOnlyMemory<T> ToMemoryUnsafe()`
`104`	`140`	`{`
`105`	`141`	`return _currentBuffer.AsMemory(0, _Length);`
`106`	`142`	`}`
	`143`	`+ /// <summary>reset buffer status, buffer will be reallocated</summary>`
`107`	`144`	`[MethodImpl(MethodImplOptions.AggressiveInlining)]`
`108`		`- public void Reset(int preallocateSize = DefaultSize)`
	`145`	`+ public void Reset(int preallocateSize)`
`109`	`146`	`{`
	`147`	`+ if(preallocateSize < 0)`
	`148`	`+ {`
	`149`	`+ throw new ArgumentOutOfRangeException("preallocateSize", "size must be greater than 0");`
	`150`	`+ }`
`110`	`151`	`_Pool.Return(_currentBuffer);`
`111`	`152`	`_currentBuffer = _Pool.Rent(preallocateSize);`
`112`	`153`	`_Length = 0;`
`113`	`154`	`_Position = 0;`
`114`	`155`	`}`
	`156`	`+ /// <summary>reset buffer status, buffer will be reused</summary>`
	`157`	`+ [MethodImpl(MethodImplOptions.AggressiveInlining)]`
	`158`	`+ public void Reset()`
	`159`	`+ {`
	`160`	`+ _Length = 0;`
	`161`	`+ _Position = 0;`
	`162`	`+ }`
`115`	`163`	`}`
`116`	`164`	`}`