diff --git a/config/redirects b/config/redirects index b8c7cd290cd..6fb667595f0 100644 --- a/config/redirects +++ b/config/redirects @@ -1454,6 +1454,9 @@ raw: /master/release-notes/3.0-general-improvements -> ${base}/release-notes/3.0 [*-v4.0]: /${version}/reference/operator/aggregation/asinh -> ${base}/${version}/reference/operator/aggregation [*-v4.0]: /${version}/reference/operator/aggregation/acosh -> ${base}/${version}/reference/operator/aggregation [*-v4.0]: /${version}/reference/operator/aggregation/atanh -> ${base}/${version}/reference/operator/aggregation +[*-v4.0]: /${version}/reference/operator/aggregation/sinh -> ${base}/${version}/reference/operator/aggregation +[*-v4.0]: /${version}/reference/operator/aggregation/cosh -> ${base}/${version}/reference/operator/aggregation +[*-v4.0]: /${version}/reference/operator/aggregation/tanh -> ${base}/${version}/reference/operator/aggregation [*-v4.0]: /${version}/reference/operator/aggregation/degreesToRadians -> ${base}/${version}/reference/operator/aggregation [*-v4.0]: /${version}/reference/operator/aggregation/radiansToDegrees -> ${base}/${version}/reference/operator/aggregation @@ -1664,6 +1667,9 @@ raw: /v2.8/release-notes/2.8-changes -> ${base}/v3.0/release-notes/3.0 [v3.0-v4.0]: /${version}/reference/operator/aggregation/asinh -> ${base}/${version}/reference/operator/aggregation [v3.0-v4.0]: /${version}/reference/operator/aggregation/acosh -> ${base}/${version}/reference/operator/aggregation [v3.0-v4.0]: /${version}/reference/operator/aggregation/atanh -> ${base}/${version}/reference/operator/aggregation +[v3.0-v4.0]: /${version}/reference/operator/aggregation/sinh -> ${base}/${version}/reference/operator/aggregation +[v3.0-v4.0]: /${version}/reference/operator/aggregation/cosh -> ${base}/${version}/reference/operator/aggregation +[v3.0-v4.0]: /${version}/reference/operator/aggregation/tanh -> ${base}/${version}/reference/operator/aggregation [v3.0-v4.0]: /${version}/reference/operator/aggregation/degreesToRadians -> ${base}/${version}/reference/operator/aggregation [v3.0-v4.0]: /${version}/reference/operator/aggregation/radiansToDegrees -> ${base}/${version}/reference/operator/aggregation diff --git a/source/includes/extracts-agg-operators.yaml b/source/includes/extracts-agg-operators.yaml index ae7101d16b1..b4531152ea8 100644 --- a/source/includes/extracts-agg-operators.yaml +++ b/source/includes/extracts-agg-operators.yaml @@ -46,6 +46,18 @@ content: | - Returns the inverse hyperbolic tangent (hyperbolic arc tangent) of a value in radians. + * - :expression:`$sinh` + - Returns the hyperbolic sine of a value that is measured in + radians. + + * - :expression:`$cosh` + - Returns the hyperbolic cosine of a value that is measured in + radians. + + * - :expression:`$tanh` + - Returns the hyperbolic tangent of a value that is measured in + radians. + * - :expression:`$degreesToRadians` - Converts a value from degrees to radians. diff --git a/source/meta/aggregation-quick-reference.txt b/source/meta/aggregation-quick-reference.txt index 21e795f2958..dbd20acad67 100644 --- a/source/meta/aggregation-quick-reference.txt +++ b/source/meta/aggregation-quick-reference.txt @@ -361,6 +361,7 @@ Index of Expression Operators - :expression:`$cond` - :expression:`$convert` - :expression:`$cos` + - :expression:`$cosh` - :expression:`$dateFromParts` - :expression:`$dateFromString` - :expression:`$dateToParts` @@ -434,6 +435,7 @@ Index of Expression Operators - :expression:`$setIsSubset` - :expression:`$setUnion` - :expression:`$sin` + - :expression:`$sinh` - :expression:`$size` - :expression:`$slice` - :expression:`$split` @@ -450,6 +452,7 @@ Index of Expression Operators - :group:`$sum` - :expression:`$switch` - :expression:`$tan` + - :expression:`$tanh` - :expression:`$toBool` - :expression:`$toDate` - :expression:`$toDecimal` diff --git a/source/reference/operator/aggregation.txt b/source/reference/operator/aggregation.txt index 6549f888671..e6854132ec1 100644 --- a/source/reference/operator/aggregation.txt +++ b/source/reference/operator/aggregation.txt @@ -307,6 +307,10 @@ Alphabetical Listing of Expression Operators - Returns the cosine of a value that is measured in radians. + * - :expression:`$cosh` + + - Returns the hyperbolic cosine of a value that is measured in + radians. * - :expression:`$dateFromParts` @@ -776,6 +780,10 @@ Alphabetical Listing of Expression Operators - Returns the sine of a value that is measured in radians. + * - :expression:`$sinh` + + - Returns the hyperbolic sine of a value that is measured in + radians. * - :expression:`$slice` @@ -880,7 +888,12 @@ Alphabetical Listing of Expression Operators * - :expression:`$tan` - Returns the tangent of a value that is measured in radians. - + + + * - :expression:`$tanh` + + - Returns the hyperbolic tangent of a value that is measured in + radians. * - :expression:`$toBool` @@ -995,6 +1008,7 @@ Alphabetical Listing of Expression Operators /reference/operator/aggregation/cond /reference/operator/aggregation/convert /reference/operator/aggregation/cos + /reference/operator/aggregation/cosh /reference/operator/aggregation/dateFromParts /reference/operator/aggregation/dateToParts /reference/operator/aggregation/dateFromString @@ -1070,6 +1084,7 @@ Alphabetical Listing of Expression Operators /reference/operator/aggregation/setUnion /reference/operator/aggregation/size /reference/operator/aggregation/sin + /reference/operator/aggregation/sinh /reference/operator/aggregation/slice /reference/operator/aggregation/split /reference/operator/aggregation/sqrt @@ -1085,6 +1100,7 @@ Alphabetical Listing of Expression Operators /reference/operator/aggregation/sum /reference/operator/aggregation/switch /reference/operator/aggregation/tan + /reference/operator/aggregation/tanh /reference/operator/aggregation/toBool /reference/operator/aggregation/toDate /reference/operator/aggregation/toDecimal diff --git a/source/reference/operator/aggregation/cos.txt b/source/reference/operator/aggregation/cos.txt index ccf8b298a44..71dd7b4239e 100644 --- a/source/reference/operator/aggregation/cos.txt +++ b/source/reference/operator/aggregation/cos.txt @@ -142,7 +142,7 @@ Example :expression:`$cos` is a 128-bit decimal. - id: radians - name: Sine of Value in Radians + name: Cosine of Value in Radians content: | The ``trigonometry`` collection contains a document that diff --git a/source/reference/operator/aggregation/cosh.txt b/source/reference/operator/aggregation/cosh.txt new file mode 100644 index 00000000000..acfc0051230 --- /dev/null +++ b/source/reference/operator/aggregation/cosh.txt @@ -0,0 +1,170 @@ +=================== +$cosh (aggregation) +=================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. expression:: $cosh + + .. versionadded:: 4.2 + + Returns the hyperbolic cosine of a value that is measured in radians. + + :expression:`$cosh` has the following syntax: + + .. code-block:: javascript + + { $cosh: } + + :expression:`$cosh` takes any valid :ref:`expression + ` that resolves to a number, measured in + radians. If the expression returns a value in degrees, use the + :expression:`$degreesToRadians` operator to convert the value to + radians. + + By default :expression:`$cosh` returns values as a ``double``. + :expression:`$cosh` can also return values as a :ref:`128-bit decimal + ` if the ```` resolves to a 128-bit + decimal value. + + For more information on expressions, see + :ref:`aggregation-expressions`. + +Behavior +-------- + +``null``, ``NaN``, and ``+/- Infinity`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If the input argument resolves to a value of ``null`` or refers to a +field that is missing, :expression:`$cosh` returns ``null``. If the +argument resolves to ``NaN``, :expression:`$cosh` returns ``NaN``. If +the argument resolves to negative or positive ``Infinity``, +:expression:`$cosh` returns positive ``Infinity``. + +.. list-table:: + :header-rows: 1 + :widths: 50 50 + + * - Example + - Results + + * - ``{ $cosh: NaN }`` + - ``NaN`` + + * - ``{ $cosh: null }`` + - ``null`` + + * - ``{ $cosh: -Infinity }`` + - ``Infinity`` + + * - ``{ $cosh: Infinity }`` + - ``Infinity`` + +Example +------- + +.. tabs:: + + tabs: + + - id: degrees + name: Hyperbolic Cosine of Value in Degrees + content: | + + The following ``trigonometry`` collection contains a document + that stores an ``angle`` value measured in degrees: + + .. code-block:: javascript + + db.trigonometry.insertOne( + { + "_id" : ObjectId( "5c50782193f833234ba90d85" ), + "angle" : NumberDecimal( "53.1301023541559787031443874490659" ) + } + ) + + The following aggregation operation uses the + :expression:`$cosh` expression to calculate the hyperbolic + cosine of ``angle`` and adds it to the input document using the + :pipeline:`$addFields` pipeline stage: + + .. code-block:: javascript + + db.trigonometry.aggregate( [ + { + $addFields : { + "cosh_output" : { $cosh : { $degreesToRadians : "$angle" } } + } + } + ] ) + + The :expression:`$degreesToRadians` expression converts the + ``angle`` in degrees to radians. + + Example output: + + .. code-block:: javascript + :copyable: false + + { + "_id" : ObjectId("5c50782193f833234ba90d85"), + "angle" : NumberDecimal("53.1301023541559787031443874490659"), + "cosh_output" : NumberDecimal("1.461642741099671277595921778079396") + } + + Because ``angle`` is stored as a :ref:`128-bit decimal + `, the :expression:`$cosh` output is also a + 128-bit decimal. + + - id: radians + name: Hyperbolic Cosine of Value in Radians + content: | + + The following ``trigonometry`` collection contains a document + that stores an ``angle`` value measured in radians: + + .. code-block:: javascript + + db.trigonometry.insertOne( + { + "_id" : ObjectId( "5c50782193f833234ba90d15" ), + "angle" : NumberDecimal( "1.6301023541559787031443874490659" ) + } + ) + + The following aggregation operation uses the + :expression:`$cosh` expression to calculate the hyperbolic + cosine of ``angle`` and adds it to the input document using + the :pipeline:`$addFields` pipeline stage: + + .. code-block:: javascript + + db.trigonometry.aggregate( [ + { + $addFields : { + "cosh_output" : { $cosh : "$angle" } + } + } + ] ) + + Example output: + + .. code-block:: javascript + :copyable: false + + { + "_id" : ObjectId("5c50782193f833234ba90d15"), + "angle" : NumberDecimal("1.6301023541559787031443874490659"), + "cosh_output" : NumberDecimal("2.650153334504361016712328539738000") + } + + Because ``angle`` is stored as a :ref:`128-bit decimal + `, the :expression:`$cosh` output is also + a 128-bit decimal. diff --git a/source/reference/operator/aggregation/sinh.txt b/source/reference/operator/aggregation/sinh.txt new file mode 100644 index 00000000000..b8e50d8c485 --- /dev/null +++ b/source/reference/operator/aggregation/sinh.txt @@ -0,0 +1,171 @@ +=================== +$sinh (aggregation) +=================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. expression:: $sinh + + .. versionadded:: 4.2 + + Returns the hyperbolic sine of a value that is measured in radians. + + :expression:`$sinh` has the following syntax: + + .. code-block:: javascript + + { $sinh: } + + :expression:`$sinh` takes any valid :ref:`expression + ` that resolves to a number, measured in + radians. If the expression returns a value in degrees, use the + :expression:`$degreesToRadians` operator to convert the value to + radians. + + By default :expression:`$sinh` returns values as a ``double``. + :expression:`$sinh` can also return values as a :ref:`128-bit decimal + ` if the ```` resolves to a 128-bit + decimal value. + + For more information on expressions, see + :ref:`aggregation-expressions`. + +Behavior +-------- + +``null``, ``NaN``, and ``+/- Infinity`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If the input argument resolves to a value of ``null`` or refers to a +field that is missing, :expression:`$sinh` returns ``null``. If the +argument resolves to ``NaN``, :expression:`$sinh` returns ``NaN``. If +the argument resolves to negative or positive ``Infinity``, +:expression:`$sinh` returns negative or positive ``Infinity`` +respectively. + +.. list-table:: + :header-rows: 1 + :widths: 50 50 + + * - Example + - Results + + * - ``{ $sinh: NaN }`` + - ``NaN`` + + * - ``{ $sinh: null }`` + - ``null`` + + * - ``{ $sinh: -Infinity }`` + - ``-Infinity`` + + * - ``{ $sinh: Infinity }`` + - ``Infinity`` + +Example +------- + +.. tabs:: + + tabs: + + - id: degrees + name: Hyperbolic Sine of Value in Degrees + content: | + + The following ``trigonometry`` collection contains a document + that stores an ``angle`` value measured in degrees: + + .. code-block:: javascript + + db.trigonometry.insertOne( + { + "_id" : ObjectId( "5c50782193f833234ba90d25" ), + "angle" : NumberDecimal( "53.1301023541559787031443874490659" ) + } + ) + + The following aggregation operation uses the + :expression:`$sinh` expression to calculate the hyperbolic sine + of ``angle`` and adds it to the input document using the + :pipeline:`$addFields` pipeline stage: + + .. code-block:: javascript + + db.trigonometry.aggregate( [ + { + $addFields : { + "sinh_output" : { $sinh : { $degreesToRadians : "$angle" } } + } + } + ] ) + + The :expression:`$degreesToRadians` expression converts the + ``angle`` in degrees to radians. + + Example output: + + .. code-block:: javascript + :copyable: false + + { + "_id" : ObjectId("5c50782193f833234ba90d25"), + "angle" : NumberDecimal("53.1301023541559787031443874490659"), + "sinh_output" : NumberDecimal("1.066020404405732132503284522731829") + } + + Because ``angle`` is stored as a :ref:`128-bit decimal + `, the :expression:`$sinh` output is also a + 128-bit decimal. + + - id: radians + name: Hyperbolic Sine of Value in Radians + content: | + + The following ``trigonometry`` collection contains a document + that stores an ``angle`` value measured in radians: + + .. code-block:: javascript + + db.trigonometry.insertOne( + { + "_id" : ObjectId( "5c50782193f833234ba90d35" ), + "angle" : NumberDecimal( "1.6301023541559787031443874490659" ) + } + ) + + The following aggregation operation uses the + :expression:`$sinh` expression to calculate the hyperbolic sine + of ``angle`` and adds it to the input document using the + :pipeline:`$addFields` pipeline stage: + + .. code-block:: javascript + + db.trigonometry.aggregate( [ + { + $addFields : { + "sinh_output" : { $sinh : "$angle" } + } + } + ] ) + + Example output: + + .. code-block:: javascript + :copyable: false + + { + "_id" : ObjectId("5c50782193f833234ba90d35"), + "angle" : NumberDecimal("1.6301023541559787031443874490659"), + "sinh_output" : NumberDecimal("2.454243813557362033961729701069671") + } + + Because ``angle`` is stored as a :ref:`128-bit decimal + `, the :expression:`$sinh` output is also + a 128-bit decimal. diff --git a/source/reference/operator/aggregation/tanh.txt b/source/reference/operator/aggregation/tanh.txt new file mode 100644 index 00000000000..67ffb41264e --- /dev/null +++ b/source/reference/operator/aggregation/tanh.txt @@ -0,0 +1,171 @@ +=================== +$tanh (aggregation) +=================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. expression:: $tanh + + .. versionadded:: 4.2 + + Returns the hyperbolic tangent of a value that is measured in + radians. + + :expression:`$tanh` has the following syntax: + + .. code-block:: javascript + + { $tanh: } + + :expression:`$tanh` takes any valid :ref:`expression + ` that resolves to a number, measured in + radians. If the expression returns a value in degrees, use the + :expression:`$degreesToRadians` operator to convert the value to + radians. + + By default :expression:`$tanh` returns values as a ``double``. + :expression:`$tanh` can also return values as a :ref:`128-bit decimal + ` if the ```` resolves to a 128-bit + decimal value. + + For more information on expressions, see + :ref:`aggregation-expressions`. + +Behavior +-------- + +``null``, ``NaN``, and ``+/- Infinity`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If the input argument resolves to a value of ``null`` or refers to a +field that is missing, :expression:`$tanh` returns ``null``. If the +argument resolves to ``NaN``, :expression:`$tanh` returns ``NaN``. If +the argument resolves to negative or positive ``Infinity``, +:expression:`$tanh` returns ``-1`` or ``1`` respectively. + +.. list-table:: + :header-rows: 1 + :widths: 50 50 + + * - Example + - Results + + * - ``{ $tanh: NaN }`` + - ``NaN`` + + * - ``{ $tanh: null }`` + - ``null`` + + * - ``{ $tanh: -Infinity }`` + - ``-1`` + + * - ``{ $tanh: Infinity }`` + - ``1`` + +Example +------- + +.. tabs:: + + tabs: + + - id: degrees + name: Hyperbolic Tangent of Value in Degrees + content: | + + The following ``trigonometry`` collection contains a document + that stores an ``angle`` value measured in degrees: + + .. code-block:: javascript + + db.trigonometry.insertOne( + { + "_id" : ObjectId( "5c50782193f833234ba90d45" ), + "angle" : NumberDecimal( "53.1301023541559787031443874490659" ) + } + ) + + The following aggregation operation uses the + :expression:`$tanh` expression to calculate the hyperbolic + tangent of ``angle`` and adds it to the input document using + the :pipeline:`$addFields` pipeline stage: + + .. code-block:: javascript + + db.trigonometry.aggregate( [ + { + $addFields : { + "tanh_output" : { $tanh : { $degreesToRadians : "$angle" } } + } + } + ] ) + + The :expression:`$degreesToRadians` expression converts the + ``angle`` in degrees to radians. + + Example output: + + .. code-block:: javascript + :copyable: false + + { + "_id" : ObjectId("5c50782193f833234ba90d45"), + "angle" : NumberDecimal("53.1301023541559787031443874490659"), + "tanh_output" : NumberDecimal("0.7293303448445332820512777329448416") + } + + Because ``angle`` is stored as a :ref:`128-bit decimal + `, the :expression:`$tanh` output is also a + 128-bit decimal. + + - id: radians + name: Hyperbolic Tangent of Value in Radians + content: | + + The following ``trigonometry`` collection contains a document + that stores an ``angle`` value measured in radians: + + .. code-block:: javascript + + db.trigonometry.insertOne( + { + "_id" : ObjectId( "5c50782193f833234ba90d55" ), + "angle" : NumberDecimal( "1.6301023541559787031443874490659" ) + } + ) + + The following aggregation operation uses the + :expression:`$tanh` expression to calculate the hyperbolic + tangent of ``angle`` and adds it to the input document using + the :pipeline:`$addFields` pipeline stage: + + .. code-block:: javascript + + db.trigonometry.aggregate( [ + { + $addFields : { + "tanh_output" : { $tanh : "$angle" } + } + } + ] ) + + Example output: + + .. code-block:: javascript + :copyable: false + + { + "_id" : ObjectId("5c50782193f833234ba90d55"), + "angle" : NumberDecimal("1.6301023541559787031443874490659"), + "tanh_output" : NumberDecimal("0.9260761562750713360156803177935379") + } + + Because ``angle`` is stored as a :ref:`128-bit decimal + `, the :expression:`$tanh` output is also + a 128-bit decimal.