.TH LIBNORMALFORM_TO_STRING 3 LIBNORMALFORM
.SH NAME
libnormalform_to_string \- Serialise into a string

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

char *libnormalform_to_string(LIBNORMALFORM_SENTENCE *\fIx\fP);
.fi
.PP
Link with
.IR -lnormalform .

.SH DESCRIPTION
The
.BR libnormalform_to_string ()
function creates a string representation if
.I x
designed for machine parsing, but can also be
read by sufficiently literate humans.
.PP
Before calling the
.BR libnormalform_to_string ()
function, application provided objects in
.I x
must be configured for serialisation:
.I .identifier
in each
.IR "struct libnormalform_variable" ,
.IR "struct libnormalform_function" ,
.IR "struct libnormalform_map" ,
and
.IR "struct libnormalform_transformer" ,
shall either be set to the string representation,
of the object, that can be parsed by the application
without it being terminated by a null byte.
.PP
The returned pointer shall either be
deallocated with the
.BR free (3)
function.
.PP
.I x
must not be
.IR NULL .

.SH RETURN VALUE
Upon successful completion, the
.BR libnormalform_to_string ()
function returns a null-byte terminated
non-empty, ASCII string representation of
.IR x ;
otherwise, the function returns
.I NULL
and sets
.I errno
to indicate the error.

.SH ERRORS
The
.BR libnormalform_to_string ()
function fails if:
.TP
.I ENOMEM
Insufficient memory was available to
serialise the sentence object.

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

.SH NOTES
When a
.I LIBNORMALFORM_SENTENCE
is created, it is optimised (this includes eliminiation
of redundant information and reordering) and reduced to
into fewer types of connetives (it's reducted into negation
normal form, except with XOR allowed, but not necessarily
to any canonical form) during construction, so the
.BR libnormalform_to_string ()
function will not necessarily reproduce the sentence
as it was specified when it was constructed.

.SH SEE ALSO
.BR libnormalform (7),
.BR libnormalform_from_string (3)