ReNamer:Pascal Script:Functions

Introduction

ReNamer has many procedures and functions to manipulate the entities related to file names. These entities may be derived from the existing filename, path, system date, meta tags from the file, strings entered by the user, etc.

A common prefix Wide in the function name indicates that the function deals with Unicode strings (WideString). The prefix is used because there are similar functions which deal with Ansi strings and in some cases simply for internal consistency. For example: ShowMessage and WideShowMessage procedures.

??? What is T prefix?
??? What is UTF8?

Basic String Handling Routines

Routine	Remarks
procedure Insert(Source: String; var S: String; Index: Integer);	Inserts the string S into string Source at position Index.
procedure Delete(var S: String; Index, Count: Integer);	Deletes Count characters from the string S, starting from position Index.
function Copy(S: String; Index, Count: Integer): String;	Copies Count characters from string S, starting at position Index, and returns them as a new string.
function Pos(Substr: String; S: String): Integer;	Returns the position of a string Substr in another string S.

Note: Indexes of characters in strings are 1 based, so first character in string S would be S[1].

Length Managing Routines

Routine	Remarks
procedure SetLength(var S: Array; NewLength: Integer);	Sets the length of array variable S to NewLength.
procedure SetLength(var S: String; NewLength: Integer);	Sets the length of string variable S to NewLength.
procedure SetLength(var S: WideString; NewLength: Integer);	Sets the length of widestring S to NewLength.
function Length(const S: Array): Integer;	Returns the length of array S (number of elements).
function Length(const S: String): Integer;	Returns the length of string S (number of characters).
function Length(const S: WideString): Integer;	Returns the length of WideString S (number of characters).

Unicode String Handling Routines

Routine	Remarks
procedure WideInsert(const Substr: WideString; var Dest: WideString; Index: Integer);	Inserts Substr in Dest at position Index.
procedure WideDelete(var S: WideString; Index, Count: Integer);	Deletes Count characters from S, starting from the Index position.
procedure WideSetLength(var S: WideString; NewLength: Integer);	Change the length of string S to a new length specified by NewLength. If new length is smaller than original, the string is truncated. If new length is greater than original, the string will be expanded but additional characters will not be initialized and can be anything.
function WideLength(const S: WideString): Integer;	Returns the length of WideString S.
function WideCopy(const S: WideString; Index, Count: Integer): WideString;	Returns Count characters from WideString S, starting at position Index.
function WidePos(const SubStr, S: WideString): Integer;	Find and occurrence of SubStr in S. Returns the position of first occurrence, or 0 if nothing was found.
function WidePosEx(const SubStr, S: WideString; Offset: Cardinal): Integer;	Find and occurrence of SubStr in S but start searching from position specified by Offset. Returns the position of first occurrence, or 0 if nothing was found.
function WideUpperCase(const S: WideString): WideString;	Returns the ALLCAPS version of the WideString S
function WideLowerCase(const S: WideString): WideString;	Returns the lowercase version of the WideString S
function WideCompareStr(const S1, S2: WideString): Integer;	Compares two WideStrings S1 and S2, case-sensitive, and returns an integer based on the result. The return value is less than 0 if S1 is less than S2, 0 if S1 equals S2, or greater than 0 if S1 is greater than S2.
function WideCompareText(const S1, S2: WideString): Integer;	Compares two WideStrings S1 and S2, case-insensitive, and returns an integer based on the result. The return value is less than 0 if S1 is less than S2, 0 if S1 equals S2, or greater than 0 if S1 is greater than S2.
function WideSameText(const S1, S2: WideString): Boolean;	Compares two WideStrings S1 and S2. Returns TRUE if both are identical, otherwise returns FALSE.
function WideTextPos(const SubStr, S: WideString): Integer;	Behaves like WidePos function, except text if processed in case-insensitive manner.
function WideTrim(const S: WideString): WideString;	Removes leading and trailing spaces and control characters from the given string S.
function WideReplaceStr(const S, OldPattern, NewPattern: WideString): WideString;	???
function WideReplaceText(const S, OldPattern, NewPattern: WideString): WideString;	???
function WideSplitString(const Input, Delimiter: WideString): TStringsArray;	Splits the WideString Input wherever Delimiter occurs, and returns an array that contains the split parts. The Delimiter itself can be a multi-character WideString. (Unlike the usual comma, hyphen or space that is used for this purpose) The split parts (returned as elements of the array) do not contain the Delimiter WideString
function WideCaseCapitalize(const S: WideString): WideString;	Returns the Sentence case version of the WideString S. Only the first alphabetic character is capitalized. All other alphabetic characters are converted to lowercase. If S begins with numeric characters, the first alphabetic character that follows will be capitalized.
function WideCaseInvert(const S: WideString): WideString;	Inverts the case of all characters in the WideString S and returns the WideString.

Meta Tags Extraction

Function	Remarks
function CalculateMetaTag(const FilePath: WideString; const MetaTagName String): String;	Extracts and returns the value of a metatag specified by MetaTagName from the file specified by the complete absolute path FilePath.

For example, to extract EXIF_Date tag from an image and set it to the filename, one can use something like this:

begin
  FileName := CalculateMetaTag(FilePath, 'EXIF_Date');
end.

The full list of meta tags can be found in Meta Tags article.

Regular Expressions

Function	Remarks
function ReplaceRegEx(const Input, Find, Replace: WideString;const CaseSensitive, UseSubstitution: Boolean): WideString;	Find-and-replace function using RegEx. Works like RegEx rule.
function MatchesRegEx(const Input, Find: WideString;const CaseSensitive: Boolean): TStringsArray;	Returns a list of RegEx matches as an array. Function returns an array of full matches, which matched the entire expression, not the sub-patterns.
function SubMatchesRegEx(const Input, Find: WideString;const CaseSensitive: Boolean): TStringsArray;	This function is very similar to MatchesRegEx, but instead of returning full expression matches it will return an array of sub-expression matches for the first full expression match. For example, *SubMatchesRegEx('one two three', '(.) (.) (.)') will return an array ['one', 'two', 'three']. In this way, it can easily be combined with MatchesRegEx function, to allow users to find all global matches, and then parse those matches through SubMatchesRegEx** function to find individual sub-expression matches of each global match.

General parameters of the functions:

Input - The WideString that is input to the function.
Find - RegEx pattern to be found (same as Expression field in the RegEx rule).
Replace - Replacement string (same as the Replace field in the RegEx rule).
CaseSensitive - Specifies whether to process in a case-sensitive mode.
UseSubstitution - Determines whether use backreferences in the result.

Unicode Character Handling Routines

Function	Remarks
function IsWideCharUpper(WC: WideChar): Boolean;	Checks a Unicode character WC and returns TRUE if it is in UPPERCASE.
function IsWideCharLower(WC: WideChar): Boolean;	Checks a Unicode character WC and returns TRUE if it is in lowercase.
function IsWideCharDigit(WC: WideChar): Boolean;	Checks a Unicode character WC and returns TRUE if it is a digit (numeric character 0-9).
function IsWideCharSpace(WC: WideChar): Boolean;	Checks a Unicode character WC and returns TRUE if it is a white-space character, such as: space, form-feed, newline, carriage-return, tab and vertical-tab (characters classified as C1_SPACE).
function IsWideCharPunct(WC: WideChar): Boolean;	Checks a Unicode character WC and returns TRUE if it is a punctuation mark (characters classified as C1_PUNCT).
function IsWideCharCntrl(WC: WideChar): Boolean;	Checks a Unicode character WC and returns TRUE if it is a control character (characters classified as C1_CNTRL).
function IsWideCharBlank(WC: WideChar): Boolean;	Checks a Unicode character WC and returns TRUE if it is a blank, such as: space and tab (characters classified as C1_BLANK).
function IsWideCharXDigit(WC: WideChar): Boolean;	Checks a Unicode character WC and returns TRUE if it is a hexadecimal digit (0-9 or A-F).
function IsWideCharAlpha(WC: WideChar): Boolean;	Checks a Unicode character WC and returns TRUE if it is a alphanumeric character (a-z or A-Z).
function IsWideCharAlphaNumeric(WC: WideChar): Boolean;	Checks a Unicode character WC and returns TRUE if it is a alphanumeric character or a numeric character (a-z, A-Z or 0-9).
function WideCharUpper(const WC: WideChar): WideChar;	Returns a UPPERCASE version of the input Unicode character. In case of non-alphabetic character, it returns the same character.
function WideCharLower(const WC: WideChar): WideChar;	Returns a lowercase version of the input Unicode character. In case of non-alphabetic character, it returns the same character.

Note: Character classifications, such as C1_UPPER, C1_LOWER, C1_DIGIT, C1_SPACE, C1_PUNCT, C1_CNTRL, C1_BLANK, C1_XDIGIT, C1_ALPHA - are part of Unicode definitions. More information regarding classification can be found on the internet. For example: http://www.fileformat.info/info/unicode/.

Unicode Conversion Routines

Function	Remarks
function WideToAnsi(const WS: WideString): String;	Converts a Unicode string to its ANSI version.
function AnsiToWide(const S: String): WideString;	Converts a ANSI string to its Unicode version.
function UTF8Encode(const WS: WideString): String;	Convert Unicode string to the UTF-8 encoded string. Useful to storing Unicode strings in files.
function UTF8Decode(const S: String): WideString;	Convert UTF-8 encoded string to its full Unicode representation.

Basic Conversion Routines

Function	Remarks
function IntToStr(Value: Integer): String;	Converts an integer to a string. The following assumptions are correct: IntToStr(123) = '123' IntToStr(0123) = '123' IntToStr(123) <> '0123'
function StrToInt(const S: String): Integer;	Converts a string to an integer. The following equality is correct: StrToInt('123') = 123 StrToInt('123') = 0123 StrToInt('0123') = 123 Warning: An error will occur if the parameter to this function cannot be converted to an integer!
function StrToIntDef(const S: String; const Default: Integer): Integer;	Behaves like StrToInt function, but instead of producing an error on incorrect input function allows the Default value to be specified, which will be returned if the input cannot be converted to an integer.
function DateToStr(D: TDateTime): String;	Converts a date to a string, using system format for the short date, for example: dd/mm/yyyy.
function StrToDate(const S: String): TDateTime;	Converts a date string to a proper TDateTime value, using system format for the short date, for example: dd/mm/yyyy.
function IntToHex(Value: Integer; Digits: Integer): String;	Converts an integer to its hexadecimal representation. Here are samples: IntToHex(1234, 1) = '4D2' IntToHex(1234, 8) = '000004D2'
function HexToInt(const HexNum: String): Integer;	Converts a hexadecimal value to its decimal representation. Warning: An error will occur if the parameter to this function cannot be converted to an integer!
function HexToIntDef(const HexNum: String; Default: Integer): Integer;	Behaves like HexToInt function, but instead of producing an error on incorrect input function allows the Default value to be specified, which will be returned if the input cannot be converted to an integer.
function Ord(X: Char): Byte;	Return an ordinal value (byte representation) of a character.
function Chr(X: Byte): Char;	Return a character by its ordinal value (byte representation).

Date And Time Routines

Function	Remarks
function Date: TDateTime;	Returns the current system date.
function Time: TDateTime;	Returns the current system time.
function Now: TDateTime;	Returns the current system date and time.
function EncodeDate(Year, Month, Day: Word): TDateTime;	Generates date value for the specified Year, Month, Day. Parameters must be within a valid date range: Year = 0..9999, Month = 1..12, Day = 1..31 (depending on month/year). An error will be raised if parameters are invalid.
function EncodeTime(Hour, Min, Sec, MSec: Word): TDateTime;	Generates time value for the specified Hour, Min, Sec, MSec. Parameters must be within a valid time range: Hour = 0..23, Min = 0..59, Sec = 0..59, MSec = 0..999. An error will be raised if parameters are invalid.
function TryEncodeDate(Year, Month, Day: Word; var Date: TDateTime): Boolean;	Behaves exactly like EncodeDate function, except this function returns the TRUE or FALSE depending on the success of the operation. If operation was successful, function will return TRUE and the generated date value will be written in the Date variable.
function TryEncodeTime(Hour, Min, Sec, MSec: Word; var Time: TDateTime): Boolean;	Behaves exactly like EncodeTime function, except this function returns the TRUE or FALSE depending on the success of the operation. If operation was successful, function will return TRUE and the generated time value will be written in the Time variable.
procedure DecodeDate(const DateTime: TDateTime; var Year, Month, Day: Word);	Extracts Year, Month and Day components from a given DateTime value.
procedure DecodeTime(const DateTime: TDateTime; var Hour, Min, Sec, MSec: Word);	Extracts Hour, Min, Sec and MSec components from a given DateTime value.
function DayOfWeek(const DateTime: TDateTime): Word;	Returns the day of the week (as an index) for the specified DateTime value. The indexes are: 1 = Sunday, 2 = Monday, 3 = Tuesday, 4 = Wednesday, 5 = Thursday, 6 = Friday, 7 = Saturday.
function DateTimeToUnix(D: TDateTime): Int64;	Converts D value of type TDateTime to a Unix timestamp.
function UnixToDateTime(U: Int64): TDateTime;	Converts a Unix timestamp to a value of TDateTime type.
function FormatDateTime(const Fmt: String; D: TDateTime): String;	This function provides rich formatting of a DateTime value into a string. Date and time format is defined by the Fmt string.
function IncYear(const AValue: TDateTime;const ANumberOfYears: Integer): TDateTime;
function IncMonth(const AValue: TDateTime;ANumberOfMonths: Integer): TDateTime;
function IncWeek(const AValue: TDateTime; const ANumberOfWeeks: Integer): TDateTime;
function IncDay(const AValue: TDateTime;const ANumberOfDays: Integer): TDateTime;
function IncHour(const AValue: TDateTime;const ANumberOfHours: Int64): TDateTime;
function IncMinute(const AValue: TDateTime;const ANumberOfMinutes: Int64): TDateTime;
function IncSecond(const AValue: TDateTime;const ANumberOfSeconds: Int64): TDateTime;
function IncMilliSecond(const AValue: TDateTime;const ANumberOfMilliSeconds: Int64): TDateTime;

File Management Routines

Function	Remarks
function WideFileSize(const FileName: WideString): Int64;
function WideFileExists(const FileName: WideString): Boolean;
function WideDirectoryExists(const Directory: WideString): Boolean;
function WideForceDirectories(Dir: WideString): Boolean;
function WideCreateDir(const Dir: WideString): Boolean;
function WideDeleteFile(const FileName: WideString): Boolean;
function WideRenameFile(const OldName, NewName: WideString): Boolean;
function WideFileSearch(const Name, DirList: WideString): WideString;
function WideGetCurrentDir: WideString;
function WideSetCurrentDir(const Dir: WideString): Boolean;
procedure WideScanDirForFiles(Dir: WideString; var Files: TStringsArray;const Recursive, IncludeHidden, IncludeSystem: Boolean; const Mask: WideString);
procedure WideScanDirForFolders(Dir: WideString; var Folders: TStringsArray;const Recursive, IncludeHidden, IncludeSystem: Boolean);

File Name Utilities

Function	Remarks
function WideExtractFilePath(const FileName: WideString): WideString;	Returns the entire path of the file (starting from the drive letter)
function WideExtractFileDir(const FileName: WideString): WideString;	Returns the folder in which the file is located.
function WideExtractFileDrive(const FileName: WideString): WideString;	Returns the drive letter ???or is it the name of the drive?
function WideExtractFileName(const FileName: WideString): WideString;	Returns the filename with extension. (e.g. "FileName.txt")
function WideExtractBaseName(const FileName: WideString): WideString;	Returns only the file' base name (but not the dot or extension). (e.g. "FileName")
function WideExtractFileExt(const FileName: WideString): WideString;	Returns the file's extension with the dot (e.g. ".txt")
function WideChangeFileExt(const FileName, Extension: WideString): WideString;	Replaces the original extension, and returns the new filename with extension. (e.g. "FineName.txt" -> "FineName.pdf")
function WideStripExtension(const FileName: WideString): WideString;	Strips off the extension from the filename. ??? what does it return?
function WideExpandFileName(const FileName: WideString): WideString;	???
function WideExtractRelativePath(const BaseName, DestName: WideString): WideString;	Given two files lacated in two different folders, returns the relative path of DestName file with respect to the BaseName file. e.g. If we input these two filenames: D:\Folder1\FileName1.txt (The base file) D:\Folder2\Folder22\FileName2.pdf (The destination file) Then the relative path of the destination file is- ..\Folder2\Folder22\FileName2.pdf
function WideExtractShortPathName(const FileName: WideString): WideString;
function WideIncludeTrailingPathDelimiter(const S: WideString): WideString;
function WideExcludeTrailingPathDelimiter(const S: WideString): WideString;
function WideSameFileName(const S1, S2: WideString): Boolean;	Compares the filenames S1 and S2, and returns TRUE if they are identical.
function WideGetEnvironmentVar(const VarName: WideString): WideString;

File Read/Write Routines

Function	Remarks
function FileReadFragment(const FileName: WideString; Start, Length: Integer): String;	Starting at position Start, read Length number of characters of the file FileName and return them as a string. Start is 0-based, so in order to start the fragment at the beginning of the file, set this parameter to 0 (zero).
function FileReadLine(const FileName: WideString; LineNum: Integer): String;	Read a line from a file FileName specified by a line index LineNum. LineNum is 1 based, so to get the first line set this parameter to 1 (one).
function FileCountLines(const FileName: WideString): Integer;
function FileReadContent(const FileName: WideString): String;
procedure FileWriteContent(const FileName: WideString; const Content: String);
procedure FileAppendContent(const FileName: WideString; const Content: String);

File Properties Routines

Function	Remarks
function FileTimeModified(const FileName: WideString): TDateTime;
function FileTimeCreated(const FileName: WideString): TDateTime;
function SetFileTimeCreated(const FileName: WideString;const DateTime: TDateTime): Boolean;
function SetFileTimeModified(const FileName: WideString;const DateTime: TDateTime): Boolean;

Process Execution Routines

Function	Remarks
function ShellOpenFile(const FileName: WideString): Boolean;
function ExecuteProgram(const Command: String; WaitForProgram: Boolean): Cardinal;
function ExecConsoleApp(const CommandLine: String; out Output: String): Cardinal;

Interactive Dialogs

Function	Remarks
procedure ShowMessage(const Msg: String);
procedure WideShowMessage(const Msg: WideString);
function DialogYesNo(const Msg: String): Boolean;
function WideDialogYesNo(const Msg: WideString): Boolean;
function InputBox(const ACaption, APrompt, ADefault: String): String;
function InputQuery(const ACaption, APrompt: String; var Value: String): Boolean;
function WideInputBox(const ACaption, APrompt, ADefault: WideString): WideString;
function WideInputQuery(const ACaption, APrompt: WideString;var Value: WideString): Boolean;

Other Routines

Function	Remarks
procedure Randomize();
procedure Sleep(Milliseconds: Cardinal);	Sleeps (waits) for specified miliseconds
procedure DivMod(Dividend: Integer; Divisor: Word; var Result, Remainder: Word);
procedure SetClipboardText(const S: WideString);
function GetClipboardText: WideString;
function RandomRange(const AFrom, ATo: Integer): Integer;
function Base64Encode(const S: String): String;
function Base64Decode(const S: String): String;
function GetTickCount: Cardinal;
function SizeOf(X): Integer;