Changeset 99960 in vbox for trunk/include/iprt

Timestamp:

May 24, 2023 9:55:50 PM (23 months ago)

Author:

vboxsync

svn:sync-xref-src-repo-rev:

157620

Message:

IPRT/sg: Corrected RTSgBufIsAtEnd and made the code deal with (skip) empty segments. Added a testcase (incomplete).

File:

• trunk/include/iprt/sg.h (modified) (12 diffs)

trunk/include/iprt/sg.h

@@ -176 +176 @@
 DECLINLINE(bool) RTSgBufIsAtEnd(PCRTSGBUF pSgBuf)
 {
-    return pSgBuf->idxSeg > pSgBuf->cSegs
-        || (   pSgBuf->idxSeg == pSgBuf->cSegs
-            && pSgBuf->cbSegLeft == 0);
+    return pSgBuf->idxSeg >= pSgBuf->cSegs
+        || (   pSgBuf->cbSegLeft == 0  /* sg.cpp doesn't create this situation, but just in case someone does. */
+            && pSgBuf->idxSeg + 1 == pSgBuf->cSegs);
 }
 
@@ -200 +200 @@
  * @param   cSegs     Number of segments in the array.
  *
- * @note paSegs and cSegs can be NULL and 0 respectively to indicate an empty
- *       S/G buffer.  Operations on the S/G buffer will not do anything in this
- *       case.
+ * @note    paSegs and cSegs can be NULL and 0 respectively to indicate an empty
+ *          S/G buffer.  Operations on the S/G buffer will not do anything in
+ *          this case.
  */
 RTDECL(void) RTSgBufInit(PRTSGBUF pSgBuf, PCRTSGSEG paSegs, size_t cSegs);
@@ -215 +215 @@
 /**
  * Clones a given S/G buffer.
- *
+ *  
+ * This is only a shallow copy.  Both S/G buffers will point to the same segment
+ * array. 
+ *  
+ * The buffer position will be preserved.
+ *  
  * @param   pSgBufNew    The new S/G buffer to clone to.
  * @param   pSgBufOld    The source S/G buffer to clone from.
- *
- * @note This is only a shallow copy. Both S/G buffers will point to the
- *       same segment array.
  */
 RTDECL(void) RTSgBufClone(PRTSGBUF pSgBufNew, PCRTSGBUF pSgBufOld);
@@ -257 +259 @@
  *                       is smaller than the amount of bytes requested.
  *
- * @note This operation advances the internal buffer pointer of both S/G buffers.
+ * @note    This operation advances the internal buffer pointer of both S/G buffers.
  */
 RTDECL(void *) RTSgBufGetNextSegment(PRTSGBUF pSgBuf, size_t *pcbSeg);
@@ -269 +271 @@
  * @param   cbCopy       Number of bytes to copy.
  *
- * @note This operation advances the internal buffer pointer of both S/G buffers.
+ * @note    This operation advances the internal buffer pointer of both S/G buffers.
  */
 RTDECL(size_t) RTSgBufCopy(PRTSGBUF pSgBufDst, PRTSGBUF pSgBufSrc, size_t cbCopy);
@@ -281 +283 @@
  * @param   cbCmp        How many bytes to compare.
  *
- * @note This operation doesn't change the internal position of the S/G buffers.
+ * @note    This operation doesn't change the internal position of the S/G buffers.
  */
 RTDECL(int) RTSgBufCmp(PCRTSGBUF pSgBuf1, PCRTSGBUF pSgBuf2, size_t cbCmp);
@@ -306 +308 @@
  *          Can be less than than cbSet if the end of the S/G buffer was reached.
  * @param   pSgBuf       The S/G buffer.
- * @param   ubFill       The byte to fill the buffer with.
- * @param   cbSet        How many bytes to set.
- *
- * @note This operation advances the internal buffer pointer of the S/G buffer.
- */
-RTDECL(size_t) RTSgBufSet(PRTSGBUF pSgBuf, uint8_t ubFill, size_t cbSet);
+ * @param   bFill        The byte to fill the buffer with.
+ * @param   cbToSet      How many bytes to set.
+ *
+ * @note    This operation advances the internal buffer pointer of the S/G buffer.
+ */
+RTDECL(size_t) RTSgBufSet(PRTSGBUF pSgBuf, uint8_t bFill, size_t cbToSet);
 
 /**
@@ -321 +323 @@
  * @param   cbCopy       How many bytes to copy.
  *
- * @note This operation advances the internal buffer pointer of the S/G buffer.
+ * @note    This operation advances the internal buffer pointer of the S/G buffer.
  */
 RTDECL(size_t) RTSgBufCopyToBuf(PRTSGBUF pSgBuf, void *pvBuf, size_t cbCopy);
@@ -333 +335 @@
  * @param   cbCopy       How many bytes to copy.
  *
- * @note This operation advances the internal buffer pointer of the S/G buffer.
+ * @note    This operation advances the internal buffer pointer of the S/G buffer.
  */
 RTDECL(size_t) RTSgBufCopyFromBuf(PRTSGBUF pSgBuf, const void *pvBuf, size_t cbCopy);
@@ -346 +348 @@
  * @param   pvUser       Opaque user data to pass in the given callback.
  *
- * @note This operation advances the internal buffer pointer of the S/G buffer.
+ * @note    This operation advances the internal buffer pointer of the S/G buffer.
  */
 RTDECL(size_t) RTSgBufCopyToFn(PRTSGBUF pSgBuf, size_t cbCopy, PFNRTSGBUFCOPYTO pfnCopyTo, void *pvUser);
@@ -359 +361 @@
  * @param   pvUser       Opaque user data to pass in the given callback.
  *
- * @note This operation advances the internal buffer pointer of the S/G buffer.
+ * @note    This operation advances the internal buffer pointer of the S/G buffer.
  */
 RTDECL(size_t) RTSgBufCopyFromFn(PRTSGBUF pSgBuf, size_t cbCopy, PFNRTSGBUFCOPYFROM pfnCopyFrom, void *pvUser);
@@ -392 +394 @@
  * Returns whether the given S/G buffer is zeroed out from the current position
  * upto the number of bytes to check.
- *
- * @returns true if the buffer has only zeros
- *          false otherwise.
+ * 
+ * @retval  true if the buffer has only zeros
+ * @retval  false otherwise.
  * @param   pSgBuf      The S/G buffer.
- * @param   cbCheck     Number of bytes to check.
+ * @param   cbCheck     Number of bytes to check. 
+ *  
+ * @note    This operation advances the internal buffer pointer of the S/G buffer.
  */
 RTDECL(bool) RTSgBufIsZero(PRTSGBUF pSgBuf, size_t cbCheck);