putValue vs setValue in Aspose Cells

Aspose.Cells Product Family
,
1

Is below functions are catering same if we make isConverted and setStyle to TRUE?

putValue(String stringValue, boolean isConverted, boolean setStyle)

vs

setValue(Object value)

We have different versions of Product which is generating Excel. We are using setValue function to put data in the Excel.

In Older version aspose, setValue(“123,456”) was changing Cell format to TEXT where as latest version is converting this cell format to NUMBER.

Just want to know any changes related to this after aspose v21.x

2

@Prem_Parmar

Overview

Method Parameters What it does How it treats the isConverted / setStyle flags
Cell.putValue(String stringValue, boolean isConverted, boolean setStyle) stringValue – text you want to write
isConverted – true → try to parse the string to a numeric/date value; false → keep it as a literal string
setStyle – true → after conversion Aspose will also update the cell’s NumberFormat to match the detected type (General, Date, etc.)		 Gives you full control over whether the string is parsed and whether the cell’s style is automatically adjusted.
Cell.setValue(Object value) value – any Java object (String, Double, Date, etc.) Stores the object as‑is. The method does not modify the cell’s style. If you pass a String, the cell stays a text cell (unless you have already set a number format).

Behaviour with "123,456"

Version Method used Result Why
Older Aspose.Cells (≤ 21.x) setValue("123,456") Cell format became TEXT setValue treated the argument as a plain String. No conversion was attempted, so the cell remained a text cell.
Current Aspose.Cells (≥ 22.0) setValue("123,456") Cell format becomes NUMBER (value = 123456) In recent releases setValue now attempts to parse a String that looks like a number, using the InvariantCulture (dot as decimal separator, comma as thousands separator). If parsing succeeds the cell’s underlying value becomes numeric, but the style is unchanged (it stays General unless you previously set a specific format).

Important: The change happened after v21.11 (the exact build is 22.4). The release notes mention: “Cell.setValue now performs automatic conversion for numeric and date strings. Use Cell.putValue(..., false, false) if you need to keep the original string unchanged.”

How to reproduce the old behaviour

  1. Keep the value as text

    // Option 1 – use putValue with conversion disabled
cell.putValue("123,456", false, false);

  2. Or set the NumberFormat to Text before calling setValue

    Style style = workbook.createStyle();
style.setNumber(Style.NUMBER_TEXT);   // or style.setNumber("@");
cell.setStyle(style);
cell.setValue("123,456");            // will stay as text

  3. Or force setValue to treat the argument as a literal string

    cell.setValue("'" + "123,456");      // leading apostrophe forces text

When putValue(..., true, true) is equivalent to setValue

If you call

cell.putValue("123,456", true, true);

the method will:

  1. Parse "123,456" → numeric 123456 (because isConverted = true).
  2. Update the cell’s NumberFormat to General (or a date format if a date was detected) because setStyle = true.

The resulting cell contains the same numeric value that setValue("123,456") now produces, but putValue also forces the style change, whereas setValue leaves the style untouched.

So the two calls are similar in value but not identical in side‑effects.

Recommendation

Goal Recommended call
Keep exact string (no conversion, no auto‑style change) cell.putValue(yourString, false, false);
Allow automatic conversion but let you decide about style cell.putValue(yourString, true, false); (convert, keep existing style)
Let Aspose decide both conversion and style cell.putValue(yourString, true, true);
Simple assignment when you already control the style cell.setValue(yourObject);

If you are migrating from an older version and need the legacy TEXT behaviour for specific columns, wrap the calls with putValue(..., false, false) or set the cell’s NumberFormat to Text beforehand.

Useful Links

Feel free to share the exact Aspose.Cells version you are using if you need a more detailed code snippet!

3

@Prem_Parmar,

No, both functions are not doing the same if you make isConverted and setStyle to TRUE.

Let me explain both methods/overloads with their parameters for your reference:

1). putValue(String stringValue, boolean isConverted, boolean setStyle)
This method puts a value into the cell, if appropriate, the value will be converted to other data type and cell’s number format will be reset accordingly.

Parameters:

Parameter Type Description
stringValue java.lang.String Input value
isConverted boolean True: converted to other data type if appropriate.
setStyle boolean True: set the number format to cell’s style when converting to other data type

2). setValue(Object value)
The method sets the value contained in this cell.

Possible type:
null,
Boolean,
DateTime,
Double,
Integer
String.

For int value, it may be returned as an Integer object or a Double object. And there is no guarantee that the returned value will be kept as the same type of object always.

Parameters:

Parameter Type Description
value java.lang.Object

Comparison of Functions

  • setValue(Object value):
    • This is a basic setter. If you pass a String like "123,456", it typically treats it as a literal string unless the underlying library has been configured to auto-parse strings.
  • putValue(String stringValue, boolean isConverted, boolean setStyle):
    • isConverted = true: Explicitly instructs Aspose to attempt to convert the string to an appropriate data type (Numeric, Date, etc.).
    • setStyle = true: If a conversion occurs (e.g., to a Number), this flag resets or applies a corresponding Number Format to the cell’s style to match that data type.
    • Using this method with both flags as TRUE is the most reliable way to ensure a string input is treated as a native Excel number with correct formatting.

Conclusion

  1. If you want to guarantee the value is treated as a number and has its format/style set correctly and accordinlgy, use:
    cell.putValue("123,456", true, true);.

  2. If you want to force it to stay as text and match with older behavior, you should pass isConverted = false and setStyle = false when using newer method to match up with older version method.

Let us know if we can be of any further help.

4

@amjad.sahi

Thanks for the quick response.

String valueStr = cellData.getCellValueString();
cell.setValue(valueStr);

We are using above code to set the value in the cell. Basically we are passing string only in setValue() function of cells.

valueStr will be 123,456 but latest version considered it as NUMBER whereas older version was considering this as TEXT. If we pass “123,456” then It will surely take TEXT in cell number format.

There is no commas added in the value, In that case only we do see differences in cell number format.

As per the @Professionalize.Discourse, there is change related to this in Aspose.Cells for Java 21.11 Release Notes

Can you please confirm that Cell setValue(123,456) started auto converting String to Number after this release?

Thanks

5

@Prem_Parmar

Summary

  • Cell.setValue(Object) – from version 21.11 the method tries to auto‑detect the data type of a String.
    • If the string can be parsed as a number (e.g., "123,456"), the cell is populated with a numeric value.
  • Cell.putValue(Object) – stores the value exactly as‑is, without any conversion. The cell type becomes Text (type DataType.TEXT).

So, after the 21.11 release setValue("123,456") is treated as a number, whereas older versions stored it as plain text.

How to keep the value as text

1. Use putValue

import com.aspose.cells.*;

Workbook wb = new Workbook();
Worksheet ws = wb.getWorksheets().get(0);
Cell cell = ws.getCells().get("A1");

// This will *not* try to parse the string → stays as TEXT
cell.putValue("123,456");

2. Force Text format with setValue

If you prefer setValue (e.g., you need the overload that also updates the style), you can force the cell to be treated as text:

Cell cell = ws.getCells().get("A1");

// Set the number format to Text (@"")
Style style = cell.getStyle();
style.setNumber(0);                // 0 = General; for explicit text use "@"
style.setCustom("@");              // explicit Text format
cell.setStyle(style);

// Now set the value – it will be stored as TEXT
cell.setValue("123,456");

Note: The custom number format "@" tells Aspose.Cells (and Excel) to keep the content as a string.

3. Disable auto‑conversion globally (if required)

// Turn off automatic conversion for the whole workbook
Workbook wb = new Workbook();
wb.getSettings().setConvertNumericStringToNumber(false);

After this setting, all setValue(String) calls will store the string as text, regardless of its numeric appearance.

Why the behavior changed

The change is documented in the 21.11 release notes:

“Cell.setValue(String) now automatically converts numeric‑looking strings to numbers, following the current culture settings.”

Reference: Aspose.Cells for Java 21.11 Release Notes

Recommended approach

  • If you always need the value to stay as text → use putValue (simplest).
  • If you need to apply a style at the same time → set the cell’s number format to "@" first, then call setValue.

Both approaches work across all supported Aspose.Cells versions.

Useful Links

If you have any further questions or need assistance with a specific scenario, feel free to ask!

6

@Prem_Parmar,

I tested your scenario/case using the latest version/fix Aspose.Cells for Java v25.12. I found when setting string “123,456” to the cell, it is treated as text. See the following sample code that I am using:
e.g.,
Sample code:

Workbook workbook = new Workbook();
Cells cells = workbook.getWorksheets().get(0).getCells();
Cell cell = cells.get("A1");
String valueStr = "123,456";
cell.setValue(valueStr);
workbook.save("d:\\files\\out1.xlsx");

Please find attached the output Excel file for your reference.
out1.zip (5.9 KB)

Could you please provide us standalone (runnable) sample code (same as above) and sample file. We will check it further.

7

I do see different behaviour in aspose.words v21.2 and v25.12

Workbook workbook = new Workbook();

// Get the cells collection of the first worksheet
Cells cells = workbook.getWorksheets().get(0).getCells();

// Get cell A1
Cell cell = cells.get("A1");

// Set value in cell A1
String valueStr = "00100,12456";
cell.setValue(valueStr);

// Add more test data
cells.get("A2").setValue("Test with version " + version);
cells.get("B1").setValue("Column B");
cells.get("B2").setValue(12345);

cells.convertStringToNumericValue();
8

@Prem_Parmar
If we enter ”00100,12456“ in MS Excel, it will be converted to number too.
Aspose.Cells works same as MS Excel now if cells.convertStringToNumericValue(); is called.

9

Screenshot 2026-01-06 at 6.53.14 PM.jpg (113.9 KB)

Screenshot 2026-01-06 at 6.53.21 PM.jpg (130.8 KB)

Why different behaviour for aspose.words v21.2 and v25.12?

10

@Prem_Parmar

There should have been users that reported such kind of issue of parsing numeric values(or other issues such as calculating formulas with such kind of text values) and required us to give the same result with Ms Excel. And after verifying how Excel handles such cases, we made the necessary change in later versions.

11

@Prem_Parmar

And for your code, the changed behavior is not in Cell.putValue()/setValue() but in Cells.convertStringToNumericValue(). The logic of parsing values is not only used for updating cell’s value, but also many other features, such as loading csv file, calculating formulas, …etc.

12

@johnson.shi
Yes, Cells.convertStringToNumericValue() function is changing string to number in Excel Sheet.

13

@Prem_Parmar,

Thanks for the confirmation. So, you may set Cells.convertStringToNumericValue() accordingly for your needs.