# 문자열 변환과 포매팅

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

int PyOS_snprintf(char *str, size_t size, const char *format, ...)
  Part of the Stable ABI.

  포맷 문자열 format 과 추가 인자에 따라 size 바이트를 넘지 않도록 str로 출력합니다. 유닉스 매뉴얼 페이지 snprintf(3)를 보십시오.

int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)
  Part of the Stable ABI.

  포맷 문자열 format 과 가변 인자 목록 va에 따라 size 바이트를 넘지 않도록 str로 출력합니다. 유닉스 매뉴얼 페이지 vsnprintf(3)를 보십시오.

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

The wrappers ensure that `str[size-1]` is always `'\0'` upon return. They never write more than size bytes (including the trailing `'\0'`) into str. Both functions require that `str != NULL`, `size > 0`, `format != NULL` and `size < INT_MAX`. Note that this means there is no equivalent to the C99 `n = snprintf(NULL, 0, ...)` which would determine the necessary buffer size.

이 함수들의 반환 값(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)
  Part of the Stable ABI.

  Convert the initial part of the string in `str` to an unsigned long value according to the given `base`, which must be between `2` and `36` inclusive, or be the special value `0`.

  Leading white space and case of characters are ignored. If `base` is zero it looks for a leading `0b`, `0o` or `0x` to tell which base. If these are absent it defaults to `10`. Base must be 0 or between 2 and 36 (inclusive). If `ptr` is non-`NULL` it will contain a pointer to the end of the scan.

  If the converted value falls out of range of corresponding return type, range error occurs (`errno` is set to `ERANGE`) and `ULONG_MAX` is returned. If no conversion can be performed, `0` is returned.

  See also the Unix man page strtoul(3).

  버전 3.2에 추가.

long PyOS_strtol(const char *str, char **ptr, int base)
  Part of the Stable ABI.

  Convert the initial part of the string in `str` to an long value according to the given `base`, which must be between `2` and `36` inclusive, or be the special value `0`.

  Same as `PyOS_strtoul()`, but return a long value instead and `LONG_MAX` on overflows.

  See also the Unix man page strtol(3).

  버전 3.2에 추가.

double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)
  Part of the Stable ABI.

  Convert a string `s` to a double, raising a Python exception on failure. The set of accepted strings corresponds to the set of strings accepted by Python’s `float()` constructor, except that `s` must not have leading or trailing whitespace. The conversion is independent of the current locale.

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

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

  `s`가 float에 저장하기에 너무 큰 값을 나타낼 때 (예를 들어, 여러 플랫폼에서 `"1e500"`가 그런 문자열입니다), `overflow_exception`가 `NULL`이면 (적절한 부호와 함께) `Py_HUGE_VAL`을 반환하고, 어떤 예외도 설정하지 않습니다. 그렇지 않으면, `overflow_exception`은 파이썬 예외 객체를 가리켜야 합니다; 그 예외를 발생시키고 `-1.0`를 반환합니다. 두 경우 모두, 변환된 값 다음의 첫 번째 문자를 가리키도록 `*endptr`을 설정합니다.

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

  버전 3.1에 추가.

char *PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)
  Part of the Stable ABI.

  Convert a double val to a string using supplied format_code, precision, and flags.

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

  flags는 `Py_DTSF_SIGN`, `Py_DTSF_ADD_DOT_0` 또는 `Py_DTSF_ALT` 값을 0개 이상 함께 or 할 수 있습니다:

  - `Py_DTSF_SIGN`은 val가 음수가 아닐 때도 항상 반환된 문자열 앞에 부호 문자가 오는 것을 뜻합니다.

  - `Py_DTSF_ADD_DOT_0`은 반환된 문자열이 정수처럼 보이지 않도록 하는 것을 뜻합니다.

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

  ptype이 `NULL`이 아니면, 포인터가 가리키는 값은 `Py_DTST_FINITE`, `Py_DTST_INFINITE` 또는 `Py_DTST_NAN` 중 하나로 설정되어, val가 각각 유한 수, 무한 수 또는 NaN임을 나타냅니다.

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

  버전 3.1에 추가.

int PyOS_stricmp(const char *s1, const char *s2)

  Case insensitive comparison of strings. The function works almost identically to `strcmp()` except that it ignores the case.

int PyOS_strnicmp(const char *s1, const char *s2, Py_ssize_t size)

  Case insensitive comparison of strings. The function works almost identically to `strncmp()` except that it ignores the case.