Rename Us Users' Guide vlsoftware.net

Functions, available in expressions

 Contents Index Previous Next

Rename Us expression engine allows you to execute Pascal-like expressions, which can be used in renaming actions.

The expressions can consist of functions (nesting of any depth), arithmetical and logical operators, and literals (numeric, string, or boolean). Expression returns one value of numeric, string, or boolean type.

Notes

1. Names of functions and operators are case insensitive.

2. Parameters of parameterized functions may be constants (literals) or expressions.

3. String literals must be enclosed in single quotes. If a literal includes quote marks, each of them must be doubled.

4. Multi-line string literals are not allowed. If you want to pass big text as parameter, you can split it on less separate string literals and concatenate them using + operator.

Functions

Functions concerning current file in the thread

<CURRENT_NAME>
Returns current name. For the first action in action list, this will be file name (extension). For next actions, this will be the result of the previous action.
<FILE_PATH>
Returns full file path.
<FILENO>
Returns file number in the project file list.
<INITIAL_NAME>
Returns the initial file name or extension (i.e. name before performing the first action).
<MP3TAG_ALBUM>
Returns the contents of the Album tag of MP3 file (only for files, which have .mp3 or .ape extension).
<MP3TAG_ARTIST>
Returns the contents of the Artist tag of MP3 file (only for files, which have .mp3 or .ape extension).
<MP3TAG_COMMENT>
Returns the contents of the Comment tag of MP3 file (only for files, which have .mp3 or .ape extension).
<MP3TAG_COMPOSER>
Returns the contents of the Composer tag of MP3 file (only for files, which have .mp3 or .ape extension).
<MP3TAG_COPYRIGHT>
Returns the contents of the Copyright tag of MP3 file (only for files, which have .mp3 or .ape extension).
<MP3TAG_ENCODER>
Returns the contents of the Encoder tag of MP3 file (only for files, which have .mp3 or .ape extension).
<MP3TAG_GENRE>
Returns the contents of the Genre tag of MP3 file (only for files, which have .mp3 or .ape extension).
<MP3TAG_TITLE>
Returns the contents of the Title tag of MP3 file (only for files, which have .mp3 or .ape extension).
<MP3TAG_TRACK>
Returns the contents of the Track tag of MP3 file (only for files, which have .mp3 or .ape extension).
<MP3TAG_URL>
Returns the contents of the URL tag of MP3 file (only for files, which have .mp3 or .ape extension).
<MP3TAG_YEAR>
Returns the contents of the Year tag of MP3 file (only for files, which have .mp3 or .ape extension).

Mathematical

abs( x Numeric ): Numeric
Returns an absolute value of numeric x
frac( x Numeric ): Numeric
Returns fractional part of numeric x
int( x Numeric ): Numeric
Returns integer part of numeric x
round( x Numeric ): Numeric
Returns the value of numeric x rounded to the nearest whole number
sqrt( x Numeric ): Numeric
Returns square root of numeric x
power( x Numeric, y Numeric ): Numeric
Raises numeric base x to numeric power y
exp( x Numeric ): Numeric
Returns the exponential of numeric x
ln( x Numeric ): Numeric
Returns the natural (base e) logarithm of numeric x
cos( x Numeric ): Numeric
Returns the cosine of numeric x, where x is given in radians
sin( x Numeric ): Numeric
Returns the sine of numeric x, where x is given in radians
tan( x Numeric ): Numeric
Returns the tangent of numeric x, where x is given in radians
atan( x Numeric ): Numeric
Returns the arc tangent of numeric x, that is, the value whose tangent is x

Date and time

date: Date
Returns current date
time: Time
Returns current time
add_date_time( x DateTime, y Numeric ): DateTime
Adds y days to date/time x. y can be an integer or floating-point number. For example, 2.5 means two days and 12 hours.
compare_date_time( Date1 DateTime, Date2 Numeric ): Numeric
Returns an integer indicating the result of comparison of the date/time Date1 and date/time Date2: 0 when Date1 = Date2, 1 when Date1 > Date2, and -1 when Date1 < Date2.
date_time_diff( Date1 DateTime, Date2 DateTime ): Numeric
Returns difference in days (as floating-point number) between date/time Date1 and date/time Date2
format_date_time( x DateTime, Mask String ): String
Formats a date/time x using mask Mask. For example, to display only current month, use date for the first parameter and 'm' or 'mmmm' for the second one.

File related

file_created( FileName String ): DateTime
Returns the date and time the file FileName was created. FileName should be full file path.
file_last_modified( FileName String ): DateTime
Returns the date and time the file FileName was last modified. FileName should be full file path.
file_last_accessed( FileName String ): DateTime
Returns the date and time the file FileName was last accessed. FileName should be full file path.
file_size( FileName String ): Numeric
Returns the size of the file FileName in bytes. FileName should be full file path.
file_version( FileName String ): Numeric
Returns the version of the file FileName. FileName should be full file path.
extract_file_ext( FileName String ): String
Extracts the extension of the file FileName (with period)
extract_file_name( FileName String ): String
Extracts file name from the full file path FileName
extract_file_dir( FileName String ): String
Extracts file path (without \ character at the end) from the full file path FileName
extract_file_path( FileName String ): String
Extracts file path (with \ character at the end) from the full file path FileName
extract_file_text( FileName String ): String
Extracts text from the text file FileName. FileName should be full file path.
file_exists( FileName String ): Boolean
Returns True if file FileName exists, False otherwise
dir_exists( DirectoryName String ): Boolean
Returns True if directory DirectoryName exists, False otherwise

Miscellaneous

to_number( x <AnyType> ): Numeric
Converts x to number
to_string( x <AnyType> ): String
Converts x to string
format_float( x Numeric, Mask String ): String
Formats a numeric x using mask Mask. For example, to always display two decimal places after the floating point, use '0.00' for the second parameter.
lpad( Str String, Count Numeric, Char String ): String
Adds Char characters to the left-side of a string Str. Count is the number of characters to return.
rpad( Str String, Count Numeric, Char String ): String
Adds Char characters to the right-side of a string Str. Count is the number of characters to return.
iif( Condition Boolean, x <AnyType>, y <AnyType> ): <AnyType>
Returns x if Condition evaluates to True, or y in another case
upper( Str String ): String
Converts a string Str to upper case
lower( Str String ): String
Converts a string Str to lower case
capitalize( Str String ): String
Converts first characters of every word in a string Str to upper case
pretty( Str String ): String
Makes the first character of string Str in upper case and the rest in lower case
length( Str String ): Integer
Returns length (count of characters) of a string Str
pos( SubStr String, Str String ): Integer
Returns position of substring SubStr in string Str
substr( Str String, Index Integer, Count Integer ): String
Returns a substring of a string Str, containing Count characters starting at Index position
substr_count( Str String, SubStr String ): Integer
Returns the number of times the substring SubStr occurs in string Str
trim( Str String ): String
Trims leading and trailing spaces and control characters from a string Str
trim_left( Str String ): String
Trims leading spaces and control characters from a string Str
trim_right( Str String ): String
Trims trailing spaces and control characters from a string Str
string_replace( Str String, SubStr Integer, NewSubStr Integer ): String
Replaces all occurancies of substring SubStr with substring NewSubStr in text Str
concat( Str1 String, Str2 Integer ): String
Returns a string that is the result of concatenating string Str1 to string Str2
ordinal_number( x Integer, Language String, Case Integer, Gender Integer ): String

Returns the original number and the ordinal suffix of integer x.

Language is the language in which the result should be represented. Possible values: 'en-US' (American English), 'uk-UA' (Ukrainian).

Case (from 'A' to 'F') and Gender ('M', 'F', 'N') are for Ukrainian language only.
quantitative_numeral( x Integer, Language String, Case Integer, Gender Integer ): String

Returns the quantitative numeral of integer x.

Language is the language in which the result should be represented. Possible values: 'uk-UA' (Ukrainian).

Case (from 'A' to 'F') and Gender ('M', 'F', 'N') are for Ukrainian language only.
number_to_words( x Numeric, Language String, Options String ): String

Converts number x to its representation in words.

Language is the language in which the result should be represented. Possible values: 'en-US' (American English), 'uk-UA' (Ukrainian).

Options is a pipe separated list of options in OptionName=OptionValue format.
Allowed options:
- ShowZeroSubunits. Instructs either to include fractional part of the number if it equals to zero. Possible values: True or False. Default value: False.
- ProcessSubunits. Instructs either to convert fractional part of the number to words. Possible values: True or False. Default value: False.
- UnitsSubunitsSeparator. Specifies a separator between an integer and fractional parts of the number. Default value is a space character.
- SubunitsDimension. Specifies dimension for fractional part of the number. Default value is 2. This option is ignored when ProcessSubunits is True.
- CurrencyCode. Specifies currency code in ISO 4217 format. Currently, only the following currency codes are supported: USD, EUR, UAH. Using this option instructs to interpret the number as currency value and add main currency and fractional currency names (i.e., units and sub-units).
- Type. Specifies the type of the conversion. Possible values: regular, fraction. This option is meaningful only if Language is 'uk-UA'.
- UnitsShortened. Instructs to shorten the main currency name (units) if it is used. This option is meaningful only if Language is 'uk-UA'.
- SubunitsShortened. Instructs to shorten the fractional currency name (sub-units) if it is used. This option is meaningful only if Language is 'uk-UA'.

Examples

1. Output the number 3467.35 as:

three thousand four hundred sixty seven dollars and 35 cents

Solution:

number_to_words( 3467.35, 'en-US', 'UnitsSubunitsSeparator= and |CurrencyCode=USD|ShowZeroSubunits=true' )

2. Output the number 3467.35 as:

three thousand four hundred sixty seven and 3500

Solution:

number_to_words( 3467.35, 'en-US', 'UnitsSubunitsSeparator= and |SubunitsDimension=4|ShowZeroSubunits=true' )
remove_digits( Str String ): String
Removes digits from a string Str
digits_only( Str String ): String
Removes non-digit characters from a string Str
parse( x <AnyType> ): <AnyType>
Calculates and returns the result of the expression x. Its main purpose is to calculate expressions not known in the time of the formula writing, i.e. held in database fields, files etc.
char( x Integer ): String
Converts an ASCII code x to its character value.