Difference between revisions of "ReNamer:Pascal Script:Functions"

From den4b Wiki
Jump to: navigation, search
(Undo revision 1820 by SafetyCar (Talk) undoing from Chrome, Opera messed it up)
Line 2: Line 2:
  
 
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.
 
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.
 
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 T prefix?  
 
 
*??? What is UTF8?
 
*??? What is UTF8?
  
== Basic String Handling ==
+
== Basic String Handling ==
  
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
 
! Routine
 
! Routine
 
 
! Remarks
 
! Remarks
 
|-
 
|-
| procedure '''Insert'''(Source: String; var S: String; Index: Integer);
+
| procedure '''Insert'''(Source: String; var S: String; Index: Integer);  
 
 
| Inserts the string '''S''' into string '''Source''' at position '''Index'''.
 
| Inserts the string '''S''' into string '''Source''' at position '''Index'''.
 
|-
 
|-
| procedure '''Delete'''(var S: String; Index, Count: Integer);
+
| procedure '''Delete'''(var S: String; Index, Count: Integer);  
 
 
| Deletes '''Count''' characters from the string '''S''', starting from position '''Index'''.
 
| Deletes '''Count''' characters from the string '''S''', starting from position '''Index'''.
 
|-
 
|-
| function '''Copy'''(S: String; Index, Count: Integer): String;
+
| 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.
 
| Copies '''Count''' characters from string '''S''', starting at position '''Index''', and returns them as a new string.
 
|-
 
|-
| function '''Pos'''(Substr: String; S: String): Integer;
+
| function '''Pos'''(Substr: String; S: String): Integer;  
 
 
| Returns the position of a string '''Substr''' in another string '''S'''.
 
| 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].
 
'''Note:''' Indexes of characters in strings are 1 based, so first character in string S would be S[1].
 
  
== Length Management ==
+
== Length Management ==
  
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
 
! Routine
 
! Routine
 
 
! Remarks
 
! Remarks
 
|-
 
|-
| procedure '''SetLength'''(var S: Array; NewLength: Integer);
+
| procedure '''SetLength'''(var S: Array; NewLength: Integer);  
 
 
| Sets the length of array variable '''S''' to '''NewLength'''.
 
| Sets the length of array variable '''S''' to '''NewLength'''.
 
|-
 
|-
| procedure '''SetLength'''(var S: String; NewLength: Integer);
+
| procedure '''SetLength'''(var S: String; NewLength: Integer);  
 
 
| Sets the length of string variable '''S''' to '''NewLength'''.
 
| Sets the length of string variable '''S''' to '''NewLength'''.
 
|-
 
|-
| procedure '''SetLength'''(var S: WideString; NewLength: Integer);
+
| procedure '''SetLength'''(var S: WideString; NewLength: Integer);  
 
 
| Sets the length of widestring '''S''' to '''NewLength'''.
 
| Sets the length of widestring '''S''' to '''NewLength'''.
 
|-
 
|-
| function '''Length'''(const S: Array): Integer;
+
| function '''Length'''(const S: Array): Integer;  
 
 
| Returns the length of array '''S ''' (number of elements).
 
| Returns the length of array '''S ''' (number of elements).
 
|-
 
|-
| function '''Length'''(const S: String): Integer;
+
| function '''Length'''(const S: String): Integer;  
 
 
| Returns the length of string '''S''' (number of characters).
 
| Returns the length of string '''S''' (number of characters).
 
|-
 
|-
 
| function '''Length'''(const S: WideString): Integer;
 
| function '''Length'''(const S: WideString): Integer;
 
 
| Returns the length of WideString '''S''' (number of characters).
 
| Returns the length of WideString '''S''' (number of characters).
 
|}
 
|}
  
== Unicode String Handling ==
+
== Unicode String Handling ==
  
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
 
! Routine
 
! Routine
 
 
! Remarks
 
! Remarks
 
|-
 
|-
| procedure '''WideInsert'''(const Substr: WideString; var Dest: WideString; Index: Integer);
+
| procedure '''WideInsert'''(const Substr: WideString; var Dest: WideString; Index: Integer);  
 
 
| Inserts '''Substr''' in '''Dest''' at position '''Index'''.
 
| Inserts '''Substr''' in '''Dest''' at position '''Index'''.
 
|-
 
|-
| procedure '''WideDelete'''(var S: WideString; Index, Count: Integer);
+
| procedure '''WideDelete'''(var S: WideString; Index, Count: Integer);  
 
 
| Deletes '''Count''' characters from '''S''', starting from the '''Index''' position.
 
| Deletes '''Count''' characters from '''S''', starting from the '''Index''' position.
 
|-
 
|-
| procedure '''WideSetLength'''(var S: WideString; NewLength: Integer);
+
| 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.
 
| 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;
+
| function '''WideLength'''(const S: WideString): Integer;  
 
 
| Returns the length of WideString '''S'''.
 
| Returns the length of WideString '''S'''.
 
|-
 
|-
| function '''WideCopy'''(const S: WideString; Index, Count: Integer): WideString;
+
| function '''WideCopy'''(const S: WideString; Index, Count: Integer): WideString;  
 
 
| Returns '''Count''' characters from WideString '''S''', starting at position '''Index'''.
 
| Returns '''Count''' characters from WideString '''S''', starting at position '''Index'''.
 
|-
 
|-
| function '''WidePos'''(const SubStr, S: WideString): Integer;
+
| 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.
 
| 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;
+
| 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.
 
| 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;
+
| function '''WideUpperCase'''(const S: WideString): WideString;  
 
 
| Returns the ALLCAPS version of the WideString '''S'''
 
| Returns the ALLCAPS version of the WideString '''S'''
 
|-
 
|-
| function '''WideLowerCase'''(const S: WideString): WideString;
+
| function '''WideLowerCase'''(const S: WideString): WideString;  
 
 
| Returns the lowercase version of the WideString '''S'''
 
| Returns the lowercase version of the WideString '''S'''
 
|-
 
|-
| function '''WideCompareStr'''(const S1, S2: WideString): Integer;
+
| 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.
 
| 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;
+
| 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.
 
| 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;
+
| function '''WideSameText'''(const S1, S2: WideString): Boolean;  
 
 
| Compares two WideStrings '''S1''' and '''S2''', case-insensitive. Returns TRUE if both are identical, otherwise returns FALSE.
 
| Compares two WideStrings '''S1''' and '''S2''', case-insensitive. Returns TRUE if both are identical, otherwise returns FALSE.
 
|-
 
|-
| function '''WideTextPos'''(const SubStr, S: WideString): Integer;
+
| function '''WideTextPos'''(const SubStr, S: WideString): Integer;  
 
 
| Behaves like '''WidePos''' function, except text if processed in case-insensitive manner.
 
| Behaves like '''WidePos''' function, except text if processed in case-insensitive manner.
 
|-
 
|-
| function '''WideTrim'''(const S: WideString): WideString;
+
| function '''WideTrim'''(const S: WideString): WideString;  
 
 
| Removes leading and trailing spaces and control characters from the given string '''S'''.
 
| Removes leading and trailing spaces and control characters from the given string '''S'''.
 
|-
 
|-
| function '''WideReplaceStr'''(const S, OldPattern, NewPattern: WideString): WideString;
+
| function '''WideReplaceStr'''(const S, OldPattern, NewPattern: WideString): WideString;  
 
 
| Returns the result of replacing on a string S, a string OldPattern (Case Sensitive), with a NewPattern.
 
| Returns the result of replacing on a string S, a string OldPattern (Case Sensitive), with a NewPattern.
 
|-
 
|-
| function '''WideReplaceText'''(const S, OldPattern, NewPattern: WideString): WideString;
+
| function '''WideReplaceText'''(const S, OldPattern, NewPattern: WideString): WideString;  
 
 
| Returns the result of replacing on a string S, a text OldPattern (Case Non-Sensitive), with a NewPattern.
 
| Returns the result of replacing on a string S, a text OldPattern (Case Non-Sensitive), with a NewPattern.
 
|-
 
|-
| function '''WideSplitString'''(const Input, Delimiter: WideString): TStringsArray;
+
| function '''WideSplitString'''(const Input, Delimiter: WideString): TStringsArray;  
 
 
|  
 
|  
 
Splits the WideString '''Input '''wherever '''Delimiter''' occurs, and returns an array that contains the split parts.  
 
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 '''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
 
*The split parts (returned as elements of the array) do not contain the '''Delimiter''' WideString
  
 
|-
 
|-
| function '''WideCaseCapitalize'''(const S: WideString): WideString;
+
| function '''WideCaseCapitalize'''(const S: WideString): WideString;  
 
 
|  
 
|  
 
Returns the ''Sentence case'' version of the WideString '''S'''.  
 
Returns the ''Sentence case'' version of the WideString '''S'''.  
Line 164: Line 128:
  
 
|-
 
|-
| function '''WideCaseInvert'''(const S: WideString): WideString;
+
| function '''WideCaseInvert'''(const S: WideString): WideString;  
 
 
| Inverts the case of all characters in the WideString '''S''' and returns the WideString.<br>
 
| Inverts the case of all characters in the WideString '''S''' and returns the WideString.<br>
 
|}
 
|}
Line 174: Line 137:
 
|-
 
|-
 
! Function
 
! Function
 
 
! Remarks
 
! Remarks
 
|-
 
|-
| function '''CalculateMetaTag'''(const FilePath: WideString; const MetaTagName String): String;
+
| 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'''.
 
| 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:
 
For example, to extract '''EXIF_Date''' tag from an image and set it to the filename, one can use something like this:
<source lang="null">
+
<source>
 
begin
 
begin
 
   FileName := CalculateMetaTag(FilePath, 'EXIF_Date');
 
   FileName := CalculateMetaTag(FilePath, 'EXIF_Date');
 
end.
 
end.
 
</source>
 
</source>
 
  
 
The full list of meta tags can be found in [[ReNamer:Meta Tags|Meta Tags]] article.
 
The full list of meta tags can be found in [[ReNamer:Meta Tags|Meta Tags]] article.
 
  
== Regular Expressions ==
+
== Regular Expressions ==
  
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
 
! Function
 
! Function
 
 
! Remarks
 
! Remarks
 
|-
 
|-
| function '''ReplaceRegEx'''(const Input, Find, Replace: WideString;const CaseSensitive, UseSubstitution: Boolean): WideString;
+
| 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]].
 
| Find-and-replace function using RegEx. Works like [[ReNamer:Rules:RegEx|RegEx rule]].
 
|-
 
|-
| function '''MatchesRegEx'''(const Input, Find: WideString;const CaseSensitive: Boolean): TStringsArray;
+
| 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.  
| 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.
+
 
 
 
For example, given the Input 'Ax1_-_Bx2---Cx3' and the function '''MatchesRegEx'''(Input, ''''([A-Z])x(\d)'''', False).&nbsp;What we get is [''''Ax1'''', ''''Bx2'''', ''''Cx3'''']. Being these the 3 full matches found on the Input.
 
For example, given the Input 'Ax1_-_Bx2---Cx3' and the function '''MatchesRegEx'''(Input, ''''([A-Z])x(\d)'''', False).&nbsp;What we get is [''''Ax1'''', ''''Bx2'''', ''''Cx3'''']. Being these the 3 full matches found on the Input.
+
|-
 +
| 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.
  
|-
 
| 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, given the Input 'Ax1_-_Bx2---Cx3' and the function '''SubMatchesRegEx'''(Input, ''''([A-Z])x(\d)'''', False).&nbsp;What we get is&nbsp;[''''A'''',&nbsp;''''1'''']. Being these the first sub-matches requested&nbsp;(two in this case).  
 
For example, given the Input 'Ax1_-_Bx2---Cx3' and the function '''SubMatchesRegEx'''(Input, ''''([A-Z])x(\d)'''', False).&nbsp;What we get is&nbsp;[''''A'''',&nbsp;''''1'''']. Being these the first sub-matches requested&nbsp;(two in this case).  
 
  
 
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.
 
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:  
 
General parameters of the functions:  
 
  
*Input - The WideString that is input to the function.  
+
* 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]]).
*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.
*Replace - Replacement string (same as the '''Replace''' field in the [[ReNamer:Rules:RegEx|RegEx rule]]).
+
* UseSubstitution - Determines whether use [[ReNamer:Regular Expressions#Backreferences|backreferences]] in the result.
 
*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 ==
+
== Unicode Character Handling ==
  
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
 
! Function
 
! Function
 
 
! Remarks
 
! Remarks
 
|-
 
|-
| function '''IsWideCharUpper'''(WC: WideChar): Boolean;
+
| function '''IsWideCharUpper'''(WC: WideChar): Boolean;  
 
 
| Checks a Unicode character '''WC''' and returns TRUE if it is in UPPERCASE.
 
| Checks a Unicode character '''WC''' and returns TRUE if it is in UPPERCASE.
 
|-
 
|-
| function '''IsWideCharLower'''(WC: WideChar): Boolean;
+
| function '''IsWideCharLower'''(WC: WideChar): Boolean;  
 
 
| Checks a Unicode character '''WC''' and returns TRUE if it is in lowercase.
 
| Checks a Unicode character '''WC''' and returns TRUE if it is in lowercase.
 
|-
 
|-
| function '''IsWideCharDigit'''(WC: WideChar): Boolean;
+
| function '''IsWideCharDigit'''(WC: WideChar): Boolean;  
+
| Checks a Unicode character '''WC''' and returns TRUE if it is a digit (numeric character 0-9).  
| Checks a Unicode character '''WC''' and returns TRUE if it is a digit (numeric character 0-9).
 
 
|-
 
|-
| function '''IsWideCharSpace'''(WC: WideChar): Boolean;
+
| 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).
 
| 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;
+
| function '''IsWideCharPunct'''(WC: WideChar): Boolean;  
 
 
| Checks a Unicode character '''WC''' and returns TRUE if it is a punctuation mark (characters classified as C1_PUNCT).
 
| Checks a Unicode character '''WC''' and returns TRUE if it is a punctuation mark (characters classified as C1_PUNCT).
 
|-
 
|-
| function '''IsWideCharCntrl'''(WC: WideChar): Boolean;
+
| function '''IsWideCharCntrl'''(WC: WideChar): Boolean;  
 
 
| Checks a Unicode character '''WC''' and returns TRUE if it is a control character (characters classified as C1_CNTRL).
 
| Checks a Unicode character '''WC''' and returns TRUE if it is a control character (characters classified as C1_CNTRL).
 
|-
 
|-
| function '''IsWideCharBlank'''(WC: WideChar): Boolean;
+
| 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).
 
| 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;
+
| function '''IsWideCharXDigit'''(WC: WideChar): Boolean;  
 
 
| Checks a Unicode character '''WC''' and returns TRUE if it is a hexadecimal digit (0-9 or A-F).
 
| Checks a Unicode character '''WC''' and returns TRUE if it is a hexadecimal digit (0-9 or A-F).
 
|-
 
|-
| function '''IsWideCharAlpha'''(WC: WideChar): Boolean;
+
| function '''IsWideCharAlpha'''(WC: WideChar): Boolean;  
 
 
| Checks a Unicode character '''WC''' and returns TRUE if it is a alphanumeric character (a-z or A-Z).
 
| Checks a Unicode character '''WC''' and returns TRUE if it is a alphanumeric character (a-z or A-Z).
 
|-
 
|-
| function '''IsWideCharAlphaNumeric'''(WC: WideChar): Boolean;
+
| 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).
 
| 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;
+
| 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.
 
| 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;
+
| 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.
 
| 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/].
 
'''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 ==
+
== Unicode Conversion ==
  
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
 
! Function
 
! Function
 
 
! Remarks
 
! Remarks
 
|-
 
|-
| function '''WideToAnsi'''(const WS: WideString): String;
+
| function '''WideToAnsi'''(const WS: WideString): String;  
 
 
| Converts a Unicode string to its ANSI version.
 
| Converts a Unicode string to its ANSI version.
 
|-
 
|-
| function '''AnsiToWide'''(const S: String): WideString;
+
| function '''AnsiToWide'''(const S: String): WideString;  
 
 
| Converts a ANSI string to its Unicode version.
 
| Converts a ANSI string to its Unicode version.
 
|-
 
|-
| function '''UTF8Encode'''(const WS: WideString): String;
+
| function '''UTF8Encode'''(const WS: WideString): String;  
 
 
| Convert Unicode string to the UTF-8 encoded string. Useful to storing Unicode strings in files.
 
| Convert Unicode string to the UTF-8 encoded string. Useful to storing Unicode strings in files.
 
|-
 
|-
 
| function '''UTF8Decode'''(const S: String): WideString;
 
| function '''UTF8Decode'''(const S: String): WideString;
 
 
| Convert UTF-8 encoded string to its full Unicode representation.
 
| Convert UTF-8 encoded string to its full Unicode representation.
 
|}
 
|}
  
== Basic Conversion ==
+
== Basic Conversion ==
  
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
 
! Function
 
! Function
 
 
! Remarks
 
! Remarks
 
|-
 
|-
 
| function '''BoolToStr'''(B: Boolean): String;
 
| function '''BoolToStr'''(B: Boolean): String;
 
 
| Convert boolean variable into a string. Returns '''True''' or '''False''' string.
 
| Convert boolean variable into a string. Returns '''True''' or '''False''' string.
 
|-
 
|-
| function '''IntToStr'''(Value: Integer): String;
+
| function '''IntToStr'''(Value: Integer): String;  
 
 
| Converts an integer to a string. The following assumptions are correct:
 
| Converts an integer to a string. The following assumptions are correct:
<div style="font-family: monospace">
+
<div style="font-family: monospace">
*IntToStr(123) = '123'
+
* IntToStr(123) = '123'
+
* IntToStr(0123) = '123'
*IntToStr(0123) = '123'
+
* IntToStr(123) <> '0123'
 
*IntToStr(123) &lt;&gt; '0123'
 
 
</div>
 
</div>
 
|-
 
|-
| function '''StrToInt'''(const S: String): Integer;
+
| function '''StrToInt'''(const S: String): Integer;  
 
 
| Converts a string to an integer. The following equalities are correct:
 
| Converts a string to an integer. The following equalities are correct:
<div style="font-family: monospace">
+
<div style="font-family: monospace">
*StrToInt('123') = 123
+
* StrToInt('123') = 123
+
* StrToInt('123') = 0123
*StrToInt('123') = 0123
+
* StrToInt('0123') = 123
 
*StrToInt('0123') = 123
 
 
</div>
 
</div>
 
 
'''Warning:''' An error will occur if the parameter to this function cannot be converted to an integer!
 
'''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;
+
| 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.
 
| 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 '''FloatToStr'''(Value: Extended): string;
 
| function '''FloatToStr'''(Value: Extended): string;
 
 
| Converts supplied floating point value to its string representation, using default system format.
 
| Converts supplied floating point value to its string representation, using default system format.
 
|-
 
|-
 
| function '''StrToFloat'''(const S: string): Extended;
 
| function '''StrToFloat'''(const S: string): Extended;
 
 
| Converts supplied string to a floating point value.<br>'''Warning:''' An error will occur if the parameter to this function cannot be converted to a floating point value!
 
| Converts supplied string to a floating point value.<br>'''Warning:''' An error will occur if the parameter to this function cannot be converted to a floating point value!
 
|-
 
|-
 
| function '''StrToFloatDef'''(const S: string; const Default: Extended): Extended;
 
| function '''StrToFloatDef'''(const S: string; const Default: Extended): Extended;
 
 
| Behaves like '''StrToFloat''' 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 a floating point value.
 
| Behaves like '''StrToFloat''' 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 a floating point value.
 
|-
 
|-
 
| function '''FormatFloat'''(const Format: string; Value: Extended): string;
 
| function '''FormatFloat'''(const Format: string; Value: Extended): string;
 
 
| Converts supplied floating point value to its string representation, using user specific '''Format'''. Format string may contain following specifiers:
 
| Converts supplied floating point value to its string representation, using user specific '''Format'''. Format string may contain following specifiers:
 
 
{| class="wikitable"
 
{| class="wikitable"
|-
 
 
! Specifier
 
! Specifier
 
 
! Represents
 
! Represents
 
|-
 
|-
 
| '''0'''&nbsp;(zero)
 
| '''0'''&nbsp;(zero)
 
 
| Digit placeholder. If the value being formatted has a digit in the position where the "0" appears in the format string, then that digit is copied to the output string. Otherwise, a "0" is stored in that position in the output string.
 
| Digit placeholder. If the value being formatted has a digit in the position where the "0" appears in the format string, then that digit is copied to the output string. Otherwise, a "0" is stored in that position in the output string.
 
|-
 
|-
 
| '''#'''&nbsp;(hash)
 
| '''#'''&nbsp;(hash)
 
 
| Digit placeholder. If the value being formatted has a digit in the position where the "#" appears in the format string, then that digit is copied to the output string. Otherwise, nothing is stored in that position in the output string.
 
| Digit placeholder. If the value being formatted has a digit in the position where the "#" appears in the format string, then that digit is copied to the output string. Otherwise, nothing is stored in that position in the output string.
 
|-
 
|-
 
| '''.'''&nbsp;(dot)
 
| '''.'''&nbsp;(dot)
 
 
| Decimal point. The first "." character in the format string determines the location of the decimal separator in the formatted value, any additional "." characters are ignored.
 
| Decimal point. The first "." character in the format string determines the location of the decimal separator in the formatted value, any additional "." characters are ignored.
 
|-
 
|-
 
| ''','''&nbsp;(comma)
 
| ''','''&nbsp;(comma)
 
 
| Thousand separator. If the format string contains one or more "," characters, the output will have thousand separators inserted between each group of three digits to the left of the decimal point. The placement and number of "," characters in the format string does not affect the output.
 
| Thousand separator. If the format string contains one or more "," characters, the output will have thousand separators inserted between each group of three digits to the left of the decimal point. The placement and number of "," characters in the format string does not affect the output.
 
|}
 
|}
 
 
|-
 
|-
| function '''DateToStr'''(D: TDateTime): String;
+
| function '''DateToStr'''(D: TDateTime): String;  
 
 
| Converts a date to a string, using system format for the short date, for example: '''dd/mm/yyyy'''.
 
| Converts a date to a string, using system format for the short date, for example: '''dd/mm/yyyy'''.
 
|-
 
|-
| function '''StrToDate'''(const S: String): TDateTime;
+
| 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'''.
 
| 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;
+
| function '''IntToHex'''(Value: Integer; Digits: Integer): String;  
 
 
| Converts an integer to its hexadecimal representation. Here are samples:
 
| Converts an integer to its hexadecimal representation. Here are samples:
<div style="font-family: monospace">
+
<div style="font-family: monospace">
*IntToHex(1234, 1) = '4D2'
+
* IntToHex(1234, 1) = '4D2'
+
* IntToHex(1234, 8) = '000004D2'
*IntToHex(1234, 8) = '000004D2'
 
 
</div>
 
</div>
 
|-
 
|-
| function '''HexToInt'''(const HexNum: String): Integer;
+
| function '''HexToInt'''(const HexNum: String): Integer;  
+
| Converts a hexadecimal value to its decimal representation.<br/>'''Warning:''' An error will occur if the parameter to this function cannot be converted to an integer!
| Converts a hexadecimal value to its decimal representation.<br>'''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;
+
| 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.
 
| 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;
+
| function '''Ord'''(X: Char): Byte;  
 
 
| Return an ordinal value (byte representation) of a character.
 
| Return an ordinal value (byte representation) of a character.
 
|-
 
|-
| function '''Chr'''(X: Byte): Char;
+
| function '''Chr'''(X: Byte): Char;  
 
 
| Return a character by its ordinal value (byte representation).
 
| Return a character by its ordinal value (byte representation).
 
|}
 
|}
  
== Date and Time ==
+
== Date and Time ==
  
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
 
! Function
 
! Function
 
 
! Remarks
 
! Remarks
 
|-
 
|-
| function '''Date''': TDateTime;
+
| function '''Date''': TDateTime;  
 
 
| Returns the current system date.
 
| Returns the current system date.
 
|-
 
|-
| function '''Time''': TDateTime;
+
| function '''Time''': TDateTime;  
 
 
| Returns the current system time.
 
| Returns the current system time.
 
|-
 
|-
| function '''Now''': TDateTime;
+
| function '''Now''': TDateTime;  
 
 
| Returns the current system date and time.
 
| Returns the current system date and time.
 
|-
 
|-
| function '''EncodeDate'''(Year, Month, Day: Word): TDateTime;
+
| 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.
 
| 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;
+
| 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.
 
| 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;
+
| 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.
 
| 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;
+
| 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.
 
| 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);
+
| procedure '''DecodeDate'''(const DateTime: TDateTime; var Year, Month, Day: Word);  
 
 
| Extracts '''Year''', '''Month''' and '''Day''' components from a given '''DateTime''' value.
 
| Extracts '''Year''', '''Month''' and '''Day''' components from a given '''DateTime''' value.
 
|-
 
|-
| procedure '''DecodeTime'''(const DateTime: TDateTime; var Hour, Min, Sec, MSec: Word);
+
| procedure '''DecodeTime'''(const DateTime: TDateTime; var Hour, Min, Sec, MSec: Word);  
 
 
| Extracts '''Hour''', '''Min''', '''Sec''' and '''MSec''' components from a given '''DateTime''' value.
 
| Extracts '''Hour''', '''Min''', '''Sec''' and '''MSec''' components from a given '''DateTime''' value.
 
|-
 
|-
| function '''DayOfWeek'''(const DateTime: TDateTime): Word;
+
| 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.
 
| 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;
 
| function '''DateTimeToUnix'''(D: TDateTime): Int64;
 
 
| Converts '''D''' value of type '''TDateTime''' to a Unix timestamp.
 
| Converts '''D''' value of type '''TDateTime''' to a Unix timestamp.
 
|-
 
|-
| function '''UnixToDateTime'''(U: Int64): TDateTime;
+
| function '''UnixToDateTime'''(U: Int64): TDateTime;  
 
 
| Converts a Unix timestamp to a value of '''TDateTime''' type.
 
| Converts a Unix timestamp to a value of '''TDateTime''' type.
 
|-
 
|-
| function '''FormatDateTime'''(const Fmt: String; D: TDateTime): String;
+
| 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.  
| 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 '''IncYear'''(const AValue: TDateTime;const ANumberOfYears: Integer): TDateTime;  
 
 
|  
 
|  
 
|-
 
|-
| function '''IncMonth'''(const AValue: TDateTime;ANumberOfMonths: Integer): TDateTime;
+
| function '''IncMonth'''(const AValue: TDateTime;ANumberOfMonths: Integer): TDateTime;  
 
 
|  
 
|  
 
|-
 
|-
| function '''IncWeek'''(const AValue: TDateTime; const ANumberOfWeeks: Integer): TDateTime;
+
| function '''IncWeek'''(const AValue: TDateTime; const ANumberOfWeeks: Integer): TDateTime;  
 
 
|  
 
|  
 
|-
 
|-
| function '''IncDay'''(const AValue: TDateTime;const ANumberOfDays: Integer): TDateTime;
+
| function '''IncDay'''(const AValue: TDateTime;const ANumberOfDays: Integer): TDateTime;  
 
 
|  
 
|  
 
|-
 
|-
| function '''IncHour'''(const AValue: TDateTime;const ANumberOfHours: Int64): TDateTime;
+
| function '''IncHour'''(const AValue: TDateTime;const ANumberOfHours: Int64): TDateTime;  
 
 
|  
 
|  
 
|-
 
|-
| function '''IncMinute'''(const AValue: TDateTime;const ANumberOfMinutes: Int64): TDateTime;
+
| function '''IncMinute'''(const AValue: TDateTime;const ANumberOfMinutes: Int64): TDateTime;  
 
 
|  
 
|  
 
|-
 
|-
| function '''IncSecond'''(const AValue: TDateTime;const ANumberOfSeconds: Int64): TDateTime;
+
| function '''IncSecond'''(const AValue: TDateTime;const ANumberOfSeconds: Int64): TDateTime;  
 
 
|  
 
|  
 
|-
 
|-
| function '''IncMilliSecond'''(const AValue: TDateTime;const ANumberOfMilliSeconds: Int64): TDateTime;
+
| function '''IncMilliSecond'''(const AValue: TDateTime;const ANumberOfMilliSeconds: Int64): TDateTime;  
 
 
|  
 
|  
 
|}
 
|}
  
== File Management ==
+
== File Management ==
  
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
 
! Function
 
! Function
 
 
! Remarks
 
! Remarks
 
|-
 
|-
| function '''WideFileSize'''(const FileName: WideString): Int64;
+
| function '''WideFileSize'''(const FileName: WideString): Int64;  
 
 
| Returns the size of the file.
 
| Returns the size of the file.
 
|-
 
|-
| function '''WideFileExists'''(const FileName: WideString): Boolean;
+
| function '''WideFileExists'''(const FileName: WideString): Boolean;  
 
 
| Check whether specified file exists. Returns TRUE if file exists, otherwise FALSE.
 
| Check whether specified file exists. Returns TRUE if file exists, otherwise FALSE.
 
|-
 
|-
| function '''WideDirectoryExists'''(const Directory: WideString): Boolean;
+
| function '''WideDirectoryExists'''(const Directory: WideString): Boolean;  
 
 
| Check whether specified directory exists. Returns TRUE if directory exists, otherwise FALSE.
 
| Check whether specified directory exists. Returns TRUE if directory exists, otherwise FALSE.
 
|-
 
|-
| function '''WideForceDirectories'''(Dir: WideString): Boolean;
+
| function '''WideForceDirectories'''(Dir: WideString): Boolean;  
 
 
| Makes sure that that all directories in the path exist. If they don't, function will try to create them, recursively. Returns TRUE if all folders exist or have been successfully created.
 
| Makes sure that that all directories in the path exist. If they don't, function will try to create them, recursively. Returns TRUE if all folders exist or have been successfully created.
 
|-
 
|-
| function '''WideCreateDir'''(const Dir: WideString): Boolean;
+
| function '''WideCreateDir'''(const Dir: WideString): Boolean;  
 
 
| Create specified directory (non-recursive). Returns TRUE on success, otherwise FALSE.
 
| Create specified directory (non-recursive). Returns TRUE on success, otherwise FALSE.
 
|-
 
|-
| function '''WideDeleteFile'''(const FileName: WideString): Boolean;
+
| function '''WideDeleteFile'''(const FileName: WideString): Boolean;  
 
 
| Delete physical file from the disk. Returns TRUE on success, otherwise FALSE.
 
| Delete physical file from the disk. Returns TRUE on success, otherwise FALSE.
 
|-
 
|-
| function '''WideRenameFile'''(const OldName, NewName: WideString): Boolean;
+
| function '''WideRenameFile'''(const OldName, NewName: WideString): Boolean;  
 
 
| Rename file from '''OldName''' to '''NewName'''. Returns TRUE on success, otherwise FALSE.
 
| Rename file from '''OldName''' to '''NewName'''. Returns TRUE on success, otherwise FALSE.
 
|-
 
|-
 
| function '''WideCopyFile'''(FromFile, ToFile: WideString; FailIfExists: Boolean): Boolean;
 
| function '''WideCopyFile'''(FromFile, ToFile: WideString; FailIfExists: Boolean): Boolean;
 
 
| Rename file from '''FromFile''' to '''ToFile'''. If '''FailIfExists''' flag is TRUE, file will not be copied when destination file already exists, otherwise, destination file will be overwritten. Returns TRUE on success, otherwise FALSE.
 
| Rename file from '''FromFile''' to '''ToFile'''. If '''FailIfExists''' flag is TRUE, file will not be copied when destination file already exists, otherwise, destination file will be overwritten. Returns TRUE on success, otherwise FALSE.
 
|-
 
|-
| function '''WideFileSearch'''(const Name, DirList: WideString): WideString;
+
| function '''WideFileSearch'''(const Name, DirList: WideString): WideString;  
 
 
| Search through the directories passed in '''DirList''' for a file named '''Name'''. DirList is a list of path names delimited by semicolons. If file matching Name is located, function returns a string specifying a path name for that file. If no matching file exists, function returns an empty string.
 
| Search through the directories passed in '''DirList''' for a file named '''Name'''. DirList is a list of path names delimited by semicolons. If file matching Name is located, function returns a string specifying a path name for that file. If no matching file exists, function returns an empty string.
 
|-
 
|-
| function '''WideGetCurrentDir''': WideString;
+
| function '''WideGetCurrentDir''': WideString;  
 
 
| Returns the current working directory.
 
| Returns the current working directory.
 
|-
 
|-
| function '''WideSetCurrentDir'''(const Dir: WideString): Boolean;
+
| function '''WideSetCurrentDir'''(const Dir: WideString): Boolean;  
 
 
| Sets the current working directory to the directory specified by parameter '''Dir'''.
 
| Sets the current working directory to the directory specified by parameter '''Dir'''.
 
|-
 
|-
| procedure '''WideScanDirForFiles'''(Dir: WideString; var Files: TStringsArray; const Recursive, IncludeHidden, IncludeSystem: Boolean; const Mask: WideString);
+
| 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);
+
| procedure '''WideScanDirForFolders'''(Dir: WideString; var Folders: TStringsArray; const Recursive, IncludeHidden, IncludeSystem: Boolean);  
 
 
|  
 
|  
 
|}
 
|}
  
== File Name Utilities ==
+
== File Name Utilities ==
  
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
 
! Function
 
! Function
 
 
! Remarks
 
! Remarks
 
|-
 
|-
| function '''WideExtractFilePath'''(const FileName: WideString): WideString;
+
| function '''WideExtractFilePath'''(const FileName: WideString): WideString;  
 
 
| Returns the entire path of the file <br>(starting from the drive letter)
 
| Returns the entire path of the file <br>(starting from the drive letter)
 
|-
 
|-
| function '''WideExtractFileDir'''(const FileName: WideString): WideString;
+
| function '''WideExtractFileDir'''(const FileName: WideString): WideString;  
 
 
| Returns the folder in which the file is located.
 
| Returns the folder in which the file is located.
 
|-
 
|-
| function '''WideExtractFileDrive'''(const FileName: WideString): WideString;
+
| function '''WideExtractFileDrive'''(const FileName: WideString): WideString;  
 
 
| Returns the drive letter<br>???or is it the name of the drive?
 
| Returns the drive letter<br>???or is it the name of the drive?
 
|-
 
|-
| function '''WideExtractFileName'''(const FileName: WideString): WideString;
+
| function '''WideExtractFileName'''(const FileName: WideString): WideString;  
 
 
| Returns the filename with extension. <br>(e.g. "FileName.txt")
 
| Returns the filename with extension. <br>(e.g. "FileName.txt")
 
|-
 
|-
| function '''WideExtractBaseName'''(const FileName: WideString): WideString;
+
| function '''WideExtractBaseName'''(const FileName: WideString): WideString;  
 
 
| Returns only the file' base name (but not the dot or extension). (e.g. "FileName")
 
| Returns only the file' base name (but not the dot or extension). (e.g. "FileName")
 
|-
 
|-
| function '''WideExtractFileExt'''(const FileName: WideString): WideString;
+
| function '''WideExtractFileExt'''(const FileName: WideString): WideString;  
 
 
| Returns the file's extension with the dot (e.g. ".txt")
 
| Returns the file's extension with the dot (e.g. ".txt")
 
|-
 
|-
| function '''WideChangeFileExt'''(const FileName, Extension: WideString): WideString;
+
| function '''WideChangeFileExt'''(const FileName, Extension: WideString): WideString;  
 
 
| Replaces the original extension, and returns the new filename with extension. (e.g. "FineName.txt" -&gt; "FineName.pdf")
 
| Replaces the original extension, and returns the new filename with extension. (e.g. "FineName.txt" -&gt; "FineName.pdf")
 
|-
 
|-
| function '''WideStripExtension'''(const FileName: WideString): WideString;
+
| function '''WideStripExtension'''(const FileName: WideString): WideString;  
 
 
| Strips off the extension from the filename.<br>??? what does it return?
 
| Strips off the extension from the filename.<br>??? what does it return?
 
|-
 
|-
| function '''WideExpandFileName'''(const FileName: WideString): WideString;
+
| function '''WideExpandFileName'''(const FileName: WideString): WideString;  
 
 
| &nbsp;???
 
| &nbsp;???
 
|-
 
|-
| function '''WideExtractRelativePath'''(const BaseName, DestName: WideString): WideString;
+
| function '''WideExtractRelativePath'''(const BaseName, DestName: WideString): WideString;  
 
 
|  
 
|  
 
Given two files located in two different folders, returns the relative path of '''DestName''' file with respect to the '''BaseName''' file.  
 
Given two files located 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:  
 
e.g. If we input these two filenames:  
 
  
 
'''D:\Folder1\FileName1.txt'''&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; (The base file)<br>'''D:\Folder2\Folder22\FileName2.pdf'''&nbsp;&nbsp; (The destination file)  
 
'''D:\Folder1\FileName1.txt'''&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; (The base file)<br>'''D:\Folder2\Folder22\FileName2.pdf'''&nbsp;&nbsp; (The destination file)  
 
  
 
Then the relative path of the destination file is-<br>'''..\Folder2\Folder22\FileName2.pdf'''  
 
Then the relative path of the destination file is-<br>'''..\Folder2\Folder22\FileName2.pdf'''  
 
 
 
|-
 
|-
| function '''WideExtractShortPathName'''(const FileName: WideString): WideString;
+
| function '''WideExtractShortPathName'''(const FileName: WideString): WideString;  
 
 
|  
 
|  
 
|-
 
|-
| function '''WideIncludeTrailingPathDelimiter'''(const S: WideString): WideString;
+
| function '''WideIncludeTrailingPathDelimiter'''(const S: WideString): WideString;  
 
 
|  
 
|  
 
|-
 
|-
| function '''WideExcludeTrailingPathDelimiter'''(const S: WideString): WideString;
+
| function '''WideExcludeTrailingPathDelimiter'''(const S: WideString): WideString;  
 
 
|  
 
|  
 
|-
 
|-
| function '''WideSameFileName'''(const S1, S2: WideString): Boolean;
+
| function '''WideSameFileName'''(const S1, S2: WideString): Boolean;  
 
 
| Compares the filenames '''S1''' and '''S2''', and returns TRUE if they are identical.
 
| Compares the filenames '''S1''' and '''S2''', and returns TRUE if they are identical.
 
|-
 
|-
| function '''WideGetEnvironmentVar'''(const VarName: WideString): WideString;
+
| function '''WideGetEnvironmentVar'''(const VarName: WideString): WideString;  
 
 
|  
 
|  
 
|}
 
|}
  
== File Read/Write ==
+
== File Read/Write ==
  
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
 
! Function
 
! Function
 
 
! Remarks
 
! Remarks
 
|-
 
|-
| function '''FileReadFragment'''(const FileName: WideString; Start, Length: Integer): String;
+
| 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).
 
| 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;
+
| 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).
 
| 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 '''FileCountLines'''(const FileName: WideString): Integer;  
 
 
|  
 
|  
 
|-
 
|-
| function '''FileReadContent'''(const FileName: WideString): String;
+
| function '''FileReadContent'''(const FileName: WideString): String;  
 
 
|  
 
|  
 
|-
 
|-
| procedure '''FileWriteContent'''(const FileName: WideString; const Content: String);
+
| procedure '''FileWriteContent'''(const FileName: WideString; const Content: String);  
 
 
|  
 
|  
 
|-
 
|-
| procedure '''FileAppendContent'''(const FileName: WideString; const Content: String);
+
| procedure '''FileAppendContent'''(const FileName: WideString; const Content: String);  
 
 
|  
 
|  
 
|}
 
|}
  
== File Time ==
+
== File Time ==
  
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
 
! Function
 
! Function
 
 
! Remarks
 
! Remarks
 
|-
 
|-
| function '''FileTimeModified'''(const FileName: WideString): TDateTime;
+
| function '''FileTimeModified'''(const FileName: WideString): TDateTime;  
 
 
| Returns last modified time of the specified file.
 
| Returns last modified time of the specified file.
 
|-
 
|-
| function '''FileTimeCreated'''(const FileName: WideString): TDateTime;
+
| function '''FileTimeCreated'''(const FileName: WideString): TDateTime;  
 
 
| Returns creation time of the specified file.
 
| Returns creation time of the specified file.
 
|-
 
|-
| function '''SetFileTimeCreated'''(const FileName: WideString; const DateTime: TDateTime): Boolean;
+
| function '''SetFileTimeCreated'''(const FileName: WideString; const DateTime: TDateTime): Boolean;  
 
 
| Sets creation time for the specified file.
 
| Sets creation time for the specified file.
 
|-
 
|-
| function '''SetFileTimeModified'''(const FileName: WideString; const DateTime: TDateTime): Boolean;
+
| function '''SetFileTimeModified'''(const FileName: WideString; const DateTime: TDateTime): Boolean;  
 
 
| Sets last modified time for the specified file.
 
| Sets last modified time for the specified file.
 
|}
 
|}
  
== Process Execution ==
+
== Process Execution ==
  
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
 
! Function
 
! Function
 
 
! Remarks
 
! Remarks
 
|-
 
|-
| function '''ShellOpenFile'''(const FileName: WideString): Boolean;
+
| function '''ShellOpenFile'''(const FileName: WideString): Boolean;  
 
 
| Run (open) a file specified by '''FileName'''. Works like "Start &gt; Run" command. Parameter does not have to be an exacutable file, it can by any file or protocol with assigned handler. For example, you can open a Word document or a web page, and associated application will be launched:
 
| Run (open) a file specified by '''FileName'''. Works like "Start &gt; Run" command. Parameter does not have to be an exacutable file, it can by any file or protocol with assigned handler. For example, you can open a Word document or a web page, and associated application will be launched:
<div style="font-family: monospace">
+
<div style="font-family: monospace">
*ShellOpenFile('<nowiki>http://www.den4b.com/</nowiki>');
+
* ShellOpenFile('<nowiki>http://www.den4b.com/</nowiki>');
+
* ShellOpenFile('C:\Document.doc');
*ShellOpenFile('C:\Document.doc');
 
 
</div>
 
</div>
 
|-
 
|-
| function '''ExecuteProgram'''(const Command: String; WaitForProgram: Boolean): Cardinal;
+
| function '''ExecuteProgram'''(const Command: String; WaitForProgram: Boolean): Cardinal;  
 
 
| Execute a command line specified by parameter '''Command'''. Works like "Command Prompt". Parameter '''WaitForProgram''' allows you to specify whether the code needs to wait until the command (launched program) has finished executing.
 
| Execute a command line specified by parameter '''Command'''. Works like "Command Prompt". Parameter '''WaitForProgram''' allows you to specify whether the code needs to wait until the command (launched program) has finished executing.
 
|-
 
|-
| function '''ExecConsoleApp'''(const CommandLine: String; out Output: String): Cardinal;
+
| function '''ExecConsoleApp'''(const CommandLine: String; out Output: String): Cardinal;  
 
 
| Execute a command line specified by parameter '''CommandLine''' and record its standard output in the variable '''Output'''. Works like "Command Prompt". Should be used only for console style applications. Returns the exit code.
 
| Execute a command line specified by parameter '''CommandLine''' and record its standard output in the variable '''Output'''. Works like "Command Prompt". Should be used only for console style applications. Returns the exit code.
 
|}
 
|}
  
== Dialogs ==
+
== Dialogs ==
  
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
 
! Function
 
! Function
 
 
! Remarks
 
! Remarks
 
|-
 
|-
| procedure '''ShowMessage'''(const Msg: String);
+
| procedure '''ShowMessage'''(const Msg: String);  
 
 
| Show a simple dialog with the message specified by '''Msg''' parameter.
 
| Show a simple dialog with the message specified by '''Msg''' parameter.
 
|-
 
|-
| procedure '''WideShowMessage'''(const Msg: WideString);
+
| procedure '''WideShowMessage'''(const Msg: WideString);  
 
 
| Same as '''ShowMessage''' function but parameter is Unicode text.
 
| Same as '''ShowMessage''' function but parameter is Unicode text.
 
|-
 
|-
| function '''DialogYesNo'''(const Msg: String): Boolean;
+
| function '''DialogYesNo'''(const Msg: String): Boolean;  
 
 
| Show a simple prompt with the message specified by '''Msg''' parameter and two button: Ys and No. Returns TRUE if user clicks Yes button, otherwise FALSE.
 
| Show a simple prompt with the message specified by '''Msg''' parameter and two button: Ys and No. Returns TRUE if user clicks Yes button, otherwise FALSE.
 
|-
 
|-
| function '''WideDialogYesNo'''(const Msg: WideString): Boolean;
+
| function '''WideDialogYesNo'''(const Msg: WideString): Boolean;  
 
 
| Same as '''DialogYesNo''' function but parameter is Unicode text.
 
| Same as '''DialogYesNo''' function but parameter is Unicode text.
 
|-
 
|-
| function '''InputBox'''(const ACaption, APrompt, ADefault: String): String;
+
| function '''InputBox'''(const ACaption, APrompt, ADefault: String): String;  
 
 
|  
 
|  
 
|-
 
|-
| function '''InputQuery'''(const ACaption, APrompt: String; var Value: String): Boolean;
+
| function '''InputQuery'''(const ACaption, APrompt: String; var Value: String): Boolean;  
 
 
|  
 
|  
 
|-
 
|-
| function '''WideInputBox'''(const ACaption, APrompt, ADefault: WideString): WideString;
+
| function '''WideInputBox'''(const ACaption, APrompt, ADefault: WideString): WideString;  
 
 
|  
 
|  
 
|-
 
|-
| function '''WideInputQuery'''(const ACaption, APrompt: WideString; var Value: WideString): Boolean;
+
| function '''WideInputQuery'''(const ACaption, APrompt: WideString; var Value: WideString): Boolean;  
 
 
|  
 
|  
 
|}
 
|}
  
== Other Routines ==
+
== Other Routines ==
  
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
 
! Function
 
! Function
 
 
! Remarks
 
! Remarks
 
|-
 
|-
| procedure '''Sleep'''(Milliseconds: Cardinal);
+
| procedure '''Sleep'''(Milliseconds: Cardinal);  
 
 
| Sleep (pause the execution) for specified number of '''Milliseconds'''.
 
| Sleep (pause the execution) for specified number of '''Milliseconds'''.
 
|-
 
|-
| procedure '''DivMod'''(Dividend: Integer; Divisor: Word; var Result, Remainder: Word);
+
| procedure '''DivMod'''(Dividend: Integer; Divisor: Word; var Result, Remainder: Word);  
 
 
| Perform integer division and fetch the remainder as well, all in one operation. '''Dividend''' is the integer into which you are dividing. '''Divisor''' is the value by which to divide '''Dividend'''. '''Result''' returns the result of the integer division. '''Remainder''' returns the remainder (the difference between Result * Divisor and Dividend).
 
| Perform integer division and fetch the remainder as well, all in one operation. '''Dividend''' is the integer into which you are dividing. '''Divisor''' is the value by which to divide '''Dividend'''. '''Result''' returns the result of the integer division. '''Remainder''' returns the remainder (the difference between Result * Divisor and Dividend).
 
|-
 
|-
| procedure '''Randomize''';
+
| procedure '''Randomize''';  
 
 
| Prepares the random number generator. Should only be called once per application cycle.
 
| Prepares the random number generator. Should only be called once per application cycle.
 
|-
 
|-
| function '''RandomRange'''(const AFrom, ATo: Integer): Integer;
+
| function '''RandomRange'''(const AFrom, ATo: Integer): Integer;  
 
 
| Return a random integer number within the specified '''AFrom'''..'''ATo''' (inclusive) range.
 
| Return a random integer number within the specified '''AFrom'''..'''ATo''' (inclusive) range.
 
|-
 
|-
| function '''GetClipboardText''': WideString;
+
| function '''GetClipboardText''': WideString;  
 
 
| Get the content of the the clipboard (text only).
 
| Get the content of the the clipboard (text only).
 
|-
 
|-
| procedure '''SetClipboardText'''(const S: WideString);
+
| procedure '''SetClipboardText'''(const S: WideString);  
 
 
| Set the content of the the clipboard (text only).
 
| Set the content of the the clipboard (text only).
 
|-
 
|-
| function '''Base64Encode'''(const S: String): String;
+
| function '''Base64Encode'''(const S: String): String;  
 
 
| Encode string '''S''' into [http://en.wikipedia.org/wiki/Base64 Base64]. Useful for encoding binary data in order to minimize the likelihood of data being modified in transit through different systems, like email or internet.
 
| Encode string '''S''' into [http://en.wikipedia.org/wiki/Base64 Base64]. Useful for encoding binary data in order to minimize the likelihood of data being modified in transit through different systems, like email or internet.
 
|-
 
|-
| function '''Base64Decode'''(const S: String): String;
+
| function '''Base64Decode'''(const S: String): String;  
 
 
| Decode [http://en.wikipedia.org/wiki/Base64 Base64] string;
 
| Decode [http://en.wikipedia.org/wiki/Base64 Base64] string;
 
|-
 
|-
| function '''GetTickCount''': Cardinal;
+
| function '''GetTickCount''': Cardinal;  
 
 
| Retrieves the number of milliseconds that have elapsed since the system was started (up to 49.7 days, then timer resets). The precision of this timer is very limited.
 
| Retrieves the number of milliseconds that have elapsed since the system was started (up to 49.7 days, then timer resets). The precision of this timer is very limited.
 
|-
 
|-
| function '''SizeOf'''(X): Integer;
+
| function '''SizeOf'''(X): Integer;  
 
 
| Pass a variable reference to determine the number of bytes used to represent the variable. Pass a type identifier to determine the number of bytes used to represent instances of that type.
 
| Pass a variable reference to determine the number of bytes used to represent the variable. Pass a type identifier to determine the number of bytes used to represent instances of that type.
 
|}
 
|}

Revision as of 12:50, 23 June 2010

Introduction

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

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

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

Basic String Handling

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 Management

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

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; Returns the result of replacing on a string S, a string OldPattern (Case Sensitive), with a NewPattern.
function WideReplaceText(const S, OldPattern, NewPattern: WideString): WideString; Returns the result of replacing on a string S, a text OldPattern (Case Non-Sensitive), with a NewPattern.
function WideSplitString(const Input, Delimiter: WideString): TStringsArray;

Splits the WideString Input wherever Delimiter occurs, and returns an array that contains the split parts.

  • The Delimiter itself can be a multi-character WideString.
    (Unlike the usual comma, hyphen or space that is used for this purpose)
  • The split parts (returned as elements of the array) do not contain the Delimiter WideString
function WideCaseCapitalize(const S: WideString): WideString;

Returns the Sentence case version of the WideString S.

Only the first alphabetic character is capitalized. All other alphabetic characters are converted to lowercase.

  • If S begins with numeric characters, the first alphabetic character that follows will be capitalized.
function WideCaseInvert(const S: WideString): WideString; Inverts the case of all characters in the WideString S and returns the WideString.

Meta Tags Extraction

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

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

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

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

Regular Expressions

Function Remarks
function ReplaceRegEx(const Input, Find, Replace: WideString;const CaseSensitive, UseSubstitution: Boolean): WideString; Find-and-replace function using RegEx. Works like RegEx rule.
function MatchesRegEx(const Input, Find: WideString;const CaseSensitive: Boolean): TStringsArray; Returns a list of RegEx matches as an array. Function returns an array of full matches, which matched the entire expression, not the sub-patterns.

For example, given the Input 'Ax1_-_Bx2---Cx3' and the function MatchesRegEx(Input, '([A-Z])x(\d)', False). What we get is ['Ax1', 'Bx2', 'Cx3']. Being these the 3 full matches found on the Input.

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, given the Input 'Ax1_-_Bx2---Cx3' and the function SubMatchesRegEx(Input, '([A-Z])x(\d)', False). What we get is ['A', '1']. Being these the first sub-matches requested (two in this case).

In this way, it can easily be combined with MatchesRegEx function, to allow users to find all global matches, and then parse those matches through SubMatchesRegEx function to find individual sub-expression matches of each global match.

General parameters of the functions:

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

Unicode Character Handling

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

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

Unicode Conversion

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

Function Remarks
function BoolToStr(B: Boolean): String; Convert boolean variable into a string. Returns True or False string.
function IntToStr(Value: Integer): String; Converts an integer to a string. The following assumptions are correct:
  • IntToStr(123) = '123'
  • IntToStr(0123) = '123'
  • IntToStr(123) <> '0123'
function StrToInt(const S: String): Integer; Converts a string to an integer. The following equalities are correct:
  • StrToInt('123') = 123
  • StrToInt('123') = 0123
  • StrToInt('0123') = 123

Warning: An error will occur if the parameter to this function cannot be converted to an integer!

function StrToIntDef(const S: String; const Default: Integer): Integer; Behaves like StrToInt function, but instead of producing an error on incorrect input function allows the Default value to be specified, which will be returned if the input cannot be converted to an integer.
function FloatToStr(Value: Extended): string; Converts supplied floating point value to its string representation, using default system format.
function StrToFloat(const S: string): Extended; Converts supplied string to a floating point value.
Warning: An error will occur if the parameter to this function cannot be converted to a floating point value!
function StrToFloatDef(const S: string; const Default: Extended): Extended; Behaves like StrToFloat 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 a floating point value.
function FormatFloat(const Format: string; Value: Extended): string; Converts supplied floating point value to its string representation, using user specific Format. Format string may contain following specifiers:
Specifier Represents
0 (zero) Digit placeholder. If the value being formatted has a digit in the position where the "0" appears in the format string, then that digit is copied to the output string. Otherwise, a "0" is stored in that position in the output string.
# (hash) Digit placeholder. If the value being formatted has a digit in the position where the "#" appears in the format string, then that digit is copied to the output string. Otherwise, nothing is stored in that position in the output string.
. (dot) Decimal point. The first "." character in the format string determines the location of the decimal separator in the formatted value, any additional "." characters are ignored.
, (comma) Thousand separator. If the format string contains one or more "," characters, the output will have thousand separators inserted between each group of three digits to the left of the decimal point. The placement and number of "," characters in the format string does not affect the output.
function DateToStr(D: TDateTime): String; Converts a date to a string, using system format for the short date, for example: dd/mm/yyyy.
function StrToDate(const S: String): TDateTime; Converts a date string to a proper TDateTime value, using system format for the short date, for example: dd/mm/yyyy.
function IntToHex(Value: Integer; Digits: Integer): String; Converts an integer to its hexadecimal representation. Here are samples:
  • IntToHex(1234, 1) = '4D2'
  • IntToHex(1234, 8) = '000004D2'
function HexToInt(const HexNum: String): Integer; Converts a hexadecimal value to its decimal representation.
Warning: An error will occur if the parameter to this function cannot be converted to an integer!
function HexToIntDef(const HexNum: String; Default: Integer): Integer; Behaves like HexToInt function, but instead of producing an error on incorrect input function allows the Default value to be specified, which will be returned if the input cannot be converted to an integer.
function Ord(X: Char): Byte; Return an ordinal value (byte representation) of a character.
function Chr(X: Byte): Char; Return a character by its ordinal value (byte representation).

Date and Time

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

File Management

Function Remarks
function WideFileSize(const FileName: WideString): Int64; Returns the size of the file.
function WideFileExists(const FileName: WideString): Boolean; Check whether specified file exists. Returns TRUE if file exists, otherwise FALSE.
function WideDirectoryExists(const Directory: WideString): Boolean; Check whether specified directory exists. Returns TRUE if directory exists, otherwise FALSE.
function WideForceDirectories(Dir: WideString): Boolean; Makes sure that that all directories in the path exist. If they don't, function will try to create them, recursively. Returns TRUE if all folders exist or have been successfully created.
function WideCreateDir(const Dir: WideString): Boolean; Create specified directory (non-recursive). Returns TRUE on success, otherwise FALSE.
function WideDeleteFile(const FileName: WideString): Boolean; Delete physical file from the disk. Returns TRUE on success, otherwise FALSE.
function WideRenameFile(const OldName, NewName: WideString): Boolean; Rename file from OldName to NewName. Returns TRUE on success, otherwise FALSE.
function WideCopyFile(FromFile, ToFile: WideString; FailIfExists: Boolean): Boolean; Rename file from FromFile to ToFile. If FailIfExists flag is TRUE, file will not be copied when destination file already exists, otherwise, destination file will be overwritten. Returns TRUE on success, otherwise FALSE.
function WideFileSearch(const Name, DirList: WideString): WideString; Search through the directories passed in DirList for a file named Name. DirList is a list of path names delimited by semicolons. If file matching Name is located, function returns a string specifying a path name for that file. If no matching file exists, function returns an empty string.
function WideGetCurrentDir: WideString; Returns the current working directory.
function WideSetCurrentDir(const Dir: WideString): Boolean; Sets the current working directory to the directory specified by parameter Dir.
procedure WideScanDirForFiles(Dir: WideString; var Files: TStringsArray; const Recursive, IncludeHidden, IncludeSystem: Boolean; const Mask: WideString);
procedure WideScanDirForFolders(Dir: WideString; var Folders: TStringsArray; const Recursive, IncludeHidden, IncludeSystem: Boolean);

File Name Utilities

Function Remarks
function WideExtractFilePath(const FileName: WideString): WideString; Returns the entire path of the file
(starting from the drive letter)
function WideExtractFileDir(const FileName: WideString): WideString; Returns the folder in which the file is located.
function WideExtractFileDrive(const FileName: WideString): WideString; Returns the drive letter
???or is it the name of the drive?
function WideExtractFileName(const FileName: WideString): WideString; Returns the filename with extension.
(e.g. "FileName.txt")
function WideExtractBaseName(const FileName: WideString): WideString; Returns only the file' base name (but not the dot or extension). (e.g. "FileName")
function WideExtractFileExt(const FileName: WideString): WideString; Returns the file's extension with the dot (e.g. ".txt")
function WideChangeFileExt(const FileName, Extension: WideString): WideString; Replaces the original extension, and returns the new filename with extension. (e.g. "FineName.txt" -> "FineName.pdf")
function WideStripExtension(const FileName: WideString): WideString; Strips off the extension from the filename.
??? what does it return?
function WideExpandFileName(const FileName: WideString): WideString;  ???
function WideExtractRelativePath(const BaseName, DestName: WideString): WideString;

Given two files located in two different folders, returns the relative path of DestName file with respect to the BaseName file.

e.g. If we input these two filenames:

D:\Folder1\FileName1.txt                   (The base file)
D:\Folder2\Folder22\FileName2.pdf   (The destination file)

Then the relative path of the destination file is-
..\Folder2\Folder22\FileName2.pdf

function WideExtractShortPathName(const FileName: WideString): WideString;
function WideIncludeTrailingPathDelimiter(const S: WideString): WideString;
function WideExcludeTrailingPathDelimiter(const S: WideString): WideString;
function WideSameFileName(const S1, S2: WideString): Boolean; Compares the filenames S1 and S2, and returns TRUE if they are identical.
function WideGetEnvironmentVar(const VarName: WideString): WideString;

File Read/Write

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 Time

Function Remarks
function FileTimeModified(const FileName: WideString): TDateTime; Returns last modified time of the specified file.
function FileTimeCreated(const FileName: WideString): TDateTime; Returns creation time of the specified file.
function SetFileTimeCreated(const FileName: WideString; const DateTime: TDateTime): Boolean; Sets creation time for the specified file.
function SetFileTimeModified(const FileName: WideString; const DateTime: TDateTime): Boolean; Sets last modified time for the specified file.

Process Execution

Function Remarks
function ShellOpenFile(const FileName: WideString): Boolean; Run (open) a file specified by FileName. Works like "Start > Run" command. Parameter does not have to be an exacutable file, it can by any file or protocol with assigned handler. For example, you can open a Word document or a web page, and associated application will be launched:
  • ShellOpenFile('http://www.den4b.com/');
  • ShellOpenFile('C:\Document.doc');
function ExecuteProgram(const Command: String; WaitForProgram: Boolean): Cardinal; Execute a command line specified by parameter Command. Works like "Command Prompt". Parameter WaitForProgram allows you to specify whether the code needs to wait until the command (launched program) has finished executing.
function ExecConsoleApp(const CommandLine: String; out Output: String): Cardinal; Execute a command line specified by parameter CommandLine and record its standard output in the variable Output. Works like "Command Prompt". Should be used only for console style applications. Returns the exit code.

Dialogs

Function Remarks
procedure ShowMessage(const Msg: String); Show a simple dialog with the message specified by Msg parameter.
procedure WideShowMessage(const Msg: WideString); Same as ShowMessage function but parameter is Unicode text.
function DialogYesNo(const Msg: String): Boolean; Show a simple prompt with the message specified by Msg parameter and two button: Ys and No. Returns TRUE if user clicks Yes button, otherwise FALSE.
function WideDialogYesNo(const Msg: WideString): Boolean; Same as DialogYesNo function but parameter is Unicode text.
function InputBox(const ACaption, APrompt, ADefault: String): String;
function InputQuery(const ACaption, APrompt: String; var Value: String): Boolean;
function WideInputBox(const ACaption, APrompt, ADefault: WideString): WideString;
function WideInputQuery(const ACaption, APrompt: WideString; var Value: WideString): Boolean;

Other Routines

Function Remarks
procedure Sleep(Milliseconds: Cardinal); Sleep (pause the execution) for specified number of Milliseconds.
procedure DivMod(Dividend: Integer; Divisor: Word; var Result, Remainder: Word); Perform integer division and fetch the remainder as well, all in one operation. Dividend is the integer into which you are dividing. Divisor is the value by which to divide Dividend. Result returns the result of the integer division. Remainder returns the remainder (the difference between Result * Divisor and Dividend).
procedure Randomize; Prepares the random number generator. Should only be called once per application cycle.
function RandomRange(const AFrom, ATo: Integer): Integer; Return a random integer number within the specified AFrom..ATo (inclusive) range.
function GetClipboardText: WideString; Get the content of the the clipboard (text only).
procedure SetClipboardText(const S: WideString); Set the content of the the clipboard (text only).
function Base64Encode(const S: String): String; Encode string S into Base64. Useful for encoding binary data in order to minimize the likelihood of data being modified in transit through different systems, like email or internet.
function Base64Decode(const S: String): String; Decode Base64 string;
function GetTickCount: Cardinal; Retrieves the number of milliseconds that have elapsed since the system was started (up to 49.7 days, then timer resets). The precision of this timer is very limited.
function SizeOf(X): Integer; Pass a variable reference to determine the number of bytes used to represent the variable. Pass a type identifier to determine the number of bytes used to represent instances of that type.