Модуль UtilsUnit

Этот модуль содержит большое количество вспомогательных функций для преобразования типов данных, форматирования и парсинга (разбора на части) строк, и прочее. Особо обратите внимание на функции SqlUpd, SqlIns, SqlUpdIns, позволяющие формировать в исходном коде программы SQL-запросы на добавление/обновление записей (INSERT/UPDATE) в унифицированном виде и помогающие предотвратить большое число ошибок на этапе написания и сопровождения кода.

Модуль разрабатывался для Delphi 5, но работает так же и в Delphi 6, и должен работать в Delphi 7. В более поздних версиях Delphi и его клонов не тестировался.

Подробное описание

Ввиду большого числа функций, для удобного поиска их по именам, здесь приводится алфавитный указатель:

AddValue Ask Beep CheckFileCanRewrite CmpInt CmpStr CmpStrNum ConcatIfNotEmpty DateToSQL Day DirectoryExists Drop EndDrop Extended2Str FloatToSQL GetDesktopRect Hour IfDateToSQL IfEmpty0 IfNot0 IfNotEmpty IfThenElse IntIn IsFloatNum LastChar Max MaxVals min Minute Month MonthStart Msg NullIf0 NullIfEmpty NullIfEmptyStr OnlyLetters Parse ParseChars PathLead PathTrail RemoveCRs RemoveLast RemoveLastComma RemoveLastDot RemoveSpaces Replace RestoreForm Round_Fmt RussianSummaPropis SaveForm ScanNumber Second
Second2Time ShowError SqlIns SqlInsDistinct SqlUpd SqlUpdIns StrDel StrIn StrToDate StrToFloat StrToSQL StrToSQLNullEmpty Triads Warning WinVer Year Years ZeroIfEmpty

Ниже дано описание функций по пяти основным категориям.

[Строки] [Преобразование типов] [Дата/время] [SQL-запросы] [Рабочий стол/Форма]

Функции для работы со строками.

Декларация	Описание
function Replace( const S: String; CFrom, CTo: Char ): String;	Заменяет в строке S все символы CFrom на CTo, возвращает полученную строку. Например, Replace( S, '.', DecimalSeparator ) - заменит точку на символ разделителя десятичной дроби, установленную в системе в соответствии с региональными настройками текущего пользователя (в русской это будет ',').
function ConcatIfNotEmpty( const S1, S2: String ): String;	Если строка S1 не пустая, то возвращается конкатенация S1 + S2, иначе - пустая строка (независимо от значения S2!)
function RemoveLast( WhatRemove: Char; const S: String ): String;	Удаляет последний символ в строке , если он равен WhatRemove. Результирующая строка возвращается.
function RemoveLastDot( const S: String ): String;	Удаляет последний символ в строке, если он равен '.'. Результат возвращается.
function RemoveLastComma( const S: String ): String;	Удаляет последнюю запятую.
function RemoveCRs( const S: String ): String;	Удаляет все управляющие символы (код < #32) в строке и возвращает полученную строку.
function IfNot0( const S: String ): String;	Если строка равна '0', то возвращает пустую строку, иначе - саму строку S.
function RemoveSpaces( const S: String ): String;	Удаляет пробелы в строке S и возвращает результат.
function IfNotEmpty( const S1: String; const S2: String = '' ): String;	Если S1 не пустая строка (содержащая только пробелы и контрольные символы считается в этом случае так же пустой), то возвращается S2 (но если S2 так же пустая, то возвращается S1). В противном случае (когда S1 не пустая), возвращается пустая строка.
function IfEmpty0( const S1: String ): String;	Если S1 - пустая строка, то возвращается '0', иначе - сама строка S1.
function IfThenElse( Cond: Boolean; const S1: String; const S2: String = '' ): String; overload;	Если выполняется условие Cond, то возвращается строка S1, иначе - строка S2 (причём, строка S2 может быть опущена, в этом случае подразумевается пустая строка, и при Cond = FALSE возвращается пустая строка). Обратите внимание, что в отличие от оператора if в языке Delphi Pascal, оба выражения будут вычислены до того, как быть переданы в качестве параметров. Поэтому в случае невозможности получить операнд, даже если заведомо условие Cond не выполняется для этого операнда, не следует использовать эту функцию, во избежание возникновения исключительной ситуации.
function IfThenElse( Cond: Boolean; V1: Integer; V2: Integer = 0 ): Integer; overload;	Аналогично предыдущей функции, но работает с целыми числами вместо строк.
procedure StrDel( var s: String; from, count: Integer );	Аналог встроенной функции Delete.
function PathTrail( const s: String ): String;	При наличии в строке символов '/' (дробь, или прямой слэш), находит последний, и возвращает все, что лежит правее, в качестве результата. Иначе - возвращает саму строку.
function PathLead( const s: String ): String;	То же самое, но возвращает всё, что лежит левее первого прямого слэша ('/'). Если слэшей в строке нет, так же возвращает саму строку.
function LastChar( const s: String ): Char;	Возвращает последний символ строки (или #0, если строка пустая).
function min( x, y: Integer ): Integer;	Переопределение функции min. Понадобилась из-за того, что при использовании стандартной функции min (как и max) от выражения, содержащего обращения к функции Trunc результат - вещественный.
function Parse( var s: String; const d: String ): String;	"Разбирает" строку s, выделяя из неё часть слева до строки-разделителя d (эта строка возвращается в качестве результата), и оставляя в строке s только часть справа от разделителя (сам разделитель пропадает). Если разделитель в строке не найден, то возвращается вся строка s, а сама строка s очищается.
function ParseChars( var s: String; const d: String ): String;	Функция разбора строки, аналогичная предыдущей. Разница в том, что в качестве разделителя используется любой (первый встретившийся) символ из строки d. В случае, когда ни один разделитель не найден, так же возвращается вся строка s, которая сама при этом очищается.

Функции преобразования типов данных

Декларация	Описание
function StrToFloat( const S: String ): Extended;	В отличие от аналогичной функции из SysUtils, понимает в качестве десятичной точки и '.', и ','. Кроме того, не создаёт исключительную ситуацию, если строка на входе не является числом (в этом случае возвращает 0).
function Triads( S: String ): String;	Для последовательности цифр, представляющих уже отформатированное число, делит число на группы по три цифры, вставляя между тройками пробелы (для лучшей читабельности больших чисел). В случае, если S содержит точку или запятую, она считается десятичным разделителем, и деление на тройки происходит только для целой части числа.
function MaxVals( const Vals: array of Integer ): Integer;	Вычисляет максимум среди заданного массива целых чисел.
function Max( const Vals: array of Integer ): Integer;	Аналогично предыдущему. Если мешает использовать обычную функцию Max, можно и убрать.
function IntIn( I: Integer; const Vals: array of Integer ): Boolean;	Возвращает TRUE, если I присутствует в массиве Vals.
function CmpInt( x, y: Integer ): Integer;	Сравнивает два целых числа, возвращает -1 (когда x < y), 0 (если x = y) или +1 (при x > y).
function CmpStr( s1, s2: String ): Integer;	Аналогично предыдущему, сравнивает две строки, эквивалент AnsiCompareStr.
function CmpStrNum( s1, s2: String ): Integer;	Сравнивает две строки так, что встретившаяся в позиции сравнения последовательность цифр рассматривается как число, и сравниваются числа друг с другом. Например, 'C10' > 'C9', хотя, если сравнивать эти строки именно как строки посимвольно, результат другой: 'C10' < 'C9'.
function AddValue( var Dest: Double; Src: Double; var DestEdiz: String; const SrcEdiz: String; var ErrString: String ): Boolean;	Выполняет операцию Dest = Dest + Src для двух вещественных чисел, приводя единицы измерения, например, переводя килограммы в граммы. Приведение производится к единицам измерения DestEdIz. Поддерживаются только весовые единицы kg, g, кг, г.
function OnlyLetters( const s: String ): String;	Исключает из строки s все символы, кроме латинских и русских букв (включая 'Ё' и 'ё'), и возвращает полученную строку в качестве результата.
function StrIn( const s: String; const A: array of String ): Boolean;	Возвращает TRUE, если заданная строка s присутствует в массиве строк A (регистр не учитывается).
function Extended2Str( E: Extended ): String;	Форматирует вещественное в строку, используя формат с фиксированной точкой и максимум 15 десятичных знаков, обрезая последние нули (и удаляя единственную десятичную точку, если только она и остаётся).
function Round_Fmt( E: Extended ): Int64;	Форматирование с округлением до целого. Используется наиболее адекватный встроенный механизм округления, через функцию Format. К сожалению, данный метод не позволяет обеспечить корректность вычислений с промежуточным округлением результата. Для этого следует использовать функции модуля DecimalCalculations.
function RussianSummaPropis( i: Int64 ): String;	Русская сумма прописью. Например, 2153 преобразуется в строку 'две тысячи сто пятьдесят триэю
function IsFloatNum( const s: String ): Boolean;	Возвращает TRUE, если строка по содержанию представляет собой правильное вещественное число с фиксированной точкой.
function ScanNumber( const s: String ): Integer;	Преобразует строку в целое число, при этом пропуская все символы, кроме десятичных цифр.

Функции для работы с датой и временем

Декларация	Описание
function StrToDate( const S: String ): TDateTime;	Восстанавливает дату из строки. Дата должна быть в формате dd.mm.yyyy. Если в результате происходит исключение или формат не соответствует указанному, то пытается вызвать одноименную функцию из SysUtils.
function Year( DT: TDateTime ): Integer;	Извлекает из даты DT год и возвращает.
function Month( DT: TDateTime ): Integer;	Извлекает месяц (от 1 до 12).
function Day( DT: TDateTime ): Integer;	День (от 1 до 31).
function Hour( DT: TDateTime ): Integer;	Час (от 0 до 23).
function Minute( DT: TDateTime ): Integer;	Минута (от 0 до 59).
function Second( DT: TDateTime ): Integer;	Секунда (от 0 до 59).
function Years( D1, D2: TDateTime ): Integer;	Функция полных лет между двумя датами.
function MonthStart( d: TDateTime ): TDateTime;	Первый день месяца.
function Second2Time( sec: DWORD ): String;	Форматирует время, заданное в секундах, в виде строки.

Функции для формирования текста SQL-запросов.

Декларация	Описание
function FloatToSQL( E: Extended ): String;	Преобразует вещественное число в строку, заменяя знак десятичной точки на символ '.' (стандартная функция FloatToStr использует константу DecimalSeparator, в то время как в тексте SQL-запроса может встречаться только '.').
function StrToSQL( const S: String ): String;	Преобразует строку в строковую константу, ограниченную символами апострофа. Если строка содержит апострофы, то внутри строки они удваиваются. Результат преобразования может быть путем конкатенации добавлен в текст SQL-запроса на месте строковой константы, например: `Q.Text := 'SELECT * FROM Customers WHERE Family = ' + StrToSql( Customer_Family );`
function StrToSQLNullEmpty( const S: String ): String;	Аналогично предыдущей функции, но в случае, если строка S пустая, на выходе формируется строка, 'NULL'.
function DateToSQL( D: TDateTime ): String;	Преобразует дату в SQL-формат. В зависимости от значения глобальной переменной date_fmt (по умолчанию 0), используется один из следующих форматов: 0 - YYYYMMDD (без пробелов) - характерно для MS SQL; 1 - MM/DD/YYYY (через слэш); 2 - #YYYY.MM.DD# (через точку, в качестве кавычек символы '#') - используется в MS Access; другой - #MM-DD-YYYY# - так же для MS Access, но в американском стандарте (не работает в русской версии MS Office 97).
function DateTimeToSQL( D: TDateTime ): String;	Преобразует дату и время в SQL-формат. Дата форматируется так же, как и в предыдущей функции, а время добавляется через пробел в формате HH:MM:SS.
function NullIfEmpty( const S: String ): String;	Если S - пустая строка, то возвращается строка 'NULL', иначе - сама строка. Может использоваться для формирования числового параметра, подставляемого в текст SQL-запроса в виде константы, когда предварительно число преобразуется в строку, а в случае, когда требуется записать NULL, строка оставляется пустой.
function NullIfEmptyStr( const S: String ): String;	Если S содержит строку из двух апострофов, то возвращается 'NULL', иначе 0 сама строка.
function NullIf0( const S: String ): String;	Если строка S содержит только символ 0, то возвращается строка 'NULLэ, иначе сама строка S.
function ZeroIfEmpty( const S: String ): String;	Если строка S - пустая, то возвращается строка '0', иначе - сама строка S.
function IfDateToSQL( const D: String ): String;	Если D - не пустая строка, то для нее возвращается DateToSQL от StrToDate(D), иначе так пустая строка и возвращается.
function SqlUpdIns( Upd: Boolean; const Table: String; const FieldsAndValues: array of String; Distinct: Boolean = FALSE ): String;	Функция формирования SQL-запроса на обновление записи или вставки записи в таблицу. Если Upd = TRUE, то формируется оператор UPDATE, иначе - INSERT. Параметр FieldsAndValues - это список строк, каждая пара в котором представляет собой соответственно имя поля и присваиваемое значение. Причем, если в паре передано пустое имя поля, то пара пропускается (за тем, чтобы присутствовала хотя бы одна пара, программист следит сам, а вообще, пропуск имени поля, обычно осуществляемый вызовом IfThenElse - достаточно редко используется. Обычно этот трюк нужен, чтобы не писать несколько вариантов вызова SqlUpdIns, если различие заключается только в том, что в некоторых вариантах некоторые поля различаются). Параметр DISTINCT используется для случая вставки: если он TRUE, то используется конструкция INSERT INTO Table (список полей) SELECT DISTINCT список значений. Использование функции SqlUpdIns (и сопутствующих SqlUp, SqlIns) позволяет "красиво" и читабельно оформлять текст запросов в унифицированном виде, в последующем удобно такой код сопровождать и исправлять.
function SqlUpd( const Table: String; const FieldsAndValues: array of String ): String;	То же, что и SqlUpdIns, но с параметром Upd = TRUE.
function SqlIns( const Table: String; const FieldsAndValues: array of String ): String;	То же, что и SqlUpdIns, но параметр Upd = FALSE. Для добавления оператора DISTINCT в список значений SELECT используйте SqlUpdIns( FALSE, ... ); или SqlInsDistinct.
function SqlInsDistinct( const Table: String; const FieldsAndValues: array of String ): String;	То же, что и SqlUpdIns, но параметр Upd = FALSE, Distinct = TRUE.
function Drop( const TableName: String ): String;	Предполагалось, что будет формировать строку вида #13'DROP ' + TableName в качестве результата. В настоящий момент возвращает пустую строку. Для формирования строки используйте EndDrop.
function EndDrop( const TableName: String ): String;	Формирует строку #13'DROP ' + TableName;

Функции для рабочего стола, работы с формами, файлами и каталогами.

Декларация	Описание
function GetDesktopRect : TRect;	Возвращает прямоугольник рабочего стола на экране, не считая панели задач (кроме случая, когда она автоматически скрываемая) и других системных панелей, приклеенных краям экрана и не скрываемых автоматически.
procedure SaveForm( F: TForm );	Сохраняет состояние формы (размеры, положение на рабочем столе, состояние - максимизировано или нет) в реестре по пути, заданному в глобальной переменной RegistrySaveForm + имя формы. Значение этой переменной по умолчанию 'Software\', то есть для формы Form1 путь будет HKCU \ Software \ Form1. Рекомендуется модифицировать эту переменную, хотя бы внося после Software еще и наименование приложения (а лучше - имя разработчика + наименование приложения).
procedure RestoreForm( F: TForm );	Восстанавливает состояние формы из реестра, ранее сохраненное процедурой SaveForm. Значение переменной RegistrySaveForm должно быть тем же, что и при сохранении.
function Ask( const Question: String ): Boolean;	Выдает на экран сообщение с указанным вопросом и вариантами ответа ДА/НЕТ (Yes/No - в английском варианте), причём вариант НЕТ - предлагается по умолчанию. Возвращается TRUE, если пользователь ответил ДА.
procedure Msg( const Text: String );	Выдает на экран информационное сообщение, с кнопкой ОК.
procedure Warning( const Text: String );	Выдаёт на экран предупреждающее сообщение, ответ пользователя - ОК.
procedure ShowError( const Text: String );	Выдаёт на экран сообщение об ошибке.
function WinVer : TWindowsVersion;	Возвращает версию Windows. Варианты: wv31, wv95, wv98, wvNT, wvY2K, wvXP, wvLongHorn (последний теперь соответствует Vista и Windows7, а так же должен отображаться для всех последующих версий Windows).
procedure Beep;	Выдача звукового сигнала.
function CheckFileCanRewrite( const Filename: String ): Boolean;	Возвращает TRUE, если файл с именем Filename может быть перезаписан, и FALSE, если он в настоящее время открыт на запись (на исключительное использование).
function DirectoryExists( const path: String ): Boolean;	Возвращает TRUE, если указанная директория существует.

(C) by Vladimir Kladov, 2000-2010