org.gnome.glib.PathBuf Maven / Gradle / Ivy
// Java-GI - Java language bindings for GObject-Introspection-based libraries
// Copyright (C) 2022-2024 Jan-Willem Harmannij
//
// SPDX-License-Identifier: LGPL-2.1-or-later
//
// This library is free software; you can redistribute it and/or
// modify it under the terms of the GNU Lesser General Public
// License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
//
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
// Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, see {@code
* g_auto (GPathBuf) path;
*
* g_path_buf_init (&path);
*
* g_path_buf_push (&path, "usr");
* g_path_buf_push (&path, "bin");
* g_path_buf_push (&path, "echo");
*
* g_autofree char *echo = g_path_buf_to_path (&path);
* g_assert_cmpstr (echo, ==, "/usr/bin/echo");
* }
*
* You can also load a full path and then operate on its components:
*
{@code
* g_auto (GPathBuf) path;
*
* g_path_buf_init_from_path (&path, "/usr/bin/echo");
*
* g_path_buf_pop (&path);
* g_path_buf_push (&path, "sh");
*
* g_autofree char *sh = g_path_buf_to_path (&path);
* g_assert_cmpstr (sh, ==, "/usr/bin/sh");
* }
*
* {@code GPathBuf} is available since GLib 2.76.
* @version 2.76
*/
@Generated("io.github.jwharm.JavaGI")
public class PathBuf extends ManagedInstance {
static {
GLib.javagi$ensureInitialized();
}
/**
* Create a PathBuf proxy instance for the provided memory address.
*
* @param address the memory address of the native object
*/
public PathBuf(MemorySegment address) {
super(Interop.reinterpret(address, getMemoryLayout().byteSize()));
}
/**
* Allocate a new PathBuf.
*
* @param arena to control the memory allocation scope
*/
public PathBuf(Arena arena) {
super(arena.allocate(getMemoryLayout()));
}
/**
* Allocate a new PathBuf.
* The memory is allocated with {@link Arena#ofAuto}.
*/
public PathBuf() {
super(Arena.ofAuto().allocate(getMemoryLayout()));
}
/**
* Allocate a new PathBuf with the fields set to the provided values.
*
* @param dummy value for the field {@code dummy}
* @param arena to control the memory allocation scope
*/
public PathBuf(MemorySegment[] dummy, Arena arena) {
this(arena);
writeDummy(dummy, arena);
}
/**
* Allocate a new PathBuf with the fields set to the provided values.
* The memory is allocated with {@link Arena#ofAuto}.
*
* @param dummy value for the field {@code dummy}
*/
public PathBuf(MemorySegment[] dummy) {
this(Arena.ofAuto());
writeDummy(dummy, Arena.ofAuto());
}
/**
* The memory layout of the native struct.
* @return the memory layout
*/
public static MemoryLayout getMemoryLayout() {
return MemoryLayout.structLayout(
MemoryLayout.sequenceLayout(8, ValueLayout.ADDRESS).withName("dummy")
).withName("GPathBuf");
}
/**
* Allocate a new PathBuf.
*
* @param arena to control the memory allocation scope
* @return a new, uninitialized {@link PathBuf}
* @deprecated Replaced by {@link PathBuf#PathBuf(Arena)}
*/
@Deprecated
public static PathBuf allocate(Arena arena) {
MemorySegment segment = arena.allocate(getMemoryLayout());
return new PathBuf(segment);
}
/**
* Allocate a new PathBuf with the fields set to the provided values.
*
* @param arena to control the memory allocation scope
* @param dummy value for the field {@code dummy}
* @return a new {@link PathBuf} with the fields set to the provided values
* @deprecated Replaced by {@link PathBuf#PathBuf(java.lang.foreign.MemorySegment[], Arena)}
*/
@Deprecated
public static PathBuf allocate(Arena arena, MemorySegment[] dummy) {
return new PathBuf(dummy, arena);
}
/**
* Read the value of the field {@code dummy}.
*
* @return The value of the field {@code dummy}
*/
public MemorySegment[] readDummy() {
Arena _arena = Arena.ofAuto();
var _result = (MemorySegment) getMemoryLayout()
.varHandle(MemoryLayout.PathElement.groupElement("dummy")).get(handle());
return Interop.getAddressArrayFrom(_result, 8, false);
}
/**
* Write a value in the field {@code dummy}.
*
* @param dummy The new value for the field {@code dummy}
* @param _arena to control the memory allocation scope
*/
public void writeDummy(MemorySegment[] dummy, Arena _arena) {
getMemoryLayout().varHandle(MemoryLayout.PathElement.groupElement("dummy"))
.set(handle(), (dummy == null ? MemorySegment.NULL : Interop.allocateNativeArray(dummy, false, _arena)));
}
/**
* Compares two path buffers for equality and returns {@code TRUE}
* if they are equal.
*
* The path inside the paths buffers are not going to be normalized,
* so {@code X/Y/Z/A/..}, {@code X/./Y/Z} and {@code X/Y/Z} are not going to be considered
* equal.
*
* This function can be passed to g_hash_table_new() as the
* {@code key_equal_func} parameter.
* @param v1 a path buffer to compare
* @param v2 a path buffer to compare
* @return {@code TRUE} if the two path buffers are equal,
* and {@code FALSE} otherwise
*/
public static boolean equal(MemorySegment v1, MemorySegment v2) {
int _result;
try {
FunctionDescriptor _fdesc = FunctionDescriptor.of(ValueLayout.JAVA_INT,
ValueLayout.ADDRESS, ValueLayout.ADDRESS);
_result = (int) Interop.downcallHandle("g_path_buf_equal", _fdesc, false).invokeExact(
(MemorySegment) (v1 == null ? MemorySegment.NULL : v1),
(MemorySegment) (v2 == null ? MemorySegment.NULL : v2));
} catch (Throwable _err) {
throw new AssertionError("Unexpected exception occurred: ", _err);
}
return _result != 0;
}
/**
* Allocates a new {@code GPathBuf}.
* @return the newly allocated path buffer
*/
public static PathBuf new_() {
MemorySegment _result;
try {
FunctionDescriptor _fdesc = FunctionDescriptor.of(ValueLayout.ADDRESS);
_result = (MemorySegment) Interop.downcallHandle("g_path_buf_new", _fdesc, false)
.invokeExact();
} catch (Throwable _err) {
throw new AssertionError("Unexpected exception occurred: ", _err);
}
var _instance = MemorySegment.NULL.equals(_result) ? null : new PathBuf(_result);
if (_instance != null) {
MemoryCleaner.takeOwnership(_instance.handle());
}
return _instance;
}
/**
* Allocates a new {@code GPathBuf} with the given {@code path}.
* @param path the path used to initialize the buffer
* @return the newly allocated path buffer
*/
public static PathBuf newFromPath(@Nullable String path) {
try (var _arena = Arena.ofConfined()) {
MemorySegment _result;
try {
FunctionDescriptor _fdesc = FunctionDescriptor.of(ValueLayout.ADDRESS,
ValueLayout.ADDRESS);
_result = (MemorySegment) Interop.downcallHandle("g_path_buf_new_from_path", _fdesc, false)
.invokeExact(
(MemorySegment) (path == null ? MemorySegment.NULL : Interop.allocateNativeString(path, _arena)));
} catch (Throwable _err) {
throw new AssertionError("Unexpected exception occurred: ", _err);
}
var _instance = MemorySegment.NULL.equals(_result) ? null : new PathBuf(_result);
if (_instance != null) {
MemoryCleaner.takeOwnership(_instance.handle());
}
return _instance;
}
}
/**
* Clears the contents of the path buffer.
*
* This function should be use to free the resources in a stack-allocated
* {@code GPathBuf} initialized using g_path_buf_init() or
* g_path_buf_init_from_path().
*/
public void clear() {
try {
FunctionDescriptor _fdesc = FunctionDescriptor.ofVoid(ValueLayout.ADDRESS);
Interop.downcallHandle("g_path_buf_clear", _fdesc, false).invokeExact(handle());
} catch (Throwable _err) {
throw new AssertionError("Unexpected exception occurred: ", _err);
}
}
/**
* Clears the contents of the path buffer and returns the built path.
*
* This function returns {@code NULL} if the {@code GPathBuf} is empty.
*
* See also: g_path_buf_to_path()
* @return the built path
*/
public String clearToPath() {
MemorySegment _result;
try {
FunctionDescriptor _fdesc = FunctionDescriptor.of(ValueLayout.ADDRESS,
ValueLayout.ADDRESS);
_result = (MemorySegment) Interop.downcallHandle("g_path_buf_clear_to_path", _fdesc, false)
.invokeExact(handle());
} catch (Throwable _err) {
throw new AssertionError("Unexpected exception occurred: ", _err);
}
return Interop.getStringFrom(_result, true);
}
/**
* Copies the contents of a path buffer into a new {@code GPathBuf}.
* @return the newly allocated path buffer
*/
public PathBuf copy() {
MemorySegment _result;
try {
FunctionDescriptor _fdesc = FunctionDescriptor.of(ValueLayout.ADDRESS,
ValueLayout.ADDRESS);
_result = (MemorySegment) Interop.downcallHandle("g_path_buf_copy", _fdesc, false)
.invokeExact(handle());
} catch (Throwable _err) {
throw new AssertionError("Unexpected exception occurred: ", _err);
}
var _instance = MemorySegment.NULL.equals(_result) ? null : new PathBuf(_result);
if (_instance != null) {
MemoryCleaner.takeOwnership(_instance.handle());
}
return _instance;
}
/**
* Frees a {@code GPathBuf} allocated by g_path_buf_new().
*/
public void free() {
try {
FunctionDescriptor _fdesc = FunctionDescriptor.ofVoid(ValueLayout.ADDRESS);
Interop.downcallHandle("g_path_buf_free", _fdesc, false).invokeExact(handle());
} catch (Throwable _err) {
throw new AssertionError("Unexpected exception occurred: ", _err);
}
}
/**
* Frees a {@code GPathBuf} allocated by g_path_buf_new(), and
* returns the path inside the buffer.
*
* This function returns {@code NULL} if the {@code GPathBuf} is empty.
*
* See also: g_path_buf_to_path()
* @return the path
*/
public String freeToPath() {
MemorySegment _result;
try {
FunctionDescriptor _fdesc = FunctionDescriptor.of(ValueLayout.ADDRESS,
ValueLayout.ADDRESS);
_result = (MemorySegment) Interop.downcallHandle("g_path_buf_free_to_path", _fdesc, false)
.invokeExact(handle());
} catch (Throwable _err) {
throw new AssertionError("Unexpected exception occurred: ", _err);
}
return Interop.getStringFrom(_result, true);
}
/**
* Initializes a {@code GPathBuf} instance.
* @return the initialized path builder
*/
public PathBuf init() {
MemorySegment _result;
try {
FunctionDescriptor _fdesc = FunctionDescriptor.of(ValueLayout.ADDRESS,
ValueLayout.ADDRESS);
_result = (MemorySegment) Interop.downcallHandle("g_path_buf_init", _fdesc, false)
.invokeExact(handle());
} catch (Throwable _err) {
throw new AssertionError("Unexpected exception occurred: ", _err);
}
var _instance = MemorySegment.NULL.equals(_result) ? null : new PathBuf(_result);
if (_instance != null) {
MemoryCleaner.takeOwnership(_instance.handle());
}
return _instance;
}
/**
* Initializes a {@code GPathBuf} instance with the given path.
* @param path a file system path
* @return the initialized path builder
*/
public PathBuf initFromPath(@Nullable String path) {
try (var _arena = Arena.ofConfined()) {
MemorySegment _result;
try {
FunctionDescriptor _fdesc = FunctionDescriptor.of(ValueLayout.ADDRESS,
ValueLayout.ADDRESS, ValueLayout.ADDRESS);
_result = (MemorySegment) Interop.downcallHandle("g_path_buf_init_from_path", _fdesc, false)
.invokeExact(handle(),
(MemorySegment) (path == null ? MemorySegment.NULL : Interop.allocateNativeString(path, _arena)));
} catch (Throwable _err) {
throw new AssertionError("Unexpected exception occurred: ", _err);
}
var _instance = MemorySegment.NULL.equals(_result) ? null : new PathBuf(_result);
if (_instance != null) {
MemoryCleaner.takeOwnership(_instance.handle());
}
return _instance;
}
}
/**
* Removes the last element of the path buffer.
*
* If there is only one element in the path buffer (for example, {@code /} on
* Unix-like operating systems or the drive on Windows systems), it will
* not be removed and {@code false} will be returned instead.
*
{@code
* GPathBuf buf, cmp;
*
* g_path_buf_init_from_path (&buf, "/bin/sh");
*
* g_path_buf_pop (&buf);
* g_path_buf_init_from_path (&cmp, "/bin");
* g_assert_true (g_path_buf_equal (&buf, &cmp));
* g_path_buf_clear (&cmp);
*
* g_path_buf_pop (&buf);
* g_path_buf_init_from_path (&cmp, "/");
* g_assert_true (g_path_buf_equal (&buf, &cmp));
* g_path_buf_clear (&cmp);
*
* g_path_buf_clear (&buf);
* }
* @return {@code TRUE} if the buffer was modified and {@code FALSE} otherwise
*/
public boolean pop() {
int _result;
try {
FunctionDescriptor _fdesc = FunctionDescriptor.of(ValueLayout.JAVA_INT,
ValueLayout.ADDRESS);
_result = (int) Interop.downcallHandle("g_path_buf_pop", _fdesc, false).invokeExact(
handle());
} catch (Throwable _err) {
throw new AssertionError("Unexpected exception occurred: ", _err);
}
return _result != 0;
}
/**
* Extends the given path buffer with {@code path}.
*
* If {@code path} is absolute, it replaces the current path.
*
* If {@code path} contains a directory separator, the buffer is extended by
* as many elements the path provides.
*
* On Windows, both forward slashes and backslashes are treated as
* directory separators. On other platforms, {@code G_DIR_SEPARATOR_S} is the
* only directory separator.
*
{@code
* GPathBuf buf, cmp;
*
* g_path_buf_init_from_path (&buf, "/tmp");
* g_path_buf_push (&buf, ".X11-unix/X0");
* g_path_buf_init_from_path (&cmp, "/tmp/.X11-unix/X0");
* g_assert_true (g_path_buf_equal (&buf, &cmp));
* g_path_buf_clear (&cmp);
*
* g_path_buf_push (&buf, "/etc/locale.conf");
* g_path_buf_init_from_path (&cmp, "/etc/locale.conf");
* g_assert_true (g_path_buf_equal (&buf, &cmp));
* g_path_buf_clear (&cmp);
*
* g_path_buf_clear (&buf);
* }
* @param path a path
* @return the same pointer to {@code buf}, for convenience
*/
public PathBuf push(String path) {
try (var _arena = Arena.ofConfined()) {
MemorySegment _result;
try {
FunctionDescriptor _fdesc = FunctionDescriptor.of(ValueLayout.ADDRESS,
ValueLayout.ADDRESS, ValueLayout.ADDRESS);
_result = (MemorySegment) Interop.downcallHandle("g_path_buf_push", _fdesc, false)
.invokeExact(handle(),
(MemorySegment) (path == null ? MemorySegment.NULL : Interop.allocateNativeString(path, _arena)));
} catch (Throwable _err) {
throw new AssertionError("Unexpected exception occurred: ", _err);
}
var _instance = MemorySegment.NULL.equals(_result) ? null : new PathBuf(_result);
if (_instance != null) {
MemoryCleaner.takeOwnership(_instance.handle());
}
return _instance;
}
}
/**
* Adds an extension to the file name in the path buffer.
*
* If {@code extension} is {@code NULL}, the extension will be unset.
*
* If the path buffer does not have a file name set, this function returns
* {@code FALSE} and leaves the path buffer unmodified.
* @param extension the file extension
* @return {@code TRUE} if the extension was replaced, and {@code FALSE} otherwise
*/
public boolean setExtension(@Nullable String extension) {
try (var _arena = Arena.ofConfined()) {
int _result;
try {
FunctionDescriptor _fdesc = FunctionDescriptor.of(ValueLayout.JAVA_INT,
ValueLayout.ADDRESS, ValueLayout.ADDRESS);
_result = (int) Interop.downcallHandle("g_path_buf_set_extension", _fdesc, false)
.invokeExact(handle(),
(MemorySegment) (extension == null ? MemorySegment.NULL : Interop.allocateNativeString(extension, _arena)));
} catch (Throwable _err) {
throw new AssertionError("Unexpected exception occurred: ", _err);
}
return _result != 0;
}
}
/**
* Sets the file name of the path.
*
* If the path buffer is empty, the filename is left unset and this
* function returns {@code FALSE}.
*
* If the path buffer only contains the root element (on Unix-like operating
* systems) or the drive (on Windows), this is the equivalent of pushing
* the new {@code file_name}.
*
* If the path buffer contains a path, this is the equivalent of
* popping the path buffer and pushing {@code file_name}, creating a
* sibling of the original path.
*
{@code
* GPathBuf buf, cmp;
*
* g_path_buf_init_from_path (&buf, "/");
*
* g_path_buf_set_filename (&buf, "bar");
* g_path_buf_init_from_path (&cmp, "/bar");
* g_assert_true (g_path_buf_equal (&buf, &cmp));
* g_path_buf_clear (&cmp);
*
* g_path_buf_set_filename (&buf, "baz.txt");
* g_path_buf_init_from_path (&cmp, "/baz.txt");
* g_assert_true (g_path_buf_equal (&buf, &cmp);
* g_path_buf_clear (&cmp);
*
* g_path_buf_clear (&buf);
* }
* @param fileName the file name in the path
* @return {@code TRUE} if the file name was replaced, and {@code FALSE} otherwise
*/
public boolean setFilename(String fileName) {
try (var _arena = Arena.ofConfined()) {
int _result;
try {
FunctionDescriptor _fdesc = FunctionDescriptor.of(ValueLayout.JAVA_INT,
ValueLayout.ADDRESS, ValueLayout.ADDRESS);
_result = (int) Interop.downcallHandle("g_path_buf_set_filename", _fdesc, false)
.invokeExact(handle(),
(MemorySegment) (fileName == null ? MemorySegment.NULL : Interop.allocateNativeString(fileName, _arena)));
} catch (Throwable _err) {
throw new AssertionError("Unexpected exception occurred: ", _err);
}
return _result != 0;
}
}
/**
* Retrieves the built path from the path buffer.
*
* On Windows, the result contains backslashes as directory separators,
* even if forward slashes were used in input.
*
* If the path buffer is empty, this function returns {@code NULL}.
* @return the path
*/
public String toPath() {
MemorySegment _result;
try {
FunctionDescriptor _fdesc = FunctionDescriptor.of(ValueLayout.ADDRESS,
ValueLayout.ADDRESS);
_result = (MemorySegment) Interop.downcallHandle("g_path_buf_to_path", _fdesc, false)
.invokeExact(handle());
} catch (Throwable _err) {
throw new AssertionError("Unexpected exception occurred: ", _err);
}
return Interop.getStringFrom(_result, true);
}
}