blob: d7c7ffd37ba7847a44bc4f375a76ef69624f76e6 [file] [log] [blame]
Guido van Rossum4dfe8a12006-04-22 23:28:04 +00001
Georg Brandl0c77a822008-06-10 16:37:50 +00002/* Bytes (String) object interface */
Christian Heimes2c9c7a52008-05-26 13:42:13 +00003
Georg Brandl0c77a822008-06-10 16:37:50 +00004#ifndef Py_BYTESOBJECT_H
5#define Py_BYTESOBJECT_H
Guido van Rossum4dfe8a12006-04-22 23:28:04 +00006#ifdef __cplusplus
7extern "C" {
8#endif
9
10#include <stdarg.h>
11
Christian Heimes2c9c7a52008-05-26 13:42:13 +000012/*
13Type PyBytesObject represents a character string. An extra zero byte is
14reserved at the end to ensure it is zero-terminated, but a size is
15present so strings with null bytes in them can be represented. This
16is an immutable object type.
Guido van Rossum4dfe8a12006-04-22 23:28:04 +000017
Christian Heimes2c9c7a52008-05-26 13:42:13 +000018There are functions to create new string objects, to test
19an object for string-ness, and to get the
20string value. The latter function returns a null pointer
21if the object is not of the proper type.
22There is a variant that takes an explicit size as well as a
23variant that assumes a zero-terminated string. Note that none of the
24functions should be applied to nil objects.
25*/
26
27/* Caching the hash (ob_shash) saves recalculation of a string's hash value.
28 This significantly speeds up dict lookups. */
29
Martin v. Löwis4d0d4712010-12-03 20:14:31 +000030#ifndef Py_LIMITED_API
Guido van Rossum4dfe8a12006-04-22 23:28:04 +000031typedef struct {
32 PyObject_VAR_HEAD
Benjamin Peterson8f67d082010-10-17 20:54:53 +000033 Py_hash_t ob_shash;
Christian Heimes2c9c7a52008-05-26 13:42:13 +000034 char ob_sval[1];
Guido van Rossum4dfe8a12006-04-22 23:28:04 +000035
Christian Heimes2c9c7a52008-05-26 13:42:13 +000036 /* Invariants:
37 * ob_sval contains space for 'ob_size+1' elements.
38 * ob_sval[ob_size] == 0.
39 * ob_shash is the hash of the string or -1 if not computed yet.
40 */
41} PyBytesObject;
Martin v. Löwis4d0d4712010-12-03 20:14:31 +000042#endif
Guido van Rossum4dfe8a12006-04-22 23:28:04 +000043
Christian Heimes2c9c7a52008-05-26 13:42:13 +000044PyAPI_DATA(PyTypeObject) PyBytes_Type;
45PyAPI_DATA(PyTypeObject) PyBytesIter_Type;
Guido van Rossum4dfe8a12006-04-22 23:28:04 +000046
Christian Heimes2c9c7a52008-05-26 13:42:13 +000047#define PyBytes_Check(op) \
48 PyType_FastSubclass(Py_TYPE(op), Py_TPFLAGS_BYTES_SUBCLASS)
49#define PyBytes_CheckExact(op) (Py_TYPE(op) == &PyBytes_Type)
Guido van Rossum4dfe8a12006-04-22 23:28:04 +000050
Christian Heimes2c9c7a52008-05-26 13:42:13 +000051PyAPI_FUNC(PyObject *) PyBytes_FromStringAndSize(const char *, Py_ssize_t);
52PyAPI_FUNC(PyObject *) PyBytes_FromString(const char *);
Benjamin Petersonc15a0732008-08-26 16:46:47 +000053PyAPI_FUNC(PyObject *) PyBytes_FromObject(PyObject *);
Christian Heimes2c9c7a52008-05-26 13:42:13 +000054PyAPI_FUNC(PyObject *) PyBytes_FromFormatV(const char*, va_list)
55 Py_GCC_ATTRIBUTE((format(printf, 1, 0)));
56PyAPI_FUNC(PyObject *) PyBytes_FromFormat(const char*, ...)
57 Py_GCC_ATTRIBUTE((format(printf, 1, 2)));
58PyAPI_FUNC(Py_ssize_t) PyBytes_Size(PyObject *);
59PyAPI_FUNC(char *) PyBytes_AsString(PyObject *);
60PyAPI_FUNC(PyObject *) PyBytes_Repr(PyObject *, int);
61PyAPI_FUNC(void) PyBytes_Concat(PyObject **, PyObject *);
62PyAPI_FUNC(void) PyBytes_ConcatAndDel(PyObject **, PyObject *);
Martin v. Löwis4d0d4712010-12-03 20:14:31 +000063#ifndef Py_LIMITED_API
Christian Heimes2c9c7a52008-05-26 13:42:13 +000064PyAPI_FUNC(int) _PyBytes_Resize(PyObject **, Py_ssize_t);
Martin v. Löwis4d0d4712010-12-03 20:14:31 +000065#endif
Christian Heimes2c9c7a52008-05-26 13:42:13 +000066PyAPI_FUNC(PyObject *) PyBytes_DecodeEscape(const char *, Py_ssize_t,
67 const char *, Py_ssize_t,
68 const char *);
69
70/* Macro, trading safety for speed */
Martin v. Löwis4d0d4712010-12-03 20:14:31 +000071#ifndef Py_LIMITED_API
Christian Heimes2c9c7a52008-05-26 13:42:13 +000072#define PyBytes_AS_STRING(op) (assert(PyBytes_Check(op)), \
73 (((PyBytesObject *)(op))->ob_sval))
74#define PyBytes_GET_SIZE(op) (assert(PyBytes_Check(op)),Py_SIZE(op))
Martin v. Löwis4d0d4712010-12-03 20:14:31 +000075#endif
Christian Heimes2c9c7a52008-05-26 13:42:13 +000076
77/* _PyBytes_Join(sep, x) is like sep.join(x). sep must be PyBytesObject*,
78 x must be an iterable object. */
Martin v. Löwis4d0d4712010-12-03 20:14:31 +000079#ifndef Py_LIMITED_API
Christian Heimes2c9c7a52008-05-26 13:42:13 +000080PyAPI_FUNC(PyObject *) _PyBytes_Join(PyObject *sep, PyObject *x);
Martin v. Löwis4d0d4712010-12-03 20:14:31 +000081#endif
Christian Heimes2c9c7a52008-05-26 13:42:13 +000082
83/* Provides access to the internal data buffer and size of a string
84 object or the default encoded version of an Unicode object. Passing
85 NULL as *len parameter will force the string buffer to be
86 0-terminated (passing a string with embedded NULL characters will
87 cause an exception). */
88PyAPI_FUNC(int) PyBytes_AsStringAndSize(
89 register PyObject *obj, /* string or Unicode object */
90 register char **s, /* pointer to buffer variable */
91 register Py_ssize_t *len /* pointer to length variable or NULL
92 (only possible for 0-terminated
93 strings) */
94 );
95
96/* Using the current locale, insert the thousands grouping
97 into the string pointed to by buffer. For the argument descriptions,
98 see Objects/stringlib/localeutil.h */
Martin v. Löwis4d0d4712010-12-03 20:14:31 +000099#ifndef Py_LIMITED_API
Eric Smith0923d1d2009-04-16 20:16:10 +0000100PyAPI_FUNC(Py_ssize_t) _PyBytes_InsertThousandsGroupingLocale(char *buffer,
101 Py_ssize_t n_buffer,
102 char *digits,
103 Py_ssize_t n_digits,
104 Py_ssize_t min_width);
Christian Heimes2c9c7a52008-05-26 13:42:13 +0000105
Eric Smitha3b1ac82009-04-03 14:45:06 +0000106/* Using explicit passed-in values, insert the thousands grouping
107 into the string pointed to by buffer. For the argument descriptions,
108 see Objects/stringlib/localeutil.h */
Eric Smith0923d1d2009-04-16 20:16:10 +0000109PyAPI_FUNC(Py_ssize_t) _PyBytes_InsertThousandsGrouping(char *buffer,
110 Py_ssize_t n_buffer,
111 char *digits,
112 Py_ssize_t n_digits,
113 Py_ssize_t min_width,
114 const char *grouping,
115 const char *thousands_sep);
Martin v. Löwis4d0d4712010-12-03 20:14:31 +0000116#endif
Eric Smitha3b1ac82009-04-03 14:45:06 +0000117
Christian Heimes2c9c7a52008-05-26 13:42:13 +0000118/* Flags used by string formatting */
119#define F_LJUST (1<<0)
120#define F_SIGN (1<<1)
121#define F_BLANK (1<<2)
122#define F_ALT (1<<3)
123#define F_ZERO (1<<4)
Guido van Rossum4dfe8a12006-04-22 23:28:04 +0000124
125#ifdef __cplusplus
126}
127#endif
Georg Brandl0c77a822008-06-10 16:37:50 +0000128#endif /* !Py_BYTESOBJECT_H */