Reentrant Classes

Classes
class	ml::SubImage
	This class manages/represents a rectangular 6d image region which is organized linearly in memory. More...
class	ml::TSubImageBox< intT >
	This class defines a rectangular subimage region of standard ML dimensions. More...
class	ml::TSubImage< DATATYPE >
	This template class manages/represents a rectangular 6d image region in memory which is organized linearly. More...
class	ml::DateTime
	Class for performing date/time arithmetics, comparisons and formatting. More...
class	ml::RuntimeDict
	This file declares the class RuntimeDict, which manages a set of instances of class RuntimeTypes. More...
class	ml::RuntimeType
	RuntimeType contains type and inheritance information of a class and a static dictionary with information on all created instances of RuntimeType. More...
File access functions working with valid UTF-8 Unicode file names
ML_UTILS_EXPORT FILE *	MLfopen (const char *fileName, const char *mode)
	Thread-safety: These functions are reentrant.
ML_UTILS_EXPORT MLErrorCode	MLfclose (FILE *file)
	Closes an open file given by descriptor file and returns 0 on success and non zero values on failure.
ML_UTILS_EXPORT MLErrorCode	MLremove (const char *fileName)
	Deletes file with name fileName.
ML_UTILS_EXPORT MLErrorCode	MLrename (const char *oldName, const char *newName)
	Renames a file with name oldName to newName.
ML_UTILS_EXPORT int	MLopen (const char *fileName, int openFlags, int pMode)
	Opens the file with name fileName with the given openFlags, returns a file descriptor or -1 on error.
ML_UTILS_EXPORT MLErrorCode	MLclose (int fileDescriptor)
	Closes an open file given by a the file descriptor fileDescriptor and returns ML_RESULT_OK on success and on failure an MLErrorCode describing the problem.
ML_UTILS_EXPORT int	MLFileExists (const char *fileName)
	Returns 1 if the given with name fileName exists, 0 otherwise or if fileName is NULL.
ML_UTILS_EXPORT char *	MLGetTempPath ()
	Returns the path to the temporary directory of the current user or NULL on failure.
ML_UTILS_EXPORT char *	MLGetNonExistingRandomFileName (const char *prefix)
	Returns a file name which does not exist in the current directory or NULL on failure.
ML_UTILS_EXPORT int	MLFileIsReadable (const char *fileName)
	Returns 1 if the given fileName exists and is readable, 0 otherwise.
ML_UTILS_EXPORT int	MLFileIsWritable (const char *fileName)
	Returns 1 if the given file with name fileName exists and is writable, 0 otherwise.
ML_UTILS_EXPORT MLErrorCode	MLFileWriteStringData (const char *fileName, const char *str)
	Creates, opens, and overwrites the given file with name fileName with the given non NULL, null terminated data string str, and returns ML_RESULT_OK on success or an MLErrorCode describing the problem on failure.
ML_UTILS_EXPORT MLErrorCode	MLFileWriteBinaryData (const char *fileName, const MLuint8 *data, size_t numBytes)
	Creates, opens, and overwrites the given file with name fileName with the given data of a given numBytes, and returns ML_RESULT_OK on success or on failure an MLErrorCode describing the problem.
ML_UTILS_EXPORT MLErrorCode	MLFileWriteBinaryDataAt (int fileDescriptor, MLuint startPosition, const MLuint8 *data, size_t numBytes)
	Overwrites a section of the file given by file descriptor fileDescriptor which must have been opened with mode ML_O_RDWR or ML_O_WRONLY at position startPosition with the given data with numBytes.
ML_UTILS_EXPORT MLErrorCode	MLFileAppendStringData (const char *fileName, const char *strData)
	Appends the given null-terminated string strData to the file given by name fileName, creating a new file if it does not exist.
ML_UTILS_EXPORT MLErrorCode	MLFileAppendBinaryData (const char *fileName, const MLuint8 *data, size_t numBytes)
	Appends numBytes of data given by data to the file given by name fileName, creating a new file if it does not exist.
ML_UTILS_EXPORT MLErrorCode	MLFileAppendBinaryDataWithDescriptor (int fileDescriptor, const MLuint8 *data, size_t numBytes)
	Appends numBytes of data given by data to the file given by file descriptor fileDescriptor which must be valid and indicate a writable file.
ML_UTILS_EXPORT char *	MLFileReadAllAsString (const char *fileName)
	Reads the complete file with a fileName as a string, returns NULL on error.
ML_UTILS_EXPORT MLuint8 *	MLFileReadAllAsBinary (const char *fileName)
	Reads the complete file with a fileName as binary data, returns NULL on error.
ML_UTILS_EXPORT char *	MLFileReadChunkAsString (const char *fileName, MLuint startPosition, MLuint numBytes)
	Reads a string segment starting at startPosition from the file given by fileName as a string and returns NULL on error.
ML_UTILS_EXPORT MLuint8 *	MLFileReadChunkAsBinary (const char *fileName, MLuint startPosition, MLuint numBytes)
	Reads a data segment starting at startPosition from the file given by fileName and returns NULL on error.
ML_UTILS_EXPORT MLuint8 *	MLFileReadChunkAsBinaryFromDesc (int fileDescriptor, MLuint startPosition, MLuint numBytes, int useCurrentPosition)
	Reads a data segment starting at startPosition from the file given by fileDescriptor and returns NULL on error.
ML_UTILS_EXPORT char *	MLFileReadChunkAsStringFromDesc (int fileDescriptor, MLuint startPosition, MLuint numBytes)
	Reads a string segment starting at startingPosition from the file given by fileDescriptor as a string and returns NULL on error.
ML_UTILS_EXPORT MLint	MLFileGetSizeFromDescriptor (int fileDescriptor)
	Returns the size of the file given by the file descriptor fileDescriptor A negative value is returned on any error if fileDescriptor is invalid or on files larger than 2^63-1 bytes.
ML_UTILS_EXPORT MLint	MLFileGetSizeFromName (const char *fileName)
	Returns the size of the file given by the null-terminated file name fileName.
ML_UTILS_EXPORT MLint	MLFileSetBytePos (int fileDescriptor, MLuint position)
	Sets the pointer of a file given by descriptor fileDescriptor to a position and returns the positive position on success and -1 on failure.
ML_UTILS_EXPORT MLint	MLFileGetBytePos (int fileDescriptor)
	Returns current file position of the file given by descriptor fileDescriptor; it returns the positive position (>= 0) on success and -1 on failure.
Unicode string conversion
ML_UTILS_EXPORT MLuint16 *	MLConvertUTF8ToUTF16 (const char *inputString)
	Thread-safety: These functions are reentrant.
ML_UTILS_EXPORT MLuint32 *	MLConvertUTF8ToUTF32 (const char *inputString)
	Converts the given char string inputString (UTF8, terminated by 0) to UTF32, returns a newly allocated string that must be freed with MLFree(), returns NULL on error.
ML_UTILS_EXPORT char *	MLConvertUTF16ToUTF8 (const MLuint16 *inputWideString)
	Converts the given wide string inputWideString (UTF16, terminated by 0) to UTF8, returns a newly allocated wide string that must be freed with MLFree(), returns NULL on error.
ML_UTILS_EXPORT char *	MLConvertUTF8ToLatin1 (const char *inputUTFString)
	Converts the given UTF8 encoded and null terminated string inputUTFString to a Latin1 string, converting all non Latin1 chars to '?', the returned string must be freed with MLFree(), returns NULL on error.
ML_UTILS_EXPORT char *	MLConvertUTF16ToLatin1 (const MLuint16 *inputUTF16WideString)
	Converts the given UTF16 encoded wide and null terminated string inputUTF16WideString to a Latin1 string, converting all non Latin1 chars to '?', the returned string must be freed with MLFree(), returns NULL on error.
ML_UTILS_EXPORT char *	MLConvertLatin1ToUTF8 (const char *inputLatin1String)
	Converts the given Latin1 encoded and null terminated string inputLatin1String into a UTF8 string, the returned string must be freed with MLFree(), returns NULL on error.
ML_UTILS_EXPORT MLuint16 *	MLConvertLatin1ToUTF16 (const char *inputLatin1String)
	Convert the given Latin1 encoded and null terminated string inputLatin1String to a UTF16 string, the returned string must be freed with MLFree(), returns NULL on error.

---

Detailed Description

The following classes in the ML are known to be reentrant. This means that different instances of a reentrant class can be used different threads, but two different threads may not access the same instance at the same time (so manual synchronization is needed if two threads want to access the same instance).

Note: This list is not yet complete, but it will grow over time.

---

Function Documentation

ML_UTILS_EXPORT MLErrorCode MLclose

(

int

fileDescriptor

)

Closes an open file given by a the file descriptor fileDescriptor and returns ML_RESULT_OK on success and on failure an MLErrorCode describing the problem.

ML_UTILS_EXPORT MLuint16* MLConvertLatin1ToUTF16

(

const char *

inputLatin1String

)

Convert the given Latin1 encoded and null terminated string inputLatin1String to a UTF16 string, the returned string must be freed with MLFree(), returns NULL on error.

ML_UTILS_EXPORT char* MLConvertLatin1ToUTF8

(

const char *

inputLatin1String

)

Converts the given Latin1 encoded and null terminated string inputLatin1String into a UTF8 string, the returned string must be freed with MLFree(), returns NULL on error.

ML_UTILS_EXPORT char* MLConvertUTF16ToLatin1

(

const MLuint16 *

inputUTF16WideString

)

Converts the given UTF16 encoded wide and null terminated string inputUTF16WideString to a Latin1 string, converting all non Latin1 chars to '?', the returned string must be freed with MLFree(), returns NULL on error.

ML_UTILS_EXPORT char* MLConvertUTF16ToUTF8

(

const MLuint16 *

inputWideString

)

Converts the given wide string inputWideString (UTF16, terminated by 0) to UTF8, returns a newly allocated wide string that must be freed with MLFree(), returns NULL on error.

ML_UTILS_EXPORT char* MLConvertUTF8ToLatin1

(

const char *

inputUTFString

)

Converts the given UTF8 encoded and null terminated string inputUTFString to a Latin1 string, converting all non Latin1 chars to '?', the returned string must be freed with MLFree(), returns NULL on error.

ML_UTILS_EXPORT MLuint16* MLConvertUTF8ToUTF16

(

const char *

inputString

)

Thread-safety: These functions are reentrant.

Converts the given char string inputString (UTF8, terminated by 0) to UTF16, returns a newly allocated string that must be freed with MLFree(), returns NULL on error.

ML_UTILS_EXPORT MLuint32* MLConvertUTF8ToUTF32

(

const char *

inputString

)

Converts the given char string inputString (UTF8, terminated by 0) to UTF32, returns a newly allocated string that must be freed with MLFree(), returns NULL on error.

ML_UTILS_EXPORT MLErrorCode MLfclose

(

FILE *

file

)

Closes an open file given by descriptor file and returns 0 on success and non zero values on failure.

Parameters:

file

must be a valid pointer for an open file.

Returns:

ML_RESULT_OK on success and on failure an MLErrorCode describing the problem

ML_UTILS_EXPORT MLErrorCode MLFileAppendBinaryData	(	const char *	fileName,
		const MLuint8 *	data,
		size_t	numBytes
	)

Appends numBytes of data given by data to the file given by name fileName, creating a new file if it does not exist.

It returns ML_RESULT_OK on success or on failure an MLErrorCode describing the problem. Supports UTF-8 encoded unicode file names.

ML_UTILS_EXPORT MLErrorCode MLFileAppendBinaryDataWithDescriptor	(	int	fileDescriptor,
		const MLuint8 *	data,
		size_t	numBytes
	)

Appends numBytes of data given by data to the file given by file descriptor fileDescriptor which must be valid and indicate a writable file.

It returns MLErrorCode on success or on failure an MLErrorCode describing the problem.

ML_UTILS_EXPORT MLErrorCode MLFileAppendStringData	(	const char *	fileName,
		const char *	strData
	)

Appends the given null-terminated string strData to the file given by name fileName, creating a new file if it does not exist.

It returns ML_RESULT_OK on success or on failure an MLErrorCode describing the problem. Supports UTF-8 encoded unicode file names.

ML_UTILS_EXPORT int MLFileExists

(

const char *

fileName

)

Returns 1 if the given with name fileName exists, 0 otherwise or if fileName is NULL.

Sets errno if 0 is returned, use MLTranslateErrorCode to get an appropriate MLErrorCode for it. Supports UTF-8 encoded unicode file names.

ML_UTILS_EXPORT MLint MLFileGetBytePos

(

int

fileDescriptor

)

Returns current file position of the file given by descriptor fileDescriptor; it returns the positive position (>= 0) on success and -1 on failure.

File sizes > 2^63-1 are handled as error. If < 0 is returned then errno describes the error.

ML_UTILS_EXPORT MLint MLFileGetSizeFromDescriptor

(

int

fileDescriptor

)

Returns the size of the file given by the file descriptor fileDescriptor A negative value is returned on any error if fileDescriptor is invalid or on files larger than 2^63-1 bytes.

If < 0 is returned then errno describes the error.

ML_UTILS_EXPORT MLint MLFileGetSizeFromName

(

const char *

fileName

)

Returns the size of the file given by the null-terminated file name fileName.

A negative value is returned on any error if fileName is NULL or on files larger than 2^63-1 bytes. Supports UTF-8 encoded unicode file names. If < 0 is returned then errno describes the error.

ML_UTILS_EXPORT int MLFileIsReadable

(

const char *

fileName

)

Returns 1 if the given fileName exists and is readable, 0 otherwise.

Sets errno if 0 is returned, use MLTranslateErrorCode to get an appropriate MLErrorCode for it. Supports UTF-8 encoded unicode file names.

ML_UTILS_EXPORT int MLFileIsWritable

(

const char *

fileName

)

Returns 1 if the given file with name fileName exists and is writable, 0 otherwise.

Sets errno if 0 is returned, use MLTranslateErrorCode to get an appropriate MLErrorCode for it. Supports UTF-8 encoded unicode file names.

ML_UTILS_EXPORT MLuint8* MLFileReadAllAsBinary

(

const char *

fileName

)

Reads the complete file with a fileName as binary data, returns NULL on error.

The returned data chunk needs to be destroyed by calling MLFree() or Memory::freeMemory(). Supports UTF-8 encoded unicode file names.

ML_UTILS_EXPORT char* MLFileReadAllAsString

(

const char *

fileName

)

Reads the complete file with a fileName as a string, returns NULL on error.

The returned string will be null-terminated. The returned string needs to be destroyed by calling MLFree() or Memory::freeMemory(). Supports UTF-8 encoded unicode file names.

ML_UTILS_EXPORT MLuint8* MLFileReadChunkAsBinary	(	const char *	fileName,
		MLuint	startPosition,
		MLuint	numBytes
	)

Reads a data segment starting at startPosition from the file given by fileName and returns NULL on error.

If the file ends before numBytes can be read, the returned data chunk will not be shorter but only partially filled with data. If numBytes is 0, a valid memory allocation of 0 bytes takes place which also needs to be freed. Note that this function supports only files up to 2^63 bytes, because internally a sign flag is lost. The returned string needs to be destroyed by calling MLFree() or Memory::freeMemory(). Supports UTF-8 encoded unicode file names. If NULL is returned then errno describes the error.

ML_UTILS_EXPORT MLuint8* MLFileReadChunkAsBinaryFromDesc	(	int	fileDescriptor,
		MLuint	startPosition,
		MLuint	numBytes,
		int	useCurrentPosition
	)

Reads a data segment starting at startPosition from the file given by fileDescriptor and returns NULL on error.

If the file ends before numBytes can be read, the returned data chunk will not be shorter but only partially filled with data. If numBytes is 0, a valid memory allocation of 0 bytes takes place which also needs to be freed. Note that this function supports only files up to 2^63 bytes, because internally a sign flag is lost. The returned string needs to be destroyed by calling MLFree() or Memory::freeMemory(). In case of (file IO) errors the file is not closed. If NULL is returned then errno describes the error. If useCurrentPosition is 1, the current file position is taken and used to overwrite startPosition. If useCurrentPosition is 0, the startPosition is used normally. Other useCurrentPosition values are handled as error.

ML_UTILS_EXPORT char* MLFileReadChunkAsString	(	const char *	fileName,
		MLuint	startPosition,
		MLuint	numBytes
	)

Reads a string segment starting at startPosition from the file given by fileName as a string and returns NULL on error.

The returned string will be null-terminated and one byte larger than numBytes for the num-terminating character. If the file ends before numBytes can be read, the string will be shorter and also be null-terminated. If numBytes is 0, a valid memory allocation of 0 bytes takes place which also needs to be freed. Note that this function supports only files up to 2^63 bytes, because internally a sign flag is lost. On 32 bit system numBytes must not exceed 2^31 or NULL is returned as error. The returned string needs to be destroyed by calling MLFree() or Memory::freeMemory(). Supports UTF-8 encoded unicode file names.

ML_UTILS_EXPORT char* MLFileReadChunkAsStringFromDesc	(	int	fileDescriptor,
		MLuint	startPosition,
		MLuint	numBytes
	)

Reads a string segment starting at startingPosition from the file given by fileDescriptor as a string and returns NULL on error.

The returned string will be null-terminated and one byte larger than numBytes for the num-terminating character. If the file ends before numBytes can be read, the string will be shorter and also be null-terminated. If numBytes is 0, a valid memory allocation of 0 bytes takes place which also needs to be freed. Note that this function supports only files up to 2^63 bytes, because internally a sign flag is lost. On 32 bit system numBytes must not exceed 2^31 or NULL is returned as error. The returned string needs to be destroyed by calling MLFree() or Memory::freeMemory(). In case of (file IO) errors the file is not closed. If NULL is returned then errno describes the error.

ML_UTILS_EXPORT MLint MLFileSetBytePos	(	int	fileDescriptor,
		MLuint	position
	)

Sets the pointer of a file given by descriptor fileDescriptor to a position and returns the positive position on success and -1 on failure.

The position is valid only up to 2^63-1 because internally the sign flag is used. If < 0 is returned then errno describes the error.

ML_UTILS_EXPORT MLErrorCode MLFileWriteBinaryData	(	const char *	fileName,
		const MLuint8 *	data,
		size_t	numBytes
	)

Creates, opens, and overwrites the given file with name fileName with the given data of a given numBytes, and returns ML_RESULT_OK on success or on failure an MLErrorCode describing the problem.

The file is closed after write operation. Supports UTF-8 encoded unicode file names.

ML_UTILS_EXPORT MLErrorCode MLFileWriteBinaryDataAt	(	int	fileDescriptor,
		MLuint	startPosition,
		const MLuint8 *	data,
		size_t	numBytes
	)

Overwrites a section of the file given by file descriptor fileDescriptor which must have been opened with mode ML_O_RDWR or ML_O_WRONLY at position startPosition with the given data with numBytes.

It returns ML_RESULT_OK on success or on failure an MLErrorCode describing the problem. The file is NOT closed after writing.

ML_UTILS_EXPORT MLErrorCode MLFileWriteStringData	(	const char *	fileName,
		const char *	str
	)

Creates, opens, and overwrites the given file with name fileName with the given non NULL, null terminated data string str, and returns ML_RESULT_OK on success or an MLErrorCode describing the problem on failure.

The file will be closed after write operation. Supports UTF-8 encoded unicode file names.

ML_UTILS_EXPORT FILE* MLfopen	(	const char *	fileName,
		const char *	mode
	)

Thread-safety: These functions are reentrant.

Opens the file with name fileName with the access permissions given by mode, and returns a FILE pointer or NULL on failure. This method is equivalent to the stdio fopen implementation, see the fopen documentation for available mode flags ("r","w","a",...). In contrast to the original fopen method, this method accepts an UTF-8 encoded string and uses the unicode WIN32 API on Windows. On Unix systems, this method maps to fopen directly. If NULL is returned then errno describes the error.

ML_UTILS_EXPORT char* MLGetNonExistingRandomFileName

(

const char *

prefix

)

Returns a file name which does not exist in the current directory or NULL on failure.

It will be prefixed with the string prefix if prefix is non NULL and null-terminated. Otherwise a random file name is generated. The returned value must be freed with MLFree() or Memory::free(). Supports UTF-8 encoded unicode prefix strings. If NULL is returned then errno describes the error.

ML_UTILS_EXPORT char* MLGetTempPath

(

)

Returns the path to the temporary directory of the current user or NULL on failure.

The returned value must be freed with MLFree() or Memory::free().

ML_UTILS_EXPORT int MLopen	(	const char *	fileName,
		int	openFlags,
		int	pMode
	)

Opens the file with name fileName with the given openFlags, returns a file descriptor or -1 on error.

This method is equivalent to the stdio open implementation, see the open documentation for available open flags. In contrast to the original open method, this method accepts an UTF-8 encoded string and uses the unicode WIN32 API on Windows. On Unix systems, this method maps to open directly. pMode specifies the access permissions of the opened file, see ML_S_IREAD and ML_S_IWRITE. If < 0 is returned then errno describes the error.

ML_UTILS_EXPORT MLErrorCode MLremove

(

const char *

fileName

)

Deletes file with name fileName.

Parameters:

fileName

valid and null-terminated UTF8 name of the existing file.

Returns:

ML_RESULT_OK on success and on failure an MLErrorCode describing the problem

ML_UTILS_EXPORT MLErrorCode MLrename	(	const char *	oldName,
		const char *	newName
	)

Renames a file with name oldName to newName.

Parameters:

	oldName	valid and null-terminated UTF8 old name of the existing file.
	newName	valid and null-terminated UTF8 new file name.

Returns:

ML_RESULT_OK on success and on failure an MLErrorCode describing the problem