Ferreteria/v0.6/clade/Sys/Data/Things/Array/aux/Index

clade: Sys\Data\Things\Array\aux\Index

Clade Family StandardBase ⇒ Index ⇒ (TBD) Clade Aliases Alias Clade ArrayIface Sys\Data\Things\Array Base* [c,i] Aux\StandardBase ListIface IO\O\Data\Element\Branch\List\Indent Piece* [c,i] Sys\Data\Things\Array\aux\Piece Pieces* [c,i] Sys\Data\Things\Array\DStor\Pieces Subpages

History

• 2024-08-06 This is currently unused, but I'm not moving it to RETIRED yet because I think we might still need it when rewriting the incoming Request processes.
• 2024-08-10 renamed from [WFe]Data\Mem\Array\*IndexedData ⇒ [WFe]Data\Mem\Array\Aux\*Index
• 2025-04-29 moved from [WFe]Data\Mem\Array\Aux (I removed all of [WFe]Data\Mem\Array* a couple of days ago) ⇒ [WFe]Sys\Data\Things\Array\aux
• 2025-11-20 This is definitely being used now because it's part of the CLI command-parsing process.

Code

as of 2025-11-20:

interface iIndex extends BaseIface {
    // ++ DATA ++ //
    function Seq() : PiecesIface;
    function Key() : PiecesIface;
    function Fin() : PiecesIface;
    // ++ READ ++ //
    function PairCount() : int;
    function HasData() : bool;
    // ++ READ: single Piece
    function FirstPairRead() : PieceIface;
    function FirstPairPull() : PieceIface;
    function LastUsedPair() : PieceIface;
    // ++ READ: value ++ //
    function ValueByKey(string $sKey);    // returns variant
    function ValueNzByKey(string $sKey);  // returns variant
    // ++ WRITE ++ //
    function AddPair(string $sName, string $sValue) : PieceIface;
    // ++ DIAGS ++ //
    function DumpLine() : string;
    function DumpLines() : string;
}

class cIndex extends BaseClass implements iIndex {

    // ++ DATA ++ //

    private $oSeq = NULL;  // pairs to be processed, in sequence
    private $oKey = NULL;  // index of all pairs by key
    private $oFin = NULL;  // pairs used already

    public function Seq() : PiecesIface { return $this->oSeq ?? ($this->oSeq = PiecesClass::AsNew()); } // keyed by sequence integer
    public function Key() : PiecesIface { return $this->oKey ?? ($this->oKey = PiecesClass::AsNew()); } // keyed by data key
    public function Fin() : PiecesIface { return $this->oFin ?? ($this->oFin = PiecesClass::AsNew()); } // keyed by data key

    // -- DATA -- //
    // ++ WRITE ++ //

    protected function Clear() {
        $this->Fin()->ClearAll();
        $this->Seq()->ClearAll();
        $this->Key()->ClearAll();
    }
    protected function BuildIndex() {
        $this->Key()->ClearAll();
        $this->Fin()->ClearAll();
        foreach ($this->Seq() as $ndx => $oPiece) {
            $this->Key()->AddPiece($oPiece);
        }
    }

    protected function AddPiece(PieceIface $oPair) {
        $sName = $oPair->Name();
        $this->Key()->SetIt($sName,$oPair);
        $this->Seq()->AddIt($oPair);
    }

    public function AddPair(string $sName, string $sValue) : PieceIface {
        $oPair = new PieceClass($sName,$sValue);
        $this->AddPiece($oPair);
        return $oPair;
    }
    public function AddSlug(string $sName) {
        $oPair = new PieceClass($sName);
        $this->AddPiece($oPair);
    }

    // -- WRITE -- //
    // ++ READ ++ //

    public function PairCount() : int { return $this->Seq()->Count(); }
    public function HasData() : bool { return $this->PairCount() > 0; }

    // ++ READ: single Piece

    /**
     * ACTION: returns the first Pair in the Request (but leaves it in the Request(
     */
    public function FirstPairRead() : PieceIface {
        if ($this->PairCount() == 0) {
            echo 'First Pair requested from empty Request.';  // TODO: handle this as an internal error
            return new PieceClass;
        } else {
            $oSeq = $this->Seq();
            return $oSeq->GetSeq(0);
        }
    }
    /**
     * ACTION: Same as FirstPairRead(), but removes the Pair
     * ASSUMES: There is at least one item in the Request
     * NOTE: Does not modify the Keyed array, because it's unclear what we'd need that for.
     * HISTORY:
     *  2024-01-22 created
     *  2024-01-23 now saves removed pair to Fin()
     *  2024-01-25 oops... I mean *now* it does.
     */
    public function FirstPairPull() : PieceIface {
        $oSeq = $this->Seq();
        $oDone = $oSeq->RemoveFirst();
        $this->Fin()->AddIt($oDone);
        return $oDone;
    }
    public function LastUsedPair() : PieceIface {
        $oPair = $this->Fin()->GetFinal();
        return $oPair;
    }

    // ++ READ: value ++ //

    public function ValueByKey(string $sKey) { return $this->Key()->GetIt($sKey)->Value(); }
    public function ValueNzByKey(string $sKey) {
        $oKey = $this->Key();
        $vOut = ($oKey->HasIt($sKey))
          ? $oKey->GetIt($sKey)->Value()
          : NULL;
        return $vOut;
    }

    // -- READ -- //
    // ++ DIAGS ++ //

    public function DumpLine() : string {
        $cssArr = 'font-weight:bold; background:#ff0;';
        $htArr = "<span style='$cssArr'>";
        $sFin = $this->Fin()->DumpLine();
        $sSeq = $this->Seq()->DumpLine();
        $sKey = $this->Key()->DumpLine();
        return $htArr."FIN</span>: [$sFin] ".$htArr."SEQ</span>: [$sSeq] ".$htArr."KEY</span>: [$sKey]";
    }
    public function DumpLines() : string {
        $oScrn = self::Screen();
        $oList = $oScrn->NewList();
        echo $oList->ReflectObject()->Report();
        $this->LayoutElement($oList,'FIN',$this->Fin());
        $this->LayoutElement($oList,'SEQ',$this->Seq());
        $this->LayoutElement($oList,'KEY',$this->Key());
        return $oList->Render();
    }
    protected function LayoutElement(ListIface $oList, string $sName,ArrayIface $oa) {
        $oScrn = self::Screen();
        $ftName = $oScrn->BoldIt($sName);
        #$sOut = $oScrn->ListItem($ftName.': ');
        $oList->AddLine($sName);
        $oTable = $oList->NewTable();
        $oa->LayoutAsRows($oTable);
    }

    // -- DIAGS -- //
}