SwiftAnnoy

https://jbadger3.github.io/SwiftAnnoy/
Admin
SwiftAnnoy provides an interface (bindings) to the Annoy (Approximate Nearest Neighbors Oh Yeah) C++...
Tokens:5,435
Snippets:86
Trust Score:9.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### onDiskBuild

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

Prepares the index to be built on disk rather than in RAM. Should be set before adding items to the index.

```APIDOC
## onDiskBuild(url:)

### Description
Prepares the index to be built on disk instead of in RAM. This method should be called before adding items to the index.

### Method
`public func onDiskBuild(url: URL)`

### Parameters
#### Path Parameters
- **url** (URL) - Required - A file destination URL for the index.
```

--------------------------------

### Prepare AnnoyIndex for On-Disk Build

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

Configures the Annoy index to be built on disk instead of in RAM. This must be called before adding any items to the index.

```swift
public func onDiskBuild(url: URL)
```

--------------------------------

### AnnoyIndex Initialization

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

Initializes a new AnnoyIndex with a specified item length and distance metric. The distance metric defaults to Euclidean if not provided.

```APIDOC
## init(itemLength:metric:)

### Description
Initializes a new AnnoyIndex with a specified item length and distance metric. The distance metric defaults to Euclidean if not provided.

### Parameters
- **itemLength** (Int) - The vector length (Array.count) of each item stored in the index.
- **metric** (DistanceMetric) - The metric to be used to measure the distance between items. One of .angular, .dotProduct, .euclidean, or .manhattan. Defaults to .euclidean.
```

--------------------------------

### build

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

Builds the index to enable fast approximate nearest neighbors lookup. The accuracy of the lookup is influenced by the number of trees used; more trees lead to better accuracy but longer build times.

```APIDOC
## build(numTrees:)

### Description
Builds the index to enable fast approximate nearest neighbors lookup. The accuracy of the lookup is influenced by the number of trees used; more trees lead to better accuracy but longer build times.

### Parameters
- **numTrees** (Int) - The number of trees to use to build the index.
```

--------------------------------

### AnnoyIndex build Method

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

Builds the index for efficient approximate nearest neighbor lookups. Accuracy increases with more trees, but build time also increases.

```swift
public func build(numTrees: Int) throws
```

--------------------------------

### Build Annoy Index

Source: https://jbadger3.github.io/SwiftAnnoy/index.html

Build the Annoy index to enable querying. The numTrees parameter affects accuracy, build time, search time, and memory usage.

```swift
try? index.build(numTrees: 1)
```

--------------------------------

### AnnoyIndex Initializer

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

Initializes a new AnnoyIndex with a specified item length and an optional distance metric. Defaults to .euclidean.

```swift
public init(itemLength: Int, metric: DistanceMetric = .euclidean)
```

--------------------------------

### AnnoyIndex load Method

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

Loads a previously saved Annoy index from a given URL. Throws AnnoyIndexError.loadFailed if the loading process fails.

```swift
public func load(url: URL) throws
```

--------------------------------

### Create an Annoy Index

Source: https://jbadger3.github.io/SwiftAnnoy/index.html

Instantiate an AnnoyIndex with a specified item length and distance metric. Supported types include Float and Double.

```swift
let index = AnnoyIndex<Double>(itemLength: 2, metric: .euclidean)
```

--------------------------------

### save

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

Saves the current index to a file and then immediately loads it back from disk using memory mapping. This operation can throw an AnnoyIndexError.saveFailed error.

```APIDOC
## save(url:prefault:)

### Description
Saves the current index to a file and then immediately loads it back from disk using memory mapping. This operation can throw an AnnoyIndexError.saveFailed error.

### Parameters
- **url** (URL) - The file destination URL for the index.
- **prefault** (Bool) - If set to true, the entire file will be preread into memory. Defaults to false.
```

--------------------------------

### load

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

Loads a previously saved index from a file URL. This operation can throw an AnnoyIndexError.loadFailed error.

```APIDOC
## load(url:)

### Description
Loads a previously saved index from a file URL. This operation can throw an AnnoyIndexError.loadFailed error.

### Parameters
- **url** (URL) - The file URL from which to load the index.
```

--------------------------------

### AnnoyIndex save Method

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

Saves the index to a specified URL and then memory-maps it from disk. Optionally prefaults the file into memory. Throws AnnoyIndexError.saveFailed on error.

```swift
public func save(url: URL, prefault: Bool = false) throws
```

--------------------------------

### addItems

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

Adds multiple new items to the index. This operation can throw an AnnoyIndexError.addIemFailed error.

```APIDOC
## addItems(items:)

### Description
Adds multiple new items to the index. This operation can throw an AnnoyIndexError.addIemFailed error.

### Parameters
- **items** ([[T]]) - An Array of vectors to add to the index.
```

--------------------------------

### getItem

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

Retrieves the vector for an item in the index.

```APIDOC
## getItem(index:)

### Description
Retrieves the vector for a given item index from the Annoy index.

### Method
`public func getItem(index: Int) -> [T]?`

### Parameters
#### Path Parameters
- **index** (Int) - Required - The index of the item to retrieve.

### Return Value
The vector associated with the item or nil if not found.
```

--------------------------------

### setVerbos

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

When set to true provides additional information about operations carried out by Annoy via stdout.

```APIDOC
## setVerbos(boolVal:)

### Description
Provides additional information about operations carried out by Annoy via stdout when set to true.

### Method
`public func setVerbos(boolVal: Bool)`

### Parameters
- **boolVal** (Bool) - Description: A boolean value to enable or disable verbose output.
```

--------------------------------

### Add Items to Annoy Index

Source: https://jbadger3.github.io/SwiftAnnoy/index.html

Populate an Annoy index using either single items or multiple items. Indices must be added in chronological order (0...n-1).

```swift
var item0 = [1.0, 1.0]
var item1 = [3.0, 4.0]
var item2 = [6.0, 8.0]
var items = [[item0, item1, item2]]

// add one item
try? index.addItem(index: 0, vector: &item0)

// add multple items
try? index.addItems(items: &items)
```

--------------------------------

### AnnoyIndex addItems Method

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

Adds multiple items, each represented by a vector, to the index. Throws AnnoyIndexError.addIemFailed on failure.

```swift
public func addItems(items: inout [[T]]) throws
```

--------------------------------

### Set Random Seed for AnnoyIndex

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

Configures the random seed for index generation. This is useful for performance testing to ensure consistent and reproducible results.

```swift
public func setSeed(seedVal: Int)
```

--------------------------------

### getNNsForItem

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

Gathers the approximate nearest neighbors for a given item index. Allows specifying the number of neighbors and the search K value for accuracy control.

```APIDOC
## getNNsForItem(item:neighbors:search_k:)

### Description
Gathers the approximate nearest neighbors for a given item index. Allows specifying the number of neighbors and the search K value for accuracy control.

### Parameters
- **item** (Int) - The index of the item of interest.
- **neighbors** (Int) - The number of neighbors to return.
- **search_k** (Int) - The number of nodes to inspect during search. Defaults to -1 (Annoy's default calculation).

### Return Value
A tuple of arrays containing the item indices and distances, or nil if no neighbors are found.
```

--------------------------------

### unbuild

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

Unbuilds the current AnnoyIndex, allowing for the addition of more items or rebuilding the index with a different number of trees. This operation can throw an AnnoyIndexError.UnbuildFailed error.

```APIDOC
## unbuild()

### Description
Unbuilds the current AnnoyIndex, allowing for the addition of more items or rebuilding the index with a different number of trees. This operation can throw an AnnoyIndexError.UnbuildFailed error.
```

--------------------------------

### AnnoyIndex numberOfTrees Property

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

Returns the number of trees configured for the index, relevant after the index has been built.

```swift
public var numberOfTrees: Int { get }
```

--------------------------------

### AnnoyIndex getNNsForItem Method

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

Retrieves the approximate nearest neighbors for a given item index. Allows specifying the number of neighbors and the search K value for accuracy tuning.

```swift
public func getNNsForItem(item: Int, neighbors: Int, search_k: Int = -1) -> (indices: [Int], distances: [T])?
```

--------------------------------

### Query Annoy Index by Vector

Source: https://jbadger3.github.io/SwiftAnnoy/index.html

Retrieve nearest neighbors for a given vector. Results include indices and distances.

```swift
// by vector
var vector = [3.0, 4.0]
let results2 = index.getNNsForVector(vector: &vector, neighbors: 3)
print(results2)
"Optional((indices: [2, 0, 1], distances: [0.0, 3.605551275463989, 3.605551275463989]))"
```

--------------------------------

### Query Annoy Index by Item

Source: https://jbadger3.github.io/SwiftAnnoy/index.html

Retrieve nearest neighbors for a given item index. Results include indices and distances.

```swift
// by item
let results =  index.getNNsForItem(item: 3, neighbors: 3)
print(results)
"Optional((indices: [3, 2, 0], distances: [0.0, 5.0, 8.602325267042627]))"
```

--------------------------------

### AnnoyIndex unbuild Method

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

Unbuilds the index, allowing for modifications like adding more items or rebuilding with a different number of trees. Throws AnnoyIndexError.UnbuildFailed if the operation fails.

```swift
public func unbuild() throws
```

--------------------------------

### AnnoyIndex getNNsForVector Method

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

Finds the approximate nearest neighbors for a given vector. Users can specify the number of neighbors and the search K value to control accuracy and performance.

```swift
public func getNNsForVector(vector: inout [T], neighbors: Int, search_k: Int = -1) -> (indices: [Int], distances: [T])?
```

--------------------------------

### AnnoyIndex numberOfItems Property

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

Returns the total count of items currently present in the Annoy index.

```swift
public var numberOfItems: Int { get }
```

--------------------------------

### AnnoyIndexError Case: buildFailed

Source: https://jbadger3.github.io/SwiftAnnoy/Enums/AnnoyIndexError.html

Signifies an error during the process of building the Annoy index. This case does not carry associated data.

```swift
case buildFailed
```

--------------------------------

### Set Verbosity for AnnoyIndex

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

Enable or disable verbose output for Annoy operations. Set to true to see additional information printed to stdout.

```swift
public func setVerbos(boolVal: Bool)
```

--------------------------------

### DistanceMetric Enum Declaration

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

Defines the supported distance metrics for the Annoy index, such as euclidean, angular, dotProduct, and manhattan.

```swift
public enum DistanceMetric : String
```

--------------------------------

### DistanceMetric Enum

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex/DistanceMetric.html

The DistanceMetric enum defines the supported distance and similarity measures for Annoy indexes.

```APIDOC
## DistanceMetric

### Description
An enum representing the supported distance metrics for Annoy indexes.

### Cases

- **angular**: The angular distance, calculated as the Euclidean distance of normalized vectors. Formula: `sqrt(2(1-cos(u,v)))`.
- **dotProduct**: The dot product, also known as the inner product.
- **euclidean**: The L2 or straight-line distance, calculated using the Pythagorean formula.
- **manhattan**: The L1 or city block distance.
```

--------------------------------

### AnnoyIndex distanceMetric Property

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

Indicates the distance metric used for similarity calculations between vectors in the index.

```swift
public private(set) var distanceMetric: [CChar] { get }
```

--------------------------------

### addItem

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

Adds a single new item to the index with a specified index and vector representation. This operation can throw an AnnoyIndexError.addItemFailed error.

```APIDOC
## addItem(index:vector:)

### Description
Adds a single new item to the index with a specified index and vector representation. This operation can throw an AnnoyIndexError.addItemFailed error.

### Parameters
- **index** (Int) - The index (integer) to assign to the item.
- **vector** ([T]) - Array representing the feature vector for the item.
```

--------------------------------

### Euclidean Distance Metric

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex/DistanceMetric.html

Represents the L2 or straight-line distance, calculated using the Pythagorean formula. This is a standard metric for measuring distances in Euclidean space.

```swift
case euclidean
```

--------------------------------

### setSeed

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

Sets the random seed used for generating the index. Useful for performance testing to ensure consistent results.

```APIDOC
## setSeed(seedVal:)

### Description
Sets the random seed used for generating the index. This is useful for performance testing to ensure consistent results.

### Method
`public func setSeed(seedVal: Int)`

### Parameters
- **seedVal** (Int) - Description: The integer value to set as the random seed.
```

--------------------------------

### Retrieve Item Vector from AnnoyIndex

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

Fetches the vector associated with a specific item index. Returns nil if the index is not found.

```swift
public func getItem(index: Int) -> [T]?
```

--------------------------------

### AnnoyIndex itemLength Property

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

Represents the length of each vector in the index. This is typically the Array count for each item.

```swift
public private(set) var itemLength: Int { get }
```

--------------------------------

### Dot Product Distance Metric

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex/DistanceMetric.html

Represents the dot product (inner product) as a distance metric. Suitable for similarity calculations where higher dot products indicate greater similarity.

```swift
case dotProduct
```

--------------------------------

### AnnoyIndex addItem Method

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

Adds a single item with its vector to the index at a specified index. Throws AnnoyIndexError.addItemFailed if the operation fails.

```swift
public func addItem(index: Int, vector: inout [T]) throws
```

--------------------------------

### AnnoyIndexError Case: unbuildFailed

Source: https://jbadger3.github.io/SwiftAnnoy/Enums/AnnoyIndexError.html

Represents a failure that occurred while trying to unbuild or dismantle the Annoy index. This case is a simple error type.

```swift
case unbuildFailed
```

--------------------------------

### Declare Double Extension for AnnoyOperable

Source: https://jbadger3.github.io/SwiftAnnoy/Extensions.html

Extends the Double type to conform to the AnnoyOperable protocol. This allows Double values to be used with Annoy operations.

```swift
extension Double: AnnoyOperable

```

--------------------------------

### AnnoyIndex getDistance Method

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

Calculates and returns the distance between two items in the index, identified by their indices. Returns nil if either item is not found.

```swift
public func getDistance(item1: Int, item2: Int) -> T?
```

--------------------------------

### AnnoyOperable Protocol Declaration

Source: https://jbadger3.github.io/SwiftAnnoy/Protocols.html

This is the public protocol declaration for AnnoyOperable in Swift.

```swift
public protocol AnnoyOperable
```

--------------------------------

### unload

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

Unloads the underlying index and all associated items from memory.

```APIDOC
## unload()

### Description
Unloads the underlying index and all associated items from memory.
```

--------------------------------

### Declare Float Extension for AnnoyOperable

Source: https://jbadger3.github.io/SwiftAnnoy/Extensions.html

Extends the Float type to conform to the AnnoyOperable protocol. This allows Float values to be used with Annoy operations.

```swift
extension Float: AnnoyOperable

```

--------------------------------

### AnnoyIndexError Case: addItemFailed

Source: https://jbadger3.github.io/SwiftAnnoy/Enums/AnnoyIndexError.html

Indicates a failure when attempting to add an item to the Annoy index. This is a simple case without associated values.

```swift
case addItemFailed
```

--------------------------------

### AnnoyIndex dataType Property

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

Specifies the type of data used within each vector stored in the index.

```swift
public private(set) var dataType: [CChar] { get }
```

--------------------------------

### getDistance

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

Calculates the distance between two items in the index based on their indices. Returns the distance or nil if either item is not found.

```APIDOC
## getDistance(item1:item2:)

### Description
Calculates the distance between two items in the index based on their indices. Returns the distance or nil if either item is not found.

### Parameters
- **item1** (Int) - The index of the first item of interest.
- **item2** (Int) - The index of the second item of interest.

### Return Value
The distance between the two items or nil if one of the items is not in the index.
```

--------------------------------

### AnnoyIndex Class Declaration

Source: https://jbadger3.github.io/SwiftAnnoy/Classes.html

This is the declaration of the generic AnnoyIndex class. It requires the type parameter T to conform to the AnnoyOperable protocol.

```swift
public class AnnoyIndex<T> where T : AnnoyOperable
```

--------------------------------

### getNNsForVector

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

Gathers the approximate nearest neighbors for a given vector. Allows specifying the number of neighbors and the search K value for accuracy control.

```APIDOC
## getNNsForVector(vector:neighbors:search_k:)

### Description
Gathers the approximate nearest neighbors for a given vector. Allows specifying the number of neighbors and the search K value for accuracy control.

### Parameters
- **vector** ([T]) - The feature vector for which to find nearest neighbors.
- **neighbors** (Int) - The number of neighbors to return.
- **search_k** (Int) - The number of nodes to inspect during search. Defaults to -1 (Annoy's default calculation).

### Return Value
A tuple of arrays containing the item indices and distances, or nil if no neighbors are found.
```

--------------------------------

### AnnoyIndexError errorDescription Property

Source: https://jbadger3.github.io/SwiftAnnoy/Enums/AnnoyIndexError.html

The computed property 'errorDescription' provides a localized description for the AnnoyIndexError, conforming to the LocalizedError protocol.

```swift
public var errorDescription: String? { get }
```

--------------------------------

### AnnoyIndexError Case: loadFailed

Source: https://jbadger3.github.io/SwiftAnnoy/Enums/AnnoyIndexError.html

Signifies an error encountered while attempting to load an Annoy index. This case is a straightforward error type.

```swift
case loadFailed
```

--------------------------------

### AnnoyIndexError Enumeration Declaration

Source: https://jbadger3.github.io/SwiftAnnoy/Enums.html

This is the declaration for the AnnoyIndexError enumeration, which conforms to the Error and LocalizedError protocols. It is used to represent various errors that can occur within the AnnoyIndex.

```swift
public enum AnnoyIndexError : Error, LocalizedError
```

--------------------------------

### AnnoyIndex unload Method

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex.html

Unloads the underlying index data and all associated items from memory.

```swift
public func unload()
```

--------------------------------

### Manhattan Distance Metric

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex/DistanceMetric.html

Represents the L1 or city block distance. Useful in scenarios where movement is restricted to orthogonal directions.

```swift
case manhattan
```

--------------------------------

### AnnoyIndexError Case: saveFailed

Source: https://jbadger3.github.io/SwiftAnnoy/Enums/AnnoyIndexError.html

Indicates that an error occurred during the saving operation of the Annoy index. This case is a basic error indicator.

```swift
case saveFailed
```

--------------------------------

### AnnoyIndexError Case: invalidVectorLength

Source: https://jbadger3.github.io/SwiftAnnoy/Enums/AnnoyIndexError.html

Represents an error when an invalid vector length is provided. This case includes an associated message string.

```swift
case invalidVectorLength(message: String)
```

--------------------------------

### Angular Distance Metric

Source: https://jbadger3.github.io/SwiftAnnoy/Classes/AnnoyIndex/DistanceMetric.html

Represents the angular distance, calculated as the Euclidean distance of normalized vectors. Use for normalized vector comparisons.

```swift
case angular
```

--------------------------------

### AnnoyIndexError Enum Cases

Source: https://jbadger3.github.io/SwiftAnnoy/Enums/AnnoyIndexError.html

The AnnoyIndexError enum defines specific error types that can occur when working with Annoy indexes. These include issues like invalid input, failed operations, and problems during data persistence.

```APIDOC
## AnnoyIndexError Enum

### Description
Represents errors that can be thrown by AnnoyIndex operations.

### Cases

- **invalidVectorLength**: Indicates an error due to an invalid vector length provided to an Annoy operation.
  - **Declaration**: `case invalidVectorLength(message: String)`

- **addItemFailed**: Indicates that adding an item to the Annoy index failed.
  - **Declaration**: `case addItemFailed`

- **buildFailed**: Indicates that the process of building the Annoy index failed.
  - **Declaration**: `case buildFailed`

- **unbuildFailed**: Indicates that the process of unbuilding the Annoy index failed.
  - **Declaration**: `case unbuildFailed`

- **saveFailed**: Indicates that saving the Annoy index to disk failed.
  - **Declaration**: `case saveFailed`

- **loadFailed**: Indicates that loading the Annoy index from disk failed.
  - **Declaration**: `case loadFailed`

### Error Handling

- **errorDescription**: Provides a localized description of the error.
  - **Declaration**: `public var errorDescription: String? { get }`
```
Tokens:
Raw