Skip to content

Commit

Permalink
Add new expression functions
Browse files Browse the repository at this point in the history
  • Loading branch information
@DelazJ
DelazJ committed Apr 19, 2017
1 parent 0bc95d1 commit 5329562
Showing 1 changed file with 141 additions and 6 deletions.
147 changes: 141 additions & 6 deletions source/docs/user_manual/working_with_vector/expression.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -208,8 +208,6 @@ This group contains functions to handle conditional checks in expressions.
if Tests a condition and returns a
different result depending on the
conditional check
regexp_match Returns true if any part of a string
matches the supplied regular expression
===================================== =========================================

**Some example:**
Expand Down Expand Up @@ -276,6 +274,8 @@ This group contains functions which aggregate values over layers and fields.
====================== =======================================================
aggregate Returns an aggregate value calculated using
features from another layer
collect Returns the multipart geometry of aggregated
geometries from an expression
concatenate Returns the all aggregated strings from a field
or expression joined by a delimiter
count Returns the count of matching features
Expand Down Expand Up @@ -337,6 +337,41 @@ This group contains functions which aggregate values over layers and fields.
expression := "field_from_related_table")


Array Functions
---------------

This group contains functions to create and manipulate arrays.

====================== =======================================================
Function Description
====================== =======================================================
array Returns an array containing all the values passed
as parameter
array_append Returns an array with the given value added at the end
array_cat Returns an array containing all the given arrays concatenated
array_contains Returns true if an array contains the given value
array_distinct Returns an array containing distinct values of the given array
array_find Returns the index (0 for the first one) of a value
within an array. Returns -1 if the value is not found.
array_get Returns the Nth value (0 for the first one) of an array
array_insert Returns an array with the given value added at the
given position
array_intersect Returns true if any element of array1 exists in array2
array_length Returns the number of elements of an array
array_prepend Returns an array with the given value added at the beginning
array_remove_all Returns an array with all the entries of the given
value removed
array_remove_at Returns an array with the given index removed
array_to_string Concatenates array elements into a string separated by
a delimiter using and optional string for empty values.
regexp_matches Returns an array of all strings captured by capturing
groups, in the order the groups themselves appear in
the supplied regular expression against a string.
string_to_array Splits string into an array using supplied delimiter
and optional string for empty values
====================== =======================================================


Color Functions
----------------

Expand Down Expand Up @@ -374,6 +409,26 @@ This group contains functions for manipulating colors.
eg the red component or alpha component
================== ==========================================================


Composition Functions
---------------------

This group contains functions to manipulate print composer items properties.

================== ========================================================
Function Description
================== ========================================================
item_variables Returns a map of variables from a composer item inside
this composition
================== ========================================================

**Some example:**

* Get the scale of the 'Map 0' in the current print composer::

map_get( item_variables('Map 0'), 'map_scale')


.. _conversion_functions:

Conversions Functions
Expand Down Expand Up @@ -417,6 +472,8 @@ This group contains functions for handling date and time data.
of days from an interval
day_of_week Returns a number corresponding to the day of the week
for a specified date or datetime
epoch Returns the interval in milliseconds between the unix
epoch and a given date value
hour Extracts the hour from a datetime or time,
or the number of hours from an interval
minute Extracts the minute from a datetime or time,
Expand Down Expand Up @@ -539,12 +596,17 @@ This group contains general assorted functions.
==================== =======================================================
Function Description
==================== =======================================================
env Gets an environment variable and returns its content
as a string. If the variable is not found, ``NULL``
will be returned.
eval Evaluates an expression which is passed in a string.
Useful to expand dynamic parameters passed as context
variables or fields
is_layer_visible Returns true if a specified layer is visible
layer_property Returns a property of a layer or a value of its
metadata. It can be layer name, crs, geometry type,
feature count...
raster_statistic Returns statistics from a raster layer
var Returns the value stored within a specified
variable. See variable functions below
==================== =======================================================
Expand Down Expand Up @@ -645,6 +707,9 @@ This group contains functions that operate on geometry objects (e.g., length, ar
+------------------------+---------------------------------------------------+
| end_point | Returns the last node from a geometry |
+------------------------+---------------------------------------------------+
| extend | Extends the start and end of a linestring |
| | geometry by a specified amount |
+------------------------+---------------------------------------------------+
| exterior_ring | Returns a line string representing the exterior |
| | ring of a polygon geometry, |
| | or null if the geometry is not a polygon |
Expand Down Expand Up @@ -741,6 +806,10 @@ This group contains functions that operate on geometry objects (e.g., length, ar
| | null if the input geometry is not a polygon or |
| | collection |
+------------------------+---------------------------------------------------+
| offset_curve | Returns a geometry formed by offsetting a |
| | linestring geometry to the side. Distances are in |
| | the Spatial Reference System of this geometry. |
+------------------------+---------------------------------------------------+
| order_parts | Orders the parts of a MultiGeometry by a given |
| | criteria |
+------------------------+---------------------------------------------------+
Expand All @@ -758,6 +827,10 @@ This group contains functions that operate on geometry objects (e.g., length, ar
| point_on_surface | Returns a point guaranteed to lie on the surface |
| | of a geometry |
+------------------------+---------------------------------------------------+
| pole_of_inaccessibility| Calculates the approximate pole of inaccessibility|
| | for a surface, which is the most distant internal |
| | point from the boundary of the surface |
+------------------------+---------------------------------------------------+
| project | Returns a point projected from a start point |
| | using a distance and bearing (azimuth) in radians |
+------------------------+---------------------------------------------------+
Expand All @@ -775,6 +848,19 @@ This group contains functions that operate on geometry objects (e.g., length, ar
| | The resultant line will start at geometry 1 and |
| | end at geometry 2 |
+------------------------+---------------------------------------------------+
| simplify | Simplifies a geometry by removing nodes using a |
| | distance based threshold |
+------------------------+---------------------------------------------------+
| simplify_vw | Simplifies a geometry by removing nodes using an |
| | area based threshold |
+------------------------+---------------------------------------------------+
| single_sided_buffer | Returns a geometry formed by buffering out just |
| | one side of a linestring geometry. Distances are |
| | in the Spatial Reference System of this geometry |
+------------------------+---------------------------------------------------+
| smooth | Smooths a geometry by adding extra nodes which |
| | round off corners in the geometry |
+------------------------+---------------------------------------------------+
| start_point | Returns the first node from a geometry |
+------------------------+---------------------------------------------------+
| sym_difference | Returns a geometry that represents the portions |
Expand Down Expand Up @@ -836,6 +922,30 @@ This group contains functions that operate on geometry objects (e.g., length, ar

CASE WHEN $area > 10 000 THEN 'Larger' ELSE 'Smaller' END


Map Functions
--------------

This group contains functions to create or manipulate keys and values of maps.

==================== =========================================================
Function Description
==================== =========================================================
map Returns a map containing all the keys and values passed
as pair of parameters
map_akeys Returns all the keys of a map as an array
map_avals Returns all the values of a map as an array
map_concat Returns a map containing all the entries of the given
maps. If two maps contain the same key, the value of
the second map is taken.
map_delete Returns a map with the given key and its corresponding
value deleted
map_exist Returns true if the given key exists in the map
map_get Returns the value of a map, given it's key
map_insert Returns a map with an added key/value
==================== =========================================================


Record Functions
-----------------

Expand All @@ -857,6 +967,8 @@ This group contains functions that operate on record identifiers.
feature
get_feature Returns the first feature of a layer matching a
given attribute value
is_selected Returns if a feature is selected
num_selected Returns the number of selected features on a given layer
uuid Generates a Universally Unique Identifier (UUID)
for each row. Each UUID is 38 characters long.
==================== =========================================================
Expand Down Expand Up @@ -899,18 +1011,22 @@ This group contains functions that operate on strings
lower converts a string to lower case
lpad Returns a string with supplied width padded
using the fill character
regexp_match Returns the first matching position matching a regular
expression within a string, or 0 if the substring is
not found
regexp_replace Returns a string with the supplied regular
expression replaced
regexp_substr Returns the portion of a string which matches
a supplied regular expression
replace Returns a string with the supplied string
replaced
replace Returns a string with the supplied string, array, or
map of strings replaced by a string, an array of strings
or paired values
right(string, n) Returns a substring that contains the n
rightmost characters of the string
rpad Returns a string with supplied width padded
using the fill character
strpos Returns the index of a regular expression
in a string
strpos Returns the first matching position of a substring within
another string, or 0 if the substring is not found
substr Returns a part of a string
title Converts all words of a string to title
case (all words lower case with leading
Expand Down Expand Up @@ -957,18 +1073,31 @@ To use these functions in an expression, they should be preceded by @ character
atlas_geometry Returns the current atlas feature geometry
atlas_pagename Returns the current atlas page name
atlas_totalfeatures Returns the total number of features in atlas
cluster_color Returns the color of symbols within a cluster, or NULL
if symbols have mixed colors
cluster_size Returns the number of symbols contained within a cluster
geometry_part_count Returns the number of parts in rendered feature's geometry
geometry_part_num Returns the current geometry part number for feature being rendered
geometry_point_count Returns the number of points in the rendered geometry's part
geometry_point_num Returns the current point number in the rendered geometry's part
grid_axis Returns the current grid annotation axis
(eg, 'x' for longitude, 'y' for latitude)
grid_number Returns the current grid annotation value
item_id Returns the composer item user ID
(not necessarily unique)
item_uuid Returns the composer item unique ID
layer Returns the current layer
layer_id Returns the ID of current layer
layer_name Returns the name of current layer
layout_dpi Returns the composition resolution (DPI)
layout_numpages Returns the number of pages in the composition
layout_page Returns the current page of the composer item
layout_pageheight Returns the composition height in mm
layout_pagewidth Returns the composition width in mm
map_crs Returns the Coordinate reference system of the current map
map_crs_definition Returns the full definition of the Coordinate reference
system of the current map
map_extent Returns the geometry representing the current extent of the map
map_extent_center Returns the point feature at the center of the map
map_extent_height Returns the current height of the map
map_extent_width Returns the current width of the map
Expand All @@ -977,15 +1106,21 @@ To use these functions in an expression, they should be preceded by @ character
the item ID for composer map renders
map_rotation Returns the current rotation of the map
map_scale Returns the current scale of the map
map_units Returns the units of map measurements
project_crs Returns the Coordinate reference system of the project
project_crs_definition Returns the full definition of the Coordinate reference
system of the project
project_filename Returns the filename of current project
project_folder Returns the folder for current project
project_path Returns the full path (including file name)
of current project
project_title Returns the title of current project
qgis_locale Returns the current language of QGIS
qgis_os_name Returns the current Operating system name,
eg 'windows', 'linux' or 'osx'
qgis_platform Returns QGIS platform, eg 'desktop' or 'server'
qgis_release_name Returns current QGIS release name
qgis_short_version Returns current QGIS version short string
qgis_version Returns current QGIS version string
qgis_version_no Returns current QGIS version number
symbol_angle Returns the angle of the symbol used to render
Expand Down

0 comments on commit 5329562

Please sign in to comment.