Welcome to little lamb

Code » limb » commit d09a941

cdbmaker.h: Add cdbmaker_sa_{data,dlen}() to get a pointer..

author Olivier Brunel
2023-04-22 11:06:24 UTC
committer Olivier Brunel
2023-05-20 18:06:37 UTC
parent 21eee58eb0ff82a4147d93b96a4894949fe46ef0

cdbmaker.h: Add cdbmaker_sa_{data,dlen}() to get a pointer..

..and the size, respectively, of the generated cdb.

src/doc/cdbmake.h.0.md +14 -7
src/doc/cdbmake.h/cdbmaker_sa_start.3.md +22 -12
src/liblimb/include/limb/cdbmake.h +3 -0

diff --git a/src/doc/cdbmake.h.0.md b/src/doc/cdbmake.h.0.md
index b630e24..a3bd10d 100644
--- a/src/doc/cdbmake.h.0.md
+++ b/src/doc/cdbmake.h.0.md
@@ -26,37 +26,44 @@ The header defines the needed functions to create constant databases, known as
 The following structures are defined :
 
 : *struct cdbmaker_sa*
-:: Semi-opaque structure used during the creating of a cdb in-memory.
+:: An opaque structure to be passed to the functions below.
+
 
 ## Macros
 
 The following macros are defined :
 
 : *CDBMAKER_SA_ZERO*
-:: Can be used to initialized a *cdbmaker_sa* structure.
+:: Value to initialize a *cdbmaker_sa* structure.
 
 ## Types
 
-The followng types are defined :
+The following types are defined :
 
 : *cdbmaker_sa*
-:: Semi-opaque structure used during the creating of a cdb in-memory.
+:: Opaque structure to be passed to the functions below.
 
 ## Functions
 
-The following functions are defined :
+The following functions/macros are defined :
 
 : [cdbmaker_sa_add](3)
 :: Similar to [cdbmake_add](3) but the cdb will be created in-memory.
 
+: [cdbmaker_sa_data](3)
+:: To get a pointer to the in-memory cdb.
+
+: [cdbmaker_sa_dlen](3)
+:: To get the length of the in-memory cdb.
+
 : [cdbmaker_sa_finish](3)
 :: Similar to [cdbmake_finish](3) but the cdb will be created in-memory.
 
 : [cdbmaker_sa_free](3)
-:: To free memory associated with a semi-opaque *cdbmaker_sa* when done.
+:: To free memory associated with an opaque *cdbmaker_sa* when done.
 
 : [cdbmaker_sa_init](3)
-:: To initialize a *cdbmaker_sa* if not initalized through *CDBMAKER_SA_ZERO*.
+:: To initialize a *cdbmaker_sa* if not initialized through *CDBMAKER_SA_ZERO*.
 
 : [cdbmaker_sa_start](3)
 :: Similar to [cdbmake_start](3) but the cdb will be created in-memory.
diff --git a/src/doc/cdbmake.h/cdbmaker_sa_start.3.md b/src/doc/cdbmake.h/cdbmaker_sa_start.3.md
index d9a7077..c2556cf 100644
--- a/src/doc/cdbmake.h/cdbmaker_sa_start.3.md
+++ b/src/doc/cdbmake.h/cdbmaker_sa_start.3.md
@@ -4,7 +4,7 @@
 # NAME
 
 cdbmaker\_sa\_init, cdbmaker\_sa\_start, cdbmaker\_sa\_add, cdbmaker\_sa\_finish,
-cdbmaker\_sa\_free - create a cdb in memory
+cdbmaker\_sa\_data, cdbmaker\_sa\_dlen, cdbmaker\_sa\_free - create a cdb in memory
 
 # SYNOPSIS
 
@@ -17,6 +17,8 @@ void cdbmaker_sa_init(cdbmaker_sa *<em>mkr</em>)
 int cdbmaker_sa_start(cdbmaker_sa *<em>mkr</em>)
 int cdbmaker_sa_add(cdbmaker_sa *<em>mkr</em>, const char *<em>key</em>, u32 <em>klen</em>, const char *<em>data</em>, u32 <em>dlen</em>)
 int cdbmaker_sa_finish(cdbmaker_sa *<em>mkr</em>)
+const char *cdbmaker_sa_data(cdbmaker_sa *<em>mkr</em>)
+size_t cdbmaker_sa_dlen(cdbmaker_sa *<em>mkr</em>)
 void cdbmaker_sa_free(cdbmaker_sa *<em>mkr</em>)
 ```
 
@@ -31,9 +33,9 @@ functions are similar to [cdbmake_start](3), [cdbmake_add](3) and
 [cdbmake_finish](3) respectively, only the resulting cdb will not be written to
 a file but instead be available in memory.
 
-The `cdbmaker_sa_start`() prepares the semi-opaque structure pointed to by
-`mkr` in order to begin creation of a new cdb. Said structure must have
-previously been initialized as mentioned before.
+The `cdbmaker_sa_start`() prepares the opaque structure pointed to by `mkr` in
+order to begin creation of a new cdb. Said structure must have previously been
+initialized as mentioned before.
 
 Note that, after a successful call to `cdbmaker_sa_finish`() it is possible to
 re-use the same *cdbmaker_sa* structure, to create another cdb, by calling
@@ -51,15 +53,15 @@ Finally, the `cdbmaker_sa_finish`() function must be called after all elements
 have been added via `cdbmaker_sa_add`(), in order for the cdb to be actually
 created.
 
-Specifically, the *cdbmaker_sa* structure pointed to by `mkr` has a member `sa`
-which is a *stralloc*, which - after a successful call to
-`cdbmaker_sa_finish`() - will hold the newly-created cdb (i.e. the content of a
-cdb file), available from `mkr->sa.s` for a length of `mkr->sa.len` bytes.
+Then, the `cdbmaker_sa_data`() function will return a pointer to the in-memory
+cdb data, i.e. the /content/ of a cdb file, whose length will be returned by
+the `cdbmaker_sa_dlen`() function.
 
-The `cdbmaker_sa_free`() function will free memory associated with the semi-opaque
-structure pointed to by `mkr`, starting with the generated cdb data. It is not
-needed to use it before calling `cdbmaker_sa_start`() again in order to generate
-a new cdb, thusly re-using the already allocated memory area.
+The returned pointer can be used until the `cdbmaker_sa_free`() function is
+called, which will free memory associated with the opaque structure pointed to
+by `mkr`, starting with the generated cdb data. It is not needed to use it
+before calling `cdbmaker_sa_start`() again in order to generate a new cdb,
+thusly re-using the already allocated memory area.
 
 # RETURN VALUE
 
@@ -67,6 +69,14 @@ The `cdbmaker_sa_start`(), `cdbmaker_sa_add`() and `cdbmaker_sa_finish`()
 functions return 1 on success. Otherwise, they return 0 and set `errno` to
 indicate the error.
 
+The `cdbmaker_sa_data`() function returns a pointer to the generated cdb data.
+
+The `cdbmaker_sa_dlen`() function returns the length (in bytes) of the generated
+cdb data, of which a pointer to can be obtained via `cdbmaker_sa_data`().
+
+It is invalid to call either `cdbmaker_sa_data`() or `cdbmaker_sa_dlen`()
+before a successful call to `cdbmaker_sa_finish`() was made.
+
 # ERRORS
 
 The `cdbmaker_sa_start`(), `cdbmaker_sa_add`() and `cdbmaker_sa_finish`() may
diff --git a/src/liblimb/include/limb/cdbmake.h b/src/liblimb/include/limb/cdbmake.h
index f83c6b4..10d9952 100644
--- a/src/liblimb/include/limb/cdbmake.h
+++ b/src/liblimb/include/limb/cdbmake.h
@@ -18,10 +18,13 @@ typedef struct cdbmaker_sa cdbmaker_sa;
 
 #define CDBMAKER_SA_ZERO        { STRALLOC_ZERO, GENALLOC_ZERO }
 
+
 extern void cdbmaker_sa_init(cdbmaker_sa *m);
 extern int cdbmaker_sa_start(cdbmaker_sa *m);
 extern int cdbmaker_sa_add(cdbmaker_sa *m, const char *key, u32 klen, const char *data, u32 dlen);
 extern int cdbmaker_sa_finish(cdbmaker_sa *m);
+#define cdbmaker_sa_data(ctx)   ((const char *) (ctx)->sa.s)
+#define cdbmaker_sa_dlen(ctx)   (ctx)->sa.len
 extern void cdbmaker_sa_free(cdbmaker_sa *m);
 
 #endif /* LIMB_CDBMAKE_H */