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

Comparing cvsroot/libecb/ecb.pod (file contents):
Revision 1.61 by sf-exg, Thu Feb 12 12:37:33 2015 UTC vs.
Revision 1.70 by root, Tue Sep 1 16:14:42 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).
 The designers of the new X32 ABI for some inexplicable reason decided to
 make it look exactly like amd64, even though it's completely incompatible
 to that ABI, breaking about every piece of software that assumed 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
 =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, the specified diagnostic 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.
      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
     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
+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.
 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.
+function can be used to implement C<ecb_assume> or similar functionality.
-=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
 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)
 =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>
 =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.61 by sf-exg, Thu Feb 12 12:37:33 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.61 by sf-exg, Thu Feb 12 12:37:33 2015 UTC vs.
Revision 1.70 by root, Tue Sep 1 16:14:42 2015 UTC