style_expression.h File Reference

Go to the source code of this file.

Data Structures
struct	mln_style_expression_type
struct	mln_style_expression_options
struct	mln_style_expression_inputs
struct	mln_style_expression_info

Typedefs
typedef enum mln_style_expression_type_kind	mln_style_expression_type_kind
typedef struct mln_style_expression_type	mln_style_expression_type
typedef enum mln_style_expression_option_field	mln_style_expression_option_field
typedef struct mln_style_expression_options	mln_style_expression_options
typedef enum mln_style_expression_input_field	mln_style_expression_input_field
typedef struct mln_style_expression_inputs	mln_style_expression_inputs
typedef struct mln_style_expression_info	mln_style_expression_info

Enumerations
enum	mln_style_expression_type_kind : uint32_t { MLN_STYLE_EXPRESSION_TYPE_VALUE = 0 , MLN_STYLE_EXPRESSION_TYPE_NUMBER = 1 , MLN_STYLE_EXPRESSION_TYPE_STRING = 2 , MLN_STYLE_EXPRESSION_TYPE_BOOLEAN = 3 , MLN_STYLE_EXPRESSION_TYPE_COLOR = 4 , MLN_STYLE_EXPRESSION_TYPE_OBJECT = 5 , MLN_STYLE_EXPRESSION_TYPE_FORMATTED = 6 , MLN_STYLE_EXPRESSION_TYPE_IMAGE = 7 , MLN_STYLE_EXPRESSION_TYPE_PADDING = 8 , MLN_STYLE_EXPRESSION_TYPE_VARIABLE_ANCHOR_OFFSET_COLLECTION = 9 , MLN_STYLE_EXPRESSION_TYPE_ARRAY = 10 }
enum	mln_style_expression_option_field : uint32_t { MLN_STYLE_EXPRESSION_OPTION_EXPECTED_TYPE = 1U << 0U }
enum	mln_style_expression_input_field : uint32_t

Functions
mln_style_expression_options	mln_style_expression_options_default (void)
mln_style_expression_inputs	mln_style_expression_inputs_default (void)
mln_status	mln_style_expression_create (mln_buffer_view expression, const mln_style_expression_options *options, mln_style_expression *out_expression, mln_diagnostic *out_diagnostic)
void	mln_style_expression_release (mln_style_expression expression)
mln_status	mln_style_expression_get_info (mln_style_expression expression, mln_style_expression_info *out_info, mln_diagnostic *out_diagnostic)
mln_status	mln_style_expression_evaluate (mln_style_expression expression, const mln_style_expression_inputs *inputs, char *out_json, size_t json_capacity, size_t *out_json_length, mln_diagnostic *out_diagnostic)

Detailed Description

Public C API declarations for evaluating style expressions without a map.

An expression parses once into an immutable handle that evaluates against caller-supplied inputs, the way a layer evaluates it while it renders. It needs no runtime, map, or render session, and every declaration in this header is synchronous and callable from any thread.

Typedef Documentation

mln_style_expression_info

typedef struct mln_style_expression_info mln_style_expression_info

What a parsed expression depends on.

mln_style_expression_input_field

typedef enum mln_style_expression_input_field mln_style_expression_input_field

Fields present in mln_style_expression_inputs.

mln_style_expression_inputs

typedef struct mln_style_expression_inputs mln_style_expression_inputs

What one evaluation reads.

An input whose field bit is clear is absent. An expression that needs the zoom, feature data, or the color ramp parameter fails to evaluate without it, and an absent state reads as null.

mln_style_expression_option_field

typedef enum mln_style_expression_option_field mln_style_expression_option_field

Fields present in mln_style_expression_options.

mln_style_expression_options

typedef struct mln_style_expression_options mln_style_expression_options

Options for parsing a style expression.

mln_style_expression_type

typedef struct mln_style_expression_type mln_style_expression_type

A style expression type.

mln_style_expression_type_kind

typedef enum mln_style_expression_type_kind mln_style_expression_type_kind

Style expression types that a parsed expression may be required to have.

Enumeration Type Documentation

mln_style_expression_input_field

enum mln_style_expression_input_field : uint32_t

Fields present in mln_style_expression_inputs.

mln_style_expression_option_field

enum mln_style_expression_option_field : uint32_t

Fields present in mln_style_expression_options.

Enumerator
MLN_STYLE_EXPRESSION_OPTION_EXPECTED_TYPE	expected_type is set.

mln_style_expression_type_kind

enum mln_style_expression_type_kind : uint32_t

Style expression types that a parsed expression may be required to have.

Enumerator
MLN_STYLE_EXPRESSION_TYPE_VALUE	Any value.
MLN_STYLE_EXPRESSION_TYPE_IMAGE	A resolved image, as the image expression returns.
MLN_STYLE_EXPRESSION_TYPE_ARRAY	An array whose items have item_kind, which is not itself an array.

Function Documentation

mln_style_expression_create()

mln_status mln_style_expression_create	(	mln_buffer_view	expression,
		const mln_style_expression_options *	options,
		mln_style_expression *	out_expression,
		mln_diagnostic *	out_diagnostic )

Parses a style expression.

expression is UTF-8 MapLibre style-spec expression JSON, such as ["get", "name"] or a literal value. Parsing follows MapLibre GL JS createExpression() and checks the result against options->expected_type when it is set. An expression whose result is a collator has no JSON form, so it is rejected.

*out_expression must be MLN_HANDLE_NULL on entry. On success it receives an owned handle the host releases with mln_style_expression_release().

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when expression is empty or not valid JSON, options is undersized, carries unknown fields, or names an unknown type kind or an array of arrays, out_expression is null or *out_expression is not MLN_HANDLE_NULL, or the expression does not parse. The diagnostic lists each parse error with its location in the expression.
• MLN_STATUS_NATIVE_ERROR when native code fails.

mln_style_expression_evaluate()

mln_status mln_style_expression_evaluate	(	mln_style_expression	expression,
		const mln_style_expression_inputs *	inputs,
		char *	out_json,
		size_t	json_capacity,
		size_t *	out_json_length,
		mln_diagnostic *	out_diagnostic )

Evaluates a parsed expression and writes its result as UTF-8 JSON.

A null inputs sets no input. A color serializes as an ["rgba", r, g, b, a] array, a formatted value as the format expression that makes it, and an image as an object with its name and whether it is available. A number that is not finite serializes as null, as JSON.stringify() writes it.

*out_json_length receives the result's length in bytes, without a null terminator. When json_capacity exceeds that length, out_json receives the result and a null terminator; otherwise out_json is unchanged, and a caller evaluates again with at least *out_json_length + 1 bytes. out_json may be null when json_capacity is zero. Evaluation reads only its inputs, so the same inputs produce the same result.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when expression is an invalid handle; inputs is undersized, carries unknown fields, or sets a number that is not finite, a feature that is not one GeoJSON Feature, a state that is not a JSON object, a tile ID outside its zoom, or available_images that is null with a nonzero count; out_json is null with a nonzero json_capacity; out_json_length is null; or the expression fails to evaluate against the inputs, which the diagnostic describes.
• MLN_STATUS_INVALID_STATE when expression has been released.
• MLN_STATUS_NATIVE_ERROR when native code fails.

mln_style_expression_get_info()

mln_status mln_style_expression_get_info	(	mln_style_expression	expression,
		mln_style_expression_info *	out_info,
		mln_diagnostic *	out_diagnostic )

Copies what a parsed expression depends on into out_info.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when expression is an invalid handle, or out_info is null or undersized.
• MLN_STATUS_INVALID_STATE when expression has been released.
• MLN_STATUS_NATIVE_ERROR when native code fails.

mln_style_expression_inputs_default()

mln_style_expression_inputs mln_style_expression_inputs_default

(

void

)

Returns default style expression inputs, which set no input.

mln_style_expression_options_default()

mln_style_expression_options mln_style_expression_options_default

(

void

)

Returns default style expression options.

mln_style_expression_release()

void mln_style_expression_release

(

mln_style_expression

expression

)

Releases a style expression.

An evaluation already running on another thread keeps the expression until it returns. A null or already-released handle is a no-op.