Attention: Here be dragons
This is the latest
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
Formatação de Strings em GDScript
O Godot oferece várias maneiras de alterar dinamicamente o conteúdo de strings:
Strings de formatação:
var string = "I have %s cats." % "3"O método
String.format():var string = "I have {0} cats.".format([3])Concatenação de strings:
var string = "I have " + str(3) + " cats."
Esta página explica como usar strings de formatação e explica brevemente o método format() e a concatenação de strings.
Strings de formatação
Strings de formatação são uma maneira de reutilizar modelos de texto para criar, de forma concisa, strings diferentes, porém semelhantes.
Strings de formatação são como strings normais, exceto que contêm certas sequências de caracteres marcadores de posição (placeholders), como %s. Esses marcadores de posição podem então ser substituídos por parâmetros passados para a string de formatação.
Analise este exemplo concreto de GDScript:
# Define a format string with placeholder '%s'
var format_string = "We're waiting for %s."
# Using the '%' operator, the placeholder is replaced with the desired value
var actual_string = format_string % "Godot"
print(actual_string)
# Output: "We're waiting for Godot."
Placeholders sempre começam com um %, mas o(s) próximo(s) caractere(s) o especificador de formato, determina como o valor dado é convertido em uma string.
The %s seen in the example above is the simplest placeholder and works for
most use cases: it converts the value by the same method by which an implicit
String conversion or str() would convert
it. Strings remain unchanged, booleans turn into either "true" or "false",
int and float types become decimals, and other types usually return their data
in a human-readable string.
Existem outros especificadores de formato.
Múltiplos espaços reservados
Strings de formatação podem conter múltiplos espaços reservados. Nesse caso, os valores são tratados na forma de um array, um valor para cada espaço reservado (a não ser que se use um especificador de formato com *, veja dynamic padding – "espaço de preenchimento dinâmico"):
var format_string = "%s was reluctant to learn %s, but now he enjoys it."
var actual_string = format_string % ["Estragon", "GDScript"]
print(actual_string)
# Output: "Estragon was reluctant to learn GDScript, but now he enjoys it."
Note que os valores são inseridos em ordem. Lembre-se que todos os espaços reservados devem ser substituídos de uma vez, para isso o numero de valores deve ser apropriado.
Especificadores de formato
Existem outros especificadores de formato além de s que podem ser usados nos espaços reservados. Eles consistem de um ou mais caracteres. Alguns dos quais funcionam por conta própria como ser s, alguns aparecem antes de outros caracteres, e alguns apenas funcionam com certos tipos de valores ou caracteres.
Tipos de espaços reservados
Apenas um destes deve sempre aparecer como o ultimo caractere em um especificador de formato. Diferentemente do s, estes requerem certos tipos de parâmetros.
|
Conversão simples para uma String pelo mesmo método que uma conversão implícita para String. |
|
Um único caractere Unicode. Aceita um code point Unicode (inteiro) ou uma string de caractere único. Suporta valores além de 255. |
|
Um número inteiro decimal. Espera um número inteiro ou um número real (terá a parte decimal descartada / floor). |
|
Um número inteiro octal. Espera um número inteiro ou um número real (terá a parte decimal descartada / floor). |
|
Um número inteiro hexadecimal com letras em minúsculo. Espera um número inteiro ou um número real (terá a parte decimal descartada / floor). |
|
Um número inteiro hexadecimal com letras em maiúsculo. Espera um número inteiro ou um número real (terá a parte decimal descartada / floor). |
|
Um número real decimal. Espera um número inteiro ou um número real. |
|
Um vetor. Espera qualquer objeto de vetor baseado em float ou int ( |
Modificadores temporários
Estes caracteres aparecem antes dos acima. Alguns deles só funcionam em certas condições.
|
Nos especificadores numéricos, mostra o simbolo + se positivo. |
Inteiro |
Defina o espaçamento. Espaçado com espaços ou com zeros se o número inteiro começa com |
|
Antes de |
|
Preencha para a direita ao invés da esquerda. |
|
Preenchimento dinâmico, espera um parâmetro inteiro adicional para definir o preenchimento ou a precisão após |
Preenchimento
Os caracteres . (ponto), * (asterisco), - (sinal negativo) e dígitos (0-9) são usados para preenchimento. Isso permite mostrar vários valores alinhados verticalmente, como se fosse uma coluna, desde que uma fonte de largura fixa seja usada.
Para preencher um texto com comprimento mínimo, acrescente um inteiro ao especificador:
print("%10d" % 12345)
# output: " 12345"
# 5 leading spaces for a total length of 10
Se o número inteiro começar com 0, os valores inteiros são preenchidos com zeros em vez de espaços em branco:
print("%010d" % 12345)
# output: "0000012345"
A precisão para números reais pode ser especificada adicionando-se um . (ponto) seguido de um número inteiro. Se não houver um número inteiro após o ., utiliza-se precisão 0, arredondando para valores inteiros. O número inteiro a ser usado para preenchimento deve aparecer antes do ponto.
# Pad to minimum length of 10, round to 3 decimal places
print("%10.3f" % 10000.5555)
# Output: " 10000.556"
# 1 leading space
O caractere - fará um preenchimento para a direita, em vez de à esquerda, sendo útil para o alinhamento do texto à direita:
print("%-10d" % 12345678)
# Output: "12345678 "
# 2 trailing spaces
Preenchimento dinâmico
Ao usar o caractere * (asterisco), o preenchimento ou a precisão podem ser definidos sem modificar o texto de formatação. Isso é usado no lugar de um inteiro no especificador de formato. Os valores para preenchimento e precisão serão então passados ao formatar:
var format_string = "%*.*f"
# Pad to length of 7, round to 3 decimal places:
print(format_string % [7, 3, 8.8888])
# Output: " 8.889"
# 2 leading spaces
É possível preencher com zeros nos locais reservados para inteiros ao adicionar 0 antes de *:
print("%0*d" % [2, 3])
# Output: "03"
Sequência de escape
Para inserir um caractere % literal em um texto de formatação, ele deve ser escapado para evitar que seja lido como um espaço reservado. Isso é feito duplicando o caractere:
var health = 56
print("Remaining health: %d%%" % health)
# Output: "Remaining health: 56%"
Método format de String
Existe também outra maneira de formatar texto no GDScript, especificamente o método String.format(). Ele substitui todas as ocorrências de uma chave na string pelo valor correspondente. O método pode lidar com arrays ou dicionários para os pares chave/valor.
Listas podem ser utilizadas como chave, index ou uma mistura de tipos (veja exemplos abaixo). A ordem importante apenas quando o Index ou a mistura de tipos da lista é utilizada.
Um exemplo rápido em GDScript:
# Define a format string
var format_string = "We're waiting for {str}"
# Using the 'format' method, replace the 'str' placeholder
var actual_string = format_string.format({"str": "Godot"})
print(actual_string)
# Output: "We're waiting for Godot"
Exemplos de métodos de formatação
A seguir estão alguns exemplos de como usar as várias chamadas do método String.format().
Tipo |
Estilo |
Exemplo |
Resultado |
Dicionário |
chave |
|
Olá, Godette v3.0! |
Dicionário |
índice |
|
Olá, Godette v3.0! |
Dicionário |
mistura |
|
Olá, Godette v3.0! |
Vetor |
chave |
|
Olá, Godette v3.0! |
Vetor |
índice |
|
Olá, Godette v3.0! |
Vetor |
mistura |
|
Olá, Godette v3.0! |
Vetor |
sem índice |
|
Olá, Godette v3.0! |
Espaços reservados também podem ser personalizados utilizando String.format, aqui estão alguns exemplos dessa funcionalidade.
Tipo |
Exemplo |
Resultado |
Infixo (padrão) |
|
Oi, Godette v3.0 |
Pós-fixo |
|
Oi, Godette v3.0 |
Prefixo |
|
Oi, Godette v3.0 |
Combinar o método String.format e o operador % pode ser útil, já que String.format não possui uma maneira de manipular a representação de números.
Exemplo |
Resultado |
|
Oi, Godette v3.11 |
Concatenação de strings
Você também pode combinar strings concatenando-as, usando o operador +.
# Define a base string
var base_string = "We're waiting for "
# Concatenate the string
var actual_string = base_string + "Godot"
print(actual_string)
# Output: "We're waiting for Godot"
Ao usar a concatenação de strings, os valores que não são strings devem ser convertidos usando a função str(). Não há como especificar o formato de string dos valores convertidos.
var name_string = "Godette"
var version = 3.0
var actual_string = "Hi, " + name_string + " v" + str(version) + "!"
print(actual_string)
# Output: "Hi, Godette v3!"
Devido a essas limitações, as strings de formatação ou o método format() geralmente são uma escolha melhor. Em muitos casos, a concatenação de strings também é menos legível.
Nota
No código C++ do Godot, as strings de formatação do GDScript podem ser acessadas usando a função auxiliar vformat() no cabeçalho Variant.