deploy: 51be4bd

d8/d01/roaring64_8h.html

@@ -1623,9 +1623,12 @@ <h2 class="memtitle"><span class="permalink"><a href="#a992ab22db8e0c45d465fccc4
         </tr>
       </table>
 </div><div class="memdoc">
-<p>Read a bitmap from a serialized buffer safely (reading up to maxbytes). In case of failure, NULL is returned.</p>
+<p>Read a bitmap from a serialized buffer (reading up to maxbytes). In case of failure, NULL is returned.</p>
 <p>This is meant to be compatible with other languages <a href="https://github.com/RoaringBitmap/RoaringFormatSpec#extension-for-64-bit-implementations">https://github.com/RoaringBitmap/RoaringFormatSpec#extension-for-64-bit-implementations</a></p>
-<p>The function itself is safe in the sense that it will not cause buffer overflows. However, for correct operations, it is assumed that the bitmap read was once serialized from a valid bitmap (i.e., it follows the format specification). If you provided an incorrect input (garbage), then the bitmap read may not be in a valid state and following operations may not lead to sensible results. In particular, the serialized array containers need to be in sorted order, and the run containers should be in sorted non-overlapping order. This is is guaranteed to happen when serializing an existing bitmap, but not for random inputs.</p>
+<p>The function itself is safe in the sense that it will not cause buffer overflows: it will not read beyond the scope of the provided buffer (buf,maxbytes).</p>
+<p>However, for correct operations, it is assumed that the bitmap read was once serialized from a valid bitmap (i.e., it follows the format specification). If you provided an incorrect input (garbage), then the bitmap read may not be in a valid state and following operations may not lead to sensible results. In particular, the serialized array containers need to be in sorted order, and the run containers should be in sorted non-overlapping order. This is is guaranteed to happen when serializing an existing bitmap, but not for random inputs.</p>
+<p>You may use roaring64_bitmap_internal_validate to check the validity of the bitmap prior to using it.</p>
+<p>We recommend that you use checksums to check that serialized data corresponds to a serialized bitmap.</p>
 <p>This function is endian-sensitive. If you have a big-endian system (e.g., a mainframe IBM s390x), the data format is going to be big-endian and not compatible with little-endian systems. </p>
 
 </div>
@@ -1688,7 +1691,8 @@ <h2 class="memtitle"><span class="permalink"><a href="#a984d439666b29ff9474f89d7
 <p>Write a bitmap to a buffer. The output buffer should refer to at least <code>roaring64_bitmap_portable_size_in_bytes(r)</code> bytes of allocated memory.</p>
 <p>Returns how many bytes were written, which should match <code>roaring64_bitmap_portable_size_in_bytes(r)</code>.</p>
 <p>This is meant to be compatible with other languages: <a href="https://github.com/RoaringBitmap/RoaringFormatSpec#extension-for-64-bit-implementations">https://github.com/RoaringBitmap/RoaringFormatSpec#extension-for-64-bit-implementations</a></p>
-<p>This function is endian-sensitive. If you have a big-endian system (e.g., a mainframe IBM s390x), the data format is going to be big-endian and not compatible with little-endian systems. </p>
+<p>This function is endian-sensitive. If you have a big-endian system (e.g., a mainframe IBM s390x), the data format is going to be big-endian and not compatible with little-endian systems.</p>
+<p>When serializing data to a file, we recommend that you also use checksums so that, at deserialization, you can be confident that you are recovering the correct data. </p>
 
 </div>
 </div>