Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

GDScript 형식 문자열(format strings)

GDscript는 형식 문자열 이란 기능을 제공하는데, 비슷한 문자열들을 간결하게 텍스트 템플릿으로 재사용할 수 있도록 해줍니다.

형식 문자열은 특정 플레이스홀더 문자 시퀀스(sequence)를 포함한다는 점을 제외하고는 일반 문자열과 같습니다. 그러면 플레이스홀더는 형식 문자열에 전달된 매개 변수로 쉽게 대치될 수 있습니다.

As an example, with %s as a placeholder, the format string "Hello %s, how are you?" can easily be changed to "Hello World, how are you?". Notice the placeholder is in the middle of the string; modifying it without format strings could be cumbersome.

GDScript에서 사용법

구체적인 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."

플레이스홀더는 항상 %로 시작하지만, 다음 문자나 문자열인 형식 지정자(format specifier)는 주어진 값을 문자열로 변환하는 방법을 결정합니다.

위의 예제에서 볼 수 있는 %s는 가장 단순한 플레이스홀더로 대부분의 사용 사례에서 작동합니다. 이 플레이스홀더는 암시적 문자열 변환 또는 str()이 값을 변환하는 것과 동일한 방법으로 값을 변환합니다. 문자열은 변경되지 않고 부울은 "True" 또는 "False"를, 정수 또는 실수는 십진수를, 다른 타입은 데이터를 일반적으로 사람이 읽을 수 있는 문자열로 반환합니다.

GDScript에서 텍스트를 형식화하는 또 다른 방법은 String.format() 메서드입니다. 문자열에 있는 모든 키를 해당하는 값으로 바꿉니다. 이 메서드는 배열 또는 딕셔너리를 키/값 묶음으로 다룰 수 있습니다.

배열은 키, 인덱스, 혼합 스타일로 사용됩니다 (밑의 예시를 참고하세요). 순서는 배열의 인덱스나 혼합 스타일을 사용할 때만 중요합니다.

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"

오직 % 연산자에만 적용할 수 있는 형식 지정자(format specifiers) 도 있습니다.

많은 플레이스 홀더

형식 문자열은 여러가지 플레이스 홀더를 가질 수 있습니다. 예를 들어, 값은 배열의 형식으로, 각각의 플레이스 홀더에 단일 값으로 전달됩니다 (* 으로 이루어진 형식 지정자를 사용하지 않는다면, 동적 패딩 을 참고하세요):

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."

값은 순서대로 삽입됩니다. 모든 플레이스 홀더는 한번에 바꾸어야 하기 때문에, 적절한 수의 값이 있어야 합니다.

형식 지정자(Format specifiers)

플레이스 홀더에 사용되는 s 이외에도 다른 형식 지정자가 있습니다. 이들은 하나 이상의 문자로 구성됩니다. s 처럼 스스로 작동하는 것이 있는 반면, 일부는 다른 문자 앞에 나타나기도 하며, 어떤 것은 오직 특정 값이나 문자에만 작동합니다.

플레이스 홀더 유형

이들 중 하나가 반드시 형식 지정자의 마지막 문자로 항상 나타나야 합니다. s와는 별개로, 이들은 특정 타입의 매개변수가 필요합니다.

s

암시적 문자열 변환과 같은 방법으로 문자열을 간단히 변환합니다.

c

하나의 유니코드 문자. 코드 포인트나 단일 문자의 경우 부호가 없는 8비트 정수 (0-255) 가 필요합니다.

d

십진법 정수. 정수나 (반올림 되는) 실수가 필요합니다.

o

8진법 정수. 정수나 (반올림 되는) 실수가 필요합니다.

x

소문자 로 이루어진 16진법 정수. 정수나 (반올림 되는) 실수가 필요합니다.

X

대문자 로 이루어진 16진법 정수. 정수나 (반올림 되는) 실수가 필요합니다.

f

실수. 정수나 실수가 필요합니다.

v

A vector. Expects any float or int-based vector object ( Vector2, Vector3, Vector4, Vector2i, Vector3i or Vector4i). Will display the vector coordinates in parentheses, formatting each coordinate as if it was an %f, and using the same modifiers.

플레이스 홀더 수정자

이 문자는 위 문자들보다 앞에서 나타납니다. 일부는 특정 조건에서만 작동합니다.

+

숫자 지정자에서, 숫자가 양수라면 + 부호를 표시합니다.

정수(Integer)

Set padding. Padded with spaces or with zeroes if integer starts with 0 in an integer or real number placeholder. The leading 0 is ignored if - is present. When used after ., see ..

.

Before f or v, set precision to 0 decimal places. Can be followed up with numbers to change. Padded with zeroes.

-

왼쪽 대신 오른쪽을 채웁니다.

*

동적 패딩(Dynamic padding) 으로, 패딩이나 . 이후의 정밀도를 설정하기 위한 추가 적분 매개변수가 필요합니다, 동적 패딩 을 참고하세요.

패딩

. (), * (별표), - (빼기 문자) 그리고 한 자리 수 (0-9) 문자들이 패딩에 사용됩니다. 이것을 고정 너비 글꼴에 사용한다면, 세로로 정렬된 여러 값들을 프린트할 수 있습니다.

문자열을 최소 길이로 패딩하기 위해선, 지정자에 정수를 추가하십시오:

print("%10d" % 12345)
# output: "     12345"
# 5 leading spaces for a total length of 10

정수가 ``0``으로 시작한다면, 적분 값은 공백 대신 0으로 패딩됩니다:

print("%010d" % 12345)
# output: "0000012345"

정밀도는 정수 뒤에 ``.``()을 추가해서 실수로 지정할 수 있습니다. ``.``뒤에 정수가 없다면, 정밀도가 0으로, 적분 값에 반올림됩니다. 패딩에 쓰이는 정수는 점 앞에 나와야 합니다.

# Pad to minimum length of 10, round to 3 decimal places
print("%10.3f" % 10000.5555)
# Output: " 10000.556"
# 1 leading space

- 문자는 왼쪽이 아닌 오른쪽으로 채우므로, 오른쪽 텍스트 정렬에 유용합니다:

print("%-10d" % 12345678)
# Output: "12345678  "
# 2 trailing spaces

동적 패딩

* (별표) 문자를 사용해서, 형식 문자열을 수정하지 않고 패딩이나 정밀도를 설정할 수 있습니다. 이것은 형식 지정자에서 정수 대신 사용됩니다. 패딩과 정밀도의 값은 서식을 지정할 때 전달됩니다:

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

* 앞에 0 을 추가해 정수 플레이스 홀더를 0으로 채울 수도 있습니다:

print("%0*d" % [2, 3])
# Output: "03"

이스케이프 시퀀스

상수 % 문자를 형식 문자열에 넣으려면, 플레이스 홀더처럼 읽히지 않도록 이스케이프 해야 합니다. 잘못하면 문자를 두 배로 만들 것입니다:

var health = 56
print("Remaining health: %d%%" % health)
# Output: "Remaining health: 56%"

형식 메서드 예제

String.format 메서드의 호출을 사용하는 방법은 다음과 같습니다.

유형

스타일

예제

결과

딕셔너리

"안녕, {이름} v{버전}!".format({"이름":"Godette", "버전":"3.0"})

안녕, Godette v3.0!

딕셔너리

인덱스

"안녕, {0} v{1}!".format({"0":"Godette", "1":"3.0"})

안녕, Godette v3.0!

딕셔너리

믹스

"안녕, {0} v{버전}!".format({"0":"Godette", "버전":"3.0"})

안녕, Godette v3.0!

배열

"안녕, {이름} v{버전}!".format([["버전":"3.0"], ["이름":"Godette"]])

안녕, Godette v3.0!

배열

인덱스

"안녕, {0} v{1}!".format(["Godette","3.0"])

안녕, Godette v3.0!

배열

믹스

"안녕, {이름} v{0}!".format([3.0, ["이름":"Godette"]])

안녕, Godette v3.0!

배열

인덱스 없음

"안녕, {} v{}!".format(["Godette", 3.0], "{}")

안녕, Godette v3.0!

플레이스 홀더도 ``String.format``을 사용할 때 사용자 정의를 할 수 있습니다, 이 기능의 몇 가지 예를 소개합니다.

유형

예제

결과

중위 (기본)

"안녕, {0} v{1}".format(["Godette", "3.0"], "{_}")

안녕, Godette v3.0

후위

"안녕, 0% v1%".format(["Godette", "3.0"], "_%")

안녕, Godette v3.0

접두사

"안녕, %0 v%1".format(["Godette", "3.0"], "%_")

안녕, Godette v3.0

String.format 메서드와 % 연산자를 결합함으로써 String.format이 다룰 수 없는 숫자 표현을 다룰 수 있게 됩니다.

예제

결과

"안녕, {0} v{버전}".format({0:"Godette", "버전":"%0.2f" % 3.114})

안녕, Godette v3.11