*** empty log message ***

src/BTrees/Maintainer.txt

+This document provides information for developers who maintain or
+extend BTrees.
+
+BTrees are defined using a "template", roughly akin to a a C++
+template. To create a new family of BTrees, create a source file that
+defined macros used to handle differences in key and value types:
+
+  MASTER_ID provides a string to hold an RCS/CVS Id key to be included
+  in compiled binaries.
+
+  MOD_NAME_PREFIX provides the prefix used for the module. This gets
+  used to generate type names and the internal module name string.
+
+  DEFAULT_MAX_BUCKET_SIZE The maximum bucket size. Someday this will
+  be tunable on BTree instances.
+
+  DEFAULT_MAX_BTREE_SIZE The maximum btree size (number of
+  children). Someday this will be tunable on BTree instances.
+
+  KEY_TYPE The C type declaration for the key data (e.g. "int",
+  "PyObject *").
+
+  KEY_CHECK(K) Macro that tests whether a Python Object, K, can be
+  converted to the (C) key type (KEY_TYPE). This macro should return a
+  bollean. An exception will generally be raised if this returns false.
+
+  TEST_KEY(K, T) Compares (ala Python cmp) K & T, where K & T are C
+  data values (of type KEY_TYPE). Returns -1 for K < T, 0 for K == T,
+  or -1 if K > T.
+
+  DECREF_KEY(K) DECREFs the key of KEY_TYPE is PyObject* or is a no
+  op.
+
+  INCREF_KEY(K)  DECREFs the key of KEY_TYPE is PyObject* or is a no
+  op.
+  
+  COPY_KEY(K, E) Copy a key's value from E to K.  Note that this
+  doesn't INCREF when KEY_TYPE is PyObject*.
+
+  COPY_KEY_TO_OBJECT(O, K) Sets the PyObject* O to a PyObject*
+  representation of K. Note that this is a new reference, so we INCREF
+  when KEY_TYPE is PyObject*.
+
+  COPY_KEY_FROM_ARG(TARGET, ARG, STATUS) Copy an rgument to the target
+  without creating a new reference to ARG. If this can't be done, set
+  a Python error and set status to 0. If there is no error, status is
+  unchanged. 
+
+
+
+  VALUE_TYPE The C type declaration for the value data (e.g. "int",
+  "PyObject *").
+
+  TEST_VALUE(K, T) Compares (ala Python cmp) K & T, where K & T are C
+  data values (of type VALUE_TYPE). Returns -1 for K < T, 0 for K == T,
+  or -1 if K > T.
+
+  DECREF_VALUE(K) DECREFs the value of VALUE_TYPE is PyObject* or is a no
+  op.
+
+  INCREF_VALUE(K)  DECREFs the value of VALUE_TYPE is PyObject* or is a no
+  op.
+  
+  COPY_VALUE(K, E) Copy a value's value from E to K.  Note that this
+  doesn't INCREF when VALUE_TYPE is PyObject*.
+
+  COPY_VALUE_TO_OBJECT(O, K) Sets the PyObject* O to a PyObject*
+  representation of K. Note that this is a new reference, so we INCREF
+  when VALUE_TYPE is PyObject*.
+
+  COPY_VALUE_FROM_ARG(TARGET, ARG, STATUS) Copy an rgument to the target
+  without creating a new reference to ARG. If this can't be done, set
+  a Python error and set status to 0. If there is no error, status is
+  unchanged. 
+
+  NORMALIZE_VALUE(V, MIN) Normalize the value, V, using the parameter
+  MIN. This almost vertainly a YAGNI. It is a no op for most
+  types. For integers, V is replaced by V/MIN only if MIN > 0.
+
+  MERGE_DEFAULT is a macro that should be set to the default value for
+  sets when sets are are merged with mappings via weighed union or
+  intersection.  
+  
+  MERGE(O1, w1, O2, w2) This macro performs a weighted merge of two
+  values, O1 and O2 using weights w1 and w2. Note that weighted unions
+  and intersections are not enabled if this macro is undefined.
+
+  MERGE_WEIGHT(O, w) Computes a weighted value for O. This is used for
+  "filling out" weighted unions.