API Reference
XLSX.XLSXFile — TypeXLSXFile represents a reference to an Excel file.
It is created by using XLSX.readxlsx or XLSX.openxlsx.
From a XLSXFile you can navigate to a XLSX.Worksheet reference as shown in the example below.
Example
xf = XLSX.readxlsx("myfile.xlsx")
-sh = xf["mysheet"] # get a reference to a WorksheetXLSX.readxlsx — Functionreadxlsx(source::Union{AbstractString, IO}) :: XLSXFileMain function for reading an Excel file. This function will read the whole Excel file into memory and return a closed XLSXFile.
Consider using XLSX.openxlsx for lazy loading of Excel file contents.
XLSX.openxlsx — Functionopenxlsx(f::F, source::Union{AbstractString, IO}; mode::AbstractString="r", enable_cache::Bool=true) where {F<:Function}Open XLSX file for reading and/or writing. It returns an opened XLSXFile that will be automatically closed after applying f to the file.
Do syntax
This function should be used with do syntax, like in:
XLSX.openxlsx("myfile.xlsx") do xf
+sh = xf["mysheet"] # get a reference to a WorksheetXLSX.readxlsx — Functionreadxlsx(source::Union{AbstractString, IO}) :: XLSXFileMain function for reading an Excel file. This function will read the whole Excel file into memory and return a closed XLSXFile.
Consider using XLSX.openxlsx for lazy loading of Excel file contents.
XLSX.openxlsx — Functionopenxlsx(f::F, source::Union{AbstractString, IO}; mode::AbstractString="r", enable_cache::Bool=true) where {F<:Function}Open XLSX file for reading and/or writing. It returns an opened XLSXFile that will be automatically closed after applying f to the file.
Do syntax
This function should be used with do syntax, like in:
XLSX.openxlsx("myfile.xlsx") do xf
# read data from `xf`
endFilemodes
The mode argument controls how the file is opened. The following modes are allowed:
r: read mode. The existing data insourcewill be accessible for reading. This is the default mode.w: write mode. Opens an empty file that will be written tosource.rw: edit mode. Openssourcefor editing. The file will be saved to disk when the function ends.
The rw mode is known to produce some data loss. See #159.
Simple data should work fine. Users are advised to use this feature with caution when working with formulas and charts.
Arguments
sourceis IO or the complete path to the file.modeis the file mode, as explained in the last section.enable_cache:
If enable_cache=true, all read worksheet cells will be cached. If you read a worksheet cell twice it will use the cached value instead of reading from disk in the second time.
If enable_cache=false, worksheet cells will always be read from disk. This is useful when you want to read a spreadsheet that doesn't fit into memory.
The default value is enable_cache=true.
Examples
Read from file
The following example shows how you would read worksheet cells, one row at a time, where myfile.xlsx is a spreadsheet that doesn't fit into memory.
julia> XLSX.openxlsx("myfile.xlsx", enable_cache=false) do xf
for r in XLSX.eachrow(xf["mysheet"])
@@ -12,13 +12,13 @@
endEdit an existing file
XLSX.openxlsx("edit.xlsx", mode="rw") do xf
sheet = xf[1]
sheet[2, :] = [2, Date(2019, 1, 1), "add new line"]
-endSee also XLSX.readxlsx.
openxlsx(source::Union{AbstractString, IO}; mode="r", enable_cache=true) :: XLSXFileSupports opening a XLSX file without using do-syntax. In this case, the user is responsible for closing the XLSXFile using close or writing it to file using XLSX.writexlsx.
See also XLSX.writexlsx.
XLSX.writexlsx — Functionwritexlsx(output_source, xlsx_file; [overwrite=false])Writes an Excel file given by xlsx_file::XLSXFile to IO or filepath output_source.
If overwrite=true, output_source (when a filepath) will be overwritten if it exists.
XLSX.sheetnames — Functionsheetnames(xl::XLSXFile)
-sheetnames(wb::Workbook)Returns a vector with Worksheet names for this Workbook.
XLSX.sheetcount — Functionsheetcount(xlsfile) :: IntCounts the number of sheets in the Workbook.
XLSX.Worksheet — TypeA Worksheet represents a reference to an Excel Worksheet.
From a Worksheet you can query for Cells, cell values and ranges.
Example
xf = XLSX.readxlsx("myfile.xlsx")
+endSee also XLSX.readxlsx.
openxlsx(source::Union{AbstractString, IO}; mode="r", enable_cache=true) :: XLSXFileSupports opening a XLSX file without using do-syntax. In this case, the user is responsible for closing the XLSXFile using close or writing it to file using XLSX.writexlsx.
See also XLSX.writexlsx.
XLSX.writexlsx — Functionwritexlsx(output_source, xlsx_file; [overwrite=false])Writes an Excel file given by xlsx_file::XLSXFile to IO or filepath output_source.
If overwrite=true, output_source (when a filepath) will be overwritten if it exists.
XLSX.sheetnames — Functionsheetnames(xl::XLSXFile)
+sheetnames(wb::Workbook)Returns a vector with Worksheet names for this Workbook.
XLSX.sheetcount — Functionsheetcount(xlsfile) :: IntCounts the number of sheets in the Workbook.
XLSX.Worksheet — TypeA Worksheet represents a reference to an Excel Worksheet.
From a Worksheet you can query for Cells, cell values and ranges.
Example
xf = XLSX.readxlsx("myfile.xlsx")
sh = xf["mysheet"] # get a reference to a Worksheet
println( sh[2, 2] ) # access element "B2" (2nd row, 2nd column)
println( sh["B2"] ) # you can also use the cell name
println( sh["A2:B4"] ) # or a cell range
-println( sh[:] ) # all data inside worksheet's dimensionXLSX.readdata — Functionreaddata(source, sheet, ref)
+println( sh[:] ) # all data inside worksheet's dimensionXLSX.readdata — Functionreaddata(source, sheet, ref)
readdata(source, sheetref)Returns a scalar or matrix with values from a spreadsheet.
See also XLSX.getdata.
Examples
These function calls are equivalent.
julia> XLSX.readdata("myfile.xlsx", "mysheet", "A2:B4")
3×2 Array{Any,2}:
1 "first"
@@ -35,21 +35,21 @@
3×2 Array{Any,2}:
1 "first"
2 "second"
- 3 "third"XLSX.getdata — Functiongetdata(sheet, ref)
+ 3 "third"XLSX.getdata — Functiongetdata(sheet, ref)
getdata(sheet, row, column)Returns a scalar or a matrix with values from a spreadsheet. ref can be a cell reference or a range.
Indexing in a Worksheet will dispatch to getdata method.
Example
julia> f = XLSX.readxlsx("myfile.xlsx")
julia> sheet = f["mysheet"]
julia> matrix = sheet["A1:B4"]
-julia> single_value = sheet[2, 2] # B2See also XLSX.readdata.
getdata(ws::Worksheet, cell::Cell) :: CellValueReturns a Julia representation of a given cell value. The result data type is chosen based on the value of the cell as well as its style.
For example, date is stored as integers inside the spreadsheet, and the style is the information that is taken into account to chose Date as the result type.
For numbers, if the style implies that the number is visualized with decimals, the method will return a float, even if the underlying number is stored as an integer inside the spreadsheet XML.
If cell has empty value or empty String, this function will return missing.
XLSX.getcell — Functiongetcell(xlsxfile, cell_reference_name) :: AbstractCell
+julia> single_value = sheet[2, 2] # B2See also XLSX.readdata.
getdata(ws::Worksheet, cell::Cell) :: CellValueReturns a Julia representation of a given cell value. The result data type is chosen based on the value of the cell as well as its style.
For example, date is stored as integers inside the spreadsheet, and the style is the information that is taken into account to chose Date as the result type.
For numbers, if the style implies that the number is visualized with decimals, the method will return a float, even if the underlying number is stored as an integer inside the spreadsheet XML.
If cell has empty value or empty String, this function will return missing.
XLSX.getcell — Functiongetcell(xlsxfile, cell_reference_name) :: AbstractCell
getcell(worksheet, cell_reference_name) :: AbstractCell
getcell(sheetrow, column_name) :: AbstractCell
-getcell(sheetrow, column_number) :: AbstractCellReturns the internal representation of a worksheet cell.
Returns XLSX.EmptyCell if the cell has no data.
getcell(sheet, ref)Returns an AbstractCell that represents a cell in the spreadsheet.
Example:
julia> xf = XLSX.readxlsx("myfile.xlsx")
+getcell(sheetrow, column_number) :: AbstractCellReturns the internal representation of a worksheet cell.
Returns XLSX.EmptyCell if the cell has no data.
getcell(sheet, ref)Returns an AbstractCell that represents a cell in the spreadsheet.
Example:
julia> xf = XLSX.readxlsx("myfile.xlsx")
julia> sheet = xf["mysheet"]
-julia> cell = XLSX.getcell(sheet, "A1")XLSX.getcellrange — Functiongetcellrange(sheet, rng)Returns a matrix with cells as Array{AbstractCell, 2}. rng must be a valid cell range, as in "A1:B2".
XLSX.row_number — Functionrow_number(c::CellRef) :: IntReturns the row number of a given cell reference.
XLSX.column_number — Functioncolumn_number(c::CellRef) :: IntReturns the column number of a given cell reference.
XLSX.eachrow — Functioneachrow(sheet)Creates a row iterator for a worksheet.
Example: Query all cells from columns 1 to 4.
left = 1 # 1st column
+julia> cell = XLSX.getcell(sheet, "A1")XLSX.getcellrange — Functiongetcellrange(sheet, rng)Returns a matrix with cells as Array{AbstractCell, 2}. rng must be a valid cell range, as in "A1:B2".
XLSX.row_number — Functionrow_number(c::CellRef) :: IntReturns the row number of a given cell reference.
XLSX.column_number — Functioncolumn_number(c::CellRef) :: IntReturns the column number of a given cell reference.
XLSX.eachrow — Functioneachrow(sheet)Creates a row iterator for a worksheet.
Example: Query all cells from columns 1 to 4.
left = 1 # 1st column
right = 4 # 4th column
for sheetrow in XLSX.eachrow(sheet)
for column in left:right
@@ -57,7 +57,7 @@
# do something with cell
end
-endXLSX.readtable — Functionreadtable(
+endXLSX.readtable — Functionreadtable(
source,
sheet,
[columns];
@@ -73,7 +73,7 @@
return !ismissing(v) && v == "unwanted value"
endkeep_empty_rows determines whether rows where all column values are equal to missing are kept (true) or dropped (false) from the resulting table. keep_empty_rows never affects the bounds of the table; the number of rows read from a sheet is only affected by, first_row, stop_in_empty_row and stop_in_row_function (if specified). keep_empty_rows is only checked once the first and last row of the table have been determined, to see whether to keep or drop empty rows between the first and the last row.
Example
julia> using DataFrames, XLSX
-julia> df = DataFrame(XLSX.readtable("myfile.xlsx", "mysheet"))See also: XLSX.gettable.
XLSX.gettable — Functiongettable(
+julia> df = DataFrame(XLSX.readtable("myfile.xlsx", "mysheet"))See also: XLSX.gettable.
XLSX.gettable — Functiongettable(
sheet,
[columns];
[first_row],
@@ -90,7 +90,7 @@
julia> df = XLSX.openxlsx("myfile.xlsx") do xf
DataFrame(XLSX.gettable(xf["mysheet"]))
- endSee also: XLSX.readtable.
XLSX.eachtablerow — Functioneachtablerow(sheet, [columns]; [first_row], [column_labels], [header], [stop_in_empty_row], [stop_in_row_function], [keep_empty_rows])Constructs an iterator of table rows. Each element of the iterator is of type TableRow.
header is a boolean indicating whether the first row of the table is a table header.
If header == false and no column_labels were supplied, column names will be generated following the column names found in the Excel file.
The columns argument is a column range, as in "B:E". If columns is not supplied, the column range will be inferred by the non-empty contiguous cells in the first row of the table.
The user can replace column names by assigning the optional column_labels input variable with a Vector{Symbol}.
stop_in_empty_row is a boolean indicating whether an empty row marks the end of the table. If stop_in_empty_row=false, the iterator will continue to fetch rows until there's no more rows in the Worksheet. The default behavior is stop_in_empty_row=true. Empty rows may be returned by the iterator when stop_in_empty_row=false.
stop_in_row_function is a Function that receives a TableRow and returns a Bool indicating if the end of the table was reached.
Example for stop_in_row_function:
function stop_function(r)
+ endSee also: XLSX.readtable.
XLSX.eachtablerow — Functioneachtablerow(sheet, [columns]; [first_row], [column_labels], [header], [stop_in_empty_row], [stop_in_row_function], [keep_empty_rows])Constructs an iterator of table rows. Each element of the iterator is of type TableRow.
header is a boolean indicating whether the first row of the table is a table header.
If header == false and no column_labels were supplied, column names will be generated following the column names found in the Excel file.
The columns argument is a column range, as in "B:E". If columns is not supplied, the column range will be inferred by the non-empty contiguous cells in the first row of the table.
The user can replace column names by assigning the optional column_labels input variable with a Vector{Symbol}.
stop_in_empty_row is a boolean indicating whether an empty row marks the end of the table. If stop_in_empty_row=false, the iterator will continue to fetch rows until there's no more rows in the Worksheet. The default behavior is stop_in_empty_row=true. Empty rows may be returned by the iterator when stop_in_empty_row=false.
stop_in_row_function is a Function that receives a TableRow and returns a Bool indicating if the end of the table was reached.
Example for stop_in_row_function:
function stop_function(r)
v = r[:col_label]
return !ismissing(v) && v == "unwanted value"
endkeep_empty_rows determines whether rows where all column values are equal to missing are kept (true) or skipped (false) by the row iterator. keep_empty_rows never affects the bounds of the iterator; the number of rows read from a sheet is only affected by first_row, stop_in_empty_row and stop_in_row_function (if specified). keep_empty_rows is only checked once the first and last row of the table have been determined, to see whether to keep or drop empty rows between the first and the last row.
Example code:
for r in XLSX.eachtablerow(sheet)
@@ -98,15 +98,15 @@
rn = XLSX.row_number(r) # `TableRow` row number.
v1 = r[1] # will read value at table column 1.
v2 = r[:COL_LABEL2] # will read value at column labeled `:COL_LABEL2`.
-endSee also XLSX.gettable.
XLSX.writetable — Functionwritetable(filename, table; [overwrite], [sheetname])Write Tables.jl table to the specified filename.
writetable(filename::Union{AbstractString, IO}, tables::Vector{Pair{String, T}}; overwrite::Bool=false)
-writetable(filename::Union{AbstractString, IO}, tables::Pair{String, Any}...; overwrite::Bool=false)writetable(filename, data, columnnames; [overwrite], [sheetname])datais a vector of columns.columnamesis a vector of column labels.overwriteis aBoolto control iffilenameshould be overwritten if already exists.sheetnameis the name for the worksheet.
Example
import XLSX
+endSee also XLSX.gettable.
XLSX.writetable — Functionwritetable(filename, table; [overwrite], [sheetname])Write Tables.jl table to the specified filename.
writetable(filename::Union{AbstractString, IO}, tables::Vector{Pair{String, T}}; overwrite::Bool=false)
+writetable(filename::Union{AbstractString, IO}, tables::Pair{String, Any}...; overwrite::Bool=false)writetable(filename, data, columnnames; [overwrite], [sheetname])datais a vector of columns.columnamesis a vector of column labels.overwriteis aBoolto control iffilenameshould be overwritten if already exists.sheetnameis the name for the worksheet.
Example
import XLSX
columns = [ [1, 2, 3, 4], ["Hey", "You", "Out", "There"], [10.2, 20.3, 30.4, 40.5] ]
colnames = [ "integers", "strings", "floats" ]
-XLSX.writetable("table.xlsx", columns, colnames)See also: XLSX.writetable!.
writetable(filename::Union{AbstractString, IO}; overwrite::Bool=false, kw...)
+XLSX.writetable("table.xlsx", columns, colnames)See also: XLSX.writetable!.
writetable(filename::Union{AbstractString, IO}; overwrite::Bool=false, kw...)
writetable(filename::Union{AbstractString, IO}, tables::Vector{Tuple{String, Vector{Any}, Vector{String}}}; overwrite::Bool=false)Write multiple tables.
kw is a variable keyword argument list. Each element should be in this format: sheetname=( data, column_names ), where data is a vector of columns and column_names is a vector of column labels.
Example:
julia> import DataFrames, XLSX
julia> df1 = DataFrames.DataFrame(COL1=[10,20,30], COL2=["Fist", "Sec", "Third"])
julia> df2 = DataFrames.DataFrame(AA=["aa", "bb"], AB=[10.1, 10.2])
-julia> XLSX.writetable("report.xlsx", "REPORT_A" => df1, "REPORT_B" => df2)XLSX.writetable! — Functionwritetable!(sheet::Worksheet, table; anchor_cell::CellRef=CellRef("A1")))Write Tables.jl table to the specified sheet.
writetable!(sheet::Worksheet, data, columnnames; anchor_cell::CellRef=CellRef("A1"))Writes tabular data data with labels given by columnnames to sheet, starting at anchor_cell.
data must be a vector of columns. columnnames must be a vector of column labels.
See also: XLSX.writetable.
XLSX.rename! — Functionrename!(ws::Worksheet, name::AbstractString)Renames a Worksheet.
XLSX.addsheet! — Functionaddsheet!(workbook, [name]) :: WorksheetCreate a new worksheet with named name. If name is not provided, a unique name is created.