Method dataToLayout

src/coord/matrix/Matrix.ts:181–231

* @implement * - The input is allowed to be `[NaN/null/undefined, xxx]`/`[xxx, NaN/null/undefined]`; * the return is `{x: NaN, width: NaN, y: xxxresulty, height: xxxresulth}`/ * `{y: NaN, height: NaN, x: xxxresultx, width: xxxresultw}` or clamped boundary value * if `clamp` pa

(
        data: MatrixCoordRangeOption[],
        opt?: {
            // No clamp by default, considering the possibility of supporting dataZoom (overflow/scroll).
            clamp?: MatrixClampOption | NullUndefined;
            // Expand if cell merging is encountered.
            //  - `false`: If intersecting with a rect of merged cells, expand the result to cover it.
            //      This is the default option, becuase `series.data` do not support the format
            //      `MatrixCoordRangeOption` (e.g., `[[3,5], [5,8]]`), thus merged cells can only
            //      be located by single cell locators (e.g., `[3, 5]`).
            //  - `true`: regardless of cell merging, even if the resulting rect spans accorss the merged cells.
            ignoreMergeCells?: boolean;
        },
        out?: CoordinateSystemDataLayout
    )

     *  avoid covering cell borders, if necessary.
     */
    dataToLayout(
        data: MatrixCoordRangeOption[],
        opt?: {
            // No clamp by default, considering the possibility of supporting dataZoom (overflow/scroll).
            clamp?: MatrixClampOption | NullUndefined;
            // Expand if cell merging is encountered.
            //  - `false`: If intersecting with a rect of merged cells, expand the result to cover it.
            //      This is the default option, becuase `series.data` do not support the format
            //      `MatrixCoordRangeOption` (e.g., `[[3,5], [5,8]]`), thus merged cells can only
            //      be located by single cell locators (e.g., `[3, 5]`).
            //  - `true`: regardless of cell merging, even if the resulting rect spans accorss the merged cells.
            ignoreMergeCells?: boolean;
        },
        out?: CoordinateSystemDataLayout
    ): CoordinateSystemDataLayout {
        const dims = this._dims;

        out = out || {} as CoordinateSystemDataLayout;
        const outRect = out.rect = out.rect || {} as RectLike;
        outRect.x = outRect.y = outRect.width = outRect.height = NaN;
        const outLocRange = out.matrixXYLocatorRange = resetXYLocatorRange(out.matrixXYLocatorRange);

        if (!isArray(data)) {
            if (__DEV__) {
                error('Input data must be an array in `convertToLayout`, `convertToPixel`');
            }
            return out;
        }

        parseCoordRangeOption(
            outLocRange,
            null,
            data,
            dims,
            retrieve2(opt && opt.clamp, MatrixClampOption.none)
        );

        if (!opt || !opt.ignoreMergeCells) {
            if (!opt || opt.clamp !== MatrixClampOption.corner) {
                this._model.getBody().expandRangeByCellMerge(outLocRange);
            }
            if (!opt || opt.clamp !== MatrixClampOption.body) {
                this._model.getCorner().expandRangeByCellMerge(outLocRange);
            }
        }

        xyLocatorRangeToRectOneDim(outRect, outLocRange, dims, 0);
        xyLocatorRangeToRectOneDim(outRect, outLocRange, dims, 1);

        return out;
    }

    /**
     * The returned locator pair can be the input of `dataToPoint` or `dataToLayout`.