diff --git a/api-reference/operators/bitwise/$bitand.md b/api-reference/operators/bitwise/$bitand.md new file mode 100644 index 0000000..0941001 --- /dev/null +++ b/api-reference/operators/bitwise/$bitand.md @@ -0,0 +1,212 @@ +--- +title: $bitAnd +description: The $bitAnd operator performs a bitwise AND operation on integer values and returns the result as an integer. +type: operators +category: bitwise +--- + +# $bitAnd + +The `$bitAnd` operator performs a `bitwise AND` operation on integer values. It compares each bit of the first operand to the corresponding bit of the second operand. If both bits are 1, the corresponding result bit is set to 1. Otherwise, the corresponding result bit is set to 0. + +## Syntax + +```javascript +{ + $bitAnd: [ , , ... ] +} +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| **`expression1, expression2, ...`** | Expressions that evaluate to integers. The `$bitAnd` operator performs a bitwise AND operation on all provided expressions. | + +## Examples + +Consider this sample document from the stores collection. + +```json +{ + "_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4", + "name": "First Up Consultants | Beverage Shop - Satterfieldmouth", + "location": { + "lat": -89.2384, + "lon": -46.4012 + }, + "staff": { + "totalStaff": { + "fullTime": 8, + "partTime": 20 + } + }, + "sales": { + "totalSales": 75670, + "salesByCategory": [ + { + "categoryName": "Wine Accessories", + "totalSales": 34440 + }, + { + "categoryName": "Bitters", + "totalSales": 39496 + }, + { + "categoryName": "Rum", + "totalSales": 1734 + } + ] + }, + "promotionEvents": [ + { + "eventName": "Unbeatable Bargain Bash", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 6, + "Day": 23 + }, + "endDate": { + "Year": 2024, + "Month": 7, + "Day": 2 + } + }, + "discounts": [ + { + "categoryName": "Whiskey", + "discountPercentage": 7 + }, + { + "categoryName": "Bitters", + "discountPercentage": 15 + }, + { + "categoryName": "Brandy", + "discountPercentage": 8 + }, + { + "categoryName": "Sports Drinks", + "discountPercentage": 22 + }, + { + "categoryName": "Vodka", + "discountPercentage": 19 + } + ] + }, + { + "eventName": "Steal of a Deal Days", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 9, + "Day": 21 + }, + "endDate": { + "Year": 2024, + "Month": 9, + "Day": 29 + } + }, + "discounts": [ + { + "categoryName": "Organic Wine", + "discountPercentage": 19 + }, + { + "categoryName": "White Wine", + "discountPercentage": 20 + }, + { + "categoryName": "Sparkling Wine", + "discountPercentage": 19 + }, + { + "categoryName": "Whiskey", + "discountPercentage": 17 + }, + { + "categoryName": "Vodka", + "discountPercentage": 23 + } + ] + } + ] +} +``` + +### Example 1: Basic bitwise AND operation + +This query retrieves staff information for a specific store and computes a `bitwise AND` between the number of full-time and part-time staff to create permission flags. + +```javascript +db.stores.aggregate([{ + $match: { + _id: "40d6f4d7-50cd-4929-9a07-0a7a133c2e74" + } + }, + { + $project: { + name: 1, + fullTimeStaff: "$staff.totalStaff.fullTime", + partTimeStaff: "$staff.totalStaff.partTime", + staffPermissionFlag: { + $bitAnd: ["$staff.totalStaff.fullTime", "$staff.totalStaff.partTime"] + } + } + } +]) +``` + +This query returns the following result. + +```json +[ + { + "_id": "40d6f4d7-50cd-4929-9a07-0a7a133c2e74", + "name": "Proseware, Inc. | Home Entertainment Hub - East Linwoodbury", + "fullTimeStaff": 19, + "partTimeStaff": 20, + "staffPermissionFlag": 16 + } +] +``` + +### Example 2: Multiple value `$bitAnd` + +This query checks bitwise permissions or combined flags based on multiple numeric fields for a single store. + +```javascript +db.stores.aggregate([{ + $match: { + _id: "40d6f4d7-50cd-4929-9a07-0a7a133c2e74" + } + }, + { + $project: { + name: 1, + combinedFlag: { + $bitAnd: [ + "$staff.totalStaff.fullTime", + "$staff.totalStaff.partTime", + 255 + ] + } + } + } +]) +``` + +This query returns the following result. + +```json +[ + { + "_id": "40d6f4d7-50cd-4929-9a07-0a7a133c2e74", + "name": "Proseware, Inc. | Home Entertainment Hub - East Linwoodbury", + "combinedFlag": 16 + } +] +``` diff --git a/api-reference/operators/bitwise/$bitnot.md b/api-reference/operators/bitwise/$bitnot.md new file mode 100644 index 0000000..b92d8ef --- /dev/null +++ b/api-reference/operators/bitwise/$bitnot.md @@ -0,0 +1,237 @@ +--- +title: $bitNot +description: The $bitNot operator performs a bitwise NOT operation on integer values and returns the result as an integer. +type: operators +category: bitwise +--- + +# $bitNot + +The `$bitNot` operator performs a bitwise NOT operation on integer values. It inverts all the bits of the operand, turning 1s into 0s and 0s into 1s. The result is the bitwise complement of the input value. + +## Syntax + +```javascript +{ + $bitNot: +} +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| **`expression`** | An expression that evaluates to an integer. The `$bitNot` operator performs a bitwise NOT operation on this value. | + +## Examples + +Consider this sample document from the stores collection. + +```json +{ + "_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4", + "name": "First Up Consultants | Beverage Shop - Satterfieldmouth", + "location": { + "lat": -89.2384, + "lon": -46.4012 + }, + "staff": { + "totalStaff": { + "fullTime": 8, + "partTime": 20 + } + }, + "sales": { + "totalSales": 75670, + "salesByCategory": [ + { + "categoryName": "Wine Accessories", + "totalSales": 34440 + }, + { + "categoryName": "Bitters", + "totalSales": 39496 + }, + { + "categoryName": "Rum", + "totalSales": 1734 + } + ] + }, + "promotionEvents": [ + { + "eventName": "Unbeatable Bargain Bash", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 6, + "Day": 23 + }, + "endDate": { + "Year": 2024, + "Month": 7, + "Day": 2 + } + }, + "discounts": [ + { + "categoryName": "Whiskey", + "discountPercentage": 7 + }, + { + "categoryName": "Bitters", + "discountPercentage": 15 + }, + { + "categoryName": "Brandy", + "discountPercentage": 8 + }, + { + "categoryName": "Sports Drinks", + "discountPercentage": 22 + }, + { + "categoryName": "Vodka", + "discountPercentage": 19 + } + ] + }, + { + "eventName": "Steal of a Deal Days", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 9, + "Day": 21 + }, + "endDate": { + "Year": 2024, + "Month": 9, + "Day": 29 + } + }, + "discounts": [ + { + "categoryName": "Organic Wine", + "discountPercentage": 19 + }, + { + "categoryName": "White Wine", + "discountPercentage": 20 + }, + { + "categoryName": "Sparkling Wine", + "discountPercentage": 19 + }, + { + "categoryName": "Whiskey", + "discountPercentage": 17 + }, + { + "categoryName": "Vodka", + "discountPercentage": 23 + } + ] + } + ] +} +``` + +### Example 1: Basic bitwise NOT operation + +This query performs a bitwise inversion on the staff count fields for a specific store document. The inverted values can be used for special permission flags, feature toggles, or bitmask operations. The bitwise NOT of 14 results are -15, and the bitwise NOT of 8 results in -9. The observed result is due to two's complement representation where ~n = -(n+1). + +```javascript +db.stores.aggregate([{ + $match: { + _id: "26afb024-53c7-4e94-988c-5eede72277d5" + } + }, + { + $project: { + name: 1, + fullTimeStaff: "$staff.totalStaff.fullTime", + partTimeStaff: "$staff.totalStaff.partTime", + invertedFullTime: { + $bitNot: "$staff.totalStaff.fullTime" + }, + invertedPartTime: { + $bitNot: "$staff.totalStaff.partTime" + } + } + } +]) +``` + +This query returns the following result. + +```json +[ + { + "_id": "26afb024-53c7-4e94-988c-5eede72277d5", + "name": "First Up Consultants | Microphone Bazaar - South Lexusland", + "fullTimeStaff": 14, + "partTimeStaff": 8, + "invertedFullTime": -15, + "invertedPartTime": -9 + } +] +``` + +### Example 2: Using $bitNot with discount percentages + +This query extracts and processes discount information for a specific store and applies a bitwise NOT operation on each discount percentage. The bitwise NOT operation inverts all bits: 20 becomes -21 and 17 becomes -18. + +```javascript +db.stores.aggregate([{ + $match: { + _id: "26afb024-53c7-4e94-988c-5eede72277d5" + } + }, + { + $unwind: "$promotionEvents" + }, + { + $match: { + "promotionEvents.eventName": "Incredible Savings Showcase" + } + }, + { + $unwind: "$promotionEvents.discounts" + }, + { + $project: { + name: 1, + eventName: "$promotionEvents.eventName", + categoryName: "$promotionEvents.discounts.categoryName", + discountPercentage: "$promotionEvents.discounts.discountPercentage", + invertedDiscount: { + $bitNot: "$promotionEvents.discounts.discountPercentage" + } + } + } +]) +``` + +This query returns the following results: + +```json +[ + { + "_id": "26afb024-53c7-4e94-988c-5eede72277d5", + "name": "First Up Consultants | Microphone Bazaar - South Lexusland", + "eventName": "Incredible Savings Showcase", + "categoryName": "Microphone Stands", + "discountPercentage": 17, + "invertedDiscount": -18 + }, + { + "_id": "26afb024-53c7-4e94-988c-5eede72277d5", + "name": "First Up Consultants | Microphone Bazaar - South Lexusland", + "eventName": "Incredible Savings Showcase", + "categoryName": "Condenser Microphones", + "discountPercentage": 20, + "invertedDiscount": -21 + } +] +``` diff --git a/api-reference/operators/bitwise/$bitor.md b/api-reference/operators/bitwise/$bitor.md new file mode 100644 index 0000000..4a59a14 --- /dev/null +++ b/api-reference/operators/bitwise/$bitor.md @@ -0,0 +1,243 @@ +--- +title: $bitOr +description: The $bitOr operator performs a bitwise OR operation on integer values and returns the result as an integer. +type: operators +category: bitwise +--- + +# $bitOr + +The `$bitOr` operator performs a bitwise OR operation on integer values. It compares each bit of the first operand to the corresponding bit of the second operand. If either bit is 1, the corresponding result bit is set to 1. If both bits are 0, the corresponding result bit is set to 0. + +## Syntax + +```javascript +{ + $bitOr: [ , , ... ] +} +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| **`expression1, expression2, ...`** | Expressions that evaluate to integers. The `$bitOr` operator performs a bitwise OR operation on all provided expressions. | + +## Examples + +Consider this sample document from the stores collection. + +```json +{ + "_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4", + "name": "First Up Consultants | Beverage Shop - Satterfieldmouth", + "location": { + "lat": -89.2384, + "lon": -46.4012 + }, + "staff": { + "totalStaff": { + "fullTime": 8, + "partTime": 20 + } + }, + "sales": { + "totalSales": 75670, + "salesByCategory": [ + { + "categoryName": "Wine Accessories", + "totalSales": 34440 + }, + { + "categoryName": "Bitters", + "totalSales": 39496 + }, + { + "categoryName": "Rum", + "totalSales": 1734 + } + ] + }, + "promotionEvents": [ + { + "eventName": "Unbeatable Bargain Bash", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 6, + "Day": 23 + }, + "endDate": { + "Year": 2024, + "Month": 7, + "Day": 2 + } + }, + "discounts": [ + { + "categoryName": "Whiskey", + "discountPercentage": 7 + }, + { + "categoryName": "Bitters", + "discountPercentage": 15 + }, + { + "categoryName": "Brandy", + "discountPercentage": 8 + }, + { + "categoryName": "Sports Drinks", + "discountPercentage": 22 + }, + { + "categoryName": "Vodka", + "discountPercentage": 19 + } + ] + }, + { + "eventName": "Steal of a Deal Days", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 9, + "Day": 21 + }, + "endDate": { + "Year": 2024, + "Month": 9, + "Day": 29 + } + }, + "discounts": [ + { + "categoryName": "Organic Wine", + "discountPercentage": 19 + }, + { + "categoryName": "White Wine", + "discountPercentage": 20 + }, + { + "categoryName": "Sparkling Wine", + "discountPercentage": 19 + }, + { + "categoryName": "Whiskey", + "discountPercentage": 17 + }, + { + "categoryName": "Vodka", + "discountPercentage": 23 + } + ] + } + ] +} +``` + +### Example 1: Basic bitwise OR operation + +This query performs a bitwise OR operation on the staff values of a specific store document to combine permission flags. The bitwise OR of 3 (011 in binary) and 2 (010 in binary) equals 3 (011 in binary). + +```javascript +db.stores.aggregate([{ + $match: { + _id: "f2a8c190-28e4-4e14-9d8b-0256e53dca66" + } + }, + { + $project: { + name: 1, + fullTimeStaff: "$staff.totalStaff.fullTime", + partTimeStaff: "$staff.totalStaff.partTime", + combinedStaffFlag: { + $bitOr: ["$staff.totalStaff.fullTime", "$staff.totalStaff.partTime"] + } + } + } +]) +``` + +This query returns the following result. + +```json +[ + { + "_id": "f2a8c190-28e4-4e14-9d8b-0256e53dca66", + "name": "Fabrikam, Inc. | Car Accessory Outlet - West Adele", + "fullTimeStaff": 3, + "partTimeStaff": 2, + "combinedStaffFlag": 3 + } +] +``` + +### Example 2: Multiple value bitwise OR with discount percentages + +This query extracts discount details for a specific promotion event and computes a bitwise flag combining discounts and staff values. The output shows the results of the aggregation query that calculates a combined bitwise flag for each discount in the event `Super Saver Spectacular`. The operation combines discount percentages with staff numbers using bitwise OR: 7|3|2 = 7 and 11|3|2 = 11. + +```javascript +db.stores.aggregate([{ + $match: { + _id: "f2a8c190-28e4-4e14-9d8b-0256e53dca66" + } + }, + { + $unwind: "$promotionEvents" + }, + { + $match: { + "promotionEvents.eventName": "Super Saver Spectacular" + } + }, + { + $project: { + name: 1, + eventName: "$promotionEvents.eventName", + discountFlags: { + $map: { + input: "$promotionEvents.discounts", + as: "discount", + in: { + categoryName: "$$discount.categoryName", + discountPercentage: "$$discount.discountPercentage", + combinedFlag: { + $bitOr: [ + "$$discount.discountPercentage", + "$staff.totalStaff.fullTime", + "$staff.totalStaff.partTime" + ] + } + } + } + } + } + } +]) +``` + +This query returns the following result. + +```json +[ + { + "_id": "f2a8c190-28e4-4e14-9d8b-0256e53dca66", + "name": "Fabrikam, Inc. | Car Accessory Outlet - West Adele", + "eventName": "Super Saver Spectacular", + "discountFlags": [ + { + "categoryName": "Car Chargers", + "discountPercentage": 7, + "combinedFlag": 7 + }, + { + "categoryName": "Dash Cameras", + "discountPercentage": 11, + "combinedFlag": 11 + } + ] + } +] +``` diff --git a/api-reference/operators/bitwise/$bitxor.md b/api-reference/operators/bitwise/$bitxor.md new file mode 100644 index 0000000..e197c98 --- /dev/null +++ b/api-reference/operators/bitwise/$bitxor.md @@ -0,0 +1,253 @@ +--- +title: $bitXor +description: The $bitXor operator performs a bitwise XOR operation on integer values. +type: operators +category: bitwise +--- + +# $bitXor + +The `$bitXor` operator performs a bitwise exclusive OR (XOR) operation on integer values. The XOR operation returns 1 for each bit position where the corresponding bits of the operands are different, and 0 where they're the same. + +## Syntax + +```javascript +{ + $bitXor: [ , , ... ] +} +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| **`expression1, expression2, ...`** | Expressions that resolve to integer values. The operator performs XOR operations on these values in sequence. | + +## Examples + +Consider this sample document from the stores collection. + +```json +{ + "_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4", + "name": "First Up Consultants | Beverage Shop - Satterfieldmouth", + "location": { + "lat": -89.2384, + "lon": -46.4012 + }, + "staff": { + "totalStaff": { + "fullTime": 8, + "partTime": 20 + } + }, + "sales": { + "totalSales": 75670, + "salesByCategory": [ + { + "categoryName": "Wine Accessories", + "totalSales": 34440 + }, + { + "categoryName": "Bitters", + "totalSales": 39496 + }, + { + "categoryName": "Rum", + "totalSales": 1734 + } + ] + }, + "promotionEvents": [ + { + "eventName": "Unbeatable Bargain Bash", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 6, + "Day": 23 + }, + "endDate": { + "Year": 2024, + "Month": 7, + "Day": 2 + } + }, + "discounts": [ + { + "categoryName": "Whiskey", + "discountPercentage": 7 + }, + { + "categoryName": "Bitters", + "discountPercentage": 15 + }, + { + "categoryName": "Brandy", + "discountPercentage": 8 + }, + { + "categoryName": "Sports Drinks", + "discountPercentage": 22 + }, + { + "categoryName": "Vodka", + "discountPercentage": 19 + } + ] + }, + { + "eventName": "Steal of a Deal Days", + "promotionalDates": { + "startDate": { + "Year": 2024, + "Month": 9, + "Day": 21 + }, + "endDate": { + "Year": 2024, + "Month": 9, + "Day": 29 + } + }, + "discounts": [ + { + "categoryName": "Organic Wine", + "discountPercentage": 19 + }, + { + "categoryName": "White Wine", + "discountPercentage": 20 + }, + { + "categoryName": "Sparkling Wine", + "discountPercentage": 19 + }, + { + "categoryName": "Whiskey", + "discountPercentage": 17 + }, + { + "categoryName": "Vodka", + "discountPercentage": 23 + } + ] + } + ] +} +``` + +### Example 1: Basic XOR operation + +This query uses an aggregation pipeline to calculate between full-time and part-time staff counts for a specific store. The resulting document contains the store details along with a computed field. The XOR operation between 19 (binary: 10011) and 20 (binary: 10100) results in 7 (binary: 00111). + +```javascript +db.stores.aggregate([{ + $match: { + _id: "40d6f4d7-50cd-4929-9a07-0a7a133c2e74" + } + }, + { + $project: { + name: 1, + fullTimeStaff: "$staff.totalStaff.fullTime", + partTimeStaff: "$staff.totalStaff.partTime", + staffXor: { + $bitXor: ["$staff.totalStaff.fullTime", "$staff.totalStaff.partTime"] + } + } + } +]) +``` + +This query returns the following result. + +```json +[ + { + "_id": "40d6f4d7-50cd-4929-9a07-0a7a133c2e74", + "name": "Proseware, Inc. | Home Entertainment Hub - East Linwoodbury", + "fullTimeStaff": 19, + "partTimeStaff": 20, + "staffXor": 7 + } +] +``` + +### Example 2: XOR with Multiple Values + +This query computes the bitwise XOR of all discount percentages for the `Discount Delight Days` event of a specific store. The resulting document represents the bitwise XOR calculation of all discount percentages for the `Discount Delight Days` event. + +```javascript +db.stores.aggregate([{ + $match: { + _id: "40d6f4d7-50cd-4929-9a07-0a7a133c2e74" + } + }, + { + $unwind: "$promotionEvents" + }, + { + $match: { + "promotionEvents.eventName": "Discount Delight Days" + } + }, + { + $unwind: "$promotionEvents.discounts" + }, + { + $group: { + _id: "$_id", + name: { + $first: "$name" + }, + eventName: { + $first: "$promotionEvents.eventName" + }, + discountPercentages: { + $push: "$promotionEvents.discounts.discountPercentage" + } + } + }, + { + $project: { + name: 1, + eventName: 1, + discountPercentages: 1, + xorResult: { + $reduce: { + input: { + $map: { + input: "$discountPercentages", + as: "val", + in: { + $toLong: "$$val" + } + } + }, + initialValue: { + $toLong: 0 + }, + in: { + $bitXor: ["$$value", "$$this"] + } + } + } + } + } +]) +``` + +This query returns the following result. + +```json +[ + { + "_id": "40d6f4d7-50cd-4929-9a07-0a7a133c2e74", + "name": "Proseware, Inc. | Home Entertainment Hub - East Linwoodbury", + "eventName": "Discount Delight Days", + "discountPercentages": [22, 23, 10, 10, 9, 24], + "xorResult": { "$numberLong": "16" } + } +] +```