View source for Ferreteria/v0.6/clade/Sys/Data/Things/Array/QStor

{{page/clade/v2
|fam=
{{!}} align=right  {{!}}
{{l/ver/clade|Sys\Data\Things\Array\ifaces|ARoot}}<br>
{{l/ver/clade|Sys\Data\Things\Array\ifaces\Q|XAll}}
{{!}} align=center {{!}} &rarr; {{l/ver/clade|Sys\Data\Things\Array|QStor}} &rarr;
{{!}} align=left   {{!}}
{{l/ver/clade|Sys\Data\Things\Array\QStor|AObj}}<br>
{{l/ver/clade|Sys\Data\Things\Array\QStor|Fields}}<br>
{{l/ver/clade|Aux|Register}}

|alia=
{{!-!}} '''Base'''* [c,i] {{!!}} {{l/ver/clade/full|p=ferreteria|Sys\Data\Things\Array\ifaces|ARoot}}
{{!-!}} '''QStrClass''' {{!!}} {{l/ver/clade/full|p=ferreteria|Data\Mem\QVar|Str}}
{{!-!}} '''QVarIface''' {{!!}} {{l/ver/clade/full|p=ferreteria|Data\Mem|QVar}}
{{!-!}} '''RootIface''' {{!!}} {{l/ver/clade/full|p=ferreteria|Sys\Data\Things|Array}}
{{!-!}} '''XAll'''* [i,t] {{!!}} {{l/ver/clade/full|p=ferreteria|Sys\Data\Things\Array\ifaces\Q|XAll}}

}}
==About==
* PURPOSE: Same as {{l/same|DStor}}, but all the actual elements are {{l/ver/clade|Data\Mem|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''': {{l/same|DStor}}
===Usage===
* Configure the QVar-classes to use by overriding <code>{{l/ver/fx|QVarClass}}(int|string $snKey) : string</code>.
==History==
* '''{{fmt/date|2025|04|23}}''' created
* '''{{fmt/date|2025|04|28}}''' lots of renaming & rearranging
* '''{{fmt/date|2025|07|05}}''' eliminated the trait; this is now just a class and an iface.
* '''{{fmt/date|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.
* '''{{fmt/date|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===
* <code>static function {{l/ver/fx|FromOArray}}(BaseIface $oa) : self;</code>
==Code==
''as of 2025-10-21''
{{fmt/php/block|1=
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===
===={{fmt/date|2025|10|29}}====
Commented out earlier:
{{fmt/php/block|1=
    // 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 <code>{{l/ver/fx|GetQObj}}()</code>:
{{fmt/php/block|1=
    // 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;
    }
}}
===={{fmt/date|2025|07|05}}====
Commented out 06/29:
{{fmt/php/block|1=
    // 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:
{{fmt/php/block|1=
    // ++ 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; }
}}