ONNX Runtime
Loading...
Searching...
No Matches
Ort::Value Struct Reference

Wrapper around OrtValue. More...

#include <onnxruntime_cxx_api.h>

Inheritance diagram for Ort::Value:
Ort::detail::ValueImpl< OrtValue > Ort::detail::ConstValueImpl< T > Ort::detail::Base< T >

Public Types

using Base = detail::ValueImpl< OrtValue >
 
using OrtSparseValuesParam = detail::OrtSparseValuesParam
 
using Shape = detail::Shape
 
- Public Types inherited from Ort::detail::ValueImpl< OrtValue >
using B = ConstValueImpl< OrtValue >
 
using B = Base< OrtValue >
 
- Public Types inherited from Ort::detail::ConstValueImpl< T >
using B = Base< T >
 
- Public Types inherited from Ort::detail::Base< T >
using contained_type = T
 

Public Member Functions

 Value (std::nullptr_t)
 Create an empty Value object, must be assigned a valid one to be used.
 
 Value (Value &&)=default
 
Valueoperator= (Value &&)=default
 
ConstValue GetConst () const
 
UnownedValue GetUnowned () const
 
- Public Member Functions inherited from Ort::detail::ValueImpl< OrtValue >
R * GetTensorMutableData ()
 Returns a non-const typed pointer to an OrtValue/Tensor contained buffer No type checking is performed, the caller must ensure the type matches the tensor type.
 
void * GetTensorMutableRawData ()
 Returns a non-typed non-const pointer to a tensor contained data.
 
R & At (const std::vector< int64_t > &location)
 
void FillStringTensor (const char *const *s, size_t s_len)
 Set all strings at once in a string tensor.
 
void FillStringTensorElement (const char *s, size_t index)
 Set a single string in a string tensor.
 
char * GetResizedStringTensorElementBuffer (size_t index, size_t buffer_length)
 Allocate if necessary and obtain a pointer to a UTF-8 encoded string element buffer indexed by the flat element index, of the specified length.
 
void UseCooIndices (int64_t *indices_data, size_t indices_num)
 Supplies COO format specific indices and marks the contained sparse tensor as being a COO format tensor. Values are supplied with a CreateSparseTensor() API. The supplied indices are not copied and the user allocated buffers lifespan must eclipse that of the OrtValue. The location of the indices is assumed to be the same as specified by OrtMemoryInfo argument at the creation time.
 
void UseCsrIndices (int64_t *inner_data, size_t inner_num, int64_t *outer_data, size_t outer_num)
 Supplies CSR format specific indices and marks the contained sparse tensor as being a CSR format tensor. Values are supplied with a CreateSparseTensor() API. The supplied indices are not copied and the user allocated buffers lifespan must eclipse that of the OrtValue. The location of the indices is assumed to be the same as specified by OrtMemoryInfo argument at the creation time.
 
void UseBlockSparseIndices (const Shape &indices_shape, int32_t *indices_data)
 Supplies BlockSparse format specific indices and marks the contained sparse tensor as being a BlockSparse format tensor. Values are supplied with a CreateSparseTensor() API. The supplied indices are not copied and the user allocated buffers lifespan must eclipse that of the OrtValue. The location of the indices is assumed to be the same as specified by OrtMemoryInfo argument at the creation time.
 
void FillSparseTensorCoo (const OrtMemoryInfo *data_mem_info, const OrtSparseValuesParam &values_param, const int64_t *indices_data, size_t indices_num)
 The API will allocate memory using the allocator instance supplied to the CreateSparseTensor() API and copy the values and COO indices into it. If data_mem_info specifies that the data is located at difference device than the allocator, a X-device copy will be performed if possible.
 
void FillSparseTensorCsr (const OrtMemoryInfo *data_mem_info, const OrtSparseValuesParam &values, const int64_t *inner_indices_data, size_t inner_indices_num, const int64_t *outer_indices_data, size_t outer_indices_num)
 The API will allocate memory using the allocator instance supplied to the CreateSparseTensor() API and copy the values and CSR indices into it. If data_mem_info specifies that the data is located at difference device than the allocator, a X-device copy will be performed if possible.
 
void FillSparseTensorBlockSparse (const OrtMemoryInfo *data_mem_info, const OrtSparseValuesParam &values, const Shape &indices_shape, const int32_t *indices_data)
 The API will allocate memory using the allocator instance supplied to the CreateSparseTensor() API and copy the values and BlockSparse indices into it. If data_mem_info specifies that the data is located at difference device than the allocator, a X-device copy will be performed if possible.
 
- Public Member Functions inherited from Ort::detail::ConstValueImpl< T >
template<typename R >
void GetOpaqueData (const char *domain, const char *type_name, R &) const
 Obtains a pointer to a user defined data for experimental purposes.
 
bool IsTensor () const
 Returns true if Value is a tensor, false for other types like map/sequence/etc.
 
bool HasValue () const
 
size_t GetCount () const
 < Return true if OrtValue contains data and returns false if the OrtValue is a None
 
Value GetValue (int index, OrtAllocator *allocator) const
 
size_t GetStringTensorDataLength () const
 This API returns a full length of string data contained within either a tensor or a sparse Tensor. For sparse tensor it returns a full length of stored non-empty strings (values). The API is useful for allocating necessary memory and calling GetStringTensorContent().
 
void GetStringTensorContent (void *buffer, size_t buffer_length, size_t *offsets, size_t offsets_count) const
 The API copies all of the UTF-8 encoded string data contained within a tensor or a sparse tensor into a supplied buffer. Use GetStringTensorDataLength() to find out the length of the buffer to allocate. The user must also allocate offsets buffer with the number of entries equal to that of the contained strings.
 
template<typename R >
const R * GetTensorData () const
 Returns a const typed pointer to the tensor contained data. No type checking is performed, the caller must ensure the type matches the tensor type.
 
const void * GetTensorRawData () const
 Returns a non-typed pointer to a tensor contained data.
 
TypeInfo GetTypeInfo () const
 The API returns type information for data contained in a tensor. For sparse tensors it returns type information for contained non-zero values. It returns dense shape for sparse tensors.
 
TensorTypeAndShapeInfo GetTensorTypeAndShapeInfo () const
 The API returns type information for data contained in a tensor. For sparse tensors it returns type information for contained non-zero values. It returns dense shape for sparse tensors.
 
ConstMemoryInfo GetTensorMemoryInfo () const
 This API returns information about the memory allocation used to hold data.
 
void GetStringTensorElement (size_t buffer_length, size_t element_index, void *buffer) const
 The API copies UTF-8 encoded bytes for the requested string element contained within a tensor or a sparse tensor into a provided buffer. Use GetStringTensorElementLength() to obtain the length of the buffer to allocate.
 
std::string GetStringTensorElement (size_t element_index) const
 Returns string tensor UTF-8 encoded string element. Use of this API is recommended over GetStringTensorElement() that takes void* buffer pointer.
 
size_t GetStringTensorElementLength (size_t element_index) const
 The API returns a byte length of UTF-8 encoded string element contained in either a tensor or a spare tensor values.
 
OrtSparseFormat GetSparseFormat () const
 The API returns the sparse data format this OrtValue holds in a sparse tensor. If the sparse tensor was not fully constructed, i.e. Use*() or Fill*() API were not used the value returned is ORT_SPARSE_UNDEFINED.
 
TensorTypeAndShapeInfo GetSparseTensorValuesTypeAndShapeInfo () const
 The API returns type and shape information for stored non-zero values of the sparse tensor. Use GetSparseTensorValues() to obtain values buffer pointer.
 
TensorTypeAndShapeInfo GetSparseTensorIndicesTypeShapeInfo (OrtSparseIndicesFormat format) const
 The API returns type and shape information for the specified indices. Each supported indices have their own enum values even if a give format has more than one kind of indices. Use GetSparseTensorIndicesData() to obtain pointer to indices buffer.
 
template<typename R >
const R * GetSparseTensorIndicesData (OrtSparseIndicesFormat indices_format, size_t &num_indices) const
 The API retrieves a pointer to the internal indices buffer. The API merely performs a convenience data type casting on the return type pointer. Make sure you are requesting the right type, use GetSparseTensorIndicesTypeShapeInfo();.
 
bool IsSparseTensor () const
 Returns true if the OrtValue contains a sparse tensor.
 
template<typename R >
const R * GetSparseTensorValues () const
 The API returns a pointer to an internal buffer of the sparse tensor containing non-zero values. The API merely does casting. Make sure you are requesting the right data type by calling GetSparseTensorValuesTypeAndShapeInfo() first.
 
- Public Member Functions inherited from Ort::detail::Base< T >
constexpr Base ()=default
 
constexpr Base (contained_type *p) noexcept
 
 ~Base ()
 
 Base (const Base &)=delete
 
Baseoperator= (const Base &)=delete
 
 Base (Base &&v) noexcept
 
Baseoperator= (Base &&v) noexcept
 
constexpr operator contained_type * () const noexcept
 
contained_typerelease ()
 Relinquishes ownership of the contained C object pointer The underlying object is not destroyed.
 

Static Public Member Functions

template<typename T >
static Value CreateTensor (const OrtMemoryInfo *info, T *p_data, size_t p_data_element_count, const int64_t *shape, size_t shape_len)
 Creates a tensor with a user supplied buffer. Wraps OrtApi::CreateTensorWithDataAsOrtValue.
 
static Value CreateTensor (const OrtMemoryInfo *info, void *p_data, size_t p_data_byte_count, const int64_t *shape, size_t shape_len, ONNXTensorElementDataType type)
 Creates a tensor with a user supplied buffer. Wraps OrtApi::CreateTensorWithDataAsOrtValue.
 
template<typename T >
static Value CreateTensor (OrtAllocator *allocator, const int64_t *shape, size_t shape_len)
 Creates an OrtValue with a tensor using a supplied OrtAllocator. Wraps OrtApi::CreateTensorAsOrtValue. This overload will allocate the buffer for the tensor according to the supplied shape and data type. The allocated buffer will be owned by the returned OrtValue and will be freed when the OrtValue is released. The input data would need to be copied into the allocated buffer. This API is not suitable for strings.
 
static Value CreateTensor (OrtAllocator *allocator, const int64_t *shape, size_t shape_len, ONNXTensorElementDataType type)
 Creates an OrtValue with a tensor using the supplied OrtAllocator. Wraps OrtApi::CreateTensorAsOrtValue. The allocated buffer will be owned by the returned OrtValue and will be freed when the OrtValue is released. The input data would need to be copied into the allocated buffer. This API is not suitable for strings.
 
static Value CreateMap (const Value &keys, const Value &values)
 Creates an OrtValue with a Map Onnx type representation. The API would ref-count the supplied OrtValues and they will be released when the returned OrtValue is released. The caller may release keys and values after the call returns.
 
static Value CreateSequence (const std::vector< Value > &values)
 Creates an OrtValue with a Sequence Onnx type representation. The API would ref-count the supplied OrtValues and they will be released when the returned OrtValue is released. The caller may release the values after the call returns.
 
template<typename T >
static Value CreateOpaque (const char *domain, const char *type_name, const T &value)
 Creates an OrtValue wrapping an Opaque type. This is used for experimental support of non-tensor types.
 
template<typename T >
static Value CreateSparseTensor (const OrtMemoryInfo *info, T *p_data, const Shape &dense_shape, const Shape &values_shape)
 This is a simple forwarding method to the other overload that helps deducing data type enum value from the type of the buffer.
 
static Value CreateSparseTensor (const OrtMemoryInfo *info, void *p_data, const Shape &dense_shape, const Shape &values_shape, ONNXTensorElementDataType type)
 Creates an OrtValue instance containing SparseTensor. This constructs a sparse tensor that makes use of user allocated buffers. It does not make copies of the user provided data and does not modify it. The lifespan of user provided buffers should eclipse the life span of the resulting OrtValue. This call constructs an instance that only contain a pointer to non-zero values. To fully populate the sparse tensor call Use<Format>Indices() API below to supply a sparse format specific indices. This API is not suitable for string data. Use CreateSparseTensor() with allocator specified so strings can be properly copied into the allocated buffer.
 
template<typename T >
static Value CreateSparseTensor (OrtAllocator *allocator, const Shape &dense_shape)
 This is a simple forwarding method to the below CreateSparseTensor. This helps to specify data type enum in terms of C++ data type. Use CreateSparseTensor<T>
 
static Value CreateSparseTensor (OrtAllocator *allocator, const Shape &dense_shape, ONNXTensorElementDataType type)
 Creates an instance of OrtValue containing sparse tensor. The created instance has no data. The data must be supplied by on of the FillSparseTensor<Format>() methods that take both non-zero values and indices. The data will be copied into a buffer that would be allocated using the supplied allocator. Use this API to create OrtValues that contain sparse tensors with all supported data types including strings.
 

Additional Inherited Members

- Protected Attributes inherited from Ort::detail::Base< T >
contained_typep_ {}
 

Detailed Description

Wrapper around OrtValue.

Member Typedef Documentation

◆ Base

◆ OrtSparseValuesParam

◆ Shape

Constructor & Destructor Documentation

◆ Value() [1/2]

Ort::Value::Value ( std::nullptr_t  )
inlineexplicit

Create an empty Value object, must be assigned a valid one to be used.

◆ Value() [2/2]

Ort::Value::Value ( Value &&  )
default

Member Function Documentation

◆ CreateMap()

static Value Ort::Value::CreateMap ( const Value keys,
const Value values 
)
static

Creates an OrtValue with a Map Onnx type representation. The API would ref-count the supplied OrtValues and they will be released when the returned OrtValue is released. The caller may release keys and values after the call returns.

Parameters
keysan OrtValue containing a tensor with primitive data type keys.
valuesan OrtValue that may contain a tensor. Ort currently supports only primitive data type values. Wraps OrtApi::CreateValue

◆ CreateOpaque()

template<typename T >
static Value Ort::Value::CreateOpaque ( const char *  domain,
const char *  type_name,
const T &  value 
)
static

Creates an OrtValue wrapping an Opaque type. This is used for experimental support of non-tensor types.

Template Parameters
T- the type of the value.
Parameters
domain- zero terminated utf-8 string. Domain of the type.
type_name- zero terminated utf-8 string. Name of the type.
value- the value to be wrapped. Wraps OrtApi::CreateOpaqueValue

◆ CreateSequence()

static Value Ort::Value::CreateSequence ( const std::vector< Value > &  values)
static

Creates an OrtValue with a Sequence Onnx type representation. The API would ref-count the supplied OrtValues and they will be released when the returned OrtValue is released. The caller may release the values after the call returns.

Parameters
valuesa vector of OrtValues that must have the same Onnx value type. Wraps OrtApi::CreateValue

◆ CreateSparseTensor() [1/4]

template<typename T >
static Value Ort::Value::CreateSparseTensor ( const OrtMemoryInfo info,
T *  p_data,
const Shape dense_shape,
const Shape values_shape 
)
static

This is a simple forwarding method to the other overload that helps deducing data type enum value from the type of the buffer.

Template Parameters
Tnumeric datatype. This API is not suitable for strings.
Parameters
infoMemory description where the user buffers reside (CPU vs GPU etc)
p_datapointer to the user supplied buffer, use nullptr for fully sparse tensors
dense_shapea would be dense shape of the tensor
values_shapenon zero values shape. Use a single 0 shape for fully sparse tensors.
Returns

◆ CreateSparseTensor() [2/4]

static Value Ort::Value::CreateSparseTensor ( const OrtMemoryInfo info,
void *  p_data,
const Shape dense_shape,
const Shape values_shape,
ONNXTensorElementDataType  type 
)
static

Creates an OrtValue instance containing SparseTensor. This constructs a sparse tensor that makes use of user allocated buffers. It does not make copies of the user provided data and does not modify it. The lifespan of user provided buffers should eclipse the life span of the resulting OrtValue. This call constructs an instance that only contain a pointer to non-zero values. To fully populate the sparse tensor call Use<Format>Indices() API below to supply a sparse format specific indices. This API is not suitable for string data. Use CreateSparseTensor() with allocator specified so strings can be properly copied into the allocated buffer.

Parameters
infoMemory description where the user buffers reside (CPU vs GPU etc)
p_datapointer to the user supplied buffer, use nullptr for fully sparse tensors
dense_shapea would be dense shape of the tensor
values_shapenon zero values shape. Use a single 0 shape for fully sparse tensors.
typedata type
Returns
Ort::Value instance containing SparseTensor

◆ CreateSparseTensor() [3/4]

template<typename T >
static Value Ort::Value::CreateSparseTensor ( OrtAllocator allocator,
const Shape dense_shape 
)
static

This is a simple forwarding method to the below CreateSparseTensor. This helps to specify data type enum in terms of C++ data type. Use CreateSparseTensor<T>

Template Parameters
Tnumeric data type only. String data enum must be specified explicitly.
Parameters
allocatorallocator to use
dense_shapea would be dense shape of the tensor
Returns
Ort::Value

◆ CreateSparseTensor() [4/4]

static Value Ort::Value::CreateSparseTensor ( OrtAllocator allocator,
const Shape dense_shape,
ONNXTensorElementDataType  type 
)
static

Creates an instance of OrtValue containing sparse tensor. The created instance has no data. The data must be supplied by on of the FillSparseTensor<Format>() methods that take both non-zero values and indices. The data will be copied into a buffer that would be allocated using the supplied allocator. Use this API to create OrtValues that contain sparse tensors with all supported data types including strings.

Parameters
allocatorallocator to use. The allocator lifespan must eclipse that of the resulting OrtValue
dense_shapea would be dense shape of the tensor
typedata type
Returns
an instance of Ort::Value

◆ CreateTensor() [1/4]

template<typename T >
static Value Ort::Value::CreateTensor ( const OrtMemoryInfo info,
T *  p_data,
size_t  p_data_element_count,
const int64_t *  shape,
size_t  shape_len 
)
static

Creates a tensor with a user supplied buffer. Wraps OrtApi::CreateTensorWithDataAsOrtValue.

Template Parameters
TThe numeric datatype. This API is not suitable for strings.
Parameters
infoMemory description of where the p_data buffer resides (CPU vs GPU etc).
p_dataPointer to the data buffer.
p_data_element_countThe number of elements in the data buffer.
shapePointer to the tensor shape dimensions.
shape_lenThe number of tensor shape dimensions.

◆ CreateTensor() [2/4]

static Value Ort::Value::CreateTensor ( const OrtMemoryInfo info,
void *  p_data,
size_t  p_data_byte_count,
const int64_t *  shape,
size_t  shape_len,
ONNXTensorElementDataType  type 
)
static

Creates a tensor with a user supplied buffer. Wraps OrtApi::CreateTensorWithDataAsOrtValue.

Parameters
infoMemory description of where the p_data buffer resides (CPU vs GPU etc).
p_dataPointer to the data buffer.
p_data_byte_countThe number of bytes in the data buffer.
shapePointer to the tensor shape dimensions.
shape_lenThe number of tensor shape dimensions.
typeThe data type.

◆ CreateTensor() [3/4]

template<typename T >
static Value Ort::Value::CreateTensor ( OrtAllocator allocator,
const int64_t *  shape,
size_t  shape_len 
)
static

Creates an OrtValue with a tensor using a supplied OrtAllocator. Wraps OrtApi::CreateTensorAsOrtValue. This overload will allocate the buffer for the tensor according to the supplied shape and data type. The allocated buffer will be owned by the returned OrtValue and will be freed when the OrtValue is released. The input data would need to be copied into the allocated buffer. This API is not suitable for strings.

Template Parameters
TThe numeric datatype. This API is not suitable for strings.
Parameters
allocatorThe allocator to use.
shapePointer to the tensor shape dimensions.
shape_lenThe number of tensor shape dimensions.

◆ CreateTensor() [4/4]

static Value Ort::Value::CreateTensor ( OrtAllocator allocator,
const int64_t *  shape,
size_t  shape_len,
ONNXTensorElementDataType  type 
)
static

Creates an OrtValue with a tensor using the supplied OrtAllocator. Wraps OrtApi::CreateTensorAsOrtValue. The allocated buffer will be owned by the returned OrtValue and will be freed when the OrtValue is released. The input data would need to be copied into the allocated buffer. This API is not suitable for strings.

Parameters
allocatorThe allocator to use.
shapePointer to the tensor shape dimensions.
shape_lenThe number of tensor shape dimensions.
typeThe data type.

◆ GetConst()

ConstValue Ort::Value::GetConst ( ) const
inline

◆ GetUnowned()

UnownedValue Ort::Value::GetUnowned ( ) const
inline

◆ operator=()

Value & Ort::Value::operator= ( Value &&  )
default