Repository navigation
This release adds AutoFilter criteria and sorting, threaded comments, pictures in cells, checkboxes, text boxes and shapes, sparklines, ignored errors, workbook protection, document properties, sheet views, headers and footers, autofit, getText and streamed writing, and fixes SubString arguments (#498). It requires XML.jl v0.4.9. Two changes may affect existing code: see the Migration Guide.
Full details under the fold
-
Fix: functions that take a sheet name, a cell reference or a text keyword accept any
AbstractString, not just aString, so a name made withstrip,splitorfirst(name, 31)works #498 (Thanks to @mcvmcv for the report). ASubStringused to throw aMethodError(or aTypeErrorfor a keyword). Affected:- Sheet names:
addsheet!,renamesheet!,copysheet!,newxlsx,xf[name],readdata,readtable,readto,readtransposedtable,writetable(...; sheetname), thesheetnameofaddChartandaddChartEx, and the streamingaddsheet! (xf, "Sheet!A1")forms:setFont,setFill,setBorder,setAlignment,setFormat, thesetUniform*setters,setColumnWidth,setRowHeight,mergeCells,setConditionalFormat,addDataValidationandsetFormula- Getters, in both forms:
getFont,getFill,getBorder,getAlignment,getFormat,getText,getColumnWidth,getRowHeight,isMergedCell,getMergedBaseCell,getFormulaandgetRichTextString - Text keywords:
setFont'sname,underandvertAlign,setFill'spattern,setAlignment'shorizontalandvertical,setFormat'sformat, a conditional format's numberformat,setColoredDataBars's keywords, andwritetable'sanchor_cell - Other: a text or formula value for
addDefinedName, a dynamic-array formula (=SORT(...)) forsetFormula,column_labelswithnormalizenames=true,first_columngiven as a letter, andRichTextRun
A
RichTextStringor a StyledStringsstyled"…"string is used as its plain text. Before,renamesheet!with aSubStringfailed after it had renamed the sheet inworkbook.xml, leaving theWorksheetwith its old name; andaddsheet!andcopysheet!failed after adding the new sheet's part and relationship - Sheet names:
-
Requires XML.jl v0.4.9. XLSX.jl calls
@for_each_child!in place of@for_each_child, which XML.jl v0.4.9 deprecates and v0.5 removes, so it no longer warns underPkg.testand precompiles and reads sheets under--depwarn=error#496 (Thanks to @mathieu17g for the report) -
Reading a worksheet reads each
<row>and<c>'s attributes once, where XML.jl's cursor stands (XML.eachattribute!, new in v0.4.9), rather than reading the tag again for each attribute:readtableis 8–13% faster and opening a file for editing 3–6% faster on the benchmark fixtures -
Parts are saved without the line breaks and indentation XML.jl added between elements (
XML.write(…; pretty=false), new in v0.4.9). A part XLSX.jl reads and doesn't change, such as a chart, theme or styles part, is saved as Excel wrote it, bar the line end after its XML declaration, where it used to grow by up to 5% -
Benchmarks:
bench/external_read.jltimes Python's readers, python-calamine, fastexcel and openpyxl, reading the same tables asreadtable, in an optional environment of its own (bench/envs/python, whose CondaPkg installs a private Python), andreport.jlshows them beside XLSX.jl's times. It isn't a test dependency. Measured on 2026-11-13, XLSX.jl reads a table 3 to 6 times as fast as openpyxl, and takes 1.5 to 2 times as long as python-calamine and 2.6 to 4 times as long as fastexcel -
Docs: the warning on
openxlsxabout saving over the original inmode="rw"listed charts among the parts XLSX.jl can't process. It now says what the round-trip tests show: parts XLSX.jl doesn't model (pivot tables, slicers, timelines, external links, custom XML, VBA projects) are kept but not updated, the calculation chain is dropped for Excel to rebuild, and a Strict file is saved as Transitional. The tutorial and the Supported features page say the same -
Fix: saving a workbook replaced its calculation settings (
<calcPr>) withfullCalcOnLoad="1" calcMode="auto", losing manual calculation, iterative calculation (for circular references) and its iteration count, the R1C1 reference style, "precision as displayed" and Excel'scalcId. They are kept now, withfullCalcOnLoad="1"added so that Excel recalculates every formula on opening. As Excel does, a workbook set to manual calculation stays so, and is recalculated only when asked (F9) -
Fix: a row whose height Excel had fitted to its text (an
htwithoutcustomHeight) was saved withcustomHeight="1", which fixed it at that height: Excel no longer fitted it as its text changed.customHeightis now kept as the file has it,setRowHeightsets it, as before, and rowsinsertRowsadds inherit it with their height. Heights in whole points are written as Excel writes them (ht="29", not"29.0") -
Fix: a workbook saved by Excel in another language names its sheet categories in that language in
docProps/app.xml("Planilhas" for "Worksheets"). Saving it added a second, English "Worksheets" category, listing every sheet twice. The categories are now recognised by the sheets they list, and keep their names -
Tests: round-trip fidelity. A workbook made by Excel 365 with parts XLSX.jl doesn't model (a pivot table and its cache, a slicer, a timeline, an external link and custom XML) and with sparklines, a shape, a table and a note, is edited and saved: every part other than
calcChain.xml(which Excel rebuilds) is kept unchanged, as are every relationship and content type, and Excel opens the result without repair, with its pivot table refreshing. Every other test file also keeps all its parts and relationships through an edit and a save -
Defined names are written to
workbook.xmlin Excel's order: by name, ignoring case and the_xlnm.prefix, a sheet's name before the workbook's name of the same name, and sheets in order. They were written in no particular order. Excel read them either way; a file saved by Excel 365 now round-trips with its<definedNames>unchanged -
Docs: the full docs build, with doctests, passes again. The
getTextexample in the cell formats guide wrote"A\$i", which a markdown doctest takes literally; theheaderFooterFieldandheaderFooterFontexamples had noimport XLSX; and the links to the Document properties guide were ambiguous, as the API page has a heading of the same name -
Tests: a defined-names test removes the file it writes
-
setAutoFilter(sheet, rng; filters, sort)filters and sorts the range, as choosing from Excel's filter buttons does.filterspairs columns (by header text, letter or position) with criteria: a value or a list of values to show (text in any case, numbers, dates by the day,true/false,missingfor empty cells), a condition such as">" => 1000or"==" => "A*"with Excel's wildcards, two conditions joined by:andor:or, the top or bottom items or percent, above or below the average, or a date relative to today (:today,:thisWeek,:lastMonth,:yearToDate,:Q1,:M3, …).sortgives one or more columns, each ascending or descending. Excel doesn't reapply a filter or a sort when it opens a file, so, as Excel does when it saves, the rows the criteria don't show are hidden and the rows are put in order: numbers and dates, text in any case, logicals, errors, then empty cells, as Excel's sort orders them. Each row's cells move with their formats, notes, threaded comments and hyperlinks, and formulas move as if copied (=B5*2in row 5 becomes=B2*2in row 2), as in Excel. A range with merged cells, array formulas, or formulas shared with cells outside it is refused. For each kind of criterion and for a sort by two columns, the rows hidden, the order, the formulas and the XML are the same as Excel 365 gave for the same data, and Excel reapplying XLSX.jl's filters hides the same rows.filters=[]removes the criteria and shows the rows again. The sheet is marked as filtered (filterMode), as Excel marks it. Filtering by colour or icon isn't supported -
removeAutoFilteralso removes the filter's sort and the sheet's filtered mark -
addThreadedComment(sheet, ref, text; author)starts a threaded comment, Excel 365's Review → New Comment,addThreadedReplyadds a reply,setThreadedCommentResolvedresolves or reopens the thread, anddeleteThreadedCommentdeletes it with its replies. Each author becomes one of the workbook's people, shared by every comment with the same name. As Excel does, each thread also has a note holding the conversation as text for versions of Excel without threads, kept up to date as replies are added. The XML is the same as Excel 365 writes, checked against a file saved by Excel; Excel reads back every thread, reply, author and resolved thread from a file XLSX.jl writes, and keeps them when it saves.addCommentrefuses a cell that has a thread, as before, and a thread refuses a cell that has a note, since a cell has one or the other -
addHyperlinkputs a link on a range of cells ("A1:C3"), which works from any of them. As Excel does, the text goes in the range's top-left cell if it is empty, and every empty cell in the range gets the link font. A link may not overlap another.deleteHyperlinkgiven a range deletes every link overlapping it -
Internal: the threaded comment reader moves from
comments.jltothreadedcomments.jl, beside the new writer;_put_note!and_remove_note!write and remove a note and its box foraddComment,deleteCommentand threaded comments alike. Filter criteria and sorting are infiltersort.jl -
Pictures in cells, Excel 365's Insert → Pictures → Place in Cell:
sheet[ref] = CellImage("logo.png"; alt="Logo"), oraddImage(sheet, ref, image; inCell=true, alt), puts a PNG, JPEG or GIF picture in a cell as its value, keeping the cell's format.writetablewrites a column ofCellImages. A picture shown in several cells is stored once, as Excel stores it.getCellImage(sheet, ref)reads the picture in a cell, with its alternative text, andgetCellImages(sheet)lists every picture in a sheet's cells, from any file; both also read the picture anIMAGEformula shows, with its web address. A cell holding a picture still reads asmissing, andiserrorandgeterrorstill give it Excel's stored#VALUE!, as before.deleteImage(sheet, ref)deletes the picture in the cell as well as floating images there. The rich-value XML is the same as Excel 365 writes for the same pictures, checked against a file saved by Excel; Excel opens XLSX.jl's files with every picture in place, and keeps them when it saves. Streamed sheets can't hold pictures -
Fix: a cell holding a picture, the result of an
IMAGEformula, or another rich value such as a#SPILL!error kept its link to the value (itsvmattribute) when the file was saved. Saving a workbook opened withmode="rw"turned every picture placed in a cell into a plain#VALUE! -
Fix: a dynamic-array formula written to a workbook whose
xl/metadata.xmlhad no dynamic-array record pointed at a cell-metadata record that didn't exist (cm="1"). Dynamic-array formulas and pictures in cells now sharexl/metadata.xml, each adding the records it needs in Excel's form -
setCheckbox(sheet, ref)puts checkboxes in cells, as Excel 365's Insert → Checkbox does, andremoveCheckboxtakes them away. A checkbox shows its cell's value, ticked forTRUE: an empty cell is givenFALSE, and other values are kept, which Excel shows instead of a box, as it does for its own. The cells' other formatting is kept, and later formatting keeps the checkbox.hasCheckbox(sheet, ref)andgetCheckboxes(sheet)read them, with whether each is ticked, from any file. The XML is the same as Excel 365 writes, checked against a file saved by Excel, and Excel reads every checkbox back from a file XLSX.jl writes -
Internal:
_restyle_cells!gives cells a changed copy of their style, forsetCellProtectionandsetCheckboxalike;_workbook_part!finds or makes a workbook-level part with its relationship and content type.src/data/metadata.xml, the template for dynamic-array metadata, is no longer needed -
addTextBox(sheet, ref, text; ...)adds a text box, as Excel's Insert → Text Box does, andaddShape(sheet, ref, kind; text, ...)a shape, as Insert → Shapes does: 34 of Excel's preset shapes (rectangles, ovals, triangles, arrows, callouts, stars, flowchart shapes and others), with the names Excel gives each kind. They float over the cells, anchored as images are, over a range or from a cell for a size in pixels. Their text is a string,"\n"starting a paragraph, or aRichTextStringwith runs in different fonts, as in cells;fonttakessetFont's settings for the whole text, andhorizontalandverticalplace it.fill,line,lineWidthandlineDashset the fill and border, in any of XLSX.jl's colour forms. A text box is white with a thin grey border and a shape in the theme's first accent colour, as Excel makes them.getShapeslists a sheet's text boxes and shapes, with their names, kinds, cells and text, from any file, anddeleteShapedeletes them by cell or name. They move with inserted and deleted rows and columns, are deleted with all the rows or columns under them, and are copied bycopysheet!. The XML is the same as Excel 365 writes, checked against files saved by Excel, Excel reads every setting back, and the default names were checked against Excel's for all 34 kinds. The text and colours are written by the DrawingML layer charts use -
copysheet!copies a sheet whose drawing holds only shapes. Excel writes no relationships part for such a drawing, and copying one failed with aKeyError -
addSparklines(sheet, location, data; type, ...)adds a group of sparklines, small line, column or win/loss charts in single cells, as Excel's Insert → Sparklines does: one in a cell, or one for each row or column of the data in a row or column of cells, the data on this sheet or another. The group's options are Excel's: markers on every point or on the high, low, first, last and negative points, colours for each, the horizontal axis, empty cells as gaps, zeros or spanned, hidden data, the line's weight, the vertical axis's limits (each sparkline's own, the group's, or a number), right-to-left, and a range of dates to space the points by.getSparklinesreads a sheet's groups with their options, from any file, anddeleteSparklinesdeletes sparklines, or withgroup=truetheir groups. The XML is the same as Excel 365 writes for the same steps, checked against files saved by Excel, and Excel reads every type and option back from a file XLSX.jl writes -
Sparklines follow edits as Excel's do, checked against Excel's results for each: they move with
insertRows,deleteRows,insertColumnsanddeleteColumns; rows inserted below a sparkline, or columns to its right, get one of their own in its group ("Format Same As Above"); a sparkline whose cell is deleted goes, and one whose data is deleted, with its rows, columns or sheet, stays without data rather than charting#REF!;renamesheet!updates their data, andcopysheet!points the copy's sparklines at the copy. A group left with no sparklines is removed -
Extensions in a worksheet's
<extLst>are kept in the order Excel writes them: a new x14 conditional format goes before sparklines, rather than after whatever extensions the sheet already had. Its<ext>also writesuribeforexmlns:x14, as Excel does -
Internal:
_worksheet_ext!finds or makes a worksheet extension, for x14 conditional formats and sparklines alike;_cell_region, formerly in the ignored-errors code alone, turns a reference into its ranges for both -
setIgnoredErrors(sheet, ref; numberStoredAsText=true, ...)turns off Excel's error-checking warnings (the green triangle) for some cells, as Excel's Ignore Error does, or withfalseturns them back on: a number stored as text, a formula resulting in an error, a two-digit year in a text date, a formula inconsistent with its neighbours or its Table's column, a formula omitting cells beside its range, an unlocked formula, a reference to empty cells, and a value outside a list validation.getIgnoredErrorsreads them, for the sheet or one cell, andremoveIgnoredErrorsturns them all back on, in a range or the whole sheet. As Excel writes them, each cell is listed once, with every warning ignored in it, so a range is split where its cells' warnings come to differ; the XML is the same as Excel 365 writes for the same steps, checked against a file saved by Excel, and Excel reads back every warning, for each of the nine kinds, from a file XLSX.jl writes. The ranges move withinsertRows,deleteRows,insertColumnsanddeleteColumns, which already moved them -
protectWorkbook(xf; password, structure=true, windows=false)protects a workbook's structure, as Excel's Review → Protect Workbook does, so that its sheets can't be added, deleted, moved, renamed, hidden or unhidden in Excel;unprotectWorkbook,isWorkbookProtectedandgetWorkbookProtectionremove and read it. The password is stored as Excel's legacy hash, asprotectSheetstores one. Checked in Excel 365: it refuses a wrong password and accepts the right one, refuses to add a sheet to a protected workbook, and has the element where Excel writes it.getWorkbookProtectionalso recognises Excel's own SHA-512 passwords. Excel 365 for Windows ignoreswindows, which only Excel for Mac and older versions use -
The password errors of
protectSheetsay "protection password" rather than "sheet password", as they now come fromprotectWorkbooktoo -
setDocumentProperties(xf; title, subject, creator, keywords, description, lastModifiedBy, category, contentStatus, created, modified, company, manager)sets a workbook's document properties, those of Excel's File → Info, andgetDocumentPropertiesreads them back, the dates asDateTimes in UTC.setCustomProperty(xf, name, value)sets a custom property, typed as a string, number,Boolor date as Excel types it, addingdocProps/custom.xmlwith its relationship and content type when the file has none;getCustomProperty,getCustomPropertiesanddeleteCustomPropertyread and delete them. Names ignore case, as in Excel. Properties other programs write, such as sensitivity labels and lists, are kept as they are, and a missing core or app part is added when needed. The XML is the same as Excel 365 writes for the same properties, checked against a file saved by Excel, and Excel reads back every property, with its type, from a file XLSX.jl writes. The getters work on files opened for reading only -
OrderedCollections, already a dependency, is now imported, for
getCustomProperties -
setSheetView(sheet; zoom, view, showGridLines, showRowColHeaders, showZeros, rightToLeft, topLeftCell, activeCell, selection)sets how a worksheet looks when Excel opens it, as Excel's View tab does: the zoom (10 to 400 percent, kept for each view as Excel keeps it), Normal, Page Layout or Page Break Preview, whether gridlines, row and column headings and zeros are shown, right-to-left, the cell scrolled to the top left, and the selected cells and active cell.getSheetViewreads them back from any file, including one opened for reading only. With frozen or split panes, the scroll position and selection are the active pane's, as Excel keeps them. The XML is the same as Excel 365 writes for each setting, checked against a file saved by Excel, and Excel opens XLSX.jl's files with every setting as given -
freezePanes,splitFreezeandsplitPanesscroll the view back to the top. Excel counts frozen rows and columns from the cell in view, so a sheet saved scrolled to row 10 and then frozen withnrows=1would have had row 10 frozen in Excel, not row 1. They also write the<pane>attributes and the panes'<selection>s in the order Excel writes them, where the order varied before -
Internal:
_apply_pane!andsetSheetViewshare one function that rewrites a sheet's<sheetView>, writing its attributes in the schema's order -
setHeaderFooter(sheet; header, footer, ...)sets the headers and footers printed on a worksheet's pages, as Excel's Page Setup → Header/Footer does: each as a left, centre and right section (header=(left="Sales", right="Page &P of &N")) or a single centred string, with different ones for the first page (firstHeader,firstFooter) and for even pages (evenHeader,evenFooter), and whether they scale with the sheet and align with its margins.getHeaderFooterreads them back, split into sections, from any file, including one opened for reading only, andremoveHeaderFooterremoves them.headerFooterField(:page)and the like give Excel's codes for the page number, number of pages, date, time, file name, folder and sheet name, andheaderFooterFont(; name, bold, italic, size, color, ...)gives the codes that change the font, with the keywords ofsetFont. The XML is the same as Excel 365 writes for the same settings, checked against a file saved by Excel, and Excel reads back every header XLSX.jl writes. A header or footer is limited to 255 characters, as in Excel. Pictures in headers and footers aren't supported -
Internal:
_set_sheet_element!takes the children to give the element, as well as its attributes -
autofitColumns(sheet, cols=:; min_width, max_width)sets columns to the width of the text their cells show, as Excel's AutoFit Column Width does: each cell's value in its number format (so1234567.891formatted#,##0.00is measured as1,234,567.89), in its font, size and boldness, the longest line of a cell with several, merged cells left out. Characters are measured with the widths Excel 365 uses for Calibri, Aptos, Aptos Narrow, Arial, Times New Roman and Courier New, measured from Excel's own autofit. On 50 cells of different fonts, sizes, formats and lengths, the widths are within 0.2 characters of the ones Excel's AutoFit sets at the median and within 1.4 at most; they are approximate, as Excel's own vary a little with the screen -
getText(sheet, ref)gives the text Excel shows in a cell, its value in its number format, as Excel'sRange.Textdoes:"1,234.50","7 March 2026","25.6%". It renders General, digit placeholders, thousands separators and scaling, percentages, scientific and engineering notation, fractions, dates, times and elapsed times, text sections, literals, currency and locale codes, colours and conditions, and matches Excel 365 on 198 of 201 cases read from Excel (a fill repeated to the column's width, and two times exactly half-way between hundredths of a second, differ). It works on files opened for reading only, with or without the cell cache -
setFormataccepts the format codes Excel accepts and refuses the ones it refuses, checked against Excel 365 on 62 codes. It refused scientific formats withE-or a one-digit exponent, fractions with a fixed denominator (# ?/4), theeyear code, colours by number ([Color12]), upper-case date codes and letters Excel shows as they are (x0,0.0c); it accepted unknown colours ([Purple]) and date codes among digit placeholders (0 h), which Excel refuses -
Behavior change: the built-in number formats 6, 8, 38 and 40 have Excel's codes,
$#,##0_);[Red]($#,##0)and so on, and 47 ismm:ss.0.getFormatreportedRedwithout brackets andmmss.0, andsetFormatgiven Excel's code for one of them added a custom format rather than using the built-in -
setFormulatakes avaluekeyword, the formula's result, saved as its cached value as Excel saves the last value it calculated: a number, string,Bool, date or time, or an error value such asXL_NA, written after the<f>with the cell type Excel gives it (t="b",t="e", …). A string is written in the cell (t="str"), as Excel writes it. For a range, give one value for every cell or an array of the range's shape. XLSX.jl, pandas, calamine and file previews, which read cached values rather than calculating formulas, read the value rather than an empty cell. A date or time gives the cell a date or time format, as writing it to a cell does. Excel still recalculates every formula when it opens the file -
Formulas are written as Excel 365 writes them, checked by saving XLSX.jl's files in Excel: without a leading
=in<f>(a formula given tosetFormulaas"=SUM(A1:A3)"was written as<f>=SUM(A1:A3)</f>), and with a string result in the cell ast="str", not as a shared string, whether set withsetFormula(...; value)or read from a file. Excel read the old form too, and rewrote it in this form when it saved.getFormulastill returns formulas with a leading=, andsetFormulatakes them with or without one -
setFormulaon a non-contiguous range ("A1:A3,C1", or a defined name for one), or with rows or columns given as a vector or step range, gives anXLSXErrorsaying so, rather than aMethodError -
Write large files in constant memory.
writetable(...; streaming=true)writes the rows straight into the file a chunk at a time, rather than building the workbook in memory first, andstreamxlsxwithaddsheet!andwriterow!writes rows as they are produced. A Tables.jl table read a row at a time (a vector ofNamedTuples, a database query,CSV.Rows) is never held in memory as a whole. A streamed sheet can have column widths, column number formats, a frozen header row and an Excel Table, but no other formatting or objects, and its rows are written once, in order. Writing 1,000,000 rows × 20 mixed columns peaks at 823 MiB rather than 4,448 MiB (the data itself takes 664 MiB), in 10.0 s rather than 17.4 s; 100,000 × 8 strings takes 0.36 s rather than 0.62 s. Strings are written inline in each cell by default, as XlsxWriter, rust_xlsxwriter and Apache POI do when streaming: measured on that table, a shared string table made the file no smaller and needed 350 MiB more, holding every distinct string.shared_strings=truewrites them as Excel does, for data with many repeats. The sheets read back exactly aswritetablewrites them, except that an empty cell is left out, as Excel leaves it out.bench/stream_write.jlmeasures peak memory in a fresh process for each case -
writetableandwritetable!takecolumn_widths,column_formats(aDictfrom column number or name to a number format) andfreeze_header, to set the written columns' widths and number formats and freeze the header row in the same call -
Internal: writing a worksheet is split into its XML before the rows, the rows and the XML after them, and writing the package's other parts into a function of its own, which the streaming writer shares. Cell elements are written by shared helpers. The files written are byte-for-byte the same
-
Sheet names are matched without regard to case, as Excel matches them:
hassheet(xf, "data"),xf["data"],xf["data!A1"],deletesheet!(xf, "DATA")andreadtable(file, "data")all find a sheet namedData. They needed the exact case before, althoughrenamesheet!andaddsheet!already treated names differing only in case as the same. -
setFormatandsetUniformFormataccept custom format codes with the characters Excel shows as they are (/ . ^ & ' ~ { } < > =),!as an escape, theGeneralkeyword and locale codes such as[$-409]or[$€-x-euro2]. Common date formats such as"dd/mm/yyyy"and"dd.mm.yyyy"were rejected as invalid. Each was checked as accepted by Excel 365. -
setCellProtectiontakes rows and columns by number (sheet, 2:20, 2,sheet, [2, 4], 1:3,sheet, :, 5) and whole columns or rows ("B:B","5:6"), which reach as far as the sheet's used range, as the format setters do. Whole columns and rows were refused before. -
clearConditionalFormats(sheet, :)removes every conditional format on a sheet, andclearConditionalFormatstakes whole columns ("B:D"), whole rows ("2:5") and comma-separated mixes, covering the full height or width of the sheet. Only cell ranges were accepted before. -
A data point given a marker of its own (
setMarkerSymbol(c, i, sym; point=p)and the other marker setters) starts from the series' marker size, as Excel 365 writes it. It had no size before, so Excel drew it at its default size. -
clearConditionalFormatsis declared public (not exported: call it asXLSX.clearConditionalFormats) and no longer marked experimental. Its docstring has an example, and the conditional formats guide covers it. -
setColoredDataBarsis declared public (still experimental and not exported: call it asXLSX.setColoredDataBars). Its docstring and the Examples page now say so, where before the API reference listed it while the Examples page called it not public. -
Docs: printed examples in the XLSX Tutorial and the guides to worksheets, named ranges, comments, hyperlinks, data validation, protection, filtering, conditional formats and cell addressing are now doctests, checked on every docs build. The tutorial reads a
myfile.xlsxpublished beside it, which readers can download. Outputs that had drifted are corrected: a worksheet shows asWorksheet, notXLSX.Worksheet; ranges asMatrix{Any}; aDataTableas a one-line summary. A new FAQ and troubleshooting page covers common error messages and surprises. External links are checked by a separate, non-blocking CI job (DOCUMENTER_LINKCHECK=true), and one link that had moved is updated. -
Docs: a Cookbook page of short recipes for common tasks, each tested and most with a picture of the result in Excel. New pictures: every chart kind
addChartcreates, a combo chart, before-and-after pairs for each section of Formatting charts, and the finished form in Examples. Every picture has alt text describing it. Column widths and row heights move to Layout and view. -
Docs: the sidebar is grouped by task: Getting started, Data, Formatting, Layout and view, Worksheets, Images, comments and links, Charts (creating first), Examples, API Reference. The links, images and comments page is split into one page each, and the sheet settings page into Protecting a sheet and Printing, with sheet visibility and tab colour moved to Managing worksheets; the old pages remain as short pointers. A new page, Addressing cells and ranges, collects every way of naming cells, ranges, rows and columns. In the API reference, images, comments and hyperlinks have their own page, and the Tables page separates plain-cell tables from Excel Tables.
-
Docs: new guides for named ranges and for managing worksheets (sheet order moves there from the links, images and comments page), and a tutorial on creating, opening and saving workbooks. The cell formats guide has a number formats section, the conditional formats guide a section on reading and clearing them, and the Excel Tables guide a quick start.
-
Docs: the Home page has an "I want to…" table linking common tasks to their sections; a new Supported features page lists each Excel feature with its functions and guide, and what XLSX.jl doesn't do; the API reference has an alphabetical index; each guide ends with links to its API page and related examples, and each API page links to its guide; the charts overview opens with a short create-a-chart example; sidebar labels name drop-downs, AutoFilter, outlines, protection and printing.
-
Docs: examples use only public API (
setBorder(...; outside=...)in place of the internalsetOutsideBorder, and integer rows and columns in place ofXLSX.CellRange); tutorial DataFrame output is refreshed to current DataFrames printing; broken "described above" references and ausing FileIO, DataFrametypo are fixed. -
A column inserted inside a hidden column span is shown, with the span split around it, as a row inserted among hidden rows already was; and a group that gains a visible row or column loses the collapsed marker on its summary row or column. Both as Excel 365 does; the hidden span used to grow over the new column. Checked against Excel with the fixtures made for P1–P3, now used by the tests.
-
setLabelFlag(c::ChartEx, i, flag, on)shows or hides a chartEx series' label parts (:seriesName,:categoryName,:value), writing labels as Excel 365 does. As in Excel, histogram and Pareto labels have no category name and a Pareto line has no labels. -
Reading conditional formats, and adding a number format, no longer walk every node of the sheet or styles part to find one element.
getConditionalFormatson a 50,000-cell sheet read withreadxlsxtakes half the time (111 ms to 58 ms), and each new number format takes under a microsecond, from 58 μs. -
setLabelFlag(c, i, flag, on)shows or hides one part of ac:series' data labels (:value,:seriesName,:categoryName,:legendKey,:percentor:bubbleSize), andgetLabelFlag(c::Chart, i, flag)reads it back. A series with no labels is given the ones Excel 365 writes when labels are turned on, checked for every chart kind. There was no way to make ac:chart's labels appear before. -
insertRowsandinsertColumnsformat the new rows and columns as Excel does by default ("Format Same As Above"): each new cell takes its neighbour's style, without its border; a row takes the height, style and outline level of the row above, and a column the width, style and outline level of the column to its left; and a conditional format or data validation ending just before the insert grows over it. Checked against Excel 365's own results. The new rows and columns used to be unformatted. -
Deleting all the rows or columns under an image or chart set to move and size with its cells deletes it, with its picture or chart part, as Excel does. It used to shrink to nothing and stay in the file.
-
makeCombo(c)makes a:column,:stackedColumnor:linechart a combo chart, as Excel's Change Chart Type → Combo → "Clustered Column – Line on Secondary Axis" does: the last series becomes a line on new secondary axes and the others clustered columns. As in Excel, the title, legend, axes and the formatting of series that keep their type are kept, and a series that changes type takes the default formatting of its new group, keeping its name, data and data labels. Checked against Excel 365's own results. -
addSeriesandaddChartExtake absolute references, such asData!$B$2:$B$5,'My Data'!$B$1or$B$2:$B$5, so a reference read from a series withgetChartSeriescan be passed straight back. They threw before. -
addSerieswrites a series' children in schema order. A line or scatter series had itsc:smoothwritten before its data, where the schema places it after. -
addChart(ws, :combo; …)creates Excel's "Clustered Column – Line on Secondary Axis" combo chart, from a chart Excel 365 wrote, andaddSeriestakes agroupkeyword,:columnor:line, saying which of a combo chart's groups a series joins. It works on combo charts Excel made too, whichaddSeriesrefused before.groupis required on a chart with more than one plot group and an error on one with a single group. Combo series are formatted as Excel formats them, with markers on the line giving Excel's Line with Markers formatting. -
addSeriesnumbers a new series (c:idx,c:orderand its automatic accent colour) across all of a chart's series rather than within its group. This changes nothing for a chart with one group. -
addChartcreates nine more kinds, from charts Excel 365 wrote::percentStackedColumn,:percentStackedBar,:stackedLine,:percentStackedLine,:stackedLineMarkers,:percentStackedLineMarkers,:stackedArea,:percentStackedAreaand:filledRadar. Series added withaddSeriesare formatted as Excel formats them, the second series and on included.markersandsmoothapply to every line kind, and markers on a stacked line series give it the formatting of the kind with markers, as they do for:line -
addSeriesreads which kind a chart is from its plot group'sbarDir,grouping, marker flag andradarStyle, compared with each kind's template, so an existing stacked or 100% stacked chart, from Excel or elsewhere, takes the matching kind's series formatting. A stacked bar chart was read as a clustered one; the two format their series alike, so files written before are unaffected -
getSeriesFillon a chartEx chart reports the colour Excel draws where the chart itself writes none, which until now was nearly always (Excel writes no fill for acx:series until it is formatted). The colour is read from the chart's style and colours parts as a last rung of the cascade,site.level === :style, and was checked colour for colour against Excel 365: series of box & whisker, funnel, histogram and Pareto charts, a waterfall's increase, decrease and total points, and a treemap's or sunburst's points by top-level category. Lines, text, monochromatic colour schemes andc:charts are unchanged (ac:series without formatting is drawn from itsc:style, not from these parts). A waterfall, treemap or sunburst point'schainnow ends in the:stylerung -
Test fixtures written by Excel 365, with SVG exports of their charts in
test/data/chart_style_svg, record the colours Excel draws -
Internal:
src/charts/chartprops.jl(2,972 lines) is split by object intochartnodes.jl(design notes, node locators and shared helpers),charttext.jl,chartseries.jl,chartaxes.jl,chartlegend.jlandchartcascade.jl. Every function moves unchanged. No change in behaviour -
Writing a worksheet allocates less and is 10–25% faster:
writetableof 100,000 × 8 strings allocates 772 → 336 MiB, and of numbers 986 → 666 MiB (0.55 → 0.44 s). Integers and cell references are written without making strings, the tags are built once, rows are written a chunk at a time into one buffer per thread, and the sheet goes into the file in pieces rather than being copied whole twice. The files written are byte-for-byte the same -
bench/worksheet_write.jltimes each write path on its own, without fixtures, and keeps earlier runs to compare against -
Add
deleteImage, which deletes the images whose top-left corner is in a cell, or one image fromgetImages. The picture file goes too, unless another image still shows it, and a drawing left empty is removed.getImagesis now declared public -
Add
Charts.deleteChart, which deletes a chart on a worksheet with the parts only it uses, and for a chartEx chart its hidden_xlchartnames. A chart on a chartsheet is refused: delete the sheet instead -
Add
getThreadedCommentsandgetThreadedComment, which read Excel 365's threaded comments: each thread's author, text, date and whether it is resolved, with its replies. Threaded comments are still not written -
insertRows,deleteRows,insertColumnsanddeleteColumnsmove Excel Tables, so sheets with tables can now be edited this way. A table grows to take in rows or columns inserted inside it (inserted columns become table columns namedColumn1,Column2, ...) and shrinks as they are deleted from it; one deleted whole is deleted. References to a deleted table or table column (Sales[Amount]) become#REF!everywhere, and formulas in calculated columns and totals rows move. Deleting a table's header row, totals row or all its data rows on their own is refused -
Internal:
addtable!is broken into steps (choosing the name, reading the header, checking the totals row, attaching the table part) -
insertRows,deleteRows,insertColumnsanddeleteColumnsmove the sheet's images, charts and shapes, as each one's move and size with cells setting says (an object all of whose rows or columns are deleted shrinks to nothing), and its comments and their boxes. A comment on a deleted cell is deleted; a threaded comment is moved, but deleting its cell is refused. Sheets with images, charts or comments can now be edited this way -
Add
insertRows,deleteRows,insertColumnsanddeleteColumns, which work as Excel's Insert and Delete commands do. Cells move, with their row heights and attributes, and everything that refers to them follows: formulas on every sheet (relative or absolute), merged cells, conditional formats and data validations (their ranges and formulas, x14 ones included), hyperlinks, the AutoFilter and its filter columns, frozen panes (deleting all the frozen rows and columns unfreezes the sheet) and selections, column widths, page breaks, defined names (including the print area and titles) and chart series. Ranges across an insert grow and ranges cut by a delete shrink; references to deleted cells become#REF!. A shared formula stays shared when the edit moves all its cells alike; one it would change unevenly (references across the edited rows, or a delete inside its block) is stored as one formula per cell afterwards. -
Internal: the
readtableandeachtablerowmethods share one keyword list rather than repeating it, andmergeCells/removeMergedCellsandsetColumnWidth/setRowHeightdefine their shared address methods once. No change in behaviour, except that an unknown keyword toreadtableoreachtablerowis reported against the internal function the keywords are passed to -
Internal:
write.jlis split intosave.jl(writing the package),setdata.jl(writing cells),writetable.jlandsheetops.jl(adding, renaming, copying, deleting and moving sheets), and the Excel Tables half oftable.jlmoves toexceltables.jl.copysheet!anddeletesheet!are broken into steps, and repeated code in the cell format setters, range handling, conditional format data bars and the sheet cache fill is shared. No change in behaviour -
bench/maintainability.jlcounts duplication in code only: it leaves out docstrings, the bodies ofconsttables, lines of nothing but literals, andincludelines, which it counted as duplicated because blanking their literals made unrelated ones look alike -
Add
setCellProtectionandgetCellProtectionto unlock cells, so they can be filled in on a protected sheet, and to hide cells' formulas, as the Protection tab of Excel's Format Cells dialog does. Empty cells are given the format without a value, and the cells' other formatting is kept -
A cell format with both an alignment and a protection setting writes them in the order the schema requires.
setAlignmentadded the alignment after any protection Excel had written -
Add
protectSheet,unprotectSheet,isSheetProtectedandgetSheetProtectionto protect worksheets, with an optional password (Excel's legacy hash, so up to 15 ASCII characters) and the same choice of what users may still do as Excel's Protect Sheet dialog -
Add
setPageSetup/getPageSetup(orientation, paper size, scaling or fit to pages),setPageMargins/getPageMargins,setPrintOptions/getPrintOptions(gridlines, headings, centring), andsetPrintArea,getPrintArea,removePrintArea,setPrintTitles,getPrintTitlesandremovePrintTitlesfor printing. ApageSetupthat links to printer settings keeps the link -
Add
setSheetVisibilityandgetSheetVisibilityto show and hide sheets (:visible,:hiddenor:veryHidden), andsetTabColor,getTabColorandremoveTabColorfor tab colours, on worksheets and chartsheets. Hiding the workbook's last visible sheet is an error, and hiding the sheet the workbook opens on makes the first visible sheet the one it opens on -
Worksheet's internalis_hiddenfield is replaced byvisibility, which tells hidden and very hidden sheets apart.ws.is_hiddenstill reads and sets it -
Add
setAutoFilter,getAutoFilterandremoveAutoFilterto add, read and remove the filter buttons on a plain range of a sheet, outside an Excel Table. The hidden_xlnm._FilterDatabasename Excel keeps for the filter is written and removed with it, and follows the sheet throughcopysheet!,renamesheet!anddeletesheet!. A filter may not overlap an Excel Table -
addtable!,writetable!withas_table=true,appendtable!andsettotals!throw an error rather than place or grow a table onto the sheet's AutoFilter, as Excel does not allow the two to overlap -
Add
setColumnHidden,setRowHidden,isColumnHiddenandisRowHiddento hide and show rows and columns, andgroupRows,groupColumns,ungroupRows,ungroupColumns,getRowOutlineLevelandgetColumnOutlineLevelto group them in an outline, nested up to Excel's seven levels and optionally collapsed. Rows and columns needn't hold data, and can be read from a file opened only for reading -
setRowHeightsets the height of a row with no cells, which is written with just its height. It skipped such rows, returning -1 if every row was empty -
copysheet!copies the attributes of the original's rows: their styles, and whether they are hidden or grouped. The copy's rows had none -
setColumnWidthjoins adjacent column definitions left with the same settings -
Add
addDataValidation,getDataValidations,getDataValidationanddeleteDataValidationto add, read and delete data validation: drop-down lists (fromvaluesor a range), whole and decimal numbers, dates, times, text length and custom formulas, with input and error messages. Validations Excel 2010 wrote in its extended (x14) form are read and deleted too, and validations can be read from a file opened only for reading -
renamesheet!,deletesheet!andcopysheet!now update sheet references in Excel 2010 (x14) data validations, whose formula is held in an<xm:f>inside<x14:formula1>. Those references were left unchanged -
Add
addHyperlink,getHyperlink,getHyperlinksanddeleteHyperlinkto add, read and delete cell hyperlinks: to a web page, email address or file (url), or to a place in the workbook (location). An empty cell given a link takes its display text and a blue, underlined font, as in Excel. Links can be read from a file opened only for reading, with or without the cell cache -
copysheet!gives the copy's hyperlinks to web pages and files relationships of their own. The copy kept the original's relationship ids, which pointed at relationships the copy didn't have -
Docs: a Chart subtypes section in Creating charts maps each of Excel's chart subtypes to the kind or
addSerieskeywords that create it, and the Limitations list of kinds that can't be created is completed -
Docs: the Migration Guide covers v0.12 and v0.13, including every behaviour change in the v0.13 patch releases
-
Docs: the README and home page list the package's features and give a quick start
-
Docs: a new Images, comments and sheet order guide