Партнёры:
Хостинг:
NAME
FN_search_filter_t, fn_search_filter_create,
fn_search_filter_destroy, fn_search_filter_copy,
fn_search_filter_assign, fn_search_filter_expression,
fn_search_filter_arguments - filter expression for attribute
search
SYNOPSIS
#include <xfn/xfn.h>
FN_search_filter_t *fn_search_filter_create(unsigned int
*status, const unsigned char *estr, .);
void fn_search_filter_destroy(FN_search_filter_t *sfilter);
FN_search_filter_t *fn_search_filter_copy(const
FN_search_filter_t *sfilter);
FN_search_filter_t
*fn_search_filter_assign(FN_search_filter_t *dst, const
FN_search_filter_t *src);
const char *fn_search_filter_expression(const
FN_search_filter_t *sfilter);
const void **fn_search_filter_arguments(const
FN_search_filter_t *sfilter, size_t *number_of_arguments);
DESCRIPTION
The FN_search_filter_t type is an expression that is
evaluated against the attributes of named objects bound in
the scope of the search operation fn_attr_ext_search(3XFN).
The filter evaluates to TRUE or FALSE. If the filter is
empty, it evaluates to TRUE. Names of objects whose attri-
bute values satisfy the filter expression are returned by
the search operation.
If the identifier in any subexpression of the filter does
not exist as an attribute of an object, then the innermost
logical expression containing that identifier is FALSE. A
subexpression that is only an attribute tests for the pres-
ence of the attribute; the subexpression evaluates to TRUE
if the attribute has been defined for the object and FALSE
otherwise.
fn_search_filter_create() creates a search filter from the
expression string estr and the remaining arguments.
fn_search_filter_destroy() releases the storage associated
with the search filter sfilter.
fn_search_filter_copy() returns a copy of the search filter
sfilter.
fn_search_filter_assign() makes a copy of the search filter
src and assigns it to dst, releasing the old contents of
dst. A pointer to the same object as dst is returned.
fn_search_filter_expression() returns the filter expression
of sfilter.
fn_search_filter_arguments() returns an array of pointers to
arguments supplied to the filter constructor.
number_of_arguments is set to the size of this array. The
types of the arguments are determined by the substitution
tokens in the expression in sfilter.
BNF of Filter Expression
<FilterExpr> ::= [ <Expr> ]
<Expr> ::= <Expr> "or" <Expr>
<Expr> "and" <Expr>
| "not" <Expr>
| "(" <Expr> ")"
| <Attribute> [ <Rel_Op> <Value> ]
| <Ext>
<Rel_Op> ::= "==" | "!=" | "<" | "<=" | ">" | ">=" | "~="
<Attribute> ::= "%a"
<Value> ::= <Integer>
| "%v"
|<Wildcarded_string>
<Wildcarded_string> ::= "*"
| <String>
| {<String> "*"}+ [<String>]
| {"*" <String>}+ ["*"]
<String> ::= "`" { <Char> } * "`"
| "%s"
<Char> ::= <PCS> // See BNF in Section 4.1.2 for PCSdefinition
| Characters in the repertoire of a string representation
<Identifier> ::=" "%i"
<Ext> ::= <Ext_Op> "(" [Arg_List] ")"
<Ext_Op> ::= <String> | <Identifier>
<Arg_List> ::= <Arg> | <Arg> "," <Arg_List>
<Arg> ::= <Value> | <Attribute> | <Identifier>
Specification of Filter Expression
The arguments to fn_search_filter_create() are a return
status, an expression string, and a list of arguments. The
string contains the filter expression with substitution
tokens for the attributes, attribute values, strings, and
identifiers that are part of the expression. The remaining
list of arguments contains the attributes and values in the
order of appearance of their corresponding substitution
tokens in the expression. The arguments are of types
FN_attribute_t*, FN_attrvalue_t*, FN_string_t*, or
FN_identifier_t*. Any attribute values in an
FN_attribute_t* type of argument are ignored; only the
attribute identifier and attribute syntax are relevant. The
argument type expected by each substitution token are listed
in the following table.
____________________________________________________________
| Token | Argument Type |
| %a | FN_attribute_t* |
| %v | FN_attrvalue_t* |
| %s | FN_string_t* |
| %i | FN_identifier_t* |
|__________________|________________________________________|
Precedence
The following precedence relations hold in the absence of
parentheses, in the order of lowest to highest:
or
and
not
relational operators
These boolean and relational operators are left associative.
Relational Operators
Comparisons and ordering are specific to the syntax and/or
rules of the supplied attribute.
Locale (code set, language, or territory) mismatches that
occur during string comparisons and ordering operations are
resolved in an implementation-dependent way. Relational
operations that have ordering semantics may be used for
strings of code sets in which ordering is meaningful, but is
not of general use in internationalized environments.
An attribute that occurs in the absence of any relational
operator tests for the presence of the attribute.
____________________________________________________________
| Operator | Meaning |
| == | The sub-expression is TRUE if at least|
| | one value of the specified attribute is|
| | equal to the supplied value. |
| != | The sub-expression is TRUE if no values|
| | of the specified attribute equal the|
| | supplied value. |
| >= | The sub-expression is TRUE if at least|
| | one value of the attribute is greater|
| | than or equal to the supplied value. |
| > | The sub-expression is TRUE if at least|
| | one value of the attribute is greater|
| | then the supplied value. |
| <= | The sub-expression is TRUE if at least|
| | one value of the attribute is less than|
| | or equal to the supplied value. |
| < | The sub-expression is TRUE if at least|
| | one value of the attribute is less than|
| | the supplied value. |
| ~= | The sub-expression is TRUE if at least|
| | one value of the specified attribute|
| | matches the supplied value according to|
| | some context-specific approximate|
| | matching criterion. This criterion must|
| | subsume strict equality. |
|__________________|________________________________________|
Wildcarded Strings
A wildcarded string consists of a sequence of alternating
wildcard specifiers and strings. The sequence can start with
either a wildcard specifier or a string, and end with either
a wildcard specifier or a string.
The wildcard specifier is denoted by the asterisk character
('*') and means zero or more occurrences of any character.
Wildcarded strings can be used to specify substring matches.
The following are examples of wildcarded strings and what
they mean:
_______________________________________________________________
| Wildcarded String | Meaning |
| * | Any string |
| *'ing' | Any string ending with ing |
| Any string starting | |
| with jo, and con-| |
| taining the sub-| |
| string ph, | |
| and which contains| |
| the substring ne in| |
| the portion | |
| of the string fol-| |
| lowing ph, and which| |
| ends with er | |
| T} | |
| %s* | Any string starting with the supplied|
| | string |
| Any string starting| |
| with bix and ending| |
| with the supplied| |
| string | |
| T} | |
|_____________________|________________________________________|
String matches involving strings of different locales (code
set, language, or territory) are resolved in an
implementation-dependent way.
Extended Operations
In addition to the relational operators, extended operators
can be specified. All extended operators return either TRUE
or FALSE. A filter expression can contain both relational
and extended operations.
Extended operators are specified using an identifier (see
FN_identifier_t(3XFN)) or a string. If the operator is
specified using a string, the string is used to construct an
identifier of format FN_ID_STRING. Identifiers of extended
operators and signatures of the corresponding extended
operations, as well as their suggested semantics, are
registered with X/Open Company Ltd.
The following three extended operations are currently
defined:
'name'(<Wildcarded String>)
The identifier for this operation is 'name'
(FN_ID_STRING). The argument to this operation is a
wildcard string. The operation returns TRUE if the
name of the object matches the supplied wildcard
string.
'reftype'(%i)
The identifier for this operation is 'reftype'
(FN_ID_STRING). The argument to this operation is an
identifier. The operation returns TRUE if the refer-
ence type of the object is equal to the supplied iden-
tifier.
'addrtype'(%i)
The identifier for this operation is 'addrtype' (LM
FN_ID_STRING). The argument to the operation is an
identifier. The operation returns TRUE if any of the
address types in the reference of the object is equal
to the supplied identifier.
Support and exact semantics of extended operations are
context-specific. If a context does not support an extended
operation, or if the filter expression supplies the extended
operation with either an incorrect number or type of argu-
ments, the error FN_E_SEARCH_INVALID_OP is returned. (Note:
FN_E_OPERATION_NOT_SUPPORTED is returned when
fn_attr_ext_search(3XFN) is not supported.)
The following are examples of filter expressions that con-
tain extended operations:
______________________________________________________________
| Expression | Meaning |
| Evaluates to | |
| TRUE | |
| if the name of the object| |
| starts with | |
| bill. | |
| T} | |
| %i(%a, %v) | Evaluates to result of|
| | applying the specified|
| | operation to the supplied|
| | arguments. |
| (%a == %v) and 'name'('joe'*)| Evaluates to TRUE if the|
| | specified attribute has the|
| | given value and if the name|
| | of the object starts with|
| | joe. |
|______________________________|______________________________|
RETURN VALUES
fn_search_filter_create() returns a pointer to an
FN_search_filter_t object if the operation succeeds; other-
wise it returns a NULL pointer.
ERRORS
fn_search_filter_create() returns a NULL pointer if the
operation fails and sets status in the following way:
FN_E_SEARCH_INVALID_FILTER
The filter expression had a syntax error or some other
problem.
FN_E_SEARCH_INVALID_OP
An operator in the filter expression is not supported
or, if the operator is an extended operator, the
number of types of arguments supplied does not match
the signature of the operation.
FN_E_INVALID_ATTR_IDENTIFIER
The left hand side of an operator expression was not
an attribute.
FN_E_INVALID_ATTR_VALUE
The right hand side of an operator expression was not
an integer, attribute value, or (wildcarded) string.
Other status codes are possible as described in the refer-
ence manual pages for FN_status_t(3XFN) and
xfn_status_codes(3XFN).
EXAMPLES
Example 1: Creating Different Filters
The following examples illustrate how to create three dif-
ferent filters.
The first example shows how to construct a filter involving
substitution tokens and literals in the same filter expres-
sion. This example creates a filter for named objects whose
color attribute contains a string value of red, blue, or
white. The first two values are specified using substitution
tokens; the last value, white, is specified as a literal in
the expression.
unsigned int status;
extern FN_attribute_t *attr_color;
FN_string_t *red = fn_string_from_str((unsigned char *)"red");
FN_string_t *blue = fn_string_from_str((unsigned char *)"blue");
FN_search_filter_t *sfilter;
sfilter = fn_search_filter_create(
&status,
"(%a == %s) or (%a == %s) or (%a == 'white')",
attr_color, red, attr_color, blue,
attr_color);
The second example illustrates how to construct a filter
involving a wildcarded string. This example creates a filter
for searching for named objects whose last_name attribute
has a value that begins with the character m.
unsigned int status;
extern FN_attribute_t *attr_last_name;
FN_search_filter_t *sfilter;
sfilter = fn_search_filter_create(
&status, "%a == 'm'*", attr_last_name);
The third example illustrates how to construct a filter
involving extended operations. This example creates a filter
for finding all named objects whose name ends with ton.
unsigned int status;
FN_search_filter_t *sfilter;
sfilter= fn_search_filter_create(&status, "'name'(*'ton')");
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| MT-Level | MT-Safe |
|_____________________________|_____________________________|
SEE ALSO
FN_attribute_t(3XFN), FN_attrvalue_t(3XFN),
FN_identifier_t(3XFN), FN_status_t(3XFN), FN_string_t(3XFN),
fn_attr_ext_search(3XFN), xfn_status_codes(3XFN), attri-
butes(5)
|
Закладки на сайте Проследить за страницей |
Created 1996-2024 by Maxim Chirkov Добавить, Поддержать, Вебмастеру |