mediasoup-client-android-moudle.rar

# `base/numerics` This directory contains a dependency-free, header-only library of templates providing well-defined semantics for safely and performantly handling a variety of numeric operations, including most common arithmetic operations and conversions. The public API is broken out into the following header files: * `checked_math.h` contains the `CheckedNumeric` template class and helper functions for performing arithmetic and conversion operations that detect errors and boundary conditions (e.g. overflow, truncation, etc.). * `clamped_math.h` contains the `ClampedNumeric` template class and helper functions for performing fast, clamped (i.e. [non-sticky](#notsticky) saturating) arithmetic operations and conversions. * `safe_conversions.h` contains the `StrictNumeric` template class and a collection of custom casting templates and helper functions for safely converting between a range of numeric types. * `safe_math.h` includes all of the previously mentioned headers. *** aside **Note:** The `Numeric` template types implicitly convert from C numeric types and `Numeric` templates that are convertable to an underlying C numeric type. The conversion priority for `Numeric` type coercions is: * `StrictNumeric` coerces to `ClampedNumeric` and `CheckedNumeric` * `ClampedNumeric` coerces to `CheckedNumeric` *** [TOC] ## Common patterns and use-cases The following covers the preferred style for the most common uses of this library. Please don't cargo-cult from anywhere else. 😉 ### Performing checked arithmetic type conversions The `checked_cast` template converts between arbitrary arithmetic types, and is used for cases where a conversion failure should result in program termination: ```cpp // Crash if signed_value is out of range for buff_size. size_t buff_size = checked_cast<size_t>(signed_value); ``` ### Performing saturated (clamped) arithmetic type conversions The `saturated_cast` template converts between arbitrary arithmetic types, and is used in cases where an out-of-bounds source value should be saturated to the corresponding maximum or minimum of the destination type: ```cpp // Convert from float with saturation to INT_MAX, INT_MIN, or 0 for NaN. int int_value = saturated_cast<int>(floating_point_value); ``` ### Enforcing arithmetic type conversions at compile-time The `strict_cast` emits code that is identical to `static_cast`. However, provides static checks that will cause a compilation failure if the destination type cannot represent the full range of the source type: ```cpp // Throw a compiler error if byte_value is changed to an out-of-range-type. int int_value = strict_cast<int>(byte_value); ``` You can also enforce these compile-time restrictions on function parameters by using the `StrictNumeric` template: ```cpp // Throw a compiler error if the size argument cannot be represented by a // size_t (e.g. passing an int will fail to compile). bool AllocateBuffer(void** buffer, StrictCast<size_t> size); ``` ### Comparing values between arbitrary arithmetic types Both the `StrictNumeric` and `ClampedNumeric` types provide well defined comparisons between arbitrary arithmetic types. This allows you to perform comparisons that are not legal or would trigger compiler warnings or errors under the normal arithmetic promotion rules: ```cpp bool foo(unsigned value, int upper_bound) { // Converting to StrictNumeric allows this comparison to work correctly. if (MakeStrictNum(value) >= upper_bound) return false; ``` *** note **Warning:** Do not perform manual conversions using the comparison operators. Instead, use the cast templates described in the previous sections, or the constexpr template functions `IsValueInRangeForNumericType` and `IsTypeInRangeForNumericType`, as these templates properly handle the full range of corner cases and employ various optimizations. *** ### Calculating a buffer size (checked arithmetic) When making exact calculations—such as for buffer lengths—it's often necessary to know when those calculations trigger an overflow, undefined behavior, or other boundary conditions. The `CheckedNumeric` template does this by storing a bit determining whether or not some arithmetic operation has occured that would put the variable in an "invalid" state. Attempting to extract the value from a variable in an invalid state will trigger a check/trap condition, that by default will result in process termination. Here's an example of a buffer calculation using a `CheckedNumeric` type (note: the AssignIfValid method will trigger a compile error if the result is ignored). ```cpp // Calculate the buffer size and detect if an overflow occurs. size_t size; if (!CheckAdd(kHeaderSize, CheckMul(count, kItemSize)).AssignIfValid(&size)) { // Handle an overflow error... } ``` ### Calculating clamped coordinates (non-sticky saturating arithmetic) Certain classes of calculations—such as coordinate calculations—require well-defined semantics that always produce a valid result on boundary conditions. The `ClampedNumeric` template addresses this by providing performant, non-sticky saturating arithmetic operations. Here's an example of using a `ClampedNumeric` to calculate an operation insetting a rectangle. ```cpp // Use clamped arithmetic since inset calculations might overflow. void Rect::Inset(int left, int top, int right, int bottom) { origin_ += Vector2d(left, top); set_width(ClampSub(width(), ClampAdd(left, right))); set_height(ClampSub(height(), ClampAdd(top, bottom))); } ``` *** note <a name="notsticky"></a> The `ClampedNumeric` type is not "sticky", which means the saturation is not retained across individual operations. As such, one arithmetic operation may result in a saturated value, while the next operation may then "desaturate" the value. Here's an example: ```cpp ClampedNumeric<int> value = INT_MAX; ++value; // value is still INT_MAX, due to saturation. --value; // value is now (INT_MAX - 1), because saturation is not sticky. ``` *** ## Conversion functions and StrictNumeric<> in safe_conversions.h This header includes a collection of helper `constexpr` templates for safely performing a range of conversions, assignments, and tests. ### Safe casting templates * `as_signed()` - Returns the supplied integral value as a signed type of the same width. * `as_unsigned()` - Returns the supplied integral value as an unsigned type of the same width. * `checked_cast<>()` - Analogous to `static_cast<>` for numeric types, except that by default it will trigger a crash on an out-of-bounds conversion (e.g. overflow, underflow, NaN to integral) or a compile error if the conversion error can be detected at compile time. The crash handler can be overridden to perform a behavior other than crashing. * `saturated_cast<>()` - Analogous to `static_cast` for numeric types, except that it returns a saturated result when the specified numeric conversion would otherwise overflow or underflow. An NaN source returns 0 by default, but can be overridden to return a different result. * `strict_cast<>()` - Analogous to `static_cast` for numeric types, except this causes a compile failure if the destination type is not large enough to contain any value in the source type. It performs no runtime checking and thus introduces no runtime overhead. ### Other helper and conversion functions * `IsValueInRangeForNumericType<>()` - A convenience function that returns true if the type supplied as the template parameter can represent the value passed as an argument to the function. * `IsTypeInRangeForNumericType<>()` - A convenience function that evaluates entirely at compile-time and returns true if the destination type (first template parameter) can represent the full range of the source type (second template parameter). * `IsValueNegative()` - A convenience function that will accept any arithme