%--------------------------------------------------%
% vim: ft=mercury ts=4 sw=4 et
%--------------------------------------------------%
% Copyright (C) 2004-2006, 2011 The University of Melbourne.
% Copyright (C) 2013-2015, 2017-2019, 2022, 2024-2026 The Mercury team.
% This file is distributed under the terms specified in COPYING.LIB.
%--------------------------------------------------%
%
% File: version_array2d.m.
% Author: Ralph Becket <rafe@cs.mu.oz.au>.
% Stability: medium.
%
% Two-dimensional rectangular (i.e. not ragged) version arrays.
%
% See the header comments in version_array.m for more details about version
% structures.
%
%--------------------------------------------------%
%--------------------------------------------------%

:- module version_array2d.
:- interface.

:- import_module list.

%--------------------------------------------------%

    % A version_array2d is a two-dimensional version array which stores
    % the array in row-major order, meaning that first it stores
    % the elements of the first row in left-to-right order, then the elements
    % of the second row in the same order, and so on.
    %
:- type version_array2d(T).

    % version_array2d([[X11, ..., X1N], ..., [XM1, ..., XMN]]):
    %
    % Given a list of NumRows (M) elements, each of which is a list of
    % NumColumns (N) elements, returns the two-dimensional array
    % with NumRows rows and NumColumns columns.
    %
    % Throws an exception if the sublists are not all the same length.
    %
    % When given the empty list as input, it sets not just NumRows
    % but also NumColumns to zero.
    %
:- func version_array2d(list(list(T))) = version_array2d(T).

    % init(NumRows, NumColumns, DefaultValue):
    % uinit(NumRows, NumColumns, DefaultValue):
    %
    % Returns the two-dimensional array with the given numbers of rows and
    % columns in which every element is DefaultValue.
    %
    % Throws an exception if either NumRows or NumColumns is negative.
    %
:- func init(int, int, T) = version_array2d(T).
:- func uinit(uint, uint, T) = version_array2d(T).

    % bounds(VersionArray2d, NumRows, NumColumns):
    % ubounds(VersionArray2d, NumRows, NumColumns):
    %
    % Given VersionArray2d, returns the number of rows and columns it has.
    %
:- pred bounds(version_array2d(T)::in, int::out, int::out) is det.
:- pred ubounds(version_array2d(T)::in, uint::out, uint::out) is det.

    % in_bounds(VersionArray2d, RowNum, ColumnNum):
    % in_ubounds(VersionArray2d, RowNum, ColumnNum):
    %
    % Succeeds if-and-only-if both RowNum and ColumnNum are in-bounds
    % for VersionArray2d. If the sizes of the two dimensions of VersionArray2d
    % are NumRows and NumColumns respectively, this means that this predicate
    % succeeds if-and-only-if both 0 =< RowNum < NumRows and
    % 0 =< ColumnNum < NumColumns are true.
    %
:- pred in_bounds(version_array2d(T)::in, int::in, int::in) is semidet.
:- pred in_ubounds(version_array2d(T)::in, uint::in, uint::in) is semidet.

    % lookup(VersionArray2d, RowNum, ColumnNum, Value):
    % ulookup(VersionArray2d, RowNum, ColumnNum, Value):
    % VersionArray2d ^ elem(RowNum, ColumnNum) = Value:
    % VersionArray2d ^ uelem(RowNum, ColumnNum) = Value:
    %
    % Return the value at the given row and column numbers in VersionArray2d.
    % Note that both row and column numbers start from zero.
    %
    % Throw an exception if either RowNum or ColumnNum is out of bounds.
    %
:- pred lookup(version_array2d(T)::in, int::in, int::in, T::out) is det.
:- pred ulookup(version_array2d(T)::in, uint::in, uint::in, T::out) is det.
:- func elem(int, int, version_array2d(T)) = T.
:- func uelem(uint, uint, version_array2d(T)) = T.

    % set(RowNum, ColumnNum, X, !VersionArray2d):
    % uset(RowNum, ColumnNum, X, !VersionArray2d):
    % ( !.VersionArray2d ^ elem(RowNum, ColumnNum) := X ) = !:VersionArray2d:
    % ( !.VersionArray2d ^ uelem(RowNum, ColumnNum) := X ) = !:VersionArray2d:
    %
    % Return a version of the initial version_array2d that contains
    % all the same values, with the exception that the element at the
    % given row and column number is set to X.
    %
    % Throw an exception if either RowNum or ColumnNum is out of bounds.
    %
:- pred set(int::in, int::in, T::in,
    version_array2d(T)::in, version_array2d(T)::out) is det.
:- pred uset(uint::in, uint::in, T::in,
    version_array2d(T)::in, version_array2d(T)::out) is det.
:- func 'elem :='(int, int, version_array2d(T), T) = version_array2d(T).
:- func 'uelem :='(uint, uint, version_array2d(T), T) = version_array2d(T).

    % lists(version_array2d([[X11, ..., X1N], ..., [XM1, ..., XMN]])) =
    %     [[X11, ..., X1N], ..., [XM1, ..., XMN]]
    %
:- func lists(version_array2d(T)) = list(list(T)).

    % copy(OldVersionArray2d) = VersionArray2d:
    %
    % Returns a copy of OldVersionArray2d that has O(1) access time
    % to all its elements.
    %
:- func copy(version_array2d(T)) = version_array2d(T).

    % resize(OldVersionArray2d, NumRows, NumColumns, DefaultValue)
    %   = VersionArray2d:
    % uresize(OldVersionArray2d, NumRows, NumColumns, DefaultValue)
    %   = VersionArray2d:
    %
    % Returns a copy of OldVersionArray2d that is resized to
    % NumRows * NumColumns. Items with coordinates that exist in
    % OldVersionArray2d are copied from OldVersionArray2d; all other items
    % are initialised to DefaultValue.
    %
    % Throws an exception if either NumRows < 0 or NumColumns < 0.
    %
:- func resize(version_array2d(T), int, int, T) = version_array2d(T).
:- func uresize(version_array2d(T), uint, uint, T) = version_array2d(T).

    % unsafe_rewind(OldVersionArray2d) = VersionArray2d
    %
    % Returns a new 2d version array that has O(1) access time to all its
    % elements, at the cost of rendering the contents of OldVersionArray2d
    % and all its descendants undefined.
    %
    % Call this function *only* if you are absolutely certain that
    % there are no remaining live references to either OldVersionArray2d
    % or to any of its descendants.
    %
:- func unsafe_rewind(version_array2d(T)) = version_array2d(T).

%--------------------------------------------------%
%--------------------------------------------------%