.TH LIBNORMALFORM_OR 3 LIBNORMALFORM
.SH NAME
libnormalform_or \- Inclusive disjunction

.SH SYNOPSIS
.nf
#include <libnormalform.h>

LIBNORMALFORM_SENTENCE *libnormalform_or(LIBNORMALFORM_SENTENCE **\fIxs\fP);
LIBNORMALFORM_SENTENCE *libnormalform_orl(LIBNORMALFORM_SENTENCE *\fIa\fP, ... /*, NULL */);
LIBNORMALFORM_SENTENCE *libnormalform_vor(LIBNORMALFORM_SENTENCE *\fIa\fP, va_list \fPargs\fP);
LIBNORMALFORM_SENTENCE *libnormalform_or_checked(size_t \fIn\fP, LIBNORMALFORM_SENTENCE **\fIxs\fP);
LIBNORMALFORM_SENTENCE *libnormalform_orl_checked(size_t \fIn\fP, LIBNORMALFORM_SENTENCE *\fIa\fP, ... /*, NULL */);
LIBNORMALFORM_SENTENCE *libnormalform_vor_checked(size_t \fIn\fP, LIBNORMALFORM_SENTENCE *\fIa\fP, va_list \fPargs\fP);
LIBNORMALFORM_SENTENCE *libnormalform_or2(LIBNORMALFORM_SENTENCE *\fIp\fP, LIBNORMALFORM_SENTENCE *\fIq\fP);
#define LIBNORMALFORM_OR(...) /* ... */
.fi
.PP
Link with
.IR -lnormalform .

.SH DESCRIPTION
The
.BR libnormalform_or ()
function creates a sentence that is logically
equivalent to the inclusive disjunction of the
arguments, that is, a sentence that is true when
and only when at least one subsentence is true.
.PP
The value of the
.I xs
parameter shall be a null-pointer terminated list
of subsentences.
.PP
The
.BR libnormalform_orl ()
function is a variant of
.BR libnormalform_or ()
which uses variadic arguments instead of an array.
.PP
The
.BR libnormalform_vor ()
function is a variant of
.BR libnormalform_orl ()
which takes an
.I va_list
in place of variadic arguments.
.PP
The
.BR libnormalform_or_checked (),
.BR libnormalform_orl_checked (),
and
.BR libnormalform_vor_checked ()
functions are variants of the
.BR libnormalform_or (),
.BR libnormalform_orl (),
and
.BR libnormalform_vor ()
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_or2(p, q)"
is equivalent to
.IR "libnormalform_orl_checked(2, p, q, NULL)" .
.PP
The
.BR LIBNORMALFORM_OR
macro is a wrapper for the
.BR libnormalform_or_checked ()
but is more similar to
.BR libnormalform_orl ().
Unlike
.BR libnormalform_orl (),
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_or ()
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 fail if:
.TP
.B ENOMEM
Insufficient memory was available to
create the sentence object.
.PP
The
.BR libnormalform_or_checked (),
.BR libnormalform_orl_checked (),
and
.BR libnormalform_vor_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_or2 ()
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_or (),
.br
.BR libnormalform_or_checked ()
T}	Thread safety	MT-Safe race:\fIxs\fP and elements in \fIxs\fP
T{
.BR libnormalform_orl (),
.br
.BR libnormalform_orl_checked (),
.br
.BR libnormalform_or2 (),
.br
.BR LIBNORMALFORM_OR ()
T}	Thread safety	MT-Safe race:parameters
T{
.BR libnormalform_vor (),
.br
.BR libnormalform_vor_checked ()
T}	Thread safety	MT-Safe race:parameters and arguments in \fIargs\fP
T{
.BR libnormalform_or (),
.br
.BR libnormalform_orl (),
.br
.BR libnormalform_vor (),
.br
.BR libnormalform_or_checked (),
.br
.BR libnormalform_orl_checked (),
.br
.BR libnormalform_vor_checked (),
.br
.BR libnormalform_vor2 (),
.br
.BR LIBNORMALFORM_OR ()
T}	Async-signal safety	AS-Unsafe heap
T{
.BR libnormalform_or (),
.br
.BR libnormalform_orl (),
.br
.BR libnormalform_vor (),
.br
.BR libnormalform_or_checked (),
.br
.BR libnormalform_orl_checked (),
.br
.BR libnormalform_vor_checked (),
.br
.BR libnormalform_vor2 (),
.br
.BR LIBNORMALFORM_OR ()
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 (0111).
.PP
The
.BR LIBNORMALFORM_OR ()
macro requires ISO C23 support.
.PP
Using
.BR libnormalform_or2 (),
has greatest performance, however
.BR libnormalform_or ()
is better at simplifying the sentence.
The other functions are just wrappers for the
.BR libnormalform_or ()
function.
.PP
Side-effects in the arguments of the macro
.BR LIBNORMALFORM_OR ()
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)