> For the complete documentation index, see [llms.txt](https://docsv1.polyfrost.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docsv1.polyfrost.org/utilities-module/io-utilities.md).

# IO utilities

## Clipboard manipulation

OneConfig no longer provides in-house utilities for managing the user's clipboard; however, we do include [Deftu's Copycat library](https://github.com/Deftu/Copycat), which uses native code to bypass any issues brought on by certain operating systems (such as macOS disallowing headless apps from using the AWT clipboard API).

### Obtaining a clipboard instance

```java
Clipboard clipboard = Clipboard.getInstance();
```

The default implementation of `Clipboard` uses the natives provided by Copycat. Calling the `getInstance` method will automatically load the natives should it need to.

### Copying and getting strings

{% tabs %}
{% tab title="Java" %}

```java
String clipboardString = clipboard.getString();
if (clipboardString == null) {
    // If the user does not have anything copied, or the copied content
    // is not a string (e.g. it's an image), then the `getString`
    // method returns null.
    return;
}

String newClipboardString = "Hello, OneConfig!";
clipboard.setString(newClipboardString); // Copies our string to the user's clipboard
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
// If the user does not have anything copied, or the copied content
// is not a string (e.g. it's an image), then the `getString`
// method returns null.
val clipboardString = clipboard.string ?: return

val newClipboardString = "Hello, OneConfig!"
clipboard.string = newClipboardString // Copies our string to the user's clipboard
```

{% endtab %}
{% endtabs %}

### Copying and getting images

{% tabs %}
{% tab title="Java" %}

```java
ClipboardImage clipboardImage = clipboard.getImage();
if (clipboardImage == null) {
    // If the user does not have anything copied, or the copied content
    // is not an image (e.g. it's a string), then the `getImage` method returns null.
    return;
}

ClipboardImage newClipboardImage = null; // Obtain your image somehow...
clipboard.setImage(newClipboardImage); // Copies our image to the user's clipboard
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
// If the user does not have anything copied, or the copied content
// is not an image (e.g. it's a string), then the `getImage` method returns null.
val clipboardImage: ClipboardImage = clipboard.image ?: return
if (clipboardString == null) {
    return
}

val newClipboardImage: ClipboardImage = TODO("Replace with image")
clipboard.image = newClipboardImage // Copies our image to the user's clipboard
```

{% endtab %}
{% endtabs %}

By default, `ClipboardImage` on it's own is simply two `int`s for the `width` x `height`, and an array of bytes for the raw image data. Thus meaning, that should you want to make use of it in any meaningful way, you'll need to convert it to another type for another library OR handle the raw bytes on your own. Thankfully, Copycat provides a means of converting to and from the Java AWT types for you, which you can find below.

### Copying AWT images (BufferedImage)

{% tabs %}
{% tab title="Java" %}

```java
BufferedImage ourImage = ImageIO.read("/path/to/your/image");
// Now, we can't simply copy the above image as it is because we need
// a ClipboardImage, not a BufferedImage.

// So, we'll convert it using this subtype.
ClipboardImage ourClipboardImage = BufferedClipboardImage.toClipboardImage(ourImage);

// Now, we can finally copy it.
Clipboard clipboard = Clipboard.getInstance();
clipboard.setImage(ourClipboardImage);
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
val ourImage = ImageIO.read("/path/to/your/image")
// Now, we can't simply copy the above image as it is because we need
// a ClipboardImage, not a BufferedImage.

// So, we'll convert it using this subtype.
val ourClipboardImage: ClipboardImage = BufferedClipboardImage.toClipboardImage(ourImage)

// Now, we can finally copy it.
val clipboard = Clipboard.instance
clipboard.image = ourClipboardImage
```

{% endtab %}
{% endtabs %}

This works vice versa too!

{% tabs %}
{% tab title="Java" %}

```java
Clipboard clipboard = Clipboard.getInstance();
ClipboardImage clipboardImage = clipboard.getImage();

// Now, we just need to convert it to a BufferedImage
BufferedImage image = BufferedClipboardImage.toBufferedImage(clipboardImage);
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
val clipboard = Clipboard.instance
val clipboardImage = clipboard.image

// Now, we just need to convert it to a BufferedImage
val image = BufferedClipboardImage.toBufferedImage(clipboardImage)
```

{% endtab %}
{% endtabs %}

## File checksums (SHA-256 only)

OneConfig provides a single, ease-to-use method for obtaining the checksum of a file at a given path.

{% tabs %}
{% tab title="Java" %}

```java
Path myFilePath = Paths.get("/path/to/your/file");
String sha256Checksum = IOUtils.getFileChecksum(myFilePath);

// Couldn't obtain the file's checksum
if (sha256Checksum.isEmpty()) {
    return;
}
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
val myFilePath = Paths.get("/path/to/your/file")
val sha256Checksum = IOUtils.getFileChecksum(myFilePath)

// Couldn't obtain the file's checksum
if (sha256Checksum.isEmpty()) {
    return
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docsv1.polyfrost.org/utilities-module/io-utilities.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.