fpspreadsheet: Add chm help for unit fpsCurrency. Refine some help texts in fpsUtils.

git-svn-id: https://svn.code.sf.net/p/lazarus-ccr/svn@8152 8e941d3f-bd1b-0410-a28a-d453659cc2b4

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="C:\Program Files (x86)\HTML Help Workshop\hhc.exe"
-set chm_cmd=chmcmd.exe
+::set chm_cmd=chmcmd.exe
 %chm_cmd% output\fpspreadsheet.hhp
+copy /Y output\fpspreadsheet.chm ..\fpspreadsheet-api.chm
 

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

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;

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  ABaseRow  Zero-based row index from which the cell reference is seen.
-  @param  ABaseCol  Column index from which the cell reference is seen.
+  @param  ABaseCol  Zero-based column index from which the cell reference is seen.
-  @param  ACellRow  Row index of the top/left cell of the range (output)
+  @param  ACellRow  Zero-based row index of the cell (output)
-  @param  ACellCol  Column index of the top/left cell of the range (output)
+  @param  ACellCol  Zero-based column index of cell (output)
-  @param  AFlags    A set containing an element for ACellRow and/or ACellCol, if they represent a relative cell address.
+  @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 range
+  @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  ACellRow  Row index of cell (output)
-  @param  ACellCol  Column index of the top/left cell of the range (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