1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
|
.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
.B ENOMEM
Insufficient memory was available to
create the sentence object.
.TP
.B 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)
|
