CodeSnip Old Code (SVN)

{
 * Web.UCharEncodings.pas
 *
 * Implements a class that defines and provides access to character sets and
 * encodings supported when accessing web services.
 *
 * $Rev$
 * $Date$
 *
 * ***** BEGIN LICENSE BLOCK *****
 *
 * Version: MPL 1.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with the
 * License. You may obtain a copy of the License at http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
 * the specific language governing rights and limitations under the License.
 *
 * The Original Code is Web.UCharEncodings.pas, formerly
 * NsWebServices.UCharEncodings.pas.
 *
 * The Initial Developer of the Original Code is Peter Johnson
 * (http://www.delphidabbler.com/).
 *
 * Portions created by the Initial Developer are Copyright (C) 2010 Peter
 * Johnson. All Rights Reserved.
 *
 * Contributor(s)
 *   NONE
 *
 * ***** END LICENSE BLOCK *****
}


unit Web.UCharEncodings;


interface


uses
  // Delphi
  SysUtils,
  // Project
  UBaseObjects;


type

  {
  EWebCharEncodings:
    Class of exception raised by TWebCharEncodings.
  }
  EWebCharEncodings = class(Exception);

  {
  TWebCharEncodings:
    Static class that defines and provides access to character sets and
    encodings supported when accessing web services.
  }
  TWebCharEncodings = class(TNoConstructObject)
  strict private
    type
      {
      TCharEncoding:
        Maps an encoding by name onto a representative code page.
      }
      TCharEncoding = record
      public
        Name: string; // Name of encoding, e.g. ISO-8859-1 or UTF-8
        Code: Word;   // Code page or id if encoding is not ANSI
        constructor Create(const AName: string; const ACode: Word);
          {Constructor. Initialises record's fields.
            @param AName [in] Value for Name field.
            @param ACode [in] Value for Code filed.
          }
      end;
    // Constants used to identify encodings that map to predefined encodings of
    // TEncoding. UTF16 code pages are not ANSI: we use BOM as id.
    const
      UTF8CodePage = 65001;     // UTF-8
      ASCIICodePage = 20127;    // ASCII
      UTF16LECodePage = $FFFE;  // UTF-16 Little endian
      UTF16BECodePage = $FEFF;  // UTF-16 Big endian
      ErrorCodePage = 0;        // Used when code page not recognised
    const DefaultEncoding = 'ISO-8859-1'; // encoding used when none specified
    class var fEncodings: array of TCharEncoding; // list of supported encodings
    class function IndexOf(const CharSet: string): Integer;
      {Looks up index of a character set in list of supported encodings.
        @param CharSet [in] String indentifying Character set to look up.
        @return Index of CharSet in list of encodings or -1 if not found.
      }
    class function CharCode(CharSet: string): Word;
      {Gets character code associated with a character set.
        @param CharSet [in] String indentifying Character set to look up. '' is
          interpreted as DefaultEncoding.
        @return Required character code or 0 if character set is not supported.
      }
  public
    class constructor Create;
      {Class constructor. Initialises array of supported encodings.
      }
    class function Supported(const CharSet: string): Boolean;
      {Checks if a character set is supported.
        @param CharSet [in] String specifying character set. '' is interpreted
          as DefaultEncoding.
        @return True if character set is supported, False if not.
      }
    class function GetEncoding(const CharSet: string): TEncoding;
      {Creates an encoding for a character set. Caller must free the encoding if
      it is not a default encoding.
        @param CharSet [in] String specifying character set. '' is interpreted
          as DefaultEncoding.
        @return Appropriate encoding instance.
        @except Raises EWebCharEncodings if CharSet is not supported.
      }
    class function AcceptCharSet: string;
      {Returns comma separated list of accepted character sets suitable for
      inclusion in http headers.
        @return Required list.
      }
  end;


implementation


{ TWebCharEncodings }

class function TWebCharEncodings.AcceptCharSet: string;
  {Returns comma separated list of accepted character sets suitable for
  inclusion in http headers.
    @return Required list.
  }
var
  Encoding: TCharEncoding;  // each encoding in list of supported encodings
begin
  Result := '';
  for Encoding in fEncodings do
  begin
    if Result <> '' then
      Result := Result + ', ';
    Result := Result + Encoding.Name;
  end;
end;

class function TWebCharEncodings.CharCode(CharSet: string): Word;
  {Gets character code associated with a character set.
    @param CharSet [in] String indentifying Character set to look up. '' is
      interpreted as DefaultEncoding.
    @return Required character code or 0 if character set is not supported.
  }
var
  Idx: Integer; // index of CharSet in list of supported encodings
begin
  if CharSet = '' then
    CharSet := DefaultEncoding;
  Idx := IndexOf(CharSet);
  if Idx >= 0 then
    Result := fEncodings[Idx].Code
  else
    Result := ErrorCodePage;
end;

class constructor TWebCharEncodings.Create;
  {Class constructor. Initialises array of supported encodings.
  }
begin
  SetLength(fEncodings, 6);
  fEncodings[0] := TCharEncoding.Create('UTF-8', UTF8CodePage);
  fEncodings[1] := TCharEncoding.Create('UTF-16LE', UTF16LECodePage);
  fEncodings[2] := TCharEncoding.Create('UTF-16BE', UTF16BECodePage);
  fEncodings[3] := TCharEncoding.Create('ISO-8859-1', 28591);  // latin 1
  fEncodings[4] := TCharEncoding.Create('Windows-1252', 1252);
  fEncodings[5] := TCharEncoding.Create('ASCII', ASCIICodePage);
  // NOTE: UTF-16 has been left out because some problems with PHP's
  // mb_convert_encoding() with UTF-16 have been found, so it's not safe to
  // accept this encoding
end;

class function TWebCharEncodings.GetEncoding(const CharSet: string): TEncoding;
  {Creates an encoding for a character set. Caller must free the encoding if it
  is not a default encoding.
    @param CharSet [in] String specifying character set. '' is interpreted
      as DefaultEncoding.
    @return Appropriate encoding instance.
    @except Raises EWebCharEncodings if CharSet is not supported.
  }
resourcestring
  // error message
  sErrorMsg = 'Unsupported Character Encoding: %s';
var
  Code: Word; // character code associated with CharSet
begin
  Code := CharCode(CharSet);
  case Code of
    ErrorCodePage: raise EWebCharEncodings.CreateFmt(sErrorMsg, [CharSet]);
    UTF8CodePage: Exit(TEncoding.UTF8);
    UTF16LECodePage: Exit(TEncoding.Unicode);
    UTF16BECodePage: Exit(TEncoding.BigEndianUnicode);
    ASCIICodePage: Exit(TEncoding.ASCII);
    else Exit(TMBCSEncoding.Create(Code));
  end;
end;

class function TWebCharEncodings.IndexOf(const CharSet: string): Integer;
  {Looks up index of a character set in list of supported encodings.
    @param CharSet [in] String indentifying Character set to look up.
S    @return Index of CharSet in list of encodings or -1 if not found.
  }
var
  Idx: Integer; // loops thru all encodings
begin
  for Idx := Low(fEncodings) to High(fEncodings) do
  begin
    if AnsiSameText(fEncodings[Idx].Name, CharSet) then
      Exit(Idx);
  end;
  Exit(-1);
end;

class function TWebCharEncodings.Supported(const CharSet: string): Boolean;
  {Checks if a character set is supported.
    @param CharSet [in] String specifying character set. '' is interpreted as
      DefaultEncoding.
    @return True if character set is supported, False if not.
  }
begin
  Result := CharCode(CharSet) = ErrorCodePage;
end;

{ TWebCharEncodings.TCharEncoding }

constructor TWebCharEncodings.TCharEncoding.Create(const AName: string;
  const ACode: Word);
  {Constructor. Initialises record's fields.
    @param AName [in] Value for Name field.
    @param ACode [in] Value for Code filed.
  }
begin
  Name := AName;
  Code := ACode;
end;

end.