1"""sqlglot expressions - string, encoding, hashing, and regex functions."""
  2
  3from __future__ import annotations
  4
  5from sqlglot.expressions.core import Expression, Func, Binary, Predicate
  6
  7
  8# String basics
  9
 10
 11class Ascii(Expression, Func):
 12    pass
 13
 14
 15class BitLength(Expression, Func):
 16    pass
 17
 18
 19class ByteLength(Expression, Func):
 20    pass
 21
 22
 23class Chr(Expression, Func):
 24    arg_types = {"expressions": True, "charset": False}
 25    is_var_len_args = True
 26    _sql_names = ["CHR", "CHAR"]
 27
 28
 29class Concat(Expression, Func):
 30    arg_types = {"expressions": True, "safe": False, "coalesce": False}
 31    is_var_len_args = True
 32
 33
 34class ConcatWs(Concat):
 35    arg_types = {**Concat.arg_types, "flatten": False}
 36    _sql_names = ["CONCAT_WS"]
 37
 38
 39class Contains(Expression, Func):
 40    arg_types = {"this": True, "expression": True, "json_scope": False}
 41
 42
 43class Elt(Expression, Func):
 44    arg_types = {"this": True, "expressions": True}
 45    is_var_len_args = True
 46
 47
 48class EndsWith(Expression, Func):
 49    _sql_names = ["ENDS_WITH", "ENDSWITH"]
 50    arg_types = {"this": True, "expression": True}
 51
 52
 53class Format(Expression, Func):
 54    arg_types = {"this": True, "expressions": False}
 55    is_var_len_args = True
 56
 57
 58class Initcap(Expression, Func):
 59    arg_types = {"this": True, "expression": False}
 60
 61
 62class IsAscii(Expression, Func):
 63    pass
 64
 65
 66class Left(Expression, Func):
 67    arg_types = {"this": True, "expression": True, "negative_length_returns_empty": False}
 68
 69
 70class Length(Expression, Func):
 71    arg_types = {"this": True, "binary": False, "encoding": False}
 72    _sql_names = ["LENGTH", "LEN", "CHAR_LENGTH", "CHARACTER_LENGTH"]
 73
 74
 75class Levenshtein(Expression, Func):
 76    arg_types = {
 77        "this": True,
 78        "expression": False,
 79        "ins_cost": False,
 80        "del_cost": False,
 81        "sub_cost": False,
 82        "max_dist": False,
 83    }
 84
 85
 86class Lower(Expression, Func):
 87    _sql_names = ["LOWER", "LCASE"]
 88
 89
 90class MatchAgainst(Expression, Func):
 91    arg_types = {"this": True, "expressions": True, "modifier": False}
 92
 93
 94class Normalize(Expression, Func):
 95    arg_types = {"this": True, "form": False, "is_casefold": False}
 96
 97
 98class NumberToStr(Expression, Func):
 99    arg_types = {"this": True, "format": True, "culture": False}
100
101
102class Overlay(Expression, Func):
103    arg_types = {"this": True, "expression": True, "from_": True, "for_": False}
104
105
106class Pad(Expression, Func):
107    arg_types = {"this": True, "expression": True, "fill_pattern": False, "is_left": True}
108
109
110class Repeat(Expression, Func):
111    arg_types = {"this": True, "times": True}
112
113
114class Replace(Expression, Func):
115    arg_types = {"this": True, "expression": True, "replacement": False}
116
117
118class Reverse(Expression, Func):
119    pass
120
121
122class Right(Expression, Func):
123    arg_types = {"this": True, "expression": True, "negative_length_returns_empty": False}
124
125
126class RtrimmedLength(Expression, Func):
127    pass
128
129
130class Search(Expression, Func):
131    arg_types = {
132        "this": True,  # data_to_search / search_data
133        "expression": True,  # search_query / search_string
134        "json_scope": False,  # BigQuery: JSON_VALUES | JSON_KEYS | JSON_KEYS_AND_VALUES
135        "analyzer": False,  # Both: analyzer / ANALYZER
136        "analyzer_options": False,  # BigQuery: analyzer_options_values
137        "search_mode": False,  # Snowflake: OR | AND
138    }
139
140
141class SearchIp(Expression, Func):
142    arg_types = {"this": True, "expression": True}
143
144
145class Secret(Expression, Func):
146    arg_types = {"this": True, "expression": True}
147
148
149class Soundex(Expression, Func):
150    pass
151
152
153class SoundexP123(Expression, Func):
154    pass
155
156
157class Space(Expression, Func):
158    """
159    SPACE(n) → string consisting of n blank characters
160    """
161
162    pass
163
164
165class Split(Expression, Func):
166    arg_types = {
167        "this": True,
168        "expression": True,
169        "limit": False,
170        "null_returns_null": False,
171        "empty_delimiter_returns_whole": False,
172    }
173
174
175class SplitPart(Expression, Func):
176    arg_types = {
177        "this": True,
178        "delimiter": False,
179        "part_index": False,
180        "part_index_zero_as_one": False,  # usually part_index is 1-based, however Snowflake allows 0 and treats it as 1
181        "empty_delimiter_returns_whole": False,  # whether the whole input string should be returned if the delimiter string is empty (i.e. Snowflake)
182    }
183
184
185class Strtok(Expression, Func):
186    arg_types = {
187        "this": True,
188        "delimiter": False,
189        "part_index": False,
190    }
191
192
193class StartsWith(Expression, Func):
194    _sql_names = ["STARTS_WITH", "STARTSWITH"]
195    arg_types = {"this": True, "expression": True}
196
197
198class StrPosition(Expression, Func):
199    arg_types = {
200        "this": True,
201        "substr": True,
202        "position": False,
203        "occurrence": False,
204        "clamp_position": False,
205    }
206
207
208class StrToMap(Expression, Func):
209    arg_types = {
210        "this": True,
211        "pair_delim": False,
212        "key_value_delim": False,
213        "duplicate_resolution_callback": False,
214    }
215
216
217class String(Expression, Func):
218    arg_types = {"this": True, "zone": False}
219
220
221class Stuff(Expression, Func):
222    _sql_names = ["STUFF", "INSERT"]
223    arg_types = {"this": True, "start": True, "length": True, "expression": True}
224
225
226class Substring(Expression, Func):
227    _sql_names = ["SUBSTRING", "SUBSTR"]
228    arg_types = {"this": True, "start": False, "length": False, "zero_start": False}
229
230
231class SubstringIndex(Expression, Func):
232    """
233    SUBSTRING_INDEX(str, delim, count)
234
235    *count* > 0  → left slice before the *count*-th delimiter
236    *count* < 0  → right slice after the |count|-th delimiter
237    """
238
239    arg_types = {"this": True, "delimiter": True, "count": True}
240
241
242class Translate(Expression, Func):
243    arg_types = {"this": True, "from_": True, "to": True}
244
245
246class Trim(Expression, Func):
247    arg_types = {
248        "this": True,
249        "expression": False,
250        "position": False,
251        "collation": False,
252    }
253
254
255class Unicode(Expression, Func):
256    arg_types = {"this": True, "empty_is_zero": False}
257
258
259class Upper(Expression, Func):
260    _sql_names = ["UPPER", "UCASE"]
261
262
263# Encoding / base conversion
264
265
266class Base64DecodeBinary(Expression, Func):
267    arg_types = {"this": True, "alphabet": False}
268
269
270class Base64DecodeString(Expression, Func):
271    arg_types = {"this": True, "alphabet": False}
272
273
274class Base64Encode(Expression, Func):
275    arg_types = {"this": True, "max_line_length": False, "alphabet": False}
276
277
278class CodePointsToBytes(Expression, Func):
279    pass
280
281
282class CodePointsToString(Expression, Func):
283    pass
284
285
286class ConvertToCharset(Expression, Func):
287    arg_types = {"this": True, "dest": True, "source": False}
288
289
290class Decode(Expression, Func):
291    arg_types = {"this": True, "charset": True, "replace": False}
292
293
294class Encode(Expression, Func):
295    arg_types = {"this": True, "charset": True}
296
297
298class FromBase(Expression, Func):
299    arg_types = {"this": True, "expression": True}
300
301
302class FromBase32(Expression, Func):
303    pass
304
305
306class FromBase64(Expression, Func):
307    pass
308
309
310class Hex(Expression, Func):
311    arg_types = {"this": True, "case": False}
312
313
314class HexDecodeString(Expression, Func):
315    pass
316
317
318class LowerHex(Hex):
319    pass
320
321
322class SafeConvertBytesToString(Expression, Func):
323    pass
324
325
326class ToBase32(Expression, Func):
327    pass
328
329
330class ToBase64(Expression, Func):
331    pass
332
333
334class ToBinary(Expression, Func):
335    arg_types = {"this": True, "format": False, "safe": False}
336
337
338class ToChar(Expression, Func):
339    arg_types = {
340        "this": True,
341        "format": False,
342        "nlsparam": False,
343        "is_numeric": False,
344    }
345
346
347class ToCodePoints(Expression, Func):
348    pass
349
350
351class ToDecfloat(Expression, Func):
352    arg_types = {
353        "this": True,
354        "format": False,
355    }
356
357
358class ToDouble(Expression, Func):
359    arg_types = {
360        "this": True,
361        "format": False,
362        "safe": False,
363    }
364
365
366class ToFile(Expression, Func):
367    arg_types = {
368        "this": True,
369        "path": False,
370        "safe": False,
371    }
372
373
374class ToNumber(Expression, Func):
375    arg_types = {
376        "this": True,
377        "format": False,
378        "nlsparam": False,
379        "precision": False,
380        "scale": False,
381        "safe": False,
382        "safe_name": False,
383        "default": False,
384    }
385
386
387class TryBase64DecodeBinary(Expression, Func):
388    arg_types = {"this": True, "alphabet": False}
389
390
391class TryBase64DecodeString(Expression, Func):
392    arg_types = {"this": True, "alphabet": False}
393
394
395class TryHexDecodeBinary(Expression, Func):
396    pass
397
398
399class TryHexDecodeString(Expression, Func):
400    pass
401
402
403class TryToDecfloat(Expression, Func):
404    arg_types = {
405        "this": True,
406        "format": False,
407    }
408
409
410class Unhex(Expression, Func):
411    arg_types = {"this": True, "expression": False}
412
413
414# Regex
415
416
417class RegexpCount(Expression, Func):
418    arg_types = {
419        "this": True,
420        "expression": True,
421        "position": False,
422        "parameters": False,
423    }
424
425
426class RegexpExtract(Expression, Func):
427    arg_types = {
428        "this": True,
429        "expression": True,
430        "position": False,
431        "occurrence": False,
432        "parameters": False,
433        "group": False,
434        "null_if_pos_overflow": False,  # for transpilation target behavior
435    }
436
437
438class RegexpExtractAll(Expression, Func):
439    arg_types = {
440        "this": True,
441        "expression": True,
442        "group": False,
443        "parameters": False,
444        "position": False,
445        "occurrence": False,
446    }
447
448
449class RegexpFullMatch(Expression, Binary, Predicate, Func):
450    arg_types = {"this": True, "expression": True, "options": False}
451
452
453class RegexpILike(Expression, Binary, Predicate, Func):
454    arg_types = {"this": True, "expression": True, "flag": False}
455
456
457class RegexpInstr(Expression, Func):
458    arg_types = {
459        "this": True,
460        "expression": True,
461        "position": False,
462        "occurrence": False,
463        "option": False,
464        "parameters": False,
465        "group": False,
466    }
467
468
469class RegexpReplace(Expression, Func):
470    arg_types = {
471        "this": True,
472        "expression": True,
473        "replacement": False,
474        "position": False,
475        "occurrence": False,
476        "modifiers": False,
477        "single_replace": False,
478    }
479
480
481class RegexpSplit(Expression, Func):
482    # "mode" is Dremio-specific, appended after "limit" for from_arg_list compat
483    arg_types = {"this": True, "expression": True, "limit": False, "mode": False}
484
485
486class RegexpSubstr(Expression, Func):
487    arg_types = {
488        "this": True,
489        "expression": True,
490        "position": False,
491        "occurrence": False,
492        "parameters": False,
493        "group": False,
494    }
495
496
497# Hashing / cryptographic
498
499
500class Compress(Expression, Func):
501    arg_types = {"this": True, "method": False}
502
503
504class Decrypt(Expression, Func):
505    arg_types = {
506        "this": True,
507        "passphrase": True,
508        "aad": False,
509        "encryption_method": False,
510        "safe": False,
511    }
512
513
514class DecryptRaw(Expression, Func):
515    arg_types = {
516        "this": True,
517        "key": True,
518        "iv": True,
519        "aad": False,
520        "encryption_method": False,
521        "aead": False,
522        "safe": False,
523    }
524
525
526class DecompressBinary(Expression, Func):
527    arg_types = {"this": True, "method": True}
528
529
530class DecompressString(Expression, Func):
531    arg_types = {"this": True, "method": True}
532
533
534class Encrypt(Expression, Func):
535    arg_types = {"this": True, "passphrase": True, "aad": False, "encryption_method": False}
536
537
538class EncryptRaw(Expression, Func):
539    arg_types = {"this": True, "key": True, "iv": True, "aad": False, "encryption_method": False}
540
541
542class CityHash64(Expression, Func):
543    arg_types = {"expressions": False}
544    is_var_len_args = True
545
546
547class FarmFingerprint(Expression, Func):
548    arg_types = {"expressions": True}
549    is_var_len_args = True
550    _sql_names = ["FARM_FINGERPRINT", "FARMFINGERPRINT64"]
551
552
553class MD5(Expression, Func):
554    _sql_names = ["MD5"]
555
556
557class MD5Digest(Expression, Func):
558    arg_types = {"this": True, "expressions": False}
559    is_var_len_args = True
560    _sql_names = ["MD5_DIGEST"]
561
562
563class MD5NumberLower64(Expression, Func):
564    pass
565
566
567class MD5NumberUpper64(Expression, Func):
568    pass
569
570
571class SHA(Expression, Func):
572    _sql_names = ["SHA", "SHA1"]
573
574
575class SHA1Digest(Expression, Func):
576    pass
577
578
579class SHA2(Expression, Func):
580    _sql_names = ["SHA2"]
581    arg_types = {"this": True, "length": False}
582
583
584class SHA2Digest(Expression, Func):
585    arg_types = {"this": True, "length": False}
586
587
588class StandardHash(Expression, Func):
589    arg_types = {"this": True, "expression": False}
590
591
592# Parse
593
594
595class ParseBignumeric(Expression, Func):
596    pass
597
598
599class ParseNumeric(Expression, Func):
600    pass
601
602
603class ParseUrl(Expression, Func):
604    arg_types = {"this": True, "part_to_extract": False, "key": False, "permissive": False}