From cca833c7dc0cd68623d12e6eab753560a6c7afec Mon Sep 17 00:00:00 2001
From: zgrguric <zgrguric@xrplwin.com>
Date: Thu, 28 Sep 2023 22:27:35 +0200
Subject: [PATCH] UNLReportFlagLedger

---
 README.md                              | 34 ++++++++++-
 src/Utilities/UNLReportFlagLedger.php  | 74 ++++++++++++++++++++++++
 tests/Unit/UNLReportFlagLedgerTest.php | 78 ++++++++++++++++++++++++++
 3 files changed, 185 insertions(+), 1 deletion(-)
 create mode 100644 src/Utilities/UNLReportFlagLedger.php
 create mode 100644 tests/Unit/UNLReportFlagLedgerTest.php

diff --git a/README.md b/README.md
index f5dd103..42d0b2a 100644
--- a/README.md
+++ b/README.md
@@ -153,9 +153,41 @@ $account_tx = $client->api('tx')->params([
     'binary' => false
 ]);
 ```
-
 For other methods refer to https://xrpl.org/websocket-api-tool.html and [src/Api/Methods](src/Api/Methods)
 
+## Utilities
+
+There are few utilities available with this package:
+- Balance changes
+- Flags
+- UNLReport Flag Ledger
+
+### Flags
+
+```PHP
+use XRPLWin\XRPL\Utilities\Flags;
+
+//Methods:
+Flags::extract(int $flags, string $transactionType): array
+Flags::description(string $transactiontype, string $flagname, bool $htmlFormat = false): string
+Flags::hasFlag(int $flags, int $check): bool
+```
+
+### UNLReportFlagLedger
+
+Flag ledger is calculated using modulo formula LedgerIndex % 256.
+
+```PHP
+use XRPLWin\XRPL\Utilities\UNLReportFlagLedger;
+
+UNLReportFlagLedger::isFlag(256);   //for ledger sequence 256 - true
+UNLReportFlagLedger::isFlag(257);   //for ledger sequence 257 - false
+UNLReportFlagLedger::prev(6873600);          //6873344
+UNLReportFlagLedger::prevOrCurrent(6873600); //6873600
+UNLReportFlagLedger::next(6873600);          //6873856
+UNLReportFlagLedger::nextOrCurrent(6873600); //6873600
+```
+
 ## Running tests
 Run all tests in "tests" directory.
 ```
diff --git a/src/Utilities/UNLReportFlagLedger.php b/src/Utilities/UNLReportFlagLedger.php
new file mode 100644
index 0000000..721bc0f
--- /dev/null
+++ b/src/Utilities/UNLReportFlagLedger.php
@@ -0,0 +1,74 @@
+<?php declare(strict_types=1);
+
+namespace XRPLWin\XRPL\Utilities;
+
+/**
+ * UNLReportFlagLedger
+ * Extract, check and process Flag ledgers for UNLReports.
+ */
+final class UNLReportFlagLedger
+{
+  /**
+   * Checks if provided ledgerIndex is flag ledger.
+   * @return bool
+   */
+  public static function isFlag(int $ledgerIndex): bool
+  {
+    if($ledgerIndex < 0)
+      throw new \Exception('Invalid negative ledger index sent');
+
+    return (($ledgerIndex % 256) === 0);
+  }
+
+  /**
+   * @param string $operator - lt|lte|gte|gt
+   */
+  public static function getFlagLedgerIndex(int $referenceLedgerIndex, string $operator): int
+  {
+    if($referenceLedgerIndex <= 0)
+      throw new \Exception('Invalid negative ledger index sent');
+
+    if($operator == 'gte' || $operator == 'lte') {
+      if(self::isFlag($referenceLedgerIndex))
+        return $referenceLedgerIndex;
+    }
+
+    if($operator == 'lte' || $operator == 'lt') {
+      $x = $referenceLedgerIndex;
+      while(true) {
+        if(self::isFlag($x) && $referenceLedgerIndex != $x)
+          return $x;
+        $x--;
+      }
+    } else if($operator == 'gte' || $operator == 'gt') {
+      $x = $referenceLedgerIndex;
+      while(true) {
+        if(self::isFlag($x) && $referenceLedgerIndex != $x)
+          return $x;
+        $x++;
+      }
+    }
+    return 0;
+  }
+
+  public static function prev(int $referenceLedgerIndex): int
+  {
+    return self::getFlagLedgerIndex($referenceLedgerIndex, 'lt');
+  }
+
+  public static function next(int $referenceLedgerIndex): int
+  {
+    return self::getFlagLedgerIndex($referenceLedgerIndex, 'gt');
+  }
+
+  public static function prevOrCurrent(int $referenceLedgerIndex): int
+  {
+    return self::getFlagLedgerIndex($referenceLedgerIndex, 'lte');
+  }
+
+  public static function nextOrCurrent(int $referenceLedgerIndex): int
+  {
+    return self::getFlagLedgerIndex($referenceLedgerIndex, 'gte');
+  }
+
+}
\ No newline at end of file
diff --git a/tests/Unit/UNLReportFlagLedgerTest.php b/tests/Unit/UNLReportFlagLedgerTest.php
new file mode 100644
index 0000000..22e3749
--- /dev/null
+++ b/tests/Unit/UNLReportFlagLedgerTest.php
@@ -0,0 +1,78 @@
+<?php declare(strict_types=1);
+
+namespace XRPLWin\XRPL\Tests\Unit;
+
+use PHPUnit\Framework\TestCase;
+use XRPLWin\XRPL\Utilities\UNLReportFlagLedger;
+
+class UNLReportFlagLedgerTest extends TestCase
+{
+  public function testIsFlag()
+  {
+    $this->assertTrue(UNLReportFlagLedger::isFlag(0));
+    $this->assertFalse(UNLReportFlagLedger::isFlag(1));
+    $this->assertFalse(UNLReportFlagLedger::isFlag(2));
+    $this->assertFalse(UNLReportFlagLedger::isFlag(3));
+    $this->assertFalse(UNLReportFlagLedger::isFlag(254));
+    $this->assertFalse(UNLReportFlagLedger::isFlag(255));
+    $this->assertTrue(UNLReportFlagLedger::isFlag(256));
+    $this->assertFalse(UNLReportFlagLedger::isFlag(6873343));
+    $this->assertTrue(UNLReportFlagLedger::isFlag(6873344));
+    $this->assertFalse(UNLReportFlagLedger::isFlag(6873345));
+    $this->assertFalse(UNLReportFlagLedger::isFlag(82855136));
+    $this->assertTrue(UNLReportFlagLedger::isFlag( (256*15875) ));
+  }
+
+  public function testprev()
+  {
+    $this->assertEquals(6873088, UNLReportFlagLedger::prev(6873344));
+    $this->assertEquals(6873344, UNLReportFlagLedger::prev(6873345));
+    $this->assertEquals(6873344, UNLReportFlagLedger::prev(6873599));
+    $this->assertEquals(6873344, UNLReportFlagLedger::prev(6873600));
+    $this->assertEquals(256, UNLReportFlagLedger::prev(257));
+    $this->assertEquals(0, UNLReportFlagLedger::prev(256));
+    $this->assertEquals(0, UNLReportFlagLedger::prev(20));
+    $this->assertEquals(0, UNLReportFlagLedger::prev(1));
+  }
+
+  public function testprevOrCurrent()
+  {
+    $this->assertEquals(6873344, UNLReportFlagLedger::prevOrCurrent(6873344));
+    $this->assertEquals(6873344, UNLReportFlagLedger::prevOrCurrent(6873345));
+    $this->assertEquals(6873344, UNLReportFlagLedger::prevOrCurrent(6873599));
+    $this->assertEquals(6873600, UNLReportFlagLedger::prevOrCurrent(6873600));
+    $this->assertEquals(256, UNLReportFlagLedger::prevOrCurrent(257));
+    $this->assertEquals(256, UNLReportFlagLedger::prevOrCurrent(256));
+    $this->assertEquals(0, UNLReportFlagLedger::prevOrCurrent(20));
+  }
+
+  public function testnext()
+  {
+    
+    $this->assertEquals(6873600, UNLReportFlagLedger::next(6873344));
+    $this->assertEquals(6873600, UNLReportFlagLedger::next(6873345));
+    $this->assertEquals(6873600, UNLReportFlagLedger::next(6873599));
+    $this->assertEquals(6873856, UNLReportFlagLedger::next(6873600));
+    $this->assertEquals(6873856, UNLReportFlagLedger::next(6873700));
+    $this->assertEquals(512, UNLReportFlagLedger::next(256));
+    $this->assertEquals(256, UNLReportFlagLedger::next(255));
+    $this->assertEquals(256, UNLReportFlagLedger::next(254));
+    $this->assertEquals(256, UNLReportFlagLedger::next(1));
+  }
+
+  public function testnextOrCurrent()
+  {
+    $this->assertEquals(6873344, UNLReportFlagLedger::nextOrCurrent(6873344));
+    $this->assertEquals(6873600, UNLReportFlagLedger::nextOrCurrent(6873345));
+    $this->assertEquals(6873600, UNLReportFlagLedger::nextOrCurrent(6873599));
+    $this->assertEquals(6873600, UNLReportFlagLedger::nextOrCurrent(6873600));
+    $this->assertEquals(6873856, UNLReportFlagLedger::nextOrCurrent(6873700));
+  }
+
+  public function testExceptions()
+  {
+    $this->expectException(\Exception::class);
+    UNLReportFlagLedger::nextOrCurrent(-1);
+  }
+
+}
\ No newline at end of file