intermediate changes

ref:cde9a383711a11544ce7e107a78147fb96cc4029

1 files changed, 1224 insertions, 0 deletions

diff --git a/contrib/libs/hyperscan/src/hs_compile.h b/contrib/libs/hyperscan/src/hs_compile.h
new file mode 100644
index 0000000000..b318c29db1
--- /dev/null
+++ b/contrib/libs/hyperscan/src/hs_compile.h
@@ -0,0 +1,1224 @@
+/*
+ * Copyright (c) 2015-2020, Intel Corporation
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ *  * Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *  * Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *  * Neither the name of Intel Corporation nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#ifndef HS_COMPILE_H_
+#define HS_COMPILE_H_
+
+/**
+ * @file
+ * @brief The Hyperscan compiler API definition.
+ *
+ * Hyperscan is a high speed regular expression engine.
+ *
+ * This header contains functions for compiling regular expressions into
+ * Hyperscan databases that can be used by the Hyperscan runtime.
+ */
+
+#include "hs_common.h"
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+/**
+ * A type containing error details that is returned by the compile calls (@ref
+ * hs_compile(), @ref hs_compile_multi() and @ref hs_compile_ext_multi()) on
+ * failure. The caller may inspect the values returned in this type to
+ * determine the cause of failure.
+ *
+ * Common errors generated during the compile process include:
+ *
+ *    - *Invalid parameter*
+ *
+ *      An invalid argument was specified in the compile call.
+ *
+ *    - *Unrecognised flag*
+ *
+ *      An unrecognised value was passed in the flags argument.
+ *
+ *    - *Pattern matches empty buffer*
+ *
+ *      By default, Hyperscan only supports patterns that will *always*
+ *      consume at least one byte of input. Patterns that do not have this
+ *      property (such as `/(abc)?/`) will produce this error unless
+ *      the @ref HS_FLAG_ALLOWEMPTY flag is supplied. Note that such
+ *      patterns will produce a match for *every* byte when scanned.
+ *
+ *    - *Embedded anchors not supported*
+ *
+ *      Hyperscan only supports the use of anchor meta-characters (such as
+ *      `^` and `$`) in patterns where they could *only* match
+ *      at the start or end of a buffer. A pattern containing an embedded
+ *      anchor, such as `/abc^def/`, can never match, as there is no
+ *      way for `abc` to precede the start of the data stream.
+ *
+ *    - *Bounded repeat is too large*
+ *
+ *      The pattern contains a repeated construct with very large finite
+ *      bounds.
+ *
+ *    - *Unsupported component type*
+ *
+ *      An unsupported PCRE construct was used in the pattern.
+ *
+ *    - *Unable to generate bytecode*
+ *
+ *      This error indicates that Hyperscan was unable to compile a pattern
+ *      that is syntactically valid. The most common cause is a pattern that is
+ *      very long and complex or contains a large repeated subpattern.
+ *
+ *    - *Unable to allocate memory*
+ *
+ *      The library was unable to allocate temporary storage used during
+ *      compilation time.
+ *
+ *    - *Allocator returned misaligned memory*
+ *
+ *      The memory allocator (either malloc() or the allocator set with @ref
+ *      hs_set_allocator()) did not correctly return memory suitably aligned
+ *      for the largest representable data type on this platform.
+ *
+ *    - *Internal error*
+ *
+ *      An unexpected error occurred: if this error is reported, please contact
+ *      the Hyperscan team with a description of the situation.
+ */
+typedef struct hs_compile_error {
+    /**
+     * A human-readable error message describing the error.
+     */
+    char *message;
+
+    /**
+     * The zero-based number of the expression that caused the error (if this
+     * can be determined). If the error is not specific to an expression, then
+     * this value will be less than zero.
+     */
+    int expression;
+} hs_compile_error_t;
+
+/**
+ * A type containing information on the target platform which may optionally be
+ * provided to the compile calls (@ref hs_compile(), @ref hs_compile_multi(),
+ * @ref hs_compile_ext_multi()).
+ *
+ * A hs_platform_info structure may be populated for the current platform by
+ * using the @ref hs_populate_platform() call.
+ */
+typedef struct hs_platform_info {
+    /**
+     * Information about the target platform which may be used to guide the
+     * optimisation process of the compile.
+     *
+     * Use of this field does not limit the processors that the resulting
+     * database can run on, but may impact the performance of the resulting
+     * database.
+     */
+    unsigned int tune;
+
+    /**
+     * Relevant CPU features available on the target platform
+     *
+     * This value may be produced by combining HS_CPU_FEATURE_* flags (such as
+     * @ref HS_CPU_FEATURES_AVX2). Multiple CPU features may be or'ed together
+     * to produce the value.
+     */
+    unsigned long long cpu_features;
+
+    /**
+     * Reserved for future use.
+     */
+    unsigned long long reserved1;
+
+    /**
+     * Reserved for future use.
+     */
+    unsigned long long reserved2;
+} hs_platform_info_t;
+
+/**
+ * A type containing information related to an expression that is returned by
+ * @ref hs_expression_info() or @ref hs_expression_ext_info.
+ */
+typedef struct hs_expr_info {
+    /**
+     * The minimum length in bytes of a match for the pattern.
+     *
+     * Note: in some cases when using advanced features to suppress matches
+     * (such as extended parameters or the @ref HS_FLAG_SINGLEMATCH flag) this
+     * may represent a conservative lower bound for the true minimum length of
+     * a match.
+     */
+    unsigned int min_width;
+
+    /**
+     * The maximum length in bytes of a match for the pattern. If the pattern
+     * has an unbounded maximum length, this will be set to the maximum value
+     * of an unsigned int (UINT_MAX).
+     *
+     * Note: in some cases when using advanced features to suppress matches
+     * (such as extended parameters or the @ref HS_FLAG_SINGLEMATCH flag) this
+     * may represent a conservative upper bound for the true maximum length of
+     * a match.
+     */
+    unsigned int max_width;
+
+    /**
+     * Whether this expression can produce matches that are not returned in
+     * order, such as those produced by assertions. Zero if false, non-zero if
+     * true.
+     */
+    char unordered_matches;
+
+    /**
+     * Whether this expression can produce matches at end of data (EOD). In
+     * streaming mode, EOD matches are raised during @ref hs_close_stream(),
+     * since it is only when @ref hs_close_stream() is called that the EOD
+     * location is known. Zero if false, non-zero if true.
+     *
+     * Note: trailing `\b` word boundary assertions may also result in EOD
+     * matches as end-of-data can act as a word boundary.
+     */
+    char matches_at_eod;
+
+    /**
+     * Whether this expression can *only* produce matches at end of data (EOD).
+     * In streaming mode, all matches for this expression are raised during
+     * @ref hs_close_stream(). Zero if false, non-zero if true.
+     */
+    char matches_only_at_eod;
+} hs_expr_info_t;
+
+/**
+ * A structure containing additional parameters related to an expression,
+ * passed in at build time to @ref hs_compile_ext_multi() or @ref
+ * hs_expression_ext_info.
+ *
+ * These parameters allow the set of matches produced by a pattern to be
+ * constrained at compile time, rather than relying on the application to
+ * process unwanted matches at runtime.
+ */
+typedef struct hs_expr_ext {
+    /**
+     * Flags governing which parts of this structure are to be used by the
+     * compiler. See @ref HS_EXT_FLAG.
+     */
+    unsigned long long flags;
+
+    /**
+     * The minimum end offset in the data stream at which this expression
+     * should match successfully. To use this parameter, set the
+     * @ref HS_EXT_FLAG_MIN_OFFSET flag in the hs_expr_ext::flags field.
+     */
+    unsigned long long min_offset;
+
+    /**
+     * The maximum end offset in the data stream at which this expression
+     * should match successfully. To use this parameter, set the
+     * @ref HS_EXT_FLAG_MAX_OFFSET flag in the hs_expr_ext::flags field.
+     */
+    unsigned long long max_offset;
+
+    /**
+     * The minimum match length (from start to end) required to successfully
+     * match this expression. To use this parameter, set the
+     * @ref HS_EXT_FLAG_MIN_LENGTH flag in the hs_expr_ext::flags field.
+     */
+    unsigned long long min_length;
+
+    /**
+     * Allow patterns to approximately match within this edit distance. To use
+     * this parameter, set the @ref HS_EXT_FLAG_EDIT_DISTANCE flag in the
+     * hs_expr_ext::flags field.
+     */
+    unsigned edit_distance;
+
+    /**
+     * Allow patterns to approximately match within this Hamming distance. To
+     * use this parameter, set the @ref HS_EXT_FLAG_HAMMING_DISTANCE flag in the
+     * hs_expr_ext::flags field.
+     */
+    unsigned hamming_distance;
+} hs_expr_ext_t;
+
+/**
+ * @defgroup HS_EXT_FLAG hs_expr_ext_t flags
+ *
+ * These flags are used in @ref hs_expr_ext_t::flags to indicate which fields
+ * are used.
+ *
+ * @{
+ */
+
+/** Flag indicating that the hs_expr_ext::min_offset field is used. */
+#define HS_EXT_FLAG_MIN_OFFSET      1ULL
+
+/** Flag indicating that the hs_expr_ext::max_offset field is used. */
+#define HS_EXT_FLAG_MAX_OFFSET      2ULL
+
+/** Flag indicating that the hs_expr_ext::min_length field is used. */
+#define HS_EXT_FLAG_MIN_LENGTH      4ULL
+
+/** Flag indicating that the hs_expr_ext::edit_distance field is used. */
+#define HS_EXT_FLAG_EDIT_DISTANCE   8ULL
+
+/** Flag indicating that the hs_expr_ext::hamming_distance field is used. */
+#define HS_EXT_FLAG_HAMMING_DISTANCE 16ULL
+
+/** @} */
+
+/**
+ * The basic regular expression compiler.
+ *
+ * This is the function call with which an expression is compiled into a
+ * Hyperscan database which can be passed to the runtime functions (such as
+ * @ref hs_scan(), @ref hs_open_stream(), etc.)
+ *
+ * @param expression
+ *      The NULL-terminated expression to parse. Note that this string must
+ *      represent ONLY the pattern to be matched, with no delimiters or flags;
+ *      any global flags should be specified with the @p flags argument. For
+ *      example, the expression `/abc?def/i` should be compiled by providing
+ *      `abc?def` as the @p expression, and @ref HS_FLAG_CASELESS as the @a
+ *      flags.
+ *
+ * @param flags
+ *      Flags which modify the behaviour of the expression. Multiple flags may
+ *      be used by ORing them together. Valid values are:
+ *       - HS_FLAG_CASELESS - Matching will be performed case-insensitively.
+ *       - HS_FLAG_DOTALL - Matching a `.` will not exclude newlines.
+ *       - HS_FLAG_MULTILINE - `^` and `$` anchors match any newlines in data.
+ *       - HS_FLAG_SINGLEMATCH - Only one match will be generated for the
+ *                               expression per stream.
+ *       - HS_FLAG_ALLOWEMPTY - Allow expressions which can match against an
+ *                              empty string, such as `.*`.
+ *       - HS_FLAG_UTF8 - Treat this pattern as a sequence of UTF-8 characters.
+ *       - HS_FLAG_UCP - Use Unicode properties for character classes.
+ *       - HS_FLAG_PREFILTER - Compile pattern in prefiltering mode.
+ *       - HS_FLAG_SOM_LEFTMOST - Report the leftmost start of match offset
+ *                                when a match is found.
+ *       - HS_FLAG_COMBINATION - Parse the expression in logical combination
+ *                               syntax.
+ *       - HS_FLAG_QUIET - Ignore match reporting for this expression. Used for
+ *                         the sub-expressions in logical combinations.
+ *
+ * @param mode
+ *      Compiler mode flags that affect the database as a whole. One of @ref
+ *      HS_MODE_STREAM or @ref HS_MODE_BLOCK or @ref HS_MODE_VECTORED must be
+ *      supplied, to select between the generation of a streaming, block or
+ *      vectored database. In addition, other flags (beginning with HS_MODE_)
+ *      may be supplied to enable specific features. See @ref HS_MODE_FLAG for
+ *      more details.
+ *
+ * @param platform
+ *      If not NULL, the platform structure is used to determine the target
+ *      platform for the database. If NULL, a database suitable for running
+ *      on the current host platform is produced.
+ *
+ * @param db
+ *      On success, a pointer to the generated database will be returned in
+ *      this parameter, or NULL on failure. The caller is responsible for
+ *      deallocating the buffer using the @ref hs_free_database() function.
+ *
+ * @param error
+ *      If the compile fails, a pointer to a @ref hs_compile_error_t will be
+ *      returned, providing details of the error condition. The caller is
+ *      responsible for deallocating the buffer using the @ref
+ *      hs_free_compile_error() function.
+ *
+ * @return
+ *      @ref HS_SUCCESS is returned on successful compilation; @ref
+ *      HS_COMPILER_ERROR on failure, with details provided in the error
+ *      parameter.
+ */
+hs_error_t HS_CDECL hs_compile(const char *expression, unsigned int flags,
+                               unsigned int mode,
+                               const hs_platform_info_t *platform,
+                               hs_database_t **db, hs_compile_error_t **error);
+
+/**
+ * The multiple regular expression compiler.
+ *
+ * This is the function call with which a set of expressions is compiled into a
+ * database which can be passed to the runtime functions (such as @ref
+ * hs_scan(), @ref hs_open_stream(), etc.) Each expression can be labelled with
+ * a unique integer which is passed into the match callback to identify the
+ * pattern that has matched.
+ *
+ * @param expressions
+ *      Array of NULL-terminated expressions to compile. Note that (as for @ref
+ *      hs_compile()) these strings must contain only the pattern to be
+ *      matched, with no delimiters or flags. For example, the expression
+ *      `/abc?def/i` should be compiled by providing `abc?def` as the first
+ *      string in the @p expressions array, and @ref HS_FLAG_CASELESS as the
+ *      first value in the @p flags array.
+ *
+ * @param flags
+ *      Array of flags which modify the behaviour of each expression. Multiple
+ *      flags may be used by ORing them together.  Specifying the NULL pointer
+ *      in place of an array will set the flags value for all patterns to zero.
+ *      Valid values are:
+ *       - HS_FLAG_CASELESS - Matching will be performed case-insensitively.
+ *       - HS_FLAG_DOTALL - Matching a `.` will not exclude newlines.
+ *       - HS_FLAG_MULTILINE - `^` and `$` anchors match any newlines in data.
+ *       - HS_FLAG_SINGLEMATCH - Only one match will be generated by patterns
+ *                               with this match id per stream.
+ *       - HS_FLAG_ALLOWEMPTY - Allow expressions which can match against an
+ *                              empty string, such as `.*`.
+ *       - HS_FLAG_UTF8 - Treat this pattern as a sequence of UTF-8 characters.
+ *       - HS_FLAG_UCP - Use Unicode properties for character classes.
+ *       - HS_FLAG_PREFILTER - Compile pattern in prefiltering mode.
+ *       - HS_FLAG_SOM_LEFTMOST - Report the leftmost start of match offset
+ *                                when a match is found.
+ *       - HS_FLAG_COMBINATION - Parse the expression in logical combination
+ *                               syntax.
+ *       - HS_FLAG_QUIET - Ignore match reporting for this expression. Used for
+ *                         the sub-expressions in logical combinations.
+ *
+ * @param ids
+ *      An array of integers specifying the ID number to be associated with the
+ *      corresponding pattern in the expressions array. Specifying the NULL
+ *      pointer in place of an array will set the ID value for all patterns to
+ *      zero.
+ *
+ * @param elements
+ *      The number of elements in the input arrays.
+ *
+ * @param mode
+ *      Compiler mode flags that affect the database as a whole. One of @ref
+ *      HS_MODE_STREAM or @ref HS_MODE_BLOCK or @ref HS_MODE_VECTORED must be
+ *      supplied, to select between the generation of a streaming, block or
+ *      vectored database. In addition, other flags (beginning with HS_MODE_)
+ *      may be supplied to enable specific features. See @ref HS_MODE_FLAG for
+ *      more details.
+ *
+ * @param platform
+ *      If not NULL, the platform structure is used to determine the target
+ *      platform for the database. If NULL, a database suitable for running
+ *      on the current host platform is produced.
+ *
+ * @param db
+ *      On success, a pointer to the generated database will be returned in
+ *      this parameter, or NULL on failure. The caller is responsible for
+ *      deallocating the buffer using the @ref hs_free_database() function.
+ *
+ * @param error
+ *      If the compile fails, a pointer to a @ref hs_compile_error_t will be
+ *      returned, providing details of the error condition. The caller is
+ *      responsible for deallocating the buffer using the @ref
+ *      hs_free_compile_error() function.
+ *
+ * @return
+ *      @ref HS_SUCCESS is returned on successful compilation; @ref
+ *      HS_COMPILER_ERROR on failure, with details provided in the @p error
+ *      parameter.
+ *
+ */
+hs_error_t HS_CDECL hs_compile_multi(const char *const *expressions,
+                                     const unsigned int *flags,
+                                     const unsigned int *ids,
+                                     unsigned int elements, unsigned int mode,
+                                     const hs_platform_info_t *platform,
+                                     hs_database_t **db,
+                                     hs_compile_error_t **error);
+
+/**
+ * The multiple regular expression compiler with extended parameter support.
+ *
+ * This function call compiles a group of expressions into a database in the
+ * same way as @ref hs_compile_multi(), but allows additional parameters to be
+ * specified via an @ref hs_expr_ext_t structure per expression.
+ *
+ * @param expressions
+ *      Array of NULL-terminated expressions to compile. Note that (as for @ref
+ *      hs_compile()) these strings must contain only the pattern to be
+ *      matched, with no delimiters or flags. For example, the expression
+ *      `/abc?def/i` should be compiled by providing `abc?def` as the first
+ *      string in the @p expressions array, and @ref HS_FLAG_CASELESS as the
+ *      first value in the @p flags array.
+ *
+ * @param flags
+ *      Array of flags which modify the behaviour of each expression. Multiple
+ *      flags may be used by ORing them together. Specifying the NULL pointer
+ *      in place of an array will set the flags value for all patterns to zero.
+ *      Valid values are:
+ *       - HS_FLAG_CASELESS - Matching will be performed case-insensitively.
+ *       - HS_FLAG_DOTALL - Matching a `.` will not exclude newlines.
+ *       - HS_FLAG_MULTILINE - `^` and `$` anchors match any newlines in data.
+ *       - HS_FLAG_SINGLEMATCH - Only one match will be generated by patterns
+ *                               with this match id per stream.
+ *       - HS_FLAG_ALLOWEMPTY - Allow expressions which can match against an
+ *                              empty string, such as `.*`.
+ *       - HS_FLAG_UTF8 - Treat this pattern as a sequence of UTF-8 characters.
+ *       - HS_FLAG_UCP - Use Unicode properties for character classes.
+ *       - HS_FLAG_PREFILTER - Compile pattern in prefiltering mode.
+ *       - HS_FLAG_SOM_LEFTMOST - Report the leftmost start of match offset
+ *                                when a match is found.
+ *       - HS_FLAG_COMBINATION - Parse the expression in logical combination
+ *                               syntax.
+ *       - HS_FLAG_QUIET - Ignore match reporting for this expression. Used for
+ *                         the sub-expressions in logical combinations.
+ *
+ * @param ids
+ *      An array of integers specifying the ID number to be associated with the
+ *      corresponding pattern in the expressions array. Specifying the NULL
+ *      pointer in place of an array will set the ID value for all patterns to
+ *      zero.
+ *
+ * @param ext
+ *      An array of pointers to filled @ref hs_expr_ext_t structures that
+ *      define extended behaviour for each pattern. NULL may be specified if no
+ *      extended behaviour is needed for an individual pattern, or in place of
+ *      the whole array if it is not needed for any expressions. Memory used by
+ *      these structures must be both allocated and freed by the caller.
+ *
+ * @param elements
+ *      The number of elements in the input arrays.
+ *
+ * @param mode
+ *      Compiler mode flags that affect the database as a whole. One of @ref
+ *      HS_MODE_STREAM, @ref HS_MODE_BLOCK or @ref HS_MODE_VECTORED must be
+ *      supplied, to select between the generation of a streaming, block or
+ *      vectored database. In addition, other flags (beginning with HS_MODE_)
+ *      may be supplied to enable specific features. See @ref HS_MODE_FLAG for
+ *      more details.
+ *
+ * @param platform
+ *      If not NULL, the platform structure is used to determine the target
+ *      platform for the database. If NULL, a database suitable for running
+ *      on the current host platform is produced.
+ *
+ * @param db
+ *      On success, a pointer to the generated database will be returned in
+ *      this parameter, or NULL on failure. The caller is responsible for
+ *      deallocating the buffer using the @ref hs_free_database() function.
+ *
+ * @param error
+ *      If the compile fails, a pointer to a @ref hs_compile_error_t will be
+ *      returned, providing details of the error condition. The caller is
+ *      responsible for deallocating the buffer using the @ref
+ *      hs_free_compile_error() function.
+ *
+ * @return
+ *      @ref HS_SUCCESS is returned on successful compilation; @ref
+ *      HS_COMPILER_ERROR on failure, with details provided in the @p error
+ *      parameter.
+ *
+ */
+hs_error_t HS_CDECL hs_compile_ext_multi(const char *const *expressions,
+                                const unsigned int *flags,
+                                const unsigned int *ids,
+                                const hs_expr_ext_t *const *ext,
+                                unsigned int elements, unsigned int mode,
+                                const hs_platform_info_t *platform,
+                                hs_database_t **db, hs_compile_error_t **error);
+
+/**
+ * The basic pure literal expression compiler.
+ *
+ * This is the function call with which a pure literal expression (not a
+ * common regular expression) is compiled into a Hyperscan database which
+ * can be passed to the runtime functions (such as @ref hs_scan(),
+ * @ref hs_open_stream(), etc.)
+ *
+ * @param expression
+ *      The NULL-terminated expression to parse. Note that this string must
+ *      represent ONLY the pattern to be matched, with no delimiters or flags;
+ *      any global flags should be specified with the @p flags argument. For
+ *      example, the expression `/abc?def/i` should be compiled by providing
+ *      `abc?def` as the @p expression, and @ref HS_FLAG_CASELESS as the @a
+ *      flags. Meanwhile, the string content shall be fully parsed in a literal
+ *      sense without any regular grammars. For example, the @p expression
+ *      `abc?` simply means a char sequence of `a`, `b`, `c`, and `?`. The `?`
+ *      here doesn't mean 0 or 1 quantifier under regular semantics.
+ *
+ * @param flags
+ *      Flags which modify the behaviour of the expression. Multiple flags may
+ *      be used by ORing them together. Compared to @ref hs_compile(), fewer
+ *      valid values are provided:
+ *       - HS_FLAG_CASELESS - Matching will be performed case-insensitively.
+ *       - HS_FLAG_SINGLEMATCH - Only one match will be generated for the
+ *                               expression per stream.
+ *       - HS_FLAG_SOM_LEFTMOST - Report the leftmost start of match offset
+ *                                when a match is found.
+ *
+ * @param len
+ *      The length of the text content of the pure literal expression. As the
+ *      text content indicated by @p expression is treated as single character
+ *      one by one, the special terminating character `\0` should be allowed
+ *      to appear in expression, and not treated as a terminator for a string.
+ *      Thus, the end of a pure literal expression cannot be indicated by
+ *      identifying `\0`, but by counting to the expression length.
+ *
+ * @param mode
+ *      Compiler mode flags that affect the database as a whole. One of @ref
+ *      HS_MODE_STREAM or @ref HS_MODE_BLOCK or @ref HS_MODE_VECTORED must be
+ *      supplied, to select between the generation of a streaming, block or
+ *      vectored database. In addition, other flags (beginning with HS_MODE_)
+ *      may be supplied to enable specific features. See @ref HS_MODE_FLAG for
+ *      more details.
+ *
+ * @param platform
+ *      If not NULL, the platform structure is used to determine the target
+ *      platform for the database. If NULL, a database suitable for running
+ *      on the current host platform is produced.
+ *
+ * @param db
+ *      On success, a pointer to the generated database will be returned in
+ *      this parameter, or NULL on failure. The caller is responsible for
+ *      deallocating the buffer using the @ref hs_free_database() function.
+ *
+ * @param error
+ *      If the compile fails, a pointer to a @ref hs_compile_error_t will be
+ *      returned, providing details of the error condition. The caller is
+ *      responsible for deallocating the buffer using the @ref
+ *      hs_free_compile_error() function.
+ *
+ * @return
+ *      @ref HS_SUCCESS is returned on successful compilation; @ref
+ *      HS_COMPILER_ERROR on failure, with details provided in the error
+ *      parameter.
+ */
+hs_error_t HS_CDECL hs_compile_lit(const char *expression, unsigned flags,
+                                   const size_t len, unsigned mode,
+                                   const hs_platform_info_t *platform,
+                                   hs_database_t **db,
+                                   hs_compile_error_t **error);
+/**
+ * The multiple pure literal expression compiler.
+ *
+ * This is the function call with which a set of pure literal expressions is
+ * compiled into a database which can be passed to the runtime functions (such
+ * as @ref hs_scan(), @ref hs_open_stream(), etc.) Each expression can be
+ * labelled with a unique integer which is passed into the match callback to
+ * identify the pattern that has matched.
+ *
+ * @param expressions
+ *      The NULL-terminated expression to parse. Note that this string must
+ *      represent ONLY the pattern to be matched, with no delimiters or flags;
+ *      any global flags should be specified with the @p flags argument. For
+ *      example, the expression `/abc?def/i` should be compiled by providing
+ *      `abc?def` as the @p expression, and @ref HS_FLAG_CASELESS as the @a
+ *      flags. Meanwhile, the string content shall be fully parsed in a literal
+ *      sense without any regular grammars. For example, the @p expression
+ *      `abc?` simply means a char sequence of `a`, `b`, `c`, and `?`. The `?`
+ *      here doesn't mean 0 or 1 quantifier under regular semantics.
+ *
+ * @param flags
+ *      Array of flags which modify the behaviour of each expression. Multiple
+ *      flags may be used by ORing them together. Specifying the NULL pointer
+ *      in place of an array will set the flags value for all patterns to zero.
+ *      Compared to @ref hs_compile_multi(), fewer valid values are provided:
+ *       - HS_FLAG_CASELESS - Matching will be performed case-insensitively.
+ *       - HS_FLAG_SINGLEMATCH - Only one match will be generated for the
+ *                               expression per stream.
+ *       - HS_FLAG_SOM_LEFTMOST - Report the leftmost start of match offset
+ *                                when a match is found.
+ *
+ * @param ids
+ *      An array of integers specifying the ID number to be associated with the
+ *      corresponding pattern in the expressions array. Specifying the NULL
+ *      pointer in place of an array will set the ID value for all patterns to
+ *      zero.
+ *
+ * @param lens
+ *      Array of lengths of the text content of each pure literal expression.
+ *      As the text content indicated by @p expression is treated as single
+ *      character one by one, the special terminating character `\0` should be
+ *      allowed to appear in expression, and not treated as a terminator for a
+ *      string. Thus, the end of a pure literal expression cannot be indicated
+ *      by identifying `\0`, but by counting to the expression length.
+ *
+ * @param elements
+ *      The number of elements in the input arrays.
+ *
+ * @param mode
+ *      Compiler mode flags that affect the database as a whole. One of @ref
+ *      HS_MODE_STREAM or @ref HS_MODE_BLOCK or @ref HS_MODE_VECTORED must be
+ *      supplied, to select between the generation of a streaming, block or
+ *      vectored database. In addition, other flags (beginning with HS_MODE_)
+ *      may be supplied to enable specific features. See @ref HS_MODE_FLAG for
+ *      more details.
+ *
+ * @param platform
+ *      If not NULL, the platform structure is used to determine the target
+ *      platform for the database. If NULL, a database suitable for running
+ *      on the current host platform is produced.
+ *
+ * @param db
+ *      On success, a pointer to the generated database will be returned in
+ *      this parameter, or NULL on failure. The caller is responsible for
+ *      deallocating the buffer using the @ref hs_free_database() function.
+ *
+ * @param error
+ *      If the compile fails, a pointer to a @ref hs_compile_error_t will be
+ *      returned, providing details of the error condition. The caller is
+ *      responsible for deallocating the buffer using the @ref
+ *      hs_free_compile_error() function.
+ *
+ * @return
+ *      @ref HS_SUCCESS is returned on successful compilation; @ref
+ *      HS_COMPILER_ERROR on failure, with details provided in the error
+ *      parameter.
+ */
+hs_error_t HS_CDECL hs_compile_lit_multi(const char * const *expressions,
+                                         const unsigned *flags,
+                                         const unsigned *ids,
+                                         const size_t *lens,
+                                         unsigned elements, unsigned mode,
+                                         const hs_platform_info_t *platform,
+                                         hs_database_t **db,
+                                         hs_compile_error_t **error);
+
+/**
+ * Free an error structure generated by @ref hs_compile(), @ref
+ * hs_compile_multi() or @ref hs_compile_ext_multi().
+ *
+ * @param error
+ *      The @ref hs_compile_error_t to be freed. NULL may also be safely
+ *      provided.
+ *
+ * @return
+ *      @ref HS_SUCCESS on success, other values on failure.
+ */
+hs_error_t HS_CDECL hs_free_compile_error(hs_compile_error_t *error);
+
+/**
+ * Utility function providing information about a regular expression. The
+ * information provided in @ref hs_expr_info_t includes the minimum and maximum
+ * width of a pattern match.
+ *
+ * Note: successful analysis of an expression with this function does not imply
+ * that compilation of the same expression (via @ref hs_compile(), @ref
+ * hs_compile_multi() or @ref hs_compile_ext_multi()) would succeed. This
+ * function may return @ref HS_SUCCESS for regular expressions that Hyperscan
+ * cannot compile.
+ *
+ * Note: some per-pattern flags (such as @ref HS_FLAG_ALLOWEMPTY, @ref
+ * HS_FLAG_SOM_LEFTMOST) are accepted by this call, but as they do not affect
+ * the properties returned in the @ref hs_expr_info_t structure, they will not
+ * affect the outcome of this function.
+ *
+ * @param expression
+ *      The NULL-terminated expression to parse. Note that this string must
+ *      represent ONLY the pattern to be matched, with no delimiters or flags;
+ *      any global flags should be specified with the @p flags argument.  For
+ *      example, the expression `/abc?def/i` should be compiled by providing
+ *      `abc?def` as the @p expression, and @ref HS_FLAG_CASELESS as the @a
+ *      flags.
+ *
+ * @param flags
+ *      Flags which modify the behaviour of the expression. Multiple flags may
+ *      be used by ORing them together. Valid values are:
+ *       - HS_FLAG_CASELESS - Matching will be performed case-insensitively.
+ *       - HS_FLAG_DOTALL - Matching a `.` will not exclude newlines.
+ *       - HS_FLAG_MULTILINE - `^` and `$` anchors match any newlines in data.
+ *       - HS_FLAG_SINGLEMATCH - Only one match will be generated by the
+ *                               expression per stream.
+ *       - HS_FLAG_ALLOWEMPTY - Allow expressions which can match against an
+ *                              empty string, such as `.*`.
+ *       - HS_FLAG_UTF8 - Treat this pattern as a sequence of UTF-8 characters.
+ *       - HS_FLAG_UCP - Use Unicode properties for character classes.
+ *       - HS_FLAG_PREFILTER - Compile pattern in prefiltering mode.
+ *       - HS_FLAG_SOM_LEFTMOST - Report the leftmost start of match offset
+ *                                when a match is found.
+ *       - HS_FLAG_COMBINATION - Parse the expression in logical combination
+ *                               syntax.
+ *       - HS_FLAG_QUIET - Ignore match reporting for this expression. Used for
+ *                         the sub-expressions in logical combinations.
+ *
+ * @param info
+ *      On success, a pointer to the pattern information will be returned in
+ *      this parameter, or NULL on failure. This structure is allocated using
+ *      the allocator supplied in @ref hs_set_allocator() (or malloc() if no
+ *      allocator was set) and should be freed by the caller.
+ *
+ * @param error
+ *      If the call fails, a pointer to a @ref hs_compile_error_t will be
+ *      returned, providing details of the error condition. The caller is
+ *      responsible for deallocating the buffer using the @ref
+ *      hs_free_compile_error() function.
+ *
+ * @return
+ *      @ref HS_SUCCESS is returned on successful compilation; @ref
+ *      HS_COMPILER_ERROR on failure, with details provided in the error
+ *      parameter.
+ */
+hs_error_t HS_CDECL hs_expression_info(const char *expression,
+                                       unsigned int flags,
+                                       hs_expr_info_t **info,
+                                       hs_compile_error_t **error);
+
+/**
+ * Utility function providing information about a regular expression, with
+ * extended parameter support. The information provided in @ref hs_expr_info_t
+ * includes the minimum and maximum width of a pattern match.
+ *
+ * Note: successful analysis of an expression with this function does not imply
+ * that compilation of the same expression (via @ref hs_compile(), @ref
+ * hs_compile_multi() or @ref hs_compile_ext_multi()) would succeed. This
+ * function may return @ref HS_SUCCESS for regular expressions that Hyperscan
+ * cannot compile.
+ *
+ * Note: some per-pattern flags (such as @ref HS_FLAG_ALLOWEMPTY, @ref
+ * HS_FLAG_SOM_LEFTMOST) are accepted by this call, but as they do not affect
+ * the properties returned in the @ref hs_expr_info_t structure, they will not
+ * affect the outcome of this function.
+ *
+ * @param expression
+ *      The NULL-terminated expression to parse. Note that this string must
+ *      represent ONLY the pattern to be matched, with no delimiters or flags;
+ *      any global flags should be specified with the @p flags argument.  For
+ *      example, the expression `/abc?def/i` should be compiled by providing
+ *      `abc?def` as the @p expression, and @ref HS_FLAG_CASELESS as the @a
+ *      flags.
+ *
+ * @param flags
+ *      Flags which modify the behaviour of the expression. Multiple flags may
+ *      be used by ORing them together. Valid values are:
+ *       - HS_FLAG_CASELESS - Matching will be performed case-insensitively.
+ *       - HS_FLAG_DOTALL - Matching a `.` will not exclude newlines.
+ *       - HS_FLAG_MULTILINE - `^` and `$` anchors match any newlines in data.
+ *       - HS_FLAG_SINGLEMATCH - Only one match will be generated by the
+ *                               expression per stream.
+ *       - HS_FLAG_ALLOWEMPTY - Allow expressions which can match against an
+ *                              empty string, such as `.*`.
+ *       - HS_FLAG_UTF8 - Treat this pattern as a sequence of UTF-8 characters.
+ *       - HS_FLAG_UCP - Use Unicode properties for character classes.
+ *       - HS_FLAG_PREFILTER - Compile pattern in prefiltering mode.
+ *       - HS_FLAG_SOM_LEFTMOST - Report the leftmost start of match offset
+ *                                when a match is found.
+ *       - HS_FLAG_COMBINATION - Parse the expression in logical combination
+ *                               syntax.
+ *       - HS_FLAG_QUIET - Ignore match reporting for this expression. Used for
+ *                         the sub-expressions in logical combinations.
+ *
+ * @param ext
+ *      A pointer to a filled @ref hs_expr_ext_t structure that defines
+ *      extended behaviour for this pattern. NULL may be specified if no
+ *      extended parameters are needed.
+ *
+ * @param info
+ *      On success, a pointer to the pattern information will be returned in
+ *      this parameter, or NULL on failure. This structure is allocated using
+ *      the allocator supplied in @ref hs_set_allocator() (or malloc() if no
+ *      allocator was set) and should be freed by the caller.
+ *
+ * @param error
+ *      If the call fails, a pointer to a @ref hs_compile_error_t will be
+ *      returned, providing details of the error condition. The caller is
+ *      responsible for deallocating the buffer using the @ref
+ *      hs_free_compile_error() function.
+ *
+ * @return
+ *      @ref HS_SUCCESS is returned on successful compilation; @ref
+ *      HS_COMPILER_ERROR on failure, with details provided in the error
+ *      parameter.
+ */
+hs_error_t HS_CDECL hs_expression_ext_info(const char *expression,
+                                           unsigned int flags,
+                                           const hs_expr_ext_t *ext,
+                                           hs_expr_info_t **info,
+                                           hs_compile_error_t **error);
+
+/**
+ * Populates the platform information based on the current host.
+ *
+ * @param platform
+ *      On success, the pointed to structure is populated based on the current
+ *      host.
+ *
+ * @return
+ *      @ref HS_SUCCESS on success, other values on failure.
+ */
+hs_error_t HS_CDECL hs_populate_platform(hs_platform_info_t *platform);
+
+/**
+ * @defgroup HS_PATTERN_FLAG Pattern flags
+ *
+ * @{
+ */
+
+/**
+ * Compile flag: Set case-insensitive matching.
+ *
+ * This flag sets the expression to be matched case-insensitively by default.
+ * The expression may still use PCRE tokens (notably `(?i)` and
+ * `(?-i)`) to switch case-insensitive matching on and off.
+ */
+#define HS_FLAG_CASELESS        1
+
+/**
+ * Compile flag: Matching a `.` will not exclude newlines.
+ *
+ * This flag sets any instances of the `.` token to match newline characters as
+ * well as all other characters. The PCRE specification states that the `.`
+ * token does not match newline characters by default, so without this flag the
+ * `.` token will not cross line boundaries.
+ */
+#define HS_FLAG_DOTALL          2
+
+/**
+ * Compile flag: Set multi-line anchoring.
+ *
+ * This flag instructs the expression to make the `^` and `$` tokens match
+ * newline characters as well as the start and end of the stream. If this flag
+ * is not specified, the `^` token will only ever match at the start of a
+ * stream, and the `$` token will only ever match at the end of a stream within
+ * the guidelines of the PCRE specification.
+ */
+#define HS_FLAG_MULTILINE       4
+
+/**
+ * Compile flag: Set single-match only mode.
+ *
+ * This flag sets the expression's match ID to match at most once. In streaming
+ * mode, this means that the expression will return only a single match over
+ * the lifetime of the stream, rather than reporting every match as per
+ * standard Hyperscan semantics. In block mode or vectored mode, only the first
+ * match for each invocation of @ref hs_scan() or @ref hs_scan_vector() will be
+ * returned.
+ *
+ * If multiple expressions in the database share the same match ID, then they
+ * either must all specify @ref HS_FLAG_SINGLEMATCH or none of them specify
+ * @ref HS_FLAG_SINGLEMATCH. If a group of expressions sharing a match ID
+ * specify the flag, then at most one match with the match ID will be generated
+ * per stream.
+ *
+ * Note: The use of this flag in combination with @ref HS_FLAG_SOM_LEFTMOST
+ * is not currently supported.
+ */
+#define HS_FLAG_SINGLEMATCH     8
+
+/**
+ * Compile flag: Allow expressions that can match against empty buffers.
+ *
+ * This flag instructs the compiler to allow expressions that can match against
+ * empty buffers, such as `.?`, `.*`, `(a|)`. Since Hyperscan can return every
+ * possible match for an expression, such expressions generally execute very
+ * slowly; the default behaviour is to return an error when an attempt to
+ * compile one is made. Using this flag will force the compiler to allow such
+ * an expression.
+ */
+#define HS_FLAG_ALLOWEMPTY      16
+
+/**
+ * Compile flag: Enable UTF-8 mode for this expression.
+ *
+ * This flag instructs Hyperscan to treat the pattern as a sequence of UTF-8
+ * characters. The results of scanning invalid UTF-8 sequences with a Hyperscan
+ * library that has been compiled with one or more patterns using this flag are
+ * undefined.
+ */
+#define HS_FLAG_UTF8            32
+
+/**
+ * Compile flag: Enable Unicode property support for this expression.
+ *
+ * This flag instructs Hyperscan to use Unicode properties, rather than the
+ * default ASCII interpretations, for character mnemonics like `\w` and `\s` as
+ * well as the POSIX character classes. It is only meaningful in conjunction
+ * with @ref HS_FLAG_UTF8.
+ */
+#define HS_FLAG_UCP             64
+
+/**
+ * Compile flag: Enable prefiltering mode for this expression.
+ *
+ * This flag instructs Hyperscan to compile an "approximate" version of this
+ * pattern for use in a prefiltering application, even if Hyperscan does not
+ * support the pattern in normal operation.
+ *
+ * The set of matches returned when this flag is used is guaranteed to be a
+ * superset of the matches specified by the non-prefiltering expression.
+ *
+ * If the pattern contains pattern constructs not supported by Hyperscan (such
+ * as zero-width assertions, back-references or conditional references) these
+ * constructs will be replaced internally with broader constructs that may
+ * match more often.
+ *
+ * Furthermore, in prefiltering mode Hyperscan may simplify a pattern that
+ * would otherwise return a "Pattern too large" error at compile time, or for
+ * performance reasons (subject to the matching guarantee above).
+ *
+ * It is generally expected that the application will subsequently confirm
+ * prefilter matches with another regular expression matcher that can provide
+ * exact matches for the pattern.
+ *
+ * Note: The use of this flag in combination with @ref HS_FLAG_SOM_LEFTMOST
+ * is not currently supported.
+ */
+#define HS_FLAG_PREFILTER       128
+
+/**
+ * Compile flag: Enable leftmost start of match reporting.
+ *
+ * This flag instructs Hyperscan to report the leftmost possible start of match
+ * offset when a match is reported for this expression. (By default, no start
+ * of match is returned.)
+ *
+ * For all the 3 modes, enabling this behaviour may reduce performance. And
+ * particularly, it may increase stream state requirements in streaming mode.
+ */
+#define HS_FLAG_SOM_LEFTMOST    256
+
+/**
+ * Compile flag: Logical combination.
+ *
+ * This flag instructs Hyperscan to parse this expression as logical
+ * combination syntax.
+ * Logical constraints consist of operands, operators and parentheses.
+ * The operands are expression indices, and operators can be
+ * '!'(NOT), '&'(AND) or '|'(OR).
+ * For example:
+ *     (101&102&103)|(104&!105)
+ *     ((301|302)&303)&(304|305)
+ */
+#define HS_FLAG_COMBINATION     512
+
+/**
+ * Compile flag: Don't do any match reporting.
+ *
+ * This flag instructs Hyperscan to ignore match reporting for this expression.
+ * It is designed to be used on the sub-expressions in logical combinations.
+ */
+#define HS_FLAG_QUIET           1024
+
+/** @} */
+
+/**
+ * @defgroup HS_CPU_FEATURES_FLAG CPU feature support flags
+ *
+ * @{
+ */
+
+/**
+ * CPU features flag - Intel(R) Advanced Vector Extensions 2 (Intel(R) AVX2)
+ *
+ * Setting this flag indicates that the target platform supports AVX2
+ * instructions.
+ */
+#define HS_CPU_FEATURES_AVX2             (1ULL << 2)
+
+/**
+ * CPU features flag - Intel(R) Advanced Vector Extensions 512 (Intel(R) AVX512)
+ *
+ * Setting this flag indicates that the target platform supports AVX512
+ * instructions, specifically AVX-512BW. Using AVX512 implies the use of AVX2.
+ */
+#define HS_CPU_FEATURES_AVX512           (1ULL << 3)
+
+/**
+ * CPU features flag - Intel(R) Advanced Vector Extensions 512
+ * Vector Byte Manipulation Instructions (Intel(R) AVX512VBMI)
+ *
+ * Setting this flag indicates that the target platform supports AVX512VBMI
+ * instructions. Using AVX512VBMI implies the use of AVX512.
+ */
+#define HS_CPU_FEATURES_AVX512VBMI       (1ULL << 4)
+
+/** @} */
+
+/**
+ * @defgroup HS_TUNE_FLAG Tuning flags
+ *
+ * @{
+ */
+
+/**
+ * Tuning Parameter - Generic
+ *
+ * This indicates that the compiled database should not be tuned for any
+ * particular target platform.
+ */
+#define HS_TUNE_FAMILY_GENERIC 0
+
+/**
+ * Tuning Parameter - Intel(R) microarchitecture code name Sandy Bridge
+ *
+ * This indicates that the compiled database should be tuned for the
+ * Sandy Bridge microarchitecture.
+ */
+#define HS_TUNE_FAMILY_SNB 1
+
+/**
+ * Tuning Parameter - Intel(R) microarchitecture code name Ivy Bridge
+ *
+ * This indicates that the compiled database should be tuned for the
+ * Ivy Bridge microarchitecture.
+ */
+#define HS_TUNE_FAMILY_IVB 2
+
+/**
+ * Tuning Parameter - Intel(R) microarchitecture code name Haswell
+ *
+ * This indicates that the compiled database should be tuned for the
+ * Haswell microarchitecture.
+ */
+#define HS_TUNE_FAMILY_HSW 3
+
+/**
+ * Tuning Parameter - Intel(R) microarchitecture code name Silvermont
+ *
+ * This indicates that the compiled database should be tuned for the
+ * Silvermont microarchitecture.
+ */
+#define HS_TUNE_FAMILY_SLM 4
+
+/**
+ * Tuning Parameter - Intel(R) microarchitecture code name Broadwell
+ *
+ * This indicates that the compiled database should be tuned for the
+ * Broadwell microarchitecture.
+ */
+#define HS_TUNE_FAMILY_BDW 5
+
+/**
+ * Tuning Parameter - Intel(R) microarchitecture code name Skylake
+ *
+ * This indicates that the compiled database should be tuned for the
+ * Skylake microarchitecture.
+ */
+#define HS_TUNE_FAMILY_SKL 6
+
+/**
+ * Tuning Parameter - Intel(R) microarchitecture code name Skylake Server
+ *
+ * This indicates that the compiled database should be tuned for the
+ * Skylake Server microarchitecture.
+ */
+#define HS_TUNE_FAMILY_SKX 7
+
+/**
+ * Tuning Parameter - Intel(R) microarchitecture code name Goldmont
+ *
+ * This indicates that the compiled database should be tuned for the
+ * Goldmont microarchitecture.
+ */
+#define HS_TUNE_FAMILY_GLM 8
+
+/**
+ * Tuning Parameter - Intel(R) microarchitecture code name Icelake
+ *
+ * This indicates that the compiled database should be tuned for the
+ * Icelake microarchitecture.
+ */
+#define HS_TUNE_FAMILY_ICL 9
+
+/**
+ * Tuning Parameter - Intel(R) microarchitecture code name Icelake Server
+ *
+ * This indicates that the compiled database should be tuned for the
+ * Icelake Server microarchitecture.
+ */
+#define HS_TUNE_FAMILY_ICX 10
+
+/** @} */
+
+/**
+ * @defgroup HS_MODE_FLAG Compile mode flags
+ *
+ * The mode flags are used as values for the mode parameter of the various
+ * compile calls (@ref hs_compile(), @ref hs_compile_multi() and @ref
+ * hs_compile_ext_multi()).
+ *
+ * A mode value can be built by ORing these flag values together; the only
+ * required flag is one of @ref HS_MODE_BLOCK, @ref HS_MODE_STREAM or @ref
+ * HS_MODE_VECTORED. Other flags may be added to enable support for additional
+ * features.
+ *
+ *  @{
+ */
+
+/**
+ * Compiler mode flag: Block scan (non-streaming) database.
+ */
+#define HS_MODE_BLOCK           1
+
+/**
+ * Compiler mode flag: Alias for @ref HS_MODE_BLOCK.
+ */
+#define HS_MODE_NOSTREAM        1
+
+/**
+ * Compiler mode flag: Streaming database.
+ */
+#define HS_MODE_STREAM          2
+
+/**
+ * Compiler mode flag: Vectored scanning database.
+ */
+#define HS_MODE_VECTORED        4
+
+/**
+ * Compiler mode flag: use full precision to track start of match offsets in
+ * stream state.
+ *
+ * This mode will use the most stream state per pattern, but will always return
+ * an accurate start of match offset regardless of how far back in the past it
+ * was found.
+ *
+ * One of the SOM_HORIZON modes must be selected to use the @ref
+ * HS_FLAG_SOM_LEFTMOST expression flag.
+ */
+#define HS_MODE_SOM_HORIZON_LARGE   (1U << 24)
+
+/**
+ * Compiler mode flag: use medium precision to track start of match offsets in
+ * stream state.
+ *
+ * This mode will use less stream state than @ref HS_MODE_SOM_HORIZON_LARGE and
+ * will limit start of match accuracy to offsets within 2^32 bytes of the
+ * end of match offset reported.
+ *
+ * One of the SOM_HORIZON modes must be selected to use the @ref
+ * HS_FLAG_SOM_LEFTMOST expression flag.
+ */
+#define HS_MODE_SOM_HORIZON_MEDIUM  (1U << 25)
+
+/**
+ * Compiler mode flag: use limited precision to track start of match offsets in
+ * stream state.
+ *
+ * This mode will use less stream state than @ref HS_MODE_SOM_HORIZON_LARGE and
+ * will limit start of match accuracy to offsets within 2^16 bytes of the
+ * end of match offset reported.
+ *
+ * One of the SOM_HORIZON modes must be selected to use the @ref
+ * HS_FLAG_SOM_LEFTMOST expression flag.
+ */
+#define HS_MODE_SOM_HORIZON_SMALL   (1U << 26)
+
+/** @} */
+
+#ifdef __cplusplus
+} /* extern "C" */
+#endif
+
+#endif /* HS_COMPILE_H_ */