All Products
Search

This Product

    ApsaraVideo VOD:String functions

    Document Center

    ApsaraVideo VOD:String functions

    Last Updated:Jul 10, 2026

    String functions support extraction, concatenation, case conversion, regular expression matching, splitting, and formatting of string values.

    substr

    Feature Description
    Syntax substr(s, i, j)
    Description Extracts parts from a string.
    Parameter
    • s: the string that you want to extract.
    • i: the position to start extraction in the source string, counting from 1. A value of -1 specifies the rightmost character of the string. Data type: integer.
    • j: the position to end extraction in the source string, counting from 1. A value of -1 specifies the rightmost character of the string. Data type: integer.
    Return value Returns a substring s[i, j] from the source string s.
    Example 
    //Note: The two methods that are used to determine whether a file is an M3U8 file.
if eq(substr($uri, -5, -1), '.m3u8') {
    say(concat($uri, ' is .m3u8'))
}

uri_len = len($uri)
if eq(substr($uri, -5, uri_len), '.m3u8') {
    say(concat($uri, ' is .m3u8'))
}

    concat

    Feature Description
    Syntax concat(s1, ...)
    Description Concatenates strings.
    Parameter The strings that you want to concatenate. You can specify one or more strings. Numeric values are supported.
    Return value Returns a concatenated string.
    Example 
    //Note: The two methods that are used to determine whether a file is an M3U8 file.
if eq(substr($uri, -5, -1), '.m3u8') {
    say(concat($uri, ' is .m3u8'))
}

uri_len = len($uri)
if eq(substr($uri, -5, uri_len), '.m3u8') {
    say(concat($uri, ' is .m3u8'))
}

    upper

    Feature Description
    Syntax upper(s)
    Description Converts a string to uppercase letters.
    Parameter s: the string that you want to convert.
    Return value Returns the s string in uppercase.
    Example 
    mystr = 'Hello, Dsl'                                                                                                                                                                                   
say(upper(mystr))                                                                                                                                                                                      
say(lower(mystr)) 
//Output:
//HELLO,DSL
//hello, dsl

    lower

    Feature Description
    Syntax lower(s)
    Description Converts a string to lowercase letters.
    Parameter s: the string that you want to convert.
    Return value Returns the s string in lowercase.
    Example 
    mystr = 'Hello, Dsl'                                                                                                                                                                                   
say(upper(mystr))                                                                                                                                                                                      
say(lower(mystr)) 
//Output:
//HELLO,DSL
//hello, dsl

    len

    Feature Description
    Syntax len(s)
    Description Queries the length of a string.
    Parameter s: the string that you want to measure.
    Return value Returns the length of the s string. Data type: integer.
    Example 
    //Note: The two methods that are used to determine whether a file is an M3U8 file.
if eq(substr($uri, -5, -1), '.m3u8') {
    say(concat($uri, ' is .m3u8'))
}

uri_len = len($uri)
if eq(substr($uri, -5, uri_len), '.m3u8') {
    say(concat($uri, ' is .m3u8'))
}

    byte

    Feature Description
    Syntax byte(c)
    Description Queries the ASCII value of a character.
    Parameter c: the character whose ASCII value you want to query. You can specify only one character.
    Return value Returns the ASCII value of the specified character. Data type: numeric.
    Example 
    say(byte('a'))
say(byte('A'))
//Output: 97
//65

    match_re

    Item Description
    Syntax match_re(s, p [, o]).
    Description Checks if a string matches a regular expression. This function uses the PCRE regular expression engine. For more information, see PCRE syntax.
    Parameter
    • s: string. The target string.
    • p: string. The regular expression.
    • o: string. Optional. Specifies options for the regular expression engine.
      • If omitted, the match is case-sensitive.
      • If set to i, the match is case-insensitive.
    Return value Returns true if the string matches the pattern, and false otherwise.
    Example 
    url = concat('http://', $host, $uri)
m1 = match_re(url, 'http://.*\.example\.com/.*', 'i')
m2 = match_re(url, '^http://.*\.aliyundoc\.com\.cn/.*\.d\\.html(\?.*)?$')
m3 = match_re(url, '^http://.*.demo.aliyundoc/.*\.d\.html(\?.*)?$')
m4 = match_re(url, '^http://.*\.aliyundoc\.com\.cn/zt_d/')
m5 = match_re(url, '^http://learn.aliyundoc.com.cn/zt_d/we2015/?$')
m6 = match_re($args, 'from=wap1$')
m7 = match_re($args, 'from=comos1$')

if and(m1, or(m2, m3), not(m4), not(m5), or(not(m6), not(m7))) {                                                                                                                                       
    add_rsp_header('USER-DEFINED-1', 'hit1')                                                                                                                                                           
    add_rsp_header('USER-DEFINED-2', 'hit2')  
}

    capture_re

    Feature Description
    Syntax capture_re(s, p [,init])
    Description Captures the matches of a string and returns the matching substrings. For more information about PCRE, see PCRE syntax.
    Parameter
    • s: the string that you want to match. Data type: string.
    • p: the regular expression for matching. Data type: string.
    • init: the position to start matching, counting from 1. Data type: integer.
    Return value Returns the matching substrings as a dictionary if the pattern matches, or an empty dictionary otherwise.
    Example 
    pcs = capture_re($request_uri,'^/([^/]+)/([^/]+)([^?]+)\?(.*)')
sec1 = get(pcs, 1)
sec2 = get(pcs, 2)
sec3 = get(pcs, 3)
if or(not(sec1), not(sec2), not(sec3)) {
   add_rsp_header('X-TENGINE-ERROR', 'auth failed - missing necessary uri set')
   exit(403)
}
digest = md5(concat(sec1, sec3))
if ne(digest, sec2) {
    add_rsp_header('X-TENGINE-ERROR', 'auth failed - invalid digest')
    exit(403)
}

    gsub_re

    Feature Description
    Syntax gsub_re(subject, regex, replace [,option])
    Description Replaces all matches of a string and returns the string after the replacement. For more information about PCRE, see PCRE syntax.
    Parameter
    • subject: the string that you want to match. Data type: string.
    • regex: the regular expression. Data type: string.
    • replace: the string for replacement. Data type: string.
      You can specify the replace parameter by using the matching substrings.
      • $0: specifies all substrings that match regex.
      • $N: specifies the substring that matches the Nth parenthesized subexpression () of regex.
    • option: the regular expression engine. Data type: string. This parameter is optional.
    Return value Returns the string after replacing all regex matches in subject with replace.
    Example 
    subject = 'Hello, Es'
regex = '([a-zA-Z])[a-z]+'
replace = '[$0,$1]'
add_rsp_header('X-DEBUG-GSUB-RE', gsub_re(subject, regex, replace))         
//Output:
//X-DEBUG-GSUB-RE: [Hello,H], [Es,E]

    split

    Feature Description
    Syntax split(s [,sep])
    Description Splits a string into an array of substrings and returns the array.
    Parameter
    • s: the string that you want to split. Data type: string.
    • sep: the separator that is used to split the string. Data type: string.
    Return value Returns an array of key-value pairs in the dictionary type. The value of the key parameter is a number that starts from 1, for example, [1]=xx and [2]=y. If sep is left empty, the string is split by whitespace characters. Whitespace characters include space characters and tab characters (\t).
    Example 
    if $arg_from {
    t = split($arg_from, ',')
    if get(t, 1) {
        say(concat('[1]=', get(t, 1)))
    }
    if get(t, 2) {
        say(concat('[2]=', get(t, 1)))
    }
}         
//Request: ?from=xx1,xx2,xx3 
//Response: [1]=xx1
//[2]=xx1

    split_as_key

    Feature Description
    Syntax split_as_key(s [,sep])
    Description Splits a string into an array of substrings and returns the array.
    Parameter
    • s: the string that you want to split. Data type: string.
    • sep: the separator that is used to split the string. Data type: string.
    Return value Returns response parameters in the same way as the split() function. However, the key parameter is named after each split element: Element 1 -> Element 2.
    Example 
    def echo_each(k, v, u) {
    s = concat(k, '=', v, ' u=', get(u, 1))
    say(s) 
}
if $arg_from {
    t = split_as_key($arg_from, ',')
    foreach(t, echo_each, ['hi,dsl'])
}    
//Request: ?from=xx1,xx2,xx3 
//Response: xx2=xx2 u=hi,dsl
//xx1=xx1 u=hi,dsl
//xx3=xx3 u=hi,dsl

    tohex

    Feature Description
    Syntax tohex(s)
    Description Converts a string to a hexadecimal string.
    Parameter s: the string that you want to convert.
    Return value Returns a hexadecimal string converted from s.
    Example 
    digest = sha1('xxxx')
add_rsp_header('X-DSL-TOHEX', tohex(digest))    

//Note: A response header is added.
//X-DSL-TOHEX: 4ad583af22c2e7d40c1c916b2920299155a46464

    tostring

    Feature Description
    Syntax tostring(a)
    Description Converts data of any type to a string.
    Parameter a: the data that you want to convert. Data type: any type.
    Return value Returns a string converted from the a value.
    Example 
    s = tostring(123)
add_rsp_header('X-DSL-TOSTRING', s)  

//Note: A response header is added.
//X-DSL-TOSTRING: 123

    tochar

    Feature Description
    Syntax tochar(n1, n2, ...)
    Description
    • Converts one or more internal integers (ASCII values) to a string. For example, 48 corresponds to the character "0".
    • The length of the returned string is based on the number of specified parameters.
    Parameter nX: the integers that you want to convert. You can specify one or more integers.
    Return value Returns a string converted from integers.
    Example 
    add_rsp_header('X-DSL-TOCHAR', tochar(97))
add_rsp_header('X-DSL-TOCHAR', tochar(97, 98), true)
//Output: A response header is added.
//X-DSL-TOCHAR: a
//X-DSL-TOCHAR: ab

if $arg_filename {
    hn = 'Content-Disposition'
    add_rsp_header('Content-Disposition', concat('attachment;filename=', tochar(34), filename, tochar(34)))
    add_rsp_header(hn, hv)
}     
//Output: A response header is added.
//Content-Disposition: attachment;filename="The value of the filename parameter"

    reverse

    Feature Description
    Syntax reverse(str)
    Description Reverses a string.
    Parameter str: the string that you want to reverse.
    Return value Returns the reversed string.
    Example 
    say(reverse('hello'))
    Output:
    #olleh

    find

    Feature Description
    Syntax string.find (s, substr, pos)
    Description Searches for a substring in a specified string.
    Parameter
    • s: the string that you want to search.
    • substr: the substring that you want to search.
    • pos: the position where the search starts. Data type: numeric. This parameter is optional. You can specify a negative integer. The default value is 1.
    Return value
    • Returns an array if the specified substring is found.
      • Index 1 indicates the position where the search starts.
      • Index 2 indicates the position where the search ends.
    • Returns an empty array if the specified substring is not found.
    Example 
     str = 'hello dsl'
 add_rsp_header('string-find()-start', tostring(get(find(str, 'dsl'), 1)))
 str = 'hello dsl 12'
 add_rsp_header('string-find()-end', tostring(get(find(str, 'dsl'), 2)))
 str = 'hello dsl'
 add_rsp_header('string-find()-tail-start', tostring(get(find(str, 'dsl', -6), 1)))
 str = 'hello dsl 12'
 add_rsp_header('string-find()-tail-end', tostring(get(find(str, 'dsl', -6), 2)))
    Output:
    string-find()-start:7
string-find()-end:9
string-find()-tail-start:7
string-find()-tail-end:9

    format

    Feature Description
    Syntax format(fmt, ···)
    Description Formats values according to a format string. The format string is the first parameter and must be a string. It follows the sprintf specification from the C programming language.
    The syntax of a format string is: %[parameter][flag][field width][.precision]specifier.
    • %%: prints literal percentage signs (%).
    • %c: converts integers into ASCII characters.
    • %d: converts integers into decimal numbers.
    • %f: converts N-precision numbers into floating point numbers.
    • %o: converts integers into octal numbers.
    • %s: converts integers into strings.
    • %x: converts integers into hexadecimal numbers in lowercase letters.
    • %X: converts integers into hexadecimal numbers in uppercase letters.
    Parameter
    • fmt: the string type. This parameter specifies a format string.
    • The variable number of parameters: any type.
    Return value Returns an ASCII string.
    Example 
    say(concat('format:', format('%%%s$%.2s$%s$%c$%d$%2.2f$%.2o$%x$%X', 'format', 3.1415926, true, 95, 3.1415926, 3.1415926, 3.1415926, 10, 10)))
    Output:
    format:%format$3.$true$_$3$3.14$03$a$A

    tobin

    Feature Description
    Syntax tobin(str)
    Description Converts a hexadecimal string to an ASCII string.
    Parameter str: the hexadecimal string that you want to convert. It is not case-sensitive.
    Return value Returns an ASCII string.
    Example 
    say(concat('tobin:', tobin('2F2F')))
    Output:
    tobin://

    trim

    Feature Description
    Syntax trim(s, [, loc])
    Description Removes whitespace characters before and/or after a string.
    Parameter
    • s: the string.
    • loc: the default value is both. This parameter is optional. Valid values:
      • both: removes the whitespace characters before and after the string.
      • left: removes only the whitespace characters before the string.
      • right: removes only the whitespace characters after the string.
    Return value Returns the trimmed string.
    Example 
    say(concat('trim():', trim(' abcd ')))
say(concat('trim(left):', trim(' abcd ', 'left')))
say(concat('trim(right):', trim(' abcd ', 'right')))
    Output:
    trim():abcd
trim(left):abcd
trim(right): abcd