7.25.11. grn_expr — Groonga v14.0.6 documentation

Skip to main content
`Ctrl`+`K`

# 7.25.11. grn_expr

grn_expr is an `grn_obj` that represents an expression. Here is a list of what expression can do:

> - Expression can apply some operations to a record by `grn_expr_exec()`.

> - Expression can represents search condition. `grn_table_select()` can select records that match against the search condition represented by expression.

There are two string representations of expression:

> - Query syntax

> - Script syntax

`grn_expr_parse()` parses string represented expression and appends the parsed expression to another expression.

## 7.25.11.1. Example

TODO…

## 7.25.11.2. Reference

grn_obj *grn_expr_create(grn_ctx *ctx, const char *name, unsigned int name_size)

grn_rc grn_expr_close(grn_ctx *ctx, grn_obj *expr)

grn_obj *grn_expr_add_var(grn_ctx *ctx, grn_obj *expr, const char *name, unsigned int name_size)

grn_obj *grn_expr_get_var_by_offset(grn_ctx *ctx, grn_obj *expr, unsigned int offset)

grn_obj *grn_expr_append_obj(grn_ctx *ctx, grn_obj *expr, grn_obj *obj, grn_operator op, int nargs)

grn_obj *grn_expr_append_const(grn_ctx *ctx, grn_obj *expr, grn_obj *obj, grn_operator op, int nargs)

grn_obj *grn_expr_append_const_str(grn_ctx *ctx, grn_obj *expr, const char *str, unsigned int str_size, grn_operator op, int nargs)

grn_obj *grn_expr_append_const_int(grn_ctx *ctx, grn_obj *expr, int i, grn_operator op, int nargs)

grn_rc grn_expr_append_op(grn_ctx *ctx, grn_obj *expr, grn_operator op, int nargs)

grn_rc grn_expr_get_keywords(grn_ctx *ctx, grn_obj *expr, grn_obj *keywords)

  Extracts keywords from `expr` and stores to `keywords`. Keywords in `keywords` are owned by `expr`. Don’t unlink them. Each keyword is `GRN_BULK` and its domain is `GRN_DB_TEXT`.

  `keywords` must be `GRN_PVECTOR`.

  Here is an example code:

      grn_obj keywords;
      GRN_PTR_INIT(&keywords, GRN_OBJ_VECTOR, GRN_ID_NIL);
      grn_expr_get_keywords(ctx, expr, &keywords);
      {
        int i, n_keywords;
        n_keywords = GRN_BULK_VSIZE(&keywords) / sizeof(grn_obj *);
        for (i = 0; i < n_keywords; i++) {
          grn_obj *keyword = GRN_PTR_VALUE_AT(&keywords, i);
          const char *keyword_content;
          int keyword_size;
          keyword_content = GRN_TEXT_VALUE(keyword);
          keyword_size = GRN_TEXT_LEN(keyword);
          /*
            Use keyword_content and keyword_size.
            You don't need to unlink keyword.
            keyword is owned by expr.
          */
        }
      }
      GRN_OBJ_FIN(ctx, &keywords);

  Parameters:

    - ctx – The context that creates the `expr`.

    - expr – The expression to be extracted.

    - keywords –

      The container to store extracted keywords. It must be `GRN_PVECTOR`.

      Each extracted keyword is `GRN_BULK` and its domain is `GRN_DB_TEXT`.

      Extracted keywords are owned by `expr`. Don’t unlink them.

  Returns:

    `GRN_SUCCESS` on success, not `GRN_SUCCESS` on error.

grn_rc grn_expr_syntax_escape(grn_ctx *ctx, const char *string, int string_size, const char *target_characters, char escape_character, grn_obj *escaped_string)

  Escapes `target_characters` in `string` by `escape_character`.

  Parameters:

    - ctx – Its encoding must be the same encoding of `string`. It is used for allocating buffer for `escaped_string`.

    - string – String expression representation.

    - string_size – The byte size of `string`. `-1` means `string` is NULL terminated string.

    - target_characters – NULL terminated escape target characters. For example, `"+-><~*()\"\\:"` is `target_characters` for Query syntax.

    - escape_character – The character to use escape a character in `target_characters`. For example, `\\` (backslash) is `escaped_character` for Query syntax.

    - escaped_string – The output of escaped `string`. It should be text typed bulk.

  Returns:

    `GRN_SUCCESS` on success, not `GRN_SUCCESS` on error.

grn_rc grn_expr_syntax_escape_query(grn_ctx *ctx, const char *query, int query_size, grn_obj *escaped_query)

  Escapes special characters in Query syntax.

  Parameters:

    - ctx – Its encoding must be the same encoding of `query`. It is used for allocating buffer for `escaped_query`.

    - query – String expression representation in Query syntax.

    - query_size – The byte size of `query`. `-1` means `query` is NULL terminated string.

    - escaped_query – The output of escaped `query`. It should be text typed bulk.

  Returns:

    `GRN_SUCCESS` on success, not `GRN_SUCCESS` on error.

grn_rc grn_expr_compile(grn_ctx *ctx, grn_obj *expr)

grn_obj *grn_expr_exec(grn_ctx *ctx, grn_obj *expr, int nargs)

grn_obj *grn_expr_alloc(grn_ctx *ctx, grn_obj *expr, grn_id domain, grn_obj_flags flags)