Package io.github.dornol.excelkit.core

Record Class CellData

java.lang.Object
java.lang.Record
io.github.dornol.excelkit.core.CellData
Record Components:
columnIndex - the column index of the cell (0-based)
formattedValue - the formatted string value extracted from Excel
public record CellData(int columnIndex, @Nullable String formattedValue) extends Record
Represents a single cell's value read from an Excel file, along with its column index and formatted string content.

Provides utility methods to convert the cell's value into various Java types, including number, string, boolean, date/time, etc.

Since:
2025-07-19

  • Constructor Details

    • CellData

      public CellData(int columnIndex, @Nullable String formattedValue)
      Validates and normalizes the cell data.

  • Method Details

    • getDefaultLocale

      public static Locale getDefaultLocale()
      Returns the default locale used by no-arg number parsing methods.
      Returns:
      The current default locale

    • setDefaultLocale

      public static void setDefaultLocale(Locale locale)
      Sets the default locale for number parsing. Affects all subsequent calls to asNumber(), asLong(), asInt(), asDouble(), asFloat(), and asBigDecimal().

      The default value is Locale.getDefault().

      Parameters:
      locale - The locale to use as default (must not be null)

    • addDateFormat

      public static void addDateFormat(String pattern)
      Adds a custom date format pattern for asLocalDate(). The pattern is inserted at the beginning of the list so it takes priority over built-in patterns.

      This method is thread-safe.

      Parameters:
      pattern - the date pattern (e.g., "dd.MM.yyyy")

    • addDateTimeFormat

      public static void addDateTimeFormat(String pattern)
      Adds a custom date-time format pattern for asLocalDateTime(). The pattern is inserted at the beginning of the list so it takes priority over built-in patterns.

      This method is thread-safe.

      Parameters:
      pattern - the date-time pattern (e.g., "dd.MM.yyyy HH:mm:ss")

    • getDateFormats

      public static List<DateTimeFormatter> getDateFormats()
      Returns an unmodifiable view of the currently registered date format patterns.
      Returns:
      the list of date format patterns

    • getDateTimeFormats

      public static List<DateTimeFormatter> getDateTimeFormats()
      Returns an unmodifiable view of the currently registered date-time format patterns.
      Returns:
      the list of date-time format patterns

    • resetDateFormats

      public static void resetDateFormats()
      Resets the date format patterns to the built-in defaults. Removes any custom patterns previously added via addDateFormat(String).

      This method is thread-safe.

    • resetDateTimeFormats

      public static void resetDateTimeFormats()
      Resets the date-time format patterns to the built-in defaults. Removes any custom patterns previously added via addDateTimeFormat(String).

      This method is thread-safe.

    • asNumber

      public @Nullable Number asNumber(Locale locale)
      Parses the value as a Number using the given locale. This method removes formatting characters such as commas, currency symbols, and percent signs. Returns null if the value is empty or blank.
      Parameters:
      locale - the locale to use for number formatting (e.g. Locale.KOREA)
      Returns:
      parsed number, or null if empty or blank
      Throws:
      IllegalArgumentException - if parsing fails

    • asNumber

      public @Nullable Number asNumber()
      Parses the value as a Number using the configured default locale. Returns null if the value is empty or blank.
      Returns:
      parsed number, or null if blank
      See Also:

    • asLong

      public @Nullable Long asLong()
      Converts the value to Long. Returns null if the value is empty or blank.
      Returns:
      the long value, or null if blank

    • asInt

      public @Nullable Integer asInt()
      Converts the value to Integer. Returns null if the value is empty or blank. Throws if the long value is out of int range.
      Returns:
      the integer value, or null if blank

    • asString

      public String asString()
      Returns the raw string as-is.
      Returns:
      the formatted string value

    • asBoolean

      public boolean asBoolean()
      Converts the value to a boolean.

      Accepts "true", "1", "y", "yes" (case-insensitive) as true. Returns false if the value is empty, blank, or does not match any recognized true value.

      Returns:
      true if the value represents a true-like string, otherwise false

    • asBooleanOrNull

      public @Nullable Boolean asBooleanOrNull()
      Converts the value to a nullable Boolean.

      Returns null if the value is empty or blank, allowing callers to distinguish between "no value" and an explicit false. Accepts "true", "1", "y", "yes" (case-insensitive) as true; all other non-blank values are treated as false.

      Returns:
      Boolean.TRUE, Boolean.FALSE, or null if blank

    • asLocalDateTime

      public @Nullable LocalDateTime asLocalDateTime()
      Converts the formatted value to LocalDateTime using multiple supported date-time formats. Returns null if the value is empty or blank. Supported formats include: - yyyy-MM-dd[ HH:mm[:ss]] - yyyy/MM/dd[ HH:mm[:ss]] - MM/dd/yy[ HH:mm[:ss]] - M/d/yy[ HH:mm[:ss]] - ISO_LOCAL_DATE_TIME The patterns support optional sections for time (hours, minutes, seconds). If all patterns fail, a DateTimeParseException will be thrown.
      Returns:
      the parsed date-time, or null if blank

    • asLocalDateTime

      public @Nullable LocalDateTime asLocalDateTime(String format)
      Converts the value to LocalDateTime using the specified format. Returns null if the value is empty or blank.
      Parameters:
      format - the date-time pattern (e.g., "yyyy-MM-dd HH:mm:ss")
      Returns:
      the parsed date-time, or null if blank

    • asLocalDate

      public @Nullable LocalDate asLocalDate()
      Converts the formatted value to LocalDate using multiple supported date formats. Returns null if the value is empty or blank. Supported formats include: - yyyy-MM-dd - yyyy/MM/dd - MM/dd/yy - M/d/yy - ISO_LOCAL_DATE If all patterns fail, a DateTimeParseException will be thrown.
      Returns:
      the parsed date, or null if blank

    • asLocalDate

      public @Nullable LocalDate asLocalDate(String format)
      Converts the value to LocalDate using the specified format. Returns null if the value is empty or blank.
      Parameters:
      format - the date pattern (e.g., "yyyy/MM/dd")
      Returns:
      the parsed date, or null if blank

    • asLocalTime

      public @Nullable LocalTime asLocalTime()
      Converts the value to LocalTime using ISO format (HH:mm:ss). Returns null if the value is empty or blank.
      Returns:
      the parsed time, or null if blank

    • asLocalTime

      public @Nullable LocalTime asLocalTime(String format)
      Converts the value to LocalTime using the specified format. Returns null if the value is empty or blank.
      Parameters:
      format - the time pattern (e.g., "HH:mm")
      Returns:
      the parsed time, or null if blank

    • asZonedDateTime

      public @Nullable ZonedDateTime asZonedDateTime(ZoneId zone)
      Converts the value to ZonedDateTime by parsing as LocalDateTime and attaching the given time zone. Returns null if the value is empty or blank.
      Parameters:
      zone - the time zone to apply
      Returns:
      the zoned date-time, or null if blank
      Since:
      0.9.2

    • asZonedDateTime

      public @Nullable ZonedDateTime asZonedDateTime(String format, ZoneId zone)
      Converts the value to ZonedDateTime using the specified format and time zone. Returns null if the value is empty or blank.
      Parameters:
      format - the date-time pattern
      zone - the time zone to apply
      Returns:
      the zoned date-time, or null if blank
      Since:
      0.9.2

    • asDouble

      public @Nullable Double asDouble()
      Converts the value to Double. Returns null if the value is empty or blank.
      Returns:
      the double value, or null if blank

    • asFloat

      public @Nullable Float asFloat()
      Converts the value to Float. Returns null if the value is empty or blank.
      Returns:
      the float value, or null if blank

    • asBigDecimal

      public @Nullable BigDecimal asBigDecimal()
      Converts the value to BigDecimal with full precision.

      Unlike asNumber(), this method parses the cleaned string directly as a BigDecimal, avoiding intermediate Double conversion that can lose precision for large or high-precision values. Returns null if the value is empty or blank.

      Returns:
      the BigDecimal value, or null if blank
      Throws:
      IllegalArgumentException - if the value cannot be parsed as a number

    • isEmpty

      public boolean isEmpty()
      Checks if the value is empty or blank.
      Returns:
      true if the formatted value is empty or consists only of whitespace

    • asEnum

      public <E extends Enum<E>> @Nullable E asEnum(Class<E> enumType)
      Converts the value to an enum constant by name (case-insensitive). Returns null if the value is empty or blank.
      Type Parameters:
      E - the enum type
      Parameters:
      enumType - the enum class
      Returns:
      the matching enum constant, or null if blank
      Throws:
      IllegalArgumentException - if no matching constant is found

    • as

      public <R> @Nullable R as(Function<String,R> converter)
      Converts the cell value using a custom conversion function.

      The function receives the raw string value and returns the converted result. Returns null if the value is empty or blank. 

      
 UUID id = cell.as(UUID::fromString);
 MyType obj = cell.as(MyType::parse);
      Type Parameters:
      R - the return type
      Parameters:
      converter - the conversion function
      Returns:
      the converted value, or null if blank

    • asInt

      public int asInt(int defaultValue)
      Converts the cell value to Integer, returning the given default if blank.
      Parameters:
      defaultValue - the value to return if the cell is blank
      Returns:
      the parsed integer or the default value

    • asLong

      public long asLong(long defaultValue)
      Converts the cell value to Long, returning the given default if blank.
      Parameters:
      defaultValue - the value to return if the cell is blank
      Returns:
      the parsed long or the default value

    • asDouble

      public double asDouble(double defaultValue)
      Converts the cell value to Double, returning the given default if blank.
      Parameters:
      defaultValue - the value to return if the cell is blank
      Returns:
      the parsed double or the default value

    • asString

      public String asString(String defaultValue)
      Returns the string value, or the given default if blank.
      Parameters:
      defaultValue - the value to return if the cell is blank
      Returns:
      the string value or the default value

    • as

      public <R> R as(Function<String,R> converter, R defaultValue)
      Converts the cell value using a custom function, returning the given default if blank. 
      
 UUID id = cell.as(UUID::fromString, DEFAULT_UUID);
      Type Parameters:
      R - the return type
      Parameters:
      converter - the conversion function
      defaultValue - the value to return if the cell is blank
      Returns:
      the converted value or the default value

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. Reference components are compared with Objects::equals(Object,Object); primitive components are compared with '=='.
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • columnIndex

      public int columnIndex()
      Returns the value of the columnIndex record component.
      Returns:
      the value of the columnIndex record component

    • formattedValue

      public @Nullable String formattedValue()
      Returns the value of the formattedValue record component.
      Returns:
      the value of the formattedValue record component