Added formatExpression to MagickImage (#191).

src/internal/native/string.ts

@@ -16,6 +16,15 @@ export function _createString(instance: number, defaultValueOrUndefined?: string
     return ImageMagick._api.UTF8ToString(instance);
 }
 
+/** @internal */
+export function _createStringAndRelinquish(api: ImageMagickApi, instance: number): string | null {
+    const result = _createString(instance);
+
+    api._MagickMemory_Relinquish(instance);
+
+    return result;
+}
+
 /** @internal */
 export function _withNativeString<TReturnType>(api: ImageMagickApi, str: string, func: (instance: number) => TReturnType): TReturnType {
     const length = api.lengthBytesUTF8(str) + 1;

src/magick-image.ts

@@ -69,7 +69,7 @@ import { StringInfo } from './internal/string-info';
 import { TemporaryDefines } from './helpers/temporary-defines';
 import { VirtualPixelMethod } from './enums/virtual-pixel-method';
 import { WarningEvent } from './events/warning-event';
-import { _createString, _withString } from './internal/native/string';
+import { _createString, _createStringAndRelinquish, _withString } from './internal/native/string';
 import { _getEdges } from './enums/gravity';
 import { _withByteArray, _withDoubleArray } from './internal/native/array';
 
@@ -1106,6 +1106,12 @@ export interface IMagickImage extends IDisposable {
      */
     flop(): void;
 
+    /**
+     * Formats the specified expression (more info can be found here: https://imagemagick.org/script/escape.php).
+     * @param expression The expression.
+     */
+    formatExpression(expression: string): string | null;
+
     /**
      * Gamma correct image.
      * @param gamma The image gamma.
@@ -2782,6 +2788,21 @@ export class MagickImage extends NativeInstance implements IMagickImage {
         });
     }
 
+    /**
+     * Formats the specified expression (more info can be found here: https://imagemagick.org/script/escape.php).
+     * @param expression The expression.
+     */
+    formatExpression(expression: string): string | null {
+        return this.useExceptionPointer(exception => {
+            return this._settings._use(settings => {
+                return _withString(expression, expressionPtr => {
+                    const instance = ImageMagick._api._MagickImage_FormatExpression(this._instance, settings._instance, expressionPtr, exception);
+                    return _createStringAndRelinquish(ImageMagick._api, instance);
+                });
+            });
+        });
+    }
+
     gammaCorrect(gamma: number): void;
     gammaCorrect(gamma: number, channels: Channels): void;
     gammaCorrect(gamma: number, channelsOrUndefined?: Channels): void {

tests/magick-image/format-expression.spec.ts

@@ -0,0 +1,27 @@
+/*
+  Copyright Dirk Lemstra https://github.com/dlemstra/magick-wasm.
+  Licensed under the Apache License, Version 2.0.
+*/
+
+import { ColorSpace } from '@src/enums/color-space';
+import { TestFiles } from '@test/test-files';
+
+describe('MagickImage#formatExpression', () => {
+    it('should format the specified expression', () => {
+        TestFiles.Images.Color.purple.use(image => {
+            let result = image.formatExpression("%[pixel:u]");
+
+            expect(image.colorSpace).toBe(ColorSpace.sRGB);
+
+            expect(result).toBe('srgb(128,0,128)')
+
+            const rgbProfile = TestFiles.Profiles.Color.SRGB.load();
+            const cmykProfile = TestFiles.Profiles.Color.USWebCoatedSWOP.load();
+            image.transformColorSpace(rgbProfile, cmykProfile);
+
+            result = image.formatExpression("%[pixel:u]");
+
+            expect(result).toBe('cmyk(161,255,47,15)')
+        });
+    });
+});