Merge pull request #175 from FeathersRe/UG-DG-Updates-v2.1

UG-DG-Updates-v2.1

docs/UserGuide.md

@@ -51,7 +51,7 @@ A quick reference table for all commands is presented below. Certain commands ha
 | Clear all transactions | `clear`                                                                                               | N/A               |
 | Settle up debts        | `settleup [member]`                                                                                   | `settle`          |
 | Switch groups          | `group [group_name]`                                                                                  | N/A               |
-| Filter transactions    | `filter time a/[TIME] b/[TIME]`                                                                       | N/A               |
+| Filter transactions    | `filter a/[TIME] b/[TIME]`                                                                            | N/A               |
 | View chart             | `chart`                                                                                               | N/A               |
 | Exit                   | `exit`                                                                                                | N/A               |
 
@@ -65,6 +65,7 @@ A quick reference table for all commands is presented below. Certain commands ha
     - [Group Management](#group-management)
     - [Member and Transaction Management](#member-and-transaction-management)
     - [Group Balances \& Expense Tracking](#group-balances--expense-tracking)
+    - [Easily Finding Transactions You Need](#Easily-Finding-Transactions)
     - [Debt Simplification](#debt-simplification)
     - [Security](#security)
     - [Data Storage](#data-storage)
@@ -94,10 +95,13 @@ A quick reference table for all commands is presented below. Certain commands ha
     - [Clearing all transactions `clear`](#clearing-all-transactions-clear)
     - [Settle a user's debts: `settleup`](#settle-a-users-debts-settleup)
     - [Switching groups: `group`](#switching-groups-group)
-    - [Filter transactions: `filter`](#filter-transactions-filter)
+    - [Filter transactions (by transaction time): `filter`](#filter-transactions-filter)
     - [Views the balances of all members on a chart: `chart`](#views-the-balances-of-all-members-on-a-chart-chart)
     - [Exiting the application: `exit`](#exiting-the-application-exit)
   - [FAQ](#faq)
+  - [Common Errors](#Common-Errors)
+    - [Failure to adhere to command format](#Failure-to-adhere-to-command-format)
+    - [Invalid Requests](#Invalid-Requests)
   - [Known Issues](#known-issues)
   - [Future Improvements](#future-improvements)
 
@@ -119,6 +123,10 @@ Within each group, LongAh! provides comprehensive member and transaction managem
 
 Tracking group balances and expenses has never been easier with LongAh! Users can log transactions between members, facilitating transparent and equitable expense distribution. LongAh! also offers intuitive visualizations, allowing users to quickly assess group financial dynamics at a glance.
 
+### Easily Finding Transactions
+
+Apart from neatly organising users' pending transactions, LongAh! offers a variety of ways for users to conveniently locate the transactions they are interested in by simply providing the related details. As of now, LongAh! has embedded support towards user searches based on both member names and transaction time, effectively lowering the cost of navigating through the transaction list when entries increase. 
+
 ### Debt Simplification
 
 LongAh! streamlines debt settlement processes by automatically computing the optimal repayment strategy. By presenting users with a simplified list of debts and transactions, LongAh! minimizes the effort required to settle financial obligations within the group, fostering smoother financial interactions.
@@ -673,16 +681,61 @@ group friends
 
 ### Filter transactions: `filter`
 
-Filters transactions based on the time of the transaction.
+Filters transactions based on the date & time of dated transactions.
+
+Format: `filter a/[TIME] b/[TIME]` OR `filter a/[TIME]` OR `filter b/[TIME]` OR `filter [TIME]`
 
-Format: `filter time a/[TIME] b/[TIME]` OR `filter time a/[TIME]` OR `filter time b/[TIME]` OR `filter time`
-* The `TIME` should be in the format `dd-MM-yyyy HHmm`.
-* The `a/` prefix is used to filter transactions that occurred after the specified time.
-* The `b/` prefix is used to filter transactions that occurred before the specified time.
+* The `TIME` should be in the format of `DD-MM-YYYY HHMM`.
+* The `a/` prefix is used to specify the earlier time bound of the search. It should be before the `b/` prefix at all times.
+* The `b/` prefix is used to specify the later time bound of the search.
+* The `filter a/[TIME] b/[TIME]` command applies for searching transactions occurring between a specified time period.
+* The `filter a/[TIME]` command applies for searching transactions after a specified date & time.
+* The `filter b/[TIME]` command applies for searching transactions before a specified date & time.
+* The `filter [TIME]` command applies for searching transactions matching a specified date & time.
 
 Example of usage:
 ```
-
+add member alice
+add member bob
+add transaction alice t/01-01-2022 2359 p/bob a/3
+add transaction alice t/01-01-2023 2359 p/bob a/3
+add transaction alice t/01-01-2024 2359 p/bob a/3
+
+filter a/01-02-2022 2359 b/01-02-2023 2359 //filtering transactions between a time period
+  The following list of transactions is between the time 01-02-2022 2359 and 01-02-2023 2359.
+  2.
+  Lender: alice
+  Transaction time: 01-01-2023 2359
+  Borrower 1: bob Owed amount: $3.00
+
+filter a/01-01-2020 2359 //filtering transactions after a specified date & time
+  The following list of transactions is after the time 01-01-2020 2359.
+  1.
+  Lender: alice
+  Transaction time: 01-01-2022 2359
+  Borrower 1: bob Owed amount: $3.00
+  2.
+  Lender: alice
+  Transaction time: 01-01-2023 2359
+  Borrower 1: bob Owed amount: $3.00
+  3.
+  Lender: alice
+  Transaction time: 01-01-2024 2359
+  Borrower 1: bob Owed amount: $3.00
+
+filter b/31-12-2022 2359 //filtering transcations before a specified date & time
+  The following list of transactions is before the time 31-12-2022 2359.
+  1.
+  Lender: alice
+  Transaction time: 01-01-2022 2359
+  Borrower 1: bob Owed amount: $3.00
+
+filter 01-01-2024 2359 //filtering transactions matching a specified date & time
+  The following list of transactions matches with the time 01-01-2024 2359.
+  3.
+  Lender: alice
+  Transaction time: 01-01-2024 2359
+  Borrower 1: bob Owed amount: $3.00
 ```
 
 ### Views the balances of all members on a chart: `chart`
@@ -732,6 +785,42 @@ close
 
 **A**: Install LongAh! on the other computer and replace the empty members, pin, and transaction TXT files it creates with the files containing your data.
 
+## Common Errors
+
+### Failure to adhere to command format
+Error messages will be output by LongAh! in the event if the user input does not match the corresponding formatting for 
+the desired operation. For e.g.
+```
+lsit transactions
+  Invalid command. Use 'help' to see the list of commands.
+```
+Or
+```
+filter 23-Nov-2022 11:59
+  Invalid DateTime format. Please format you date and time inputs in the form of DD-MM-YYYY HHmm
+```
+This could be potentially caused by
+* Misspelled Action keywords (e.g. lsit transactions instead of list transactions)
+* Absence of required user parameters
+* Absence of important formatting prefixes (e.g. t/)
+* User parameters does not follow intended standards (e.g. Wrong formatting of date & time input)
+
+### Invalid Requests
+As LongAh! is designed to specifically target transactions taking place in real-life, illogical requests going against 
+real-life/system standards may also trigger error messages. For e.g.,
+```
+add transaction alice t/20-07-2077 2359 p/bob a/200
+  Invalid DateTime input. Dates of the future are not allowed.
+```
+Or
+```
+add transaction alice p/bob a/200.0005
+  Invalid transaction value.
+```
+This could be potentially caused by
+* Invalid parameters (e.g. Dates of the future, Transaction Values more than 2 decimal places)
+* Illogical parameters (e.g. A member being both a lender and a borrower within a transaction)
+
 ## Known Issues
 
 ## Future Improvements

docs/diagrams/addDateTimeforDatedTransaction.puml

@@ -0,0 +1,27 @@
+@startuml
+participant ":TransactionList" as Foo1
+participant ":Transaction" as Foo2
+participant ":DateTime" as Foo3
+participant ":LongAhException" as Foo4
+[->      Foo1 : ""addTransaction(taskExpression, members)""
+Foo1 -> Foo1:addTransaction(expression,memberList)
+Foo1 -> Foo2: new Transaction(expression, memberList)
+Foo2 -> Foo2:parseTransaction(expression, memberList)
+alt expression contains dateTimeExpression
+    Foo2 -> Foo3:new DateTime(dateTimeExpression)
+    alt dateTimeExpression is valid
+        Foo3 --> Foo2: DateTime object created
+        Foo2 -> Foo2: Transaction DateTime added
+        ref over Foo2: Adding other transaction details
+        Foo2 --> Foo1: Transaction object created
+        Foo1 --> Foo1: Transaction added
+        Foo1 -->[      :
+    else dateTimeExpression is not in format
+        Foo3 -> Foo4:LongAhException(invalid dateTime format)
+        ref over Foo4: Handling Invalid DateTime Format
+   else dateTimeExpression is of future
+        Foo3 -> Foo4: LongAhException(invalid  dateTime input)
+        ref over Foo4: Handling Invalid DateTime Input
+   end
+end
+@enduml

docs/diagrams/comparingDateTime.puml

@@ -0,0 +1,19 @@
+@startuml
+participant ":TransactionList" as Foo
+participant ":Transaction" as Foo1
+participant ":DateTime" as Foo2
+[->      Foo:""filterTransactionsEqualToDateTime(dateTimeExpression)""
+Foo -> Foo2:new DateTime(dateTimeExpression)
+Foo2 --> Foo: DateTime object of user input created
+loop for Transaction in Transactionlist
+    Foo -> Foo1: transaction.getTransactionTime()
+    Foo1 --> Foo: DateTime object of transaction
+    Foo -> Foo2: transactionDateTime.isEqual(userDateTime)
+    Foo2 --> Foo: Boolean determining whether the two DateTimes are equal
+    alt two DateTimes are equal
+    ref over Foo1:Generate transaction printout
+    Foo1 --> Foo:Added Transaction to Transactionlist printout
+    end
+end
+Foo -->[      : ""Transactionlist printout""
+@enduml

docs/diagrams/printingDateTime.puml

@@ -0,0 +1,12 @@
+@startuml
+participant ":Transaction" as Foo
+participant ":DateTime" as Foo1
+[->      Foo:""toString()""
+alt Transaction has dateTime
+    Foo -> Foo1:toString()
+    Foo1 --> Foo: String representing dateTime
+    Foo -> Foo: Added String dateTime to printout
+end
+ref over Foo:Adding other transaction details to printout
+Foo -->[      : ""Transaction printout""
+@enduml

src/main/java/longah/util/DateTime.java

@@ -32,6 +32,12 @@ public DateTime(String dateTimeExpression) throws LongAhException {
         }
     }
 
+    /**
+     * Getter method to get the dateTime object associated with the current object instance. Currently used within the
+     * class only.
+     *
+     * @return Returns the dateTime object associated with the current instance.
+     */
     private LocalDateTime getDateTime() {
         return this.dateTime;
     }