//*****************************************************************************
//* Object Name: CFlagsExtracter
//*****************************************************************************
//* Copyright © GalaSoft Laurent Bugnion 2006
//*****************************************************************************
//* Project                 : GalaSoftLb.Utilities
//* Target                  : .NET Framework 2.0
//* Language/Compiler       : C#
//* Author                  : Laurent Bugnion (LBu), GalaSoft
//* Web                     : http://www.galasoft.ch
//* Contact info            : laurent@galasoft.ch
//* Created                 : 15.09.2006
//*****************************************************************************
//* Description:
//* See the class definition here under.
//* Last debug version: D0001.
//*
//*****************************************************************************
//* Revision History:
//* 15.09.2006 LBu : Created.
//*                  Released V1.0.
//*****************************************************************************

//*****************************************************************************
//* Imports *******************************************************************
//*****************************************************************************

#region Imports

using System;
using System.Collections.Generic;
using System.Text;

using GalaSoftLb.Utilities.Attributes;

#endregion

namespace GalaSoftLb.Utilities
{
  // Class definition *********************************************************
  /// <summary>
  /// Converts an integer value into the corresponding enumerated flags,
  /// returned in an array.
  /// </summary>
  /// <typeparam name="T">An Enumeration with the <see cref="FlagsAttribute"/> set.
  /// <para>The enumeration constants must be in powers of two, that is, 1, 2, 4, 8,
  /// and so on. This means the individual flags in combined enumeration constants do
  /// not overlap.</para></typeparam>
  [CClassInfo( typeof( CFlagsExtracter<> ),
    strVersion = "V01.00.00",
    strDate = "200609151520",
    strDescription = "Extracts flags from an integer value and gives the corresponding enum values back." )]
  public class CFlagsExtracter<T>
  {
    //*************************************************************************
    //* Enums *****************************************************************
    //*************************************************************************

    #region Enums
    #endregion

    //*************************************************************************
    //* Constants *************************************************************
    //*************************************************************************

    #region Constants
    #endregion

    //*************************************************************************
    //* Static attributes *****************************************************
    //*************************************************************************

    #region StaticAttributes
    #endregion

    //*************************************************************************
    //* Attributes ************************************************************
    //*************************************************************************

    #region Attributes

    /// <summary>
    /// Contains the enumerated flags corresponding to the integer value
    /// passed to the constructor.
    /// </summary>
    private List<T> m_leFlags = new List<T>();

    #endregion

    //*************************************************************************
    //* Properties ************************************************************
    //*************************************************************************

    #region Properties

    // ------------------------------------------------------------------------
    /// <summary>
    /// Contains the enumerated flags corresponding to the integer value
    /// passed to the constructor.
    /// </summary>
    public T[] aeFlags
    {
      get
      {
        return m_leFlags.ToArray();
      }
    }

    #endregion

    //*************************************************************************
    //* Static methods ********************************************************
    //*************************************************************************

    #region Static methods

    // ------------------------------------------------------------------------
    /// <summary>
    /// Converts an integer value into the corresponding enumerated flags,
    /// returned in an array.
    /// </summary>
    /// <param name="iFlags">An integer corresponding to the flags set. For example,
    /// binary 100101101 = decimal 301</param>
    /// <returns>An array of enumerated values of the type parameter T.</returns>
    public static T[] ExtractFlags( int iFlags )
    {
      return new CFlagsExtracter<T>( iFlags ).aeFlags;
    }

    #endregion

    //*************************************************************************
    //* Constructor & generated code ******************************************
    //*************************************************************************

    #region Constructors

    // ------------------------------------------------------------------------
    /// <summary>
    /// Creates a new instance of the extracter with its property
    /// <see cref="aeFlags" /> set accordingly to the parameter iFlags.
    /// </summary>
    /// <param name="iFlags">An integer corresponding to the flags set. For example,
    /// binary 100101101 = decimal 301</param>
    public CFlagsExtracter( int iFlags )
    {
      // Check if the "T" Enum is correctly qualified as "Flags"
      Type oEnumType = typeof( T );
      if ( oEnumType.GetCustomAttributes( typeof( FlagsAttribute ), false ).Length == 0 )
      {
        // RESX
        throw new ArgumentException( String.Format( "The type {0} is not an enum, or not a Flags enumeration", oEnumType.FullName ) );
      }

      // GetValues returns the values sorted by the binary value of the enum
      Array aValues = Enum.GetValues( typeof( T ) );
      T[] aeValues = (T[]) aValues;
      int[] aiValues = (int[]) aValues;

      for ( int index = 0; index < aiValues.Length; index++ )
      {
        if ( aiValues[ index ] > 0 )
        {
          int iTest = aiValues[ index ] & iFlags;
          if ( iTest == aiValues[ index ] )
          {
            m_leFlags.Add( aeValues[ index ] );
          }
        }
      }
    }
    
    #endregion

    //*************************************************************************
    //* Event handlers ********************************************************
    //*************************************************************************

    #region Event handlers
    #endregion

    //*************************************************************************
    //* Methods ***************************************************************
    //*************************************************************************

    #region Methods
    #endregion

    //*************************************************************************
    //* Operators *************************************************************
    //*************************************************************************

    #region Operators
    #endregion
  }
}