Skip to content

Latest commit

 

History

History
183 lines (136 loc) · 5.28 KB

README.md

File metadata and controls

183 lines (136 loc) · 5.28 KB

DelphiSafeArrayHelper

Uma biblioteca Delphi/FreePascal que fornece um wrapper amigável e type-safe para trabalhar com SafeArrays COM, especialmente útil para interoperabilidade COM/.NET.

🎯 Motivação

Trabalhar com SafeArrays em Delphi pode ser complexo e propenso a erros. Esta biblioteca simplifica o uso de SafeArrays através de uma interface intuitiva com gerenciamento automático de memória.

✨ Características

  • Interface-based: Gerenciamento automático de memória através de reference counting
  • API Intuitiva: Acesso aos elementos como arrays nativos do Delphi
  • Type-safe: Validação de índices e tipos em tempo de execução
  • Conversões Fáceis: Métodos para converter entre SafeArray e arrays nativos
  • Suporte Multidimensional: Trabalhe com arrays de múltiplas dimensões
  • Documentação Completa: XMLDoc em todo o código
  • Bem Testado: Suite completa de testes com DUnitX

📋 Requisitos

  • Delphi 2010 ou superior
  • FreePascal 3.0 ou superior (modo Delphi)
  • Windows (usa Windows API para SafeArray)

🚀 Instalação

  1. Clone o repositório:
git clone https://github.com/mmfbr/DelphiSafeArrayHelper.git

  1. Adicione o caminho da pasta src ao Library Path do seu projeto

  2. Adicione SafeArrayWrapper à cláusula uses:

uses
  SafeArrayWrapper;

📖 Uso Básico

Criando um SafeArray

var
  SafeArr: ISafeArrayWrapper;
begin
  // Array de inteiros com 10 elementos (índices 0..9)
  SafeArr := CreateSafeArray(varInteger, 10);
  
  // Array com bounds customizados [5..15]
  SafeArr := TSafeArrayWrapper.Create(varInteger, 5, 15);
  
  // Array multidimensional 3x4
  SafeArr := CreateSafeArray(varVariant, [0, 2, 0, 3]);
end;

Acessando Elementos

// Array unidimensional
SafeArr[0] := 100;
Value := SafeArr[0];

// Array multidimensional
SafeArr[[1, 2]] := 'Hello';
Value := SafeArr[[1, 2]];

Conversões

// De Variant para SafeArray wrapper
var
  VarArr: Variant;
  SafeArr: ISafeArrayWrapper;
begin
  VarArr := VarArrayCreate([0, 4], varDouble);
  SafeArr := VariantToSafeArray(VarArr);
end;

// De SafeArray wrapper para arrays nativos
var
  IntArray: TArray<Integer>;
  StrArray: TArray<string>;
begin
  IntArray := SafeArr.ToIntegerArray;
  StrArray := SafeArr.ToStringArray;
end;

Interoperabilidade COM/.NET

uses
  mscorlib_TLB,
  SafeArrayWrapper;

var
  DotNetArray: OleVariant;
  SafeArr: ISafeArrayWrapper;
  Args: OleVariant;
begin
  // Preparar argumentos para método .NET
  SafeArr := CreateSafeArray(varVariant, 2);
  SafeArr[0] := 'Hello';
  SafeArr[1] := 'World';
  
  // Converter para passar ao método
  Args := SafeArr.ToVariantArray;
  DotNetObject.MethodThatExpectsArray(Args);
  
  // Receber array de método .NET
  DotNetArray := DotNetObject.GetNames();
  SafeArr := VariantToSafeArray(DotNetArray);
  
  // Processar elementos
  for I := 0 to SafeArr.Count - 1 do
    ProcessName(SafeArr[I]);
end;

🧪 Executando os Testes

O projeto inclui uma suite completa de testes usando DUnitX:

  1. Abra tests/SafeArrayWrapperTests.dproj no Delphi
  2. Compile e execute o projeto
  3. Verifique os resultados no console ou GUI do DUnitX

📚 Documentação da API

Interface ISafeArrayWrapper

Propriedades

  • Count: Integer - Número total de elementos
  • Dimensions: Integer - Número de dimensões
  • Items[Index]: Variant - Acesso indexado (propriedade default)
  • VarType: TVarType - Tipo dos elementos
  • SafeArray: PSafeArray - Ponteiro para o SafeArray nativo

Métodos

  • GetLBound(Dimension: Integer = 1): Integer - Limite inferior
  • GetUBound(Dimension: Integer = 1): Integer - Limite superior
  • Clear - Limpa todos os elementos
  • Resize(NewSize: Integer) - Redimensiona o array
  • Append(Value: Variant) - Adiciona elemento ao final
  • ToVariantArray: Variant - Converte para Variant array
  • ToStringArray: TArray<string> - Converte para array de strings
  • ToIntegerArray: TArray<Integer> - Converte para array de inteiros
  • ToDoubleArray: TArray<Double> - Converte para array de doubles

Funções Auxiliares

  • CreateSafeArray(VarType: TVarType; Count: Integer): ISafeArrayWrapper
  • WrapSafeArray(SafeArray: PSafeArray; OwnsData: Boolean = False): ISafeArrayWrapper
  • VariantToSafeArray(Variant: Variant): ISafeArrayWrapper

🤝 Contribuindo

Contribuições são bem-vindas! Por favor:

  1. Faça um Fork do projeto
  2. Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
  3. Commit suas mudanças (git commit -m 'Add some AmazingFeature')
  4. Push para a branch (git push origin feature/AmazingFeature)
  5. Abra um Pull Request

📄 Licença

Este projeto está licenciado sob a MIT License - veja o arquivo LICENSE para detalhes.

🙏 Agradecimentos

  • Comunidade Delphi por anos de conhecimento compartilhado sobre COM e SafeArrays
  • Contribuidores do projeto DUnitX por fornecer um excelente framework de testes

📞 Contato

Seu Nome - @mmfbr77

Link do Projeto: https://github.com/mmfbr/DelphiSafeArrayHelper