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 renamig 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 other 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:

Expression Result
number_to_words( dataset_field_val(1, 'pay_sum'), 'en-US', 'UnitsSubunitsSeparator= and |CurrencyCode=USD|SubunitsDimension=2|ShowZeroSubunits=true' )  
number_to_words( 3467.35, 'en-US', 'UnitsSubunitsSeparator= and |CurrencyCode=USD|ShowZeroSubunits=true' ) three thousand four hundred sixty seven dollars and 35 cents
number_to_words( 3467.35, 'en-US', 'UnitsSubunitsSeparator= and |SubunitsDimension=4|ShowZeroSubunits=true' ) three thousand four hundred sixty seven and 3500
remove_digits( Str String ): String Removes digits from a string Str
digits_only( Str String ): String Removes non-digit characters from a string Str