Chuyển đổi và định dạng chuỗi

Chức năng chuyển đổi số và đầu ra chuỗi được định dạng.

int PyOS_snprintf(char *str, size_t size, const char *format, ...)

Một phần của ABI ổn định.

Xuất không quá size byte thành str theo chuỗi định dạng format và các đối số bổ sung. Xem trang người dùng Unix snprintf(3).

int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)

Một phần của ABI ổn định.

Xuất không quá size byte thành str theo chuỗi định dạng format và danh sách đối số biến va. Trang người dùng Unix vsnprintf(3).

PyOS_snprintf() và PyOS_vsnprintf() bao bọc các hàm thư viện Standard C snprintf() và vsnprintf(). Mục đích của chúng là đảm bảo hành vi nhất quán trong các trường hợp góc, điều mà các chức năng Tiêu chuẩn C không làm được.

Trình bao bọc đảm bảo rằng str[size-1] luôn là '\0' khi trả lại. Họ không bao giờ ghi nhiều hơn size byte (bao gồm cả '\0' ở cuối) vào str. Cả hai chức năng đều yêu cầu str != NULL, size > 0, format != NULL và size < INT_MAX. Lưu ý rằng điều này có nghĩa là không có giá trị tương đương với C99 n = snprintf(NULL, 0, ...) để xác định kích thước bộ đệm cần thiết.

Giá trị trả về (rv) cho các hàm này nên được hiểu như sau:

• Khi 0 <= rv < size, quá trình chuyển đổi đầu ra thành công và các ký tự rv được ghi vào str (không bao gồm byte '\0' ở cuối tại str[rv]).

• Khi rv >= size, quá trình chuyển đổi đầu ra bị cắt bớt và cần có bộ đệm với byte rv + 1 để thành công. str[size-1] là '\0' trong trường hợp này.

• Khi rv < 0, quá trình chuyển đổi đầu ra không thành công và str[size-1] cũng là '\0' trong trường hợp này, nhưng phần còn lại của str không được xác định. Nguyên nhân chính xác của lỗi phụ thuộc vào nền tảng cơ bản.

Các hàm sau cung cấp chuyển đổi chuỗi thành số độc lập với miền địa phương.

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

Một phần của ABI ổn định.

Chuyển đổi phần đầu tiên của chuỗi trong str thành giá trị unsigned long theo base đã cho, giá trị này phải nằm trong khoảng từ 2 đến 36 hoặc là giá trị đặc biệt 0.

Khoảng trắng hàng đầu và trường hợp ký tự bị bỏ qua. Nếu base bằng 0, nó sẽ tìm 0b, 0o hoặc 0x dẫn đầu để biết cơ sở nào. Nếu những thứ này vắng mặt, nó sẽ mặc định là 10. Cơ số phải là 0 hoặc từ 2 đến 36 (đã bao gồm). Nếu ptr không phải là NULL thì nó sẽ chứa một con trỏ ở cuối quá trình quét.

Nếu giá trị được chuyển đổi nằm ngoài phạm vi của loại trả về tương ứng, sẽ xảy ra lỗi phạm vi (errno được đặt thành ERANGE) và ULONG_MAX được trả về. Nếu không thể thực hiện chuyển đổi, 0 sẽ được trả về.

Xem thêm trang Unix strtoul(3).

Added in version 3.2.

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

Một phần của ABI ổn định.

Chuyển đổi phần đầu tiên của chuỗi trong str thành giá trị long theo base đã cho, giá trị này phải nằm trong khoảng từ 2 đến 36 hoặc là giá trị đặc biệt 0.

Tương tự như PyOS_strtoul(), nhưng thay vào đó trả về giá trị long và LONG_MAX khi tràn.

Xem thêm trang Unix strtol(3).

Added in version 3.2.

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

Một phần của ABI ổn định.

Chuyển đổi chuỗi s thành double, đưa ra ngoại lệ Python khi thất bại. Tập hợp các chuỗi được chấp nhận tương ứng với tập hợp các chuỗi được hàm tạo float() của Python chấp nhận, ngoại trừ s không được có khoảng trắng ở đầu hoặc cuối. Việc chuyển đổi độc lập với ngôn ngữ hiện tại.

Nếu endptr là NULL thì chuyển đổi toàn bộ chuỗi. Tăng ValueError và trả về -1.0 nếu chuỗi không phải là biểu diễn hợp lệ của số dấu phẩy động.

Nếu endptr không phải là NULL, hãy chuyển đổi càng nhiều chuỗi càng tốt và đặt *endptr để trỏ đến ký tự đầu tiên chưa được chuyển đổi. Nếu không có phân đoạn ban đầu nào của chuỗi là biểu diễn hợp lệ của số dấu phẩy động, hãy đặt *endptr để trỏ đến phần đầu của chuỗi, tăng ValueError và trả về -1.0.

Nếu s đại diện cho một giá trị quá lớn để lưu trữ trong float (ví dụ: "1e500" là một chuỗi như vậy trên nhiều nền tảng) thì nếu overflow_exception là NULL hãy trả về Py_INFINITY (với một dấu thích hợp) và không đặt bất kỳ ngoại lệ nào. Nếu không, overflow_exception phải trỏ đến một đối tượng ngoại lệ Python; nêu ngoại lệ đó và trả về -1.0. Trong cả hai trường hợp, đặt *endptr để trỏ đến ký tự đầu tiên sau giá trị được chuyển đổi.

Nếu bất kỳ lỗi nào khác xảy ra trong quá trình chuyển đổi (ví dụ: lỗi hết bộ nhớ), hãy đặt ngoại lệ Python thích hợp và trả về -1.0.

Added in version 3.1.

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

Một phần của ABI ổn định.

Chuyển đổi double val thành một chuỗi bằng cách sử dụng format_code, precision và flags được cung cấp.

format_code phải là một trong các 'e', 'E', 'f', 'F', 'g', 'G' hoặc 'r'. Đối với 'r', precision được cung cấp phải bằng 0 và bị bỏ qua. Mã định dạng 'r' chỉ định định dạng repr() tiêu chuẩn.

flags có thể bằng 0 hoặc nhiều giá trị sau hoặc kết hợp với nhau:

Py_DTSF_SIGN

Luôn đặt trước chuỗi trả về một ký tự dấu, ngay cả khi val không âm.

Py_DTSF_ADD_DOT_0

Đảm bảo rằng chuỗi trả về sẽ không giống số nguyên.

Py_DTSF_ALT

Áp dụng quy tắc định dạng "thay thế". Xem tài liệu về công cụ xác định PyOS_snprintf() '#' để biết chi tiết.

Py_DTSF_NO_NEG_0

Số 0 âm được chuyển thành số 0 dương.

Added in version 3.11.

Nếu ptype không phải là NULL thì giá trị mà nó trỏ tới sẽ được đặt thành một trong các hằng số sau tùy thuộc vào loại val:

*ptype	loại val
Py_DTST_FINITE	số hữu hạn
Py_DTST_INFINITE	số vô hạn
Py_DTST_NAN	không phải là một con số

Giá trị trả về là một con trỏ tới buffer với chuỗi được chuyển đổi hoặc NULL nếu chuyển đổi không thành công. Người gọi có trách nhiệm giải phóng chuỗi trả về bằng cách gọi 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)

Một phần của ABI ổn định.

So sánh chuỗi không phân biệt chữ hoa chữ thường. Các hàm này hoạt động gần như giống hệt với strcmp() và strncmp() (tương ứng), ngoại trừ việc chúng bỏ qua trường hợp ký tự ASCII.

Trả về 0 nếu các chuỗi bằng nhau, trả về giá trị âm nếu str1 sắp xếp theo từ điển trước str2 hoặc giá trị dương nếu sắp xếp sau.

Trong các đối số str1 hoặc str2, byte NUL đánh dấu sự kết thúc của chuỗi. Đối với PyOS_mystrnicmp(), đối số size cung cấp kích thước tối đa của chuỗi, như thể NUL có mặt tại chỉ mục do size đưa ra.

Các chức năng này không sử dụng ngôn ngữ.

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

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

So sánh chuỗi không phân biệt chữ hoa chữ thường.

Trên Windows, đây lần lượt là các bí danh của stricmp() và strnicmp().

Trên các nền tảng khác, chúng lần lượt là bí danh của PyOS_mystricmp() và PyOS_mystrnicmp().

Phân loại và chuyển đổi ký tự

Các macro sau cung cấp khả năng phân loại và chuyển đổi ký tự độc lập với miền địa phương (không giống như thư viện chuẩn C ctype.h). Đối số phải là char có dấu hoặc không dấu.

Py_ISALNUM(c)

Trả về true nếu ký tự c là ký tự chữ và số.

Py_ISALPHA(c)

Trả về true nếu ký tự c là ký tự chữ cái (a-z và A-Z).

Py_ISDIGIT(c)

Trả về true nếu ký tự c là chữ số thập phân (0-9).

Py_ISLOWER(c)

Trả về true nếu ký tự c là chữ cái ASCII viết thường (a-z).

Py_ISUPPER(c)

Trả về true nếu ký tự c là chữ cái ASCII viết hoa (A-Z).

Py_ISSPACE(c)

Trả về true nếu ký tự c là ký tự khoảng trắng (dấu cách, tab, xuống dòng, dòng mới, tab dọc hoặc nguồn cấp dữ liệu biểu mẫu).

Py_ISXDIGIT(c)

Trả về true nếu ký tự c là chữ số thập lục phân (0-9, a-f và A-F).

Py_TOLOWER(c)

Trả về chữ thường tương đương với ký tự c.

Py_TOUPPER(c)

Trả về chữ hoa tương đương của ký tự c.