Add API reference documentation for bitwise

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: [ <expression1>, <expression2>, ... ]
+}
+```
+
+## 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
+  }
+]
+```