array ( 0 => 'index.php', 1 => 'PHP Manual', ), 'head' => array ( 0 => 'UTF-8', 1 => 'uk', ), 'this' => array ( 0 => 'function.sprintf.php', 1 => 'sprintf', 2 => 'Return a formatted string', ), 'up' => array ( 0 => 'ref.strings.php', 1 => 'String Функції', ), 'prev' => array ( 0 => 'function.soundex.php', 1 => 'soundex', ), 'next' => array ( 0 => 'function.sscanf.php', 1 => 'sscanf', ), 'alternatives' => array ( ), 'source' => array ( 'lang' => 'en', 'path' => 'reference/strings/functions/sprintf.xml', ), 'history' => array ( ), ); $setup["toc"] = $TOC; $setup["toc_deprecated"] = $TOC_DEPRECATED; $setup["parents"] = $PARENTS; manual_setup($setup); contributors($setup); ?>

sprintf

(PHP 4, PHP 5, PHP 7, PHP 8)

sprintf — Return a formatted string

Опис

sprintf(string $format, mixed ...$values): string

Returns a string produced according to the formatting string format.

Параметри

format

Рядок формату складається з нуля або більше директив: звичайних символів (крім %), які відображаються в результаті без змін, та специфікаторів перетворення, для кожного з яких задається свій параметр.

Специфікатор перетворення відповідає прототипу: %[argnum$][flags][width][.precision]specifier.

Номер параметра

Ціле число, слідом за ним — знак долара $. Вказує порядковий номер параметра для перетворення.

Прапорці
Позначення Опис
- Вирівнює по лівому краю в межах заданої ширини. Праве вирівнювання виконується автоматично.
+ Дописує до додатнього числа знак +. Знак мінуса до від'ємного числа дописується автоматично.
(пропуск) Доповнює результат пропусками. Також виконується автоматично.
0 Доповнює число нулями ліворуч. Разом зі специфікатором s доповнює число нулями також праворуч.
' (символ) Доповнює рядок символом (символ).

Ширина

Може бути цілим числом, що вказує найменшу кількість символів в значенні після перетворення, або знак *. Якщо використано знак *, то ширина вказується як додаткове ціле число, що передує значенню, відформатованому специфікатором.

Точність

Крапка ., за якою (необов'язково) слідує ціле число чи знак *, значення якого залежить від специфікатора:

  • Для специфікаторів e, E, f і F — це кількість знаків, що будуть надруковані після десяткового розділювача (початково: 6).
  • Для специфікаторів g, G, h і H — найбільша допустима кількість значущих цифр, що будуть надруковані.
  • Для специфікатора s — діє як точка відсікання, встановлюючи максимальну кількість символів у рядку.

Зауваження: Якщо крапку вказано без зазначення точності, тоді точністю вважатиметься 0. Якщо використано знак *, то точність вказується як додаткове ціле число, що передує значенню, відформатованому специфікатором.

Специфікатори
Назва Опис
% Буквальний знак відсотка. Ніяких параметрів не потрібно.
b Параметр розглядається як ціле число і відображається як двійкове число.
c Параметр розглядається як ціле число і відображається як символ з таким кодом ASCII.
d Параметр розглядається як ціле число і відображається як знакове десяткове число.
e Параметр розглядається як експоненційний запис (напр. 1.2e+2).
E Схожий до специфікатора e, але використовує знак експоненти з великої букви (напр. 1.2E+2).
f Параметр розглядається і відображається як десятковий дріб (з урахуванням локалі).
F Параметр розглядається і відображається як десятковий дріб (БЕЗ урахування локалі).
g

Загальний формат.

Нехай P дорівнює точності, якщо вона не дорівнює нулю, 6, якщо точність не вказано, або 1, якщо точність дорівнює нулю. Тоді, якщо перетворення в стилі "E" матиме показник степеня X:

Якщо P > X ≥ −4, перетворення буде в стилі "f" та з точністю P − (X + 1). Інакше, перетворення буде в стилі "e" та з точністю P − 1.

G Схожий до специфікатора g, але використовує E та f.
h Схожий до специфікатора g, але використовує F. Доступний, починаючи з PHP 8.0.0.
H Схожий до специфікатора g, але використовує E та F. Доступний, починаючи з PHP 8.0.0.
o Параметр розглядається як ціле число і відображається як вісімкове число.
s Параметр розглядається і відображається як рядок.
u Параметр розглядається як ціле число і відображається як беззнакове десяткове число.
x Параметр розглядається як ціле число і відображається як шіснадцяткове число (з малими буквами).
X Параметр розглядається як ціле число і відображається як шіснадцяткове число (з великими буквами).

Увага

Специфікатор "c" ігнорує заповнення та ширину.

Увага

Спроба використати разом рядковий специфікатор та специфікатор ширини з символами, що займають більше одного байта, може призвести до неочікуваного результату.

Змінні будуть приведені до відповідного типу для специфікатора:
Обробка типів
Тип Специфікатор
string s
int d, u, c, o, x, X, b
float e, E, f, F, g, G, h, H

values

Значення, що повертаються

Returns a string produced according to the formatting string format.

Помилки/виключення

Починаючи з PHP 8.0.0, якщо не задано жодного параметра, то викидається ValueError. Раніше виводилось повідомлення E_WARNING.

Починаючи з PHP 8.0.0, якщо значення [width] менше за нуль або більше за PHP_INT_MAX, то викидається ValueError. Раніше виводилось повідомлення E_WARNING.

Починаючи з PHP 8.0.0, якщо значення [precision] менше за нуль або більше за PHP_INT_MAX, то викидається ValueError. Раніше виводилось повідомлення E_WARNING.

Починаючи з PHP 8.0.0, якщо якщо не задано обов'язкові параметри, то викидається ArgumentCountError. Раніше функція повертала false, а також виводилося повідомлення E_WARNING.

Журнал змін

Версія Опис
8.0.0 Ця функція більше не повертає false у разі помилки.
8.0.0 Викидає ValueError, якщо не задано жодного параметра. Раніше ця функція виводила E_WARNING.
8.0.0 Викидає ValueError, якщо значення [width] менше за нуль або більше за PHP_INT_MAX. Раніше ця функція виводила E_WARNING.
8.0.0 Викидає ValueError, якщо значення [precision] менше за нуль або більше за PHP_INT_MAX. Раніше ця функція виводила E_WARNING.
8.0.0 Викидає ArgumentCountError, якщо не задано обов'язкові параметри. Раніше ця функція виводила E_WARNING.

Приклади

Приклад #1 Argument swapping

The format string supports argument numbering/swapping.

<?php
$num = 5;
$location = 'tree';

$format = 'There are %d monkeys in the %s';
echo sprintf($format, $num, $location);
?>

Поданий вище приклад виведе:

There are 5 monkeys in the tree

However imagine we are creating a format string in a separate file, commonly because we would like to internationalize it and we rewrite it as:

Приклад #2 Wrong Argument Order

The format string supports argument numbering/swapping.

<?php
$num = 5;
$location = 'tree';

$format = 'The %s contains %d monkeys';
echo sprintf($format, $num, $location);
?>

We now have a problem. The order of the placeholders in the format string does not match the order of the arguments in the code. We would like to leave the code as is and simply indicate in the format string which arguments the placeholders refer to. We would write the format string like this instead:

Приклад #3 Use Order Placeholder

<?php
$num = 5;
$location = 'tree';

$format = 'The %2$s contains %1$d monkeys';
echo sprintf($format, $num, $location);
?>

An added benefit is that placeholders can be repeated without adding more arguments in the code.

Приклад #4 Repeated Placeholder

<?php
$num = 5;
$location = 'tree';

$format = 'The %2$s contains %1$d monkeys.
That\'s a nice %2$s full of %1$d monkeys.';
echo sprintf($format, $num, $location);
?>

When using argument swapping, the n$ position specifier must come immediately after the percent sign (%), before any other specifiers, as shown below.

Приклад #5 Specifying padding character

<?php
echo sprintf("%'.9d\n", 123);
echo sprintf("%'.09d\n", 123);
?>

Поданий вище приклад виведе:

......123
000000123

Приклад #6 Position specifier with other specifiers

<?php
$num = 5;
$location = 'tree';

$format = 'The %2$s contains %1$04d monkeys';
echo sprintf($format, $num, $location);
?>

Поданий вище приклад виведе:

The tree contains 0005 monkeys

Приклад #7 sprintf(): zero-padded integers

<?php
$year = 2005;
$month = 5;
$day = 6;

$isodate = sprintf("%04d-%02d-%02d", $year, $month, $day);
echo $isodate, PHP_EOL;
?>

Приклад #8 sprintf(): formatting currency

<?php
$money1 = 68.75;
$money2 = 54.35;
$money = $money1 + $money2;
echo $money, PHP_EOL;

$formatted = sprintf("%01.2f", $money);
echo $formatted, PHP_EOL;
?>

Поданий вище приклад виведе:

123.1
123.10

Приклад #9 sprintf(): scientific notation

<?php
$number = 362525200;

echo sprintf("%.3e", $number), PHP_EOL;
?>

Поданий вище приклад виведе:

3.625e+8

Прогляньте також