[ViewVC] Diff of: cvs/cvsroot/libecb/ecb.pod

Comparing cvsroot/libecb/ecb.pod (file contents):
Revision 1.62 by root, Wed Feb 18 20:29:27 2015 UTC vs.
Revision 1.70 by root, Tue Sep 1 16:14:42 2015 UTC

 it. This is mainly useful to get the contents of a macro in string form,
 e.g.:
    #define SQL_LIMIT 100
    sql_exec ("select * from table limit " ECB_STRINGIFY (SQL_LIMIT));
+=item ECB_STRINGIFY_EXPR (expr)
+Like C<ECB_STRINGIFY>, but additionally evaluates C<expr> to make sure it
+is a valid expression. This is useful to catch typos or cases where the
+macro isn't available:
+   #include <errno.h>
+   ECB_STRINGIFY      (EDOM); // "33" (on my system at least)
+   ECB_STRINGIFY_EXPR (EDOM); // "33"
+   // now imagine we had a typo:
+   ECB_STRINGIFY      (EDAM); // "EDAM"
+   ECB_STRINGIFY_EXPR (EDAM); // error: EDAM undefined
 =back
 =head2 ATTRIBUTES
 Similar to C<ecb_unused>, but marks a function, variable or type as
 deprecated. This makes some compilers warn when the type is used.
 =item ecb_deprecated_message (message)
-Same as C<ecb_deprecated>, but if possible, supply a diagnostic that is
+Same as C<ecb_deprecated>, but if possible, the specified diagnostic is
 used instead of a generic depreciation message when the object is being
 used.
 =item ecb_inline
      return - (a * b);
    }
 =item ecb_noinline
-Prevent a function from being inlined - it might be optimised away, but
+Prevents a function from being inlined - it might be optimised away, but
 not inlined into other functions. This is useful if you know your function
 is rarely called and large enough for inlining not to be helpful.
 =item ecb_noreturn
       real_reserve_method (size); /* presumably noinline */
   }
 =item ecb_assume (cond)
-Try to tell the compiler that some condition is true, even if it's not
+Tries to tell the compiler that some condition is true, even if it's not
-obvious.
+obvious. This is not a function, but a statement: it cannot be used in
+another expression.
 This can be used to teach the compiler about invariants or other
 conditions that might improve code generation, but which are impossible to
 deduce form the code itself.
 =item ecb_unreachable ()
 This function does nothing itself, except tell the compiler that it will
 never be executed. Apart from suppressing a warning in some cases, this
-function can be used to implement C<ecb_assume> or similar functions.
+function can be used to implement C<ecb_assume> or similar functionality.
 =item ecb_prefetch (addr, rw, locality)
 Tells the compiler to try to prefetch memory at the given C<addr>ess
 for either reading (C<rw> = 0) or writing (C<rw> = 1). A C<locality> of
 the data will likely be accessed very often, and values in between mean
 something... in between. The memory pointed to by the address does not
 need to be accessible (it could be a null pointer for example), but C<rw>
 and C<locality> must be compile-time constants.
+This is a statement, not a function: you cannot use it as part of an
+expression.
 An obvious way to use this is to prefetch some data far away, in a big
 array you loop over. This prefetches memory some 128 array elements later,
 in the hope that it will be ready when the CPU arrives at that location.
   int sum = 0;
 =item bool ecb_is_pot32 (uint32_t x)
 =item bool ecb_is_pot64 (uint32_t x)
-Return true iff C<x> is a power of two or C<x == 0>.
+Returns true iff C<x> is a power of two or C<x == 0>.
-For smaller types then C<uint32_t> you can safely use C<ecb_is_pot32>.
+For smaller types than C<uint32_t> you can safely use C<ecb_is_pot32>.
 =item int ecb_ld32 (uint32_t x)
 =item int ecb_ld64 (uint64_t x)
 =item ECB_INFINITY
 Evaluates to positive infinity if supported by the platform, otherwise to
 a truly huge number.
-=item ECB_NON
+=item ECB_NAN
 Evaluates to a quiet NAN if supported by the platform, otherwise to
 C<ECB_INFINITY>.
 =item float ecb_ldexpf (float x, int exp)
 =item float  ecb_binary16_to_float  (uint16_t x) [-UECB_NO_LIBM]
 =item float  ecb_binary32_to_float  (uint32_t x) [-UECB_NO_LIBM]
-=item double ecb_binary32_to_double (uint64_t x) [-UECB_NO_LIBM]
+=item double ecb_binary64_to_double (uint64_t x) [-UECB_NO_LIBM]
 The reverse operation of the previous function - takes the bit
 representation of an IEEE binary16, binary32 or binary64 number and
 converts it to the native C<float> or C<double> format.
 dependencies on the math library (usually called F<-lm>) - these are
 marked with [-UECB_NO_LIBM].
 =back
+=head1 UNDOCUMENTED FUNCTIONALITY
+F<ecb.h> is full of undocumented functionality as well, some of which is
+intended to be internal-use only, some of which we forgot to document, and
+some of which we hide because we are not sure we will keep the interface
+stable.
+While you are welcome to rummage around and use whatever you find useful
+(we can't stop you), keep in mind that we will change undocumented
+functionality in incompatible ways without thinking twice, while we are
+considerably more conservative with documented things.
+=head1 AUTHORS
+C<libecb> is designed and maintained by:
+   Emanuele Giaquinta <e.giaquinta@glauco.it>
+   Marc Alexander Lehmann <schmorp@schmorp.de>

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing cvsroot/libecb/ecb.pod (file contents): Revision 1.62 by root, Wed Feb 18 20:29:27 2015 UTC vs. Revision 1.70 by root, Tue Sep 1 16:14:42 2015 UTC

Diff Legend

Comparing cvsroot/libecb/ecb.pod (file contents):
Revision 1.62 by root, Wed Feb 18 20:29:27 2015 UTC vs.
Revision 1.70 by root, Tue Sep 1 16:14:42 2015 UTC