Pointer (gradle-javacpp-plugin 1.0.11 API)

java.lang.Object
- org.bytedeco.javacpp.Pointer

All Implemented Interfaces:

java.lang.AutoCloseable

Direct Known Subclasses:

BooleanPointer, BoolPointer, BytePointer, CharPointer, CLongPointer, DoublePointer, FloatPointer, FunctionPointer, IntPointer, LongPointer, PointerPointer, ShortPointer, SizeTPointer
```
@Properties(inherit=javacpp.class)
public class Pointer
extends java.lang.Object
implements java.lang.AutoCloseable
```
All peer classes to native types must be descended from Pointer, the topmost class. It can be thought as mapping the native C++ void*, which can point to any struct, class, or union. All Pointer classes get parsed by Generator to produce proper wrapping JNI code, but this base class also provides functionality to access native array elements as well as utility methods and classes to let users benefit not only from from garbage collection, but also the try-with-resources statement, since it implements the AutoCloseable interface.
It is also possible to use a PointerScope to keep track of a group of Pointer objects, and have them deallocated in a transparent but deterministic manner.
For examples of subclasses, please refer to the following:

See Also:

BytePointer, ShortPointer, IntPointer, LongPointer, FloatPointer, DoublePointer, CharPointer, PointerPointer, BoolPointer, CLongPointer, SizeTPointer

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`protected static class`	`Pointer.CustomDeallocator` A `Pointer.Deallocator` that calls, during garbage collection, a method with signature `static void deallocate()` from the Pointer object passed to the constructor and that accepts it as argument.
`protected static interface`	`Pointer.Deallocator` The interface to implement to produce a Deallocator usable by Pointer.
`protected static class`	`Pointer.NativeDeallocator` A `Pointer.Deallocator` that calls, during garbage collection, a native function.
`protected static interface`	`Pointer.ReferenceCounter`

Field Summary

Fields
Modifier and Type	Field and Description
`protected long`	`address` The native address of this Pointer, which can be an array.
`protected long`	`capacity` The number of elements contained in this native array, or 0 if unknown.
`protected long`	`limit` The index of the first element that should not be accessed, or 0 if unknown.
`protected long`	`position` The index of the element of a native array that should be accessed.

Constructor Summary

Constructors
Constructor and Description
`Pointer()` Default constructor that does nothing.
`Pointer(java.nio.Buffer b)` Copies the address, position, limit, and capacity of a direct NIO `Buffer`.
`Pointer(Pointer p)` Copies the address, position, limit, and capacity of another Pointer.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`long`	`address()` Returns `address`.
`java.nio.Buffer`	`asBuffer()` Same as `asByteBuffer()`, but can be overridden to return subclasses of Buffer.
`java.nio.ByteBuffer`	`asByteBuffer()` Returns a ByteBuffer covering the memory space from this.position to this.limit.
`static long`	`availablePhysicalBytes()` Returns the amount of physical memory that is free according to the operating system, or 0 if unknown.
`static Pointer`	`calloc(long n, long size)`
`long`	`capacity()` Returns `capacity`.
`<P extends Pointer> P`	`capacity(long capacity)` Sets the capacity and returns this.
`void`	`close()` Calls `releaseReference()`.
`void`	`deallocate()` Calls `deallocate(true)`.
`void`	`deallocate(boolean deallocate)` Explicitly manages native memory without waiting after the garbage collector.
`static void`	`deallocateReferences()` Clears, deallocates, and removes all garbage collected objects from the `referenceQueue`.
`protected Pointer.Deallocator`	`deallocator()` Returns `deallocator`.
`protected <P extends Pointer> P`	`deallocator(Pointer.Deallocator deallocator)` Sets the deallocator and returns this.
`boolean`	`equals(java.lang.Object obj)` Checks for equality with argument.
`<P extends Pointer> P`	`fill(int b)` Calls in effect `memset(address + position, b, length)`, where `length = sizeof() * (limit - position)`.
`static java.lang.String`	`formatBytes(long bytes)` Truncates and formats the number of bytes to a human readable string ending with "T", "G", "M", or "K" (as multiples of 1024).
`static void`	`free(Pointer p)`
`int`	`hashCode()` Returns `(int)address`.
`boolean`	`isNull()` Returns `address == 0`.
`static boolean`	`isNull(Pointer p)` Returns `p == null \|\| p.address == 0`.
`long`	`limit()` Returns `limit`.
`<P extends Pointer> P`	`limit(long limit)` Sets the limit and returns this.
`static Pointer`	`malloc(long size)`
`static long`	`maxBytes()` Returns `maxBytes`, the maximum amount of memory allowed to be tracked.
`static long`	`maxPhysicalBytes()` Returns `maxPhysicalBytes`, the maximum amount of physical memory that should be used.
`static Pointer`	`memchr(Pointer p, int ch, long size)`
`static int`	`memcmp(Pointer p1, Pointer p2, long size)`
`static Pointer`	`memcpy(Pointer dst, Pointer src, long size)`
`static Pointer`	`memmove(Pointer dst, Pointer src, long size)`
`static Pointer`	`memset(Pointer dst, int ch, long size)`
`int`	`offsetof(java.lang.String member)` Returns `Loader.offsetof(getClass(), member)` or -1 on error.
`static long`	`parseBytes(java.lang.String string, long relativeMultiple)` Returns the amount of bytes for a number possibly ending with "%", "t", "g", m", or "k" (as multiples of 1024).
`static long`	`physicalBytes()` Returns the amount of physical memory currently used by the whole process, or 0 if unknown.
`long`	`position()` Returns `position`.
`<P extends Pointer> P`	`position(long position)` Sets the position and returns this.
`<P extends Pointer> P`	`put(Pointer p)` Calls in effect `memcpy(this.address + this.position, p.address + p.position, length)`, where `length = sizeof(p) * (p.limit - p.position)`.
`static Pointer`	`realloc(Pointer p, long size)`
`int`	`referenceCount()` Returns `Pointer.ReferenceCounter.count()` or -1 if no deallocator has been set.
`boolean`	`releaseReference()` Calls `Pointer.ReferenceCounter.release()`, decrementing the reference count by 1, in turn deallocating this Pointer when the count drops to 0.
`<P extends Pointer> P`	`retainReference()` Calls `Pointer.ReferenceCounter.retain()`, incrementing the reference count by 1.
`void`	`setNull()` Sets `address` to 0.
`int`	`sizeof()` Returns 1 for Pointer or BytePointer else `Loader.sizeof(getClass())` or -1 on error.
`java.lang.String`	`toString()` Returns a `String` representation of `address`, `position`, `limit`, `capacity`, and `deallocator`.
`static long`	`totalBytes()` Returns `DeallocatorReference#totalBytes`, current amount of memory tracked by deallocators.
`static long`	`totalPhysicalBytes()` Returns the amount of physical memory installed according to the operating system, or 0 if unknown.
`protected static <P extends Pointer> P`	`withDeallocator(P p)` A utility method to register easily a `Pointer.CustomDeallocator` with a Pointer.
`<P extends Pointer> P`	`zero()` Returns `fill(0)`.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
 - address
```
protected long address
```
 The native address of this Pointer, which can be an array.
 - position
```
protected long position
```
 The index of the element of a native array that should be accessed.
 - limit
```
protected long limit
```
 The index of the first element that should not be accessed, or 0 if unknown.
 - capacity
```
protected long capacity
```
 The number of elements contained in this native array, or 0 if unknown.
- Constructor Detail
 - Pointer
```
public Pointer()
```
 Default constructor that does nothing.
 - Pointer
```
public Pointer(Pointer p)
```
 Copies the address, position, limit, and capacity of another Pointer. Also keeps a reference to it to prevent its memory from getting deallocated.
 This copy constructor basically acts as a reinterpret_cast, at least on plain old data (POD) struct, so we need to be careful with it.
 
 Parameters:
 
 p - the other Pointer to reference
 - Pointer
```
public Pointer(java.nio.Buffer b)
```
 Copies the address, position, limit, and capacity of a direct NIO Buffer. Also keeps a reference to it to prevent its memory from getting deallocated.
 
 Parameters:
 
 b - the Buffer object to reference
- Method Detail
 - withDeallocator
```
protected static  P withDeallocator(P p)
```
 A utility method to register easily a Pointer.CustomDeallocator with a Pointer.
 
 Parameters:
 
 p - the Pointer with which to register the deallocator
 
 Returns:
 
 the Pointer
 - formatBytes
```
public static java.lang.String formatBytes(long bytes)
```
 Truncates and formats the number of bytes to a human readable string ending with "T", "G", "M", or "K" (as multiples of 1024).
 - parseBytes
```
public static long parseBytes(java.lang.String string,
 long relativeMultiple)
 throws java.lang.NumberFormatException
```
 Returns the amount of bytes for a number possibly ending with "%", "t", "g", m", or "k" (as multiples of 1024). May also be suffixed with an optional "b", where all letters are case-insensitive.
 
 Parameters:
 
 string - to parse
 
 relativeMultiple - to use in the case of "%", which is divided by 100
 
 Returns:
 
 the amount of bytes
 
 Throws:
 
 java.lang.NumberFormatException
 - deallocateReferences
```
public static void deallocateReferences()
```
 Clears, deallocates, and removes all garbage collected objects from the referenceQueue.
 - maxBytes
```
public static long maxBytes()
```
 Returns maxBytes, the maximum amount of memory allowed to be tracked.
 - totalBytes
```
public static long totalBytes()
```
 Returns DeallocatorReference#totalBytes, current amount of memory tracked by deallocators.
 - maxPhysicalBytes
```
public static long maxPhysicalBytes()
```
 Returns maxPhysicalBytes, the maximum amount of physical memory that should be used.
 - physicalBytes
```
@Name(value="JavaCPP_physicalBytes")
public static long physicalBytes()
```
 Returns the amount of physical memory currently used by the whole process, or 0 if unknown. Also known as "resident set size" (Linux, Mac OS X, etc) or "working set size" (Windows).
 - totalPhysicalBytes
```
@Name(value="JavaCPP_totalPhysicalBytes")
public static long totalPhysicalBytes()
```
 Returns the amount of physical memory installed according to the operating system, or 0 if unknown. It should not be possible for physicalBytes() to go over this value.
 - availablePhysicalBytes
```
@Name(value="JavaCPP_availablePhysicalBytes")
public static long availablePhysicalBytes()
```
 Returns the amount of physical memory that is free according to the operating system, or 0 if unknown.
 - isNull
```
public static boolean isNull(Pointer p)
```
 Returns p == null || p.address == 0.
 - isNull
```
public boolean isNull()
```
 Returns address == 0.
 - setNull
```
public void setNull()
```
 Sets address to 0.
 - address
```
public long address()
```
 Returns address.
 - position
```
public long position()
```
 Returns position.
 - position
```
public  P position(long position)
```
 Sets the position and returns this. That makes the array.position(i) statement sort of equivalent to the array[i] statement in C++.
 
 Parameters:
 
 position - the new position
 
 Returns:
 
 this
 - limit
```
public long limit()
```
 Returns limit.
 - limit
```
public  P limit(long limit)
```
 Sets the limit and returns this. Used to limit the size of an operation on this object.
 
 Parameters:
 
 limit - the new limit
 
 Returns:
 
 this
 - capacity
```
public long capacity()
```
 Returns capacity.
 - capacity
```
public  P capacity(long capacity)
```
 Sets the capacity and returns this. Should not be called more than once after allocation.
 
 Parameters:
 
 capacity - the new capacity
 
 Returns:
 
 this
 - deallocator
```
protected Pointer.Deallocator deallocator()
```
 Returns deallocator.
 - deallocator
```
protected  P deallocator(Pointer.Deallocator deallocator)
```
 Sets the deallocator and returns this. Also clears current deallocator if not null. That is, it deallocates previously allocated memory. Should not be called more than once after allocation.
 
 Parameters:
 
 deallocator - the new deallocator
 
 Returns:
 
 this
 - close
```
public void close()
```
 Calls releaseReference().
 
 Specified by:
 
 close in interface java.lang.AutoCloseable
 - deallocate
```
public void deallocate()
```
 Calls deallocate(true).
 - deallocate
```
public void deallocate(boolean deallocate)
```
 Explicitly manages native memory without waiting after the garbage collector. Has no effect if no deallocator was previously set with deallocator(Deallocator).
 
 Parameters:
 
 deallocate - if true, deallocates, else does not, but disables garbage collection
 - retainReference
```
public  P retainReference()
```
 Calls Pointer.ReferenceCounter.retain(), incrementing the reference count by 1. Has no effect if no deallocator was previously set with deallocator(Deallocator).
 
 Returns:
 
 this
 - releaseReference
```
public boolean releaseReference()
```
 Calls Pointer.ReferenceCounter.release(), decrementing the reference count by 1, in turn deallocating this Pointer when the count drops to 0. Has no effect if no deallocator was previously set with deallocator(Deallocator).
 
 Returns:
 
 true when the count drops to 0 and deallocation has occurred
 - referenceCount
```
public int referenceCount()
```
 Returns Pointer.ReferenceCounter.count() or -1 if no deallocator has been set.
 - offsetof
```
public int offsetof(java.lang.String member)
```
 Returns Loader.offsetof(getClass(), member) or -1 on error.
 - sizeof
```
public int sizeof()
```
 Returns 1 for Pointer or BytePointer else Loader.sizeof(getClass()) or -1 on error.
 - asByteBuffer
```
public java.nio.ByteBuffer asByteBuffer()
```
 Returns a ByteBuffer covering the memory space from this.position to this.limit. If limit == 0, it uses position + 1 instead. The way the methods were designed allows constructs such as this.position(13).limit(42).asByteBuffer().
 
 Returns:
 
 the direct NIO ByteBuffer created
 - asBuffer
```
public java.nio.Buffer asBuffer()
```
 Same as asByteBuffer(), but can be overridden to return subclasses of Buffer.
 
 Returns:
 
 asByteBuffer()
 
 See Also:
 
 BytePointer.asBuffer(), ShortPointer.asBuffer(), IntPointer.asBuffer(), LongPointer.asBuffer(), FloatPointer.asBuffer(), DoublePointer.asBuffer(), CharPointer.asBuffer()
 - malloc
```
public static Pointer malloc(long size)
```
 - calloc
```
public static Pointer calloc(long n,
 long size)
```
 - realloc
```
public static Pointer realloc(Pointer p,
 long size)
```
 - free
```
public static void free(Pointer p)
```
 - memchr
```
public static Pointer memchr(Pointer p,
 int ch,
 long size)
```
 - memcmp
```
public static int memcmp(Pointer p1,
 Pointer p2,
 long size)
```
 - memcpy
```
public static Pointer memcpy(Pointer dst,
 Pointer src,
 long size)
```
 - memmove
```
public static Pointer memmove(Pointer dst,
 Pointer src,
 long size)
```
 - memset
```
public static Pointer memset(Pointer dst,
 int ch,
 long size)
```
 - put
```
public  P put(Pointer p)
```
 Calls in effect memcpy(this.address + this.position, p.address + p.position, length), where length = sizeof(p) * (p.limit - p.position). If limit == 0, it uses position + 1 instead. The way the methods were designed allows constructs such as this.position(0).put(p.position(13).limit(42)).
 
 Parameters:
 
 p - the Pointer from which to copy memory
 
 Returns:
 
 this
 - fill
```
public  P fill(int b)
```
 Calls in effect memset(address + position, b, length), where length = sizeof() * (limit - position). If limit == 0, it uses position + 1 instead. The way the methods were designed allows constructs such as this.position(0).limit(13).fill(42);
 
 Parameters:
 
 b - the byte value to fill the memory with
 
 Returns:
 
 this
 - zero
```
public  P zero()
```
 Returns fill(0).
 - equals
```
public boolean equals(java.lang.Object obj)
```
 Checks for equality with argument. Defines obj to be equal if (obj == null && this.address == 0) || (obj.address == this.address && obj.position == this.position), and the classes are the same, unless one of them in Pointer itself.
 
 Overrides:
 
 equals in class java.lang.Object
 
 Parameters:
 
 obj - the object to compare this Pointer to
 
 Returns:
 
 true if obj is equal
 - hashCode
```
public int hashCode()
```
 Returns (int)address.
 
 Overrides:
 
 hashCode in class java.lang.Object
 - toString
```
public java.lang.String toString()
```
 Returns a String representation of address, position, limit, capacity, and deallocator.
 
 Overrides:
 
 toString in class java.lang.Object

Class Pointer

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

address

position

limit

capacity

Constructor Detail

Pointer

Pointer

Pointer

Method Detail

withDeallocator

formatBytes

parseBytes

deallocateReferences

maxBytes

totalBytes

maxPhysicalBytes

physicalBytes

totalPhysicalBytes

availablePhysicalBytes

isNull

isNull

setNull

address

position

position

limit

limit

capacity

capacity

deallocator

deallocator

close

deallocate

deallocate

retainReference

releaseReference

referenceCount

offsetof

sizeof

asByteBuffer

asBuffer

malloc

calloc

realloc

free

memchr

memcmp

memcpy

memmove

memset

put

fill

zero

equals

hashCode

toString