Class GorgonIOExtensions

Extension methods for IO operations and string formatting.

Inheritance

object

GorgonIOExtensions

Inherited Members

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

Namespace: Gorgon.IO

Assembly: Gorgon.Core.dll

Syntax

public static class GorgonIOExtensions

Methods

ChunkID(string)

Function to return the chunk ID based on the name of the chunk passed to this method.

Declaration

public static ulong ChunkID(this string chunkName)

Parameters

Type	Name	Description
string	chunkName	The name of the chunk.

Returns

Type	Description
ulong	A ulong value representing the chunk ID of the name.

Remarks

This method is used to generate a new chunk ID for the Gorgon chunked file format. It converts the characters in the string to their ASCII byte equivalents, and then builds a ulong value from those bytes.

Since the size of an ulong is 8 bytes, then the string should contain 8 characters. If it does not, then the ID will be padded with 0's on the right to take up the remaining bytes. If the string is larger than 8 characters, then it will be truncated to the 8 character limit.

The format of the long value is not endian specific and is encoded in the same order as the characters in the string. For example, encoding the string 'TESTVALU' produces:

Byte	1	2	3	4	5	6	7	8
Character	'T' (0x54)	'E' (0x45)	'S' (0x53)	'T' (0x54)	'V' (0x56)	'A' (0x41)	'L' (0x4C)	'U' (0x55)

Exceptions

Type	Condition
ArgumentNullException	Thrown when the chunkName parameter is null.

CopyToStream(Stream, Stream, int, byte[])

Function to copy the contents of this stream into another stream, up to a specified byte count.

Declaration

public static int CopyToStream(this Stream stream, Stream destination, int count, byte[] buffer)

Parameters

Type	Name	Description
Stream	stream	The source stream that will be copied from.
Stream	destination	The stream that will receive the copy of the data.
int	count	The number of bytes to copy.
byte[]	buffer	The buffer to use for reading and writing the chunks of the file.

Returns

Type	Description
int	The number of bytes copied, or 0 if no data was copied or at the end of a stream.

Remarks

This method is an extension of the CopyTo(Stream, int) method. But unlike that method, it will copy up to the number of bytes specified by count.

The buffer is used to copy data in blocks, rather than attempt to copy byte-by-byte. This may improve performance significantly. It is not recommended that the buffer exceeds 85,000 bytes. A value under this will ensure that the internal buffer will remain on the small object heap and be collected quickly when done.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the destination,stream, or the buffer parameters are null.
ArgumentEmptyException	Thrown when the buffer is less than 1 byte.
ArgumentException	Thrown when the stream is write-only. -or- Thrown when the destination is read-only.

CopyToStream(Stream, Stream, int, int)

Function to copy the contents of this stream into another stream, up to a specified byte count.

Declaration

public static int CopyToStream(this Stream stream, Stream destination, int count, int bufferSize = 131072)

Parameters

Type	Name	Description
Stream	stream	The source stream that will be copied from.
Stream	destination	The stream that will receive the copy of the data.
int	count	The number of bytes to copy.
int	bufferSize	[Optional] The size of the temporary buffer used to buffer the data between streams.

Returns

Type	Description
int	The number of bytes copied, or 0 if no data was copied or at the end of a stream.

Remarks

This method is an extension of the CopyTo(Stream, int) method. But unlike that method, it will copy up to the number of bytes specified by count.

The bufferSize is used to copy data in blocks, rather than attempt to copy byte-by-byte. This may improve performance significantly. It is not recommended that the buffer exceeds 85,000 bytes. A value under this will ensure that the internal buffer will remain on the small object heap and be collected quickly when done.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the destination, or the stream parameters are null.
ArgumentEmptyException	Thrown when the stream is write-only. -or- Thrown when the destination is read-only.

FormatDirectory(string, char)

Function to format a directory path with safe characters.

Declaration

public static string FormatDirectory(this string path, char directorySeparator)

Parameters

Type	Name	Description
string	path	The directory path to evaluate..
char	directorySeparator	Directory separator character to use.

Returns

Type	Description
string	A safe directory path formatted with placeholder characters if invalid characters are found. Directory separators will be replaced with the specified separator passed to directorySeparator.

Remarks

This will replace any illegal path characters with the underscore character. Any doubled up directory separators (e.g. // or \\) will be replaced with the directory separator passed to directorySeparator.

If null or Empty are passed to this method, then an empty string will be returned. If the path contains only a filename, that string will be formatted as though it were a directory path.

FormatFileName(string)

Function to format a filename with safe characters.

Declaration

public static string FormatFileName(this string path)

Parameters

Type	Name	Description
string	path	The path containing the filename to evaluate.

Returns

Type	Description
string	A safe filename formatted with placeholder characters if invalid characters are found.

Remarks

This will replace any illegal filename characters with the underscore character.

If null or Empty are passed to this method, then an empty string will be returned. If the path does not contain a filename, then an empty string will be returned as well.

FormatPath(string, char)

Function to format a path with safe characters.

Declaration

public static string FormatPath(this string path, char directorySeparator)

Parameters

Type	Name	Description
string	path	Path to the file or folder to format.
char	directorySeparator	Directory separator character to use.

Returns

Type	Description
string	A safe path formatted with placeholder characters if invalid characters are found.

Remarks

If the path contains directories, they will be formatted according to the formatting applied by FormatDirectory(string, char), and if the path contains a filename, it will be formatted according to the formatting applied by the FormatFileName(string) method.

If the last character in path is not the same as the directorySeparator parameter, then that last part of the path will be treated as a file.

If no directories are present in the path, then the see directorySeparator is ignored.

FormatPathPart(string)

Function to format a specific piece of a path.

Declaration

public static string FormatPathPart(this string path)

Parameters

Type	Name	Description
string	path	The path part to evaluate and repair.

Returns

Type	Description
string	A safe path part with placeholder characters if invalid characters are found.

Remarks

This method removes illegal symbols from the path and replaces them with an underscore character. It will not respect path separators and will consider those characters as illegal if provided in the path parameter.

GetPathParts(string, char)

Function to split a path into component parts.

Declaration

public static string[] GetPathParts(this string path, char directorySeparator)

Parameters

Type	Name	Description
string	path	The path to split.
char	directorySeparator	The separator to split the path on.

Returns

Type	Description
string[]	An array containing the parts of the path, or an empty array if the path is null or empty.

Remarks

This will take a path a split it into individual pieces for evaluation. The directorySeparator parameter will be the character used to determine how to split the path. For example:

string myPath = @"C:\Windows\System32\ddraw.dll";
string[] parts = myPath.GetPathParts(Path.DirectorySeparatorChar);

foreach(string part in parts)
   {
	Console.WriteLine(part);
}

/* Output should be:
 * C:
 * Windows
 * System32
 * ddraw.dll
 */

Read(Stream, Span<byte>)

Function to read data into a span from a stream.

Declaration

public static int Read(this Stream stream, Span<byte> buffer)

Parameters

Type	Name	Description
Stream	stream	The stream containing the data to read.
Span<byte>	buffer	The span to copy data into.

Returns

Type	Description
int	The number of bytes read.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the stream parameter is null.

ReadString(Stream)

Function to read a string from a stream using UTF-8 encoding.

Declaration

public static string ReadString(this Stream stream)

Parameters

Type	Name	Description
Stream	stream	The stream to read the string from.

Returns

Type	Description
string	The string in the stream.

Remarks

Gorgon stores its strings in a stream by prefixing the string data with the length of the string. This length is encoded as a series of 7-bit bytes.

This method is not thread safe. Use care when using threads with this method.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the stream parameter is null.
IOException	Thrown when an attempt to read beyond the end of the stream is made.

ReadString(Stream, Encoding)

Function to read a string from a stream with the specified encoding.

Declaration

public static string ReadString(this Stream stream, Encoding encoding)

Parameters

Type	Name	Description
Stream	stream	The stream to read the string from.
Encoding	encoding	The encoding for the string.

Returns

Type	Description
string	The string in the stream.

Remarks

Gorgon stores its strings in a stream by prefixing the string data with the length of the string. This length is encoded as a series of 7-bit bytes.

If the encoding parameter is null, then UTF-8 encoding is used.

This method is not thread safe. Use care when using threads with this method.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the stream parameter is null.
IOException	Thrown when an attempt to read beyond the end of the stream is made.

Write(Stream, ReadOnlySpan<byte>)

Function to write data from a span into a stream.

Declaration

public static void Write(this Stream stream, ReadOnlySpan<byte> buffer)

Parameters

Type	Name	Description
Stream	stream	The stream containing the data to read.
ReadOnlySpan<byte>	buffer	The span to copy data into.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the stream parameter is null.

WriteString(Stream, string)

Function to write a string to a stream with UTF-8 encoding.

Declaration

public static void WriteString(this Stream stream, string value)

Parameters

Type	Name	Description
Stream	stream	The stream to write the string into.
string	value	The string to write.

Remarks

Gorgon stores its strings in a stream by prefixing the string data with the length of the string, in bytes. This length is encoded as a series of 7-bit bytes.

This method is not thread safe. Use care when using threads with this method.

Exceptions

Type	Condition
IOException	Thrown when the stream parameter is read-only.
ArgumentNullException	Thrown when the stream parameter is null.

WriteString(Stream, string, Encoding)

Function to write a string to a stream with the specified encoding.

Declaration

public static void WriteString(this Stream stream, string value, Encoding encoding)

Parameters

Type	Name	Description
Stream	stream	The stream to write the string into.
string	value	The string to write.
Encoding	encoding	The encoding for the string.

Remarks

Gorgon stores its strings in a stream by prefixing the string data with the length of the string, in bytes. This length is encoded as a series of 7-bit bytes.

If the encoding parameter is null, then UTF-8 encoding is used.

This method is not thread safe. Use care when using threads with this method.

Exceptions

Type	Condition
IOException	Thrown when the stream parameter is read-only.
ArgumentNullException	Thrown when the stream parameter is null.

WriteToStream(string, Stream)

Function to write a string into a stream with UTF-8 encoding.

Declaration

public static int WriteToStream(this string value, Stream stream)

Parameters

Type	Name	Description
string	value	The string to write into the stream.
Stream	stream	Stream to encode the string into.

Returns

Type	Description
int	The number of bytes written to the stream.

Remarks

This will encode the string as a series of bytes into a stream. The length of the string, in bytes, will be prefixed to the string as a series of 7 bit byte values.

This method is not thread safe. Use care when using threads with this method.

Exceptions

Type	Condition
IOException	Thrown when the stream parameter is read-only.
ArgumentNullException	Thrown when the stream parameter is null.

WriteToStream(string, Stream, Encoding)

Function to encode a string into a stream with the specified encoding.

Declaration

public static int WriteToStream(this string value, Stream stream, Encoding encoding)

Parameters

Type	Name	Description
string	value	The string to write into the stream.
Stream	stream	Stream to encode the string into.
Encoding	encoding	Encoding for the string.

Returns

Type	Description
int	The number of bytes written to the stream.

Remarks

This will encode the string as a series of bytes into a stream. The length of the string, in bytes, will be prefixed to the string as a series of 7 bit byte values.

If the encoding parameter is null, then UTF-8 encoding will be used.

This method is not thread safe. Use care when using threads with this method.

Exceptions

Type	Condition
IOException	Thrown when the stream parameter is read-only.
ArgumentNullException	Thrown when the stream parameter is null.