1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
|
.. -*- rst -*-
.. groonga-command
.. database: functions_string_slice
``string_slice``
================
.. versionadded:: 11.0.3
Summary
-------
``string_slice`` extracts a substring of a string. You can use two different extraction methods depending on the arguments.
* Extraction by position
* Extraction by regular expression
Groonga uses the same regular expression syntax in Ruby.
To enable this function, register ``functions/string`` plugin by following the command::
plugin_register functions/string
Syntax
------
``string_slice`` requires two to four parameters. The required parameters are depending on the extraction method.
Extraction by position
^^^^^^^^^^^^^^^^^^^^^^
::
string_slice(target, nth[, options])
string_slice(target, nth, length[, options])
``options`` uses the following format. All of key-value pairs are optional::
{
"default_value": default_value
}
Extraction by regular expression
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
::
string_slice(target, regexp, nth[, options])
string_slice(target, regexp, name[, options])
``options`` uses the following format. All of key-value pairs are optional::
{
"default_value": default_value
}
Usage
-----
Here are a schema definition and sample data to show usage.
Sample schema:
.. groonga-command
.. include:: ../../example/reference/functions/string_slice/usage_setup_schema.log
.. plugin_register functions/string
.. table_create Memos TABLE_HASH_KEY ShortText
Sample data:
.. groonga-command
.. include:: ../../example/reference/functions/string_slice/usage_setup_data.log
.. load --table Memos
.. [
.. {"_key": "Groonga"}
.. ]
Here is a simple example for the extraction by position.
.. groonga-command
.. include:: ../../example/reference/functions/string_slice/usage_number.log
.. select Memos --output_columns '_key, string_slice(_key, 2, 3)'
Here are simple examples for the extraction by regular expression.
In the following example, extracting by specifying the group number of the capturing group: ``(subexp)``.
.. groonga-command
.. include:: ../../example/reference/functions/string_slice/usage_regexp_number.log
.. select Memos --output_columns '_key, string_slice(_key, "(Gro+)(.*)", 2)'
In the following example, extracting by specifying the name of the named capturing group: ``(?<name>subexp)``.
.. groonga-command
.. include:: ../../example/reference/functions/string_slice/usage_regexp_name.log
.. select Memos --output_columns '_key, string_slice(_key, "(Gr)(?<Name1>o*)(?<Name2>.*)", "Name1")'
In the following example, specifying the default value.
.. groonga-command
.. include:: ../../example/reference/functions/string_slice/usage_regexp_default.log
.. select Memos --output_columns '_key, string_slice(_key, "mismatch", 2, { "default_value" : "default" })'
You can specify string literal instead of column.
.. groonga-command
.. include:: ../../example/reference/functions/string_slice/usage_string_literal.log
.. select Memos --output_columns 'string_slice("Groonga", "(roon)(g)", 2)'
Parameters
----------
Extraction by position
^^^^^^^^^^^^^^^^^^^^^^
There are two required parameters, ``target`` and ``nth``.
There are two optional parameters, ``length`` and ``options``.
``target``
~~~~~~~~~~
Specify a string literal or a string type column.
``nth``
~~~~~~~
Specify a 0-based index number of charactors where to start the extraction from ``target``.
If you specify a negative value, it counts from the end of ``target``.
``length``
~~~~~~~~~~
Specify a number of characters to extract from ``nth``.
The default is 1.
``options``
~~~~~~~~~~~
Specify the following key.
``default_value``
Specify a string to be returned when a substring is an empty string except when specifying 0 for ``length``.
The default is an empty string.
Extraction by regular expression
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
There are three required parameters, ``target`` and ``regexp`` and ``nth`` or ``name``. Specify either ``nth`` or ``name``.
There is one optional parameter, ``options``.
``target``
~~~~~~~~~~
Specify a string literal or a string type column.
``regexp``
~~~~~~~~~~
Specify a regular expression string.
When you use ``nth`` and specify a value greater than 0, you must use capturing group: ``(subexp)``.
When you use ``name``, you must use named capturing group: ``(?<name>subexp)``, ``(?'name'subexp)``.
``nth``
~~~~~~~
Specify a number of the capturing group for ``regexp``.
A captured string of the ``nth`` capturing group is returned when ``regexp`` is matched to ``target``.
If 0 is specified for ``nth``, the entire string that matches ``regexp`` is returned.
Specify either ``nth`` or ``name``.
``name``
~~~~~~~~
Specify a name of the named capturing group for ``regexp``.
A captured string of the named capturing group that matches ``name`` is returned
when ``regexp`` is matched to ``target``.
Specify either ``nth`` or ``name``.
``options``
~~~~~~~~~~~
Specify the following key.
``default_value``
Specify a string returned if ``regexp`` does not match to ``target``.
This value also be returned when the value of ``nth`` or ``name`` is incorrect.
The default is an empty string.
Return value
------------
``string_slice`` returns a substring extracted under the specified conditions from ``target``.
|
