Class CsvDocument

java.lang.Object
cloud.opencode.base.csv.CsvDocument
public final class CsvDocument extends Object
CSV Document - Immutable representation of an entire CSV document CSV文档 - 整个CSV文档的不可变表示

Represents a complete CSV document with optional headers and rows. All instances are immutable and thread-safe. Use the CsvDocument.Builder to construct documents programmatically.

表示包含可选标题和行的完整CSV文档。所有实例都是不可变且线程安全的。 使用 CsvDocument.Builder 以编程方式构建文档。

Features | 主要功能:

  • Immutable document model - 不可变文档模型
  • Optional header row - 可选标题行
  • Index and name-based column access - 基于索引和名称的列访问
  • Sub-document extraction - 子文档提取
  • Stream API support - 流API支持
  • Builder pattern - Builder模式

Usage Examples | 使用示例:

CsvDocument doc = CsvDocument.builder()
    .header("name", "age", "role")
    .addRow("Alice", "30", "Engineer")
    .addRow("Bob", "25", "Designer")
    .build();

String name = doc.getRow(0).get(0);              // "Alice"
List<String> ages = doc.getColumn("age");          // ["30", "25"]
CsvDocument sub = doc.subDocument(0, 1);           // first row only

Security | 安全性:

  • Thread-safe: Yes (immutable) - 线程安全: 是（不可变）
  • Null-safe: Headers and rows are never null - 空值安全: 标题和行永不为null
Since:
JDK 25, opencode-base-csv V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final class 
    CsvDocument.Builder
    Builder for CsvDocument CsvDocument构建器

  • Method Summary

    Modifier and Type
    Method
    Description
    static CsvDocument.Builder
    builder()
    Creates a new builder 创建新的构建器
    int
    columnCount()
    Gets the number of columns based on headers or the first row 获取基于标题或第一行的列数
    boolean
    equals(Object o)
     
    List<String>
    getColumn(int index)
    Gets all values from a column by index 通过索引获取列的所有值
    List<String>
    getColumn(String name)
    Gets all values from a column by header name 通过标题名获取列的所有值
    CsvRow
    getRow(int index)
    Gets a row by index 通过索引获取行
    int
    hashCode()
     
    List<String>
    headers()
    Gets the header names 获取标题名称
    boolean
    isEmpty()
    Checks if the document has no rows 检查文档是否没有行
    int
    rowCount()
    Gets the number of data rows (excluding header) 获取数据行数（不含标题）
    List<CsvRow>
    rows()
    Gets all rows 获取所有行
    Stream<CsvRow>
    stream()
    Returns a stream of rows 返回行的流
    CsvDocument
    subDocument(int fromRow, int toRow)
    Extracts a sub-document containing a range of rows 提取包含行范围的子文档
    String
    toString()
    Returns a string preview of the document (first 5 rows) 返回文档的字符串预览（前5行）

    Methods inherited from class Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Method Details

    • headers

      public List<String> headers()
      Gets the header names 获取标题名称
      Returns:
      unmodifiable list of headers, empty if no header row | 不可修改的标题列表，无标题行时为空

    • rows

      public List<CsvRow> rows()
      Gets all rows 获取所有行
      Returns:
      unmodifiable list of rows | 不可修改的行列表

    • getRow

      public CsvRow getRow(int index)
      Gets a row by index 通过索引获取行
      Parameters:
      index - the 0-based row index | 0起始行索引
      Returns:
      the row | 行
      Throws:
      IndexOutOfBoundsException - if index is out of range | 如果索引越界

    • getColumn

      public List<String> getColumn(String name)
      Gets all values from a column by header name 通过标题名获取列的所有值
      Parameters:
      name - the header name | 标题名
      Returns:
      unmodifiable list of values | 不可修改的值列表
      Throws:
      IllegalArgumentException - if header name is not found | 如果标题名未找到

    • getColumn

      public List<String> getColumn(int index)
      Gets all values from a column by index 通过索引获取列的所有值
      Parameters:
      index - the 0-based column index | 0起始列索引
      Returns:
      unmodifiable list of values | 不可修改的值列表
      Throws:
      IndexOutOfBoundsException - if index is negative | 如果索引为负

    • rowCount

      public int rowCount()
      Gets the number of data rows (excluding header) 获取数据行数（不含标题）
      Returns:
      the row count | 行数

    • columnCount

      public int columnCount()
      Gets the number of columns based on headers or the first row 获取基于标题或第一行的列数
      Returns:
      the column count, or 0 if empty | 列数，如果为空返回0

    • isEmpty

      public boolean isEmpty()
      Checks if the document has no rows 检查文档是否没有行
      Returns:
      true if empty | 如果为空返回true

    • stream

      public Stream<CsvRow> stream()
      Returns a stream of rows 返回行的流
      Returns:
      a stream of CsvRow | CsvRow的流

    • subDocument

      public CsvDocument subDocument(int fromRow, int toRow)
      Extracts a sub-document containing a range of rows 提取包含行范围的子文档

      The sub-document shares the same headers as this document.

      子文档与此文档共享相同的标题。

      Parameters:
      fromRow - inclusive start index | 包含的起始索引
      toRow - exclusive end index | 不包含的结束索引
      Returns:
      the sub-document | 子文档
      Throws:
      IndexOutOfBoundsException - if the range is invalid | 如果范围无效

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Returns a string preview of the document (first 5 rows) 返回文档的字符串预览（前5行）
      Overrides:
      toString in class Object
      Returns:
      string preview | 字符串预览

    • builder

      public static CsvDocument.Builder builder()
      Creates a new builder 创建新的构建器
      Returns:
      a new Builder instance | 新的Builder实例