[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.75 by root, Sat Dec 28 08:01:05 2019 UTC

 The macro C<ECB_PTRSIZE> is defined to the size of a pointer on this
 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>.
+For C<ptrdiff_t> and C<size_t> use C<stddef.h>/C<cstddef>.
 =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
 9899:1999) or any later version, while not claiming to be C++.
 Note that later versions (ECB_C11) remove core features again (for
 example, variable length arrays).
-=item ECB_C11
+=item ECB_C11, ECB_C17
-True if the implementation claims to be compliant to C11 (ISO/IEC
+True if the implementation claims to be compliant to C11/C17 (ISO/IEC
-9899:2011) or any later version, while not claiming to be C++.
+9899:2011, :20187) or any later version, while not claiming to be C++.
 =item ECB_CPP
 True if the implementation defines the C<__cplusplus__> macro to a true
 value, which is typically true for C++ compilers.
-=item ECB_CPP11
+=item ECB_CPP11, ECB_CPP14, ECB_CPP17
-True if the implementation claims to be compliant to ISO/IEC 14882:2011
+True if the implementation claims to be compliant to C++11/C++14/C++17
-(C++11) or any later version.
+(ISO/IEC 14882:2011, :2014, :2017) or any later version.
 =item ECB_GCC_VERSION (major, minor)
 Expands to a true value (suitable for testing in by the preprocessor)
 if the compiler used is GNU C and the version is the given version, or
 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
-Expands either to C<static inline> or to just C<static>, if inline
+Expands either to (a compiler-specific equivalent of) C<static inline> or
-isn't supported. It should be used to declare functions that should be
+to just C<static>, if inline isn't supported. It should be used to declare
-inlined, for code size or speed reasons.
+functions that should be inlined, for code size or speed reasons.
 Example: inline this function, it surely will reduce codesize.
    ecb_inline int
    negmul (int a, int b)
      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
 =back
 =head2 OPTIMISATION HINTS
 =over 4
+=item ECB_OPTIMIZE_SIZE
+Is C<1> when the compiler optimizes for size, C<0> otherwise. This symbol
+can also be defined before including F<ecb.h>, in which case it will be
+unchanged.
 =item bool ecb_is_constant (expr)
 Returns true iff the expression can be deduced to be a compile-time
 constant, and false otherwise.
       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)
 =head2 FLOATING POINT FIDDLING
 =over 4
-=item ECB_INFINITY
+=item ECB_INFINITY [-UECB_NO_LIBM]
 Evaluates to positive infinity if supported by the platform, otherwise to
 a truly huge number.
-=item ECB_NON
+=item ECB_NAN [-UECB_NO_LIBM]
 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_ldexpf (float x, int exp) [-UECB_NO_LIBM]
 Same as C<ldexpf>, but always available.
+=item uint32_t ecb_float_to_binary16  (float  x) [-UECB_NO_LIBM]
 =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>
-type and return the IEEE 754 bit representation of it.
+type and return the IEEE 754 bit representation of it (binary16/half,
+binary32/single or binary64/double precision).
 The bit representation is just as IEEE 754 defines it, i.e. the sign bit
 will be the most significant bit, followed by exponent and mantissa.
 This function should work even when the native floating point format isn't
 On all modern platforms (where C<ECB_STDFP> is true), the compiler should
 be able to optimise away this function completely.
 These functions can be helpful when serialising floats to the network - you
-can serialise the return value like a normal uint32_t/uint64_t.
+can serialise the return value like a normal uint16_t/uint32_t/uint64_t.
 Another use for these functions is to manipulate floating point values
 directly.
 Silly example: toggle the sign bit of a float.
 =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
+representation of an IEEE binary16, binary32 or binary64 number (half,
-converts it to the native C<float> or C<double> format.
+single or double precision) and converts it to the native C<float> or
+C<double> format.
 This function should work even when the native floating point format isn't
 IEEE compliant, of course at a speed and code size penalty, and of course
 also within reasonable limits (it tries to convert normals and denormals,
 and might be lucky for infinities, and with extraordinary luck, also for
 negative zero).
 On all modern platforms (where C<ECB_STDFP> is true), the compiler should
 be able to optimise away this function completely.
+=item uint16_t ecb_binary32_to_binary16 (uint32_t x)
+=item uint32_t ecb_binary16_to_binary32 (uint16_t x)
+Convert a IEEE binary32/single precision to binary16/half format, and vice
+versa, handling all details (round-to-nearest-even, subnormals, infinity
+and NaNs) correctly.
+These are functions are available under C<-DECB_NO_LIBM>, since
+they do not rely on the platform floating point format. The
+C<ecb_float_to_binary16> and C<ecb_binary16_to_float> functions are
+usually what you want.
 =back
 =head2 ARITHMETIC
 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.75 by root, Sat Dec 28 08:01:05 2019 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.75 by root, Sat Dec 28 08:01:05 2019 UTC