!CHAPTER String functions

For string processing, AQL offers the following functions:

- *CONCAT(value1, value2, ... valuen)*: Concatenate the strings 
  passed as in *value1* to *valuen*. *null* values are ignored. List value arguments
  are expanded automatically, and their individual members will be concatenated.

      /* "foobarbaz" */
      CONCAT('foo', 'bar', 'baz')

      /* "foobarbaz" */
      CONCAT([ 'foo', 'bar', 'baz' ])

- *CONCAT_SEPARATOR(separator, value1, value2, ... valuen)*: 
  Concatenate the strings passed as arguments *value1* to *valuen* using the 
  *separator* string. *null* values are ignored. List value arguments
  are expanded automatically, and their individual members will be concatenated.

      /* "foo, bar, baz" */
      CONCAT_SEPARATOR(', ', 'foo', 'bar', 'baz')

      /* "foo, bar, baz" */
      CONCAT_SEPARATOR(', ', [ 'foo', 'bar', 'baz' ])

- *CHAR_LENGTH(value)*: Return the number of characters in *value*. This is
  a synonym for *LENGTH(value)*

- *LOWER(value)*: Lower-case *value*

- *UPPER(value)*: Upper-case *value*

- *SUBSTITUTE(value, search, replace, limit)*: Replaces search values in the string
  *value*. If *search* is a string, all occurrences of *search* will be replaced in
  *value*. If *search* is a list, each occurrence of a value contained in *search*
  will be replaced by the corresponding list item in *replace*. If *replace* has less
  list items than *search*, occurrences of unmapped *search* items will be replaced
  by the empty string. The number of replacements can optionally be limited using the
  *limit* parameter. If the *limit* is reached, no further occurrences of the search
  values will be replaced.

      /* "the lazy brown foxx" */ 
      SUBSTITUTE("the quick brown foxx", "quick", "lazy")

      /* "the slow brown dog" */ 
      SUBSTITUTE("the quick brown foxx", [ "quick", "foxx" ], [ "slow", "dog" ])       

      /* "A VOID! brown " */ 
      SUBSTITUTE("the quick brown foxx", [ "the", "quick", "foxx" ], [ "A", "VOID!" ])

      /* "the xx brown xx" */
      SUBSTITUTE("the quick brown foxx", [ "quick", "foxx" ], "xx" )                   

  Alternatively, *search* and *replace* can be specified in a combined value:

      /* "the small slow ant" */ 
      SUBSTITUTE("the quick brown foxx", { 
        "quick" : "small", 
        "brown" : "slow", 
        "foxx" : "ant" 
      }) 

- *SUBSTRING(value, offset, length)*: Return a substring of *value*,
  starting at *offset* and with a maximum length of *length* characters. Offsets
  start at position 0. Length is optional and if omitted the substring from *offset*
  to the end of the string will be returned.

- *LEFT(value, LENGTH)*: Returns the *LENGTH* leftmost characters of
  the string *value*

- *RIGHT(value, LENGTH)*: Returns the *LENGTH* rightmost characters of
  the string *value*

- *TRIM(value, type)*: Returns the string *value* with whitespace stripped 
  from the start and/or end. The optional *type* parameter specifies from which parts
  of the string the whitespace is stripped:

  - *type* 0 will strip whitespace from the start and end of the string
  - *type* 1 will strip whitespace from the start of the string only
  - *type* 2 will strip whitespace from the end of the string only

- *TRIM(value, chars)*: Returns the string *value* with whitespace stripped 
  from the start and end. The optional *chars* parameter can be used to override the
  characters that should be removed from the string. It defaults to `\r\n\t `
  (i.e. `0x0d`, `0x0a`, `0x09` and `0x20`).

      /* "foobar" */
      TRIM("  foobar\t \r\n ")         

      /* "foo;bar;baz" */
      TRIM(";foo;bar;baz, ", ",; ")     

- *LTRIM(value, chars)*: Returns the string *value* with whitespace stripped 
  from the start only. The optional *chars* parameter can be used to override the
  characters that should be removed from the string. It defaults to `\r\n\t `
  (i.e. `0x0d`, `0x0a`, `0x09` and `0x20`).

- *RTRIM(value, chars)*: Returns the string *value* with whitespace stripped 
  from the end only. The optional *chars* parameter can be used to override the
  characters that should be removed from the string. It defaults to `\r\n\t `
  (i.e. `0x0d`, `0x0a`, `0x09` and `0x20`).

- *SPLIT(value, separator, limit)*: Splits the given string *value* into a list of
  strings, using the *separator*. The *separator* can either be a string or a
  list of strings. If the *separator* is the empty string, *value* will be split
  into a list of characters. If no *separator* is specified, *value* will be
  returned inside a list.
  The optional parameter *limit* can be used to limit the number of split values in
  the result. If no *limit* is given, the number of splits returned is not bounded. 

- *REVERSE(value)*: Returns the reverse of the string *value*

- *CONTAINS(text, search, return-index)*: Checks whether the string
  *search* is contained in the string *text*. By default, this function returns 
  *true* if *search* is contained in *text*, and *false* otherwise. By
  passing *true* as the third function parameter *return-index*, the function
  will return the position of the first occurrence of *search* within *text*, 
  starting at offset 0, or *-1* if *search* is not contained in *text*.

  The string matching performed by *CONTAINS* is case-sensitive.

* *FIND_FIRST(text, search, start, end)*: Returns the position of the first
  occurrence of the string *search* inside the string *text*. Positions start at 
  zero. If *search* is not contained in *text*, -1 is returned. The search can 
  optionally be limited to a subset of *text* using the *start* and *end* arguments.

* *FIND_LAST(text, search, start, end)*: Returns the position of the last
  occurrence of the string *search* inside the string *text*. Positions start at 
  zero. If *search* is not contained in *text*, -1 is returned. The search can 
  optionally be limited to a subset of *text* using the *start* and *end* arguments.

- *LIKE(text, search, case-insensitive)*: Checks whether the pattern
  *search* is contained in the string *text*, using wildcard matching. 
  Returns *true* if the pattern is contained in *text*, and *false* otherwise. 
  The *pattern* string can contain the wildcard characters *%* (meaning any
  sequence of characters) and *_* (any single character).

  The string matching performed by *LIKE* is case-sensitive by default, but by
  passing *true* as the third parameter, the matching will be case-insensitive.

  The value for *search* cannot be a variable or a document attribute. The actual 
  value must be present at query parse time already.