Ferreteria/v0.6/clade/Sys/Data/Things/Array/QStor

clade: Sys\Data\Things\Array\QStor

Clade Family ARoot XAll → QStor → AObj Fields Register Clade Aliases Alias Clade Base* [c,i] Sys\Data\Things\Array\ifaces\ARoot QStrClass Data\Mem\QVar\Str QVarIface Data\Mem\QVar RootIface Sys\Data\Things\Array XAll* [i,t] Sys\Data\Things\Array\ifaces\Q\XAll Subpages AStr

About

• PURPOSE: Same as DStor, but all the actual elements are QVar objects stored in a core OArray.
  • It uses the same base clade but implements the internal stuff differently.
• THINKING: This is so that we can return reliably-writable QVar objects.
  • IOW: QStor returns R/W objects, while DStor returns read-only (you have to go to the array-object directly to write).
• Parallel: DStor

Usage

• Configure the QVar-classes to use by overriding QVarClass(int|string $snKey) : string.

History

• 2025-04-23 created
• 2025-04-28 lots of renaming & rearranging
• 2025-07-05 eliminated the trait; this is now just a class and an iface.
• 2025-07-13 Design change: for QStor arrays, elements can be either string *OR* QStr.
  • It keeps happening that it's expecting one but gets the other, and I can't think of any way it causes problems to just allow both/either.
• 2025-10-28 Allowing this, however, leads to data-type tangles that are very difficult to trace. I restored the original restrictions several days ago.

Functions

public

• static function FromOArray(BaseIface $oa) : self;

Code

as of 2025-10-21

interface iQStor extends BaseIface, RootIface, XAllIface {
    static function FromOArray(BaseIface $oa) : self;
}
class cQStor extends BaseClass implements iQStor {
    use XAllTrait;

    // ++ SETUP ++ //

    protected function __construct() {}

    public static function FromOArray(BaseIface $oa) : iQStor {
        $oThis = new static;
        $oThis->SetStore($oa);
        return $oThis;
    }

    // ++ SETUP: dynamic ++ //

    // CEMENT
    protected function WithVArray(array $ar) : void { $this->SetVals($ar); }

    // -- SETUP -- //
    // ++ ACCESS ++ //

    // OVERRIDE
    public function SetIt(int|string $snKey, mixed $vVal) : void {
        //+DEBUGGING
        $os = $this->GetItQ($snKey);
        $os->SetIt($vVal);
        #$n = $this->Count();
        #echo " ## VALUES STORED: ".count($this->GetVals())." ($n)".CRLF;
        $os2 = $this->GetItQ($snKey);
        $sReg = $this->ObjectInfo();
        echo " ## in $sReg: STORING [$snKey]: [".self::DiagnoseValue($os->GetIt()).'],['.self::DiagnoseValue($os2->GetIt()).']'.CRLF;
        //-DEBUGGING
        #$this->GetItQ($snKey)->SetIt($vVal);
    }
    protected function SetItQ(int|string $snKey, QVarIface $os) : void {
        $ar =& $this->GetStore();
        $ar[$snKey] = $os;
        #echo " -- after [$snKey], [".count($this->GetStore()).'] and ['.count($ar).']'.CRLF;
    }

    // OVERRIDE: values are inside Q-vars, which are the array element values
    public function SetVals(array $ar) {
        foreach ($ar as $snKey => $vVal) {
            #$this->GetItQ($snKey)->SetIt($vVal);
            $this->SetIt($snKey,$vVal);
        }
    }
    // OVERRIDE
    public function GetIt(int|string $snKey) : mixed {
        return $this->GetItQ($snKey)->GetIt();
    }
    protected function GetQObj(int|string $snKey) : QVarIface { return $this->ar[$snKey]; }
    static protected function ToString(QVarIface|string $vElem) : string {
        if (is_string($vElem)) {
            return $vElem;
        } else {
            return $vElem->GetIt();
        }
    }

    // NEW
    public function GetItQ(int|string $snKey) : QVarIface {
        if ($this->HasIt($snKey)) {
            #$this->AmHere("GOT EXISTING [$snKey]");
            $os = $this->GetQObj($snKey);
        } else {
            #$this->AmHere("CREATING NEW [$snKey]");
            $os = ($this->QVarClass($snKey))::AsNew();
            $this->SetItQ($snKey,$os);
        }
        return $os;
    }

    // -- ACCESS -- //
}

Removed

2025-10-29

Commented out earlier:

// OVERRIDE: values are inside Q-vars, which are the array element values
    // 2025-10-20 This duplicates code in XAllTrait
    public function GetVals() : array {
        $arVals = [];
        $arObjs = $this->ar;
        foreach ($arObjs as $snKey => $vElem) {
            $vVal = static::ToValue($vElem);
            $arVals[$snKey] = $vVal;
        }
        return $arVals;
    }

and also this, which used to work with the too-forgiving version of GetQObj():

// ACTION: Unwraps any QVar objects, returns anything else directly (A BIT KLUGEY)
    // How is there this but also an eponymous non-static function in Q\Series?
    static protected function ToValue(mixed $vElem) : mixed {
        if (is_a($vElem,QVarIface::class)) {
            $vRtn = $vElem->GetStrNzN();
        } else {
            $vRtn = $vElem;
        }
        return $vRtn;
    }

2025-07-05

Commented out 06/29:

// 2025-06-29 before Q-remediation
    public function GetItQ(int|string $snKey) : QVarIface {
      #echo $this->ReflectThis()->Report(); die(); // is $this an OArray?
      #echo "GetItQ() KEY=[$snKey] ";
        if ($this->OArray()->HasIt($snKey)) {
            $os = $this->OArray()->GetIt($snKey);
            #echo 'FOUND: ['.$os->HasIt().'] ';
        } else {
            #echo 'CREATING NEW ';
            $os = ($this->QVarClass($snKey))::AsNew();
            $this->OArray()->SetIt($snKey,$os);
        }
        #echo CRLF;
        return $os;
    }

Removed 06/28:

// ++ SETUP: dynamic ++ //

    // 2025-06-30 I don't think this piece should exist.
    private $oa = NULL;
    protected function WithOArray(CoreClass $oa) { $this->oa = $oa; }
    protected function OArray() : CoreClass { return $this->oa; }