ndtypes 0.2.0dev4

data/ext/ruby_ndtypes/ndtypes/doc/libndtypes/encodings.rst

@@ -0,0 +1,68 @@
+.. meta::
+   :robots: index,follow
+   :description: libndtypes documentation
+
+.. sectionauthor:: Stefan Krah <skrah at bytereef.org>
+
+
+
+Encodings
+=========
+
+Some types support encoding parameters.
+
+.. code-block:: c
+
+   #include <ndtypes.h>
+
+   /* Encoding for characters and strings */
+   enum ndt_encoding {
+     Ascii,
+     Utf8,
+     Utf16,
+     Utf32,
+     Ucs2,
+   };
+
+
+Functions
+---------
+
+.. topic:: ndt_encoding_from_string
+
+.. code-block:: c
+
+   enum ndt_encoding ndt_encoding_from_string(const char *s, ndt_context_t *ctx);
+
+Convert a string to the corresponding enum value.  The caller must use
+:func:`ndt_err_occurred` to check for errors.
+
+
+.. topic:: ndt_encoding_as_string
+
+.. code-block:: c
+
+   const char *ndt_encoding_as_string(enum ndt_encoding encoding);
+
+Convert an encoding to its string representation.
+
+
+.. topic:: ndt_sizeof_encoding
+
+.. code-block:: c
+
+   size_t ndt_sizeof_encoding(enum ndt_encoding encoding);
+
+Return the memory size of a single code point.
+
+
+.. topic:: ndt_alignof_encoding
+
+.. code-block:: c
+
+   uint16_t ndt_alignof_encoding(enum ndt_encoding encoding);
+
+Return the alignment of a single code point.
+
+
+

data/ext/ruby_ndtypes/ndtypes/doc/libndtypes/fields-values.rst

@@ -0,0 +1,175 @@
+.. meta::
+   :robots: index,follow
+   :description: libndtypes documentation
+
+.. sectionauthor:: Stefan Krah <skrah at bytereef.org>
+
+
+Fields and values
+=================
+
+Some API functions expect fields for creating tuple or record types or values
+for creating categorical types.
+
+
+Fields
+------
+
+.. topic:: uint16_opt
+
+.. code-block:: c
+
+   enum ndt_option {
+     None,
+     Some
+   };
+
+   typedef struct {
+     enum ndt_option tag;
+     uint16_t Some;
+   } uint16_opt_t;
+
+
+Due to the multitude of options in creating fields a number of functions take
+a *uint16_opt_t* struct.  If *tag* is *None*, no value has been specified
+and the *Some* field is undefined.
+
+If *tag* is *Some*, the value in the *Some* field has been explicitly given.
+
+
+Functions
+---------
+
+.. topic:: ndt_field
+
+.. code-block:: c
+
+   ndt_field_t *ndt_field(char *name, ndt_t *type, uint16_opt_t align,
+                          uint16_opt_t pack, uint16_opt_t pad, ndt_context_t *ctx);
+
+
+Create a new field.  For tuples, *name* is :c:macro:`NULL`.  The `align`
+and `pack` options are mutually exclusive and have exactly the same
+function as *gcc's* `aligned` and `packed` attributes when applied to
+individual fields.
+
+The `pad` field has no influence on the field layout. It is present to
+enable sanity checks when an explicit number of padding bytes has been
+specified (Example: PEP-3118).
+
+
+.. topic:: ndt_field_del
+
+.. code-block:: c
+
+   void ndt_field_del(ndt_field_t *field);
+
+Deallocate a field.
+
+
+.. topic:: ndt_field_array_del
+
+.. code-block:: c
+
+   void ndt_field_array_del(ndt_field_t *fields, int64_t shape);
+
+
+Deallocate an array of fields.
+
+
+Values
+------
+
+.. topic:: values
+
+.. code-block:: c
+
+   /* Selected values for the categorical type. */
+   enum ndt_value {
+     ValBool,
+     ValInt64,
+     ValFloat64,
+     ValString,
+     ValNA,
+   };
+
+   typedef struct {
+     enum ndt_value tag;
+       union {
+         bool ValBool;
+         int64_t ValInt64;
+         double ValFloat64;
+         char *ValString;
+     };
+   } ndt_value_t;
+
+
+The categorical type contains values.  Currently a small number of primitive
+types are supported.  It would be possible to use memory typed by *ndt_t* itself
+either by introducing a circular relationship between libndtypes and container
+libraries or by duplicating parts of a container library.
+
+It remains to be seen if such an added complexity is useful.
+
+
+
+.. topic:: ndt_value_from_number
+
+.. code-block:: c
+
+   ndt_value_t *ndt_value_from_number(enum ndt_value tag, char *v, ndt_context_t *ctx);
+
+Construct a number or boolean value from a string.  *tag* must be one of
+:c:macro:`ValBool`, :c:macro:`ValInt64`, or :c:macro:`ValFloat64`.
+
+
+.. topic:: ndt_value_from_string
+
+.. code-block:: c
+
+   ndt_value_t *ndt_value_from_string(char *v, ndt_context_t *ctx);
+
+Construct a :c:macro:`ValString` value from a string.
+
+
+.. topic:: *ndt_value_na
+
+.. code-block:: c
+
+   ndt_value_t *ndt_value_na(ndt_context_t *ctx);
+
+Construct the :c:macro:`NA` value.
+
+
+.. topic:: ndt_value_equal
+
+.. code-block:: c
+
+   int ndt_value_equal(const ndt_value_t *x, const ndt_value_t *y);
+
+Determine if two values are equal. :c:macro:`NA` compares not equal to
+itself.
+
+
+.. topic:: ndt_value_mem_equal
+
+.. code-block:: c
+
+   ndt_value_mem_equal(const ndt_value_t *x, const ndt_value_t *y);
+
+Determine if two values are structurally equal. :c:macro:`NA` compares
+equal to itself.
+
+
+.. topic:: ndt_value_compare
+
+.. code-block:: c
+
+   int ndt_value_compare(const ndt_value_t *x, const ndt_value_t *y);
+
+Compare values according to a sorting order. :c:macro:`NA` compares equal
+to itself.
+
+
+
+

data/ext/ruby_ndtypes/ndtypes/doc/libndtypes/functions.rst

@@ -0,0 +1,72 @@
+.. meta::
+   :robots: index,follow
+   :description: libndtypes documentation
+
+.. sectionauthor:: Stefan Krah <skrah at bytereef.org>
+
+
+Functions
+=========
+
+Most library functions are for creating types. The functions in this section
+operate *on* types.
+
+
+Copying
+-------
+
+.. topic:: ndt_copy
+
+.. code-block:: c
+
+   ndt_t *ndt_copy(const ndt_t *t, ndt_context_t *ctx);
+
+Create a copy of the argument. This is an important function, since types
+should be immutable.
+
+
+Equality
+--------
+
+.. topic:: ndt_equal
+
+.. code-block:: c
+
+   int ndt_equal(const ndt_t *t, const ndt_t *u);
+
+Return 1 if *t* and *u* are structurally equal, *0* otherwise.
+
+
+Pattern matching
+----------------
+
+.. topic:: ndt_match
+
+.. code-block:: c
+
+   int ndt_match(const ndt_t *p, const ndt_t *c, ndt_context_t *ctx);
+
+Match concrete candidate *c* against the (possibly abstract) pattern *p*.
+
+This is the main function used in type checking.
+
+
+
+Type checking
+-------------
+
+.. topic:: ndt_typecheck
+
+.. code-block:: c
+
+   ndt_t *ndt_typecheck(const ndt_t *f, const ndt_t *args, int *outer_dims, ndt_context_t *ctx);
+
+Take a function type *f*, check if it can accept the concrete type *args*.
+*args* must be a tuple type that contains the individual arguments.
+
+The return value is the inferred return type.
+
+Store the number of outer dimensions that need to be traversed before applying
+the function kernel.
+
+

data/ext/ruby_ndtypes/ndtypes/doc/libndtypes/index.rst

@@ -0,0 +1,43 @@
+.. meta::
+   :robots: index, follow
+   :description: libndtypes documentation
+   :keywords: libndtypes, C, array computing
+
+.. sectionauthor:: Stefan Krah <skrah at bytereef.org>
+
+
+libndtypes
+----------
+
+libndtypes implements the type part of a compiler frontend.  It can describe
+C types needed for array computing and additionally includes symbolic types
+for dynamic type checking.
+
+
+libndtypes has the concept of abstract and concrete types.  Concrete types
+contain the exact data layout and all sizes that are required to access
+subtypes or individual elements in memory.
+
+Abstract types are for type checking and include functions, symbolic
+dimensions and type variables.  Module support is planned at a later stage.
+
+
+Concrete types with rich layout information make it possible to write relatively
+small container libraries that can traverse memory without type erasure.
+
+
+.. toctree::
+
+   init.rst
+   context.rst
+   types.rst
+   predicates.rst
+   functions.rst
+   typedef.rst
+   io.rst
+   encodings.rst
+   fields-values.rst
+   memory.rst
+   util.rst
+
+

data/ext/ruby_ndtypes/ndtypes/doc/libndtypes/init.rst

@@ -0,0 +1,48 @@
+.. meta::
+   :robots: index,follow
+   :description: libndtypes documentation
+
+.. sectionauthor:: Stefan Krah <skrah at bytereef.org>
+
+
+Initialization and tables
+=========================
+
+libndtypes has global tables that need to be initialized and finalized.
+
+
+.. code-block:: c
+
+   int ndt_init(ndt_context_t *ctx);
+
+
+Initialize the global tables.  This function must be called once at program
+start before using any other libndtypes functions.
+
+Return *0* on success and *-1* otherwise.
+
+
+.. code-block:: c
+
+   void ndt_finalize(void);
+
+Deallocate the global tables.  This function may be called once at program
+end for the benefit of memory debuggers.
+
+
+.. code-block:: c
+
+   int ndt_typedef_add(const char *name, const ndt_t *type, ndt_context_t *ctx);
+
+Add a type alias for *type* to the typedef table. *name* must be globally
+unique. The function steals the *type* argument.
+
+On error, deallocate *type* and return *-1*.  Return *0* otherwise.
+
+
+.. code-block:: c
+
+   const ndt_t *ndt_typedef_find(const char *name, ndt_context_t *ctx);
+
+Try to find the type associated with  *name* in the typedef table.  On success,
+return a const pointer to the type, :c:macro:`NULL` otherwise.

data/ext/ruby_ndtypes/ndtypes/doc/libndtypes/io.rst

@@ -0,0 +1,100 @@
+.. meta::
+   :robots: index,follow
+   :description: libndtypes documentation
+
+.. sectionauthor:: Stefan Krah <skrah at bytereef.org>
+
+
+Input/output
+============
+
+Functions for creating and displaying types.
+
+
+Input
+-----
+
+.. topic:: ndt_from_file
+
+.. code-block:: c
+
+   ndt_t *ndt_from_file(const char *name, ndt_context_t *ctx);
+
+Create a type from a file that contains the datashape representation.
+
+
+.. topic:: ndt_from_string
+
+.. code-block:: c
+
+   ndt_t *ndt_from_string(const char *input, ndt_context_t *ctx);
+
+Create a type from a string in datashape syntax. This is the primary function
+for creating types.
+
+
+.. topic:: ndt_from_metadata_and_dtype
+
+.. code-block:: c
+
+   typedef struct {
+     int num_offset_arrays;               /* number of offset arrays */
+     int32_t num_offsets[NDT_MAX_DIM];    /* lengths of the offset arrays */
+     int32_t *offset_arrays[NDT_MAX_DIM]; /* offset arrays */
+   } ndt_meta_t;
+
+   ndt_t *ndt_from_metadata_and_dtype(const ndt_meta_t *m, const char *dtype, ndt_context_t *ctx);
+
+Create a concrete var dimension using the external offset arrays given
+in the :c:macro:`ndt_meta_t` struct.
+
+The application is responsible for keeping the offset arrays alive while the
+type *and all copies of the type* exist.
+
+This is not as difficult as it sounds.  One approach that utilizes a resource
+manager object is implemented in the Python ndtypes module.
+
+
+.. topic:: ndt_from_bpformat
+
+.. code-block:: c
+
+   ndt_t *ndt_from_bpformat(const char *input, ndt_context_t *ctx);
+
+Create a type from a buffer protocol format string (PEP-3118 syntax). This
+is useful for translating dtypes in a `Py_buffer` struct.
+
+The outer dimensions specified by the `Py_buffer` shape member need to
+be created separately.
+
+
+Output
+------
+
+.. topic:: ndt_as_string
+
+.. code-block:: c
+
+   char *ndt_as_string(const ndt_t *t, ndt_context_t *ctx);
+
+Convert *t* to its string representation.  This currently omits some layout
+details like alignment, packing or Fortran layout.
+
+
+.. topic:: ndt_indent
+
+.. code-block:: c
+
+   char *ndt_indent(const ndt_t *t, ndt_context_t *ctx);
+
+Same as :func:`ndt_as_string`, but indent the result.
+
+
+.. topic:: ndt_ast_repr
+
+.. code-block:: c
+
+   char *ndt_ast_repr(const ndt_t *t, ndt_context_t *ctx);
+
+Return the representation of the abstract syntax tree of the input type.
+This representation includes all low level details.