Add example for Smart Contract API print and math

contracts/eoslib/math.h

@@ -16,6 +16,14 @@ extern "C" {
   * @brief Multiply two 128 unsigned bit integers
   * @param self  Value to be multiplied. It will be replaced with the result.
   * @param other Value to be multiplied.
+  *
+  * Example:
+  * @code
+  * uint128_t self(100);
+  * uint128_t other(100);
+  * multeq_i128(self, other);
+  * printi128(self); // Output: 10000
+  * @endcode
   */
   void multeq_i128( uint128_t* self, const uint128_t* other );
   /**
@@ -24,6 +32,13 @@ extern "C" {
    * @brief Divide two 128 unsigned bit integers
    * @param self  Numerator. It will be replaced with the result
    * @param other Denominator
+   * Example:
+   * @code
+   * uint128_t self(100);
+   * uint128_t other(100);
+   * diveq_i128(self, other);
+   * printi128(self); // Output: 1
+   * @endcode
    */
   void diveq_i128 ( uint128_t* self, const uint128_t* other );
 
@@ -34,6 +49,14 @@ extern "C" {
    * @param a Value in double interpreted as 64 bit unsigned integer
    * @param b Value in double interpreted as 64 bit unsigned integer
    * @return Result of addition reinterpret_cast to 64 bit unsigned integers
+   *
+   * Example:
+   * @code
+   * uint64_t a = double_div( i64_to_double(5), i64_to_double(10) );
+   * uint64_t b = double_div( i64_to_double(5), i64_to_double(2) );
+   * uint64_t res = double_add( a, b );
+   * printd(res); // Output: 3
+   * @endcode
    */
   uint64_t double_add(uint64_t a, uint64_t b);
 
@@ -44,6 +67,14 @@ extern "C" {
    * @param a Value in double interpreted as 64 bit unsigned integer
    * @param b Value in double interpreted as 64 bit unsigned integer
    * @return Result of multiplication reinterpret_cast to 64 bit unsigned integers
+   *
+   * Example:
+   * @code
+   * uint64_t a = double_div( i64_to_double(10), i64_to_double(10) );
+   * uint64_t b = double_div( i64_to_double(5), i64_to_double(2) );
+   * uint64_t res = double_mult( a, b );
+   * printd(res); // Output: 2.5
+   * @endcode
    */
   uint64_t double_mult(uint64_t a, uint64_t b);
 
@@ -55,6 +86,12 @@ extern "C" {
    * @param a Numerator in double interpreted as 64 bit unsigned integer
    * @param b Denominator in double interpreted as 64 bit unsigned integer
    * @return Result of division reinterpret_cast to 64 bit unsigned integers
+   *
+   * Example:
+   * @code
+   * uint64_t a = double_div( i64_to_double(10), i64_to_double(100) );
+   * printd(a); // Output: 0.1
+   * @endcode
    */
   uint64_t double_div(uint64_t a, uint64_t b);
 
@@ -65,6 +102,14 @@ extern "C" {
    * @param a Value in double interpreted as 64 bit unsigned integer
    * @param b Value in double interpreted as 64 bit unsigned integer
    * @return 1 if first input is smaller than second input, 0 otherwise
+   *
+   * Example:
+   * @code
+   * uint64_t a = double_div( i64_to_double(10), i64_to_double(10) );
+   * uint64_t b = double_div( i64_to_double(5), i64_to_double(2) );
+   * uint64_t res = double_lt( a, b );
+   * printi(res); // Output: 1
+   * @endcode
    */
   uint32_t double_lt(uint64_t a, uint64_t b);
 
@@ -75,6 +120,14 @@ extern "C" {
    * @param a Value in double interpreted as 64 bit unsigned integer
    * @param b Value in double interpreted as 64 bit unsigned integer
    * @return 1 if first input is equal to second input, 0 otherwise
+   *
+   *  Example:
+   * @code
+   * uint64_t a = double_div( i64_to_double(10), i64_to_double(10) );
+   * uint64_t b = double_div( i64_to_double(5), i64_to_double(2) );
+   * uint64_t res = double_eq( a, b );
+   * printi(res); // Output: 0
+   * @endcode
    */
   uint32_t double_eq(uint64_t a, uint64_t b);
 
@@ -85,6 +138,14 @@ extern "C" {
    * @param a Value in double interpreted as 64 bit unsigned integer
    * @param b Value in double interpreted as 64 bit unsigned integer
    * @return 1 if first input is greater than second input, 0 otherwise
+   *
+   * Example:
+   * @code
+   * uint64_t a = double_div( i64_to_double(10), i64_to_double(10) );
+   * uint64_t b = double_div( i64_to_double(5), i64_to_double(2) );
+   * uint64_t res = double_gt( a, b );
+   * printi(res); // Output: 0
+   * @endcode
    */
   uint32_t double_gt(uint64_t a, uint64_t b);
 
@@ -94,6 +155,13 @@ extern "C" {
    * @brief Convert double to 64 bit unsigned integer
    * @param self Value in double interpreted as 64 bit unsigned integer
    * @return Result of conversion in 64 bit unsigned integer
+   *
+   * Example:
+   * @code
+   * uint64_t a = double_div( i64_to_double(5), i64_to_double(2) );
+   * uint64_t res = double_to_i64( a );
+   * printi(res); // Output: 2
+   * @endcode
    */
   uint64_t double_to_i64(uint64_t a);
 
@@ -103,6 +171,12 @@ extern "C" {
    * @brief Convert 64 bit unsigned integer to double (interpreted as 64 bit unsigned  integer)
    * @param self Value to be converted
    * @return Result of conversion in double (interpreted as 64 bit unsigned integer)
+   *
+   * Example:
+   * @code
+   * uint64_t res = i64_to_double( 3 );
+   * printd(res); // Output: 3
+   * @endcode
    */
   uint64_t i64_to_double(uint64_t a);
 

contracts/eoslib/math.hpp

@@ -5,7 +5,7 @@ namespace eos {
 
   /**
    *  @defgroup mathapi Math API
-   *  @brief Defines common math functions 
+   *  @brief Defines common math functions
    *  @ingroup contractdev
    */
 
@@ -23,6 +23,14 @@ namespace eos {
    * @brief wraps multeq_i128 from @ref mathcapi
    * @param self  Value to be multiplied. It will be replaced with the result
    * @param other Value integer to be multiplied.
+   *
+   * Example:
+   * @code
+   * uint128_t self(100);
+   * uint128_t other(100);
+   * multeq(self, other);
+   * std::cout << self; // Output: 10000
+   * @endcode
    */
   inline void multeq( uint128_t& self, const uint128_t& other ) {
      multeq_i128( &self, &other );
@@ -35,6 +43,14 @@ namespace eos {
    * @brief wraps diveq_i128 from @ref mathcapi
    * @param self  Numerator. It will be replaced with the result
    * @param other Denominator
+   *
+   * Example:
+   * @code
+   * uint128_t self(100);
+   * uint128_t other(100);
+   * diveq(self, other);
+   * std::cout << self; // Output: 1
+   * @endcode
    */
   inline void diveq( uint128_t& self, const uint128_t& other ) {
      diveq_i128( &self, &other );
@@ -63,20 +79,20 @@ namespace eos {
             return a.value >= b.value;
         }
 
-        uint128& operator *= ( const uint128_t& other ) { 
+        uint128& operator *= ( const uint128_t& other ) {
            multeq( value, other );
            return *this;
         }
-        uint128& operator *= ( const uint128& other ) { 
+        uint128& operator *= ( const uint128& other ) {
            multeq( value, other.value );
            return *this;
         }
 
-        uint128& operator /= ( const uint128_t& other ) { 
+        uint128& operator /= ( const uint128_t& other ) {
            diveq( value, other );
            return *this;
         }
-        uint128& operator /= ( const uint128& other ) { 
+        uint128& operator /= ( const uint128& other ) {
            diveq( value, other.value );
            return *this;
         }
@@ -96,6 +112,13 @@ namespace eos {
     * @param a  Value to compare
     * @param b  Value to compare
     * @return The smaller of a and b. If they are equivalent, returns a
+    *
+    * Example:
+    * @code
+    * uint128_t a(1);
+    * uint128_t b(2);
+    * std::cout << min(a, b); // Output: 1
+    * @endcode
     */
    template<typename T>
    T min( const T& a, const T&b ) {
@@ -103,11 +126,18 @@ namespace eos {
    }
 
    /**
-    * Get the smaller of the given values.
+    * Get the greater of the given values.
     * @brief Define similar to std::max()
     * @param a  Value to compare
     * @param b  Value to compare
     * @return The greater of a and b. If they are equivalent, returns a
+    *
+    * Example:
+    * @code
+    * uint128_t a(1);
+    * uint128_t b(2);
+    * std::cout << max(a, b); // Output: 2
+    * @endcode
    */
    template<typename T>
    T max( const T& a, const T&b ) {

contracts/eoslib/print.h

@@ -19,6 +19,11 @@ extern "C" {
     *  Prints string
     *  @brief Prints string
     *  @param cstr - a null terminated string
+    *
+    *  Example:
+    *  @code
+    *  prints("Hello World!"); // Output: Hello World!
+    *  @endcode
     */
    void prints( const char* cstr );
 
@@ -26,6 +31,11 @@ extern "C" {
     * Prints value as a 64 bit unsigned integer
     * @brief Prints value as a 64 bit unsigned integer
     * @param Value of 64 bit unsigned integer to be printed
+    *
+    *  Example:
+    *  @code
+    *  printi(1e+18); // Output: 1000000000000000000
+    *  @endcode
     */
    void printi( uint64_t value );
 
@@ -33,6 +43,12 @@ extern "C" {
     * Prints value as a 128 bit unsigned integer
     * @brief Prints value as a 128 bit unsigned integer
     * @param value 128 bit integer to be printed
+    *
+    *  Example:
+    *  @code
+    *  uint128_t large_int(87654323456);
+    *  printi128(large_int); // Output: 87654323456
+    *  @endcode
     */
    void printi128( const uint128_t* value );
 
@@ -40,6 +56,12 @@ extern "C" {
     * Prints value as double
     * @brief Prints value as double
     * @param Value of double (interpreted as 64 bit unsigned integer) to be printed
+    *
+    *  Example:
+    *  @code
+    *  uint64_t double_value = double_div( i64_to_double(5), i64_to_double(10) );
+    *  printd(double_value); // Output: 0.5
+    *  @endcode
     */
    void printd(uint64_t value);
 
@@ -47,6 +69,11 @@ extern "C" {
     * Prints a 64 bit names as base32 encoded string
     * @brief Prints a 64 bit names as base32 encoded string
     * @param Value of 64 bit names to be printed
+    *
+    * Example:
+    * @code
+    * printn(N(abcde)); // Output: abcde
+    * @endcode
     */
    void printn( uint64_t name );
    /// @}

contracts/eoslib/print.hpp

@@ -109,10 +109,20 @@ namespace eos {
     */
 
     /**
-     *  Print out value / list of values
+     *  Print out value / list of values (except double)
      *  @brief Print out value  / list of values
      *  @param a    Value to be printed
      *  @param args Other values to be printed
+     *
+     *  Example:
+     *  @code
+     *  char *s = "Hello World!";
+     *  uint64_t unsigned_64_bit_int = 1e+18;
+     *  uint128_t unsigned_128_bit_int (87654323456);
+     *  uint64_t string_as_unsigned_64_bit = N(abcde);
+     *  print(s , unsigned_64_bit_int, unsigned_128_bit_int, string_as_unsigned_64_bit);
+     *  // Ouput: Hello World!100000000000000000087654323456abcde
+     *  @endcode
      */
    template<typename Arg, typename... Args>
    void print( Arg a, Args... args ) {
@@ -130,6 +140,16 @@ namespace eos {
     *  @brief Overload c++ iostream
     *  @param out  Output strem
     *  @param v    Value to be printed
+    *
+    *  Example:
+    *  @code
+    *  char *s = "Hello World!";
+    *  uint64_t unsigned_64_bit_int = 1e+18;
+    *  uint128_t unsigned_128_bit_int (87654323456);
+    *  uint64_t string_as_unsigned_64_bit = N(abcde);
+    *  std::out << s << " " << unsigned_64_bit_int << " "  << unsigned_128_bit_int << " " << string_as_unsigned_64_bit);
+    *  // Ouput: Hello World! 1000000000000000000 87654323456 abcde
+    *  @endcode
     */
    template<typename T>
    inline iostream& operator<<( iostream& out, const T& v ) {