embeddedpy 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.


This version of embeddedpy might be problematic. Click here for more details.

embeddedpy/pointers.py ADDED
@@ -0,0 +1,552 @@
1
+ """The pointer category of embeddedpy: a purely functional pointer API.
2
+
3
+ Public usage: `from embeddedpy.pointers import ptr`.
4
+
5
+ The types ``Ptr`` / ``Func`` themselves live in ``embeddedpy.types`` (they are
6
+ language-level types with dereferencing semantics); this module only provides the
7
+ **functions that operate on pointers**.
8
+ """
9
+
10
+ from .arrays import (
11
+ _decode,
12
+ _elem_size,
13
+ _encode,
14
+ _flat_get,
15
+ _flat_set,
16
+ _list_shape,
17
+ )
18
+
19
+ # The simulation backend for bare addresses (MMIO) on the CPython development track.
20
+ #
21
+ # On the C track a bare address points at a real hardware register, and poke/peek read
22
+ # and write the physical address directly; the CPython track has no real hardware, so a
23
+ # "address -> value" backing dictionary absorbs pokes and supplies peeks, letting the
24
+ # development track also run the "write register then read it back" code path without a
25
+ # hard fork from the C track. The key is (address, element byte size); accesses of
26
+ # different widths never interfere with each other; an address that was never written reads
27
+ # back 0 (consistent with C's "uninitialized is readable").
28
+ _MMIO: "dict" = {}
29
+
30
+
31
+ def _mmio_get(addr: int, elem_size: int) -> object:
32
+ return _MMIO.get((addr, elem_size), 0)
33
+
34
+
35
+ def _mmio_set(addr: int, elem_size: int, value: object) -> None:
36
+ _MMIO[(addr, elem_size)] = value
37
+
38
+
39
+ def mmio_reset() -> None:
40
+ """Clear the simulated register backend (for testing)."""
41
+ _MMIO.clear()
42
+
43
+
44
+ class _Ptr:
45
+ """The pointer object on the CPython side, using a mutable cell to simulate C's
46
+ address-of and dereference.
47
+
48
+ Six forms:
49
+ - cell: points at a writable unit (scalar alias)
50
+ - array: points at an element offset of a fixed-length array (supports 2-D flat addressing)
51
+ - attr: points at a struct field
52
+ - addr: a bare address (MMIO scenario; not dereferenceable under CPython)
53
+ - heap: a heap memory block (allocated by mem.alloc, backed by a bytearray)
54
+ - bytes: an own byte copy (the output of data), byte-addressable and writable,
55
+ detached from the original value; _byte_text decides whether reads yield a char or a byte
56
+
57
+ Note: under CPython scalars are immutable, so ptr(x) does not truly alias the original
58
+ variable x; but once the same code is compiled to C it gains full pointer-alias semantics.
59
+ ptr.null() produces a null pointer whose boolean value is False (corresponding to C's NULL).
60
+ """
61
+
62
+ __slots__ = (
63
+ "_kind", "_is_null", "_freed", "_src_id", "_cell", "_base", "_offset",
64
+ "_shape", "_obj", "_name", "_addr", "_elem_size",
65
+ "_heap", "_heap_len", "_elem_type", "_byte_text",
66
+ )
67
+
68
+ def __init__(self, value: object = None, is_null: bool = False) -> None:
69
+ self._kind = "cell"
70
+ self._is_null = is_null
71
+ self._freed = False
72
+ self._src_id = None
73
+ self._cell = [None if is_null else value]
74
+ self._base = None
75
+ self._offset = 0
76
+ self._shape = None
77
+ self._obj = None
78
+ self._name = None
79
+ self._addr = None
80
+ self._elem_size = 0
81
+ self._heap = None
82
+ self._heap_len = 0
83
+ self._elem_type = None
84
+ # The element form of a byte-copy pointer: True=char (text) / False=uchar (bytes) / None=numeric
85
+ self._byte_text = None
86
+
87
+ # ------------------------------------------------------------ Construction
88
+
89
+ @classmethod
90
+ def _make_array(cls, base: list, offset: int) -> "_Ptr":
91
+ p = cls(None)
92
+ p._kind = "array"
93
+ p._base = base
94
+ p._offset = offset
95
+ p._shape = _list_shape(base)
96
+ return p
97
+
98
+ @classmethod
99
+ def _make_attr(cls, obj: object, name: str) -> "_Ptr":
100
+ p = cls(None)
101
+ p._kind = "attr"
102
+ p._obj = obj
103
+ p._name = name
104
+ return p
105
+
106
+ @classmethod
107
+ def _make_addr(cls, addr: int, elem_size: int) -> "_Ptr":
108
+ p = cls(None)
109
+ p._kind = "addr"
110
+ p._addr = addr
111
+ p._elem_size = elem_size
112
+ return p
113
+
114
+ @classmethod
115
+ def _make_heap(
116
+ cls, buf: bytearray, elem_type: object, elem_size: int, count: int
117
+ ) -> "_Ptr":
118
+ """Heap memory block: backed by a bytearray, addressed by element size."""
119
+ p = cls(None)
120
+ p._kind = "heap"
121
+ p._heap = buf
122
+ p._elem_type = elem_type
123
+ p._elem_size = elem_size
124
+ p._heap_len = count
125
+ return p
126
+
127
+ @classmethod
128
+ def _make_byte_copy(cls, raw: bytes, text: bool) -> "_Ptr":
129
+ """Byte-copy pointer: copy raw into an own buffer, addressed by **byte**.
130
+
131
+ ``text`` decides the element form on dereference: a text pointer reads one character
132
+ (str), a byte pointer reads one byte (bytes), aligned with the char / uchar print form
133
+ on the C track. The copy is writable; a poke only changes the copy and does not affect
134
+ the original value.
135
+ """
136
+ p = cls(None)
137
+ p._kind = "bytes"
138
+ p._obj = bytearray(raw)
139
+ p._elem_size = 1
140
+ p._byte_text = text
141
+ return p
142
+
143
+ def _copy(self) -> "_Ptr":
144
+ p = _Ptr(None)
145
+ p._kind = self._kind
146
+ p._is_null = self._is_null
147
+ p._freed = self._freed
148
+ p._src_id = self._src_id
149
+ p._cell = self._cell
150
+ p._base = self._base
151
+ p._offset = self._offset
152
+ p._shape = self._shape
153
+ p._obj = self._obj
154
+ p._name = self._name
155
+ p._addr = self._addr
156
+ p._elem_size = self._elem_size
157
+ p._heap = self._heap
158
+ p._heap_len = self._heap_len
159
+ p._elem_type = self._elem_type
160
+ p._byte_text = self._byte_text
161
+ return p
162
+
163
+ # ------------------------------------------------------------ Read/Write
164
+
165
+ def _read(self) -> object:
166
+ if self._freed:
167
+ raise RuntimeError("use of a freed pointer")
168
+ if self._kind == "cell":
169
+ return self._cell[0]
170
+ if self._kind == "array":
171
+ return _flat_get(self._base, self._shape, self._offset)
172
+ if self._kind == "attr":
173
+ return getattr(self._obj, self._name)
174
+ if self._kind == "heap":
175
+ return self._heap_read()
176
+ if self._kind == "bytes":
177
+ # Byte copy: read the current position's one byte according to the element form.
178
+ buf = self._obj
179
+ if not isinstance(buf, (bytes, bytearray)):
180
+ raise TypeError("byte copy expects a byte buffer")
181
+ if self._offset >= len(buf):
182
+ raise IndexError("byte buffer read out of bounds")
183
+ b = buf[self._offset]
184
+ if self._byte_text is None:
185
+ return b
186
+ if self._byte_text:
187
+ return bytes((b,)).decode("latin-1")
188
+ return bytes((b,))
189
+ if self._kind == "addr":
190
+ # Bare address (MMIO): the development track has no real hardware, so read from
191
+ # the simulation backend.
192
+ return _mmio_get(self._addr, self._elem_size)
193
+ raise RuntimeError("raw address cannot be dereferenced under CPython")
194
+
195
+ def _write(self, value: object) -> None:
196
+ if self._freed:
197
+ raise RuntimeError("use of a freed pointer")
198
+ if self._kind == "cell":
199
+ self._cell[0] = value
200
+ elif self._kind == "array":
201
+ _flat_set(self._base, self._shape, self._offset, value)
202
+ elif self._kind == "attr":
203
+ setattr(self._obj, self._name, value)
204
+ elif self._kind == "heap":
205
+ self._heap_write(value)
206
+ elif self._kind == "bytes":
207
+ # Byte copy is writable; the written value only affects the copy, the original
208
+ # remains unchanged.
209
+ buf = self._obj
210
+ if not isinstance(buf, bytearray):
211
+ raise TypeError("byte copy expects a writable byte buffer")
212
+ if self._offset >= len(buf):
213
+ raise IndexError("byte buffer write out of bounds")
214
+ buf[self._offset] = _byte_value(value)
215
+ elif self._kind == "addr":
216
+ # Bare address (MMIO): the development track has no real hardware, so write to the
217
+ # simulation backend so that a peek after a poke is consistent.
218
+ _mmio_set(self._addr, self._elem_size, value)
219
+ else:
220
+ raise RuntimeError("raw address cannot be written under CPython")
221
+
222
+ def _heap_read(self) -> object:
223
+ """Read one element from a heap memory block, decoded using C's fixed-width semantics."""
224
+ buf = self._heap
225
+ assert buf is not None
226
+ size = self._elem_size
227
+ start = self._offset * size
228
+ end = start + size
229
+ if end > len(buf):
230
+ raise IndexError("heap memory read out of bounds")
231
+ raw = bytes(buf[start:end])
232
+ return _decode(raw, self._elem_type)
233
+
234
+ def _heap_write(self, value: object) -> None:
235
+ """Write one element into a heap memory block, encoded using C's fixed-width semantics."""
236
+ buf = self._heap
237
+ assert buf is not None
238
+ size = self._elem_size
239
+ start = self._offset * size
240
+ end = start + size
241
+ if end > len(buf):
242
+ raise IndexError("heap memory write out of bounds")
243
+ buf[start:end] = _encode(value, self._elem_type)
244
+
245
+ # ------------------------------------------------- Struct fields (pointer base)
246
+
247
+ def _pointee(self) -> object:
248
+ """Dereference to the final pointed-to object, piercing through multiple pointer layers.
249
+
250
+ Corresponds to C's ``*p`` (one layer) and ``**p`` (multiple layers); when the pointer
251
+ points at a struct it returns the struct object itself.
252
+ """
253
+ if self._is_null:
254
+ raise RuntimeError("null pointer dereference")
255
+ obj = self._read()
256
+ while isinstance(obj, _Ptr):
257
+ if obj._is_null:
258
+ raise RuntimeError("null pointer dereference")
259
+ obj = obj._read()
260
+ return obj
261
+
262
+ def _field_get(self, name: str) -> object:
263
+ """Read a struct field: corresponds to C's ``p->f``."""
264
+ obj = self._pointee()
265
+ try:
266
+ return getattr(obj, name)
267
+ except AttributeError:
268
+ raise AttributeError(
269
+ f"{type(obj).__name__} object has no field {name!r}"
270
+ ) from None
271
+
272
+ def _field_set(self, name: str, value: object) -> None:
273
+ """Write a struct field: corresponds to C's ``p->f = v``."""
274
+ obj = self._pointee()
275
+ if not hasattr(obj, name):
276
+ raise AttributeError(
277
+ f"{type(obj).__name__} object has no field {name!r}"
278
+ )
279
+ setattr(obj, name, value)
280
+
281
+ def __getattr__(self, name: str) -> object:
282
+ """Struct field read: ``p.f`` is equivalent to C's ``p->f``.
283
+
284
+ Only triggered when ordinary attribute lookup fails, so slots and built-in attributes
285
+ are unaffected.
286
+ """
287
+ # An unassigned __slots__ slot also reaches here and must be rejected immediately,
288
+ # otherwise it would form a recursion with the slot access inside _read().
289
+ if name in _Ptr.__slots__ or (name.startswith("__") and name.endswith("__")):
290
+ raise AttributeError(name)
291
+ return self._field_get(name)
292
+
293
+ def __setattr__(self, name: str, value: object) -> None:
294
+ """Struct field write: ``p.f = v`` is equivalent to C's ``p->f = v``."""
295
+ if name in _Ptr.__slots__ or (name.startswith("__") and name.endswith("__")):
296
+ object.__setattr__(self, name, value)
297
+ return
298
+ self._field_set(name, value)
299
+
300
+ def _skip(self, n: int) -> "_Ptr":
301
+ if self._kind == "array":
302
+ return _Ptr._make_array(self._base, self._offset + n)
303
+ if self._kind == "addr":
304
+ p = self._copy()
305
+ p._addr = self._addr + n * (self._elem_size or 1)
306
+ return p
307
+ if self._kind == "heap":
308
+ p = self._copy()
309
+ p._offset = self._offset + n
310
+ return p
311
+ if self._kind == "bytes":
312
+ # Byte copy: offset is counted in bytes; after skip it still points at the same copy.
313
+ buf = self._obj
314
+ if not isinstance(buf, (bytes, bytearray)):
315
+ raise TypeError("byte copy expects a byte buffer")
316
+ if self._offset + n > len(buf):
317
+ raise IndexError("byte buffer offset out of bounds")
318
+ p = self._copy()
319
+ p._offset = self._offset + n
320
+ return p
321
+ if self._kind == "cell" and isinstance(self._cell[0], _Ptr):
322
+ return self._cell[0]._skip(n)
323
+ if self._kind == "cell" and n == 0:
324
+ # Consistent with C: &x + 0 still points at x
325
+ return self
326
+ raise RuntimeError("this pointer does not support offset arithmetic")
327
+
328
+ # ------------------------------------------------------------ Truthiness
329
+
330
+ def __bool__(self) -> bool:
331
+ return not self._is_null
332
+
333
+ # -------------------------------------------------- Equality (by address, corresponds to C's p == q)
334
+
335
+ def _addr_key(self) -> tuple:
336
+ """The address identity of a pointer.
337
+
338
+ Corresponds to C's "two pointers compare by address": they are equal only if they point
339
+ at the same place. The cell form uses the **source object identity** (``_src_id``)
340
+ rather than the list's id -- because ``ptr.ref(x)`` creates a new cell container each
341
+ time, yet the C side takes the same variable.
342
+ """
343
+ if self._is_null:
344
+ return ("null",)
345
+ if self._kind == "addr":
346
+ return ("addr", self._addr)
347
+ if self._kind == "array":
348
+ return ("array", id(self._base), self._offset)
349
+ if self._kind == "attr":
350
+ return ("attr", id(self._obj), self._name)
351
+ if self._kind == "heap":
352
+ return ("heap", id(self._heap), self._offset)
353
+ if self._kind == "bytes":
354
+ return ("bytes", id(self._obj), self._offset)
355
+ if self._src_id is not None:
356
+ return ("cell", self._src_id)
357
+ return ("cell", id(self._cell))
358
+
359
+ def __eq__(self, other: object) -> bool:
360
+ if not isinstance(other, _Ptr):
361
+ return NotImplemented
362
+ return self._addr_key() == other._addr_key()
363
+
364
+ def __ne__(self, other: object) -> bool:
365
+ result = self.__eq__(other)
366
+ if result is NotImplemented:
367
+ return result
368
+ return not result
369
+
370
+ def __hash__(self) -> int:
371
+ return hash(self._addr_key())
372
+
373
+ def __repr__(self) -> str:
374
+ if self._is_null:
375
+ return "ptr.null()"
376
+ if self._kind == "addr":
377
+ return f"ptr(0x{self._addr:X})"
378
+ if self._kind == "array":
379
+ return f"ptr(array@{self._offset})"
380
+ if self._kind == "attr":
381
+ return f"ptr({self._name})"
382
+ return f"ptr({self._cell[0]!r})"
383
+
384
+ def _ref(x: object) -> _Ptr:
385
+ """The common implementation of taking an address."""
386
+ if x is None:
387
+ raise TypeError(
388
+ "ptr(x) does not accept None; use ptr.null() for a null pointer"
389
+ )
390
+ if isinstance(x, _Ptr):
391
+ return _Ptr(x)
392
+ if isinstance(x, list):
393
+ return _Ptr._make_array(x, 0)
394
+ p = _Ptr(x)
395
+ # Record the source object identity: two ptr.ref(same variable) calls are the same address
396
+ # on the C side; here we use it to make pointer comparison consistent with C (the _cell is a
397
+ # fresh container each time and cannot be used for this).
398
+ p._src_id = id(x)
399
+ return p
400
+
401
+ class _PtrAPI:
402
+ """A purely functional pointer API.
403
+
404
+ Correspondence:
405
+ ptr.ref(x) -> &x take address
406
+ ptr.null() -> NULL null pointer
407
+ ptr.peek(p) -> *p read
408
+ ptr.poke(p, v) -> *p = v write
409
+ ptr.skip(p, n) -> p + n offset (by element)
410
+ ptr.field(s, "f") -> &s.f field address
411
+ ptr.from_int(a, T) -> (T*)a bare address
412
+ ptr.cast(p, T) -> (T*)p type re-interpretation
413
+
414
+ The legacy form ptr(x) (equivalent to ptr.ref(x)) is also kept; the two styles can be
415
+ mixed.
416
+ """
417
+
418
+ __slots__ = ()
419
+
420
+ def __call__(self, x: object) -> _Ptr:
421
+ """Legacy address-of: ptr(x) is equivalent to ptr.ref(x)."""
422
+ return _ref(x)
423
+
424
+ def ref(self, x: object) -> _Ptr:
425
+ """Take an address, corresponding to C's &x."""
426
+ return _ref(x)
427
+
428
+ def null(self) -> _Ptr:
429
+ """A null pointer, corresponding to C's NULL."""
430
+ return _Ptr(None, is_null=True)
431
+
432
+ def peek(self, p: object) -> object:
433
+ """Dereferenced read, corresponding to C's *p."""
434
+ if not isinstance(p, _Ptr):
435
+ raise TypeError("ptr.peek requires a pointer")
436
+ if p._is_null:
437
+ raise RuntimeError("null pointer dereference")
438
+ return p._read()
439
+
440
+ def poke(self, p: object, value: object) -> None:
441
+ """Dereferenced write, corresponding to C's *p = v."""
442
+ if not isinstance(p, _Ptr):
443
+ raise TypeError("ptr.poke expects a pointer")
444
+ if p._is_null:
445
+ raise RuntimeError("null pointer dereference")
446
+ p._write(value)
447
+
448
+ def skip(self, p: object, n: int) -> _Ptr:
449
+ """Pointer offset, corresponding to C's p + n (by element)."""
450
+ if not isinstance(p, _Ptr):
451
+ raise TypeError("ptr.skip expects a pointer")
452
+ return p._skip(int(n))
453
+
454
+ def field(self, obj: object, name: str) -> _Ptr:
455
+ """Take a struct field address, corresponding to C's &s.f.
456
+
457
+ The first argument may be a struct value or a pointer to a struct
458
+ (corresponding to C's ``&p->f``).
459
+ """
460
+ if not isinstance(name, str):
461
+ raise TypeError("ptr.field field name must be a string")
462
+ target = obj
463
+ if isinstance(target, _Ptr):
464
+ # Pointer base: first dereference to the struct object, then take the field address.
465
+ target = target._pointee()
466
+ if not hasattr(target, name):
467
+ raise AttributeError(f"no field named {name}")
468
+ return _Ptr._make_attr(target, name)
469
+
470
+ def from_int(self, addr: int, elem_type: object = None) -> _Ptr:
471
+ """Construct a bare-address pointer, corresponding to C's (T*)addr."""
472
+ return _Ptr._make_addr(int(addr), _elem_size(elem_type))
473
+
474
+ def cast(self, p: object, elem_type: object) -> _Ptr:
475
+ """Pointer type re-interpretation, corresponding to C's (T*)p."""
476
+ if not isinstance(p, _Ptr):
477
+ raise TypeError("ptr.cast requires a pointer")
478
+ q = p._copy()
479
+ if q._kind == "addr":
480
+ q._elem_size = _elem_size(elem_type)
481
+ return q
482
+
483
+ ptr = _PtrAPI()
484
+
485
+
486
+ def _byte_value(v: object) -> int:
487
+ """Fold a pointer element down to a single byte value.
488
+
489
+ The element may be a numeric value (``Ptr[uint8]`` / heap memory) or a single-byte
490
+ character family member (``char`` is a 1-character text, ``uchar`` / ``schar`` are 1-byte
491
+ byte strings).
492
+ """
493
+ if isinstance(v, bool):
494
+ return int(v)
495
+ if isinstance(v, int):
496
+ return v & 0xFF
497
+ if isinstance(v, str):
498
+ raw = v.encode("utf-8")
499
+ if len(raw) != 1:
500
+ raise ValueError("a char element must hold exactly one byte")
501
+ return raw[0]
502
+ if isinstance(v, bytes):
503
+ if len(v) != 1:
504
+ raise ValueError("a byte element must hold exactly one byte")
505
+ return v[0]
506
+ raise TypeError(f"cannot read a byte from {type(v).__name__}")
507
+
508
+
509
+ def _read_byte_view(p: object, n: int) -> bytes:
510
+ """Read n bytes from "pointer + byte length" (CPython track).
511
+
512
+ Corresponds to the C track's ``(const unsigned char *)p`` plus a length. The pointer may be
513
+ a byte copy (the output of ``data``), an array/heap pointer, or a raw byte string.
514
+ """
515
+ if isinstance(n, bool) or not isinstance(n, int):
516
+ raise TypeError("byte length must be an integer")
517
+ if n < 0:
518
+ raise ValueError("byte length cannot be negative")
519
+ if isinstance(p, _Ptr):
520
+ if p._is_null:
521
+ raise RuntimeError("null pointer dereference")
522
+ if p._kind == "bytes":
523
+ buf = p._obj
524
+ if not isinstance(buf, (bytes, bytearray)):
525
+ raise TypeError("byte copy expects a byte buffer")
526
+ end = p._offset + n
527
+ if end > len(buf):
528
+ raise ValueError("byte length exceeds the buffer")
529
+ return bytes(buf[p._offset:end])
530
+ out = bytearray()
531
+ cur = p
532
+ for _ in range(n):
533
+ out.append(_byte_value(cur._read()))
534
+ cur = cur._skip(1)
535
+ return bytes(out)
536
+ raw: bytes
537
+ if isinstance(p, bytes):
538
+ raw = p
539
+ elif isinstance(p, bytearray):
540
+ raw = bytes(p)
541
+ elif isinstance(p, str):
542
+ raw = p.encode("utf-8")
543
+ else:
544
+ raise TypeError("from_ptr expects a pointer to a byte buffer")
545
+ if n > len(raw):
546
+ raise ValueError("byte length exceeds the buffer")
547
+ return raw[:n]
548
+
549
+
550
+ __all__ = [
551
+ "ptr",
552
+ ]
embeddedpy/strings.py ADDED
@@ -0,0 +1,68 @@
1
+ """Byte entry/exit points for text buffers.
2
+
3
+ External usage: ``from embeddedpy.strings import strings``.
4
+
5
+ ``Str`` is an immutable value with a length; the C-side character buffer interface
6
+ wants a raw address + length. This module provides an explicit pair of entry/exit
7
+ points between the two representations:
8
+
9
+ - ``strings.data(s)``: copy out a byte copy and return a ``char *`` pointing to it;
10
+ - ``strings.from_ptr(p, n)``: copy from "pointer + byte length" into a text value.
11
+
12
+ Both directions copy: the outgoing copy and the incoming text are detached from each
13
+ other. Use ``strings.byte_len(s)`` for the byte length and ``len(s)`` for the character
14
+ count; the buffer has no NUL terminator -- pointer and length are used as a pair.
15
+ """
16
+
17
+ from typing import Any
18
+
19
+ from .pointers import _Ptr, _read_byte_view
20
+
21
+
22
+ class _StringsAPI:
23
+ """Text buffer API: free functions, no methods introduced."""
24
+
25
+ __slots__ = ()
26
+
27
+ @staticmethod
28
+ def data(s: Any) -> Any:
29
+ """Get a byte-copy pointer of the text (corresponds to C's ``char *``).
30
+
31
+ Copy: the bytes are copied into an owned buffer, and a pointer to the copy is
32
+ returned. Modifying the copy does not affect the original text; the copy is
33
+ byte-addressable and can be read/written with ``ptr.peek`` / ``ptr.poke`` and
34
+ moved byte-wise with ``ptr.skip``.
35
+ """
36
+ if isinstance(s, bytes):
37
+ raw = s
38
+ elif isinstance(s, str):
39
+ raw = s.encode("utf-8")
40
+ else:
41
+ raise TypeError("strings.data expects a string or bytes")
42
+ return _Ptr._make_byte_copy(raw, text=True)
43
+
44
+ @staticmethod
45
+ def byte_len(s: Any) -> int:
46
+ """Byte length (not the character count). Use ``len(s)`` for the character count."""
47
+ if isinstance(s, bytes):
48
+ return len(s)
49
+ if isinstance(s, str):
50
+ return len(s.encode("utf-8"))
51
+ raise TypeError("strings.byte_len expects a string or bytes")
52
+
53
+ @staticmethod
54
+ def from_ptr(p: Any, n: Any) -> Any:
55
+ """Build text from "pointer + byte length" (corresponds to C's ``char *`` + length).
56
+
57
+ Copy: the resulting text is detached from the original buffer, so it is unaffected
58
+ even if the original buffer later becomes invalid. The length is measured in
59
+ **bytes**, not the character count; the bytes must be valid UTF-8.
60
+ """
61
+ return _read_byte_view(p, n).decode("utf-8")
62
+
63
+
64
+ strings = _StringsAPI()
65
+
66
+ __all__ = [
67
+ "strings",
68
+ ]