Started a page with some examples for inspiration

Author: jesperkdab

.reuse/dep5

@@ -4,6 +4,6 @@ Upstream-Contact:  <info@kdab.com>
 Source: https://www.github.com/KDAB/KDAlgorithms
 
 #misc source code
-Files: run .gitignore CMakeLists.txt CMakePresets.json README.md _clang-format .pre-commit-config.yaml appveyor.yml Documentation/* Example/CMakeLists.txt
+Files: run .gitignore CMakeLists.txt CMakePresets.json README.md _clang-format .pre-commit-config.yaml appveyor.yml Documentation/* Example/CMakeLists.txt Inspiration/CMakeLists.txt
 Copyright: 2022 Klarälvdalens Datakonsult AB, a KDAB Group company <info@kdab.com>
 License: MIT

CMakeLists.txt

@@ -80,5 +80,13 @@ if(BUILD_TESTING AND ${KDALGORITHMS_BUILD_TEST})
     add_executable(tst_return_type_traits tests/tst_return_type_traits.cpp)
 
     # Make it show up in Qt Creator
-    add_custom_target(additional_files SOURCES README.md run Documentation/algorithms.md Documentation/deploying.md)
+    add_custom_target(additional_files SOURCES
+        README.md
+        run
+        Documentation/algorithms.md
+        Documentation/deploying.md
+        Documentation/inspiration.md
+    )
+
+    add_subdirectory(Inspiration)
 endif()

Documentation/inspiration.md

@@ -0,0 +1,74 @@
+Just for Inspiration
+====================
+This page contains a number of (well one for now) examples, where you may use algorithms to write clearer code.
+
+It took me (Jesper) quite a long time before I could really appreciate usage of algorithms, and furthermore
+I was often struggling to find the right one to use. 
+I was also often paralyzed when I had to chose between two solutions to the same problem: 
+one using a relative simple for loop and one which was more complex but using algorithms.
+
+Today, I have settled with the understanding that algorithms is a means to an end, not the end itself. 
+Their primary purpose is to make the code more expressive - so instead of having to read through a for loop to understand exactly what it is building up, I can see that it for example filters out some items, and transform the result to another format.
+
+
+Traversing a list which do not provide iterators
+------------------------------------------------
+(Example in Inspiration/qlistview_all_columns_selected.cpp)
+
+Sometimes you want to filter, transform, or apply any other algorithm to a *list* provided to you via an API which do *not* offer iterators, and which you therefore *can not* apply algorithms on.
+
+One solution is of course to create a wrapper object providing an iterator API, but as this solution shows, another solution is to simply create a list of indexes to iterate.
+
+### The Problem
+Imagine you want to check if all columns of a given row in a table (here QTableWidget) is selected. This looks a lot like <a href="https://github.com/KDAB/KDAlgorithms/blob/main/Documentation/algorithms.md#all_any_none">all_of</a>, doesn't it?
+
+To get to the selected items, you will have to ask the table for its QItemSelectionModel, which in turn, naturally does not offer a *are all columns for a given row selected* API, nor does it offer an iterator to traverse all columns for a given row (which would have been a really weird API to begin with, if it did).
+
+What the selection model does offer you is to answer yes or no to the question is a given (row, column) selected.
+
+A solution often looks like this:
+
+```
+    bool allColumnsSelected = true;
+    int row = m_table->currentRow();
+    auto selectionModel = m_table->selectionModel();
+    auto model = m_table->model();
+    for (int i = 0; i < m_table->columnCount(); ++i) {
+        if (!selectionModel->isSelected(model->index(row, i))) {
+            allColumnsSelected = false;
+            break;
+        }
+    }
+    
+    if (allColumnsSelected)
+        doSomething();
+```
+
+The code is proper Qt code, and might not be super readable to you if you are not a Qt developer, but even if you are, you need to read all lines carefully to understand it. The key part in the above is the explicit for loop over all columns.
+
+Here is a solution using KDAlgorithms, and more specifically **all_of**:
+
+```
+    auto columns = kdalgorithms::iota(m_table->columnCount());
+    auto isColumnSelected = [row = m_table->currentRow(),
+                             selectionModel = m_table->selectionModel(),
+                             model = m_table->model()](int column) {
+        return selectionModel->isSelected(model->index(row, column));
+    };
+
+    if (kdalgorithms::all_of(columns, isColumnSelected))
+        doSomething();
+```
+
+The trick is to iterate (implicitly inside the algorithms) over the list of indexes for the columns. We do so by first fetching a list of all indexes (the variable *columns*). Following that we create a lambda expression to answer if a given column is selected, and now the test is super readable.
+
+### Some after thoughts
+If you have that feeling that you have seen this trick before, namely creating a list of the indexes and operating on that, then chances are you occasionally write Python code. In python you often find code like:
+
+```
+vector = [1, 2, 3, 4, 5]
+for i in range(len(vector)):
+    if vector[i] % 2 == 1:
+        vector[i] = 0
+```        
+

Inspiration/CMakeLists.txt

@@ -0,0 +1,14 @@
+cmake_minimum_required(VERSION 3.9)
+project(Inspiration)
+
+set(CMAKE_INCLUDE_CURRENT_DIR ON)
+find_package(QT NAMES Qt6 Qt5 REQUIRED COMPONENTS Core Gui)
+find_package(Qt${QT_VERSION_MAJOR} CONFIG REQUIRED COMPONENTS Core Gui Widgets)
+set(CMAKE_AUTOMOC TRUE)
+set(CMAKE_AUTORCC TRUE)
+
+
+add_executable(qlistview_all_columns_selected
+  qlistview_all_columns_selected.cpp
+)
+target_link_libraries(qlistview_all_columns_selected Qt${QT_VERSION_MAJOR}::Core Qt${QT_VERSION_MAJOR}::Gui  Qt${QT_VERSION_MAJOR}::Widgets)

Inspiration/qlistview_all_columns_selected.cpp

@@ -0,0 +1,116 @@
+/****************************************************************************
+**
+** This file is part of KDAlgorithms
+**
+** SPDX-FileCopyrightText: 2023 Klarälvdalens Datakonsult AB, a KDAB Group company <info@kdab.com>
+**
+** SPDX-License-Identifier: MIT
+**
+****************************************************************************/
+
+#include "../src/kdalgorithms.h"
+#include <QApplication>
+#include <QDebug>
+#include <QLabel>
+#include <QTableWidget>
+#include <QVBoxLayout>
+
+/*
+    For details see https://github.com/KDAB/KDAlgorithms/blob/main/Documentation/inspiration.md
+*/
+class Test : public QWidget
+{
+public:
+    Test()
+    {
+        auto layout = new QVBoxLayout(this);
+
+        m_table = new QTableWidget(5, 5);
+        layout->addWidget(m_table);
+
+        m_label1 = new QLabel("Select Something");
+        layout->addWidget(m_label1);
+        connect(m_table, &QTableWidget::currentCellChanged, this, &Test::updateLabelV1);
+
+        m_label2 = new QLabel("Select Something");
+        layout->addWidget(m_label2);
+        connect(m_table, &QTableWidget::currentCellChanged, this, &Test::updateLabelV2);
+
+        m_label3 = new QLabel("Select Something");
+        layout->addWidget(m_label3);
+        connect(m_table, &QTableWidget::currentCellChanged, this, &Test::updateLabelV3);
+    }
+
+private:
+    /* The normal implementation using for loops */
+    void updateLabelV1()
+    {
+        bool allColumnsSelected = true;
+        int row = m_table->currentRow();
+        auto selectionModel = m_table->selectionModel();
+        auto model = m_table->model();
+        for (int i = 0; i < m_table->columnCount(); ++i) {
+            if (!selectionModel->isSelected(model->index(row, i))) {
+                allColumnsSelected = false;
+                break;
+            }
+        }
+
+        if (allColumnsSelected)
+            m_label1->setText("All columns selected");
+        else
+            m_label1->setText("Not all columns selected");
+    }
+
+    /* The improved version using algorithms */
+    void updateLabelV2()
+    {
+        auto columns = kdalgorithms::iota(m_table->columnCount());
+        auto isColumnSelected = [row = m_table->currentRow(),
+                                 selectionModel = m_table->selectionModel(),
+                                 model = m_table->model()](int column) {
+            return selectionModel->isSelected(model->index(row, column));
+        };
+
+        if (kdalgorithms::all_of(columns, isColumnSelected))
+            m_label2->setText("All columns selected");
+        else
+            m_label2->setText("Not all columns selected");
+    }
+
+    /* The version I would have written without algorithms */
+    void updateLabelV3()
+    {
+        bool allColumnsSelected = [this] {
+            int row = m_table->currentRow();
+            auto selectionModel = m_table->selectionModel();
+            auto model = m_table->model();
+            for (int i = 0; i < m_table->columnCount(); ++i) {
+                if (!selectionModel->isSelected(model->index(row, i))) {
+                    return false;
+                }
+            }
+            return true;
+        }();
+
+        if (allColumnsSelected)
+            m_label3->setText("All columns selected");
+        else
+            m_label3->setText("Not all columns selected");
+    }
+
+    QTableWidget *m_table;
+    QLabel *m_label1;
+    QLabel *m_label2;
+    QLabel *m_label3;
+};
+
+int main(int argc, char **argv)
+{
+    QApplication app(argc, argv);
+
+    Test test;
+    test.resize(600, 300);
+    test.show();
+    app.exec();
+}

README.md

@@ -5,8 +5,10 @@ The purpose of this library is to make it easier to work with algorithms in C++1
 
 * <a href="Documentation/algorithms.md">Documentation of all the algorithms</a>
 * <a href="Documentation/deploying.md">Deploying the algorithms with CMake</a>
-* <a href="tests/tst_kdalgorithms.cpp">Be inspired by all the unit tests</a>
+* <a href="Documentation/inspiration.md">Get inspired by some real world examples</a>
+* <a href="tests/tst_kdalgorithms.cpp">Get inspired by all the unit tests</a>
 * <a href="https://youtu.be/iAEIPk64ZJw?list=PL6CJYn40gN6gf-G-o6syFwGrtq3kItEqI">Youtube video introducing the library</a>
+* <a href="https://www.kdab.com/introducing-kdalgorithms">A blog post on KDAlgorithms</a>
 
 Example - filtered
 ------------------