Class CsvTransform

java.lang.Object
cloud.opencode.base.csv.transform.CsvTransform
public final class CsvTransform extends Object
CSV Transform - Fluent, immutable transformation pipeline for CsvDocument CSV转换 - CsvDocument的流式不可变转换管道

Provides a fluent API for transforming CSV documents by renaming, reordering, adding, removing, and mapping columns. Each method returns a new CsvTransform instance (immutable chain pattern). All transformations are applied in sequence when the terminal execute() method is called.

提供用于转换CSV文档的流式API，支持重命名、重新排序、添加、删除和映射列。 每个方法返回一个新的CsvTransform实例（不可变链模式）。所有转换在调用终端 execute() 方法时按顺序执行。

Features | 主要功能:

  • Immutable transformation chain - 不可变转换链
  • Lazy execution on terminal operation - 终端操作时延迟执行
  • Column rename (single and batch) - 列重命名（单个和批量）
  • Column reorder, add, remove - 列重新排序、添加、删除
  • Column value mapping - 列值映射
  • Row-level transformation - 行级转换
  • Column filtering by predicate - 按谓词过滤列

Usage Examples | 使用示例:

CsvDocument result = CsvTransform.from(doc)
    .renameColumn("name", "fullName")
    .addColumn("status", "active")
    .removeColumns("role")
    .mapColumn("fullName", String::toUpperCase)
    .execute();

Security | 安全性:

  • Thread-safe: Yes (immutable) - 线程安全: 是（不可变）
  • Null-safe: Null parameters throw NullPointerException - 空值安全: null参数抛出NullPointerException
Since:
JDK 25, opencode-base-csv V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • from

      public static CsvTransform from(CsvDocument doc)
      Creates a transformation pipeline from a CsvDocument 从CsvDocument创建转换管道
      Parameters:
      doc - the source document | 源文档
      Returns:
      a new CsvTransform instance | 新的CsvTransform实例
      Throws:
      NullPointerException - if doc is null | 如果doc为null

    • renameColumn

      public CsvTransform renameColumn(String oldName, String newName)
      Renames a single column 重命名单个列
      Parameters:
      oldName - the current column name | 当前列名
      newName - the new column name (must not be blank) | 新列名（不得为空白）
      Returns:
      a new CsvTransform with the rename step added | 添加了重命名步骤的新CsvTransform
      Throws:
      NullPointerException - if oldName or newName is null | 如果oldName或newName为null

    • renameColumns

      public CsvTransform renameColumns(Map<String,String> mapping)
      Renames multiple columns using a mapping 使用映射重命名多个列

      Each entry in the map represents an old name to new name mapping. All old names must exist in the document headers.

      映射中的每个条目表示旧名到新名的映射。所有旧名必须存在于文档标题中。

      Parameters:
      mapping - the old-to-new name mapping | 旧名到新名的映射
      Returns:
      a new CsvTransform with the rename step added | 添加了重命名步骤的新CsvTransform
      Throws:
      NullPointerException - if mapping is null | 如果mapping为null

    • reorderColumns

      public CsvTransform reorderColumns(String... columnOrder)
      Reorders columns by specifying the desired column order 通过指定期望的列顺序来重新排列列

      All column names must exist in the document headers. Only the specified columns will appear in the result.

      所有列名必须存在于文档标题中。结果中只出现指定的列。

      Parameters:
      columnOrder - the desired column order | 期望的列顺序
      Returns:
      a new CsvTransform with the reorder step added | 添加了重排步骤的新CsvTransform
      Throws:
      NullPointerException - if columnOrder is null | 如果columnOrder为null

    • addColumn

      public CsvTransform addColumn(String name, String defaultValue)
      Adds a new column with a fixed default value 添加具有固定默认值的新列
      Parameters:
      name - the new column name | 新列名
      defaultValue - the default value for all rows | 所有行的默认值
      Returns:
      a new CsvTransform with the add column step added | 添加了新列步骤的新CsvTransform
      Throws:
      NullPointerException - if name is null | 如果name为null

    • addColumn

      public CsvTransform addColumn(String name, Function<CsvRow,String> valueMapper)
      Adds a new column with values computed from each row 添加值由每行计算得出的新列
      Parameters:
      name - the new column name | 新列名
      valueMapper - function to compute the value for each row | 计算每行值的函数
      Returns:
      a new CsvTransform with the add column step added | 添加了新列步骤的新CsvTransform
      Throws:
      NullPointerException - if name or valueMapper is null | 如果name或valueMapper为null

    • removeColumns

      public CsvTransform removeColumns(String... columns)
      Removes specified columns 移除指定的列
      Parameters:
      columns - the column names to remove | 要移除的列名
      Returns:
      a new CsvTransform with the remove step added | 添加了移除步骤的新CsvTransform
      Throws:
      NullPointerException - if columns is null | 如果columns为null

    • mapColumn

      public CsvTransform mapColumn(String column, UnaryOperator<String> mapper)
      Transforms values in a specific column 转换特定列中的值
      Parameters:
      column - the column name | 列名
      mapper - the transformation function | 转换函数
      Returns:
      a new CsvTransform with the map step added | 添加了映射步骤的新CsvTransform
      Throws:
      NullPointerException - if column or mapper is null | 如果column或mapper为null

    • mapRows

      public CsvTransform mapRows(UnaryOperator<CsvRow> mapper)
      Transforms entire rows 转换整行

      The mapper receives each CsvRow and must return a new CsvRow. Headers remain unchanged.

      映射器接收每个CsvRow并必须返回一个新的CsvRow。标题保持不变。

      Parameters:
      mapper - the row transformation function | 行转换函数
      Returns:
      a new CsvTransform with the map step added | 添加了映射步骤的新CsvTransform
      Throws:
      NullPointerException - if mapper is null | 如果mapper为null

    • filterColumns

      public CsvTransform filterColumns(Predicate<String> headerPredicate)
      Keeps only columns whose header names match the predicate 仅保留标题名匹配谓词的列
      Parameters:
      headerPredicate - the predicate to test header names | 测试标题名的谓词
      Returns:
      a new CsvTransform with the filter step added | 添加了过滤步骤的新CsvTransform
      Throws:
      NullPointerException - if headerPredicate is null | 如果headerPredicate为null

    • execute

      public CsvDocument execute()
      Executes all transformation steps and returns the result 执行所有转换步骤并返回结果
      Returns:
      the transformed document | 转换后的文档
      Throws:
      OpenCsvException - if a transformation step fails | 如果转换步骤失败