// in case of plain ascii
// wb.setSheetName(0, "HSSF Test");
// create a sheet with 30 rows (0-29)
+int rownum;
for (rownum = (short) 0; rownum < 30; rownum++)
{
// create a row
Name namedCell = wb.createName();
namedCell.setNameName(cname);
String reference = sname+"!A1:A1"; // area reference
- namedCell.setReference(reference);
+ namedCell.setRefersToFormula(reference);
// 2. create named range for a single cell using cellreference
- Name namedCell = wb.createName();
- namedCell.setNameName(cname);
+ Name namedCel2 = wb.createName();
+ namedCel2.setNameName(cname);
String reference = sname+"!A1"; // cell reference
- namedCell.setReference(reference);
+ namedCel2.setRefersToFormula(reference);
// 3. create named range for an area using AreaReference
- Name namedCell = wb.createName();
- namedCell.setNameName(cname);
+ Name namedCel3 = wb.createName();
+ namedCel3.setNameName(cname);
String reference = sname+"!A1:C5"; // area reference
- namedCell.setReference(reference);
+ namedCel3.setRefersToFormula(reference);
+
+ // 4. create named formula
+ Name namedCel4 = wb.createName();
+ namedCel4.setNameName("my_sum");
+ namedCel4.setRefersToFormula("SUM(sname+!$I$2:$I$6)");
</source>
<p>
Reading from Named Range / Named Cell
Name aNamedCell = wb.getNameAt(namedCellIdx);
// retrieve the cell at the named range and test its contents
- AreaReference aref = new AreaReference(aNamedCell.getReference());
+ AreaReference aref = new AreaReference(aNamedCell.getRefersToFormula());
CellReference[] crefs = aref.getAllReferencedCells();
for (int i=0; i<crefs.length; i++) {
Sheet s = wb.getSheet(crefs[i].getSheetName());
// Retrieve the cell at the named range and test its contents
// Will get back one AreaReference for C10, and
// another for D12 to D14
- AreaReference[] arefs = AreaReference.generateContiguous(aNamedCell.getReference());
+ AreaReference[] arefs = AreaReference.generateContiguous(aNamedCell.getRefersToFormula());
for (int i=0; i<arefs.length; i++) {
// Only get the corners of the Area
// (use arefs[i].getAllReferencedCells() to get all cells)
if(name.isDeleted()){
//named range points to a deleted cell.
} else {
- AreaReference ref = new AreaReference(name.getReference());
+ AreaReference ref = new AreaReference(name.getRefersToFormula());
}
</source>
</section>
\r
name = wb.createName();\r
name.setNameName("Interest_Rate");\r
- name.setReference("'Loan Calculator'!$E$5");\r
+ name.setRefersToFormula("'Loan Calculator'!$E$5");\r
\r
name = wb.createName();\r
name.setNameName("Loan_Amount");\r
- name.setReference("'Loan Calculator'!$E$4");\r
+ name.setRefersToFormula("'Loan Calculator'!$E$4");\r
\r
name = wb.createName();\r
name.setNameName("Loan_Start");\r
- name.setReference("'Loan Calculator'!$E$7");\r
+ name.setRefersToFormula("'Loan Calculator'!$E$7");\r
\r
name = wb.createName();\r
name.setNameName("Loan_Years");\r
- name.setReference("'Loan Calculator'!$E$6");\r
+ name.setRefersToFormula("'Loan Calculator'!$E$6");\r
\r
name = wb.createName();\r
name.setNameName("Number_of_Payments");\r
- name.setReference("'Loan Calculator'!$E$10");\r
+ name.setRefersToFormula("'Loan Calculator'!$E$10");\r
\r
name = wb.createName();\r
name.setNameName("Monthly_Payment");\r
- name.setReference("-PMT(Interest_Rate/12,Number_of_Payments,Loan_Amount)");\r
+ name.setRefersToFormula("-PMT(Interest_Rate/12,Number_of_Payments,Loan_Amount)");\r
\r
name = wb.createName();\r
name.setNameName("Total_Cost");\r
- name.setReference("'Loan Calculator'!$E$12");\r
+ name.setRefersToFormula("'Loan Calculator'!$E$12");\r
\r
name = wb.createName();\r
name.setNameName("Total_Interest");\r
- name.setReference("'Loan Calculator'!$E$11");\r
+ name.setRefersToFormula("'Loan Calculator'!$E$11");\r
\r
name = wb.createName();\r
name.setNameName("Values_Entered");\r
- name.setReference("IF(Loan_Amount*Interest_Rate*Loan_Years*Loan_Start>0,1,0)");\r
+ name.setRefersToFormula("IF(Loan_Amount*Interest_Rate*Loan_Years*Loan_Start>0,1,0)");\r
}\r
}\r
}
/**
- * sets the name of the named range
+ * Sets the name of the named range
+ *
+ * <p>The following is a list of syntax rules that you need to be aware of when you create and edit names.</p>
+ * <ul>
+ * <li><strong>Valid characters</strong>
+ * The first character of a name must be a letter, an underscore character (_), or a backslash (\).
+ * Remaining characters in the name can be letters, numbers, periods, and underscore characters.
+ * </li>
+ * <li><strong>Cell references disallowed</strong>
+ * Names cannot be the same as a cell reference, such as Z$100 or R1C1.</li>
+ * <li><strong>Spaces are not valid</strong>
+ * Spaces are not allowed as part of a name. Use the underscore character (_) and period (.) as word separators, such as, Sales_Tax or First.Quarter.
+ * </li>
+ * <li><strong>Name length</strong>
+ * A name can contain up to 255 characters.
+ * </li>
+ * <li><strong>Case sensitivity</strong>
+ * Names can contain uppercase and lowercase letters.
+ * </li>
+ * </ul>
* @param nameName named range name to set
+ * @throws IllegalArgumentException if the name is invalid or the workbook already contains this name (case-insensitive)
*/
public void setNameName(String nameName){
_definedNameRec.setNameText(nameName);
}
/**
- * @deprecated (Nov 2008) Misleading name. Use {@link #getFormula()} instead.
+ * Returns the formula that the name is defined to refer to.
+ *
+ * @deprecated (Nov 2008) Misleading name. Use {@link #getRefersToFormula()} instead.
*/
public String getReference() {
- return getFormula();
+ return getRefersToFormula();
}
/**
- * @deprecated (Nov 2008) Misleading name. Use {@link #setFormula(String)} instead.
+ * Sets the formula that the name is defined to refer to.
+ *
+ * @deprecated (Nov 2008) Misleading name. Use {@link #setRefersToFormula(String)} instead.
*/
public void setReference(String ref){
- setFormula(ref);
+ setRefersToFormula(ref);
}
- public void setFormula(String formulaText) {
+ /**
+ * Sets the formula that the name is defined to refer to. The following are representative examples:
+ *
+ * <ul>
+ * <li><code>'My Sheet'!$A$3</code></li>
+ * <li><code>8.3</code></li>
+ * <li><code>HR!$A$1:$Z$345</code></li>
+ * <li><code>SUM(Sheet1!A1,Sheet2!B2)</li>
+ * <li><code>-PMT(Interest_Rate/12,Number_of_Payments,Loan_Amount)</li>
+ * </ul>
+ *
+ * @param formulaText the reference for this name
+ * @throws IllegalArgumentException if the specified reference is unparsable
+ */
+ public void setRefersToFormula(String formulaText) {
Ptg[] ptgs = HSSFFormulaParser.parse(formulaText, _book);
_definedNameRec.setNameDefinition(ptgs);
}
/**
- * Note - this method only applies to named ranges
- * @return the formula text defining this name
+ * Returns the formula that the name is defined to refer to. The following are representative examples:
+ *
+ * @return the reference for this name
+ * @see #setRefersToFormula(String)
*/
- public String getFormula() {
+ public String getRefersToFormula() {
if (_definedNameRec.isFunctionName()) {
throw new IllegalStateException("Only applicable to named ranges");
}
* @return true if the name refers to a deleted cell, false otherwise
*/
public boolean isDeleted(){
- String formulaText = getReference();
- if (formulaText.startsWith("#REF!")) {
- // sheet deleted
- return true;
- }
- if (formulaText.endsWith("#REF!")) {
- // cell range deleted
- return true;
- }
- return false;
+ String formulaText = getRefersToFormula();
+ return formulaText.indexOf("#REF!") != -1;
}
+
+ /**
+ * Checks if this name is a function name
+ *
+ * @return true if this name is a function name
+ */
public boolean isFunctionName() {
return _definedNameRec.isFunctionName();
}
+
public String toString() {
StringBuffer sb = new StringBuffer(64);
sb.append(getClass().getName()).append(" [");
package org.apache.poi.ss.usermodel;
+/**
+ * Represents a defined name for a range of cells.
+ * <p>
+ * A name is a meaningful shorthand that makes it easier to understand the purpose of a
+ * cell reference, constant or a formula.
+ * </p>
+ * Examples:
+ * <pre><blockquote>
+ * Sheet sheet = workbook.createSheet("Loan Calculator");
+ * Name name;
+ *
+ * name = workbook.createName();
+ * name.setNameName("Interest_Rate");
+ * name.setRefersToFormula("'Loan Calculator'!$E$5");
+ *
+ * name = wb.createName();
+ * name.setNameName("Loan_Amount");
+ * name.setRefersToFormula("'Loan Calculator'!$E$4");
+ *
+ * name = wb.createName();
+ * name.setNameName("Number_of_Payments");
+ * name.setRefersToFormula("'Loan Calculator'!$E$10");
+ *
+ * name = wb.createName();
+ * name.setNameName("Monthly_Payment");
+ * name.setRefersToFormula("-PMT(Interest_Rate/12,Number_of_Payments,Loan_Amount)");
+ *
+ * name = wb.createName();
+ * name.setNameName("Values_Entered");
+ * name.setRefersToFormula("IF(Loan_Amount*Interest_Rate>0,1,0)");
+ *
+ * </blockquote></pre>
+ */
public interface Name {
- /** Get the sheets name which this named range is referenced to
+ /**
+ * Get the sheets name which this named range is referenced to
+ *
* @return sheet name, which this named range refered to
*/
String getSheetName();
/**
- * gets the name of the named range
+ * Gets the name of the named range
+ *
* @return named range name
*/
String getNameName();
/**
- * sets the name of the named range
- * @param nameName named range name to set
+ * Sets the name of the named range
+ *
+ * <p>The following is a list of syntax rules that you need to be aware of when you create and edit names.</p>
+ * <ul>
+ * <li><strong>Valid characters</strong>
+ * The first character of a name must be a letter, an underscore character (_), or a backslash (\).
+ * Remaining characters in the name can be letters, numbers, periods, and underscore characters.
+ * </li>
+ * <li><strong>Cell references disallowed</strong>
+ * Names cannot be the same as a cell reference, such as Z$100 or R1C1.</li>
+ * <li><strong>Spaces are not valid</strong>
+ * Spaces are not allowed as part of a name. Use the underscore character (_) and period (.) as word separators, such as, Sales_Tax or First.Quarter.
+ * </li>
+ * <li><strong>Name length</strong>
+ * A name can contain up to 255 characters.
+ * </li>
+ * <li><strong>Case sensitivity</strong>
+ * Names can contain uppercase and lowercase letters.
+ * </li>
+ * </ul>
+ * @param name named range name to set
+ * @throws IllegalArgumentException if the name is invalid or the workbook already contains this name (case-insensitive)
*/
- void setNameName(String nameName);
+ void setNameName(String name);
/**
- * @deprecated (Nov 2008) Misleading name. Use {@link #getFormula()} instead.
+ * Returns the formula that the name is defined to refer to. The following are representative examples:
+ *
+ * @return the reference for this name
+ * @see #setRefersToFormula(String)
*/
- String getReference();
+ String getRefersToFormula();
/**
- * @deprecated (Nov 2008) Misleading name. Use {@link #setFormula(String)} instead.
- */
- void setReference(String ref);
-
- /**
- * @return the formula text defining this name
+ * Sets the formula that the name is defined to refer to. The following are representative examples:
+ *
+ * <ul>
+ * <li><code>'My Sheet'!$A$3</code></li>
+ * <li><code>8.3</code></li>
+ * <li><code>HR!$A$1:$Z$345</code></li>
+ * <li><code>SUM(Sheet1!A1,Sheet2!B2)</li>
+ * <li><code>-PMT(Interest_Rate/12,Number_of_Payments,Loan_Amount)</li>
+ * </ul>
+ *
+ * @param ref the reference for this name
+ * @throws IllegalArgumentException if the specified reference is unparsable
*/
- String getFormula();
-
- /**
- * Sets the formula text defining this name
- */
- void setFormula(String formulaText);
+ void setRefersToFormula(String ref);
+
/**
* Checks if this name is a function name
*
*
* @param value <code>true</code> if the sheet displays Automatic Page Breaks.
*/
- void setAutobreaks(boolean b);
+ void setAutobreaks(boolean value);
/**
* Set whether to display the guts or not
\r
public Ptg[] getNameDefinition() {\r
\r
- return FormulaParser.parse(_nameRecord.getReference(), _fpBook);\r
+ return FormulaParser.parse(_nameRecord.getRefersToFormula(), _fpBook);\r
}\r
\r
public String getNameText() {\r
* //applies to the entire workbook
* XSSFName name1 = wb.createName();
* name1.setNameName("FMLA");
- * name1.setReference("Sheet1!$B$3");
+ * name1.setRefersToFormula("Sheet1!$B$3");
*
* //applies to Sheet1
* XSSFName name2 = wb.createName();
* name2.setNameName("SheetLevelName");
* name2.setComment("This name is scoped to Sheet1");
* name2.setLocalSheetId(0);
- * name2.setReference("Sheet1!$B$3");
+ * name2.setRefersToFormula("Sheet1!$B$3");
*
* </blockquote></pre>
*
ctName.setName(name);
}
- /**
- * @deprecated (Nov 2008) Misleading name. Use {@link #getFormula()} instead.
- */
- public String getReference() {
- return getFormula();
- }
-
- /**
- * @deprecated (Nov 2008) Misleading name. Use {@link #setFormula(String)} instead.
- */
- public void setReference(String ref){
- setFormula(ref);
- }
/**
* Returns the reference of this named range, such as Sales!C20:C30.
*
* @return the reference of this named range
*/
- public String getFormula() {
+ public String getRefersToFormula() {
return ctName.getStringValue();
}
* @param formulaText the reference to set
* @throws IllegalArgumentException if the specified reference is unparsable
*/
- public void setFormula(String formulaText) {
+ public void setRefersToFormula(String formulaText) {
XSSFEvaluationWorkbook fpb = XSSFEvaluationWorkbook.create(workbook);
Ptg[] ptgs;
try {
* @return true if the name refers to a deleted cell, false otherwise
*/
public boolean isDeleted(){
- String ref = getReference();
+ String ref = getRefersToFormula();
return ref != null && ref.indexOf("#REF!") != -1;
}
int sheetId = (int)ctName.getLocalSheetId();
return workbook.getSheetName(sheetId);
} else {
- String ref = getReference();
+ String ref = getRefersToFormula();
AreaReference areaRef = new AreaReference(ref);
return areaRef.getFirstCell().getSheetName();
}
XSSFName name = getBuiltInName(XSSFName.BUILTIN_PRINT_AREA, sheetIndex);
if (name == null) return null;
//adding one here because 0 indicates a global named region; doesnt make sense for print areas
- return name.getReference();
+ return name.getRefersToFormula();
}
sb.append("!");
sb.append(parts[i]);
}
- name.setFormula(sb.toString());
+ name.setRefersToFormula(sb.toString());
}
/**
if (name == null) {
name = createBuiltInName(XSSFName.BUILTIN_PRINT_TITLE, sheetIndex);
String reference = getReferenceBuiltInRecord(name.getSheetName(), startColumn, endColumn, startRow, endRow);
- name.setReference(reference);
+ name.setRefersToFormula(reference);
namedRanges.add(name);
}
* Specifies the spacing that should be added above the first line in this
* paragraph in the document in absolute units.
*
- * @return
+ * @return the spacing that should be added above the first line
* @see #setSpacingBefore(BigInteger)
*/
public BigInteger getSpacingBefore() {
* document in line units.
* The value of this attribute is specified in one hundredths of a line.
*
- * @return
+ * @return the spacing that should be added before the first line in this paragraph
* @see #setSpacingBeforeLines(BigInteger)
*/
public BigInteger getSpacingBeforeLines() {
assertEquals(0, wb.getNameAt(0).getCTName().getLocalSheetId());
assertFalse(wb.getNameAt(0).getCTName().isSetLocalSheetId());
- assertEquals("SheetA!$A$1", wb.getNameAt(0).getReference());
+ assertEquals("SheetA!$A$1", wb.getNameAt(0).getRefersToFormula());
assertEquals("SheetA", wb.getNameAt(0).getSheetName());
assertEquals(0, wb.getNameAt(1).getCTName().getLocalSheetId());
assertFalse(wb.getNameAt(1).getCTName().isSetLocalSheetId());
- assertEquals("SheetB!$A$1", wb.getNameAt(1).getReference());
+ assertEquals("SheetB!$A$1", wb.getNameAt(1).getRefersToFormula());
assertEquals("SheetB", wb.getNameAt(1).getSheetName());
assertEquals(0, wb.getNameAt(2).getCTName().getLocalSheetId());
assertFalse(wb.getNameAt(2).getCTName().isSetLocalSheetId());
- assertEquals("SheetC!$A$1", wb.getNameAt(2).getReference());
+ assertEquals("SheetC!$A$1", wb.getNameAt(2).getRefersToFormula());
assertEquals("SheetC", wb.getNameAt(2).getSheetName());
// Save and re-load, still there
XSSFWorkbook nwb = XSSFTestDataSamples.writeOutAndReadBack(wb);
assertEquals(3, nwb.getNumberOfNames());
- assertEquals("SheetA!$A$1", nwb.getNameAt(0).getReference());
+ assertEquals("SheetA!$A$1", nwb.getNameAt(0).getRefersToFormula());
}
/**
name2.setNameName("testTwo");\r
\r
String ref1 = "Test1!$A$1:$B$1";\r
- name1.setReference(ref1);\r
- assertEquals(ref1, name1.getReference());\r
+ name1.setRefersToFormula(ref1);\r
+ assertEquals(ref1, name1.getRefersToFormula());\r
assertEquals("Test1", name1.getSheetName());\r
\r
String ref2 = "'Testing Named Ranges'!$A$1:$B$1";\r
- name1.setReference(ref2);\r
- //XSSFName#setReference stores the reference in canonical form and puts the sheet name in single quotes\r
- assertEquals("'Testing Named Ranges'!$A$1:$B$1", name1.getReference());\r
+ name1.setRefersToFormula(ref2);\r
+ assertEquals("'Testing Named Ranges'!$A$1:$B$1", name1.getRefersToFormula());\r
assertEquals("Testing Named Ranges", name1.getSheetName());\r
\r
assertEquals(-1, name1.getLocalSheetId());\r
workBook.createSheet("Test");\r
XSSFName name = workBook.createName();\r
name.setNameName("\u03B1");\r
- name.setReference("Test!$D$3:$E$8");\r
+ name.setRefersToFormula("Test!$D$3:$E$8");\r
\r
\r
XSSFWorkbook workBook2 = XSSFTestDataSamples.writeOutAndReadBack(workBook);\r
XSSFName name2 = workBook2.getNameAt(0);\r
\r
assertEquals("\u03B1", name2.getNameName());\r
- assertEquals("Test!$D$3:$E$8", name2.getReference());\r
+ assertEquals("Test!$D$3:$E$8", name2.getRefersToFormula());\r
}\r
\r
public void testAddRemove() {\r
XSSFName nr1 = wb.getNameAt(0);
assertEquals(XSSFName.BUILTIN_PRINT_TITLE, nr1.getNameName());
- assertEquals("'FirstSheet'!$A:$A,'FirstSheet'!$1:$4", nr1.getReference());
+ assertEquals("'FirstSheet'!$A:$A,'FirstSheet'!$1:$4", nr1.getRefersToFormula());
// Save and re-open
XSSFWorkbook nwb = XSSFTestDataSamples.writeOutAndReadBack(wb);
nr1 = nwb.getNameAt(0);
assertEquals(XSSFName.BUILTIN_PRINT_TITLE, nr1.getNameName());
- assertEquals("'FirstSheet'!$A:$A,'FirstSheet'!$1:$4", nr1.getReference());
+ assertEquals("'FirstSheet'!$A:$A,'FirstSheet'!$1:$4", nr1.getRefersToFormula());
// check that setting RR&C on a second sheet causes a new Print_Titles built-in
// name to be created
XSSFName nr2 = nwb.getNameAt(1);
assertEquals(XSSFName.BUILTIN_PRINT_TITLE, nr2.getNameName());
- assertEquals("'SecondSheet'!$B:$C,'SecondSheet'!$1:$1", nr2.getReference());
+ assertEquals("'SecondSheet'!$B:$C,'SecondSheet'!$1:$1", nr2.getRefersToFormula());
nwb.setRepeatingRowsAndColumns(1, -1, -1, -1, -1);
assertEquals(0, workbook.getNumberOfNames());
Name nameA = workbook.createName();
- nameA.setReference("A2");
+ nameA.setRefersToFormula("A2");
nameA.setNameName("ForA2");
XSSFName nameB = workbook.createName();
- nameB.setReference("B3");
+ nameB.setRefersToFormula("B3");
nameB.setNameName("ForB3");
nameB.setComment("B3 Comment");
workbook = XSSFTestDataSamples.writeOutAndReadBack(workbook);
assertEquals(2, workbook.getNumberOfNames());
- assertEquals("A2", workbook.getNameAt(0).getReference());
+ assertEquals("A2", workbook.getNameAt(0).getRefersToFormula());
assertEquals("ForA2", workbook.getNameAt(0).getNameName());
assertNull(workbook.getNameAt(0).getComment());
- assertEquals("B3", workbook.getNameAt(1).getReference());
+ assertEquals("B3", workbook.getNameAt(1).getRefersToFormula());
assertEquals("ForB3", workbook.getNameAt(1).getNameName());
assertEquals("B3 Comment", workbook.getNameAt(1).getComment());
workbook = XSSFTestDataSamples.openSampleWorkbook("WithVariousData.xlsx");
assertEquals(2, workbook.getNumberOfNames());
- assertEquals("Sheet1!$A$2:$A$7", workbook.getNameAt(0).getReference());
+ assertEquals("Sheet1!$A$2:$A$7", workbook.getNameAt(0).getRefersToFormula());
assertEquals("AllANumbers", workbook.getNameAt(0).getNameName());
assertEquals("All the numbers in A", workbook.getNameAt(0).getComment());
- assertEquals("Sheet1!$B$2:$B$7", workbook.getNameAt(1).getReference());
+ assertEquals("Sheet1!$B$2:$B$7", workbook.getNameAt(1).getRefersToFormula());
assertEquals("AllBStrings", workbook.getNameAt(1).getNameName());
assertEquals("All the strings in B", workbook.getNameAt(1).getComment());
workbook = XSSFTestDataSamples.writeOutAndReadBack(workbook);
assertEquals(2, workbook.getNumberOfNames());
- assertEquals("Sheet1!$A$2:$A$7", workbook.getNameAt(0).getReference());
+ assertEquals("Sheet1!$A$2:$A$7", workbook.getNameAt(0).getRefersToFormula());
assertEquals("AllANumbers", workbook.getNameAt(0).getNameName());
assertEquals("All the numbers in A", workbook.getNameAt(0).getComment());
- assertEquals("Sheet1!$B$2:$B$7", workbook.getNameAt(1).getReference());
+ assertEquals("Sheet1!$B$2:$B$7", workbook.getNameAt(1).getRefersToFormula());
assertEquals("BStringsFun", workbook.getNameAt(1).getNameName());
assertEquals("All the strings in B", workbook.getNameAt(1).getComment());
}
HSSFWorkbook wb = new HSSFWorkbook();
HSSFSheet sheet = wb.createSheet("Sheet1");
HSSFName name = wb.createName();
- name.setFormula("Sheet1!B1");
+ name.setRefersToFormula("Sheet1!B1");
name.setNameName("pfy1");
Ptg[] ptgs;
HSSFName name = wb.createName();
wb.createSheet("Sheet1");
name.setNameName("test");
- name.setFormula("Sheet1!A1+Sheet1!A2");
- assertEquals("Sheet1!A1+Sheet1!A2", name.getFormula());
- name.setFormula("5*6");
- assertEquals("5*6", name.getFormula());
+ name.setRefersToFormula("Sheet1!A1+Sheet1!A2");
+ assertEquals("Sheet1!A1+Sheet1!A2", name.getRefersToFormula());
+ name.setRefersToFormula("5*6");
+ assertEquals("5*6", name.getRefersToFormula());
}
}
projects / poi.git / commitdiff