1 /**
2   Mirrors _stringobject.h
3 
4 Type PyStringObject represents a character string.  An extra zero byte is
5 reserved at the end to ensure it is zero-terminated, but a size is
6 present so strings with null bytes in them can be represented.  This
7 is an immutable object type.
8 
9 There are functions to create new string objects, to test
10 an object for string-ness, and to get the
11 string value.  The latter function returns a null pointer
12 if the object is not of the proper type.
13 There is a variant that takes an explicit size as well as a
14 variant that assumes a zero-terminated string.  Note that none of the
15 functions should be applied to nil objects.
16 
17 Note _stringobject goes away in python 3 (well, sort of; it gets moved to
18 bytesobject.h - look there for portability)
19   */
20 module deimos.python.stringobject;
21 
22 import deimos.python.pyport;
23 import deimos.python.object;
24 import core.stdc.stdarg;
25 
26 version(Python_3_0_Or_Later) {
27 }else{
28 extern(C):
29 // Python-header-file: Include/stringobject.h:
30 
31 /** Invariants:
32  *     ob_sval contains space for 'ob_size+1' elements.
33  *     ob_sval[ob_size] == 0.
34  *     ob_shash is the hash of the string or -1 if not computed yet.
35  *     ob_sstate != 0 iff the string object is in stringobject.c's
36  *       'interned' dictionary; in this case the two references
37  *       from 'interned' to this object are *not counted* in ob_refcnt.
38  *
39  * subclass of PyVarObject
40  */
41 /// Availability: 2.*
42 struct PyStringObject {
43     mixin PyObject_VAR_HEAD;
44 
45     ///_
46     C_long ob_shash;
47     ///_
48     int ob_sstate;
49     // Will the D layout for a 1-char array be the same as the C layout?  I
50     // think the D array will be larger.
51     // John-Colvin 2014-10-14: It should be the same. char[1].sizeof == 1
52     char[1] _ob_sval;
53     ///_
54     char* ob_sval()() {
55         return _ob_sval.ptr;
56     }
57 }
58 
59 /// Availability: 2.*
60 mixin(PyAPI_DATA!"PyTypeObject PyBaseString_Type");
61 /// Availability: 2.*
62 mixin(PyAPI_DATA!"PyTypeObject PyString_Type");
63 
64 // D translation of C macro:
65 /// Availability: 2.*
66 int PyString_Check()(PyObject* op) {
67     return PyObject_TypeCheck(op, &PyString_Type);
68 }
69 // D translation of C macro:
70 /// Availability: 2.*
71 int PyString_CheckExact()(PyObject* op) {
72     return Py_TYPE(op) == &PyString_Type;
73 }
74 
75 /**
76    For PyString_FromString(), the parameter `str' points to a null-terminated
77    string containing exactly `size' bytes.
78 
79    For PyString_FromStringAndSize(), the parameter the parameter `str' is
80    either NULL or else points to a string containing at least `size' bytes.
81    For PyString_FromStringAndSize(), the string in the `str' parameter does
82    not have to be null-terminated.  (Therefore it is safe to construct a
83    substring by calling `PyString_FromStringAndSize(origstring, substrlen)'.)
84    If `str' is NULL then PyString_FromStringAndSize() will allocate `size+1'
85    bytes (setting the last byte to the null terminating character) and you can
86    fill in the data yourself.  If `str' is non-NULL then the resulting
87    PyString object must be treated as immutable and you must not fill in nor
88    alter the data yourself, since the strings may be shared.
89 
90    The PyObject member `op->ob_size', which denotes the number of "extra
91    items" in a variable-size object, will contain the number of bytes
92    allocated for string data, not counting the null terminating character.
93    It is therefore equal to the `size' parameter (for
94    PyString_FromStringAndSize()) or the length of the string in the `str'
95    parameter (for PyString_FromString()).
96 */
97 /// Availability: 2.*
98 PyObject* PyString_FromStringAndSize(const(char)*, Py_ssize_t);
99 /// ditto
100 PyObject* PyString_FromString(const(char)*);
101 /// Availability: 2.*
102 PyObject* PyString_FromFormatV(const(char)*,  va_list);
103 /// Availability: 2.*
104 PyObject* PyString_FromFormat(const(char)*, ...);
105 /// Availability: 2.*
106 Py_ssize_t PyString_Size(PyObject*);
107 /// Availability: 2.*
108 const(char)* PyString_AsString(PyObject*);
109 /** Use only if you know it's a string */
110 /// Availability: 2.*
111 int PyString_CHECK_INTERNED()(PyObject* op) {
112     return (cast(PyStringObject*)op).ob_sstate;
113 }
114 /** Macro, trading safety for speed */
115 /// Availability: 2.*
116 const(char)* PyString_AS_STRING()(PyObject* op) {
117     return (cast(PyStringObject*)op).ob_sval;
118 }
119 /// Availability: 2.*
120 Py_ssize_t PyString_GET_SIZE()(PyObject* op) {
121     return (cast(PyStringObject*)op).ob_size;
122 }
123 /// Availability: 2.*
124 PyObject* PyString_Repr(PyObject*, int);
125 /// Availability: 2.*
126 void PyString_Concat(PyObject**, PyObject*);
127 /// Availability: 2.*
128 void PyString_ConcatAndDel(PyObject**, PyObject*);
129 /// Availability: 2.*
130 int _PyString_Resize(PyObject**, Py_ssize_t);
131 /// Availability: 2.*
132 int _PyString_Eq(PyObject*, PyObject*);
133 /// Availability: 2.*
134 PyObject* PyString_Format(PyObject*, PyObject*);
135 /// Availability: 2.*
136 PyObject* _PyString_FormatLong(PyObject*, int, int, int, char**, int*);
137 /// Availability: 2.*
138 PyObject* PyString_DecodeEscape(const(char)*, Py_ssize_t, const(char)*, Py_ssize_t, const(char)*);
139 
140 /// Availability: 2.*
141 void PyString_InternInPlace(PyObject**);
142 /// Availability: 2.*
143 void PyString_InternImmortal(PyObject**);
144 /// Availability: 2.*
145 PyObject* PyString_InternFromString(const(char)*);
146 
147 /// Availability: 2.*
148 PyObject* _PyString_Join(PyObject* sep, PyObject* x);
149 
150 /// Availability: 2.*
151 PyObject* PyString_Decode(const(char)* s, Py_ssize_t size, const(char)* encoding, const(char) *errors);
152 /// Availability: 2.*
153 PyObject* PyString_Encode(const(char)* s, Py_ssize_t size, const(char)* encoding, const(char)* errors);
154 
155 /// Availability: 2.*
156 PyObject* PyString_AsEncodedObject(PyObject* str, const(char)* encoding, const(char)* errors);
157 /// Availability: 2.*
158 PyObject* PyString_AsDecodedObject(PyObject* str, const(char)* encoding, const(char)* errors);
159 
160 // Since no one has legacy Python extensions written in D, the deprecated
161 // functions PyString_AsDecodedString and PyString_AsEncodedString were
162 // omitted.
163 
164 /// Availability: 2.*
165 int PyString_AsStringAndSize(PyObject* obj, char** s, int* len);
166 
167 version(Python_2_6_Or_Later){
168     /** Using the current locale, insert the thousands grouping
169        into the string pointed to by buffer.  For the argument descriptions,
170        see Objects/stringlib/localeutil.h */
171 
172     /// Availability: 2.6, 2.7
173     int _PyString_InsertThousandsGrouping(char* buffer,
174             Py_ssize_t n_buffer,
175             Py_ssize_t n_digits,
176             Py_ssize_t buf_size,
177             Py_ssize_t* count,
178             int append_zero_char);
179 
180     /** Format the object based on the format_spec, as defined in PEP 3101
181        (Advanced String Formatting). */
182     /// Availability: 2.6, 2.7
183     PyObject*  _PyBytes_FormatAdvanced(PyObject* obj,
184             char* format_spec,
185             Py_ssize_t format_spec_len);
186 }
187 
188 }