문자열 변환과 포매팅¶

숫자 변환과 포맷된 문자열 출력을 위한 함수.

int PyOS_snprintf(char *str, size_t size, const char *format, ...)¶: …의 일부 안정 ABI.
포맷 문자열 format 과 추가 인자에 따라 size 바이트를 넘지 않도록 str로 출력합니다. 유닉스 매뉴얼 페이지 snprintf(3)를 보십시오.

int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)¶: …의 일부 안정 ABI.
포맷 문자열 format 과 가변 인자 목록 va에 따라 size 바이트를 넘지 않도록 str로 출력합니다. 유닉스 매뉴얼 페이지 vsnprintf(3)를 보십시오.

PyOS_snprintf()와 PyOS_vsnprintf()는 표준 C 라이브러리 함수 snprintf()와 vsnprintf()를 감쌉니다. 그들의 목적은 경계 조건에서 표준 C 함수가 제공하지 않는 수준의 일관된 동작을 보장하는 것입니다.

래퍼는 반환 시 str[size-1]이 항상 '\0'이 되도록 합니다. str에 size 바이트(후행 '\0' 포함)를 초과해서 쓰지 않습니다. 두 함수 모두 str != NULL, size > 0, format != NULL 및 size < INT_MAX를 요구합니다. 이는 필요한 버퍼 크기를 결정하는 C99 n = snprintf(NULL, 0, ...)에 해당하는 것이 없다는 뜻임에 유의하십시오.

이 함수들의 반환 값(rv)은 다음과 같이 해석되어야 합니다:

0 <= rv < size 일 때, 출력 변환에 성공했으며 rv 문자가 str에 기록되었습니다 (str[rv]의 후행 '\0' 바이트 제외).
rv >= size 일 때, 출력 변환이 잘렸고 성공하려면 rv + 1 바이트의 버퍼가 필요합니다. str[size-1]은 이때 '\0'입니다.
rv < 0 인 경우 출력 변환이 실패했으며 이 경우에도 str[size-1] 은 '\0' 이지만, str 의 나머지 부분은 정의되지 않습니다. 오류의 정확한 원인은 기본 플랫폼에 따라 다릅니다.

다음 함수는 로케일 독립적인 문자열에서 숫자로의 변환을 제공합니다.

unsigned long PyOS_strtoul(const char *str, char **ptr, int base)¶

…의 일부 안정 ABI.

str 내 문자열의 앞부분을 주어진 base (2에서 36 사이 또는 특별한 값 0)에 따라 unsigned long 값으로 변환합니다.

앞부분의 공백과 문자의 대소문자는 무시됩니다. base 가 0이면 앞에 붙은 0b, 0o 또는 0x 를 찾아 어떤 진법인지 판단합니다. 이들이 없으면 기본값으로 10 을 사용합니다. 기본은 0이거나 2에서 36 사이(포함)여야 합니다. ptr 이 NULL 이 아니면 스캔된 부분의 끝을 가리키는 포인터를 포함하게 됩니다.

변환된 값이 해당 반환 유형의 범위를 벗어나면 범위 오류가 발생하고(errno 가 ERANGE 로 설정됨), ULONG_MAX 이 반환됩니다. 변환이 불가능한 경우 0 이 반환됩니다.

Unix 매뉴얼 페이지인 strtoul(3) 을 참고하십시오.

Added in version 3.2.

long PyOS_strtol(const char *str, char **ptr, int base)¶

…의 일부 안정 ABI.

str 내 문자열의 앞부분을 주어진 base (2에서 36 사이 또는 특별한 값 0)에 따라 long 값으로 변환합니다.

PyOS_strtoul() 과 동일하지만, 대신 long 값을 반환하며 오버플로 발생 시 LONG_MAX 를 반환합니다.

Unix 매뉴얼 페이지인 strtol(3) 을 참고하십시오.

Added in version 3.2.

double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)¶

…의 일부 안정 ABI.

문자열 s를 double로 변환하고, 실패 시 파이썬 예외를 발생시킵니다. 허용되는 문자열 집합은 s가 선행이나 후행 공백을 가질 수 없다는 점을 제외하고는 파이썬의 float() 생성자가 허용하는 문자열 집합에 대응합니다. 변환은 현재 로케일과 독립적입니다.

endptr이 NULL이면, 전체 문자열을 변환합니다. 문자열이 부동 소수점 숫자의 유효한 표현이 아니면 ValueError를 발생시키고 -1.0을 반환합니다.

endptr이 NULL이 아니면, 가능한 한 많은 문자열을 변환하고 *endptr이 변환되지 않은 첫 번째 문자를 가리키도록 설정합니다. 문자열의 초기 세그먼트가 부동 소수점 숫자의 유효한 표현이 아니면, *endptr이 문자열의 시작을 가리키도록 설정하고, ValueError를 발생시키고 -1.0을 반환합니다.

s 가 float에 저장하기에 너무 큰 값(예: 많은 플랫폼에서 "1e500" 과 같은 문자열)을 나타내고 overflow_exception 이 NULL 인 경우, 어떤 예외도 설정하지 않고 적절한 부호와 함께 INFINITY 를 반환합니다. 그렇지 않은 경우, overflow_exception 은 파이썬 예외 객체를 가리켜야 하며, 해당 예외를 발생시키고 -1.0 을 반환합니다. 두 경우 모두 *endptr 가 변환된 값 바로 뒤의 첫 번째 문자를 가리키도록 설정합니다.

변환 중 다른 에러가 발생하면 (예를 들어 메모리 부족 에러), 적절한 파이썬 예외를 설정하고 -1.0을 반환합니다.

Added in version 3.1.

char *PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)¶

…의 일부 안정 ABI.

제공된 format_code, precision 및 flags를 사용하여 double val을 문자열로 변환합니다.

format_code는 'e', 'E', 'f', 'F', 'g', 'G' 또는 'r' 중 하나여야 합니다. 'r'의 경우, 제공된 precision은 0이어야 하며 무시됩니다. 'r' 포맷 코드는 표준 repr() 형식을 지정합니다.

flags 는 다음과 같은 값들 중 0개 이상의 값을 비트별 OR 연산으로 결합한 것입니다:

Py_DTSF_SIGN¶: val 이 음수가 아니더라도 반환되는 문자열 앞에 항상 부호 문자를 추가합니다.

Py_DTSF_ADD_DOT_0¶: 반환된 문자열이 정수처럼 보이지 않도록 합니다.

Py_DTSF_ALT¶: “대체” 포매팅 규칙을 적용합니다. 자세한 내용은 PyOS_snprintf() '#' 지정자에 관한 설명서를 참조하십시오.

Py_DTSF_NO_NEG_0¶: 음수 0은 양의 0으로 변환됩니다.

Added in version 3.11.

ptype 이 NULL 이 아닌 경우, 가리키는 값은 val 의 유형에 따라 다음 상수 중 하나로 설정됩니다.

ptype	val 의 유형
Py_DTST_FINITE¶	유한한 수
Py_DTST_INFINITE¶	무한한 수
Py_DTST_NAN¶	숫자가 아님

반환 값은 변환된 문자열이 있는 buffer에 대한 포인터이거나, 변환에 실패하면 NULL입니다. 호출자는 PyMem_Free()를 호출하여 반환된 문자열을 해제해야 합니다.

Added in version 3.1.

int PyOS_mystricmp(const char *str1, const char *str2)¶

int PyOS_mystrnicmp(const char *str1, const char *str2, Py_ssize_t size)¶

…의 일부 안정 ABI.

대소문자를 구분하지 않는 문자열 비교입니다. 이 함수들은 대소문자를 구분하지 않는다는 점을 제외하고는 각각 strcmp() 및 strncmp() 와 거의 동일하게 작동합니다.

문자열이 같으면 0 을 반환하고, str1 이 사전 순으로 str2 보다 앞서면 음수를, 뒤에 오면 양수를 반환합니다.

str1 또는 str2 인자에서 NULL 바이트는 문자열의 끝을 나타냅니다. PyOS_mystrnicmp() 의 경우, size 인자는 마치 size 인덱스에 NULL이 있는 것처럼 문자열의 최대 크기를 지정합니다.

이 함수들은 로케일을 사용하지 않습니다.

int PyOS_stricmp(const char *str1, const char *str2)¶

int PyOS_strnicmp(const char *str1, const char *str2, Py_ssize_t size)¶

대소문자를 구분하지 않는 문자열 비교.

Windows에서 이들은 각각 stricmp`와 :c:func:()!strnicmp`의 별칭입니다.

다른 플랫폼에서는 이들은 각각 PyOS_mystricmp() 와 PyOS_mystrnicmp() 의 별칭입니다.

문자 분류 및 변환¶

다음 매크로는 (C 표준 라이브러리인 ctype.h 와 달리) 로케인에 독립적인 문자 분류 및 변환을 제공합니다. 인수는 부호가 있는 또는 없는 char 여야 합니다.

Py_ISALNUM(c)¶: c 가 영숫자 문자인 경우 참을 반환합니다.

Py_ISALPHA(c)¶: c 가 알파벳 문자(a-z 및 A-Z)인 경우 참을 반환합니다.

Py_ISDIGIT(c)¶: c 가 십진수 숫자(0-9)인 경우 참을 반환합니다.

Py_ISLOWER(c)¶: 문자 c 가 소문자 ASCII 문자(a-z)인 경우 True를 반환합니다.

Py_ISUPPER(c)¶: 문자 c 가 대문자 ASCII 문자(A-Z)인 경우 True를 반환합니다.

Py_ISSPACE(c)¶: 문자 c 가 공백 문자(스페이스, 탭, 캐리지 리턴, 줄 바꿈, 세로 탭 또는 폼 피드)인 경우 True를 반환합니다.

Py_ISXDIGIT(c)¶: 문자 c 가 16진수(0-9, a-f, A-F)인 경우 True를 반환합니다.

Py_TOLOWER(c)¶: 문자 c 의 소문자 대응 문자를 반환합니다.

Py_TOUPPER(c)¶: 문자 c 의 대문자 대응 문자를 반환합니다.