.TH LIBNORMALFORM_TRANSFORMATION 3 LIBNORMALFORM
.SH PROLOGUE
This document describes the function
.BR libnormalform_transformation ,
refer to
.BR struct_libnormalform_transformation (3)
for the type
.IR "struct libnormalform_transformation" .

.SH NAME
libnormalform_transformation \- Function morphism

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

enum libnormalform_builtin_transformer {
        \fILIBNORMALFORM_NOT_BUILT_IN\fP = 0,
        \fILIBNORMALFORM_DOMAIN_VIEW\fP,
        \fILIBNORMALFORM_IMAGE_VIEW\fP
};

struct libnormalform_transformer {
        void *(*\fItransform\fP)(void *user_data, void *input);
        void (*\fIdeallocate\fP)(void *user_data, void *output);
        void *\fIuser_data\fP;
        const char *\fIidentifier\fP;
        struct libnormalform_transformer *\fIcopy_for_clone\fP;
        int \fIrequires_elimination\fP;
	enum libnormalform_builtin_transformer \fIbuiltin\fP;
};

LIBNORMALFORM_SENTENCE *libnormalform_transformation(struct libnormalform_transformer *\fIfunction\fP,
                                                     LIBNORMALFORM_SENTENCE *\fIsentence\fP);
.fi
.PP
Link with
.IR -lnormalform .

.SH DESCRIPTION
The
.BR libnormalform_transformation ()
function creates a sentence output
the transformation with the application-defined
.I function
over a
.IR sentence.
The pointer
.I function
is application-managed, and must exists while
the returned sentece exists.
.PP
.I function->transform
is used only be the
.BR libnormalform_evaluate (3)
function to modify input to other
functions (both
.I struct libnormalform_function
and
.IR "struct libnormalform_transformer" ).
.I function->user_data is passed to
.I *function->transform
as its first argument, and the function
input is passed as its second argument.
The function is expected to return a
.RI non- NULL
pointer upon successful completion and
.I NULL
on failure; on failure the function may
optionally set
.IR errno .
If
.I function->deallocate
is
.IR non -NULL ,
but unless
.I *function->transform
returns
.IR NULL ,
the library will call
.I *function->deallocate
when the pointer returned by
.I *function->transform
is no longer needed.
.I function->user_data is passed to
.I *function->deallocate
as its first argument, and the returned
pointer is passed as its second argument.
.I function->user_data
is only used by the application for
application-defined purposes.
.I function->user_data
and
.I function->deallocate
may, unlike
.IR function->transform ,
be
.IR NULL ;
however
.IR function->transform ,
.IR function->deallocate ,
and
.I function->user_data
need not be set before the
.BR libnormalform_evaluate (3)
function is called.
.PP
See
.BR libnormalform_to_string (3)
for the purpose of
.IR function->identifier ,
it need not be set before the
.BR libnormalform_to_string (3)
function is called.
.PP
See
.BR libnormalform_clone (3)
for the purpose of
.IR function->copy_for_clone ,
it need not be set before the
.BR libnormalform_clone (3)
function is called.
.PP
See
.BR libnormalform_express (3)
for the purpose of
.IR function->requires_elimination ,
it need not be set before any of the
.BR libnormalform_express (3),
.BR libnormalform_dnf (3),
and
.BR libnormalform_cnf (3)
functions are called.
.PP
See
.BR libnormalform_express (3)
for the purpose of
.IR function->builtin ,
the
.BR libnormalform_transformation ()
function always sets it to
.IR LIBNORMALFORM_NOT_BUILT_IN .
.PP
.I function
must not be
.IR NULL .
.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
The
.BR libnormalform_transformation ()
function adopt the ownership of
.IR sentence .
Therefore, the user shall not attempt to
deallocate
.IR sentence .
This holds even on failure: if the function
fails,
.I sentence
is deallocated.
.PP
.I *function->transform
may be called multiple types for the same
input even if it is only specified in a sentence
once, therefore calling it multiple times must
not have undesirable side effects. The function
shall return equivalent output given equivalent
input. Additionally for any functions F, G,
T(F # G) must be equivalent to T(F) # T(G) for
any operator #, where T is
.IR *function->transform .
Transformations over constants and variables
are removed as these do not take any input.
Transformations over qualifiers are illegal.

.SH RETURN VALUE
Upon successful completion, the
.BR libnormalform_transformation ()
function returns an sentence object of
the transformation; otherwise, the function
returns
.I NULL
and sets
.I errno
to indicate the error.
.PP
The
.BR libnormalform_transformation ()
function also fails without setting
.I errno
if
.I sentence
is
.IR NULL .

.SH ERRORS
The
.BR libnormalform_transformation ()
function fails if:
.TP
.I ENOMEM
Insufficient memory was available to
create the sentence object.
.TP
.I EDOM
.I sentence
contains a qualifier.

.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_transformation ()
T}	Thread safety	MT-Safe race:\fIsentence\fP
T{
.BR libnormalform_transformation ()
T}	Async-signal safety	AS-Unsafe heap
T{
.BR libnormalform_transformation ()
T}	Async-cancel safety	AC-Safe mem, AC-Unsafe heap
.TE

.SH NOTES
Sentences created with the
.BR libnormalform_empty (),
.BR libnormalform_nonempty (),
and
.BR libnormalform_singleton ()
functions count as qualifiers and
cannot be used in a transformation.

.SH SEE ALSO
.BR libnormalform (7)