1 files changed, 242 insertions, 0 deletions
diff --git a/man3/libnormalform_xor.3 b/man3/libnormalform_xor.3
new file mode 100644
index 0000000..70e9584
--- /dev/null
+++ b/man3/libnormalform_xor.3
@@ -0,0 +1,242 @@
+.TH LIBNORMALFORM_XOR 3 LIBNORMALFORM
+.SH NAME
+libnormalform_xor \- Exclusive disjunction
+
+.SH SYNOPSIS
+.nf
+#include <libnormalform.h>
+
+LIBNORMALFORM_SENTENCE *libnormalform_xor(LIBNORMALFORM_SENTENCE **\fIxs\fP);
+LIBNORMALFORM_SENTENCE *libnormalform_xorl(LIBNORMALFORM_SENTENCE *\fIa\fP, ... /*, NULL */);
+LIBNORMALFORM_SENTENCE *libnormalform_vxor(LIBNORMALFORM_SENTENCE *\fIa\fP, va_list \fPargs\fP);
+LIBNORMALFORM_SENTENCE *libnormalform_xor_checked(size_t \fIn\fP, LIBNORMALFORM_SENTENCE **\fIxs\fP);
+LIBNORMALFORM_SENTENCE *libnormalform_xorl_checked(size_t \fIn\fP, LIBNORMALFORM_SENTENCE *\fIa\fP, ... /*, NULL */);
+LIBNORMALFORM_SENTENCE *libnormalform_vxor_checked(size_t \fIn\fP, LIBNORMALFORM_SENTENCE *\fIa\fP, va_list \fPargs\fP);
+LIBNORMALFORM_SENTENCE *libnormalform_xor2(LIBNORMALFORM_SENTENCE *\fIp\fP, LIBNORMALFORM_SENTENCE *\fIq\fP);
+#define LIBNORMALFORM_XOR(...) /* ... */
+.fi
+.PP
+Link with
+.IR -lnormalform .
+
+.SH DESCRIPTION
+The
+.BR libnormalform_xor ()
+function creates a sentence that is logically
+equivalent to the exclusive disjunction of the
+arguments, that is, a sentence that is true when
+and only when an odd number of subsentence is true.
+.PP
+The value of the
+.I xs
+parameter shall be a null-pointer terminated list
+of subsentences.
+.PP
+The
+.BR libnormalform_xorl ()
+function is a variant of
+.BR libnormalform_xor ()
+which uses variadic arguments instead of an array.
+.PP
+The
+.BR libnormalform_vxor ()
+function is a variant of
+.BR libnormalform_xorl ()
+which takes an
+.I va_list
+in place of variadic arguments.
+.PP
+The
+.BR libnormalform_xor_checked (),
+.BR libnormalform_xorl_checked (),
+and
+.BR libnormalform_vxor_checked ()
+functions are variants of the
+.BR libnormalform_xor (),
+.BR libnormalform_xorl (),
+and
+.BR libnormalform_vxor ()
+functions respectively which assumes
+that it is given
+.I n
+subsentances, and checks that all are
+.RI non- NULL .
+However, these functions still require
+the list of subsentences to be terminated
+using a null-pointer.
+.PP
+.I "libnormalform_xor2(p, q)"
+is equivalent to
+.IR "libnormalform_xorl_checked(2, p, q, NULL)" .
+.PP
+The
+.BR LIBNORMALFORM_XOR
+macro is a wrapper for the
+.BR libnormalform_xor_checked ()
+but is more similar to
+.BR libnormalform_xorl ().
+Unlike
+.BR libnormalform_xorl (),
+the argument list
+.I must not
+be terminated by a null-pointer, instead
+the macro automatically as the null-pointer.
+The macro will count the number of arguments
+it is given, therefore it will fail it the
+argument list is has an extra null-pointer.
+.PP
+The returned pointer shall either be
+deallocated with the
+.BR libnormalform_free (3)
+function or be relinquished by being
+used as part of another sentence.
+.PP
+These functions adopt the ownership of any
+.I LIBNORMALFORM_SENTENCE *
+passed into it. Therefore, the user shall
+not attempt to deallocate input sentences.
+This holds even on failure: if the function
+fails, input sentences are deallocated.
+
+.SH RETURN VALUE
+Upon successful completion, the
+.BR libnormalform_xor ()
+function and its variants return an object
+representing  the sentence; otherwise, the
+functions return
+.I NULL
+and set
+.I errno
+to indicate the error.
+
+.SH ERRORS
+These functions fails if:
+.TP
+.I ENOMEM
+Insufficient memory was available to
+create the sentence object.
+.PP
+The
+.BR libnormalform_xor_checked (),
+.BR libnormalform_xorl_checked (),
+and
+.BR libnormalform_vxor_checked ()
+functions will also fail without setting
+.I errno
+if any of the first
+.I n
+.IR "LIBNORMALFORM_SENTENCE *" 's
+are
+.IR NULL .
+Likewise, the
+.BR libnormalform_xor2 ()
+function will fail without setting
+.I errno
+if
+.I p
+or
+.I q
+is
+.IR NULL .
+
+.SH ATTRIBUTES
+For an explanation of the terms used in this
+section, see
+.BR attributes (7)
+and
+.IR "info \(dq(libc)POSIX Safety Concepts\(dq" .
+.TS
+allbox;
+lb lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.BR libnormalform_xor (),
+.br
+.BR libnormalform_xor_checked ()
+T}	Thread safety	MT-Safe race:\fIxs\fP and elements in \fIxs\fP
+T{
+.BR libnormalform_xorl (),
+.br
+.BR libnormalform_xorl_checked (),
+.br
+.BR libnormalform_xor2 (),
+.br
+.BR LIBNORMALFORM_XOR ()
+T}	Thread safety	MT-Safe race:parameters
+T{
+.BR libnormalform_vxor (),
+.br
+.BR libnormalform_vxor_checked ()
+T}	Thread safety	MT-Safe race:parameters and arguments in \fIargs\fP
+T{
+.BR libnormalform_xor (),
+.br
+.BR libnormalform_xorl (),
+.br
+.BR libnormalform_vxor (),
+.br
+.BR libnormalform_xor_checked (),
+.br
+.BR libnormalform_xorl_checked (),
+.br
+.BR libnormalform_vxor_checked (),
+.br
+.BR libnormalform_vxor2 (),
+.br
+.BR LIBNORMALFORM_XOR ()
+T}	Async-signal safety	AS-Unsafe heap
+T{
+.BR libnormalform_xor (),
+.br
+.BR libnormalform_xorl (),
+.br
+.BR libnormalform_vxor (),
+.br
+.BR libnormalform_xor_checked (),
+.br
+.BR libnormalform_xorl_checked (),
+.br
+.BR libnormalform_vxor_checked (),
+.br
+.BR libnormalform_vxor2 (),
+.br
+.BR LIBNORMALFORM_XOR ()
+T}	Async-cancel safety	AC-Safe mem, AC-Unsafe heap
+.TE
+
+.SH NOTES
+If there are no subsentences, the resulting sentence is a contradiction.
+.PP
+The connective is commutative and associative. It's truthtable is (0110).
+.PP
+The
+.BR LIBNORMALFORM_XOR ()
+macro requires ISO C23 support.
+.PP
+Using
+.BR libnormalform_xor2 (),
+has greatest performance, however
+.BR libnormalform_xor ()
+is better at simplifying the sentence.
+The other functions are just wrappers for the
+.BR libnormalform_xor ()
+function.
+.PP
+These functions creates a clause where each term
+is connected with the XOR connective. Unlike what
+the name Exclusive disjunction imply, this does
+.I not
+create a sentence that is true when exactly one
+subsentence is true. Rather this creates the parity
+of the terms: the sentece is when an odd number of
+subsentences are true.
+.PP
+Side-effects in the arguments of the macro
+.BR LIBNORMALFORM_XOR ()
+are guaranteed to be applied exactly once.
+The side-effects in each macro are applied
+in no particular order.
+
+.SH SEE ALSO
+.BR libnormalform (7)