den4b Wiki - User contributions [en]

ReNamer:Pascal Script:Functions

2009-08-03T04:33:32Z

Prologician: /* Unicode String Handling Routines */ Noted case insensitivity for WideSameText()

== Introduction ==

ReNamer has many [http://www.taoyue.com/tutorials/pascal/pas4a.html procedures] and [http://www.taoyue.com/tutorials/pascal/pas4c.html 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 [http://en.wikipedia.org/wiki/Unicode 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 ==

{| class="wikitable"
|-
! 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 ==

{| class="wikitable"
|-
! 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 ==

{| class="wikitable"
|-
! 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''', case-insensitive. 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;
|  ???<br>
|-
| function '''WideReplaceText'''(const S, OldPattern, NewPattern: WideString): WideString;
|  ???<br>
|-
| 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. <br>(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.<br>

*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.<br>
|}

== Meta Tags Extraction ==

{| class="prettytable"
|-
! 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:
<pre>
begin
FileName := CalculateMetaTag(FilePath, 'EXIF_Date');
end.
</pre>

The full list of meta tags can be found in [[ReNamer:Meta Tags|Meta Tags]] article.

== Regular Expressions ==

{| class="wikitable"
|-
! Function
! Remarks
|-
| function '''ReplaceRegEx'''(const Input, Find, Replace: WideString;const CaseSensitive, UseSubstitution: Boolean): WideString;
| Find-and-replace function using RegEx. Works like [[ReNamer:Rules:RegEx|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 [[ReNamer:Rules:RegEx|RegEx rule]]).
* Replace - Replacement string (same as the '''Replace''' field in the [[ReNamer:Rules:RegEx|RegEx rule]]).
* CaseSensitive - Specifies whether to process in a case-sensitive mode.
* UseSubstitution - Determines whether use [[ReNamer:Regular Expressions#Backreferences|backreferences]] in the result.

== Unicode Character Handling Routines ==

{| class="prettytable"
|-
! 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/ http://www.fileformat.info/info/unicode/].

== Unicode Conversion Routines ==

{| class="wikitable"
|-
! 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 ==

{| class="wikitable"
|-
! Function
! Remarks
|-
| function '''IntToStr'''(Value: Integer): String;
| Converts an integer to a string. The following assumptions are correct:
<div style="font-family: monospace">
* IntToStr(123) = '123'
* IntToStr(0123) = '123'
* IntToStr(123) <> '0123'
</div>
|-
| function '''StrToInt'''(const S: String): Integer;
| Converts a string to an integer. The following equality is correct:
<div style="font-family: monospace">
* StrToInt('123') = 123
* StrToInt('123') = 0123
* StrToInt('0123') = 123
</div>
'''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:
<div style="font-family: monospace">
* IntToHex(1234, 1) = '4D2'
* IntToHex(1234, 8) = '000004D2'
</div>
|-
| 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 ==

{| class="wikitable"
|-
! 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. [[ReNamer:Date and Time format|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 ==

{| class="wikitable"
|-
! 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 ==

{| class="prettytable"
|-
| align="center" | '''Function'''
| <center>'''Remarks'''</center>
|-
| function '''WideExtractFilePath'''(const FileName: WideString): WideString;
| Returns the entire path of the file <br>(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<br>???or is it the name of the drive?
|-
| function '''WideExtractFileName'''(const FileName: WideString): WideString;
| Returns the filename with extension. <br>(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.<br>??? 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)<br>'''D:\Folder2\Folder22\FileName2.pdf'''   (The destination file)

Then the relative path of the destination file is-<br>'''..\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;
|
|}

<br>

== File Read/Write Routines ==

{| class="prettytable"
|-
! 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 ==

{| class="prettytable"
|-
| align="center" | '''Function'''
| <center>'''Remarks'''</center>
|-
| 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;
|
|}

<br>

== Process Execution Routines ==

{| class="prettytable"
|-
| align="center" | '''Function'''
| <center>'''Remarks'''</center>
|-
| function '''ShellOpenFile'''(const FileName: WideString): Boolean;
|
|-
| function '''ExecuteProgram'''(const Command: String; WaitForProgram: Boolean): Cardinal;
|
|-
| function '''ExecConsoleApp'''(const CommandLine: String; out Output: String): Cardinal;
|
|}

<br>

== Interactive Dialogs ==

{| class="prettytable"
|-
| align="center" | '''Function'''
| <center>'''Remarks'''</center>
|-
| 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;
|
|}

<br>

== Other Routines ==

{| class="prettytable"
|-
| align="center" | '''Function'''
| <center>'''Remarks'''</center>
|-
| 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;
|
|}

ReNamer:Pascal Script:Functions

2009-08-03T01:55:03Z

Prologician: /* File Read/Write Routines */ Italic-bolding consistency, and a few grammar tweaks to FileReadFragment()

== Introduction ==

ReNamer has many [http://www.taoyue.com/tutorials/pascal/pas4a.html procedures] and [http://www.taoyue.com/tutorials/pascal/pas4c.html 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 [http://en.wikipedia.org/wiki/Unicode 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 ==

{| class="wikitable"
|-
! 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 ==

{| class="wikitable"
|-
! 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 ==

{| class="wikitable"
|-
! 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;
|  ???<br>
|-
| function '''WideReplaceText'''(const S, OldPattern, NewPattern: WideString): WideString;
|  ???<br>
|-
| 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. <br>(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.<br>

*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.<br>
|}

== Meta Tags Extraction ==

{| class="prettytable"
|-
! 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:
<pre>
begin
FileName := CalculateMetaTag(FilePath, 'EXIF_Date');
end.
</pre>

The full list of meta tags can be found in [[ReNamer:Meta Tags|Meta Tags]] article.

== Regular Expressions ==

{| class="wikitable"
|-
! Function
! Remarks
|-
| function '''ReplaceRegEx'''(const Input, Find, Replace: WideString;const CaseSensitive, UseSubstitution: Boolean): WideString;
| Find-and-replace function using RegEx. Works like [[ReNamer:Rules:RegEx|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 [[ReNamer:Rules:RegEx|RegEx rule]]).
* Replace - Replacement string (same as the '''Replace''' field in the [[ReNamer:Rules:RegEx|RegEx rule]]).
* CaseSensitive - Specifies whether to process in a case-sensitive mode.
* UseSubstitution - Determines whether use [[ReNamer:Regular Expressions#Backreferences|backreferences]] in the result.

== Unicode Character Handling Routines ==

{| class="prettytable"
|-
! 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/ http://www.fileformat.info/info/unicode/].

== Unicode Conversion Routines ==

{| class="wikitable"
|-
! 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 ==

{| class="wikitable"
|-
! Function
! Remarks
|-
| function '''IntToStr'''(Value: Integer): String;
| Converts an integer to a string. The following assumptions are correct:
<div style="font-family: monospace">
* IntToStr(123) = '123'
* IntToStr(0123) = '123'
* IntToStr(123) <> '0123'
</div>
|-
| function '''StrToInt'''(const S: String): Integer;
| Converts a string to an integer. The following equality is correct:
<div style="font-family: monospace">
* StrToInt('123') = 123
* StrToInt('123') = 0123
* StrToInt('0123') = 123
</div>
'''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:
<div style="font-family: monospace">
* IntToHex(1234, 1) = '4D2'
* IntToHex(1234, 8) = '000004D2'
</div>
|-
| 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 ==

{| class="wikitable"
|-
! 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. [[ReNamer:Date and Time format|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 ==

{| class="wikitable"
|-
! 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 ==

{| class="prettytable"
|-
| align="center" | '''Function'''
| <center>'''Remarks'''</center>
|-
| function '''WideExtractFilePath'''(const FileName: WideString): WideString;
| Returns the entire path of the file <br>(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<br>???or is it the name of the drive?
|-
| function '''WideExtractFileName'''(const FileName: WideString): WideString;
| Returns the filename with extension. <br>(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.<br>??? 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)<br>'''D:\Folder2\Folder22\FileName2.pdf'''   (The destination file)

Then the relative path of the destination file is-<br>'''..\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;
|
|}

<br>

== File Read/Write Routines ==

{| class="prettytable"
|-
! 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 ==

{| class="prettytable"
|-
| align="center" | '''Function'''
| <center>'''Remarks'''</center>
|-
| 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;
|
|}

<br>

== Process Execution Routines ==

{| class="prettytable"
|-
| align="center" | '''Function'''
| <center>'''Remarks'''</center>
|-
| function '''ShellOpenFile'''(const FileName: WideString): Boolean;
|
|-
| function '''ExecuteProgram'''(const Command: String; WaitForProgram: Boolean): Cardinal;
|
|-
| function '''ExecConsoleApp'''(const CommandLine: String; out Output: String): Cardinal;
|
|}

<br>

== Interactive Dialogs ==

{| class="prettytable"
|-
| align="center" | '''Function'''
| <center>'''Remarks'''</center>
|-
| 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;
|
|}

<br>

== Other Routines ==

{| class="prettytable"
|-
| align="center" | '''Function'''
| <center>'''Remarks'''</center>
|-
| 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;
|
|}

ReNamer:Pascal Script:Functions

2009-08-03T01:48:01Z

Prologician: /* File Name Utilities */ Corrected a typo in WideExtractBaseName(), fixed the example for WideExtractFileExt() (it adds the period)

== Introduction ==

ReNamer has many [http://www.taoyue.com/tutorials/pascal/pas4a.html procedures] and [http://www.taoyue.com/tutorials/pascal/pas4c.html 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 [http://en.wikipedia.org/wiki/Unicode 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 ==

{| class="wikitable"
|-
! 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 ==

{| class="wikitable"
|-
! 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 ==

{| class="wikitable"
|-
! 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;
|  ???<br>
|-
| function '''WideReplaceText'''(const S, OldPattern, NewPattern: WideString): WideString;
|  ???<br>
|-
| 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. <br>(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.<br>

*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.<br>
|}

== Meta Tags Extraction ==

{| class="prettytable"
|-
! 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:
<pre>
begin
FileName := CalculateMetaTag(FilePath, 'EXIF_Date');
end.
</pre>

The full list of meta tags can be found in [[ReNamer:Meta Tags|Meta Tags]] article.

== Regular Expressions ==

{| class="wikitable"
|-
! Function
! Remarks
|-
| function '''ReplaceRegEx'''(const Input, Find, Replace: WideString;const CaseSensitive, UseSubstitution: Boolean): WideString;
| Find-and-replace function using RegEx. Works like [[ReNamer:Rules:RegEx|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 [[ReNamer:Rules:RegEx|RegEx rule]]).
* Replace - Replacement string (same as the '''Replace''' field in the [[ReNamer:Rules:RegEx|RegEx rule]]).
* CaseSensitive - Specifies whether to process in a case-sensitive mode.
* UseSubstitution - Determines whether use [[ReNamer:Regular Expressions#Backreferences|backreferences]] in the result.

== Unicode Character Handling Routines ==

{| class="prettytable"
|-
! 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/ http://www.fileformat.info/info/unicode/].

== Unicode Conversion Routines ==

{| class="wikitable"
|-
! 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 ==

{| class="wikitable"
|-
! Function
! Remarks
|-
| function '''IntToStr'''(Value: Integer): String;
| Converts an integer to a string. The following assumptions are correct:
<div style="font-family: monospace">
* IntToStr(123) = '123'
* IntToStr(0123) = '123'
* IntToStr(123) <> '0123'
</div>
|-
| function '''StrToInt'''(const S: String): Integer;
| Converts a string to an integer. The following equality is correct:
<div style="font-family: monospace">
* StrToInt('123') = 123
* StrToInt('123') = 0123
* StrToInt('0123') = 123
</div>
'''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:
<div style="font-family: monospace">
* IntToHex(1234, 1) = '4D2'
* IntToHex(1234, 8) = '000004D2'
</div>
|-
| 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 ==

{| class="wikitable"
|-
! 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. [[ReNamer:Date and Time format|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 ==

{| class="wikitable"
|-
! 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 ==

{| class="prettytable"
|-
| align="center" | '''Function'''
| <center>'''Remarks'''</center>
|-
| function '''WideExtractFilePath'''(const FileName: WideString): WideString;
| Returns the entire path of the file <br>(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<br>???or is it the name of the drive?
|-
| function '''WideExtractFileName'''(const FileName: WideString): WideString;
| Returns the filename with extension. <br>(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.<br>??? 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)<br>'''D:\Folder2\Folder22\FileName2.pdf'''   (The destination file)

Then the relative path of the destination file is-<br>'''..\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;
|
|}

<br>

== File Read/Write Routines ==

{| class="prettytable"
|-
! 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 from the first character set this parameter 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 ==

{| class="prettytable"
|-
| align="center" | '''Function'''
| <center>'''Remarks'''</center>
|-
| 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;
|
|}

<br>

== Process Execution Routines ==

{| class="prettytable"
|-
| align="center" | '''Function'''
| <center>'''Remarks'''</center>
|-
| function '''ShellOpenFile'''(const FileName: WideString): Boolean;
|
|-
| function '''ExecuteProgram'''(const Command: String; WaitForProgram: Boolean): Cardinal;
|
|-
| function '''ExecConsoleApp'''(const CommandLine: String; out Output: String): Cardinal;
|
|}

<br>

== Interactive Dialogs ==

{| class="prettytable"
|-
| align="center" | '''Function'''
| <center>'''Remarks'''</center>
|-
| 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;
|
|}

<br>

== Other Routines ==

{| class="prettytable"
|-
| align="center" | '''Function'''
| <center>'''Remarks'''</center>
|-
| 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;
|
|}

ReNamer:Pascal Script:Functions

2009-08-02T09:55:14Z

Prologician: /* File Read/Write Routines */ Fix a missing italic marker.

== Introduction ==

ReNamer has many [http://www.taoyue.com/tutorials/pascal/pas4a.html procedures] and [http://www.taoyue.com/tutorials/pascal/pas4c.html 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 [http://en.wikipedia.org/wiki/Unicode 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 ==

{| class="wikitable"
|-
! 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 ==

{| class="wikitable"
|-
! 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 ==

{| class="wikitable"
|-
! 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;
|  ???<br>
|-
| function '''WideReplaceText'''(const S, OldPattern, NewPattern: WideString): WideString;
|  ???<br>
|-
| 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. <br>(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.<br>

*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.<br>
|}

== Meta Tags Extraction ==

{| class="prettytable"
|-
! 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:
<pre>
begin
FileName := CalculateMetaTag(FilePath, 'EXIF_Date');
end.
</pre>

The full list of meta tags can be found in [[ReNamer:Meta Tags|Meta Tags]] article.

== Regular Expressions ==

{| class="wikitable"
|-
! Function
! Remarks
|-
| function '''ReplaceRegEx'''(const Input, Find, Replace: WideString;const CaseSensitive, UseSubstitution: Boolean): WideString;
| Find-and-replace function using RegEx. Works like [[ReNamer:Rules:RegEx|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 [[ReNamer:Rules:RegEx|RegEx rule]]).
* Replace - Replacement string (same as the '''Replace''' field in the [[ReNamer:Rules:RegEx|RegEx rule]]).
* CaseSensitive - Specifies whether to process in a case-sensitive mode.
* UseSubstitution - Determines whether use [[ReNamer:Regular Expressions#Backreferences|backreferences]] in the result.

== Unicode Character Handling Routines ==

{| class="prettytable"
|-
! 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/ http://www.fileformat.info/info/unicode/].

== Unicode Conversion Routines ==

{| class="wikitable"
|-
! 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 ==

{| class="wikitable"
|-
! Function
! Remarks
|-
| function '''IntToStr'''(Value: Integer): String;
| Converts an integer to a string. The following assumptions are correct:
<div style="font-family: monospace">
* IntToStr(123) = '123'
* IntToStr(0123) = '123'
* IntToStr(123) <> '0123'
</div>
|-
| function '''StrToInt'''(const S: String): Integer;
| Converts a string to an integer. The following equality is correct:
<div style="font-family: monospace">
* StrToInt('123') = 123
* StrToInt('123') = 0123
* StrToInt('0123') = 123
</div>
'''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:
<div style="font-family: monospace">
* IntToHex(1234, 1) = '4D2'
* IntToHex(1234, 8) = '000004D2'
</div>
|-
| 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 ==

{| class="wikitable"
|-
! 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. [[ReNamer:Date and Time format|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 ==

{| class="wikitable"
|-
! 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 ==

{| class="prettytable"
|-
| align="center" | '''Function'''
| <center>'''Remarks'''</center>
|-
| function '''WideExtractFilePath'''(const FileName: WideString): WideString;
| Returns the entire path of the file <br>(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<br>???or is it the name of the drive?
|-
| function '''WideExtractFileName'''(const FileName: WideString): WideString;
| Returns the filename with extension. <br>(e.g. "FileName.txt")
|-
| function '''WideExtractBaseName'''(const FileName: WideString): WideString;
| Retusn 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 only (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.<br>??? 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)<br>'''D:\Folder2\Folder22\FileName2.pdf'''   (The destination file)

Then the relative path of the destination file is-<br>'''..\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;
|
|}

<br>

== File Read/Write Routines ==

{| class="prettytable"
|-
| align="center" | '''Function'''
| <center>'''Remarks'''</center>
|-
| function '''FileReadFragment'''(const FileName: WideString; Start, Length: Integer): String;
| Starting at ''Start'', reads ''Length'' number of bytes of the file ''FileName'' as raw data.
|-
| function '''FileReadLine'''(const FileName: WideString; LineNum: Integer): String;
|
|-
| 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);
|
|}

<br>

== File Properties Routines ==

{| class="prettytable"
|-
| align="center" | '''Function'''
| <center>'''Remarks'''</center>
|-
| 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;
|
|}

<br>

== Process Execution Routines ==

{| class="prettytable"
|-
| align="center" | '''Function'''
| <center>'''Remarks'''</center>
|-
| function '''ShellOpenFile'''(const FileName: WideString): Boolean;
|
|-
| function '''ExecuteProgram'''(const Command: String; WaitForProgram: Boolean): Cardinal;
|
|-
| function '''ExecConsoleApp'''(const CommandLine: String; out Output: String): Cardinal;
|
|}

<br>

== Interactive Dialogs ==

{| class="prettytable"
|-
| align="center" | '''Function'''
| <center>'''Remarks'''</center>
|-
| 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;
|
|}

<br>

== Other Routines ==

{| class="prettytable"
|-
| align="center" | '''Function'''
| <center>'''Remarks'''</center>
|-
| 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;
|
|}

ReNamer:Pascal Script:Functions

2009-08-02T09:54:42Z

Prologician: /* File Read/Write Routines */ Description for FileReadFragment()

== Introduction ==

ReNamer has many [http://www.taoyue.com/tutorials/pascal/pas4a.html procedures] and [http://www.taoyue.com/tutorials/pascal/pas4c.html 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 [http://en.wikipedia.org/wiki/Unicode 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 ==

{| class="wikitable"
|-
! 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 ==

{| class="wikitable"
|-
! 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 ==

{| class="wikitable"
|-
! 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;
|  ???<br>
|-
| function '''WideReplaceText'''(const S, OldPattern, NewPattern: WideString): WideString;
|  ???<br>
|-
| 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. <br>(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.<br>

*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.<br>
|}

== Meta Tags Extraction ==

{| class="prettytable"
|-
! 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:
<pre>
begin
FileName := CalculateMetaTag(FilePath, 'EXIF_Date');
end.
</pre>

The full list of meta tags can be found in [[ReNamer:Meta Tags|Meta Tags]] article.

== Regular Expressions ==

{| class="wikitable"
|-
! Function
! Remarks
|-
| function '''ReplaceRegEx'''(const Input, Find, Replace: WideString;const CaseSensitive, UseSubstitution: Boolean): WideString;
| Find-and-replace function using RegEx. Works like [[ReNamer:Rules:RegEx|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 [[ReNamer:Rules:RegEx|RegEx rule]]).
* Replace - Replacement string (same as the '''Replace''' field in the [[ReNamer:Rules:RegEx|RegEx rule]]).
* CaseSensitive - Specifies whether to process in a case-sensitive mode.
* UseSubstitution - Determines whether use [[ReNamer:Regular Expressions#Backreferences|backreferences]] in the result.

== Unicode Character Handling Routines ==

{| class="prettytable"
|-
! 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/ http://www.fileformat.info/info/unicode/].

== Unicode Conversion Routines ==

{| class="wikitable"
|-
! 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 ==

{| class="wikitable"
|-
! Function
! Remarks
|-
| function '''IntToStr'''(Value: Integer): String;
| Converts an integer to a string. The following assumptions are correct:
<div style="font-family: monospace">
* IntToStr(123) = '123'
* IntToStr(0123) = '123'
* IntToStr(123) <> '0123'
</div>
|-
| function '''StrToInt'''(const S: String): Integer;
| Converts a string to an integer. The following equality is correct:
<div style="font-family: monospace">
* StrToInt('123') = 123
* StrToInt('123') = 0123
* StrToInt('0123') = 123
</div>
'''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:
<div style="font-family: monospace">
* IntToHex(1234, 1) = '4D2'
* IntToHex(1234, 8) = '000004D2'
</div>
|-
| 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 ==

{| class="wikitable"
|-
! 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. [[ReNamer:Date and Time format|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 ==

{| class="wikitable"
|-
! 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 ==

{| class="prettytable"
|-
| align="center" | '''Function'''
| <center>'''Remarks'''</center>
|-
| function '''WideExtractFilePath'''(const FileName: WideString): WideString;
| Returns the entire path of the file <br>(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<br>???or is it the name of the drive?
|-
| function '''WideExtractFileName'''(const FileName: WideString): WideString;
| Returns the filename with extension. <br>(e.g. "FileName.txt")
|-
| function '''WideExtractBaseName'''(const FileName: WideString): WideString;
| Retusn 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 only (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.<br>??? 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)<br>'''D:\Folder2\Folder22\FileName2.pdf'''   (The destination file)

Then the relative path of the destination file is-<br>'''..\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;
|
|}

<br>

== File Read/Write Routines ==

{| class="prettytable"
|-
| align="center" | '''Function'''
| <center>'''Remarks'''</center>
|-
| function '''FileReadFragment'''(const FileName: WideString; Start, Length: Integer): String;
| Starting at ''Start', reads ''Length'' number of bytes of the file ''FileName'' as raw data.
|-
| function '''FileReadLine'''(const FileName: WideString; LineNum: Integer): String;
|
|-
| 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);
|
|}

<br>

== File Properties Routines ==

{| class="prettytable"
|-
| align="center" | '''Function'''
| <center>'''Remarks'''</center>
|-
| 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;
|
|}

<br>

== Process Execution Routines ==

{| class="prettytable"
|-
| align="center" | '''Function'''
| <center>'''Remarks'''</center>
|-
| function '''ShellOpenFile'''(const FileName: WideString): Boolean;
|
|-
| function '''ExecuteProgram'''(const Command: String; WaitForProgram: Boolean): Cardinal;
|
|-
| function '''ExecConsoleApp'''(const CommandLine: String; out Output: String): Cardinal;
|
|}

<br>

== Interactive Dialogs ==

{| class="prettytable"
|-
| align="center" | '''Function'''
| <center>'''Remarks'''</center>
|-
| 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;
|
|}

<br>

== Other Routines ==

{| class="prettytable"
|-
| align="center" | '''Function'''
| <center>'''Remarks'''</center>
|-
| 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;
|
|}