path: root/man3/libnormalform_nor.3

.TH LIBNORMALFORM_NOR 3 LIBNORMALFORM
.SH NAME
libnormalform_nor \- Alternative denial

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

LIBNORMALFORM_SENTENCE *libnormalform_nor(LIBNORMALFORM_SENTENCE **\fIxs\fP);
LIBNORMALFORM_SENTENCE *libnormalform_norl(LIBNORMALFORM_SENTENCE *\fIa\fP, ... /*, NULL */);
LIBNORMALFORM_SENTENCE *libnormalform_vnor(LIBNORMALFORM_SENTENCE *\fIa\fP, va_list \fPargs\fP);
LIBNORMALFORM_SENTENCE *libnormalform_nor_checked(size_t \fIn\fP, LIBNORMALFORM_SENTENCE **\fIxs\fP);
LIBNORMALFORM_SENTENCE *libnormalform_norl_checked(size_t \fIn\fP, LIBNORMALFORM_SENTENCE *\fIa\fP, ... /*, NULL */);
LIBNORMALFORM_SENTENCE *libnormalform_vnor_checked(size_t \fIn\fP, LIBNORMALFORM_SENTENCE *\fIa\fP, va_list \fPargs\fP);
LIBNORMALFORM_SENTENCE *libnormalform_nor2(LIBNORMALFORM_SENTENCE *\fIp\fP, LIBNORMALFORM_SENTENCE *\fIq\fP);
#define LIBNORMALFORM_NOR(...) /* ... */
.fi
.PP
Link with
.IR -lnormalform .

.SH DESCRIPTION
The
.BR libnormalform_nor ()
function creates a sentence where each subsentence
is connected with a NOR (alternative denial) operator.
In the case that exactly two subsentences are given,
this creates a clause that is true when and only when
at least one is false. There is no generally meaningful
interpretation if a NOR-clause containing more than
two terms.
.PP
The value of the
.I xs
parameter shall be a null-pointer terminated list
of subsentences.
.PP
The
.BR libnormalform_norl ()
function is a variant of
.BR libnormalform_nor ()
which uses variadic arguments instead of an array.
.PP
The
.BR libnormalform_vnor ()
function is a variant of
.BR libnormalform_norl ()
which takes an
.I va_list
in place of variadic arguments.
.PP
The
.BR libnormalform_nor_checked (),
.BR libnormalform_norl_checked (),
and
.BR libnormalform_vnor_checked ()
functions are variants of the
.BR libnormalform_nor (),
.BR libnormalform_norl (),
and
.BR libnormalform_vnor ()
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_nor2(p, q)"
is equivalent to
.IR "libnormalform_norl_checked(2, p, q, NULL)" .
.PP
The
.BR LIBNORMALFORM_NOR
macro is a wrapper for the
.BR libnormalform_nor_checked ()
but is more similar to
.BR libnormalform_norl ().
Unlike
.BR libnormalform_norl (),
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_nor ()
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.
.TP
.I EDOM
The function was not given any subsentences.
.PP
The
.BR libnormalform_nor_checked (),
.BR libnormalform_norl_checked (),
and
.BR libnormalform_vnor_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_nor2 ()
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_nor (),
.br
.BR libnormalform_nor_checked ()
T}	Thread safety	MT-Safe race:\fIxs\fP and elements in \fIxs\fP
T{
.BR libnormalform_norl (),
.br
.BR libnormalform_norl_checked (),
.br
.BR libnormalform_nor2 (),
.br
.BR LIBNORMALFORM_NOR ()
T}	Thread safety	MT-Safe race:parameters
T{
.BR libnormalform_vnor (),
.br
.BR libnormalform_vnor_checked ()
T}	Thread safety	MT-Safe race:parameters and arguments in \fIargs\fP
T{
.BR libnormalform_nor (),
.br
.BR libnormalform_norl (),
.br
.BR libnormalform_vnor (),
.br
.BR libnormalform_nor_checked (),
.br
.BR libnormalform_norl_checked (),
.br
.BR libnormalform_vnor_checked (),
.br
.BR libnormalform_vnor2 (),
.br
.BR LIBNORMALFORM_NOR ()
T}	Async-signal safety	AS-Unsafe heap
T{
.BR libnormalform_nor (),
.br
.BR libnormalform_norl (),
.br
.BR libnormalform_vnor (),
.br
.BR libnormalform_nor_checked (),
.br
.BR libnormalform_norl_checked (),
.br
.BR libnormalform_vnor_checked (),
.br
.BR libnormalform_vnor2 (),
.br
.BR LIBNORMALFORM_NOR ()
T}	Async-cancel safety	AC-Safe mem, AC-Unsafe heap
.TE

.SH NOTES
The connective is commutative and left-associative. It's truthtable is (1000).
.PP
The
.BR LIBNORMALFORM_NOR ()
macro requires ISO C23 support.
.PP
The
.BR libnormalform_nor ()
is primary function, the other functions are
just wrappers for the
.BR libnormalform_nor ()
function.
.PP
These functions creates a clause where each term is
connected with the NOR connective. Unlike what the
names Joint denial and Negated OR imply, this does
.I not
create a sentence that is true when all subsentences
are false. There is unfortunately no generally
meaningful interpretation: adding true term on the
right always create a contradiction, while adding a
false term on the right inverts the original clause.
.PP
Side-effects in the arguments of the macro
.BR LIBNORMALFORM_NOR ()
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)