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

Comparing cvsroot/libecb/ecb.pod (file contents):
Revision 1.60 by sf-exg, Wed Feb 11 19:16:12 2015 UTC vs.
Revision 1.64 by root, Wed Feb 18 20:48:59 2015 UTC

 platform (currently C<4> or C<8>) and can be used in preprocessor
 expressions.
 For C<ptrdiff_t> and C<size_t> use C<stddef.h>.
-=head2 LANGUAGE/COMPILER VERSIONS
+=head2 LANGUAGE/ENVIRONMENT/COMPILER VERSIONS
 All the following symbols expand to an expression that can be tested in
 preprocessor instructions as well as treated as a boolean (use C<!!> to
 ensure it's either C<0> or C<1> if you need that).
 C<__x86_64> stands for, well, the x86-64 ABI, making these macros
 necessary.
 =back
+=head2 MACRO TRICKERY
+=over 4
+=item ECB_CONCAT (a, b)
+Expands any macros in C<a> and C<b>, then concatenates the result to form
+a single token. This is mainly useful to form identifiers from components,
+e.g.:
+   #define S1 str
+   #define S2 cpy
+   ECB_CONCAT (S1, S2)(dst, src); // == strcpy (dst, src);
+=item ECB_STRINGIFY (arg)
+Expands any macros in C<arg> and returns the stringified version of
+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
 A major part of libecb deals with additional attributes that can be
 assigned to functions, variables and sometimes even types - much like
 C<const> or C<volatile> in C. They are implemented using either GCC
 Marks a function or a variable as "unused", which simply suppresses a
 warning by GCC when it detects it as unused. This is useful when you e.g.
 declare a variable but do not always use it:
   {
-    int var ecb_unused;
+    ecb_unused int var;
     #ifdef SOMECONDITION
        var = ...;
        return var;
     #else
 =item ecb_deprecated
 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
+used instead of a generic depreciation message when the object is being
+used.
 =item ecb_inline
 Expands either to C<static inline> or to just C<static>, if inline
 isn't supported. It should be used to declare functions that should be
 inlined, for code size or speed reasons.
 Example: multiply a vector, and allow the compiler to parallelise the
 loop, because it knows it doesn't overwrite input values.
    void
-   multiply (float *ecb_restrict src,
+   multiply (ecb_restrict float *src,
-             float *ecb_restrict dst,
+             ecb_restrict float *dst,
              int len, float factor)
    {
      int i;
      for (i = 0; i < len; ++i)
     return is_constant (n) && !(n & (n - 1))
       ? rndm16 () & (num - 1)
       : (n * (uint32_t)rndm16 ()) >> 16;
   }
-=item bool ecb_expect (expr, value)
+=item ecb_expect (expr, value)
 Evaluates C<expr> and returns it. In addition, it tells the compiler that
 the C<expr> evaluates to C<value> a lot, which can be used for static
 branch optimisations.
   {
     if (ecb_expect_false (current + size > end))
       real_reserve_method (size); /* presumably noinline */
   }
-=item bool ecb_assume (cond)
+=item ecb_assume (cond)
 Try to tell the compiler that some condition is true, even if it's not
 obvious.
 This can be used to teach the compiler about invariants or other
 Then the compiler I<might> be able to optimise out the second call
 completely, as it knows that C<< current + 1 > end >> is false and the
 call will never be executed.
-=item bool ecb_unreachable ()
+=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.
-=item bool ecb_prefetch (addr, rw, locality)
+=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
 C<0> means that there will only be one access later, C<3> means that
 the data will likely be accessed very often, and values in between mean
 =head2 FLOATING POINT FIDDLING
 =over 4
+=item ECB_INFINITY
+Evaluates to positive infinity if supported by the platform, otherwise to
+a truly huge number.
+=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)
+Same as C<ldexpf>, but always available.
 =item uint32_t ecb_float_to_binary32  (float  x) [-UECB_NO_LIBM]
 =item uint64_t ecb_double_to_binary64 (double x) [-UECB_NO_LIBM]
 These functions each take an argument in the native C<float> or C<double>

Diff Legend

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

Comparing cvsroot/libecb/ecb.pod (file contents): Revision 1.60 by sf-exg, Wed Feb 11 19:16:12 2015 UTC vs. Revision 1.64 by root, Wed Feb 18 20:48:59 2015 UTC

Diff Legend

Comparing cvsroot/libecb/ecb.pod (file contents):
Revision 1.60 by sf-exg, Wed Feb 11 19:16:12 2015 UTC vs.
Revision 1.64 by root, Wed Feb 18 20:48:59 2015 UTC