From 70f71d010643847733bc462b17c4c36e7b9f3255 Mon Sep 17 00:00:00 2001
From: BlackMATov <blackmat@mail.ru>
Date: Sat, 19 Dec 2020 03:21:43 +0700
Subject: [PATCH] add bitflags examples to readme

---
 README.md                          | 92 ++++++++++++++++++++++++++++--
 untests/enum_bitflags_examples.cpp | 49 ++++++++++++++++
 2 files changed, 137 insertions(+), 4 deletions(-)
 create mode 100644 untests/enum_bitflags_examples.cpp

diff --git a/README.md b/README.md
index 00904e8..89ccaff 100644
--- a/README.md
+++ b/README.md
@@ -48,10 +48,14 @@ target_link_libraries(your_project_target enum.hpp)
 
 ## Examples
 
-- [Enum declarations](#Enum-declarations)
-- [Traits using](#Traits-using)
-- [Generic context](#Generic-context)
-- [Adapting external enums](#Adapting-external-enums)
+- `enum.hpp`
+  - [Enum declarations](#Enum-declarations)
+  - [Traits using](#Traits-using)
+  - [Generic context](#Generic-context)
+  - [Adapting external enums](#Adapting-external-enums)
+- `enum_bitflags.hpp`
+  - [Enum bitflags using](#Enum-bitflags-using)
+  - [Additional bitflags functions](#Additional-bitflags-functions)
 
 ### Enum declarations
 
@@ -199,6 +203,86 @@ int main() {
 }
 ```
 
+### Enum bitflags using
+
+```cpp
+#include <enum.hpp/enum_bitflags.hpp>
+
+namespace
+{
+    enum class perms : unsigned {
+        execute = 1 << 0,
+        write = 1 << 1,
+        read = 1 << 2,
+    };
+
+    // declares operators for perms enum (~, |, &, ^)
+    ENUM_HPP_OPERATORS_DECL(perms)
+}
+
+int main() {
+    namespace bf = enum_hpp::bitflags;
+
+    // every enum operator returns bitflags<enum> value
+    bf::bitflags flags = perms::read | perms::write;
+
+    // the bitflags class has some member functions for working with bit flags
+    if ( flags.has(perms::write) ) {
+        flags.clear(perms::write);
+    }
+
+    // you can passing other the same type bitflags to these functions
+    flags.set(perms::write | perms::execute);
+
+    // or using bit flags with the usual bit operations but type safe
+    if ( flags & perms::execute ) {
+        flags &= ~perms::execute; // flags.toggle(perms::execute);
+    }
+
+    // or compare them, why not?
+    if ( flags == (perms::read | perms::write) ) {
+        return 0;
+    }
+
+    return 1;
+}
+```
+
+### Additional bitflags functions
+
+```cpp
+#include <enum.hpp/enum_bitflags.hpp>
+
+namespace
+{
+    enum class perms : unsigned {
+        execute = 1 << 0,
+        write = 1 << 1,
+        read = 1 << 2,
+    };
+
+    // declares operators for perms enum (~, |, &, ^)
+    ENUM_HPP_OPERATORS_DECL(perms)
+}
+
+int main() {
+    namespace bf = enum_hpp::bitflags;
+
+    bf::bitflags<perms> flags = perms::read | perms::write;
+
+    // bitflags namespace has many free functions
+    // that can accept both enumerations and bit flags
+
+    if ( bf::any_of(flags, perms::write | perms::execute) ) {
+        // it's writable or executable
+    }
+
+    if ( bf::any_except(flags, perms::write | perms::execute) ) {
+        // and something else :-)
+    }
+}
+```
+
 ## API
 
 - `enum.hpp`
diff --git a/untests/enum_bitflags_examples.cpp b/untests/enum_bitflags_examples.cpp
new file mode 100644
index 0000000..b081fd8
--- /dev/null
+++ b/untests/enum_bitflags_examples.cpp
@@ -0,0 +1,49 @@
+/*******************************************************************************
+ * This file is part of the "https://github.com/blackmatov/enum.hpp"
+ * For conditions of distribution and use, see copyright notice in LICENSE.md
+ * Copyright (C) 2019-2020, by Matvey Cherevko (blackmatov@gmail.com)
+ ******************************************************************************/
+
+#include <enum.hpp/enum_bitflags.hpp>
+
+#include "doctest/doctest.hpp"
+
+#include <string>
+#include <iostream>
+
+namespace
+{
+    enum class perms : unsigned {
+        execute = 1 << 0,
+        write = 1 << 1,
+        read = 1 << 2,
+    };
+    ENUM_HPP_OPERATORS_DECL(perms)
+}
+
+TEST_CASE("bitflags_examples") {
+    SUBCASE("Enum operators using") {
+        namespace bf = enum_hpp::bitflags;
+
+        bf::bitflags<perms> flags = perms::read | perms::write;
+
+        if ( flags.has(perms::write) ) {
+            flags.clear(perms::write);
+        }
+
+        flags.set(perms::write | perms::execute);
+
+        if ( flags & perms::execute ) {
+            flags ^= perms::execute; // flags.toggle(perms::execute);
+        }
+
+        CHECK(flags == (perms::read | perms::write));
+    }
+
+    SUBCASE("Additional bitflags functions") {
+        namespace bf = enum_hpp::bitflags;
+        bf::bitflags<perms> flags = perms::read | perms::write;
+        CHECK(bf::any_of(flags, perms::write | perms::execute));
+        CHECK(bf::any_except(flags, perms::write | perms::execute));
+    }
+}