String Manipulation Functions: Difference between revisions

From wiki.jriver.com
Jump to navigation Jump to search
 
(7 intermediate revisions by 2 users not shown)
Line 11: Line 11:
| description=
| description=
{{argument optional}}
{{argument optional}}
The [[#Clean|Clean()]] function is generally used to sanitize a <i>string</i> by stripping empty brackets, remove superfluous dash characters, eliminate leading or trailing articles, or replace filesystem-illegal characters. It is typically employed before some operation such as Rename to clean the product of joining various fields, some of which may be empty, or to produce filesystem-safe filenames. It may be used for a variety of purposes, however.
The [[#Clean|Clean()]] function is generally used to sanitize a <i>string</i> by stripping empty brackets, remove superfluous dash characters, eliminate leading or trailing articles, or replace filesystem-illegal characters. It is typically employed before some operation such as Rename to clean the product of joining various fields, some of which may be empty, or to produce filesystem-safe filenames. However, It may be used for a variety of purposes.

{{argument table
{{argument table
| name=mode
| name=mode
Line 21: Line 22:
{{argument table row|4|Replaces each filesystem-illegal character, '''allowing backslashes''', {{monospace|/ : * ? " < > |}} with an underscore {{monospace|<nowiki>_</nowiki>}}, and replaces each unprintable character with a space.}}
{{argument table row|4|Replaces each filesystem-illegal character, '''allowing backslashes''', {{monospace|/ : * ? " < > |}} with an underscore {{monospace|<nowiki>_</nowiki>}}, and replaces each unprintable character with a space.}}
{{argument table row|5|Standardises quotes, replacing “ and ” with " and also, ‘ and ’ with '}}
{{argument table row|5|Standardises quotes, replacing “ and ” with " and also, ‘ and ’ with '}}
{{argument table row|6|Removes numbers from the start.}}
{{argument table row|7|Removes numbers from the end.}}
{{argument table row|8|Removes numbers from the either side.}}
{{argument table row|9|Removes accents.}}
}}
}}
| examples=
| examples=
Line 31: Line 36:
'''{{monospace|<nowiki>clean(\//:*?"&lt;&gt;|, 3)</nowiki>}}'''
'''{{monospace|<nowiki>clean(\//:*?"&lt;&gt;|, 3)</nowiki>}}'''
: This trivial example demonstrates how all filesystem-illegal characters are converted to underscores, producing the nine-character output <span style="font-family: monospace,monospace; font-size:1em;">_________</span> which consists entirely of underscores.
: This trivial example demonstrates how all filesystem-illegal characters are converted to underscores, producing the nine-character output <span style="font-family: monospace,monospace; font-size:1em;">_________</span> which consists entirely of underscores.
}}

=== <span id="Extract">Extract(&hellip;)</span> ===
: Returns a portion of a string bounded by another substring

{{function description box
| name=Extract
| arguments=Mode, SourceString, String1, String2
| description=
The [[#Extract|Extract()]] function allows for easy extraction of a portion of a SourceString based on surrounding strings. This is a task that would typically require the use [[regex()|Regular Expressions]] to achieve. ''Extract()'' allows for a much simpler, easier to follow and understand path to success for all, especially for those (the majority of us?) that find regular expressions a little overwhelming.

Mode ''must'' be specified as there is no default.

{{argument table
| name=mode
| contents=
{{argument table row|1|Returns everything up to, and including, ''String1''}}
{{argument table row|2|Returns everything up to, but ''not'' including, ''String1''}}
{{argument table row|3|Returns everything after, and including, ''String1''}}
{{argument table row|4|Returns everything after, but ''not'' including, ''String1''}}
{{argument table row|5|Returns everything between, and including, ''String1'' and ''String2''}}
{{argument table row|6|Returns everything between, but ''not'' including, ''String1'' and ''String2''}}
}}

: All of the modes above are '''case-insensitive'''. If case sensitivity is desired, add 100 to the chosen mode value.
: ''SourceString'' can be a library field, an expression result, or a literally given string.
: ''String1'', like ''Mode'', is always required, and can be a library field, an expression result, or a literally given string.
: ''String2'' is only required when using modes 5, 6, 105 or 106, and can be a library field, an expression result, or a literally given string.


| examples=
'''Mode 2 - "Everything up to, but not including"'''
'''{{monospace|<nowiki>Extract(2,[Name], in)</nowiki>}}'''<br>Where ''[Name]'' is <span style="color: blue;">''Orchestral Suite No. 3 in D major, BWV 1068: 1. Ouverture''</span>, this returns: Orchestral Suite No. 3


'''Mode 6 - "Everything between, but not including"'''

'''{{monospace|<nowiki>Extract(6,[Name],-==,==-)</nowiki>}}'''<br>Where ''[Name]'' is <span style="color: blue;">''String Quartet No. 11 in F minor Op. 95 -==Serioso==- I. Allegro con brio''</span>, this returns: Serioso


'''Mode 3 - "Everything after, and including"'''

'''{{monospace|<nowiki>Extract(3,[Filename],[Composer])</nowiki>}}'''<br>Where ''[Filename]'' is <span style="color: blue;">''<nowiki>\\NAS\Share1\Music\CD\Bach\Flac\Concertos for Orchestra\Concerto for 2 Harpsichords - BWV 1062: I. Vivace</nowiki>''</span> and ''[Composer]'' is <span style="color: blue;">''Bach''</span>, this returns:<br>Bach\Flac\Concertos for Orchestra\Concerto for 2 Harpsichords - BWV 1062: I. Vivace


'''Mode 104 - "Everything after, but not including, <u>with case-sensitivity</u>"'''

'''{{monospace|<nowiki>Extract(104,Nocturne OP9 NO2,NO)</nowiki>}}'''<br>Returns: 2

}}
}}


Line 198: Line 252:
{{function description box
{{function description box
| name=Mid
| name=Mid
| arguments=string, start position, quantity
| arguments=string, start position, quantity, mode
| description=
| description=
{{argument optional|start position|0}}
{{argument optional|start position|0}}
{{argument optional|quantity|1}}
{{argument optional|quantity|1}}
{{argument optional}}
The [[#Mid|Mid()]] function returns a specified <i>quantity</i> of characters from the <i>start position</i> in <i>string</i>.
By default, the [[#Mid|Mid()]] function returns a specified <i>quantity</i> of characters from the <i>start position</i> in <i>string</i>.
It is also possible to return characters between two indices by specifying that the function operates in ''mode 1''. When mode 1 is specified, ''quantity'' is taken as the end index and the function will return all characters from ''start'', up to, but not including, ''end''.


The <i>start position</i> is 0-based (i.e. the first character is considered position 0). A quantify of -1 returns all characters from the start positionning to the end of <i>string</i>.
The <i>start position</i> is 0-based (i.e. the first character is considered position 0). A quantify of -1 returns all characters from the start positionning to the end of <i>string</i>.
Line 210: Line 266:
'''{{monospace|<nowiki>mid(12345, 1, 2)</nowiki>}}'''
'''{{monospace|<nowiki>mid(12345, 1, 2)</nowiki>}}'''
: Returns 2 characters beginning at <i>start position</i> 1, which is <span style="font-family: monospace,monospace; font-size:1em;">23</span>.
: Returns 2 characters beginning at <i>start position</i> 1, which is <span style="font-family: monospace,monospace; font-size:1em;">23</span>.
'''{{monospace|<nowiki>mid(12345, 1, 3, 1)</nowiki>}}'''
: '''''Mode 1''''' has been specified here, therefore, this returns characters from <i>start position</i> 1, up to, but not including, end position 3, which is <span style="font-family: monospace,monospace; font-size:1em;">23</span>.
'''Additional Examples:'''
'''Additional Examples:'''
* [http://yabb.jriver.com/interact/index.php?topic=52809.0 An example that uses Mid() to re-order a date field.]
* [http://yabb.jriver.com/interact/index.php?topic=52809.0 An example that uses Mid() to re-order a date field.]
Line 259: Line 317:
: '''Padding''' is the string you wish to pad with. This can be given literally, or sourced from a given library field. If not specified, this will default to a single space.
: '''Padding''' is the string you wish to pad with. This can be given literally, or sourced from a given library field. If not specified, this will default to a single space.


''See also: [[#PadNumber|PadNumber()]]''
''See also: [[PadNumber()]]''


| examples=
| examples=
Line 284: Line 342:
: '''Characters''' is required and specifies how much padding is to be applied.
: '''Characters''' is required and specifies how much padding is to be applied.
: '''Padding''' is the string you wish to pad with. This can be given literally, or sourced from a given library field. If not specified, this will default to a single space.
: '''Padding''' is the string you wish to pad with. This can be given literally, or sourced from a given library field. If not specified, this will default to a single space.

''See also: [[PadNumber()]]''


| examples=
| examples=
Line 446: Line 506:


=== <span id="Replace">Replace(&hellip;)</span> ===
=== <span id="Replace">Replace(&hellip;)</span> ===
: Replace or remove a string segment
: Replace or remove a string segment.


{{function description box
{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="Replace" valign="top"
| name=Replace
| arguments=String, Find, Replace, Mode
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 2px 1px 0 2px; border-right: 1px solid #bbb;" width="100" | Description
| description=
| style="background: #f9f9f9; color: #111; border-style: solid; border-width: 2px 2px 0 0" width="1200" | <span style="font-family: monospace,monospace; font-size:1em; color:#0f3f8d; font-size:110%"><b>replace(</b><i>string</i><b>, </b><i>old</i><b>, </b><i>new</i><b>)</b></span>
{{argument optional|Replace|empty}}
The [[#Replace|Replace()]] function replaces all instances of <i>old</i> within <i>string</i> with <i>new</i>.
{{argument optional|Mode|0}}
If <i>new</i> is unspecified, it defaults to an empty value, causing <i>old</i> to be removed.
[[#Replace|Replace()]] operates in a case-sensitive manner.


{{argument table
Argument <i>new</i> is optional (defaults to EMPTY).
| name=mode
| contents=
{{argument table row|0|Case Sensitive}}
{{argument table row|1|Case Insensitive}}
}}

The [[#Replace|Replace()]] function replaces all instances of <i>Find</i> within <i>String</i>, with <i>Replace</i>. If <i>Replace</i> is unspecified, it defaults to an empty value, causing <i>Find</i> to be removed. By default, Replace() operates in a case-sensitive manner, but can be switched to case-insensitive operation by specifying Mode 1.
| examples=
'''{{monospace|<nowiki>Replace(The Daily Show with John Oliver, hn Oliver, n Stewart)</nowiki>}}'''
: Returns Daily Show with Jon Stewart


'''{{monospace|<nowiki>Replace(Led Zeppelin.[remastered], .[remastered])</nowiki>}}'''
: Returns Led Zeppelin. As no <i>Replace</i> value is specified, the default empty value is used as a replacement, effectively removing all instances of <i>Find</i>.


'''{{monospace|<nowiki>Replace(Abba,a)</nowiki>}}'''
: Returns Abb. No <i>Replace</i> value is specified, so any matches are removed. Also, no <i>Mode</i> is specified, so <i>Find</i> is case-sensitive.


'''{{monospace|<nowiki>Replace(Abba,a,,1)</nowiki>}}'''
: Returns bb. No <i>Replace</i> value is specified, so any matches are removed. Also, <i>Mode</i> 1 is specified, so <i>Find</i> is case-insensitive.
}}


|- valign="top"
|- valign="top"
Line 534: Line 616:
{{argument table row|2|Trims leading and trailing new lines}}
{{argument table row|2|Trims leading and trailing new lines}}
{{argument table row|3|Trims leading, trailing and double new lines}}
{{argument table row|3|Trims leading, trailing and double new lines}}
{{argument table row|4|Trims 3 or more new lines to double new lines}}


}}
}}

Latest revision as of 09:12, 20 May 2023

The functions in this section are used primarily to manipulate strings. Since the Media Center expression language is primarily string-oriented, these functions provide a means to manipulate field values or the output from other expressions.

Clean(…)

Clean a string to be used for various operations.
Description Clean(string, mode)
  • Argument mode is optional (defaults to 0).

The Clean() function is generally used to sanitize a string by stripping empty brackets, remove superfluous dash characters, eliminate leading or trailing articles, or replace filesystem-illegal characters. It is typically employed before some operation such as Rename to clean the product of joining various fields, some of which may be empty, or to produce filesystem-safe filenames. However, It may be used for a variety of purposes.

Available mode values:

0Removes empty () and [], superfluous dash (-) and whitespace characters and sometimes comma (be careful).
1Removes the article 'the' from the beginning and ', the' from the end.
2Removes any article (a, an, the, etc.) from the beginning and end.
3Replaces each filesystem-illegal character \ / : * ? " < > with an underscore _, and replaces each unprintable character with a space.
4Replaces each filesystem-illegal character, allowing backslashes, / : * ? " < > with an underscore _, and replaces each unprintable character with a space.
5Standardises quotes, replacing “ and ” with " and also, ‘ and ’ with '
6Removes numbers from the start.
7Removes numbers from the end.
8Removes numbers from the either side.
9Removes accents.
Examples clean([album] - [date])
The concatenation of [Album] - [Date] may leave a dangling - string when date is empty. Clean() in the default mode removes this dangling string.

clean(The Beatles, 1)

For sorting or grouping purposes, it is often desirable to remove the leading article The from a string. Clean() in mode 1 provides a convenient solution, and in this example produces Beatles.

clean(AC//DC: Back In Black, 3)

When an expression is to be used to produce a filename, filesystem-illegal characters must be removed or converted to legal characters. Clean() in mode 3 will convert such characters into safe underscores. This example would produce the filesystem-safe value of AC_DC_ Back In Black.

clean(\//:*?"<>|, 3)

This trivial example demonstrates how all filesystem-illegal characters are converted to underscores, producing the nine-character output _________ which consists entirely of underscores.
(Back to top)   (Function index)

Extract(…)

Returns a portion of a string bounded by another substring
Description Extract(Mode, SourceString, String1, String2)

The Extract() function allows for easy extraction of a portion of a SourceString based on surrounding strings. This is a task that would typically require the use Regular Expressions to achieve. Extract() allows for a much simpler, easier to follow and understand path to success for all, especially for those (the majority of us?) that find regular expressions a little overwhelming.

Mode must be specified as there is no default.

Available mode values:

1Returns everything up to, and including, String1
2Returns everything up to, but not including, String1
3Returns everything after, and including, String1
4Returns everything after, but not including, String1
5Returns everything between, and including, String1 and String2
6Returns everything between, but not including, String1 and String2
All of the modes above are case-insensitive. If case sensitivity is desired, add 100 to the chosen mode value.
SourceString can be a library field, an expression result, or a literally given string.
String1, like Mode, is always required, and can be a library field, an expression result, or a literally given string.
String2 is only required when using modes 5, 6, 105 or 106, and can be a library field, an expression result, or a literally given string.
Examples Mode 2 - "Everything up to, but not including"

Extract(2,[Name], in)
Where [Name] is Orchestral Suite No. 3 in D major, BWV 1068: 1. Ouverture, this returns: Orchestral Suite No. 3


Mode 6 - "Everything between, but not including"

Extract(6,[Name],-==,==-)
Where [Name] is String Quartet No. 11 in F minor Op. 95 -==Serioso==- I. Allegro con brio, this returns: Serioso


Mode 3 - "Everything after, and including"

Extract(3,[Filename],[Composer])
Where [Filename] is \\NAS\Share1\Music\CD\Bach\Flac\Concertos for Orchestra\Concerto for 2 Harpsichords - BWV 1062: I. Vivace and [Composer] is Bach, this returns:
Bach\Flac\Concertos for Orchestra\Concerto for 2 Harpsichords - BWV 1062: I. Vivace


Mode 104 - "Everything after, but not including, with case-sensitivity"

Extract(104,Nocturne OP9 NO2,NO)
Returns: 2

(Back to top)   (Function index)

Find(…)

Finds a string or character in another string, returning its zero-based position in that string.
Description Find(Search, Find, Start, Flags)
  • Argument Start is optional (defaults to 0).
  • Argument Flags is optional (defaults to 0).
"Search" is the string to be searched and can be a literal given string, library field, or nested expression result.
"Find" is the character or string you wish to locate within the "Search" value.
"Start" specifies numerically, where in the string the function should begin working. This is ignored if searching from the end of the string.
"Flags" has three available values... 0 performs a case-insensitive search from the start of the string, 1 performs a case sensitive search from the start of the string and 2 performs a case insensitive search from the end of the string. These can be combined, so, a "Flags" value of 3 would perform a case sensitive search from the end of the string.

If no match is found, the function returns a value of -1

Regardless of where in "Search" "Start" is initiated, the result is always zero-based, counting from the first character in "Search".

When a match is found, the result returned is 'zero-based', meaning that if the result is zero, that points to the first character in "Search". This means that results will be compatible for use in combination with other zero-based functions, such as Mid(), for example.

Examples Find(John LenNon, N, 0, 0)
A case insensitive search for N, from the start, where "J" is counted as zero. The result is "3"

Find(John LenNon, N, 4, 0)

A case insensitive search for N, from the fourth character from the start, in this case, the space after "John", where "J" is counted as zero. The result is "7", the first "N" in LenNon.

Find(John LenNon, N, 4, 2)

A case insensitive search for N, from the end of the string. The result is "10", the last "N" in LenNon.

Find(John LenNon, N, 9, 3)

A case sensitive search for N, from the end of the string. The result is "8", the only "N" in LenNon. Note that start position is ignored.
(Back to top)   (Function index)

FixCase(…)

Changes the case of a given string.
Description FixCase(string, mode)
  • Argument mode is optional (defaults to 0).

The FixCase() function will convert the supplied text string according to the specified mode. Available mode values:

0Title Case
1All words
2First word
3All uppercase
4All lowercase
5All words (preserve existing capitalization)
Examples fixcase(enjoy the silence)
The default mode 0 is used, so the output is: Enjoy the Silence.

fixcase(enjoy the silence, 1)

Using mode 1, all words are uppercased, so the output is: Enjoy The Silence.

fixcase(MY ALbUm IS cAlLeD: adam, 4)

Outputs: my album is called: adam.

fixcase(MY ALbUm IS cAlLeD: adam, 5)

Using mode 5, the initial character of each word is uppercased, but other existing capitalization is preserved, so the output is: MY ALbUm IS CAlLeD: Adam.
(Back to top)   (Function index)

FixSpacing(…)

Intelligently splits adjacent camel-cased words.
Description FixSpacing(string, mode)
  • Argument mode is optional (defaults to 1).

The FixSpacing() function inserts spaces between adjacent camel-cased words in string. It is useful for helping to clean and convert metadata that favors compactness over standard sentence structure. Available mode values:

0Disables conversion
1Enables camel-case conversion
Examples fixspacing(OneWorld)
Outputs One World.

fixspacing([name], 1)

Outputs the name field with any camel-case converted into standard sentence structure. If the value of name was, MiracleOn34thStreet, the output would be Miracle On 34th Street.

fixspacing(Another [name])

Assuming the same [name] as above, this would return Another Miracle On 34th Street.
(Back to top)   (Function index)

Hexify(…)

Hexifies a string to make it suitable for web usage.
Description Hexify(string)

The Hexify() function URI encodes a string to make it useable by a browser or search engine. Hexify() is typically used by expressions generating or working on URLs in Media Center's Link Manager.

Examples hexify(Oasis - /(What's The Story/) Morning Glory?)
The result is Oasis%20-%20%28What%27s%20The%20Story%29%20Morning%20Glory%3F.
(Back to top)   (Function index)

Left(…)

Retrieves a specified number of characters from the left of a string.
Description Left(string, quantity)

The Left() function retrieves no more than quantity characters from the left of the string.

Examples left([filename], 3)
Return the Windows drive letter, colon and first back-slash from the filename (for filenames beginning with a windows drive letter).
(Back to top)   (Function index)

Length(…)

Returns the number of characters in a string.
Description Length(string)

The Length() function returns the number of characters contained in string.

Examples length(A Simple Plan)
Returns 13.

if(compare(length([filename]), >=, 68), Long, Short)

The length of the filename is calculated, and compared against 68, outputting Long when the length is greater than or equal to 68, and Short otherwise.
(Back to top)   (Function index)

Letter(…)

Returns the starting letter or letters of a given string.
Description Letter(string, number, mode)
  • Argument number is optional (defaults to 1).
  • Argument mode is optional (defaults to 0).

The Letter() function returns the starting letter or letters of a given string, which can be given literally or as a library field. The function's mode defaults to "Ignore Articles", and for this, it uses the existing, user managed articles list. It also defaults to "number grouping", meaning that if the first character is a number, regardless of that number, a hash (#) is returned. Number specifies the number of starting characters to return, and defaults to one. Available mode values:

These modes are useful when working with a selection of multiple files that may have a mix of articles and numbers and allow you to achieve whichever combination of results you require.

0Ignore articles and group numbers
1Do not group numbers, return the actual number. Articles are ignored.
2Do not ignore articles, but perform number grouping
3Do not ignore articles and do not group numbers
Examples letter(10CC)
Returns #.

letter(10CC,2)

Returns ##.

letter(10CC,2,1)

Returns 10.

letter(The Band,2)

Returns Ba.

letter(The Band,2,3)

Returns Th.
(Back to top)   (Function index)

Mid(…)

Retrieves specified characters from a string.
Description Mid(string, start position, quantity, mode)
  • Argument start position is optional (defaults to 0).
  • Argument quantity is optional (defaults to 1).
  • Argument mode is optional (defaults to 0).

By default, the Mid() function returns a specified quantity of characters from the start position in string. It is also possible to return characters between two indices by specifying that the function operates in mode 1. When mode 1 is specified, quantity is taken as the end index and the function will return all characters from start, up to, but not including, end.

The start position is 0-based (i.e. the first character is considered position 0). A quantify of -1 returns all characters from the start positionning to the end of string.

Examples mid(12345)
Returns 1, using is the default quantity (1) of characters from the default start position of (0 - the beginning of the string).

mid(12345, 1, 2)

Returns 2 characters beginning at start position 1, which is 23.

mid(12345, 1, 3, 1)

Mode 1 has been specified here, therefore, this returns characters from start position 1, up to, but not including, end position 3, which is 23.

Additional Examples:

(Back to top)   (Function index)

MoveArticles(…)

Takes "The Beatles" and reverses it to "Beatles, The"
Description MoveArticles(string)

The MoveArticles() function is similar to the Swap() function, except that it operates on strings with prefixed articles (such as "The Beatles" or "A Flock of Seagulls".)

Examples MoveArticles(The Beatles)
Moves the article to the end of the name Beatles, The.
(Back to top)   (Function index)

NoArticles(…)

Takes "The Beatles" and returns "Beatles".
Description NoArticles(string)

Available string values:

StringCan be given literally, or refenced via library field or other expression.

Using the user defined list of articles found in Media Center options at "Tree & View > Sorting", the NoArticles() function removes any articles from a given string.

Examples NoArticles([Artist])
Returns the artist with any articles in the user defined list removed.
(Back to top)   (Function index)

PadLeft(…)

Pads any given string to the left, with any given amount of any given character.
Description PadLeft(value, characters, padding)
  • Argument padding is optional (defaults to " " (space)).
Value is the value you wish to pad. This can be given literally, or sourced from a given library field.
Characters is required and specifies how much padding is to be applied.
Padding is the string you wish to pad with. This can be given literally, or sourced from a given library field. If not specified, this will default to a single space.

See also: PadNumber()

Examples PadLeft(1,3)
Returns: "   1" (without the quotes). No padding value has been specified, therefore, the function pads with spaces by default.

PadLeft(1,3,0)

Returns: 0001

PadLeft(1,3,Padding-)

Returns: Padding-Padding-Padding-1
(Back to top)   (Function index)

PadRight(…)

Pads any given string to the right, with any given amount of any given character.
Description PadRight(value, characters, padding)
  • Argument padding is optional (defaults to " " (space)).
Value is the value you wish to pad. This can be given literally, or sourced from a given library field.
Characters is required and specifies how much padding is to be applied.
Padding is the string you wish to pad with. This can be given literally, or sourced from a given library field. If not specified, this will default to a single space.

See also: PadNumber()

Examples PadRight(1,3)
Returns: "1   " (without the quotes). No padding value has been specified, therefore, the function pads with spaces by default.

PadRight(1,3,0)

Returns: 1000

PadRight(1,3,Padding-)

Returns: 1Padding-Padding-Padding-
(Back to top)   (Function index)

Regex(…)

Regular expression pattern matching and capture.
Description regex(string, regexp, run mode, case sensitivity)

The Regex() function performs regular expression (RE) pattern matching on a string. The string is evaluated against the regular expression regexp, and run mode dictates the values output by Regex(). The three modes allow for match testing, capture output, silent operation or return all captures in a semicolon delimited string.

Up to 9 match captures, one for each capture group, are placed into special variables referenced as [R1], [R2], ... [R9], which can be used in later in the expression. The contents of the captures [R1] ... [R9] are available until the end of the expression, or Regex() is run again, whereby they are replaced.

Additional information is available regarding the full syntax and other implementation details.

Available run mode values:

0Runs in Boolean test mode, returning either a 1 or 0, indicating whether the string matched (1) or did not match (0) the regexp. This run mode is useful within an If() test, so that different true or false actions may be taken.
1 to 9Outputs the specified Nth capture group's contents, where N ranges from 1 to 9. Only a single capture is output in this mode, but all captures are available in the [R1] ... [R9] capture variables. This run mode is used to easily output a single matching sub-string.
-1Runs in silent mode, with no output being produced. This run mode is useful as a means to capture portions of the string to be later used in subsequent portions of an expression.
-2Outputs all captures as a semi-colon delimited list.

The case sensitivity argument toggles the case-sensitivity of regular expression matching. Note that case insensitivity does not apply to characters inside a character class [ ]. Use both uppercase and lowercase characters when necessary to match either case (e.g. [aAbB] to match either uppercase or lowercase A or B).

Available case sensitivity values:

0Ignore case when matching (e.g. the letters E and e are identical)
1Consider case when matching (e.g. the letters E and e are considered different)

The regular expression language assigns special meaning to many characters. A few of these meta-characters, such as forward slash /, comma , and both ( and ) are also reserved and used by the Media Center expression language. To force the Media Center expression engine to ignore the meta-characters in regexp, surround the entire regular expression with /# #/. This is one of Media Center's escapements, which tells the expression engine to ignore everything inside, so that the entire, uninterpreted regexp can be provided to the Regex() regular expression evaluator. Although surrounding regexp by /# #/ is not necessary or required when no conflicting characters are in use, and you may manually escape the expression languages meta-characters with a forward slash /, it is probably a safe practice to always encase every regexp within /# #/.

Argument run mode is optional (defaults to 0). Argument case sensitivity is optional (defaults to 0).

Important Notes
Proficient users of Regex should be aware of the following points regarding Media Center's implementation:

1: The Regex() function will ONLY return results for things that are explicitly placed in a capture group, for example:
[\w\s]+ is a recognised regular expression, however, in order for this to work in Media Center, it must be modified, like so: ([\w\s]+)
Putting parens around it creates a capture group, and that is the only way MC will return a result.

2: All Regex() modes except -2 will return exactly one result for each defined capture group.

3: Care must be taken when working with strings of indeterminate length, or lists with an indeterminate number of elements, as if you have more capture groups in your expression than there exist matches in the string, Regex() will return nothing at all.

Regex mode -2 was devised specifically to get around the above issues, without which, it would be almost impossible to deal with lists with a variable number of elements.

Examples ifelse(regex([name], /#^(the|an|a)\b#/, 0, 1), Fix your case!)

Searches the name field for any of the lowercase articles the, and and a at the beginning of name, and outputs Fix your case! when the match succeeds. The run mode is 0 which is a test and capture mode, and case sensitivity is enabled.

if(regex([artist], /#([[:punct:]])#/, 0), [R1] --> [Artist], No Punctuation)

Using the default mode 0, Regex() will output a Boolean for use inside a conditional to cause some action to occur based on the match success or failure. This example matches against the artist field looking for any punctuation character. If the match succeeds (a punctuation character was found), that character is output followed by the string --> and the artist. In there was no match, the string No Punctuation is output.

regex(D03T02 some track.mp3, /#^D(\d+)T(\d+)#/, 1)Disc: [R1], Track: [R2]

The string is matched against the regexp that is looking for a D followed by any number of digits, followed by a T and then more digits. Those digits were captured, and later used to output the value Disc: 03, Track: 02.

regex([filename (name)], /#^(\d+)-#/, -1)Track number is [R1]

Using run mode -1, the file's name is pattern tested against the regexp which is looking for leading digits followed by a dash. Those digits are captured in buffer [R1] which is used later in the expression. If the file name was 2-foo.mp3, the output would be Track number is 2.

regex([filename], /#(\d{1,2})\.(\d{1,2}).(\d{4})#/, -1)[R3]//[R1]//[R2]

Matches and captures a date formatted as dd.mm.yyyy anywhere within the filename, and rearranges it in a standard format of yyyy/mm/dd. Since run mode is -1, no output occurs. However, captured match segments are made available for subsequent use. The three captures, [R1], [R2] and [R3] are arranged in the textual output so that we get the desired year/month/day ordering, such as 2011/08/19.

Regex([Actors],/#([\w\s\.]+(?=\s\[))#/,-2)

Where [Actors] is a semicolon delimited list of indeterminate length, and each list item contains the actor names followed by the character played in square brackets. For example:
For an [Actors] field containing:
F. Murray Abraham [Antonio Salieri];Tom Hulce [Wolfgang Amadeus Mozart];Elizabeth Berridge [Constanze Mozart];Roy Dotrice [Leopold Mozart];Simon Callow [Emanuel Schikaneder];Christine Ebersole [Katerina Cavalieri];Jeffrey Jones [Emperor Joseph II];Barbara Bryne [Mrs. Weber], this regular expression example will return:

F. Murray Abraham;Tom Hulce;Elizabeth Berridge;Roy Dotrice;Simon Callow;Christine Ebersole;Jeffrey Jones;Barbara Bryne

(Back to top)

RemoveCharacters(…)

Removes a list of characters from a string.
Description removecharacters(string, character list, mode)

The RemoveCharacters() function will remove from string any characters in the character list. The characters removed depend upon the mode specified. The function operates in a case-sensitive manner.

Available mode values:

0Remove all instances
1Remove from the beginning only
2Remove from the end only
3Remove from each end

Argument mode is optional (defaults to 0).

Examples removecharacters(Paper, Ppr)

Removes P, p, and r from Paper, resulting in ae. The default mode 0 is in effect, removing all instances of the characters specified in the character list.

removecharacters(Paper, Ppr, 1)

With mode 1 set, only the initial character P is removed, resulting in aper.

removecharacters(Paper, Ppr, 2)

In mode 2, only one character from the end of the string are removed, leaving "Pape.

removecharacters(Paper, Ppr, 3)

Both the front and back are affected in mode 3, causing the removal of the leading P and trailing r resulting in ape.

removecharacters([artist], /(/))

Removes any ( and ) characters from anywhere within the [artist] field.

(Back to top)

RemoveLeft(…)

Trims characters from the beginning of a string.
Description removeleft(string, quantity)

The RemoveLeft() function removes a specified quantity of characters from the left side of a string. If the quantity is larger than the length of the string, the output will be empty.

Examples removeleft(Good Deeds, 5)

Removes the first 5 characters from resulting in Deeds being output.

(Back to top)

RemoveRight(…)

Trims characters from the end of a string
Description removeright(string, quantity)

The RemoveRight() function removes a specified quantity of characters from the right side of a string. If the quantity is larger than the length of the string, the output will be empty.

Examples removeright(03-02-1959,5)

Removes the last 5 characters from the given date, leaving only the month and year 03-02.

(Back to top)

Replace(…)

Replace or remove a string segment.
Description Replace(String, Find, Replace, Mode)
  • Argument Replace is optional (defaults to empty).
  • Argument Mode is optional (defaults to 0).

Available mode values:

0Case Sensitive
1Case Insensitive

The Replace() function replaces all instances of Find within String, with Replace. If Replace is unspecified, it defaults to an empty value, causing Find to be removed. By default, Replace() operates in a case-sensitive manner, but can be switched to case-insensitive operation by specifying Mode 1.

Examples Replace(The Daily Show with John Oliver, hn Oliver, n Stewart)
Returns Daily Show with Jon Stewart


Replace(Led Zeppelin.[remastered], .[remastered])

Returns Led Zeppelin. As no Replace value is specified, the default empty value is used as a replacement, effectively removing all instances of Find.


Replace(Abba,a)

Returns Abb. No Replace value is specified, so any matches are removed. Also, no Mode is specified, so Find is case-sensitive.


Replace(Abba,a,,1)

Returns bb. No Replace value is specified, so any matches are removed. Also, Mode 1 is specified, so Find is case-insensitive.
(Back to top)   (Function index)

|- valign="top" ! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 0px 1px 2px 2px; border-top: 1px solid #bbb; border-right: 1px solid #bbb;" | Examples |style="background: #f9f9f9; color: #111; border-style: solid; border-width: 0px 2px 2px 0; border-top: 1px solid #bbb;" | replace(The Daily Show with John Oliver, hn Oliver, n Stewart)

Now that John Oliver has completed his summer stand-in for Jon Stewart, it is time for a replacement. The old sequence hn Oliver will be replaced with the new sequence n Stewart, resulting in The Daily Show with Jon Stewart.

replace(Sample String, s, Replaced)

In this example, the original string does not contain the old value s anywhere, so no replacement occurs and the original string is returned.

replace(Led Zeppelin.[remastered], .[remastered])

Removes the trailing old value .[remastered] from the original string, resulting in Led Zeppelin. Because no new string is specified, the default empty value is used as a replacement, effectively stripping the old value.

|}

(Back to top)

Right(…)

Retrieves a specified number of characters from the right of a string.
Examples right([filename], 3)

Returns the last three characters from the filename (typically this is the file's suffix).

(Back to top)

Swap(…)

Takes Firstname Lastname and swaps to Lastname, Firstname.
Description Swap(string)

The Swap() function is used to reverse the order of a personal name in a string (converting Firstname Lastname into Lastname, Firstname). The function has special handling for strings that end with Jr., Sr., I, II, III, IV, V (so that these common suffixes are handled properly), and it can also handle semicolon-delimited string lists (such as [Artist], [Actors], and [Director]).

Examples swap(Paul Simon)
Reverses the lexical order of the name to Simon, Paul.

swap(Sammy Davis Jr.)

Handles most common name suffixes and results in Davis, Sammy Jr.

swap(Paul Simon; Art Garfunkel)

Reverses the lexical order of the list of names to Simon, Paul; Garfunkel, Art.
(Back to top)   (Function index)

Trim(…)

Removes leading and trailing non-printable characters and new lines from a given string.
Description Trim(string)

The Trim() function takes any given string, removing any leading and trailing non-printable characters and new lines

Examples Trim([Lyrics])
(Back to top)   (Function index)

TrimLines(…)

Removes leading, trailing and double new lines from a given string.
Description TrimLines(string, mode)
  • Argument mode is optional (defaults to 3).

The TrimLines() function can remove leading, trailing and double newlines from a given string, which can be given literally or as a library field. The function's mode defaults to removing all three, mode 3. Available mode values:

1Trims double new lines.
2Trims leading and trailing new lines
3Trims leading, trailing and double new lines
4Trims 3 or more new lines to double new lines
Examples TrimLines([Lyrics])
Defaults to mode 3, removing all leading, trailing and double new lines.

TrimLines([Lyrics],2)

Removes leading and trailing new lines.
(Back to top)   (Function index)

UnMoveArticles(…)

Takes "Beatles, The" and reverses it to restore the normal word order, "The Beatles"
Description UnMoveArticles(string)

The UnMoveArticles() function is the opposite of the MoveArticles() function. It is used to restore the normal order of an band name with a prefix article in a string (converting Beatles, The into The Beatles).

Examples UnMoveArticles(Flock of Seagulls, A)
Restores the normal order of the name to A Flock of Seagulls.

Please Note: These examples were simplified and ignore the commas in the string arguments. For these expressions to work properly (when entered directly), you would need to escape the comma in the string literal: UnMoveArticles(Beatles/, The). However, this function is typically used with a field value (or the output of another function), and would therefore be treated as a single argument even if the resulting string contains a comma. See Function Arguments for further details.

(Back to top)   (Function index)

Unswap(…)

Takes Lastname, Firstname and reverses it to Firstname Lastname.
Description Unswap(string)

The Unswap() function is the opposite of the Swap() function. It is used to restore the normal western-style order of a personal name in a string (converting Lastname, Firstname into Firstname Lastname). This command also works properly with semicolon-delimited list data (such as the [Artist] field), and like the Swap() command, it handles common name suffixes such as Jr., Sr., I, II, III, IV, V, etc.

Examples Unswap(Simon, Paul)
Reverses the lexical order of the name to Paul Simon.

Unswap(Simon, Paul; Garfunkel, Art)

Reverses the lexical order of the name list to Paul Simon; Art Garfunkel.

Please Note: These examples were simplified and ignore the commas in the string arguments. For these expressions to work properly (when entered directly), you would need to escape the comma in the string literal: Unswap(Simon/, Paul; Garfunkel/, Art). However, this function is typically used with a field value (or the output of another function), and would therefore be treated as a single argument even if the resulting string contains a comma. See Function Arguments for further details.

(Back to top)   (Function index)

Urlify(…)

Takes a string and applies html formatting for browser consumption
Description Urlify(string)

The Urlify() function takes a given string and outputs with HTML formatting suitable for browser consumption. This function is typically used by expressions generating or working on URLs in Media Center's Link Manager. It does not apply full formatting, for example, spaces remain as spaces, therefore, better mileage may be found using the Hexify() function.

Examples https:////www.metacritic.com//search//movie//urlify(Fast & Furious Presents: Hobbs & Shaw)//results
Returns: https://www.metacritic.com/search/movie/Fast &amp; Furious Presents: Hobbs &amp; Shaw/results.
(Back to top)   (Function index)