Add LaTeX array environment (PR 1/3): model fields + factory constructor (#251)

* [item 1] Add verticalLines/horizontalLines fields to MTMathTable

Adds inert NSArray<NSNumber*>* verticalLines/horizontalLines properties to
MTMathTable, defaulting to empty arrays and deep-copied in -copyWithZone:.
No behavior change for existing environments (fields are unused until the
array environment factory constructor consumes them).


* [item 2] Add +arrayTableWithAlignments factory constructor

Adds MTMathAtomFactory +arrayTableWithAlignments:verticalLines:horizontalLines:rows:error:,
which builds a bare textstyle MTMathTable for the array environment from
already-validated structured input (alignments/vertical-line counts computed
by the future column-spec parser). horizontalLines is normalized to
numRows+1 entries so the renderer can index every row boundary.

* [item 3] Validate array row cell counts (too-many-cells / short-row)

Pins the too-many-cells and short-row contract of
+arrayTableWithAlignments:verticalLines:horizontalLines:rows:error: with
explicit tests. The validation guard itself was already introduced in
item 2; no production code changes here.

* Declare verticalLines/horizontalLines copy for snapshot safety

The new NSArray properties were strong (default), so the setter aliased
the caller's array by reference. The factory itself assigns a mutable
hLines behind the NSArray*-typed horizontalLines, so a later in-place
mutation would leak into the stored table. Declare both properties copy
(the standard Cocoa idiom for an immutable-snapshot NSArray, O(1) when
the source is already immutable). With the copy setters, copyWithZone:
no longer needs arrayWithArray: — a plain assignment snapshots.

Adds a test that mutating a mutable array after assignment does not
change the stored value.

* Pad short array rows to numCols; normalize verticalLines (review)

Address gemini review on #251:
- Pad short rows out to numCols so a trailing all-empty column keeps its
  alignment and vertical rule (numColumns is derived from the widest row).
- Normalize verticalLines to numCols+1 (mirrors horizontalLines) and guard
  nil for both nonnull line params.

Not adopted: the reviewer's out-of-bounds crash framing and the truncation
of over-long line arrays. -columnOffsetsForTable: already bounds-guards every
access (i < vLines.count ? ... : 0) and the rule loops iterate the arrays'
own counts, so a short/over-long array cannot crash; truncating would also
silently swallow caller mistakes.


Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: kostub

iosMath/lib/MTMathAtomFactory.h

@@ -210,6 +210,21 @@ FOUNDATION_EXPORT NSString *const MTSymbolDegree;
  matrix environments are have builtin delimiters added to the table and hence are returned as inner atoms.
  */
 + (nullable MTMathAtom*) tableWithEnvironment:(nullable NSString*) env rows:(NSArray<NSArray<MTMathList*>*>*) rows error:(NSError**) error;
+
+/**
+ Construct a bare `array`-environment table from already-validated structured input.
+ The parser owns all column-spec syntax validation; this method only validates row
+ cell counts against `columnAlignments.count` and assembles the table.
+ @param columnAlignments one MTColumnAlignment per declared column.
+ @param verticalLines `|` counts per column boundary (length columnAlignments.count+1).
+ @param horizontalLines `\hline` counts per row boundary (normalized here to numRows+1).
+ @returns a bare MTMathTable (no delimiters), or nil + error on too-many-cells.
+ */
++ (nullable MTMathAtom*) arrayTableWithAlignments:(NSArray<NSNumber*>*) columnAlignments
+                                    verticalLines:(NSArray<NSNumber*>*) verticalLines
+                                  horizontalLines:(NSArray<NSNumber*>*) horizontalLines
+                                             rows:(NSArray<NSArray<MTMathList*>*>*) rows
+                                            error:(NSError**) error;
 @end
 
 NS_ASSUME_NONNULL_END

iosMath/lib/MTMathAtomFactory.m

@@ -527,6 +527,59 @@ + (nullable MTMathAtom *)tableWithEnvironment:(NSString *)env rows:(NSArray<NSAr
     return nil;
 }
 
++ (nullable MTMathAtom*) arrayTableWithAlignments:(NSArray<NSNumber*>*) columnAlignments
+                                    verticalLines:(NSArray<NSNumber*>*) verticalLines
+                                  horizontalLines:(NSArray<NSNumber*>*) horizontalLines
+                                             rows:(NSArray<NSArray<MTMathList*>*>*) rows
+                                            error:(NSError**) error
+{
+    MTMathTable* table = [[MTMathTable alloc] initWithEnvironment:@"array"];
+    NSInteger numCols = columnAlignments.count;
+    for (int i = 0; i < rows.count; i++) {
+        NSArray<MTMathList*>* row = rows[i];
+        if ((NSInteger) row.count > numCols) {
+            if (error) {
+                NSString* message = [NSString stringWithFormat:
+                    @"array row has %ld cells but column specification declares %ld columns",
+                    (long) row.count, (long) numCols];
+                *error = [NSError errorWithDomain:MTParseError
+                                             code:MTParseErrorInvalidNumColumns
+                                         userInfo:@{ NSLocalizedDescriptionKey : message }];
+            }
+            return nil;
+        }
+        for (int j = 0; j < row.count; j++) {
+            [table setCell:row[j] forRow:i column:j];
+        }
+        // Pad short rows out to numCols. numColumns is derived from the widest row,
+        // so without this a trailing all-empty column (its alignment + vertical rule)
+        // would be silently dropped. setCell backfills the intermediate cells.
+        if ((NSInteger) row.count < numCols) {
+            [table setCell:[MTMathList new] forRow:i column:numCols - 1];
+        }
+    }
+    for (int j = 0; j < numCols; j++) {
+        [table setAlignment:columnAlignments[j].integerValue forColumn:j];
+    }
+    // Normalize verticalLines to length numCols+1 so every declared column boundary is
+    // represented (mirrors horizontalLines below). Guard nil for the nonnull property.
+    NSMutableArray<NSNumber*>* vLines = [NSMutableArray arrayWithArray:verticalLines ?: @[]];
+    while ((NSInteger) vLines.count < numCols + 1) {
+        [vLines addObject:@0];
+    }
+    table.verticalLines = vLines;
+    // Normalize horizontalLines to length numRows+1 so the renderer can index boundaries.
+    NSMutableArray<NSNumber*>* hLines = [NSMutableArray arrayWithArray:horizontalLines ?: @[]];
+    while (hLines.count < table.numRows + 1) {
+        [hLines addObject:@0];
+    }
+    table.horizontalLines = hLines;
+    table.interRowAdditionalSpacing = 0;
+    table.interColumnSpacing = 18;   // ≈ 2·\arraycolsep at the default size; matches matrix.
+    table.cellStyle = kMTLineStyleText;   // post-#245: cells render textstyle via the table.
+    return table;
+}
+
 + (NSMutableDictionary<NSString*, MTMathAtom*>*) supportedLatexSymbols
 {
     static NSMutableDictionary<NSString*, MTMathAtom*>* commands = nil;

iosMath/lib/MTMathList.h

@@ -728,6 +728,16 @@ typedef NS_ENUM(NSInteger, MTColumnAlignment) {
 /// measures the inter-column/row glue in this style.
 @property (nonatomic) MTLineStyle cellStyle;
 
+/// The number of `|` vertical rules at each column boundary (array environment).
+/// Length numColumns+1: index 0 = before column 0 … numColumns = after the last column.
+/// Empty for every non-array environment (inert default — no layout effect).
+@property (nonatomic, copy, nonnull) NSArray<NSNumber*>* verticalLines;
+
+/// The number of `\hline` horizontal rules at each row boundary (array environment).
+/// Length numRows+1: index 0 = above row 0 … numRows = below the last row.
+/// Empty for every non-array environment (inert default — no layout effect).
+@property (nonatomic, copy, nonnull) NSArray<NSNumber*>* horizontalLines;
+
 /// Set the value of a given cell. The table is automatically resized to contain this cell.
 - (void) setCell:(MTMathList*) list forRow:(NSInteger) row column:(NSInteger) column;
 

iosMath/lib/MTMathList.m

@@ -1178,6 +1178,8 @@ - (instancetype)initWithEnvironment:(NSString *)env
         self.interRowAdditionalSpacing = 0;
         self.interColumnSpacing = 0;
         self.cellStyle = kMTLineStyleInherit;
+        self.verticalLines = [NSArray array];
+        self.horizontalLines = [NSArray array];
         _environment = env;
     }
     return self;
@@ -1206,6 +1208,9 @@ - (id)copyWithZone:(NSZone *)zone
     op.cellStyle = self.cellStyle;
     op->_environment = self.environment;
     op.alignments = [NSMutableArray arrayWithArray:self.alignments];
+    // The copy setters take an immutable snapshot, so a plain assignment suffices.
+    op.verticalLines = self.verticalLines;
+    op.horizontalLines = self.horizontalLines;
     // Perform a deep copy of the cells.
     NSMutableArray* cellCopy = [NSMutableArray arrayWithCapacity:self.cells.count];
     for (NSMutableArray* row in self.cells) {

iosMathTests/MTMathListTest.m

@@ -302,6 +302,130 @@ - (void) testCopy
     [MTMathListTest checkListCopy:list2 original:list forTest:self];
 }
 
+- (void)testMathTableVerticalHorizontalLinesDefaultAndCopy
+{
+    MTMathTable* table = [[MTMathTable alloc] init];
+    // Default: both empty (inert — existing envs unaffected).
+    XCTAssertNotNil(table.verticalLines);
+    XCTAssertNotNil(table.horizontalLines);
+    XCTAssertEqual(table.verticalLines.count, 0);
+    XCTAssertEqual(table.horizontalLines.count, 0);
+
+    table.verticalLines = @[ @1, @0, @2 ];
+    table.horizontalLines = @[ @1, @0 ];
+    MTMathTable* copy = [table copy];
+    XCTAssertEqualObjects(copy.verticalLines, (@[ @1, @0, @2 ]));
+    XCTAssertEqualObjects(copy.horizontalLines, (@[ @1, @0 ]));
+    // Mutating the original's field must not affect the copy.
+    table.verticalLines = @[ @9 ];
+    XCTAssertEqualObjects(copy.verticalLines, (@[ @1, @0, @2 ]));
+
+    // The properties take an immutable snapshot: mutating a mutable array
+    // *after* assigning it must not change the stored value (copy semantics).
+    NSMutableArray<NSNumber*>* mutV = [@[ @1, @2 ] mutableCopy];
+    NSMutableArray<NSNumber*>* mutH = [@[ @3 ] mutableCopy];
+    table.verticalLines = mutV;
+    table.horizontalLines = mutH;
+    [mutV addObject:@99];
+    [mutH addObject:@99];
+    XCTAssertEqualObjects(table.verticalLines, (@[ @1, @2 ]));
+    XCTAssertEqualObjects(table.horizontalLines, (@[ @3 ]));
+}
+
+- (void)testArrayTableFactoryBuildsBareTextstyleTable
+{
+    MTMathList* a = [MTMathListBuilder buildFromString:@"a"];
+    MTMathList* b = [MTMathListBuilder buildFromString:@"b"];
+    MTMathList* c = [MTMathListBuilder buildFromString:@"c"];
+    MTMathList* d = [MTMathListBuilder buildFromString:@"d"];
+    NSArray* rows = @[ @[ a, b ], @[ c, d ] ];
+
+    NSError* error = nil;
+    MTMathAtom* atom = [MTMathAtomFactory
+        arrayTableWithAlignments:@[ @(kMTColumnAlignmentRight), @(kMTColumnAlignmentLeft) ]
+                   verticalLines:@[ @1, @0, @1 ]
+                 horizontalLines:@[ @1 ]
+                            rows:rows
+                           error:&error];
+    XCTAssertNil(error);
+    XCTAssertNotNil(atom);
+    // Bare table — no MTInner / delimiters wrapping.
+    XCTAssertEqual(atom.type, kMTMathAtomTable);
+    MTMathTable* table = (MTMathTable*) atom;
+    XCTAssertEqualObjects(table.environment, @"array");
+    XCTAssertEqual(table.numRows, 2);
+    XCTAssertEqual(table.numColumns, 2);
+    XCTAssertEqual([table getAlignmentForColumn:0], kMTColumnAlignmentRight);
+    XCTAssertEqual([table getAlignmentForColumn:1], kMTColumnAlignmentLeft);
+    XCTAssertEqualObjects(table.verticalLines, (@[ @1, @0, @1 ]));
+    // horizontalLines normalized to numRows+1 == 3.
+    XCTAssertEqualObjects(table.horizontalLines, (@[ @1, @0, @0 ]));
+    XCTAssertEqual(table.interColumnSpacing, 18);
+    XCTAssertEqual(table.interRowAdditionalSpacing, 0);
+    XCTAssertEqual(table.cellStyle, kMTLineStyleText);
+}
+
+- (void)testArrayTableFactoryRejectsTooManyCells
+{
+    MTMathList* a = [MTMathListBuilder buildFromString:@"a"];
+    MTMathList* b = [MTMathListBuilder buildFromString:@"b"];
+    // Spec declares 1 column but the row has 2 cells.
+    NSError* error = nil;
+    MTMathAtom* atom = [MTMathAtomFactory
+        arrayTableWithAlignments:@[ @(kMTColumnAlignmentCenter) ]
+                   verticalLines:@[ @0, @0 ]
+                 horizontalLines:@[]
+                            rows:@[ @[ a, b ] ]
+                           error:&error];
+    XCTAssertNil(atom);
+    XCTAssertNotNil(error);
+    XCTAssertEqual(error.code, MTParseErrorInvalidNumColumns);
+    XCTAssertEqualObjects(error.localizedDescription,
+        @"array row has 2 cells but column specification declares 1 columns");
+}
+
+- (void)testArrayTableFactoryAcceptsShortRows
+{
+    MTMathList* a = [MTMathListBuilder buildFromString:@"a"];
+    // Spec declares 3 columns; row has 1 cell — allowed. The short row is padded out
+    // to 3 cells so the declared trailing columns (alignment + vertical rule) survive.
+    NSError* error = nil;
+    MTMathAtom* atom = [MTMathAtomFactory
+        arrayTableWithAlignments:@[ @(kMTColumnAlignmentCenter),
+                                    @(kMTColumnAlignmentCenter),
+                                    @(kMTColumnAlignmentCenter) ]
+                   verticalLines:@[ @0, @0, @0, @0 ]
+                 horizontalLines:@[]
+                            rows:@[ @[ a ] ]
+                           error:&error];
+    XCTAssertNil(error);
+    XCTAssertNotNil(atom);
+    MTMathTable* table = (MTMathTable*) atom;
+    XCTAssertEqual(table.numColumns, 3);
+    XCTAssertEqual([table.cells[0] count], 3);
+}
+
+- (void)testArrayTableFactoryNormalizesVerticalLines
+{
+    MTMathList* a = [MTMathListBuilder buildFromString:@"a"];
+    MTMathList* b = [MTMathListBuilder buildFromString:@"b"];
+    // Caller passes a too-short verticalLines (and nil horizontalLines); the factory
+    // pads verticalLines to numCols+1 and tolerates nil rather than crashing.
+    NSError* error = nil;
+    MTMathAtom* atom = [MTMathAtomFactory
+        arrayTableWithAlignments:@[ @(kMTColumnAlignmentCenter),
+                                    @(kMTColumnAlignmentCenter) ]
+                   verticalLines:@[ @1 ]
+                 horizontalLines:nil
+                            rows:@[ @[ a, b ] ]
+                           error:&error];
+    XCTAssertNil(error);
+    XCTAssertNotNil(atom);
+    MTMathTable* table = (MTMathTable*) atom;
+    XCTAssertEqual(table.verticalLines.count, 3);   // numCols(2) + 1
+    XCTAssertEqualObjects(table.verticalLines, (@[ @1, @0, @0 ]));
+}
+
 @end
 
 @interface MTMathAtomTest : XCTestCase