vb6runtime 0.2.0

//! # `LoadResData` Function
//!
//! Returns the data stored in a resource (.res) file.
//!
//! ## Syntax
//!
//! ```vb
//! LoadResData(index, format)
//! ```
//!
//! ## Parameters
//!
//! - `index` (Required): `Integer` or `String` identifying the resource
//!   - Can be a numeric ID or string name
//!   - Must match the ID/name used when the resource was compiled
//! - `format` (Required): `Integer` specifying the format of the resource data
//!   - Custom user-defined format number (1-32767)
//!   - Cannot use predefined formats (use `LoadResPicture`/`LoadResString` instead)
//!
//! ## Return Value
//!
//! Returns a Byte array (Variant containing Byte array):
//! - Contains the raw binary data from the resource file
//! - Array is zero-based
//! - Returns Empty if resource not found (in some VB versions)
//! - Raises error 326 if resource not found
//! - Data is returned exactly as stored in .res file
//!
//! ## Remarks
//!
//! The `LoadResData` function loads custom binary data from resources:
//!
//! - Loads custom data from compiled resource (.res) files
//! - Resource file must be linked to project at compile time
//! - Returns data as Byte array (`Variant`/`Byte()`)
//! - Used for custom binary resources (not bitmaps/icons/strings)
//! - For images, use `LoadResPicture` instead
//! - For strings, use `LoadResString` instead
//! - Resource files created with Resource Editor or RC.EXE
//! - Index can be numeric ID or string name
//! - Format must be custom type (not 1=Cursor, 2=Bitmap, 3=Icon, etc.)
//! - Useful for embedding files (sounds, data, etc.)
//! - Data embedded in compiled EXE (no external files needed)
//! - More secure than external files (can't be easily modified)
//! - Faster access than loading from disk
//! - Resource file added via Project > Add File or in .vbp
//! - Only one resource file per project
//! - Changes to .res file require recompile
//! - Error 326: "Resource with identifier not found" if ID/format don't match
//! - Error 48: "Error loading from file" if resource file corrupt
//!
//! ## Typical Uses
//!
//! 1. **Load Binary Data**
//!    ```vb
//!    Dim data() As Byte
//!    data = LoadResData(101, 256) ' Custom format 256
//!    ```
//!
//! 2. **Load Sound File**
//!    ```vb
//!    Dim wavData() As Byte
//!    wavData = LoadResData("STARTUP_SOUND", 257)
//!    ```
//!
//! 3. **Load Configuration Data**
//!    ```vb
//!    Dim configData() As Byte
//!    configData = LoadResData("CONFIG", 300)
//!    ```
//!
//! 4. **Load Binary Template**
//!    ```vb
//!    Dim template() As Byte
//!    template = LoadResData(1001, 400)
//!    ```
//!
//! 5. **Load Custom File Type**
//!    ```vb
//!    Dim xmlData() As Byte
//!    xmlData = LoadResData("SCHEMA", 500)
//!    ```
//!
//! 6. **Load Multiple Resources**
//!    ```vb
//!    For i = 1 To 5
//!        data = LoadResData(i, 256)
//!        ProcessData data
//!    Next i
//!    ```
//!
//! 7. **Load Named Resource**
//!    ```vb
//!    Dim helpData() As Byte
//!    helpData = LoadResData("HELP_FILE", 600)
//!    ```
//!
//! 8. **Conditional Loading**
//!    ```vb
//!    If useCustomTheme Then
//!        themeData = LoadResData("DARK_THEME", 700)
//!    End If
//!    ```
//!
//! ## Basic Examples
//!
//! ### Example 1: Loading and Using Binary Data
//! ```vb
//! ' Load binary data from resource
//! Dim resourceData() As Byte
//! resourceData = LoadResData(101, 256)
//!
//! ' Use the data
//! Dim fileNum As Integer
//! fileNum = FreeFile
//! Open "C:\output.dat" For Binary As #fileNum
//! Put #fileNum, , resourceData
//! Close #fileNum
//! ```
//!
//! ### Example 2: Loading Sound Data
//! ```vb
//! ' Load WAV file from resources
//! Dim wavData() As Byte
//! wavData = LoadResData("BEEP", 257)
//!
//! ' Play using Windows API
//! Call sndPlaySound(wavData(0), SND_ASYNC Or SND_MEMORY)
//! ```
//!
//! ### Example 3: Error Handling
//! ```vb
//! On Error Resume Next
//! Dim data() As Byte
//! data = LoadResData(999, 256)
//! If Err.Number = 326 Then
//!     MsgBox "Resource not found!", vbCritical
//!     Err.Clear
//! ElseIf Err.Number <> 0 Then
//!     MsgBox "Error loading resource: " & Err.Description, vbCritical
//!     Err.Clear
//! End If
//! ```
//!
//! ### Example 4: Converting to String
//! ```vb
//! ' Load text data stored as binary
//! Dim textData() As Byte
//! textData = LoadResData("README", 300)
//!
//! ' Convert byte array to string
//! Dim content As String
//! content = StrConv(textData, vbUnicode)
//! MsgBox content
//! ```
//!
//! ## Common Patterns
//!
//! ### Pattern 1: `SafeLoadResData`
//! ```vb
//! Function SafeLoadResData(ByVal resID As Variant, _
//!                          ByVal resFormat As Integer, _
//!                          ByRef outData() As Byte) As Boolean
//!     On Error Resume Next
//!     outData = LoadResData(resID, resFormat)
//!     SafeLoadResData = (Err.Number = 0)
//!     Err.Clear
//! End Function
//! ```
//!
//! ### Pattern 2: `LoadResDataToFile`
//! ```vb
//! Sub LoadResDataToFile(ByVal resID As Variant, _
//!                       ByVal resFormat As Integer, _
//!                       ByVal filename As String)
//!     Dim data() As Byte
//!     Dim fileNum As Integer
//!     
//!     data = LoadResData(resID, resFormat)
//!     
//!     fileNum = FreeFile
//!     Open filename For Binary As #fileNum
//!     Put #fileNum, , data
//!     Close #fileNum
//! End Sub
//! ```
//!
//! ### Pattern 3: `GetResDataSize`
//! ```vb
//! Function GetResDataSize(ByVal resID As Variant, _
//!                         ByVal resFormat As Integer) As Long
//!     On Error Resume Next
//!     Dim data() As Byte
//!     data = LoadResData(resID, resFormat)
//!     
//!     If Err.Number = 0 Then
//!         GetResDataSize = UBound(data) + 1
//!     Else
//!         GetResDataSize = 0
//!     End If
//! End Function
//! ```
//!
//! ### Pattern 4: `LoadResDataAsString`
//! ```vb
//! Function LoadResDataAsString(ByVal resID As Variant, _
//!                              ByVal resFormat As Integer) As String
//!     Dim data() As Byte
//!     data = LoadResData(resID, resFormat)
//!     LoadResDataAsString = StrConv(data, vbUnicode)
//! End Function
//! ```
//!
//! ### Pattern 5: `ResDataExists`
//! ```vb
//! Function ResDataExists(ByVal resID As Variant, _
//!                        ByVal resFormat As Integer) As Boolean
//!     On Error Resume Next
//!     Dim data() As Byte
//!     data = LoadResData(resID, resFormat)
//!     ResDataExists = (Err.Number = 0)
//!     Err.Clear
//! End Function
//! ```
//!
//! ### Pattern 6: `LoadMultipleResources`
//! ```vb
//! Function LoadMultipleResources(startID As Integer, _
//!                                endID As Integer, _
//!                                resFormat As Integer) As Collection
//!     Dim col As New Collection
//!     Dim i As Integer
//!     Dim data() As Byte
//!     
//!     On Error Resume Next
//!     For i = startID To endID
//!         data = LoadResData(i, resFormat)
//!         If Err.Number = 0 Then
//!             col.Add data
//!         End If
//!         Err.Clear
//!     Next i
//!     
//!     Set LoadMultipleResources = col
//! End Function
//! ```
//!
//! ### Pattern 7: `CompareResData`
//! ```vb
//! Function CompareResData(ByVal resID1 As Variant, _
//!                         ByVal resID2 As Variant, _
//!                         ByVal resFormat As Integer) As Boolean
//!     Dim data1() As Byte, data2() As Byte
//!     Dim i As Long
//!     
//!     data1 = LoadResData(resID1, resFormat)
//!     data2 = LoadResData(resID2, resFormat)
//!     
//!     If UBound(data1) <> UBound(data2) Then
//!         CompareResData = False
//!         Exit Function
//!     End If
//!     
//!     For i = 0 To UBound(data1)
//!         If data1(i) <> data2(i) Then
//!             CompareResData = False
//!             Exit Function
//!         End If
//!     Next i
//!     
//!     CompareResData = True
//! End Function
//! ```
//!
//! ### Pattern 8: `CopyResDataToArray`
//! ```vb
//! Sub CopyResDataToArray(ByVal resID As Variant, _
//!                        ByVal resFormat As Integer, _
//!                        ByRef targetArray() As Byte)
//!     Dim source() As Byte
//!     Dim i As Long
//!     
//!     source = LoadResData(resID, resFormat)
//!     ReDim targetArray(LBound(source) To UBound(source))
//!     
//!     For i = LBound(source) To UBound(source)
//!         targetArray(i) = source(i)
//!     Next i
//! End Sub
//! ```
//!
//! ### Pattern 9: `LoadResDataWithFallback`
//! ```vb
//! Function LoadResDataWithFallback(ByVal primaryID As Variant, _
//!                                  ByVal fallbackID As Variant, _
//!                                  ByVal resFormat As Integer) As Byte()
//!     On Error Resume Next
//!     
//!     LoadResDataWithFallback = LoadResData(primaryID, resFormat)
//!     If Err.Number <> 0 Then
//!         Err.Clear
//!         LoadResDataWithFallback = LoadResData(fallbackID, resFormat)
//!     End If
//! End Function
//! ```
//!
//! ### Pattern 10: `CachedResDataLoader`
//! ```vb
//! Dim resCache As New Collection
//!
//! Function LoadResDataCached(ByVal resID As Variant, _
//!                            ByVal resFormat As Integer) As Byte()
//!     Dim key As String
//!     On Error Resume Next
//!     
//!     key = CStr(resID) & "_" & CStr(resFormat)
//!     
//!     ' Try cache first
//!     LoadResDataCached = resCache(key)
//!     If Err.Number <> 0 Then
//!         ' Not in cache, load and cache it
//!         Err.Clear
//!         LoadResDataCached = LoadResData(resID, resFormat)
//!         resCache.Add LoadResDataCached, key
//!     End If
//! End Function
//! ```
//!
//! ## Advanced Examples
//!
//! ### Example 1: Resource Manager Class
//! ```vb
//! ' Class: ResourceManager
//! Private m_cache As Collection
//!
//! Private Sub Class_Initialize()
//!     Set m_cache = New Collection
//! End Sub
//!
//! Public Function LoadData(ByVal resID As Variant, _
//!                          ByVal resFormat As Integer) As Byte()
//!     Dim key As String
//!     On Error Resume Next
//!     
//!     key = CStr(resID) & "_" & CStr(resFormat)
//!     LoadData = m_cache(key)
//!     
//!     If Err.Number <> 0 Then
//!         Err.Clear
//!         LoadData = LoadResData(resID, resFormat)
//!         If Err.Number = 0 Then
//!             m_cache.Add LoadData, key
//!         Else
//!             Err.Raise vbObjectError + 1000, "ResourceManager", _
//!                       "Failed to load resource"
//!         End If
//!     End If
//! End Function
//!
//! Public Function GetAsString(ByVal resID As Variant, _
//!                             ByVal resFormat As Integer) As String
//!     Dim data() As Byte
//!     data = LoadData(resID, resFormat)
//!     GetAsString = StrConv(data, vbUnicode)
//! End Function
//!
//! Public Sub SaveToFile(ByVal resID As Variant, _
//!                       ByVal resFormat As Integer, _
//!                       ByVal filename As String)
//!     Dim data() As Byte
//!     Dim fileNum As Integer
//!     
//!     data = LoadData(resID, resFormat)
//!     fileNum = FreeFile
//!     Open filename For Binary As #fileNum
//!     Put #fileNum, , data
//!     Close #fileNum
//! End Sub
//!
//! Public Sub ClearCache()
//!     Set m_cache = New Collection
//! End Sub
//!
//! Private Sub Class_Terminate()
//!     Set m_cache = Nothing
//! End Sub
//! ```
//!
//! ### Example 2: Sound Player with Resources
//! ```vb
//! ' Module with API declarations
//! Private Declare Function sndPlaySound Lib "winmm.dll" Alias "sndPlaySoundA" ( _
//!     lpszSoundName As Any, ByVal uFlags As Long) As Long
//!
//! Private Const SND_ASYNC = &H1
//! Private Const SND_MEMORY = &H4
//!
//! ' Sound resource IDs
//! Private Const RES_SOUND_BEEP = 101
//! Private Const RES_SOUND_CLICK = 102
//! Private Const RES_SOUND_ERROR = 103
//! Private Const RES_FORMAT_WAVE = 257
//!
//! Public Sub PlayResourceSound(ByVal soundID As Integer)
//!     Dim soundData() As Byte
//!     On Error Resume Next
//!     
//!     soundData = LoadResData(soundID, RES_FORMAT_WAVE)
//!     If Err.Number = 0 Then
//!         Call sndPlaySound(soundData(0), SND_ASYNC Or SND_MEMORY)
//!     Else
//!         Debug.Print "Sound not found: " & soundID
//!     End If
//! End Sub
//!
//! Public Sub PlayBeep()
//!     PlayResourceSound RES_SOUND_BEEP
//! End Sub
//!
//! Public Sub PlayClick()
//!     PlayResourceSound RES_SOUND_CLICK
//! End Sub
//!
//! Public Sub PlayError()
//!     PlayResourceSound RES_SOUND_ERROR
//! End Sub
//! ```
//!
//! ### Example 3: Configuration Manager
//! ```vb
//! ' Class: ConfigManager
//! Private m_config As String
//!
//! Public Sub LoadConfig()
//!     Dim configData() As Byte
//!     On Error Resume Next
//!     
//!     ' Try to load from resource
//!     configData = LoadResData("CONFIG", 300)
//!     If Err.Number = 0 Then
//!         m_config = StrConv(configData, vbUnicode)
//!     Else
//!         ' Use default config
//!         m_config = GetDefaultConfig()
//!     End If
//!     Err.Clear
//! End Sub
//!
//! Public Function GetSetting(ByVal key As String) As String
//!     Dim lines() As String
//!     Dim i As Long
//!     Dim pos As Long
//!     
//!     lines = Split(m_config, vbCrLf)
//!     For i = 0 To UBound(lines)
//!         If Left(lines(i), Len(key) + 1) = key & "=" Then
//!             GetSetting = Mid(lines(i), Len(key) + 2)
//!             Exit Function
//!         End If
//!     Next i
//! End Function
//!
//! Private Function GetDefaultConfig() As String
//!     GetDefaultConfig = "Version=1.0" & vbCrLf & _
//!                       "Language=English" & vbCrLf & _
//!                       "Theme=Default"
//! End Function
//! ```
//!
//! ### Example 4: Template Engine
//! ```vb
//! ' Class: TemplateEngine
//! Private Const RES_FORMAT_TEMPLATE = 400
//!
//! Public Function ProcessTemplate(ByVal templateID As Variant, _
//!                                  ParamArray values()) As String
//!     Dim template As String
//!     Dim data() As Byte
//!     Dim i As Long
//!     Dim result As String
//!     
//!     ' Load template from resources
//!     data = LoadResData(templateID, RES_FORMAT_TEMPLATE)
//!     template = StrConv(data, vbUnicode)
//!     
//!     result = template
//!     
//!     ' Replace placeholders with values
//!     For i = LBound(values) To UBound(values)
//!         result = Replace(result, "{" & i & "}", CStr(values(i)))
//!     Next i
//!     
//!     ProcessTemplate = result
//! End Function
//!
//! Public Function LoadTemplate(ByVal templateID As Variant) As String
//!     Dim data() As Byte
//!     data = LoadResData(templateID, RES_FORMAT_TEMPLATE)
//!     LoadTemplate = StrConv(data, vbUnicode)
//! End Function
//!
//! Public Function HasTemplate(ByVal templateID As Variant) As Boolean
//!     On Error Resume Next
//!     Dim data() As Byte
//!     data = LoadResData(templateID, RES_FORMAT_TEMPLATE)
//!     HasTemplate = (Err.Number = 0)
//!     Err.Clear
//! End Function
//! ```
//!
//! ## Error Handling
//!
//! ```vb
//! ' Error 326: Resource with identifier not found
//! On Error Resume Next
//! data = LoadResData(999, 256)
//! If Err.Number = 326 Then
//!     MsgBox "Resource ID 999 not found!"
//! End If
//!
//! ' Error 48: Error loading from file
//! data = LoadResData(101, 256)
//! If Err.Number = 48 Then
//!     MsgBox "Resource file is corrupt or missing!"
//! End If
//!
//! ' Safe loading with error handling
//! Function TryLoadResData(ByVal resID As Variant, _
//!                         ByVal resFormat As Integer, _
//!                         ByRef outData() As Byte) As Boolean
//!     On Error Resume Next
//!     outData = LoadResData(resID, resFormat)
//!     TryLoadResData = (Err.Number = 0)
//!     If Err.Number <> 0 Then
//!         Debug.Print "Error loading resource: " & Err.Description
//!     End If
//!     Err.Clear
//! End Function
//! ```
//!
//! ## Performance Considerations
//!
//! - **Fast Access**: Resources are embedded in EXE (very fast loading)
//! - **Memory Overhead**: Data loaded into memory when accessed
//! - **No Caching**: Each call loads fresh copy (implement caching if needed)
//! - **Compile Time**: Large resources increase EXE size and compile time
//! - **One Resource File**: Only one .res file per project (combine all resources)
//! - **Array Copy**: Returns copy of data (not reference)
//!
//! ## Best Practices
//!
//! 1. **Always handle errors** - resource might not exist
//! 2. **Use constants** for resource IDs and formats
//! 3. **Cache frequently used data** to avoid repeated loading
//! 4. **Use meaningful names** for string-based resource IDs
//! 5. **Document resource IDs** in code or separate file
//! 6. **Keep resources organized** by format number
//! 7. **Test resource loading** during development
//! 8. **Validate data size** after loading if needed
//! 9. **Consider memory usage** for large resources
//! 10. **Use appropriate formats** - `LoadResPicture` for images, `LoadResString` for text
//!
//! ## Comparison with Related Functions
//!
//! | Function | Purpose | Return Type | Data Type |
//! |----------|---------|-------------|-----------|
//! | **`LoadResData`** | Load custom binary data | Byte array | Any binary data |
//! | **`LoadResPicture`** | Load image from resources | `StdPicture` | BMP, ICO, CUR |
//! | **`LoadResString`** | Load string from resources | String | Text strings |
//! | **`LoadPicture`** | Load image from file | `StdPicture` | External file |
//!
//! ## `LoadResData` vs `LoadResPicture` vs `LoadResString`
//!
//! ```vb
//! ' LoadResData - custom binary data
//! Dim binData() As Byte
//! binData = LoadResData(101, 256)
//!
//! ' LoadResPicture - images
//! Picture1.Picture = LoadResPicture(101, vbResBitmap)
//!
//! ' LoadResString - strings
//! Dim msg As String
//! msg = LoadResString(101)
//! ```
//!
//! **When to use each:**
//! - **`LoadResData`**: Custom binary files, sound files, configuration data
//! - **`LoadResPicture`**: Images (bitmaps, icons, cursors)
//! - **`LoadResString`**: Localized text strings
//!
//! ## Platform Notes
//!
//! - Available in VB6 (not in early VB versions)
//! - Requires resource file (.res) linked to project
//! - Resource file created with Resource Editor or RC.EXE
//! - Only one resource file per project
//! - Resources embedded in compiled EXE/DLL
//! - Returns Variant containing Byte array
//! - Array is always zero-based (0 to n-1)
//! - Custom formats: 1-32767 (avoid predefined formats)
//! - Maximum resource size limited by available memory
//!
//! ## Limitations
//!
//! - **One resource file**: Only one .res file per project
//! - **Compile time**: Must recompile to update resources
//! - **No modification**: Cannot modify resources at runtime
//! - **Limited tools**: VB6 Resource Editor is basic
//! - **Format restrictions**: Cannot use predefined formats (1-16)
//! - **No compression**: Resources stored uncompressed in EXE
//! - **No encryption**: Resources easily extractable from EXE
//! - **Memory copy**: Always returns copy of data (not reference)
//! - **Error messages**: Limited error information
//! - **No streaming**: Entire resource loaded into memory
//!
//! ## Related Functions
//!
//! - `LoadResPicture`: Load picture from resource file
//! - `LoadResString`: Load string from resource file
//! - `LoadPicture`: Load picture from external file
//! - `StrConv`: Convert byte array to string
//! - `FreeFile`: Get file number for saving resource data

use super::resfile::{rt, ResId};
use super::{index_to_res_id, resource_not_found};
use crate::array::ArrayValue;
use crate::error::VBResult;
use crate::state::resources;
use crate::value::VBVariant;
use crate::VBType;

/// Highest custom resource format `LoadResData` accepts.
///
/// VB6 documents custom formats as 1-32767. Values at or below
/// [`MAX_PREDEFINED_FORMAT`] are the predefined Win32 `RT_*` types, which
/// `LoadResData` is documented not to load.
const MAX_CUSTOM_FORMAT: i32 = 32767;

/// Highest predefined Win32 resource type ordinal.
///
/// `RT_*` ordinals run up to `RT_MANIFEST` (24). VB6 tells programmers to use
/// `LoadResPicture`/`LoadResString` for those instead. `RT_RCDATA` (10) is the
/// exception: it is the type the VB6 Resource Editor writes custom data under,
/// and real programs do pass 10 to `LoadResData`.
const MAX_PREDEFINED_FORMAT: i32 = 24;

/// Implementation of the `LoadResData` function.
///
/// VB6 behavior:
/// - Reads custom binary data from the project's linked `.res` file
/// - `index` is a numeric resource ID or a string resource name
/// - `format` selects the resource type: a custom format (1-32767), most
///   commonly `RT_RCDATA` (10) as written by the VB6 Resource Editor
/// - Returns a zero-based `Byte` array holding the resource bytes verbatim
/// - Raises error 326 if the resource, or the resource file, is not found
///
/// Note that VB6 returns a *copy* of the data, so callers can mutate the
/// returned array without affecting later loads.
pub fn loadresdata(index: &VBVariant, format: &VBVariant) -> VBResult<VBVariant> {
    let res_id = index_to_res_id(index)?;

    // An unusable format cannot match any resource type.
    let format = format
        .as_i32()
        .ok()
        .filter(|value| (1..=MAX_CUSTOM_FORMAT).contains(value))
        .ok_or_else(resource_not_found)?;

    // Predefined types other than RT_RCDATA belong to LoadResPicture and
    // LoadResString. VB6 documents them as unsupported here.
    if format <= MAX_PREDEFINED_FORMAT && format != rt::RCDATA as i32 {
        return Err(resource_not_found());
    }

    let bytes = resources::with_file(|res| {
        let res_type = format as u16;
        let entry = match &res_id {
            ResId::Ordinal(ordinal) => res.find_by_ordinal(res_type, *ordinal),
            ResId::Name(name) => res.find_by_name(res_type, name),
        }
        .ok_or_else(resource_not_found)?;

        Ok(res.data(entry).to_vec())
    })?;

    Ok(bytes_to_variant(&bytes))
}

/// Wraps `bytes` in the zero-based `Byte` array VB6 returns.
fn bytes_to_variant(bytes: &[u8]) -> VBVariant {
    let elements = bytes.iter().map(|b| VBVariant::from_byte(*b)).collect();
    VBVariant::from_array(ArrayValue::from_vec_with_bounds(
        VBType::Byte,
        elements,
        // VB6 byte arrays from LoadResData are always zero-based.
        0,
    ))
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::error::err_number;
    use crate::library::resources::test_support::{
        named_record, null_record, record, with_linked_res,
    };

    #[test]
    fn loads_custom_data_by_ordinal() {
        let mut bytes = null_record();
        bytes.extend(record(rt::RCDATA, 101, b"custom-bytes"));

        with_linked_res(&bytes, || {
            let value = loadresdata(
                &VBVariant::from_integer(101),
                &VBVariant::from_integer(rt::RCDATA as i16),
            )
            .unwrap();

            let array = value.as_array().unwrap();
            assert_eq!(array.element_type(), &VBType::Byte);
            assert_eq!(array.lower_bound(0).unwrap(), 0);
            assert_eq!(array.upper_bound(0).unwrap(), 11);
            let actual: Vec<u8> = array
                .as_slice()
                .iter()
                .map(|v| v.as_byte().unwrap())
                .collect();
            assert_eq!(actual, b"custom-bytes");
        });
    }

    #[test]
    fn loads_custom_data_by_string_name() {
        let mut bytes = null_record();
        bytes.extend(named_record("300", "CONFIG", b"key=value"));

        with_linked_res(&bytes, || {
            let value = loadresdata(
                &VBVariant::from_string("CONFIG"),
                &VBVariant::from_long(300),
            )
            .unwrap();
            let array = value.as_array().unwrap();
            assert_eq!(array.len(), 9);
        });
    }

    #[test]
    fn zero_length_resource_yields_an_empty_array() {
        let mut bytes = null_record();
        bytes.extend(record(rt::RCDATA, 7, b""));

        with_linked_res(&bytes, || {
            let value = loadresdata(
                &VBVariant::from_integer(7),
                &VBVariant::from_integer(rt::RCDATA as i16),
            )
            .unwrap();
            let array = value.as_array().unwrap();
            assert!(array.is_empty());
            // An empty zero-based array has UBound one below LBound.
            assert_eq!(array.upper_bound(0).unwrap(), -1);
        });
    }

    #[test]
    fn missing_resource_raises_326() {
        let mut bytes = null_record();
        bytes.extend(record(rt::RCDATA, 101, b"data"));

        with_linked_res(&bytes, || {
            let error = loadresdata(
                &VBVariant::from_integer(999),
                &VBVariant::from_integer(rt::RCDATA as i16),
            )
            .unwrap_err();
            assert_eq!(error.number, err_number::RESOURCE_NOT_FOUND);
        });
    }

    #[test]
    fn wrong_format_does_not_match_the_resource() {
        let mut bytes = null_record();
        bytes.extend(record(rt::RCDATA, 101, b"data"));

        with_linked_res(&bytes, || {
            // Right ID, wrong custom format.
            let error =
                loadresdata(&VBVariant::from_integer(101), &VBVariant::from_long(500)).unwrap_err();
            assert_eq!(error.number, err_number::RESOURCE_NOT_FOUND);
        });
    }

    #[test]
    fn predefined_picture_and_string_formats_are_rejected() {
        let mut bytes = null_record();
        bytes.extend(record(rt::ICON, 1, b"icon"));
        bytes.extend(record(rt::STRING, 1, b"str"));

        with_linked_res(&bytes, || {
            for format in [rt::ICON, rt::BITMAP, rt::CURSOR, rt::STRING, rt::GROUP_ICON] {
                let error = loadresdata(
                    &VBVariant::from_integer(1),
                    &VBVariant::from_integer(format as i16),
                )
                .unwrap_err();
                assert_eq!(
                    error.number,
                    err_number::RESOURCE_NOT_FOUND,
                    "format {format} should be rejected"
                );
            }
        });
    }

    #[test]
    fn out_of_range_formats_are_rejected() {
        let mut bytes = null_record();
        bytes.extend(record(rt::RCDATA, 1, b"data"));

        with_linked_res(&bytes, || {
            for format in [
                VBVariant::from_long(0),
                VBVariant::from_long(-5),
                VBVariant::from_long(32768),
                VBVariant::Null,
            ] {
                let error = loadresdata(&VBVariant::from_integer(1), &format).unwrap_err();
                assert_eq!(error.number, err_number::RESOURCE_NOT_FOUND);
            }
        });
    }

    #[test]
    fn returned_array_is_an_independent_copy() {
        let mut bytes = null_record();
        bytes.extend(record(rt::RCDATA, 1, b"abc"));

        with_linked_res(&bytes, || {
            let format = VBVariant::from_integer(rt::RCDATA as i16);
            let mut first = loadresdata(&VBVariant::from_integer(1), &format).unwrap();
            // Mutate the first copy, then reload.
            if let VBVariant::Array(array) = &mut first {
                array.set(&[0], VBVariant::from_byte(b'Z')).unwrap();
            }

            let second = loadresdata(&VBVariant::from_integer(1), &format).unwrap();
            let reloaded = second.as_array().unwrap();
            assert_eq!(reloaded.as_slice()[0].as_byte().unwrap(), b'a');
        });
    }

    #[test]
    fn no_linked_resource_file_raises_326() {
        let _guard = crate::state::test_support::lock_test();
        resources::clear();
        let error = loadresdata(
            &VBVariant::from_integer(1),
            &VBVariant::from_integer(rt::RCDATA as i16),
        )
        .unwrap_err();
        assert_eq!(error.number, err_number::RESOURCE_NOT_FOUND);
    }
    // ---- against a real VB6-authored .res file ----

    #[test]
    fn loads_a_dll_blob_from_a_real_res_file() {
        // Project1.RES stores two binaries under the custom string type "DLL".
        // The type is a string, so this exercises the name-typed lookup path
        // via find_by_name only when the type is numeric; here the type is
        // "DLL", which no numeric format matches, so LoadResData cannot reach
        // it -- assert that faithfully rather than pretending otherwise.
        use crate::library::resources::test_support::with_test_data_res;

        with_test_data_res("test-data/CdiuBeatUpEditor/Project1.RES", || {
            let error = loadresdata(
                &VBVariant::from_string("FMOD"),
                &VBVariant::from_long(rt::RCDATA as i32),
            )
            .unwrap_err();
            assert_eq!(error.number, err_number::RESOURCE_NOT_FOUND);
        });
    }
}