Table.enso

from Standard.Base import all
import Standard.Base.Data.Array_Proxy.Array_Proxy
import Standard.Base.Data.Index_Sub_Range as Index_Sub_Range_Module
import Standard.Base.Data.Ordering.Comparator
import Standard.Base.Error.Common.Index_Out_Of_Bounds
import Standard.Base.Error.Common.No_Such_Method
import Standard.Base.Error.Common.Type_Error
import Standard.Base.Error.File_Error.File_Error
import Standard.Base.Error.Illegal_Argument.Illegal_Argument
import Standard.Base.Error.Incomparable_Values.Incomparable_Values
import Standard.Base.Error.Unimplemented.Unimplemented

import project.Data.Aggregate_Column.Aggregate_Column
import project.Data.Column.Column
import project.Data.Column as Column_Module
import project.Data.Column_Name_Mapping.Column_Name_Mapping
import project.Data.Column_Selector.Column_Selector
import project.Data.Data_Formatter.Data_Formatter
import project.Data.Join_Condition.Join_Condition
import project.Data.Join_Kind.Join_Kind
import project.Data.Match_Columns.Match_Columns
import project.Data.Match_Columns as Match_Columns_Helpers
import project.Data.Position.Position
import project.Data.Report_Unmatched.Report_Unmatched
import project.Data.Row.Row
import project.Data.Set_Mode.Set_Mode
import project.Data.Sort_Column.Sort_Column
import project.Data.Storage.Storage
import project.Data.Value_Type.Value_Type
import project.Internal.Aggregate_Column_Helper
import project.Internal.Java_Problems
import project.Internal.Join_Helpers
import project.Internal.Parse_Values_Helper
import project.Internal.Problem_Builder.Problem_Builder
import project.Internal.Table_Helpers
import project.Internal.Table_Helpers.Table_Column_Helper
import project.Internal.Unique_Name_Strategy.Unique_Name_Strategy
import project.Internal.Widget_Helpers
import project.Data.Expression.Expression
import project.Data.Expression.Expression_Error
import project.Delimited.Delimited_Format.Delimited_Format

from project.Data.Column_Type_Selection import Column_Type_Selection, Auto
from project.Internal.Rows_View import Rows_View
from project.Errors import all

from project.Data.Column import get_item_string
from project.Internal.Filter_Condition_Helpers import make_filter_column

polyglot java import org.enso.table.data.column.builder.object.StorageTypeMismatch
polyglot java import org.enso.table.data.table.Table as Java_Table
polyglot java import org.enso.table.data.table.Column as Java_Column
polyglot java import org.enso.table.data.table.join.Equals as Java_Join_Equals
polyglot java import org.enso.table.data.table.join.EqualsIgnoreCase as Java_Join_Equals_Ignore_Case
polyglot java import org.enso.table.data.table.join.Between as Java_Join_Between
polyglot java import org.enso.table.operations.OrderBuilder
polyglot java import org.enso.table.data.mask.OrderMask
polyglot java import java.util.UUID

## Represents a column-oriented table data structure.
type Table
    ## Creates a new table from a vector of `[name, items]` pairs.

       Arguments:
       - columns: The `[name, items]` pairs to construct a new table from.

       > Example
         Create a new table with the given columns.

             from Standard.Table import Table

             example_new =
                 first_column = ["count", [1, 2, 3]]
                 second_column = ["is_valid", [True, False, True]]
                 Table.new [first_column, second_column]
    new : Vector (Vector | Column) -> Table
    new columns =
        cols = columns.map c->
            case c of
                _ : Vector -> Column.from_vector (c.at 0) (c.at 1) . java_column
                Column.Value java_col -> java_col
        if cols.is_empty then Error.throw (Illegal_Argument.Error "Cannot create a table with no columns.") else
            if (cols.all c-> c.getSize == cols.first.getSize).not then Error.throw (Illegal_Argument.Error "All columns must have the same row count.") else
                if cols.distinct .getName . length != cols.length then Error.throw (Illegal_Argument.Error "Column names must be distinct.") else
                    Table.Value (Java_Table.new cols.to_array)

    ## Creates a new table from a vector of column names and a vector of vectors
       specifying row contents.

       Arguments:
       - header: A list of texts specifying the column names
       - rows: A vector of vectors, specifying the contents of each table row. The
         length of each element of `rows` must be equal in length to `header`.

       > Example
         Create a table with 3 columns, named `foo`, `bar`, and `baz`, containing
         `[1, 2, 3]`, `[True, False, True]`, and `['a', 'b', 'c']`, respectively.

             from Standard.Table import Table

             example_from_rows =
                 header = [ 'foo' , 'bar' , 'baz' ]
                 row_1 =  [ 1     , True  , 'a'   ]
                 row_2 =  [ 2     , False , 'b'   ]
                 row_3 =  [ 3     , True  , 'c'   ]
                 Table.from_rows header [row_1, row_2, row_3]
    from_rows : Vector -> Vector -> Table
    from_rows header rows =
        columns = header.map_with_index i-> name-> [name, rows.map (_.at i)]
        Table.new columns

    ## PRIVATE

       A table.

       Arguments:
       - java_table: The internal java representation of the table.
    Value java_table

    ## Returns a text containing an ASCII-art table displaying this data.

       Arguments:
       - show_rows: the number of initial rows that should be displayed.
       - format_terminal: whether ANSI-terminal formatting should be used

       > Example
         Convert the table to a pretty-printed representation.

             import Standard.Examples

             example_display = Examples.inventory_table.display
    display : Integer -> Boolean -> Text
    display self show_rows=10 format_terminal=False =
        cols = Vector.from_polyglot_array self.java_table.getColumns
        index =  self.java_table.getIndex
        col_names = [index.getName] + cols.map .getName
        col_vals = cols.map .getStorage
        num_rows = self.row_count
        display_rows = Math.min num_rows show_rows
        rows = Vector.new display_rows row_num->
            cols = col_vals.map col->
                if col.isNa row_num then "Nothing" else get_item_string col row_num
            [index.ilocString row_num] + cols
        table = print_table col_names rows 1 format_terminal
        if num_rows - display_rows <= 0 then table else
            missing = '\n\u2026 and ' + (num_rows - display_rows).to_text + ' hidden rows.'
            table + missing

    ## Prints an ASCII-art table with this data to the standard output.

       Arguments:
       - show_rows: the number of initial rows that should be displayed.

       > Example
         Convert the table to a pretty-printed representation and print it to
         the console.

             import Standard.Examples

             example_print = Examples.inventory_table.print
    print self show_rows=10 =
        IO.println (self.display show_rows format_terminal=True)
        IO.println ''

    ## Converts this table into a JS_Object.

       > Example
         Convert a table to a corresponding JavaScript JS_Object representation.

             import Standard.Examples

             example_to_json = Examples.inventory_table.to_js_object
    to_js_object : JS_Object
    to_js_object self =
        cols = self.columns
        rows = 0.up_to self.row_count . map row->
            vals_kv = cols.map col-> [col.name, col.at row]
            JS_Object.from_pairs vals_kv
        rows

    ## Returns the column with the given name.

       Arguments:
       - selector: The name or index of the column being looked up.

       > Example
         Get the names of all of the items from the shop inventory.

             import Standard.Examples

             example_at = Examples.inventory_table.at "item_name"

       > Example
         Get the last column.

             import Standard.Examples

             example_at = Examples.inventory_table.at -1
    @selector Widget_Helpers.make_column_name_selector
    at : Text | Integer -> Column ! No_Such_Column | Index_Out_Of_Bounds
    at self selector=0 = case selector of
        _ : Integer ->
            java_columns = Vector.from_polyglot_array self.java_table.getColumns
            Column.Value (java_columns.at selector)
        _ -> self.get selector (Error.throw (No_Such_Column.Error selector))

    ## Returns the column with the given name or index.

       Arguments:
       - selector: The name or index of the column being looked up.
       - if_missing: The value to use if the selector isn't present.

       > Example
         Get the names of all of the items from the shop inventory.

             import Standard.Examples

             example_at = Examples.inventory_table.get "item_name"

       > Example
         Get the last column.

             import Standard.Examples

             example_at = Examples.inventory_table.get -1
    @selector Widget_Helpers.make_column_name_selector
    get : Text | Integer -> Any -> Column | Any
    get self selector=0 ~if_missing=Nothing =
        java_column = case selector of
            _ : Integer -> Vector.from_polyglot_array self.java_table.getColumns . get selector
            _ : Text -> self.java_table.getColumnByName selector
            _ -> Error.throw (Illegal_Argument.Error "expected 'selector' to be either a Text or an Integer, but got "+(Meta.get_simple_type_name selector)+".")
        if java_column.is_nothing then if_missing else Column.Value java_column

    ## Gets the first column.
    first_column : Column ! Index_Out_Of_Bounds
    first_column self = self.at 0

    ## Gets the second column
    second_column : Column ! Index_Out_Of_Bounds
    second_column self = self.at 1

    ## Gets the last column
    last_column : Column ! Index_Out_Of_Bounds
    last_column self = self.at -1

    ## Returns the number of columns in the table.
    column_count : Integer
    column_count self = self.java_table.getColumns.length

    ## Returns a new table with a chosen subset of columns, as specified by the
       `columns`, from the input table. Any unmatched input columns will be
       dropped from the output.

       Arguments:
       - columns: Column selection criteria - a single instance or Vector of
         names, indexes or `Column_Selector`.
       - reorder: By default, or if set to `False`, columns in the output will
         be in the same order as in the input table. If `True`, the order in the
         output table will match the order in the columns list. If a column is
         matched by multiple selectors in reorder mode, it will be placed at
         the position of the first one matched.
       - error_on_missing_columns: Specifies if a missing input column should
         result in an error regardless of the `on_problems` settings. Defaults
         to `True`.
       - on_problems: Specifies how to handle problems if they occur, reporting
         them as warnings by default.

       ! Error Conditions

         - If there are no columns in the output table, a `No_Output_Columns` is
           raised as an error regardless of the problem behavior, because it is
           not possible to create a table without any columns.
         - If a column in `columns` is not in the input table, a
           `Missing_Input_Columns` is raised as an error, unless
           `error_on_missing_columns` is set to `False`, in which case the
           problem is reported according to the `on_problems` setting.
         - If a column index is out of range, a `Column_Indexes_Out_Of_Range` is
           raised as an error, unless `error_on_missing_columns` is set to
           `False`, in which case the problem is reported according to the
           `on_problems` setting.

       > Example
         Select columns by name.

             table.select_columns ["bar", "foo"]

       > Example
         Select columns using names passed as a Vector.

             table.select_columns ["bar", "foo"]

       > Example
         Select columns matching a regular expression.

             table.select_columns (Column_Selector.By_Name "foo.+" Case_Sensitivity.Insensitive use_regex=True)

       > Example
         Select the first two columns and the last column, moving the last one to front.

             table.select_columns [-1, 0, 1] reorder=True

       Icon: select_column
    select_columns :  Text | Integer | Column_Selector | Vector (Integer | Text | Column_Selector) -> Boolean -> Boolean -> Problem_Behavior -> Table ! No_Output_Columns | Missing_Input_Columns | Column_Indexes_Out_Of_Range
    select_columns self columns=[0] (reorder = False) (error_on_missing_columns = True) (on_problems = Report_Warning) =
        new_columns = self.columns_helper.select_columns selectors=columns reorder=reorder error_on_missing_columns=error_on_missing_columns on_problems=on_problems
        Table.new new_columns

    ## Returns a new table with the chosen set of columns, as specified by the
       `columns`, removed from the input table. Any unmatched input columns will
       be kept in the output. Columns are returned in the same order as in the
       input.

       Arguments:
       - columns: Column selection criteria - a single instance or Vector of
         names, indexes or `Column_Selector`, which are to be removed.
       - error_on_missing_columns: Specifies if a missing input column should
         result in an error regardless of the `on_problems` settings. Defaults
         to `False`.
       - on_problems: Specifies how to handle problems if they occur, reporting
         them as warnings by default.

       ! Error Conditions

         - If there are no columns in the output table, a `No_Output_Columns` is
           raised as an error regardless of the problem behavior, because it is
           not possible to create a table without any columns.
         - If a column in `columns` is not in the input table, a
           `Missing_Input_Columns` is reported according to the `on_problems`
           setting, unless `error_on_missing_columns` is set to `True`, in which
           case it is raised as an error.
         - If a column index is out of range, a `Column_Indexes_Out_Of_Range` is
           reported according to the `on_problems` setting, unless
           `error_on_missing_columns` is set to `True`, in which case it is
           raised as an error.

       > Example
         Remove columns with given names.

             table.remove_columns ["bar", "foo"]

       > Example
         Remove columns using names passed as a Vector.

             table.remove_columns ["bar", "foo"]

       > Example
         Remove columns matching a regular expression.

             table.remove_columns (Column_Selector.By_Name "foo.+" Case_Sensitivity.Insensitive use_regex=True)

       > Example
         Remove the first two columns and the last column.

             table.remove_columns [-1, 0, 1]

    remove_columns :  Text | Integer | Column_Selector | Vector (Integer | Text | Column_Selector) -> Boolean -> Problem_Behavior -> Table ! No_Output_Columns | Missing_Input_Columns | Column_Indexes_Out_Of_Range
    remove_columns self (columns=[0]) (error_on_missing_columns = False) (on_problems = Report_Warning) =
        new_columns = self.columns_helper.remove_columns selectors=columns error_on_missing_columns=error_on_missing_columns on_problems=on_problems
        Table.new new_columns

    ## Returns a new table with the specified selection of columns moved to
       either the start or the end in the specified order.

       Arguments:
       - columns: Column selection criteria - a single instance or Vector of
         names, indexes or `Column_Selector`, which should be reordered and
         specifying their order.
       - position: Specifies how to place the selected columns in relation to
         the remaining columns which were not matched by `columns` (if any).
       - error_on_missing_columns: Specifies if a missing input column should
         result in an error regardless of the `on_problems` settings. Defaults
         to `False`.
       - on_problems: Specifies how to handle problems if they occur, reporting
         them as warnings by default.

       ! Error Conditions

         - If a column in `columns` is not in the input table, a
           `Missing_Input_Columns` is reported according to the `on_problems`
           setting, unless `error_on_missing_columns` is set to `True`, in which
           case it is raised as an error.
         - If a column index is out of range, a `Column_Indexes_Out_Of_Range` is
           reported according to the `on_problems` setting, unless
           `error_on_missing_columns` is set to `True`, in which case it is
           raised as an error.

       > Example
         Move a column with a specified name to back.

             table.reorder_columns ["foo"] position=Position.After_Other_Columns

       > Example
         Move columns using names passed as a Vector.

             table.reorder_columns ["bar", "foo"] position=Position.After_Other_Columns

       > Example
         Move columns matching a regular expression to front, keeping columns matching "foo.+" before columns matching "b.*".

             table.reorder_columns (Column_Selector.By_Name "foo.+" Case_Sensitivity.Insensitive use_regex=True)

       > Example
         Swap the first two columns.

             table.reorder_columns [1, 0] position=Position.Before_Other_Columns

       > Example
         Move the first column to back.

             table.reorder_columns [0] position=Position.After_Other_Columns

    reorder_columns : Text | Integer | Column_Selector | Vector (Integer | Text | Column_Selector) -> Position -> Boolean -> Problem_Behavior -> Table ! Missing_Input_Columns | Column_Indexes_Out_Of_Range
    reorder_columns self (columns = [0]) (position = Position.Before_Other_Columns) (error_on_missing_columns = False) (on_problems = Report_Warning) =
        new_columns = self.columns_helper.reorder_columns selectors=columns position=position error_on_missing_columns=error_on_missing_columns on_problems=on_problems
        Table.new new_columns

    ## Returns a new table with the columns sorted by name according to the
       specified sort method. By default, sorting will be according to
       case-sensitive ascending order based on the normalized Unicode ordering.

       Arguments:
       - order: Whether sorting should be in ascending or descending order.
       - text_ordering: The sort methodology to use.

       > Example
         Sort columns according to the default ordering.

             table.sort_columns

       > Example
         Sort columns according to the natural case-insensitive ordering.

             table.sort_columns text_ordering=(Text_Ordering.Case_Insensitive sort_digits_as_numbers=True)

       > Example
         Sort columns in descending order.

             table.reorder_columns Sort_Direction.Descending
    sort_columns : Sort_Direction -> Text_Ordering -> Table
    sort_columns self order=Sort_Direction.Ascending text_ordering=Text_Ordering.Default =
        new_columns = Table_Helpers.sort_columns internal_columns=self.columns order text_ordering
        Table.new new_columns

    ## Returns a new table with the columns renamed based on either a mapping
       from the old name to the new or a positional list of new names.

       Arguments:
       - column_map: Mapping from old column names to new or a vector of new
         column names to apply by position.
       - error_on_missing_columns: Specifies if a missing input column should
         result in an error regardless of the `on_problems` settings. Defaults
         to `True`.
       - on_problems: Specifies how to handle problems if they occur, reporting
         them as warnings by default.

       ! Error Conditions

         - If a column in `columns` is not in the input table, a
           `Missing_Input_Columns` is raised as an error, unless
           `error_on_missing_columns` is set to `False`, in which case the
           problem is reported according to the `on_problems` setting.
         - If a column index is out of range, a `Column_Indexes_Out_Of_Range` is
           raised as an error, unless `error_on_missing_columns` is set to
           `False`, in which case the problem is reported according to the
           `on_problems` setting.
         - Other problems are reported according to the `on_problems` setting:
             - If a column is matched by two selectors resulting in a different
               name mapping, a `Ambiguous_Column_Rename`.
             - If in `By_Position` mode and more names than columns are
               provided, a `Too_Many_Column_Names_Provided`.
             - If any of the new names are invalid, an
               `Invalid_Output_Column_Names`.
             - If any of the new names clash either with existing names or each
               other, a `Duplicate_Output_Column_Names`.

       > Example
         Rename the first column to "FirstColumn"

              table.rename_columns (Column_Name_Mapping.By_Position ["FirstColumn"])

       > Example
         Rename the first column to "FirstColumn" passed as a Vector

              table.rename_columns ["FirstColumn"]

       > Example
         Add a prefix to all column names.

              table.rename_columns (table.columns.map c-> "prefix_" + c.name)

       > Example
         For all columns starting with the prefix `name=`, replace it with `key:`.

              table.rename_columns (Column_Name_Mapping.By_Name (Map.from_vector [["name=(.*)", "key:$1"]]) Regex_Matcher.Value)
    rename_columns : Map | Vector Text | Column_Name_Mapping -> Boolean -> Problem_Behavior -> Table ! Missing_Input_Columns | Column_Indexes_Out_Of_Range | Ambiguous_Column_Rename | Too_Many_Column_Names_Provided | Invalid_Output_Column_Names | Duplicate_Output_Column_Names
    rename_columns self (column_map=(Column_Name_Mapping.By_Position ["Column"])) (error_on_missing_columns=True) (on_problems=Report_Warning) = case column_map of
        _ : Vector ->
            self.rename_columns (Column_Name_Mapping.By_Position column_map) error_on_missing_columns on_problems
        _ : Map ->
            self.rename_columns (Column_Name_Mapping.By_Name column_map) error_on_missing_columns on_problems
        _ ->
            case Table_Helpers.rename_columns internal_columns=self.columns mapping=column_map error_on_missing_columns=error_on_missing_columns on_problems=on_problems of
                new_names ->
                    new_columns = self.columns.map_with_index i->c->(c.rename (new_names.at i))
                    Table.new new_columns

    ## Returns a new table with the columns renamed based on entries in the
       first row.

       Arguments:
       - on_problems: Specifies how to handle problems if they occur, reporting
         them as warnings by default.

         The following problems can occur:
         - If any of the new names are invalid, an
           `Invalid_Output_Column_Names`.
         - If any of the new names clash either with existing names or each
           other, a Duplicate_Output_Column_Names.

       > Example
         Rename the column based on the first row

              table.use_first_row_as_names
    use_first_row_as_names : Problem_Behavior -> Table
    use_first_row_as_names self (on_problems=Report_Warning) =
        mapper = col->
            val = col.at 0
            case val of
                _ : Text -> val
                Nothing -> Nothing
                _ -> val.to_text
        new_names = self.columns.map mapper
        self.drop (First 1) . rename_columns (Column_Name_Mapping.By_Position new_names) on_problems=on_problems

    ## ALIAS group, summarize

       Aggregates the rows in a table using any `Group_By` entries in columns.
       The columns argument specifies which additional aggregations to perform and to return.

       Arguments:
       - columns: Vector of `Aggregate_Column` specifying the aggregated table.
         Expressions can be used within the aggregate column to perform more
         complicated calculations.
       - error_on_missing_columns: Specifies if a missing columns in aggregates
         should result in an error regardless of the `on_problems` settings.
         Defaults to `False`, meaning that problematic aggregate will not be
         included in the result and the problem reported according to the
         `on_problems` setting.
       - on_problems: Specifies how to handle problems if they occur, reporting
         them as warnings by default.

       ! Error Conditions

         - If there are no columns in the output table, a `No_Output_Columns` is
           raised as an error regardless of the problem behavior, because it is
           not possible to create a table without any columns.
         - If a column index is out of range, a `Column_Indexes_Out_Of_Range` is
           reported according to the `on_problems` setting, unless
           `error_on_missing_columns` is set to `True`, in which case it is
           raised as an error. Problems resolving `Group_By` columns are
           reported as dataflow errors regardless of these settings, as a
           missing grouping will completely change semantics of the query.
         - If a column selector is given as a `Text` and it does not match any
           columns in the input table nor is it a valid expression, an
           `Invalid_Aggregate_Column` problem is raised according to the
           `on_problems` settings (unless `error_on_missing_columns` is set to
           `True` in which case it will always be an error). Problems resolving
           `Group_By` columns are reported as dataflow errors regardless of
           these settings, as a missing grouping will completely change
           semantics of the query.
         - If an aggregation fails, an `Invalid_Aggregation` dataflow error is
           raised.
         - Additionally, the following problems may be reported according to the
           `on_problems` setting:
           - If there are invalid column names in the output table,
             a `Invalid_Output_Column_Names`.
           - If there are duplicate column names in the output table,
             a `Duplicate_Output_Column_Names`.
           - If grouping on or computing the `Mode` on a floating point number,
             a `Floating_Point_Equality`.
           - If when concatenating values there is an quoted delimited,
             an `Unquoted_Delimiter`
           - If there are more than 10 issues with a single column,
             an `Additional_Warnings`.

       > Example
         Group by the Key column, count the rows

              table.aggregate [Aggregate_Column.Group_By "Key", Aggregate_Column.Count]
    aggregate : Vector Aggregate_Column -> Boolean -> Problem_Behavior -> Table ! No_Output_Columns | Invalid_Aggregate_Column | Invalid_Output_Column_Names | Duplicate_Output_Column_Names | Floating_Point_Equality | Invalid_Aggregation | Unquoted_Delimiter | Additional_Warnings
    aggregate self columns (error_on_missing_columns=False) (on_problems=Report_Warning) =
        validated = Aggregate_Column_Helper.prepare_aggregate_columns columns self error_on_missing_columns=error_on_missing_columns

        on_problems.attach_problems_before validated.problems <| Illegal_Argument.handle_java_exception <|
            java_key_columns = validated.key_columns.map .java_column
            index = self.java_table.indexFromColumns java_key_columns.to_array

            new_columns = validated.valid_columns.map c->(Aggregate_Column_Helper.java_aggregator c.first c.second)

            java_table = index.makeTable new_columns.to_array
            new_table = Table.Value java_table

            on_problems.attach_problems_after new_table <|
                problems = java_table.getProblems
                Java_Problems.parse_aggregated_problems problems

    ## ALIAS sort
       Sorts the rows of the table according to the specified columns and order.

       Arguments:
       - columns: The columns and order to sort the table.
       - text_ordering: The ordering method to use on text values.
       - error_on_missing_columns: Specifies if a missing input column should
         result in an error regardless of the `on_problems` settings. Defaults
         to `True`.
       - on_problems: Specifies how to handle problems if they occur, reporting
         them as warnings by default.

       ! Error Conditions

         - If a column in `columns` is not in the input table, a
           `Missing_Input_Columns` is raised as an error, unless
           `error_on_missing_columns` is set to `False`, in which case the
           problem is reported according to the `on_problems` setting.
         - If a column index is out of range, a `Column_Indexes_Out_Of_Range` is
           raised as an error, unless `error_on_missing_columns` is set to
           `False`, in which case the problem is reported according to the
           `on_problems` setting.
         - If no columns have been selected for ordering,
           a `No_Input_Columns_Selected` is raised as dataflow error regardless
           of any settings.
         - If a column used for ordering contains values that cannot be
           compared, an `Incomparable_Values` error is raised.

       ? Missing Values

         Missing (`Nothing`) values are sorted as less than any other object.

       > Example
         Sorting `table` in ascending order by the value in column `'Quantity'`.

             table.order_by ['Quantity']

       > Example
         Sorting `table` in descending order by the value in column `'Quantity'`.

             table.order_by [Sort_Column.Name 'Quantity' Sort_Direction.Descending]

       > Example
         Sorting `table` in ascending order by the value in column `'Quantity'`,
         using the value in column `'Rating'` for breaking ties.

             table.order_by ['Quantity', 'Rating']

       > Example
         Sorting `table` in ascending order by the value in column `'Quantity'`,
         using the value in column `'Rating'` in descending order for breaking
         ties.

             table.order_by [Sort_Column.Name 'Quantity', Sort_Column.Name 'Rating' Sort_Direction.Descending]

       > Example
         Order the table by the second column in ascending order. In case of any
         ties, break them based on the 7th column from the end of the table in
         descending order.

             table.order_by [1, Sort_Column.Index -7 Sort_Direction.Descending]

       > Example
         Sort the table by columns whose names start with letter `a`.

              table.order_by [(Sort_Column.Select_By_Name "a.*" use_regex=True case_sensitivity=Case_Sensitivity.Insensitive)]
    order_by : Text | Sort_Column | Vector (Text | Sort_Column) -> Text_Ordering -> Boolean -> Problem_Behavior -> Table ! Incomparable_Values | No_Input_Columns_Selected | Missing_Input_Columns | Column_Indexes_Out_Of_Range
    order_by self (columns = ([(Sort_Column.Name (self.columns.at 0 . name))])) text_ordering=Text_Ordering.Default error_on_missing_columns=True on_problems=Problem_Behavior.Report_Warning =
        problem_builder = Problem_Builder.new error_on_missing_columns=error_on_missing_columns types_to_always_throw=[No_Input_Columns_Selected]
        columns_for_ordering = Table_Helpers.prepare_order_by self.columns columns problem_builder
        problem_builder.attach_problems_before on_problems <|
            java_columns = columns_for_ordering.map c->
                c.column.java_column
            directions = columns_for_ordering.map c->
                c.associated_selector.direction.to_sign
            comparator = Comparator.for_text_ordering text_ordering
            java_table = Illegal_Argument.handle_java_exception <| Incomparable_Values.handle_errors <|
                self.java_table.orderBy java_columns.to_array directions.to_array comparator
            Table.Value java_table

    ## Returns the distinct set of rows within the specified columns from the
       input table.

       When multiple rows have the same values within the specified columns, the
       first row of each such set is returned if possible, but in database
       backends any row from each set may be returned (for example if the row
       ordering is unspecified).

       For the in-memory table, the unique rows will be in the order they
       occurred in the input (this is not guaranteed for database operations).

       Arguments:
       - columns: The columns of the table to use for distinguishing the rows.
       - case_sensitivity: Specifies if the text values should be compared case
         sensitively.
       - on_problems: Specifies how to handle if a problem occurs, raising as a
         warning by default.

       ! Error Conditions

         - If there are no columns in the output table, a `No_Output_Columns` is
           raised as an error regardless of the problem behavior, because it is
           not possible to create a table without any columns.
         - If a column in `columns` is not in the input table, a
           `Missing_Input_Columns` is raised as an error, unless
           `error_on_missing_columns` is set to `False`, in which case the
           problem is reported according to the `on_problems` setting.
         - If no valid columns are selected, a `No_Input_Columns_Selected`, is
           reported as a dataflow error regardless of setting.
         - If floating points values are present in the distinct columns, a
           `Floating_Point_Equality` is reported according to the `on_problems`
           setting.
    distinct : Text | Integer | Column_Selector | Vector (Integer | Text | Column_Selector) -> Case_Sensitivity -> Boolean -> Problem_Behavior -> Table ! No_Output_Columns | Missing_Input_Columns | No_Input_Columns_Selected | Floating_Point_Equality
    distinct self (columns = self.column_names) case_sensitivity=Case_Sensitivity.Default error_on_missing_columns=True on_problems=Report_Warning =
        key_columns = self.columns_helper.select_columns selectors=columns reorder=True error_on_missing_columns=error_on_missing_columns on_problems=on_problems . catch No_Output_Columns _->
            Error.throw No_Input_Columns_Selected
        java_columns = key_columns.map .java_column
        text_folding_strategy = Case_Sensitivity.folding_strategy case_sensitivity
        java_table = Illegal_Argument.handle_java_exception <|
            self.java_table.distinct java_columns.to_array text_folding_strategy
        on_problems.attach_problems_after (Table.Value java_table) <|
            problems = java_table.getProblems
            Java_Problems.parse_aggregated_problems problems

    ## Parses columns within a Table to a specific value type.
       By default, it looks at all `Text` columns and attempts to deduce the
       type (columns with other types are not affected). If `column_types` are
       provided, only selected columns are parsed, according to the specified
       type.

       The default parser options only parse values where the process is
       reversible (e.g., 0123 would not be converted to an integer as there is
       a leading 0). However, settings in the `Data_Formatter` can
       control this.
    parse_values : Data_Formatter -> (Nothing | Vector Column_Type_Selection) -> Problem_Behavior -> Table
    parse_values self value_formatter=Data_Formatter.Value column_types=Nothing on_problems=Report_Warning =
        columns = self.columns
        problem_builder = Vector.new_builder

        find_datatype index column =
            matching_input = column_types.filter selection->
                selector = selection.column
                case selector of
                    _ : Text -> column.name == selector
                    _ : Integer -> if selector >= 0 then index == selector else
                        index == columns.length + selector
            if matching_input.length == 0 then Nothing else
                if matching_input.length == 1 then matching_input.first.datatype else
                    first_type = matching_input.first.datatype
                    ambiguous = matching_input.any s-> s.datatype != first_type
                    problem_builder.append (Duplicate_Type_Selector.Error column.name ambiguous)
                    if ambiguous then Nothing else first_type

        expected_types = case column_types of
            Nothing -> columns.map _->Auto
            _ ->
                missing_columns = Vector.new_builder
                invalid_indices = Vector.new_builder
                column_types.each selection->
                    selector = selection.column
                    case selector of
                        _ : Integer ->
                            valid = Table_Helpers.is_index_valid columns.length selector
                            if valid.not then
                                invalid_indices.append selector
                        _ : Text ->
                            found = columns.any col-> col.name == selector
                            if found.not then
                                missing_columns.append selector
                if missing_columns.is_empty.not then
                    problem_builder.append (Missing_Input_Columns.Error missing_columns.to_vector)
                if invalid_indices.is_empty.not then
                    problem_builder.append (Column_Indexes_Out_Of_Range.Error invalid_indices.to_vector)
                columns.map_with_index find_datatype

        new_columns = columns.zip expected_types column-> expected_type-> case expected_type of
            Nothing -> column
            _ ->
                parser = if expected_type == Auto then value_formatter.make_auto_parser else
                    value_formatter.make_datatype_parser expected_type
                storage = column.java_column.getStorage
                new_storage_and_problems = parser.parseColumn column.name storage
                new_storage = new_storage_and_problems.value
                problems = Vector.from_polyglot_array new_storage_and_problems.problems . map (Parse_Values_Helper.translate_parsing_problem expected_type)
                problems.each problem_builder.append
                Column.Value (Java_Column.new column.name new_storage)

        ## TODO [RW] this case of is a workaround for wrong dataflow handling on arrays, it can be removed once the PR fixing it is merged, the relevant PR is:
           https://github.com/enso-org/enso/pull/3400
        result = Table.new new_columns
        on_problems.attach_problems_after result problem_builder.to_vector

    ## Replaces the first, last, or all occurrences of `term` with
       `new_text` in each text row of selected columns.
       If `term` is empty, the function returns the table unchanged.

       This method follows the exact replacement semantics of the
       `Text.replace` method.

       Arguments:
       - columns: Column selection criteria or a column name or index.
       - term: The term to find.
       - new_text: The new text to replace occurrences of `term` with.
         If `matcher` is a `Regex_Matcher`, `new_text` can include replacement
         patterns (such as `$<n>`) for a marked group.
       - mode: Specifies which occurences of term the engine tries to find. When the
         mode is `First` or `Last`, this method replaces the first or last occurence
         of term in each individual table cell. If set to `All`, it replaces all
         occurences of term.
       - matcher: If a `Text_Matcher`, the text is compared using case-sensitivity
         rules specified in the matcher. If a `Regex_Matcher`, the term is used as a
         regular expression and matched using the associated options.
       - on_problems: Specifies how to handle if a problem occurs, raising as a
         warning by default.

         The following problems can occur:
         - If a column in columns is not in the input table, a `Missing_Input_Columns`.
         - If a column index is out of range, a `Column_Indexes_Out_Of_Range`.
         - If a column in columns does not have a storage type of `Text`, or `Any`,
           thus it is guaranteed that it can't contain any text values, a
           `Invalid_Value_Type`.

       > Example
         Replace dashes with underscores in a column named "variable_names".

             table.replace_text "variable_names" "-" "_"

       > Example
         Remove leading and trailing spaces from cells in multiple columns.

             table.replace_text By_Name ["foo", "bar"] "^\s*(.*?)\s*$" "$1" matcher=Regex_Matcher.Value

       > Example
         Replace texts in quotes with parentheses in column at index 1.

             table.replace_text 1 '"(.*?)"' '($1)' matcher=Regex_Matcher.Value
    replace_text : Text | Integer | Column_Selector | Vector (Integer | Text | Column_Selector) -> Text -> Text -> Matching_Mode.First | Matching_Mode.Last | Regex_Mode -> (Text_Matcher | Regex_Matcher) -> Problem_Behavior -> Table
    replace_text self columns=[0] term="" new_text="" mode=Regex_Mode.All matcher=Text_Matcher.Case_Sensitive on_problems=Problem_Behavior.Report_Warning = if term.is_empty then self else
        problem_builder = Problem_Builder.new

        selection = self.columns_helper.select_columns_helper columns reorder=False problem_builder
        selected_names = Map.from_vector (selection.map column-> [column.name, True])

        map_preserve_name column f = column.map f . rename column.name
        do_replace = _.replace term new_text mode matcher
        do_replace_only_text = case _ of
                item : Text -> do_replace item
                item -> item

        transform column = case column.storage_type of
            Storage.Text -> map_preserve_name column do_replace
            Storage.Any -> map_preserve_name column do_replace_only_text
            _ ->
                problem = Invalid_Value_Type.Error Value_Type.Char column.value_type
                problem_builder.report_other_warning problem
                column

        new_columns = self.columns.map column->
            is_selected = selected_names.get column.name False
            if is_selected then transform column else column

        result = Table.new new_columns
        problem_builder.attach_problems_after on_problems result

    ## ALIAS Filter Rows

       Selects only the rows of this table that correspond to `True` values of
       `filter`.

       Arguments:
       - column: The column to use for filtering. Can be a column name, index or
         the `Column` object itself.
       - filter: The filter to apply to the column. It can either be an instance
         of `Filter_Condition` or a predicate taking a cell value and returning
         a boolean value indicating whether the corresponding row should be kept
         or not.
       - on_problems: Specifies how to handle if a non-fatal problem occurs,
         attaching a warning by default.

       ! Error Conditions

         - If a column name cannot be found, a `No_Such_Column` dataflow error
           is raised.
         - If a column index is invalid, an `Index_Out_Of_Bounds` dataflow error
           is raised.
         - If the column is an invalid type for the filter, an
           `Invalid_Value_Type` dataflow error is raised.
         - Additionally, the following problems may be reported according to the
           `on_problems` setting:
           - If filtering by equality on a floating-point column,
             a `Floating_Point_Equality`.

       > Example
         Get people older than 30.

             people.filter "Age" (Greater 30)

       > Example
         Filter people between 30 and 40.

             people.filter "Age" (Between 30 40)

       > Example
         Select rows where more than 50% of the stock is sold.

             table.filter "sold_stock" (Greater (table.at "total_stock" / 2))

       > Example
         Select people celebrating a jubilee.

             people.filter "age" (age -> (age%10 == 0))
    @column Widget_Helpers.make_column_name_selector
    @filter Filter_Condition.default_widget
    filter : (Column | Text | Integer) -> (Filter_Condition|(Any->Boolean)) -> Problem_Behavior -> Table ! No_Such_Column | Index_Out_Of_Bounds | Invalid_Value_Type
    filter self column filter=(Filter_Condition.Is_True) on_problems=Report_Warning = case column of
        _ : Column ->
            mask filter_column = Table.Value (self.java_table.mask filter_column.java_column)
            case filter of
                _ : Filter_Condition -> mask (make_filter_column column filter on_problems)
                _ : Function -> mask (column.map filter)
        _ ->
            table_at = self.at column
            self.filter table_at filter on_problems

    ## ALIAS Filter Rows

       Selects only the rows of this table that correspond to `True` values of
       `filter`.

       Arguments:
       - expression: The expression to evaluate to filter the rows.
       - on_problems: Specifies how to handle non-fatal problems, attaching a
         warning by default.

       ! Error Conditions

         - If a column name cannot be found, a `No_Such_Column` dataflow error
           is raised.
         - If the provided expression is invalid, a corresponding
           `Expression_Error` dataflow error is raised.
         - If the expression returns a column that does not have a boolean type,
           an `Invalid_Value_Type` dataflow error is raised.
         - Additionally, the following problems may be reported according to the
           `on_problems` setting:
           - If the expression checks equality on a floating-point column,
             a `Floating_Point_Equality`.
           - If an arithmetic error occurs when computing the expression,
             an `Arithmetic_Error`.
           - If more than 10 rows encounter computation issues,
             an `Additional_Warnings`.

       > Example
         Select people celebrating a jubilee.

             people.filter_by_expression "[age] % 10 == 0"
    filter_by_expression : Text -> Problem_Behavior -> Table ! No_Such_Column | Invalid_Value_Type | Expression_Error
    filter_by_expression self expression on_problems=Report_Warning =
        column = self.compute expression on_problems
        self.filter column Filter_Condition.Is_True

    ## PRIVATE
    with_no_rows self = self.take (First 0)

    ## Creates a new Table with the specified range of rows from the input
       Table.

       Arguments:
       - range: The selection of rows from the table to return.

       For the purposes of the `Index_Sub_Range.While` predicate a single
       "element" of the table is represented by the `Row` type.

       > Example
         Take first 10 rows of the table.

             table.take (First 10)

       > Example
         Take rows from the top of the table as long as their values sum to 10.

             table.take (While row-> row.to_vector.compute Statistic.Sum == 10)
    take : (Index_Sub_Range | Range | Integer) -> Table
    take self range=(First 1) =
        Index_Sub_Range_Module.take_helper self.row_count self.rows.at self.slice (slice_ranges self) range

    ## Creates a new Table from the input with the specified range of rows
       removed.

       Arguments:
       - range: The selection of rows from the table to remove.

       For the purposes of the `Index_Sub_Range.While` predicate a single
       "element" of the table is represented by the `Row` type.

       > Example
         Drop first 10 rows of the table.

             table.drop (First 10)

       > Example
         Drop rows from the top of the table as long as their values sum to 10.

             table.drop (While row-> row.to_vector.compute Statistic.Sum == 10)
    drop : (Index_Sub_Range | Range | Integer) -> Table
    drop self range=(First 1) =
        Index_Sub_Range_Module.drop_helper self.row_count self.rows.at self.slice (slice_ranges self) range

    ## UNSTABLE
       ALIAS Add Column, Update Column

       Sets the column value at the given name.

       Arguments:
       - column: The new column or expression to create column.
       - new_name: Optional new name for the column.
       - set_mode: Specifies the expected behaviour in regards to existing
         column with the same name.
       - on_problems: Specifies how to handle problems with expression
         evaluation.

       ! Error Conditions

         - In the Database backend, if the column name is not valid, an
           `Unsupported_Name` dataflow error is raised.
         - If the column name is already present and `set_mode` is `Add`, a
           `Existing_Column` dataflow error is raised.
         - If the column name is not present and `set_mode` is `Update`, a
           `Missing_Column` dataflow error is raised.
         - If a column name referenced from within an expression cannot be
           found, a `No_Such_Column` dataflow error is raised.
         - If the provided expression is invalid, a corresponding
           `Expression_Error` dataflow error is raised.
         - The following problems with expression evaluation may be reported
           according to the `on_problems` setting:
           - If the expression checks equality on a floating-point column,
             a `Floating_Point_Equality`.
           - If an arithmetic error occurs when computing the expression,
             an `Arithmetic_Error`.
           - If more than 10 rows encounter computation issues,
             an `Additional_Warnings`.

       > Example
         Create a table where the values of the total stock in the inventory is
         doubled.

             import Standard.Examples

             example_set =
                 table = Examples.inventory_table
                 double_inventory = table.at "total_stock" * 2
                 table.set double_inventory new_name="total_stock"
                 table.set "2 * [total_stock]" new_name="total_stock_expr"
    set : Column | Text -> Text | Nothing -> Problem_Behavior -> Table ! Existing_Column | Missing_Column | No_Such_Column | Expression_Error
    set self column new_name=Nothing set_mode=Set_Mode.Add_Or_Update on_problems=Report_Warning =
        resolved = case column of
            _ : Text -> self.compute column on_problems
            _ : Column -> column
        renamed = if new_name.is_nothing then resolved else resolved.rename new_name
        to_add = case set_mode of
            Set_Mode.Add_Or_Update -> True
            Set_Mode.Add -> if self.java_table.getColumnByName renamed.name . is_nothing then True else
                Error.throw (Existing_Column.Error renamed.name)
            Set_Mode.Update -> if self.java_table.getColumnByName renamed.name . is_nothing . not then True else
                Error.throw (Missing_Column.Error renamed.name)

        if to_add then Table.Value (self.java_table.addOrReplaceColumn renamed.java_column) else to_add

    ## Given an expression, create a derived column where each value is the
       result of evaluating the expression for the row.

       Arguments:
       - expression: The expression to evaluate.
       - on_problems: Specifies how to handle non-fatal problems, attaching a
         warning by default.

       ! Error Conditions

         - If a column name cannot be found, a `No_Such_Column` dataflow error
           is raised.
         - If the provided expression is invalid, a corresponding
           `Expression_Error` dataflow error is raised.
         - Additionally, the following problems may be reported according to the
           `on_problems` setting:
           - If the expression checks equality on a floating-point column,
             a `Floating_Point_Equality`.
           - If an arithmetic error occurs when computing the expression,
             an `Arithmetic_Error`.
           - If more than 10 rows encounter computation issues,
             an `Additional_Warnings`.
    compute : Text -> Problem_Behavior -> Column ! No_Such_Column | Invalid_Value_Type | Expression_Error
    compute self expression on_problems=Report_Warning =
        get_column name = self.at name
        make_constant value = Column.from_vector_repeated (UUID.randomUUID.to_text) [value] self.row_count
        new_column = Expression.evaluate expression get_column make_constant "Standard.Table.Data.Column" "Column" Column.var_args_functions
        problems = Warning.get_all new_column . map .value
        new_name = Expression.to_column_name expression
        result = new_column.rename new_name
        on_problems.attach_problems_before problems <|
            Warning.set result []

    ## Returns the vector of columns contained in this table.

       > Examples
         Get a vector containing the columns in the table.

             import Standard.Examples

             example_columns = Examples.inventory_table.columns
    columns : Vector
    columns self = Vector.from_polyglot_array <|
        Array_Proxy.new self.java_table.getColumns.length i->
            Column.Value (self.java_table.getColumns.at i)

    ## UNSTABLE

       Returns the vector of column names contained in this table.
    column_names : Vector Text
    column_names self = Vector.from_polyglot_array <|
        Array_Proxy.new self.java_table.getColumns.length i->
            self.java_table.getColumns.at i . getName

    ## Returns a vector of rows contained in this table.

       In the database backend, it first materializes the table to in-memory.

       Arguments:
       - max_rows: The maximum amount of rows to return. It is mainly meant for
         the Database backend, to limit how many rows are downloaded. In the
         in-memory backend it is only kept for API compatibility.
    rows : Integer -> Vector Row
    rows self max_rows=Nothing =
        table = case max_rows of
            Nothing -> self
            _ : Integer -> self.slice 0 max_rows
        proxy = Rows_View.Value table
        Vector.from_polyglot_array (Array_Proxy.from_proxy_object proxy)

    ## Joins two tables according to the specified join conditions.

       Arguments:
       - right: The table to join with.
       - join_kind: The `Join_Kind` for the joining the two tables.
       - on: A single condition or a common column name, or a list thereof, on
         which to correlate rows from the two tables. If multiple conditions
         are supplied, rows are correlated only if all are true.
         If common column names are provided, these columns should be present
         in both tables and an equality condition is added for each of them.
       - right_prefix: The prefix added to right table column names in case of
         name conflict.
       - on_problems: Specifies how to handle problems if they occur, reporting
         them as warnings by default.

         - If a column name cannot be found, a `No_Such_Column` is reported
           and an empty result is reported.
         - If a column index is invalid, an `Index_Out_Of_Bounds` is
           reported and an empty result is reported.
         - If there are column names that are clashing between the two tables, a
           `Duplicate_Output_Column_Names` is reported and the columns from the
           table are renamed as described below.
         - If a join condition correlates columns whose types are not compatible
           (for example comparing numeric types with text), an
           `Invalid_Value_Type` is reported.
         - If decimal columns are joined on equality, a
           `Floating_Point_Equality` is reported.

         In any of the above cases, if a problem occurs, the resulting table
         will have the desired structure, but it will be empty to indicate that
         the join has failed due to an erroneous join condition.

       ? Column Renaming

         If columns from the two tables have colliding names, a prefix (by
         default `Right_`) is added to the name of the column from the right
         table. The left column remains unchanged. It is possible that the new
         name will be in use, in this case it will be resolved using the normal
         renaming strategy - adding subsequent `_1`, `_2` etc.

       ? Result Ordering

         The ordering of rows in the resulting table is not specified.

       ? Joining on equality of columns with the same name

         When joining two columns with the same name and an equality condition,
         only one copy of column will be included in the output (avoiding
         unnecessary duplication and renaming).

       ? Same-name column join shorthand

         As a shorthand, providing a column name or a list of column names
         allows to join the two tables on equality of corresponding columns with
         the same name. So `table.join other on=["A", "B"]` is a shorthand for:
             table.join other on=[Join_Condition.Equals "A" "A", Join_Condition.Equals "B" "B"]
    @join_kind Widget_Helpers.join_kind_selector
    @on Widget_Helpers.make_column_name_selector
    join : Table -> Join_Kind -> Join_Condition | Text | Vector (Join_Condition | Text) -> Text -> Problem_Behavior -> Table
    join self right join_kind=Join_Kind.Inner on=[Join_Condition.Equals 0 0] right_prefix="Right_" on_problems=Report_Warning =
        if check_table "right" right then
                # [left_unmatched, matched, right_unmatched]
                rows_to_keep = case join_kind of
                    Join_Kind.Inner           -> [False, True, False]
                    Join_Kind.Left_Outer      -> [True, True, False]
                    Join_Kind.Right_Outer     -> [False, True, True]
                    Join_Kind.Full            -> [True, True, True]
                    Join_Kind.Left_Exclusive  -> [True, False, False]
                    Join_Kind.Right_Exclusive -> [False, False, True]

                columns_to_keep = case join_kind of
                    Join_Kind.Left_Exclusive  -> [True, False]
                    Join_Kind.Right_Exclusive -> [False, True]
                    _                         -> [True, True]

                join_resolution = make_join_helpers self right . resolve on on_problems
                right_columns_to_drop = join_resolution.redundant_column_names

                object_comparator = Comparator.new
                equality_fallback = .==

                java_conditions = join_resolution.conditions
                new_java_table = self.java_table.join right.java_table java_conditions (rows_to_keep.at 0) (rows_to_keep.at 1) (rows_to_keep.at 2) (columns_to_keep.at 0) (columns_to_keep.at 1) right_columns_to_drop right_prefix object_comparator equality_fallback

                on_problems.attach_problems_after (Table.Value new_java_table) <|
                    problems = new_java_table.getProblems
                    Java_Problems.parse_aggregated_problems problems

    ## ALIAS Cartesian Join
       Joins tables by pairing every row of the left table with every row of the
       right table.

       Arguments:
       - right: The table to join with.
       - right_row_limit: If the number of rows in the right table exceeds this,
         then a `Cross_Join_Row_Limit_Exceeded` problem is raised. The check
         exists to avoid exploding the size of the table by accident. This check
         can be disabled by setting this parameter to `Nothing`.
       - right_prefix: The prefix added to right table column names in case of
         name conflict. See "Column Renaming" below for more information.
       - on_problems: Specifies how to handle problems if they occur, reporting
         them as warnings by default.

         - If the `right` table has more rows than the `right_row_limit` allows,
           a `Cross_Join_Row_Limit_Exceeded` is reported. In warning/ignore
           mode, the join is still executed.

       ? Column Renaming

         If columns from the two tables have colliding names, a prefix (by
         default `Right_`) is added to the name of the column from the right
         table. The left column remains unchanged. It is possible that the new
         name will be in use, in this case it will be resolved using the normal
         renaming strategy - adding subsequent `_1`, `_2` etc.

       ? Result Ordering

         Rows in the result are first ordered by the order of the corresponding
         rows from the left table and then the order of rows from the right
         table. This applies only if the order of the rows was specified (for
         example, by sorting the table; in-memory tables will keep the memory
         layout order while for database tables the order may be unspecified).
    cross_join : Table -> Integer | Nothing -> Text -> Problem_Behavior -> Table
    cross_join self right right_row_limit=100 right_prefix="Right_" on_problems=Report_Warning =
        if check_table "right" right then
            limit_problems = case right_row_limit.is_nothing.not && (right.row_count > right_row_limit) of
                True ->
                    [Cross_Join_Row_Limit_Exceeded.Error right_row_limit right.row_count]
                False -> []
            on_problems.attach_problems_before limit_problems <|
                new_java_table = self.java_table.crossJoin right.java_table right_prefix
                renaming_problems = new_java_table.getProblems |> Java_Problems.parse_aggregated_problems
                on_problems.attach_problems_before renaming_problems (Table.Value new_java_table)

    ## ALIAS Join By Row Position
       Joins two tables by zipping rows from both tables table together - the
       first row of the left table is correlated with the first one of the right
       one etc.

       Arguments:
       - right: The table to join with.
       - keep_unmatched: If set to `True`, the result will include as many rows
         as the larger of the two tables - the last rows of the larger table
         will have nulls for columns of the smaller one. If set to `False`, the
         result will have as many rows as the smaller of the two tables - the
         additional rows of the larger table will be discarded. The default
         value is `Report_Unmatched` which means that the user expects that two
         tables should have the same amount of rows; if they do not, the
         behaviour is the same as if it was set to `True` - i.e. the unmatched
         rows are kept with `Nothing` values for the other table, but a
         `Row_Count_Mismatch` problem is also reported.
       - right_prefix: The prefix added to right table column names in case of
         name conflict. See "Column Renaming" below for more information.
       - on_problems: Specifies how to handle problems if they occur, reporting
         them as warnings by default.

         - If the tables have different number of rows and `keep_unmatched` is
           set to `Report_Unmatched`, the join will report `Row_Count_Mismatch`.

       ? Column Renaming

         If columns from the two tables have colliding names, a prefix (by
         default `Right_`) is added to the name of the column from the right
         table. The left column remains unchanged. It is possible that the new
         name will be in use, in this case it will be resolved using the normal
         renaming strategy - adding subsequent `_1`, `_2` etc.

       ? Row Ordering

         This operation requires a well-defined order of rows in the input
         tables. In-memory tables rely on the ordering stemming directly from
         their layout in memory. Database tables may not impose a deterministic
         ordering. If the table defines a primary key, it is used to by default
         to ensure deterministic ordering. That can be overridden by specifying
         a different ordering using `Table.order_by`. If no primary key was
         defined nor any ordering was specified explicitly by the user, the
         order of columns is undefined and the operation will fail, reporting a
         `Undefined_Column_Order` problem and returning an empty table.
    zip : Table -> Boolean | Report_Unmatched -> Text -> Problem_Behavior -> Table
    zip self right keep_unmatched=Report_Unmatched right_prefix="Right_" on_problems=Report_Warning =
        if check_table "right" right then
            keep_unmatched_bool = case keep_unmatched of
                Report_Unmatched -> True
                b : Boolean -> b
            report_mismatch = keep_unmatched == Report_Unmatched

            left_row_count = self.row_count
            right_row_count = right.row_count
            problems = if (left_row_count == right_row_count) || report_mismatch.not then [] else
                [Row_Count_Mismatch.Error left_row_count right_row_count]
            on_problems.attach_problems_before problems <|
                new_java_table = self.java_table.zip right.java_table keep_unmatched_bool right_prefix
                renaming_problems = new_java_table.getProblems |> Java_Problems.parse_aggregated_problems
                on_problems.attach_problems_before renaming_problems (Table.Value new_java_table)

    ## ALIAS append, concat
       Appends records from other table(s) to this table.

       Arguments:
       - tables: A single table or a vector of tables to append to this one. The
         tables are concatenated in the order they are specified, with `self`
         being the first one.
       - match_columns: Specifies how to match the columns.
         - If `Match_Columns.By_Name` - the columns are matched by name across
           all provided tables.
           If unmatched columns are to be dropped, the resulting table will keep
           only the set of columns that appear in all provided tables, in the
           relative order that they appeared in the `self` table.
           If unmatched columns are kept, they are added in the order of
           appearance - i.e. first all columns from `self` will be added in the
           original order, then any columns from the second table that were not
           matched will be added at the end (preserving their relative order),
           and so on for all the remaining tables.
         - If `Match_Columns.By_Position` - the columns are mapped by position.
           If unmatched columns are to be dropped, the resulting table will have
           as many columns as the table that had the least columns and the
           column names of the first table (self) will be used.
           If unmatched columns are kept, the resulting table will have as many
           columns as the table with the most columns. Since the first table may
           not have all the necessary columns to provide column names for the
           result, the result will have column names taken from the first table
           that has the biggest number of columns.
       - keep_unmatched_columns: If set to `True`, unmatched columns are kept
         and are padded with `Nothing` for tables that did not have them.
         If set to `False`, only the common subset of columns is kept - any
         column that is not present in all tables is dropped. Defaults to
         `Report_Unmatched`, which behaves like `True` - unmatched columns are
         kept and padded with `Nothing`, but a problem is reported.
       - allow_type_widening: Specifies if the resulting column type should be
         adjusted to fit columns from all arguments. If `True`, a common type
         will be chosen for each column (see "Unifying Column Types" below).
         If `False`, the resulting column type will be the same as in the first
         table containing the column. In this case, all columns that are
         concatenated must have the same type as the first one (unless this
         had a `Mixed` type - in which case it will accept any other types).
       - on_problems: Specifies how to handle problems if they occur, reporting
         them as warnings by default.

         - If `keep_unmatched_columns` is set to `Report_Unmatched` (the
           default):
           - If matching by name and there are columns that are not present in
             all tables, `Unmatched_Columns` is reported.
           - If matching by position and column counts of the merged tables
             differ, then a `Column_Count_Mismatch` is reported. The error will
             contain the greatest column count as its `expected` value and the
             smallest one as its `actual` value.
         - If `keep_unmatched_columns` is set to `False` and matching by name,
           it is possible that there are no columns that are common to all
           provided tables, in that case `No_Output_Columns` is thrown as a
           dataflow error regardless of the `on_problems` setting, because there
           are no columns to include in the resulting table.
         - If type widening is disabled and one of corresponding columns has a
           type that is incompatible with the type coming from the first table,
           a `Column_Type_Mismatch` is reported. The problematic column will be
           dropped from the resulting table. With type widening disabled, the
           subsequent tables must have the same types as the first one, unless
           the type of the first one was `Mixed` which will accept any other
           type.
         - If a common type coercion for a set of matched columns from
           concatenated tables cannot be found, a `No_Common_Type` is reported.
           In warning or ignore mode, the problematic column will be dropped
           from the resulting table.

       ? Unifying Column Types

         If `allow_type_widening` is set to `True`, then the following rules are
         used to find a common type that will fit values from all merged tables.

         Numeric columns are unified by finding the most general type that can
         fit all of the columns. The biggest integer type will be chosen and if
         integers and decimals are mixed, the decimal type will be chosen.
         If boolean columns are mixed with numeric columns, they will be coerced
         to the numeric type (and converted to 0 and 1).

         Text types will also be coerced according to the common rules - if
         constant-length texts of different lengths are mixed, they will be
         coerced to a varying-length type.

         If one of the matched columns has `Mixed` type, that type will be used
         regardless of types of other columns. Mixing any other types will
         result in a `No_Common_Type` problem. If columns of incompatible types
         are meant to be mixed, at least one of them should be explicitly
         retyped to the `Mixed` type to indicate that intention.
    union : (Table | Vector Table) -> Match_Columns -> Boolean | Report_Unmatched -> Boolean -> Problem_Behavior -> Table
    union self tables match_columns=Match_Columns.By_Name keep_unmatched_columns=Report_Unmatched allow_type_widening=True on_problems=Report_Warning =
        all_tables = case tables of
            v : Vector -> [self] + v
            single_table -> [self, single_table]
        ## `is_everything_ok` should actually never be False; it will either be
           True or will contain a dataflow error propagating through the if.
        is_everything_ok = all_tables.all (check_table "tables")
        if is_everything_ok then
            problem_builder = Problem_Builder.new
            matched_column_sets = Match_Columns_Helpers.match_columns all_tables match_columns keep_unmatched_columns problem_builder
            result_row_count = all_tables.fold 0 c-> t-> c + t.row_count
            merged_columns = matched_column_sets.map column_set->
                case Table_Helpers.unify_result_type_for_union column_set all_tables allow_type_widening problem_builder of
                    Nothing -> Nothing
                    result_type : Value_Type ->
                        concat_columns column_set all_tables result_type result_row_count
            good_columns = merged_columns.filter Filter_Condition.Not_Nothing
            if good_columns.is_empty then Error.throw No_Output_Columns else
                problem_builder.attach_problems_before on_problems <|
                    Table.new good_columns

    ## ALIAS dropna
       ALIAS drop_missing_rows
       Remove rows which are all blank or containing blank values.

       Arguments:
       - when_any: If `True`, then remove any row containing any blank values.
         If `False`, then only remove rows with all blank values.
       - treat_nans_as_blank: If `True`, then `Number.nan` is considered as blank.

       ? Blank values
         Blank values are `Nothing`, `""` and depending on setting `Number.nan`.
    filter_blank_rows : Boolean -> Boolean -> Table
    filter_blank_rows self when_any=False treat_nans_as_blank=False =
        Table_Helpers.filter_blank_rows self when_any treat_nans_as_blank

    ## ALIAS count
       Returns the number of rows in this table.

       > Example
         Count the number of rows in the table.

             import Standard.Examples

             example_row_count = Examples.inventory_table.row_count
    row_count : Integer
    row_count self = self.java_table.rowCount

    ## Returns a Table describing this table's contents.

       The table lists all columns, counts of non-null items and storage types
       of each column.

       > Example
         Get information about a table.

             import Standard.Examples

             example_info = Examples.inventory_table.info
    info : Table
    info self =
        cols = self.columns
        Table.new [["Column", cols.map .name], ["Items Count", cols.map .count], ["Storage Type", cols.map .storage_type]]

    ## Returns a new table with a chosen subset of columns left unchanged and
       the other columns pivoted to rows with a single name field and a single
       value field.

       Arguments:
       - id_fields: Set of fields to remain as columns. These values will be
         repeated for each data field that is pivoted.
       - name_field: The name of the field that will contain the names of the
         pivoted fields. If this name is already in use, it will be renamed
         with a numeric suffix.
       - value_field: The name of the field that will contain the values of the
         pivoted fields. If this name is already in use, it will be renamed
         with a numeric suffix.
       - on_problems: Specifies how to handle problems if they occur, reporting
         them as warnings by default.

       ! Error Conditions

         - If there are no columns in the output table, a `No_Output_Columns` is
           raised as an error regardless of the problem behavior, because it is
           not possible to create a table without any columns.
         - If a column in `columns` is not in the input table, a
           `Missing_Input_Columns` is raised as an error, unless
           `error_on_missing_columns` is set to `False`, in which case the
           problem is reported according to the `on_problems` setting.
         - If a column index is out of range, a `Column_Indexes_Out_Of_Range` is
           raised as an error, unless `error_on_missing_columns` is set to
           `False`, in which case the problem is reported according to the
           `on_problems` setting.
         - If any column names in the new table are clashing, a
           `Duplicate_Output_Column_Names` is reported according to the
           `on_problems` setting.
    transpose : Text | Integer | Column_Selector | Vector (Integer | Text | Column_Selector) -> Text -> Text -> Boolean -> Problem_Behavior -> Table ! No_Output_Columns | Missing_Input_Columns | Column_Indexes_Out_Of_Range | Duplicate_Output_Column_Names
    transpose self (id_fields = []) (name_field="Name") (value_field="Value") (error_on_missing_columns=True) (on_problems = Report_Warning) =
        columns_helper = self.columns_helper
        unique = Unique_Name_Strategy.new
        problem_builder = Problem_Builder.new error_on_missing_columns=error_on_missing_columns

        id_columns = columns_helper.select_columns_helper id_fields False problem_builder

        selected_names = Map.from_vector (id_columns.map column-> [column.name, True])

        data = columns_helper.internal_columns.filter column->(selected_names.get column.name False . not)
        java_data = data.map .java_column

        java_id = id_columns.map .java_column

        unique.mark_used (id_columns.map .name)
        result = Table.Value (Java_Table.transpose java_id.to_array java_data.to_array (unique.make_unique name_field) (unique.make_unique value_field))
        problem_builder.report_unique_name_strategy unique

        problem_builder.attach_problems_after on_problems result

    ## Returns a new table using a chosen field as the column header and then
       aggregating the rows within each value as specified. Optionally, a set of
       fields can be used to group the rows.

       Arguments:
       - group_by: Set of fields to group by. If not provided, a single row will
         be produced.
       - name_column: The field to use as the column header. If this field is
         not found, then each value will be a single column.
       - values: The aggregation to perform on each set of rows. Can be a single
         aggregation or a vector of aggregations. Expressions can be used within
         the aggregation to perform more complicated calculations.
       - on_problems: Specifies how to handle problems if they occur, reporting
         them as warnings by default.

       ! Error Conditions

         - If a column in `group_by` or `name_field` is not in the input table,
           a `Missing_Input_Columns` is raised as a dataflow error.
         - If a column index in `group_by`, `name_field` or `values` is out of
           range, a `Column_Indexes_Out_Of_Range` is raised as a dataflow error.
         - If a column selector in `values` given as a `Text` and it does not
           match any columns in the input table nor is it a valid expression, an
           `Invalid_Aggregate_Column` dataflow error is raised.
         - If an aggregation fails, an `Invalid_Aggregation` dataflow error is
           raised.
         - Additionally, the following problems may be reported according to the
           `on_problems` setting:
           - If grouping on, using as the column name, or computing the `Mode` on
             a floating point number, a `Floating_Point_Equality`.
           - If when concatenating values there is an quoted delimited,
             an `Unquoted_Delimiter`
           - If there are more than 10 issues with a single column,
             an `Additional_Warnings`.
    cross_tab : Text | Integer | Column_Selector | Vector (Integer | Text | Column_Selector) -> (Text | Integer) -> Vector Aggregate_Column -> Problem_Behavior -> Table ! Missing_Input_Columns | Column_Indexes_Out_Of_Range | Invalid_Aggregate_Column | Floating_Point_Equality | Invalid_Aggregation | Unquoted_Delimiter | Additional_Warnings
    cross_tab self group_by=[] name_column=self.column_names.first values=Aggregate_Column.Count (on_problems=Report_Warning) =
        columns_helper = self.columns_helper
        problem_builder = Problem_Builder.new error_on_missing_columns=True

        ## validate the name and group_by columns
        name_column_selector = case name_column of
            ix : Integer -> [ix]
            name : Text -> [name]
            _ -> Error.throw (Illegal_Argument.Error "name_column must be a column index or name.")
        matched_name = columns_helper.select_columns_helper name_column_selector True problem_builder
        grouping = columns_helper.select_columns_helper group_by True problem_builder

        ## Validate the values
        values_vector = case values of
            _ : Vector -> values
            _ -> [values]
        resolved_values = values_vector.map (Aggregate_Column_Helper.resolve_aggregate self problem_builder)
        is_group_by c = case c of
            Aggregate_Column.Group_By _ _ -> True
            _ -> False
        validated_values = if resolved_values.any is_group_by then Error.throw (Illegal_Argument.Error "Cannot use group_by for a cross_tab value.") else
            resolved_values.filter c->(c!=Nothing)

        problem_builder.attach_problems_before on_problems <| Illegal_Argument.handle_java_exception <|
            java_key_columns = grouping.map .java_column
            index  = self.java_table.indexFromColumns java_key_columns.to_array

            name_mapper = if matched_name.is_empty then Aggregate_Column_Helper.default_aggregate_column_name else
                if validated_values.length == 1 then (_ -> "") else
                    all_same = Aggregate_Column_Helper.all_same_column validated_values
                    c -> Aggregate_Column_Helper.default_aggregate_column_name c all_same

            data_columns = validated_values.map c->
                col_name = c.new_name.if_nothing <|
                    Aggregate_Column_Helper.default_aggregate_column_name c
                Aggregate_Column_Helper.java_aggregator col_name c

            result = case matched_name.is_empty of
                True ->
                    group_by = grouping.map g->(Aggregate_Column_Helper.java_aggregator g.name (Aggregate_Column.Group_By g))
                    index.makeTable (group_by + data_columns).to_array
                False ->
                    aggregate_names = validated_values.map c->
                        c.new_name.if_nothing (name_mapper c)
                    index.makeCrossTabTable java_key_columns matched_name.first.java_column data_columns aggregate_names

            on_problems.attach_problems_after (Table.Value result) <|
                problems = result.getProblems
                Java_Problems.parse_aggregated_problems problems

    ## PRIVATE
       Returns a table with a continuous sub-range of rows taken.
    slice : Integer -> Integer -> Table
    slice self start end =
        length = self.row_count
        offset = Math.max (Math.min start length) 0
        limit = Math.max (Math.min (end - offset) (length - offset)) 0
        Table.Value (self.java_table.slice offset limit)

    ## UNSTABLE

       Returns a table containing the rows of `self` table with their order
       reversed.

       > Example
         Reverse the rows in a table.

             import Standard.Examples

             example_reverse = Examples.inventory_table.reverse
    reverse : Table
    reverse self =
        mask = OrderBuilder.buildReversedMask self.row_count
        Table.Value <| self.java_table.applyMask mask

    ## ALIAS Write JSON
       UNSTABLE

       Writes this table to a specified file, serialized into JSON. The JSON
       serialization is such that the result is an array, in which every entry
       is an object representing a single row, with column names as keys.

       Arguments:
       - file: the file to write data to. If the file exists, it will be
         overwritten.

       > Example
         Write a table to a JSON file.

             import Standard.Examples

             example_to_json = Examples.inventory_table.write_json (enso_project.data / 'example.json')
    write_json : File -> Nothing
    write_json self file = self.to_json.write file

    ## This function writes a table from memory into a file.

       The specific behavior of the various `File_Format`s is specified below.

       Arguments:
       - path: The path to the output file.
       - format: The format of the file.
         If `Auto_Detect` is specified; the provided file determines the
         specific type and configures it appropriately. Details of this type are
         below.
       - on_existing_file: Specified how to handle if the file already exists.
       - match_columns: Specifies how to match columns against an existing file.
         If `Match_Columns.By_Name` - the columns are mapped by name against an
         existing file. If there is a mismatch, then a `Column_Name_Mismatch`
         error is raised.
         If `Match_Columns.By_Position` - the columns are mapped by position
         against an existing file. If there is a mismatch, then a
         `Column_Count_Mismatch` error is raised.
       - on_problems: Specifies how to handle if a problem occurs, raising as a
         warning by default. The specific issues depend on the `File_Format`
         argument.

       Returns:
       - If an unsupported `File_Format` is specified, an
         `Illegal_Argument` is raised.
       - If the path to the parent location cannot be found or the filename is
         invalid, a `File_Error.Not_Found` is raised.
       - If another IO error occurs, such as access denied, an
         `File_Error.IO_Error` is raised.
       - If appending and the columns do not match, a `Column_Mismatch` is
         raised.
       - Other specific errors or warnings that can be raised depend on the
         format argument.
       - Otherwise, the file is loaded following the rules of the format
         parameter.

       ? `File_Format` write behaviors

         - `Auto_Detect`: The file format is determined by the provided file.
         - `Bytes` and `Plain_Text`: The Table does not support these types in
           the `write` function. If passed as format, an
           `Illegal_Argument` is raised. To write out the table as plain
           text, the user needs to call the `Text.from Table` method and then
           use the `Text.write` function.

       > Example
         Write a table to a CSV file, without writing the header.

             import Standard.Examples
             from Standard.Table import Delimited

             example_to_csv = Examples.inventory_table.write (Enso_Project.data / "example_csv_output.csv") (Delimited delimiter="," headers=False)

       > Example
         Write a table to an XLSX file.

             import Standard.Examples
             from Standard.Table import Excel

             example_to_xlsx = Examples.inventory_table.write (enso_project.data / "example_xlsx_output.xlsx") Excel
    write : File|Text -> File_Format -> Existing_File_Behavior -> Match_Columns -> Problem_Behavior -> Nothing ! Column_Count_Mismatch | Illegal_Argument | File_Error
    write self path format=Auto_Detect on_existing_file=Existing_File_Behavior.Backup match_columns=Match_Columns.By_Name on_problems=Report_Warning =
        file = File.new path
        case format of
            _ : Auto_Detect ->
                base_format = format.get_format file
                if base_format == Nothing then Error.throw (File_Error.Unsupported_Type file) else
                    self.write file format=base_format on_existing_file match_columns on_problems
            _ ->
                Panic.catch No_Such_Method.Error (format.write_table file self on_existing_file match_columns on_problems) _->
                    name = (Meta.meta format).constructor.name
                    Error.throw (Illegal_Argument.Error ("Saving a Table as " + name + " is not supported."))

    ## Creates a text representation of the table using the CSV format.
    to_csv : Text
    to_csv self = Text.from self (Delimited_Format.Delimited delimiter=",")

    ## PRIVATE
    columns_helper : Table_Column_Helper
    columns_helper self =
        Table_Helpers.Table_Column_Helper.Value self.columns (x->x) self (x->x)

## PRIVATE

   Ensures that the `txt` has at least `len` characters by appending spaces at
   the end.

   Arguments:
   - txt: The text to pad.
   - len: The minimum length of the text.
pad : Text -> Integer -> Text
pad txt len =
    true_len = txt.characters.length
    txt + (" ".repeat (len - true_len))

## PRIVATE

   Adds ANSI bold escape sequences to text if the feature is enabled.

   Arguments:
   - enabled: will insert ANSI sequences only if this flag is true and we are not on Windows.
   - txt: The text to possibly bold.
ansi_bold : Boolean -> Text -> Text
ansi_bold enabled txt =
    case Platform.os of
        ## Output formatting for Windows is not currently supported.
        Platform.OS.Windows -> txt
        _ -> if enabled then '\e[1m' + txt + '\e[m' else txt

## PRIVATE

   A helper function for creating an ASCII-art representation of tabular data.

   Arguments:
   - header: vector of names of columns in the table.
   - rows: a vector of rows, where each row is a vector that contains a text
     representation of each cell
   - indices_count: the number specifying how many columns should be treated as
     indices; this will make them in bold font if `format_term` is enabled.
   - format_term: a boolean flag, specifying whether to use ANSI escape codes
     for rich formatting in the terminal.
print_table : Vector Text -> (Vector (Vector Text)) -> Integer -> Boolean -> Text
print_table header rows indices_count format_term =
    content_lengths = Vector.new header.length i->
        max_row = 0.up_to rows.length . fold 0 a-> j-> Math.max a (rows.at j . at i . characters . length)
        Math.max max_row (header.at i . characters . length)
    header_line = header.zip content_lengths pad . map (ansi_bold format_term) . join ' | '
    divider = content_lengths . map (l -> "-".repeat l+2) . join '+'
    row_lines = rows.map r->
        x = r.zip content_lengths pad
        ixes = x.take (First indices_count) . map (ansi_bold format_term)
        with_bold_ix = ixes + x.drop (First indices_count)
        y = with_bold_ix . join ' | '
        " " + y
    ([" " + header_line, divider] + row_lines).join '\n'

## PRIVATE
   A helper to create a new table consisting of slices of the original table.
slice_ranges table ranges =
    normalized = Index_Sub_Range_Module.normalize_ranges ranges
    Table.Value (table.java_table.slice normalized.to_array)

## PRIVATE
make_join_helpers left_table right_table =
    make_equals _ left right = Java_Join_Equals.new left.java_column right.java_column
    make_equals_ignore_case _ left right locale =
        Java_Join_Equals_Ignore_Case.new left.java_column right.java_column locale.java_locale
    make_between _ left right_lower right_upper =
        Java_Join_Between.new left.java_column right_lower.java_column right_upper.java_column
    Join_Helpers.Join_Condition_Resolver.Value (left_table.at _) (right_table.at _) make_equals make_equals_ignore_case make_between

## PRIVATE
   Checks if the argument is a proper table and comes from the current backend.
   It returns True or throws a dataflow error explaining the issue.
check_table arg_name table =
    if Table_Helpers.is_table table . not then Error.throw (Type_Error.Error Table table arg_name) else
            same_backend = table.is_a Table
            case same_backend of
                False ->
                    Error.throw (Illegal_Argument.Error "Currently cross-backend operations are not supported. Materialize the table using `.read` before mixing it with an in-memory Table.")
                True -> True

## PRIVATE
   A helper that efficiently concatenates storages of in-memory columns.
concat_columns column_set all_tables result_type result_row_count =
    storage_builder = Column_Module.make_storage_builder_for_type result_type initial_size=result_row_count
    column_set.column_indices.zip all_tables i-> parent_table->
        case i of
            Nothing ->
                null_row_count = parent_table.row_count
                storage_builder.appendNulls null_row_count
            _ : Integer ->
                storage = parent_table.at i . java_column . getStorage
                storage_builder.appendBulkStorage storage
    Column.from_storage column_set.name storage_builder.seal