//
//  WREpubPositionConverter.h
//  WeRead (读书)
//  Reverse-engineered header
//
//  Position converter between file positions and character positions.
//  Used for bookmark synchronization and reading progress tracking.
//  Maps (fileIndex, row, column) triples to character offsets in the
//  concatenated text of the book.
//

#import <Foundation/Foundation.h>

NS_ASSUME_NONNULL_BEGIN

@class NSAttributedString;

// ---------------------------------------------------------------------------
// Position pair structure used in row/column-based lookups
// ---------------------------------------------------------------------------
@interface WRPositionPair : NSObject
@property (nonatomic) NSInteger row;
@property (nonatomic) NSInteger column;
@end

// ---------------------------------------------------------------------------
// WREpubPositionConverter
// ---------------------------------------------------------------------------
@interface WREpubPositionConverter : NSObject

// --- Ivars (from binary analysis) ---
// {
//     NSArray          *_filePaths;            // paths to chapter XHTML files
//     NSArray          *_attributedStrings;    // parsed attributed strings per file
//     NSMutableArray   *_fileLengths;          // character count per file
//     NSMutableArray   *_cumulativeOffsets;    // cumulative character offsets
//     NSMutableDictionary *_indexCache;        // cached index lookups
//     NSMutableDictionary *_stringRangeCache;  // cached range lookups
//     ... more ...
// }

@property (nonatomic, strong, readonly) NSArray<NSString *> *filePaths;
@property (nonatomic, strong, readonly) NSArray<NSAttributedString *> *attributedStrings;

#pragma mark - Initialization

/// Initialize with file paths and their corresponding attributed strings.
/// @param filePaths         Array of chapter file paths (in spine order).
/// @param attributedStrings Array of NSAttributedString for each file.
/// @param offset            Base character offset (e.g., for non-chapter content).
/// @param isContainIntroFlyleaf YES if the flyleaf/cover page is included.
- (instancetype)initWithFilePaths:(NSArray<NSString *> *)filePaths
                 attributedStrings:(NSArray<NSAttributedString *> *)attributedStrings
                            offset:(NSInteger)offset
             isContainIntroFlyleaf:(BOOL)isContainIntroFlyleaf;

#pragma mark - Index Building

/// Build internal index tables for fast position lookup.
/// Must be called before performing conversions.
- (void)initIndices;

#pragma mark - Position Conversion

/// Convert row/column pairs to string indices within a specific file.
/// @param filePath         The chapter file path.
/// @param rowColumnPairs   Array of WRPositionPair objects.
/// @param stringIndices    (out) Array of NSNumber (NSInteger) with resolved indices.
/// @param string           The full text string of the file.
/// @param fileIndexOffset  Offset to add to the file index.
/// @param stringIndexOffset Offset to add to the resulting string index.
- (void)indicesInFile:(NSString *)filePath
     forRowColumnPairs:(NSArray<WRPositionPair *> *)rowColumnPairs
         stringIndices:(NSArray *_Nullable *_Nullable)stringIndices
                string:(NSString *)string
        fileIndexOffset:(NSInteger)fileIndexOffset
       stringIndexOffset:(NSInteger)stringIndexOffset;

/// Convert a file-based range (fileIndex, startOffset, endOffset)
/// to a character range in the concatenated book string.
/// @return NSRange in the global string, or NSNotFound if invalid.
- (NSRange)stringRangeFromFileRange:(NSDictionary *)fileRange;

#pragma mark - Utility

/// Return the total character count across all files.
- (NSInteger)totalCharacterCount;

/// Return the file index that contains the given global character position.
- (NSInteger)fileIndexForCharacterPosition:(NSInteger)position;

/// Return the local character offset within a file for a global position.
- (NSInteger)localOffsetInFileAtIndex:(NSInteger)fileIndex
                     forGlobalPosition:(NSInteger)position;

@end

NS_ASSUME_NONNULL_END