Mercurial > hg > ucx / changeset

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/Writerside/c.list	Sat Jan 25 13:40:50 2025 +0100
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE categories
+        SYSTEM "https://resources.jetbrains.com/writerside/1.0/categories.dtd">
+<categories>
+    <category id="apidoc" name="Doxygen" order="1"/>
+</categories>
\ No newline at end of file

--- a/docs/Writerside/topics/hash_key.h.md	Fri Jan 24 21:38:40 2025 +0100
+++ b/docs/Writerside/topics/hash_key.h.md	Sat Jan 25 13:40:50 2025 +0100
@@ -3,14 +3,27 @@
 UCX implements the MurmurHash2 algorithm for computing hashes that are primarily used for [CxMap](map.h.md).
 But it can be used for arbitrary custom scenarios, too.
 
-There are four functions which all generate a `CxHashKey` structure for given data.
+## Overview
+```C
+#include <cx/hash_key.h>
+
+void 	  cx_hash_murmur(CxHashKey *key);
+CxHashKey cx_hash_key(const void *obj, size_t len);
+CxHashKey cx_hash_key_str(const char *str);
+CxHashKey cx_hash_key_bytes(const unsigned char *bytes, size_t len);
+CxHashKey cx_hash_key_cxstr(cxstring str);
+``` 
 
-* `cx_hash_key()` takes an arbitrary pointer and a length
-* `cx_hash_key_bytes()` takes an `unsigned char*` and a length
-* `cx_hash_key_str()` takes a usual C string
-* `cx_hash_key_cxstr()` takes a [UCX string](string.h.md)
+## Description
+
+The primary function for creating a `CxHashKey` structure is `cx_hash_key()`.
+The other functions do effectively the same, but
 
-The hash is then available in the `hash` field of the returned structure.
+* `cx_hash_key_bytes()` is strongly typed if you want to avoid passing `void*` 
+* `cx_hash_key_str()` conveniently takes a C string and computes the length on its own
+* `cx_hash_key_cxstr()` conveniently takes a [UCX string](string.h.md)
+
+In all cases, the hash will be available in the `hash` field of the returned structure.
 
 <note>
 UCX assigns the hash value <code>1574210520</code> to the <code>NULL</code> pointer.
@@ -29,3 +42,9 @@
 key.len = strlen(mystring);
 cx_hash_murmur(&key);
 ```
+
+<seealso>
+<category ref="apidoc">
+<a href="https://ucx.sourceforge.io/api/hash__key_8h.html">hash_key.h</a>
+</category>
+</seealso>
\ No newline at end of file

--- a/docs/Writerside/topics/streams.h.md	Fri Jan 24 21:38:40 2025 +0100
+++ b/docs/Writerside/topics/streams.h.md	Sat Jan 25 13:40:50 2025 +0100
@@ -1,13 +1,68 @@
-# Stream Operations
+# Data Streams
+
+Stream copy functions provide a way to copy all - or a  limited amount of - data from one stream to another.
+Since the read/write functions of a [UCX buffer](buffer.h.md) are fully compatible with stream read/write functions,
+you can, for example, easily transfer data from a file or network stream to a UCX buffer or vice versa.
+
+## Overview
+```C
+#include <cx/streams.h>
 
-UCX provides some utilities for routine tasks.
+size_t cx_stream_copy(
+    void *src, void *dest,
+    cx_read_func rfnc, cx_write_func wfnc
+);
+size_t cx_stream_ncopy(
+    void *src, void *dest,
+    cx_read_func rfnc, cx_write_func wfnc,
+    size_t n
+);
+
+size_t cx_stream_bcopy(
+    void *src, void *dest,
+    cx_read_func rfnc, cx_write_func wfnc,
+    char *buf, size_t bufsize
+);
+size_t cx_stream_bncopy(
+    void *src, void *dest,
+    cx_read_func rfnc, cx_write_func wfnc,
+    char *buf, size_t bufsize,
+    size_t n
+);
+``` 
 
-The most useful utilities are the *stream copy* functions, which provide a simple way to copy all - or a
-bounded amount of - data from one stream to another. Since the read/write functions of a UCX buffer are
-fully compatible with stream read/write functions, you can easily transfer data from file or network streams to
-a UCX buffer or vice-versa.
+## Description
+
+All functions in the stream copy family use the `rfnc` to read data from `src`
+and use the `wfnc` to write the data to `dest`.
+
+The `cx_stream_copy()` function always uses internal stack memory as a temporary buffer for the read bytes.
+The `cx_stream_bcopy()` function uses either a pre-initialized buffer `buf` of length `bufsize`
+or, if `buf` is `NULL`, an internal heap-allocated buffer.
+
+The `cx_stream_ncopy()` function behaves like `cx_stream_copy()` except, that it reads at most `n` bytes
+(and the same is true for `cx_stream_bncopy()` and `cx_stream_bcopy()`).
+
 
-The following example shows, how easy it is to read the contents of a file into a buffer:
+<warning>
+When you are reading from a stream where you cannot track the position, there is the possibility that
+data gets lost when the destination does not accept all the bytes read from the source.
+While the stream copy functions do report how many bytes were <emphasis>successfully</emphasis> copied
+to the destination, this might - in certain cases - not be the exact number of read items.
+
+To mitigate the risk, you should make sure that the destination can always accept all read bytes and
+a possible bottleneck is only introduced by the source.
+</warning>
+
+> The size of the internal _stack_ buffer in `cx_stream_copy()` and `cx_stream_ncopy()` can be
+> set during compilation via the `CX_STREAM_COPY_BUF_SIZE` macro.
+> Similarly, the size for the implicitly allocated _heap_ buffer in can be
+> configured via the `CX_STREAM_BCOPY_BUF_SIZE` macro.
+> Refer to the [build instructions](install.md#compile-time-options) for the details.
+
+## Example
+
+The following example shows, how to read the contents of a file into a buffer:
 ```c
 FILE *inputfile = fopen(infilename, "r");
 if (inputfile) {
@@ -29,6 +84,9 @@
 }
 ```
 
-## Undocumented Symbols (TODO)
-### cx_stream_bncopy
-### cx_stream_ncopy
+
+<seealso>
+<category ref="apidoc">
+<a href="https://ucx.sourceforge.io/api/streams_8h.html">streams.h</a>
+</category>
+</seealso>
\ No newline at end of file

--- a/docs/Writerside/writerside.cfg	Fri Jan 24 21:38:40 2025 +0100
+++ b/docs/Writerside/writerside.cfg	Sat Jan 25 13:40:50 2025 +0100
@@ -3,6 +3,7 @@
 
 <ihp version="2.0">
     <topics dir="topics" web-path="topics"/>
+    <categories src="c.list"/>
     <images dir="images" web-path="images"/>
     <instance src="ucx.tree" version="3.1"/>
 </ihp>
\ No newline at end of file