strings.text

Строковые функции
=================

:::functions
`N=mf.asc(S)`
:	Возвращает код символа `S`.

`S=mf.chr(N)`
:	Возвращает символ, заданный кодом `N`.

`N=mf.atoi(S[,Radix])`
:	Конвертирует строку `S` в число.

	Значение `Radix` определяет основание, которое будет использоваться при преобразовании строки `S`.
	Допустимые значения `Radix` от `2` до `36`.

	Если параметр `Radix` не указан или равен `0`, то функция попытается его определить автоматически.

`S=mf.itoa(N[,Radix])`
:	Конвертирует целое число `N` в строку.

	Значение `Radix` определяет основание, которое должно использоваться при преобразовании числа `N`.
	Допустимые значения `Radix` от `2` до `36`.

	Если параметр `Radix` не указан, то подразумевается основание `10`.

`S=mf.string(V)`
:	Перевод значения выражения `V` в строку.

`S=mf.date([format])`
:	Возвращает текущую дату/время по формату `format`.
	Этот формат подобен тому, что выдаёт утилита `date` (Unix).

	Функция поддерживает следующую спецификацию формата даты (подобен формату функции `strftime`):

	`%%`
	:	символ '`%`'

	`%a`
	:	Краткое имя дня недели (`Sun` или `Вск`)

	`%A`
	:	Полное имя дня недели (`Sunday` или `Воскресенье`)

	`%b`
	:	Краткое имя месяца (`Jan` или `Янв`)

	`%B`
	:	Полное имя месяца (`January` или `Январь`)

	`%c`
	:	Дата и время в формате `WDay Mnt Day HH:MM:SS yyyy`
		(`Mon Jan 10 04:11:54 2000` или `Пнд Янв 10 04:11:54 2000`)

	`%C`
	:	Столетие как десятичное число (`00`-`99`). `1992` => `19`

	`%d`
	:	Две цифры дня месяца (`01`-`31`)

	`%D`
	:	Синоним для `%x`

	`%e`
	:	Синоним для `%d`, но вместо ведущего нуля будет стоять пробел.

	`%h`
	:	Синоним для `%b`

	`%H`
	:	Две цифры часа (`00`-`23`)

	`%I`
	:	Две цифры часа (`01`-`12`)

	`%j`
	:	Три цифры дня в году (`001`-`366`)

	`%k`
	:	Синоним для `%H`, но вместо ведущего нуля будет стоять пробел.

	`%l`
	:	Синоним для `%I`, но вместо ведущего нуля будет стоять пробел.

	`%L`
	:	Триггер, переключающий язык названий месяцев и дней недели - английский/локальный.

		Far Manager запрашивает у системы 2 набора наименований:

		1) английские наименования месяцев и дней недели
		2) наименования, соответствующие настройкам текущего пользователя (`LOCALE_USER_DEFAULT`)

		По умолчанию выставляются английские наименования.

	`%m`
	:	Месяц, как десятичное число (`1`-`12`)

	`%m0`
	:	Подобно `%m`, но с ведущим нулём (`01`-`12`)

	`%mh`
	:	Одна цифра месяца, как шестнадцатеричное число (`1`-`C`)

	`%M`
	:	Две цифры минут (`00`-`59`)

	`%n`
	:	Подобно переводу строки `\n`

		Внимание! В редакторе автоотступ не работает.

	`%p`
	:	`AM` или `PM`

	`%r`
	:	Подобно `%I:%M:%S %p`

	`%R`
	:	Подобно `%H:%M`

	`%S`
	:	Две цифры секунд (`00`-`59`)

	`%t`
	:	Подобно символу табуляции '`\t`'

	`%T`
	:	Синоним `%X`

	`%U`
	:	Две цифры номера недели, где `Воскресенье` (`Sunday`) является
		первым днём недели (`00`-`53`)

	`%v`
	:	Дата в формате `dd-mmm-yyyy` (`mmm` - в верхнем регистре)

	`%V`
	:	Неделя года в соответствии с `ISO 8601`:
		Если неделя, содержащая `1 Января`, имеет >= 4 дней в течение нового года,
		тогда это неделя `1`;
		в противном случае это самая последняя нумерованная неделя прошлого года (`52` или `53`)

	`%w`
	:	День недели где `0` - `Воскресенье` (`Sunday`) (`0`-`6`)

	`%W`
	:	Две цифры номера недели, где `Понедельник` (`Monday`) является
		первым днём недели (`00`-`53`)

	`%x`
	:	Дата в формате подобно `dd<sep>mm<sep>yyyy` (разделитель `<sep>` зависит 
		от локальных настроек;
		порядок дня, месяца и года зависит от локальных настроек)

	`%X`
	:	Время в формате `HH<sep>MM<sep>SS` (разделитель `<sep>` зависит от локальных настроек)

	`%y`
	:	Две цифры года без столетия (`00`-`99`)

	`%Y`
	:	Год со столетием (`19yy`-`20yy`)

	`%z`
	:	Cмещение локального времени относительно `UTC` в формате `ISO 8601`

	`%Z`
	:	Имя часового пояса

	В функции `date` допускается применение следующих escape-последовательностей:

	`\"`
	:	Символ '`"`'

	`\'`
	:	Символ '`'`'

	`\\`
	:	Символ '`\`'

	`\n`
	:	Перевод строки '`\n`'

	`\t`
	:	Символ табуляции '`\t`'

	`\a`
	:	*bell*

	`\b`
	:	`\b`

	`\f`
	:	`\f`

	`\v`
	:	`\v`

	`\N`, `\NN`, `\NNN`
	:	8-ричные символы из `OEM` кодировки

	`\xNN`
	:	16-ричные символы из `OEM` кодировки

	Если аргумент `format` не указан, то Far Manager будет использовать форматную строку
	`"%a %b %d %H:%M:%S %Z %Y"` (см.)

`N=mf.index(S1,S2[,CaseSensitive])`
:	Если подстрока `S2` содержится в строке `S1`, то возвращается её позиция, иначе `-1`.

	Необязательный параметр `CaseSensitive` задаёт режим сравнения:

	* `0` (по умолчанию) - без учёта регистра,
	* `1` - с учётом регистра.

`N=mf.rindex(S1,S2[,CaseSensitive])`
:	Если подстрока `S2` содержится в строке `S1`, то возвращается её позиция, иначе `-1`.

	Поиск ведётся от конца строки `S1`.

	Необязательный параметр `CaseSensitive` задаёт режим сравнения:

	* `0` (по умолчанию) - без учёта регистра,
	* `1` - с учётом регистра.

`S=mf.lcase(S)`
:	Преобразует строку `S` в нижний регистр.

`S=mf.ucase(S)`
:	Преобразует строку `S` в верхний регистр.

`N=mf.len(S)`
:	Возвращает длину строки `S`.

`S=mf.size2str(Size,Flags[,Width])`
:	Функция форматирует число `Size` (например, размера файла) по заданным условиям,
	указанным в `Flags`, шириной `Width`.

	Параметр `Flags` может быть комбинацией следующих значений:

	:::wide
	`0x0010000000000000`
	:	Добавлять суффиксы: `K` - для килобайтов, `M` - для мегабайтов, `G` - для гигабайтов,
		`T` - для терабайтов, `P` - для петабайтов, `E` - для эксабайтов

	`0x0800000000000000`
	:	Вставлять разделитель между тысячами.
		Используется значение `Interface/FormatNumberSeparators` из конфигурации (`far:config`)
		или значения OS (`LOCALE_STHOUSAND & LOCALE_SDECIMAL`),
		если `FormatNumberSeparators` не указан.

	`0x0080000000000000`
	:	Показывать размер в виде десятичной дроби, используя наиболее подходящую
		единицу измерения, например `0,97 К`, `1,44 М`, `53,2 Г`.

	`0x0040000000000000`
	:	Экономичный режим, не показывать пробел перед суффиксом размера файла (т.е. `0.97K`)

	`0x0400000000000000`
	:	Вместо делителя `1024` использовать делитель `1000`.

	`0x0020000000000000`
	:	Использовать минимально допустимый индекс при форматировании.
		Индекс указывается в младшем байте и может быть только `0`, `1`, `2` или `3`
		(`K`,`M`,`G`,`T`).
	:::

	Например, `0x0020000000000001` означает "*размер как минимум в мегабайтах*".

	Если `Width` не указан или равен `0`, то подразумевается - "*сколько получится*".
	Отрицательное значение ширины позволяет выравнивать слева:

	:::wide
	`mf.size2str(123,0, 5)`
	:	`' 123'`

	`mf.size2str(123,0,-5)`
	:	`'123 '`
	:::

`S=mf.strwrap(Text,Width[,Break[,Flags]])`
:	Форматирует (с выравниванием влево) исходный текст `Text` по заданной ширине `Width`,
	используя разделительную строку `Break`.

	Если `Flags` равен `0x1`, то строка всегда сворачивается по заданной ширине, даже если
	есть слово, которое больше заданной ширины (в этом случае то оно будет разрезано на части).

	Если флаг не указан или не равен `0x1` и есть длинное слово, то такое слово не будет
	разрезано и займет ширину больше чем указано в `Width`.

	Примеры:

	:::examples
	`mf.strwrap("Пример строки, которая будет разбита на несколько строк по ширине в 7 символов.",7)`
	:	~~~
		 +-------+
		 |Пример
		 |строки,
		 |которая
		 |будет
		 |разбита
		 |на
		>|несколько
		 |строк
		 |по
		 |ширине
		 |в 7
		>|символов.
		 +-------+
		~~~

	`mf.strwrap("Пример строки, которая будет разбита на несколько строк по ширине в 7 символов.",7,nil,1)`
	:	~~~
		  1234567
		 +-------+
		 |Пример
		 |строки,
		 |которая
		 |будет
		 |разбита
		 |на
		 |несколь
		 |ко
		 |строк
		 |по
		 |ширине
		 |в 7
		 |символо
		 |в.
		 +-------+
		~~~

	`mf.strwrap("Эта строка содержит оооооооооооооччччччччеееень длинное слово",9,nil,0x1)`
	:	~~~
		  123456789
		 +---------+
		 |Эта
		 |строка
		 |содержит
		 |ооооооооо
		 |ооооччччч
		 |чччеееень
		 |длинное
		 |слово
		 +---------+
		~~~
	:::

`S=mf.strpad(V,Size[,Fill[,Op]])`
:	Функция возвращает строку `V`, дополненную до заданной длины `Size` строкой `Fill`
	(по умолчанию пробелами).

	Способ дополнения зависит от параметра `Op`:

	`0`
	:	заполнение справа от `V`

	`1`
	:	заполнение слева от `V`

	`2`
	:	заполнение вокруг `V`

	Если `Size` меньше или равна длине `V` либо опущена, то дополнения не происходит
	(возвращается `V`).

	Если разность `Size` и длины `V` не делится без остатка на длину `Fill`,
	дополняющая строка обрезается справа.

	Примеры:

	:::examples
	`mf.strpad("Foo",10,"*",2)`
	:	`'***Foo****'`

	`mf.strpad("",10,"-*-",2)`
	:	`'-*--*--*--'`

	`mf.strpad(,10,"-*-")`
	:	`'-*--*--*--'`

	`mf.strpad("Foo",10)`
	:	`'Foo       '`

	`mf.strpad("Foo",10,"-")`
	:	`'Foo-------'`

	`mf.strpad("Foo",10,nil,1)`
	:	`'       Foo'`

	`mf.strpad("Foo",10,nil,2)`
	:	`'   Foo    '`

	`mf.strpad("Foo",10,"1234567890",2)`
	:	`'123Foo1234'`
	:::

`S=mf.substr(V,start[,length])`
:	Возвращает подстроку из выражения `V` начиная с позиции `start` длиной `length`.

	Если `start` >= `0`, то вернётся подстрока, начиная с позиции `start` от начала строки.

	Если `start` < `0`, то вернётся подстрока, начиная с позиции `start` от конца строки.

	Если `length` > `0`, то возвращаемая подстрока будет состоять максимум из `length` символов
	исходной строки начиная с позиции `start`.

	Если `length` < `0`, то в возвращаемой подстроке будет отсутствовать `length` символов
	от конца исходной строки, при том, что она будет начинаться с позиции `start`.

	Если `length` = `0` или не указан, то возвращается подстрока от `start` до конца строки.

	Примеры

	:::examples
	`mf.substr("abcdef", 1)`
	:	возвращает "`bcdef`"

	`mf.substr("abcdef", 1, 3)`
	:	возвращает "`bcd`"

	`mf.substr("abcdef", 0, 4)`
	:	возвращает "`abcd`"

	`mf.substr("abcdef", 0, 8)`
	:	возвращает "`abcdef`"

	`mf.substr("abcdef", -1)`
	:	возвращает "`f`"

	`mf.substr("abcdef", -2)`
	:	возвращает "`ef`"

	`mf.substr("abcdef", -3, 1)`
	:	возвращает "`d`"

	`mf.substr("abcdef", 0, -1)`
	:	возвращает "`abcde`"

	`mf.substr("abcdef", 2, -1)`
	:	возвращает "`cde`"

	`mf.substr("abcdef", 4, -4)`
	:	возвращает `""`

	`mf.substr("abcdef", -3, -1)`
	:	возвращает "`de`"
	:::

`Result=mf.replace(Str,Find,Replace[,Cnt[,CaseSensitive]])`
:	В строке `Str` заменить подстроку `Find` на подстроку `Replace` `Cnt` раз.

	Если параметр `Cnt` меньше или равен `0`, либо опущен, то будут заменены все вхождения `Find`.

	Возвращается результат замены.

	Необязательный параметр `CaseSensitive` задаёт режим сравнения:

	* `0` (по умолчанию) - без учёта регистра,
	* `1` - с учётом регистра.

	Замечания:

	* если `Find` - пустая строка, то возвращается `Str` без преобразований;
	* если `Replace` - пустая строка, то возвращается копия `Str`,
	  в которой удалены все подстроки `Find`;

`S=mf.trim(V[,N])`
:	Удаляет все пробельные символы (пробелы, табуляции, переводы строк и возвраты каретки)
	из строки `V` снаружи (`N=0` или не указан), слева (`N=1`) или справа (`N=2`).

`S=mf.xlat(S[,Flags])`
:	Возвращает транслитерируемую строку `S`.

	Функция подобна макрокоманде `Keys("XLat")`, но используется в выражениях.

	Необязательный аргумент `Flags` позволяет уточнять поведение функции:

	`1`
	:	переключить раскладку клавиатуры

	`2`
	:	издать системный звук
:::


### Замечания

Для всех строковых функций: нумерация символов в строке начинается с `0`
(см. `mf.index()`, `mf.rindex()`, `mf.substr()`).