Skip to content

C
cpython
Commit 628c622c authored by Georg Brandl's avatar Georg Brandl
Browse files
Options

Merged revisions 85132 via svnmerge from 

svn+ssh://svn.python.org/python/branches/py3k

........
  r85132 | georg.brandl | 2010-10-01 07:38:10 +0200 (Fr, 01 Okt 2010) | 1 line

  Fix weird markup that caused latex to fail.
........
parent 2e48a45d
Show whitespace changes
Inline Side-by-side
Showing with 90 additions and 92 deletions
Doc/c-api/buffer.rst
View file @ 628c622c
...@@ -190,98 +190,96 @@ Buffer-related functions ...@@ -190,98 +190,96 @@ Buffer-related functions
values. On error, -1 is returned and an exception is raised; the *view* values. On error, -1 is returned and an exception is raised; the *view*
is left in an undefined state. is left in an undefined state.
The following table gives possible values to the *flags* arguments. The following are the possible values to the *flags* arguments.
+------------------------------+---------------------------------------------------+ .. cmacro:: PyBUF_SIMPLE
| Flag | Description |
+==============================+===================================================+ This is the default flag. The returned buffer exposes a read-only
| .. cmacro:: PyBUF_SIMPLE | This is the default flag. The returned buffer | memory area. The format of data is assumed to be raw unsigned bytes,
| | exposes a read-only memory area. The format of | without any particular structure. This is a "stand-alone" flag
| | data is assumed to be raw unsigned bytes, without | constant. It never needs to be '|'d to the others. The exporter will
| | any particular structure. This is a "stand-alone"| raise an error if it cannot provide such a contiguous buffer of bytes.
| | flag constant. It |
| | never needs to be '|'d to the others. The exporter| .. cmacro:: PyBUF_WRITABLE
| | will raise an error if it cannot provide such a |
| | contiguous buffer of bytes. | Like :cmacro:`PyBUF_SIMPLE`, but the returned buffer is writable. If
| | | the exporter doesn't support writable buffers, an error is raised.
+------------------------------+---------------------------------------------------+
| .. cmacro:: PyBUF_WRITABLE | Like :cmacro:`PyBUF_SIMPLE`, but the returned | .. cmacro:: PyBUF_STRIDES
| | buffer is writable. If the exporter doesn't |
| | support | This implies :cmacro:`PyBUF_ND`. The returned buffer must provide
| | writable buffers, an error is raised. | strides information (i.e. the strides cannot be NULL). This would be
+------------------------------+---------------------------------------------------+ used when the consumer can handle strided, discontiguous arrays.
| .. cmacro:: PyBUF_STRIDES | This implies :cmacro:`PyBUF_ND`. The returned | Handling strides automatically assumes you can handle shape. The
| | buffer must provide strides information (i.e. the | exporter can raise an error if a strided representation of the data is
| | strides cannot be NULL). This would be used when | not possible (i.e. without the suboffsets).
| | the consumer can handle strided, discontiguous |
| | arrays. Handling strides automatically assumes | .. cmacro:: PyBUF_ND
| | you can handle shape. The exporter can raise an |
| | error if a strided representation of the data is | The returned buffer must provide shape information. The memory will be
| | not possible (i.e. without the suboffsets). | assumed C-style contiguous (last dimension varies the fastest). The
| | | exporter may raise an error if it cannot provide this kind of
+------------------------------+---------------------------------------------------+ contiguous buffer. If this is not given then shape will be *NULL*.
| .. cmacro:: PyBUF_ND | The returned buffer must provide shape |
| | information. The memory will be assumed C-style | .. cmacro:: PyBUF_C_CONTIGUOUS
| | contiguous (last dimension varies the | PyBUF_F_CONTIGUOUS
| | fastest). The exporter may raise an error if it | PyBUF_ANY_CONTIGUOUS
| | cannot provide this kind of contiguous buffer. If |
| | this is not given then shape will be *NULL*. | These flags indicate that the contiguity returned buffer must be
| | | respectively, C-contiguous (last dimension varies the fastest), Fortran
+------------------------------+---------------------------------------------------+ contiguous (first dimension varies the fastest) or either one. All of
|.. cmacro:: PyBUF_C_CONTIGUOUS| These flags indicate that the contiguity returned | these flags imply :cmacro:`PyBUF_STRIDES` and guarantee that the
| PyBUF_F_CONTIGUOUS| buffer must be respectively, C-contiguous (last | strides buffer info structure will be filled in correctly.
| PyBUF_ANY_CONTIGUOUS| dimension varies the fastest), Fortran contiguous |
| | (first dimension varies the fastest) or either | .. cmacro:: PyBUF_INDIRECT
| | one. All of these flags imply |
| | :cmacro:`PyBUF_STRIDES` and guarantee that the | This flag indicates the returned buffer must have suboffsets
| | strides buffer info structure will be filled in | information (which can be NULL if no suboffsets are needed). This can
| | correctly. | be used when the consumer can handle indirect array referencing implied
| | | by these suboffsets. This implies :cmacro:`PyBUF_STRIDES`.
+------------------------------+---------------------------------------------------+
| .. cmacro:: PyBUF_INDIRECT | This flag indicates the returned buffer must have | .. cmacro:: PyBUF_FORMAT
| | suboffsets information (which can be NULL if no |
| | suboffsets are needed). This can be used when | The returned buffer must have true format information if this flag is
| | the consumer can handle indirect array | provided. This would be used when the consumer is going to be checking
| | referencing implied by these suboffsets. This | for what 'kind' of data is actually stored. An exporter should always
| | implies :cmacro:`PyBUF_STRIDES`. | be able to provide this information if requested. If format is not
| | | explicitly requested then the format must be returned as *NULL* (which
| | | means ``'B'``, or unsigned bytes).
| | |
+------------------------------+---------------------------------------------------+ .. cmacro:: PyBUF_STRIDED
| .. cmacro:: PyBUF_FORMAT | The returned buffer must have true format |
| | information if this flag is provided. This would | This is equivalent to ``(PyBUF_STRIDES | PyBUF_WRITABLE)``.
| | be used when the consumer is going to be checking |
| | for what 'kind' of data is actually stored. An | .. cmacro:: PyBUF_STRIDED_RO
| | exporter should always be able to provide this |
| | information if requested. If format is not | This is equivalent to ``(PyBUF_STRIDES)``.
| | explicitly requested then the format must be |
| | returned as *NULL* (which means ``'B'``, or | .. cmacro:: PyBUF_RECORDS
| | unsigned bytes) |
+------------------------------+---------------------------------------------------+ This is equivalent to ``(PyBUF_STRIDES | PyBUF_FORMAT |
| .. cmacro:: PyBUF_STRIDED | This is equivalent to ``(PyBUF_STRIDES | | PyBUF_WRITABLE)``.
| | PyBUF_WRITABLE)``. |
+------------------------------+---------------------------------------------------+ .. cmacro:: PyBUF_RECORDS_RO
| .. cmacro:: PyBUF_STRIDED_RO | This is equivalent to ``(PyBUF_STRIDES)``. |
| | | This is equivalent to ``(PyBUF_STRIDES | PyBUF_FORMAT)``.
+------------------------------+---------------------------------------------------+
| .. cmacro:: PyBUF_RECORDS | This is equivalent to ``(PyBUF_STRIDES | | .. cmacro:: PyBUF_FULL
| | PyBUF_FORMAT | PyBUF_WRITABLE)``. |
+------------------------------+---------------------------------------------------+ This is equivalent to ``(PyBUF_INDIRECT | PyBUF_FORMAT |
| .. cmacro:: PyBUF_RECORDS_RO | This is equivalent to ``(PyBUF_STRIDES | | PyBUF_WRITABLE)``.
| | PyBUF_FORMAT)``. |
+------------------------------+---------------------------------------------------+ .. cmacro:: PyBUF_FULL_RO
| .. cmacro:: PyBUF_FULL | This is equivalent to ``(PyBUF_INDIRECT | |
| | PyBUF_FORMAT | PyBUF_WRITABLE)``. | This is equivalent to ``(PyBUF_INDIRECT | PyBUF_FORMAT)``.
+------------------------------+---------------------------------------------------+
| .. cmacro:: PyBUF_FULL_RO | This is equivalent to ``(PyBUF_INDIRECT | | .. cmacro:: PyBUF_CONTIG
| | PyBUF_FORMAT)``. |
+------------------------------+---------------------------------------------------+ This is equivalent to ``(PyBUF_ND | PyBUF_WRITABLE)``.
| .. cmacro:: PyBUF_CONTIG | This is equivalent to ``(PyBUF_ND | |
| | PyBUF_WRITABLE)``. | .. cmacro:: PyBUF_CONTIG_RO
+------------------------------+---------------------------------------------------+
| .. cmacro:: PyBUF_CONTIG_RO | This is equivalent to ``(PyBUF_ND)``. | This is equivalent to ``(PyBUF_ND)``.
| | |
+------------------------------+---------------------------------------------------+
.. cfunction:: void PyBuffer_Release(Py_buffer *view) .. cfunction:: void PyBuffer_Release(Py_buffer *view)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7