unautils.pas

Voice Commnucation Components for Delphi

{DP:METHOD
  Converts integer value to string.
  <BR />base is the base for conversion (10 or 16 for example, max is 69).
  <BR />If split &gt; 0, the result will be divided on groups of digits, with at least split digits in every group.
  <BR />splitchar is used to delimiter one group from other (when split &gt; 0).
  <BR />For example, when split = 3 and splitchar = ' ', instead of '12345' this function returns '12 345'.
}
function int2str(value: int; base: unsigned = 10; split: unsigned = 0; splitchar: char = ' '): string; overload;
function int2strW(value: int; base: unsigned = 10; split: unsigned = 0; const splitchar: wideChar = ' '): wideString; overload;
{DP:METHOD
  Converts int64 value to string.
  <BR />See int2str(int) for description of other parameters.
}
function int2str(const value: int64; base: unsigned = 10; split: unsigned = 0; splitchar: char = ' '): string; overload;
function int2strW(const value: int64; base: unsigned = 10; split: unsigned = 0; const splitchar: wideChar = ' '): wideString; overload;
{DP:METHOD
  Converts unsigned value to string.
  <BR />See int2str(int) for description of other parameters.
}
function int2str(value: unsigned; base: unsigned = 10; split: unsigned = 0; splitchar: char = ' '): string; overload;
function int2strW(value: unsigned; base: unsigned = 10; split: unsigned = 0; const splitchar: wideChar = ' '): wideString; overload;
{DP:METHOD
  Converts word value to string.
  <BR />See int2str(int) for description of other parameters.
}
function int2str(value: word; base: unsigned = 10; split: unsigned = 0; splitchar: char = ' '): string; overload;
function int2strW(value: word; base: unsigned = 10; split: unsigned = 0; const splitchar: wideChar = ' '): wideString; overload;
{DP:METHOD
}
function intArray2str(value: pInt32Array): string;

{DP:METHOD
  Converts string value to boolean. Returns false if value = '0' and true otherwise.
}
function str2bool(const value: string; defValue: bool = false): bool;
{DP:METHOD
  Converts string value to boolean. Returns true if value = 'true', false if value = 'false' and defValue otherwise.
}
function strStr2bool(const value: string; defValue: bool = false): bool;
{DP:METHOD
  Converts string value to byte.
  <BR />Returns defValue if conversion fails.
}
function str2intByte(const value: string; defValue: byte = 0; base: unsigned = 10; ignoreTrails: bool = false): byte; overload;
{DP:METHOD
  Converts string value to integer.
  <BR />Returns defValue if conversion fails.
}
function str2intInt(const value: string; defValue: int = 0; base: unsigned = 10; ignoreTrails: bool = false): int; overload;
{DP:METHOD
  Converts string value to unsigned.
  <BR />Returns defValue if conversion fails.
}
function str2intUnsigned(const value: string; defValue: unsigned = 0; base: unsigned = 10; ignoreTrails: bool = false): unsigned; overload;
{DP:METHOD
  Converts string value to int64.
  <BR />Returns defValue if conversion fails.
}
function str2intInt64(const value: string; defValue: int64 = 0; base: unsigned = 10; ignoreTrails: bool = false): int64; overload;
{DP:METHOD
}
function str2intArray(const value: string; subLevel: int = 0): pInt32Array;

{DP:METHOD
  Returns new GUID.
}
function newGUID(): string;

{DP:METHOD
  Converts milliseconds to days, hours, minutes, seconds and milliseconds
}
procedure ms2time(ms: int64; out dd, hh, mm, ss, mss: unsigned);
{$IFDEF __SYSUTILS_H_ }
{$ELSE}

{DP:METHOD
  Encodes hours, minutes seconds and milliseconds to tDateTime value
}
function encodeTime(hh, mm, ss, ms: unsigned): tDateTime;

{$ENDIF }
{DP:METHOD
  Converts milliseconds to tDateTime value
}
function ms2dateTime(ms: int64): tDateTime;
{DP:METHOD
}
function dateTime2b64str(const dateTime: tDateTime): string;
{DP:METHOD
}
function b64str2dateTime(const date: string; const defValue: tDateTime = 0): tDateTime;
{DP:METHOD
}
function sysTime2str(time: pSYSTEMTIME = nil; const format: wideString = ''; locale: LCID = LOCALE_USER_DEFAULT; flags: DWORD = LOCALE_NOUSEROVERRIDE or TIME_NOSECONDS): wideString;
{DP:METHOD
}
function sysDate2str(date: pSYSTEMTIME = nil; const format: wideString = ''; locale: LCID = LOCALE_USER_DEFAULT; flags: DWORD = 0): wideString;
{DP:METHOD
}
function sysDateTime2localDateTime(const sysDate: SYSTEMTIME; out localDate: SYSTEMTIME): bool;
{DP:METHOD
}
function utc2local(const dateTime: SYSTEMTIME): SYSTEMTIME;
{DP:METHOD
  Returns number of full months passed between two dates.
}
function monthsPassed(const now, than: SYSTEMTIME): int;


{$IFDEF __SYSUTILS_H_ }
{$ELSE}

type
  // --  --
  tDayTable = array[1..12] of byte;

const
  // --  --
  monthDays: array [boolean] of tDayTable =
    ((31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31),
     (31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31));

{DP:METHOD
  Returns true if specified year is leap.
}
function isLeapYear(year: word): bool;

{$ENDIF }


{DP:METHOD
  Converts value and total into percentage.
  <BR />For example, if value = 1, and total = 50 result will be 2.
}
function percent(value, total: unsigned): unsigned; overload;
{DP:METHOD
  Converts value and total into percentage.
  <BR />For example, if value = 10, and total = 50 result will be 20.
}
function percent(value, total: int64): int64; overload;


//	STRINGS

{DP:METHOD
  Trims the specified value by removing all control or space characters from left (beginning) and right (ending) of the string.
}
function trim(const value: string; left: bool = true; right: bool = true): string;
function trimW(const value: wideString; left: bool = true; right: bool = true): wideString;
{DP:METHOD
  Returns lower case of given char.
  <BR /><STRONG>NOTE</STRONG>: only Latin characters from ASCII table are converted.
  <BR />Example:
  <BR />A =&gt; a
  <BR />b =&gt; b
  <BR />3 =&gt; 3
}
function loCase(value: char): char;
{DP:METHOD
  Returns upper case of given character.
  <BR /><STRONG>NOTE</STRONG>: only Latin characters from ASCII table are converted.
  <BR />Example:
  <BR />A =&gt; A
  <BR />b =&gt; B
  <BR />3 =&gt; 3
}
function upCase(value: char): char;
{DP:METHOD
  Converts all character in given string into upper case.
  <BR /><STRONG>NOTE</STRONG>: only Latin characters from ASCII table are converted.
  <BR />Example:
  <BR />Alek =&gt; ALEK
  <BR />bool =&gt; BOOL
  <BR />345 =&gt; 345
}

{$IFDEF __BEFORE_D7__ }

const
  //
  { Compare String Return Values }
  {$EXTERNALSYM CSTR_LESS_THAN}
  CSTR_LESS_THAN           = 1;             { string 1 less than string 2 }
  {$EXTERNALSYM CSTR_EQUAL}
  CSTR_EQUAL               = 2;             { string 1 equal to string 2 }
  {$EXTERNALSYM CSTR_GREATER_THAN}
  CSTR_GREATER_THAN        = 3;             { string 1 greater than string 2 }

{$ENDIF }


{$IFDEF __SYSUTILS_H_ }
{$ELSE}

function upperCase(const value: string): string;
{DP:METHOD
  Converts all character in given string into lower case.
  <BR /><STRONG>NOTE</STRONG>: only Latin characters from ASCII table are converted.
  <BR />Example:
  <BR />Alek =&gt; alek
  <BR />bool =&gt; bool
  <BR />345 =&gt; 345
}
function lowerCase(const value: string): string;
{DP:METHOD
  Compares two strings with regard (ignoreCase = false) or not (ignoreCase = true) to the case of characters in the string. Returns:
  <UL>
    <LI>0 - strings are identical</LI>
    <LI>-1 - str1 is shorter or lower then str2</LI>
    <LI>+1 - str2 is shorter or lower then str1</LI>
  </UL>
  <BR /><STRONG>NOTE</STRONG>: only Latin characters from ASCII table are converted when ignoreCase = true.
}
function compareStr(const str1, str2: string; ignoreCase: bool = false): int;

{$ENDIF }	// not __SYSUTILS_H_

function lowerCaseW(const value: wideString): wideString;

function sameString(const str1, str2: string; doTrim: bool = true): bool;
function sameStringW(const str1, str2: wideString; doTrim: bool = true; locale: LCID = LOCALE_SYSTEM_DEFAULT): bool;

{DP:METHOD
  Adjusts a string length to the len value, by adding additional character at the beginning (left = true) or at the end (left = false) of the string.
}
function adjust(const value: string; len: int; fill: char = ' '; left: bool = true; truncate: bool = false): string;
function adjustW(const value: wideString; len: int; const fill: wideChar = ' '; left: bool = true; truncate: bool = false): wideString;
{DP:METHOD
  Returns a string containing specified number of specified character.
}
function padChar(pad: char; len: unsigned): string; overload;
function padChar(const pad: wideChar; len: unsigned): wideString; overload;
{DP:METHOD
  Copies source string into dest pChat. dest must be large enough to store the source.
  You can limit the number of characters to copy with maxLen parameter.
  Returns dest.
}
function strCopy(dest: pChar; const source: pChar; maxLen: unsigned): pChar; overload
{DP:METHOD
  Copies source string into dest pChat. dest must be large enough to store the source.
  Returns dest.
}
function strCopy(dest: pChar; const source: string; maxLen: unsigned = 0): pChar; overload;
{DP:METHOD
  Allocates new pChar value and copies the source string into it.
}
function strNew(const source: string): pChar; overload;
{DP:METHOD
  Returns number of chars being copied.
}
function str2array(const value: string; var A: array of char): int; overload;
function array2str(const A: array of char; out value: string; startPos: int = low(int); length: int = -1): int;
{DP:METHOD
  Returns number of wide chars being copied.
}
function wStr2Array(const value: wideString; var A: array of wideChar): int; overload;
{$IFDEF __BEFORE_D6__}
function wStr2Array(const value: string; A: pWideChar; maxLen: int = -1): int; overload;
{$ENDIF}

{DP:METHOD
  If maxArrayLength is specified, assumed that it includes the last NULL character.
  Returns number of wide chars being copied.
}
function array2wStr(const A: array of wideChar; out value: wideString; maxArrayLength: int = -1): int;

{$IFDEF __SYSUTILS_H_ }
{$ELSE}

{DP:METHOD
  Allocates memory for a new string.

  <BR />NOTE: SysUtils.strAlloc() allocates additional 4 bytes per string.
  You should use SysUtils.strDispose() to deallocate those strings. Do not mix
  unaUtils.strNew() and SysUtils.strDispose().
}
function strAlloc(size: cardinal): pChar;
{DP:METHOD
  Deallocates memory taken by a string.

  <BR />Do not mix SysUtils.strNew() and unaUtils.strDispose().
}
function strDispose(str: pChar): bool;
{DP:METHOD
  Returns length of a string.
}
function strLen(str: pChar): unsigned;
{DP:METHOD
  Allocates memory for a new string. Use unaUtils.strDispose() to release the memory.
}
function strNew(str: pChar): pChar; overload;
{DP:METHOD
  Scans the src string for specified character.
  Returns pointer on position in the string where this character was found, or nil otherwise.
}
function strScan(const str: pChar; chr: char): pChar; assembler;
{
}
function strPos(const strSource, strToFind: pChar): pChar;
{DP:METHOD
  Returns position (starting from 1) in the s where one of the characters given in delimiters was found.
  Search is performed from the end of string. Returns length of s if no characters were found.
}
function lastDelimiter(const delimiters, s: string): int;

{$ENDIF }	// not __SYSUTILS_H_

{DP:METHOD
  Returns the strength of a password string. -1 = unacceptable; 0 = weakest; 100 = strongest.
  noSameString specifies a string to which password should not be same (for example - user name).
}
function passwordStrength(const password: wideString; const noSameString: wideString = ''; reallyStrong: bool = false): int;





{DP:METHOD
  Makes value safe to pass as "plain" string, by escaping special characters with "/" symbol. Examples:
  <UL>
	<LI>"Lake"#9"Una" -- "Lake/tUna"</LI>
	<LI>"Line1"#13#10"Line2" -- "Line1/r/nLine2"</LI>
	<LI>"C:\TEMP/" -- "C:\TEMP//"</LI>
	<LI>"PAGE"#12"FEED" -- "PAGE/012FEED"</LI>
  </UL>
}
function strEscape(const value: string; const specialCare: string = ''): string;

{DP:METHOD
  Converts "escaped" value back to "plain" string. Examples:
  <UL>
	<LI>"Lake/tUna" -- "Lake"#9"Una"</LI>
	<LI>"Line1/r/nLine2" -- "Line1"#13#10"Line2"</LI>
	<LI>"C:\TEMP//" -- "C:\TEMP/"</LI>
	<LI>"PAGE/012FEED" -- "PAGE"#12"FEED"</LI>
  </UL>
}
function strUnescape(const value: string): string;

{DP:METHOD
  //
}
function html_escape(const value: string; strict: bool = true): string;

{DP:METHOD
  //
}
function url_encode(const value: string): string;
function url_decode(const value: string): string;


{DP:METHOD
  //
}
function html_markURLs(const value: string; const style: string = ''): string;
{DP:METHOD
  //
}
function html_markSpaces(const value: wideString; leadingOnly: bool = false): wideString;

{DP:METHOD
  Substitues variable fields in the template with given values. Example:
  <BR />templ = "Hello from %name% %last name%, take the 10%% of text."
  <BR />vars = "name"#9"Lake"#10"last name"#9"Una"
  <BR />result = "Hello from Lake Una, take the 10% of text."
  <BR />&nbsp;
  <P />Use the strEscape() function to ensure there are no #9 or #10 characters in the values.
}
function formatTemplate(const templ: string; const vars: string; unescapeVars: bool = true): string;
{DP:METHOD
}
function nextTokenW(const text: wideString; var startPos: unsigned): wideString;
{DP:METHOD
  Returns number of tokens replaced.
}
function replaceTokens(var text: string; const tokens: string): int; overload;
function replaceTokens(var text: string; const tokens: string; var careSelStart: int): int; overload;
function replaceTokensW(var text: wideString; const tokens: wideString; var careSelStart: int): int;


{DP:METHOD
  Wrapper for MessageBox() function
}
function guiMessageBox(owner: hWnd; const message, title: wideString; flags: int = MB_OK): int; overload;
function guiMessageBox(const message, title: wideString; flags: int = MB_OK; owner: hWnd = 0): int; overload;

{$EXTERNALSYM ShellAboutA}
function ShellAboutA(Wnd: HWND; szApp, szOtherStuff: PAnsiChar; Icon: HICON): Integer; stdcall;