forked from Telodendria/Telodendria
Convert list of man pages to a table.
This commit is contained in:
parent
744f38784c
commit
0b849bd0c1
3
TODO.txt
3
TODO.txt
|
|
@ -101,6 +101,7 @@ Documentation
|
|||
[x] Clean up dark mode in man page CSS (links)
|
||||
[x] Synopsis table should not be styled
|
||||
[x] Make available on MANPATH in tools/env.sh
|
||||
[x] Convert list of man pages into a table on home page
|
||||
[~] Internal API docs
|
||||
[x] Array
|
||||
[x] Base64
|
||||
|
|
@ -109,7 +110,7 @@ Documentation
|
|||
[ ] API (Config.3)
|
||||
[ ] File format (Config.5)
|
||||
[ ] Constants
|
||||
[ ] HashMap
|
||||
[x] HashMap
|
||||
[ ] Http
|
||||
[ ] HttpServer
|
||||
[ ] Json
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
pages are also available online for convenience:
|
||||
</p>
|
||||
<p>
|
||||
User documentation:
|
||||
</p>
|
||||
<ul>
|
||||
<li><a href="/man/man7/telodendria.7.html">telodendria(7)</a> - <b>Start here.</b>
|
||||
Introduction and project information, including project status, contact information, and
|
||||
licensing.</li>
|
||||
<li><a href="/man/man8/telodendria.8.html">telodendria(8)</a> - Command line usage</li>
|
||||
<li><a href="/man/man5/telodendria.conf.5.html">telodendria.conf(5)</a> - Configuration file</li>
|
||||
<li><a href="/man/man7/contributing.7.html">contributing(7)</a> - Contributing guide</li>
|
||||
<li><a href="/man/man8/td.8.html">td(8)</a> - Build script and patch instructions</li>
|
||||
</ul>
|
||||
<p>
|
||||
Developer documentation:
|
||||
</p>
|
||||
<ul>
|
||||
<li><a href="/man/man3/Array.3.html">Array(3)</a> - Dynamic array structure</li>
|
||||
<li><a href="/man/man3/Base64.3.html">Base64(3)</a> - Base64 encoder/decoder with unpadded support</li>
|
||||
<li><a href="/man/man3/HashMap.3.html">HashMap(3)</a> - A simple hash map implementation</li>
|
||||
<li><a href="/man/man3/Queue.3.html">Queue(3)</a> - Basic circular queue implementation</li>
|
||||
</ul>
|
||||
<p>User Documentation:</p>
|
||||
<table>
|
||||
<tr>
|
||||
<th>Man Page</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><a href="man/man7/telodendria.7.html">telodendria(7)</a></td>
|
||||
<td>
|
||||
<b>Start here.</b> This page contains the project introduction, and provides
|
||||
information about it, such as its status, how to contact the developers, and what
|
||||
the source code license is.
|
||||
</td>
|
||||
<tr>
|
||||
<td><a href="man/man8/telodendria.8.html">telodendria(8)</a><td>
|
||||
<td>
|
||||
Command line usage for <b>Telodendria</b> administrators.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<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>
|
||||
<p>
|
||||
<b>Telodendria</b> is distributed as source tarballs, in true Unix
|
||||
|
|
|
|||
Loading…
Reference in New Issue