docs/builtins: Describe MicroPython memoryview() extensions.
@@ -98,7 +98,60 @@ Functions and types
.. function:: max()
-.. class:: memoryview()
+.. class:: memoryview(buffer)
+ memoryview(buffer, offset, size)
+
+ |see_cpython| `python:memoryview`.
+
+ .. admonition:: MicroPython extension
+ :class: note
+
+ A `str` object can be passed to memoryview() constructor, in which
+ case underlying UTF-8 encoded data can be accessed by memoryview.
+ ``memoryview("abc")`` is equivalent to ``memoryview("abc".encode())``,
+ but is more memory-efficient.
+
+ .. admonition:: MicroPython extension
+ :class: note
+
+ Additional *offset* and *size* parameters can be passed to constructor.
+ ``mv = memoryview(buf, offset, size)`` is equivalent to
+ ``mv1 = memoryview(buf); mv = mv1[offset:offset + size]``, but is more
+ memory-efficient.
+
+ .. method:: init(buffer[, offset, size])
+
+ Reinitialize existing `memoryview` object inplace with a new buffer,
+ and optionally given *offset* and *size* into it.
+
+ .. admonition:: MicroPython extension
+ :class: note
+
+ This method is a MicroPython extension. It doesn't require memory
+ allocation. Just as the constructor, this method can be called
+ for `str` objects too.
+
+ Example of usage of MicroPython extensions::
+
+ # A function with zero memory allocation which can write either
+ # bytes or str objects to a stream, in the presense of short writes.
+
+ # Pre-allocate static memoryview buffer
+ bufptr = memoryview(b"")
+
+ def write_any(stream, data):
+ bufptr.init(data)
+ # We need size in bytes, not in characters in case of Unicode
+ # strings, and size of memoryview gives us that.
+ sz = len(bufptr)
+ offset = 0
+ while sz:
+ # We use another MicroPython extension, 3-argument stream
+ # .write() method. We could use memoryview.init() method
+ # to update "visible" part of underlying buffer instead.
+ written = stream.write(bufptr, offset, sz)
+ offset += written
+ sz -= written
.. function:: min()
