diff --git a/components/fpspreadsheet/docs/api/make_chm.bat b/components/fpspreadsheet/docs/api/make_chm.bat index 88f5d62cb..c0eb91ad1 100644 --- a/components/fpspreadsheet/docs/api/make_chm.bat +++ b/components/fpspreadsheet/docs/api/make_chm.bat @@ -1,4 +1,5 @@ -::set chm_cmd="C:\Program Files (x86)\HTML Help Workshop\hhc.exe" -set chm_cmd=chmcmd.exe +set chm_cmd="C:\Program Files (x86)\HTML Help Workshop\hhc.exe" +::set chm_cmd=chmcmd.exe %chm_cmd% output\fpspreadsheet.hhp +copy /Y output\fpspreadsheet.chm ..\fpspreadsheet-api.chm diff --git a/components/fpspreadsheet/docs/api/source-files.txt b/components/fpspreadsheet/docs/api/source-files.txt index 8416dc737..b9428c2b0 100644 --- a/components/fpspreadsheet/docs/api/source-files.txt +++ b/components/fpspreadsheet/docs/api/source-files.txt @@ -5,5 +5,6 @@ ../../source/common/fpsnumformat.pas ../../source/common/fpsallformats.pas ../../source/common/fpsrpn.pas +../../source/common/fpscurrency.pas ../../source/visual/fpspreadsheetctrls.pas ../../source/visual/fpspreadsheetgrid.pas diff --git a/components/fpspreadsheet/docs/fpspreadsheet-api.chm b/components/fpspreadsheet/docs/fpspreadsheet-api.chm index ca72e67dc..ae6ed8a9d 100644 Binary files a/components/fpspreadsheet/docs/fpspreadsheet-api.chm and b/components/fpspreadsheet/docs/fpspreadsheet-api.chm differ diff --git a/components/fpspreadsheet/source/common/fpscurrency.pas b/components/fpspreadsheet/source/common/fpscurrency.pas index 33623fe86..14a7645cc 100644 --- a/components/fpspreadsheet/source/common/fpscurrency.pas +++ b/components/fpspreadsheet/source/common/fpscurrency.pas @@ -1,3 +1,15 @@ +{@@ ---------------------------------------------------------------------------- + Unit **fpsCurrency** provides a variety of **utility functions** related to + currency values. + + Currency symbols are the key to detection of currency values. + In order to reckognize strings as currency symbols they have to be registered + in the internal CurrencyList. + + LICENSE: See the file COPYING.modifiedLGPL.txt, included in the Lazarus + distribution, for details about the license. +-------------------------------------------------------------------------------} + unit fpsCurrency; {$mode objfpc}{$H+} @@ -29,12 +41,14 @@ var Registers a currency symbol UTF8 string for usage by fpspreadsheet Currency symbols are the key for detection of currency values. In order to - reckognize strings are currency symbols they have to be registered in the + reckognize strings as currency symbols they have to be registered in the internal CurrencyList. Registration occurs automatically for USD, "$", the currencystring defined in the DefaultFormatSettings and for the currency symbols used explicitly when calling WriteCurrency or WriteNumerFormat. + + @param ACurrencySymbol A string symbol which identifies the currency, e.g. '$' -------------------------------------------------------------------------------} procedure RegisterCurrency(ACurrencySymbol: String); begin @@ -42,8 +56,12 @@ begin CurrencyList.Add(ACurrencySymbol); end; -{@@ RegisterCurrencies registers the currency strings contained in the string list +{@@ ---------------------------------------------------------------------------- + RegisterCurrencies() registers the currency strings contained in the string list If AReplace is true, the list replaces the currently registered list. + + @param AList A list containing the strings to be registered as currency symbols. + @param AReplace When this is @true the currently registered symbols are deleted, otherwise the strings are registered as additional currency symbols. -------------------------------------------------------------------------------} procedure RegisterCurrencies(AList: TStrings; AReplace: Boolean); var @@ -59,6 +77,8 @@ end; {@@ ---------------------------------------------------------------------------- Removes registration of a currency symbol string for usage by fpspreadsheet + + @param ACurrencySymbol The currency symbol which is to be un-registered. -------------------------------------------------------------------------------} procedure UnregisterCurrency(ACurrencySymbol: String); var @@ -70,6 +90,9 @@ end; {@@ ---------------------------------------------------------------------------- Checks whether a string is registered as valid currency symbol string + + @param ACurrencySymbol The currency symbol to be checked. + @returns @true of the currency symbol is registered, @false otherwise. -------------------------------------------------------------------------------} function CurrencyRegistered(ACurrencySymbol: String): Boolean; begin @@ -78,6 +101,8 @@ end; {@@ ---------------------------------------------------------------------------- Writes all registered currency symbols to a string list + + @param AList List to which all the registered currency symbols are copied. -------------------------------------------------------------------------------} procedure GetRegisteredCurrencies(AList: TStrings); begin @@ -87,8 +112,11 @@ end; {@@ ---------------------------------------------------------------------------- Checks whether the given number string is a negative value. In case of - currency value, this can be indicated by brackets, or a minus sign at string + currency values, this can be indicated by brackets, or a minus sign at string start or end. + + @param AText String to be analyzed. Brackets or minus sign will be removed if the string is found to correspond to a negative value. + @returns @true when the input string was detected to be a negative number, @false otherwise. -------------------------------------------------------------------------------} function IsNegative(var AText: String): Boolean; begin @@ -119,6 +147,10 @@ end; {@@ ---------------------------------------------------------------------------- Checks wheter a specified currency symbol is contained in a string, removes the currency symbol and returns the remaining string. + + @param ACurrencySymbol The currency symbol to be detected. + @param AText String to be checked. On output, the currency symbol will be removed from the string if found. + @returns @true if the input string did contain a currency symbol, @false otherwise. -------------------------------------------------------------------------------} function RemoveCurrencySymbol(ACurrencySymbol: String; var AText: String): Boolean; var @@ -137,6 +169,12 @@ end; {@@ ---------------------------------------------------------------------------- Checks whether a string is a number with attached currency symbol. Looks also for negative values in brackets. + + @param AText String which is to be converted to a currency value. + @param ANumber Returns the numeric value of the string + @param ACurrencySymbol Returns the currency symbol found. + @param AFormatSettings Contains the decimal separator used in the input string. + @returns @true if the string could be converted to a number successfully, @false otherwise. -------------------------------------------------------------------------------} function TryStrToCurrency(AText: String; out ANumber: Double; out ACurrencySymbol:String; const AFormatSettings: TFormatSettings): boolean; diff --git a/components/fpspreadsheet/source/common/fpsutils.pas b/components/fpspreadsheet/source/common/fpsutils.pas index 5d4a10251..4d6ef0674 100644 --- a/components/fpspreadsheet/source/common/fpsutils.pas +++ b/components/fpspreadsheet/source/common/fpsutils.pas @@ -715,6 +715,20 @@ begin if rfRelCol in f then Include(AFlags, rfRelCol2); end; +{@@ ---------------------------------------------------------------------------- + Extracts a cell's row and column index from a string in "R1C1" notation. + Returns in AFlags also information on relative/absolute cells. + + @param AStr Cell string, in R1C1 syntax, such as R[2]C[3] or R1C5 + @param ABaseRow Row index from which the cell reference is seen. + @param ABaseCol Column index from which the cell reference is seen. + @param ASheet Name of the worksheet which contains the cell (output) + @param ACellRow Row index of cell (output) + @param ACellCol Column index of cell (output) + @param AFlags A set containing an element for AFirstCellRow, AFirstCellCol, ALastCellRow, ALastCellCol if they represent a relative cell address. (output) + + @returns @FALSE if the string is not a valid cell reference +-------------------------------------------------------------------------------} function ParseCellString_R1C1(const AStr: String; ABaseRow, ABaseCol: Cardinal; out ASheet: String; out ACellRow, ACellCol: Cardinal; out AFlags: TsRelFlags): Boolean; @@ -733,15 +747,15 @@ end; {@@ ---------------------------------------------------------------------------- Parses a cell string in "R1C1" notation into zero-based column and row numbers - 'AFlags' indicates relative addresses. + AFlags indicates relative addresses. @param AStr Cell reference in R1C1 syntax, such as R[2]C[3] or R1C5 - @param ABaseRow Row index from which the cell reference is seen. - @param ABaseCol Column index from which the cell reference is seen. - @param ACellRow Row index of the top/left cell of the range (output) - @param ACellCol Column index of the top/left cell of the range (output) - @param AFlags A set containing an element for ACellRow and/or ACellCol, if they represent a relative cell address. - @returns @FALSE if the string is not a valid cell range + @param ABaseRow Zero-based row index from which the cell reference is seen. + @param ABaseCol Zero-based column index from which the cell reference is seen. + @param ACellRow Zero-based row index of the cell (output) + @param ACellCol Zero-based column index of cell (output) + @param AFlags A set containing rfRelRow and/or rfRelCol if the row and/or column index is relative to the base cell (output). + @returns @FALSE if the string is not a valid cell address -------------------------------------------------------------------------------} function ParseCellString_R1C1(const AStr: String; ABaseRow, ABaseCol: Cardinal; out ACellRow, ACellCol: Cardinal; out AFlags: TsRelFlags): Boolean; @@ -833,8 +847,9 @@ end; @param AStr Cell reference in R1C1 syntax, such as R[2]C[3] or R1C5 @param ABaseRow Row index from which the cell reference is seen. @param ABaseCol Column index from which the cell reference is seen. - @param ACellRow Row index of the top/left cell of the range (output) - @param ACellCol Column index of the top/left cell of the range (output) + @param ACellRow Row index of cell (output) + @param ACellCol Column index of the cell (output) + @returns @FALSE if the string is not a valid cell address -------------------------------------------------------------------------------} function ParseCellString_R1C1(const AStr: string; ABaseRow, ABaseCol: Cardinal; out ACellRow, ACellCol: Cardinal): Boolean; @@ -847,8 +862,21 @@ end; {@@ ---------------------------------------------------------------------------- Parses a 3D cell and sheet range string in Excel R1C1 dialect. Returns the - names of the limiting sheets and the indexes of the limiting borders. + names of the limiting sheets and the indexes of the limiting row/col borders. The function result is @false if the provided string is not valid. + + @param AStr Cell range string, in R1C1 syntax, such as R[2]C[3]:R[4]C[8] + @param ABaseRow Row index from which the cell range is seen. + @param ABaseCol Column index from which the cell range is seen. + @param ASheet1 Name of the worksheet with the first cell of the 3D cell block (part before the colon) (output) + @param ASheet1 Name of the worksheet with the second cell of the 3D cell block (part after the colon) (output) + @param ARow1 Index of the left row of the 3D range (part before the colon)(output) + @param ACol1 Index of the top row of the 3D range (part before the colon) (output) + @param ARow2 Index of the right row of the 3D range (part after the colon) (output) + @param ACol2 Index of the bottom row of the 3D range (part after the colon) (output) + @param AFlags A set containing element rfRow1, rfCol1, rfRow2, rfCol2 if the corresponding row/column indexes are relative addresses (output) + + @returns @FALSE if the string is not a valid cell range -------------------------------------------------------------------------------} function ParseCellRangeString_R1C1(const AStr: String; ABaseRow, ABaseCol: Cardinal; out ASheet1, ASheet2: String; out ARow1, ACol1, ARow2, ACol2: Cardinal; @@ -894,7 +922,7 @@ end; @param AStr Cell range string, such as A1 @param ACellRow Row index of the top/left cell of the range (output) @param ACellCol Column index of the top/left cell of the range (output) - @returns @False if the string is not a valid cell range + @returns @False if the string is not a valid cell reference -------------------------------------------------------------------------------} function ParseCellString(const AStr: string; out ACellRow, ACellCol: Cardinal): Boolean; @@ -904,6 +932,20 @@ begin Result := ParseCellString(AStr, ACellRow, ACellCol, flags); end; +{@@ ---------------------------------------------------------------------------- + Parses a full cell string, like 'Sheet1!A1' into zero-based column and row numbers + Note that there can be several letters to address for more than 26 columns. + + For compatibility with old version which does not return flags for relative + cell addresses. + + @param AStr Cell range string, such as A1 + @param ASheetName Name of the worksheet which contains the cell (output)= + @param ACellRow Row index of the cell (output) + @param ACellCol Column index of the cell (output) + @param ASheetSeparator Character which separates the worksheet name from the cell reference string. By default this is '!' as used by Excel. + @returns @False if the string is not a valid cell reference +-------------------------------------------------------------------------------} function ParseSheetCellString(const AStr: String; out ASheetName: String; out ACellRow, ACellCol: Cardinal; ASheetSeparator: Char = '!'): Boolean; var @@ -916,7 +958,6 @@ begin end else begin ASheetName := UTF8Copy(AStr, 1, p-1); Result := ParseCellString(Copy(AStr, p+1, Length(AStr)), ACellRow, ACellCol); -// Result := ParseCellString(UTF8Copy(AStr, p+1, UTF8Length(AStr)), ACellRow, ACellCol); end; end; @@ -924,7 +965,7 @@ end; Parses a cell row string to a zero-based row number. @param AStr Cell row string, such as '1', 1-based! - @param ARow Index of the row (zero-based!) (putput) + @param ARow Index of the row (zero-based!) (output) @returns @False if the string is not a valid cell row string -------------------------------------------------------------------------------} function ParseCellRowString(const AStr: string; out ARow: Cardinal): Boolean; @@ -956,7 +997,8 @@ begin exit; if AStr[1] = '$' then - j1 := 2 else + j1 := 2 + else j1 := 1; for j := j1 to Length(AStr) do @@ -972,23 +1014,6 @@ begin dec(ACol); Result := true; - - { - if Length(AStr) = 1 then AResult := Ord(AStr[1]) - Ord('A') - else if Length(AStr) = 2 then - begin - AResult := (Ord(AStr[1]) - Ord('A') + 1) * INT_NUM_LETTERS - + Ord(AStr[2]) - Ord('A'); - end - else if Length(AStr) = 3 then - begin - AResult := (Ord(AStr[1]) - Ord('A') + 1) * INT_NUM_LETTERS * INT_NUM_LETTERS - + (Ord(AStr[2]) - Ord('A') + 1) * INT_NUM_LETTERS - + Ord(AStr[3]) - Ord('A'); - end - else Exit(False); - - Result := True; } end; function Letter(AValue: Integer): char; @@ -1204,8 +1229,6 @@ begin Result := Format('%s:%s!%s', [ASheet1, ASheet2, s]); end; - - {@@ ---------------------------------------------------------------------------- Calculates a cell range address string from zero-based column and row indexes and the relative address state flags. @@ -1234,6 +1257,14 @@ begin ]); end; +{@@ ---------------------------------------------------------------------------- + Determines whether a worksheet name must to be quoted. This is needed when + the name begins with a numeral or a period, or when the name contains a space + character. + + @param ASheet Name of the worksheet to be analyzed + @returns @TRUE when the sheet name must be quoted, @FALSE otherwise +-------------------------------------------------------------------------------} function SheetNameNeedsQuotes(ASheet: String): Boolean; begin if ASheet <> '' then begin