diff options
Diffstat (limited to '')
| -rw-r--r-- | man3/libnormalform_transformation.3 | 245 |
1 files changed, 245 insertions, 0 deletions
diff --git a/man3/libnormalform_transformation.3 b/man3/libnormalform_transformation.3 new file mode 100644 index 0000000..7bb129e --- /dev/null +++ b/man3/libnormalform_transformation.3 @@ -0,0 +1,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 +.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) |