(PHP 4, PHP 5, PHP 7, PHP 8)
sprintf — Return a formatted 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 > 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:
<?php
$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:
<?php
$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.
<?php
$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.
Приклад #2 Specifying padding character
<?php
echo sprintf("%'.9d\n", 123);
echo sprintf("%'.09d\n", 123);
?>
Поданий вище приклад виведе:
......123 000000123
Приклад #3 Position specifier with other specifiers
<?php
$format = 'The %2$s contains %1$04d monkeys';
echo sprintf($format, $num, $location);
?>
Поданий вище приклад виведе:
The tree contains 0005 monkeys
Приклад #4 sprintf(): zero-padded integers
<?php
$isodate = sprintf("%04d-%02d-%02d", $year, $month, $day);
?>
Приклад #5 sprintf(): formatting currency
<?php
$money1 = 68.75;
$money2 = 54.35;
$money = $money1 + $money2;
echo $money;
echo "\n";
$formatted = sprintf("%01.2f", $money);
echo $formatted;
?>
Поданий вище приклад виведе:
123.1 123.10
Приклад #6 sprintf(): scientific notation
<?php
$number = 362525200;
echo sprintf("%.3e", $number);
?>
Поданий вище приклад виведе:
3.625e+8