forked from Telodendria/Telodendria
Convert list of man pages to a table.
This commit is contained in:
parent
744f38784c
commit
0b849bd0c1
3 changed files with 207 additions and 22 deletions
3
TODO.txt
3
TODO.txt
|
@ -101,6 +101,7 @@ Documentation
|
||||||
[x] Clean up dark mode in man page CSS (links)
|
[x] Clean up dark mode in man page CSS (links)
|
||||||
[x] Synopsis table should not be styled
|
[x] Synopsis table should not be styled
|
||||||
[x] Make available on MANPATH in tools/env.sh
|
[x] Make available on MANPATH in tools/env.sh
|
||||||
|
[x] Convert list of man pages into a table on home page
|
||||||
[~] Internal API docs
|
[~] Internal API docs
|
||||||
[x] Array
|
[x] Array
|
||||||
[x] Base64
|
[x] Base64
|
||||||
|
@ -109,7 +110,7 @@ Documentation
|
||||||
[ ] API (Config.3)
|
[ ] API (Config.3)
|
||||||
[ ] File format (Config.5)
|
[ ] File format (Config.5)
|
||||||
[ ] Constants
|
[ ] Constants
|
||||||
[ ] HashMap
|
[x] HashMap
|
||||||
[ ] Http
|
[ ] Http
|
||||||
[ ] HttpServer
|
[ ] HttpServer
|
||||||
[ ] Json
|
[ ] Json
|
||||||
|
|
136
man/man3/HashMap.3
Normal file
136
man/man3/HashMap.3
Normal file
|
@ -0,0 +1,136 @@
|
||||||
|
.Dd $Mdocdate: October 10 2022 $
|
||||||
|
.Dt HASHMAP 3
|
||||||
|
.Os Telodendria Project
|
||||||
|
.Sh NAME
|
||||||
|
.Nm HashMap
|
||||||
|
.Nd A simple hash map implementation.
|
||||||
|
.Sh SYNOPSIS
|
||||||
|
.In HashMap.h
|
||||||
|
.Ft HashMap *
|
||||||
|
.Fn HashMapCreate "void"
|
||||||
|
.Ft void
|
||||||
|
.Fn HashMapFree "HashMap *"
|
||||||
|
.Ft void
|
||||||
|
.Fn HashMapLoadSet "HashMap *" "float"
|
||||||
|
.Ft void *
|
||||||
|
.Fn HashMapSet "HashMap *" "char *" "void *"
|
||||||
|
.Ft void *
|
||||||
|
.Fn HashMapGet "HashMap *" "char *"
|
||||||
|
.Ft void *
|
||||||
|
.Fn HashMapDelete "HashMap *" "char *"
|
||||||
|
.Ft int
|
||||||
|
.Fn HashMapIterate "HashMap *" "char **" "void **"
|
||||||
|
.Sh DESCRIPTION
|
||||||
|
This is the public interface for Telodendria's hash map implementation.
|
||||||
|
This hash map is designed to be simple, well documented, and generally
|
||||||
|
readable and understandable, yet also performant enough to be useful,
|
||||||
|
because it is used extensively in Telodendria.
|
||||||
|
.Pp
|
||||||
|
Fundamentally, this is an entirely generic map implementation. It can
|
||||||
|
be used for many general purposes, but it is designed to only implement
|
||||||
|
the features that Telodendria needs to function well. One example of a
|
||||||
|
Telodendria-specific feature is that keys are
|
||||||
|
.Dv NULL -terminated
|
||||||
|
strings, not any arbitrary data.
|
||||||
|
.Pp
|
||||||
|
These functions operate on an opaque
|
||||||
|
.Dv HashMap
|
||||||
|
structure, which the caller has no knowledge about.
|
||||||
|
.Pp
|
||||||
|
.Fn HashMapCreate
|
||||||
|
creates a new hash map that is ready to be used with the rest of the
|
||||||
|
hash map functions.
|
||||||
|
.Fn HashMapFree
|
||||||
|
frees this hash map, such that it becomes invalid and any future use
|
||||||
|
with the functions in this API results in undefined behavior. Note that
|
||||||
|
it does not free the keys or values stored in the hash map, since this
|
||||||
|
implementation has no way of knowing what is actually stored in it, and
|
||||||
|
where it is located. You should use
|
||||||
|
.Fn HashMapIterate
|
||||||
|
to free the values appropriately.
|
||||||
|
.Pp
|
||||||
|
.Fn HashMapMaxLoadSet
|
||||||
|
controls the maximum load of the hash map before it is expanded.
|
||||||
|
When the hash map reaches the given capacity, it is grown. You don't
|
||||||
|
want to only grow hash maps when they are full, because that makes
|
||||||
|
them perform very poorly. The maximum load value is a percentage of how
|
||||||
|
full the hash map is, and it should be between 0
|
||||||
|
and 1, where 0 means that no elements will cause the map to be expanded,
|
||||||
|
and 1 means that the hash map must be completely full before it is
|
||||||
|
expanded. The default maximum load on a new
|
||||||
|
.Dv HashMap
|
||||||
|
object is 0.75, which should be good enough for most purposes, but
|
||||||
|
if you need finer tuning, feel free to play with the max load with
|
||||||
|
this function. The changes take effect on the next insert.
|
||||||
|
.Pp
|
||||||
|
.Fn HashMapSet
|
||||||
|
sets the given string key to the given value. Note neither the key nor the
|
||||||
|
value is copied into the hash map's own memory space; only pointers are
|
||||||
|
stored. It is the caller's job to ensure that the key and value memory
|
||||||
|
remains valid for the life of the HashMap, and are freed when they are no
|
||||||
|
longer needed.
|
||||||
|
.Fn HashMapGet
|
||||||
|
retrieves the value for the given key and .Fn HashMapDelete
|
||||||
|
removes a value from a given key.
|
||||||
|
.Pp
|
||||||
|
.Fn HashMapIterate
|
||||||
|
iterates over all the keys and values of a hash map. This function works
|
||||||
|
very similarly to
|
||||||
|
.Xr getopt 3 ,
|
||||||
|
where calls are repeatedly made in a
|
||||||
|
.Dv while
|
||||||
|
loop until there are no more items to go over. The difference is that this
|
||||||
|
function does not rely on globals; it takes pointer pointers, and stores all
|
||||||
|
necessary state inside the hash map structure itself. Note that this does not
|
||||||
|
make this function thread-safe; two threads cannot be iterating over any given
|
||||||
|
hash map at the same time, though they can be iterating over different hash
|
||||||
|
maps at the same time.
|
||||||
|
.Pp
|
||||||
|
This function can be tricky to use in some scenarios, as it continues where
|
||||||
|
it left off on each call, until there are no more elements to go through in
|
||||||
|
the hash map. If you are not iterating over the entire map in one go, and
|
||||||
|
happen to break the loop, then the next time you attempt to iterate the
|
||||||
|
hash map, you'll start somewhere in the middle. Thus, it's recommended to
|
||||||
|
always iterate over the entire hash map if you're going to use this
|
||||||
|
function. Also note that the behavior of this function is undefined if
|
||||||
|
insertions or deletions occur during the iteration. It may work fine; it may
|
||||||
|
not. That functionality has not been tested.
|
||||||
|
.Pp
|
||||||
|
.Fn HashMapIterate
|
||||||
|
takes a pointer to a string ponter, and a pointer to a value pointer. When
|
||||||
|
iterating over the keys and values of the hash map, it sets these pointers
|
||||||
|
to the current position in the map so that the caller can use them for his
|
||||||
|
own purposes.
|
||||||
|
.Sh RETURN VALUES
|
||||||
|
.Fn HashMapCreate
|
||||||
|
may return
|
||||||
|
.Dv NULL
|
||||||
|
if memory could not be allocated on the heap. Otherwise, it returns a
|
||||||
|
valid pointer to a
|
||||||
|
.Dv HashMap
|
||||||
|
structure which can be used with the other functions in this API.
|
||||||
|
.Pp
|
||||||
|
.Fn HashMapSet
|
||||||
|
returns the previous value at the passed key, or
|
||||||
|
.Dv NULL
|
||||||
|
if no such value exists. All keys must have values; you can't set a key
|
||||||
|
to
|
||||||
|
.Dv NULL .
|
||||||
|
To delete a key, use the
|
||||||
|
.Fn HashMapDelete
|
||||||
|
function.
|
||||||
|
.Pp
|
||||||
|
.Fn HashMapDelete
|
||||||
|
returns the value that was deleted from the hash map at the given key,
|
||||||
|
or
|
||||||
|
.Dv NULL
|
||||||
|
if no such value exists.
|
||||||
|
.Pp
|
||||||
|
.Fn HashMapIterate
|
||||||
|
returns 1 if there are still elements left in the current iteration of the
|
||||||
|
hash map, or 0 if no valid hash map was provided, or there are no more elements
|
||||||
|
in it for the current iteration. Note that as soon as this function returns 0
|
||||||
|
on a hash map, subsequent iterations will start from the beginning.
|
||||||
|
.Sh SEE ALSO
|
||||||
|
.Xr HashMap 3 ,
|
||||||
|
.Xr Queue 3
|
|
@ -44,27 +44,75 @@ on what <b>Telodendria</b> is, what its goals are, how to build the source,
|
||||||
configure it, as well as contribute to the project. The <code>man</code>
|
configure it, as well as contribute to the project. The <code>man</code>
|
||||||
pages are also available online for convenience:
|
pages are also available online for convenience:
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>User Documentation:</p>
|
||||||
User documentation:
|
<table>
|
||||||
</p>
|
<tr>
|
||||||
<ul>
|
<th>Man Page</th>
|
||||||
<li><a href="/man/man7/telodendria.7.html">telodendria(7)</a> - <b>Start here.</b>
|
<th>Description</th>
|
||||||
Introduction and project information, including project status, contact information, and
|
</tr>
|
||||||
licensing.</li>
|
<tr>
|
||||||
<li><a href="/man/man8/telodendria.8.html">telodendria(8)</a> - Command line usage</li>
|
<td><a href="man/man7/telodendria.7.html">telodendria(7)</a></td>
|
||||||
<li><a href="/man/man5/telodendria.conf.5.html">telodendria.conf(5)</a> - Configuration file</li>
|
<td>
|
||||||
<li><a href="/man/man7/contributing.7.html">contributing(7)</a> - Contributing guide</li>
|
<b>Start here.</b> This page contains the project introduction, and provides
|
||||||
<li><a href="/man/man8/td.8.html">td(8)</a> - Build script and patch instructions</li>
|
information about it, such as its status, how to contact the developers, and what
|
||||||
</ul>
|
the source code license is.
|
||||||
<p>
|
</td>
|
||||||
Developer documentation:
|
<tr>
|
||||||
</p>
|
<td><a href="man/man8/telodendria.8.html">telodendria(8)</a><td>
|
||||||
<ul>
|
<td>
|
||||||
<li><a href="/man/man3/Array.3.html">Array(3)</a> - Dynamic array structure</li>
|
Command line usage for <b>Telodendria</b> administrators.
|
||||||
<li><a href="/man/man3/Base64.3.html">Base64(3)</a> - Base64 encoder/decoder with unpadded support</li>
|
</td>
|
||||||
<li><a href="/man/man3/HashMap.3.html">HashMap(3)</a> - A simple hash map implementation</li>
|
</tr>
|
||||||
<li><a href="/man/man3/Queue.3.html">Queue(3)</a> - Basic circular queue implementation</li>
|
<tr>
|
||||||
</ul>
|
<td><a href="man/man5/telodendria.conf.5.html">telodendria.conf(5)</a></td>
|
||||||
|
<td>
|
||||||
|
Configuration file options.
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><a href="man/man7/contributing.7.html">contributing(7)</a></td>
|
||||||
|
<td>
|
||||||
|
Contributing guide.
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
<p>Developer Documentation:</p>
|
||||||
|
<table>
|
||||||
|
<tr>
|
||||||
|
<th>Man Page</th>
|
||||||
|
<th>Description</th>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><a href="man/man8/td.8.html">td(8)</a></td>
|
||||||
|
<td>
|
||||||
|
Build script and patch generation instructions.
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><a href="man/man3/Array.3.html">Array(3)</a></td>
|
||||||
|
<td>
|
||||||
|
Dynamically-sized array API.
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><a href="man/man3/Base64.3.html">Base64(3)</a></td>
|
||||||
|
<td>
|
||||||
|
Base64 implementation with Matrix's "unpadded base64" support.
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><a href="man/man3/HashMap.3.html">HashMap(3)</a></td>
|
||||||
|
<td>
|
||||||
|
A simple hash map implementation.
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><a href="man/man3/Queue.3.html">Queue(3)</a></td>
|
||||||
|
<td>
|
||||||
|
Basic fixed-size circular queue implementation.
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
<h2 id="download">Download</h2>
|
<h2 id="download">Download</h2>
|
||||||
<p>
|
<p>
|
||||||
<b>Telodendria</b> is distributed as source tarballs, in true Unix
|
<b>Telodendria</b> is distributed as source tarballs, in true Unix
|
||||||
|
|
Loading…
Reference in a new issue