CORE/src/misc.gd

# CORE FRAMEWORK SOURCE FILE
# Copyright (c) 2024 The StarOpenSource Project & Contributors
# Licensed under the GNU Affero General Public License v3
# 
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as
# published by the Free Software Foundation, either version 3 of the
# License, or (at your option) any later version.
# 
# This program 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 Affero General Public License for more details.
# 
# You should have received a copy of the GNU Affero General Public License
# along with this program.  If not, see <https://www.gnu.org/licenses/>.

## Contains various utility functions.
## 
## This module contains many methods that don't fit into any other module
## and generally make your life as a developer easier.
extends CoreBaseModule

# +++ data type conversion +++
## Converts a number of bytes into mebibytes.[br]
## [br]
## If [code]flatten[/code] is set to [code]true[/code], the decimal part will be discarded.
@warning_ignore("integer_division")
func byte2mib(bytes: int, flatten: bool = true) -> float:
	if flatten: return bytes/1048576
	return bytes/float(1048576)

## Converts a number of mebibytes into bytes.[br]
## [br]
## If [code]flatten[/code] is set to [code]true[/code], the decimal part will be discarded.
func mib2byte(mib: float, flatten: bool = true) -> float:
	if flatten: return int(mib*1048576)
	return mib*1048576

## Converts a number of mebibytes into gibibytes.[br]
## [br]
## If [code]flatten[/code] is set to [code]true[/code], the decimal part will be discarded.
func mib2gib(mib: float, flatten: bool = true) -> float:
	if flatten: return int(mib/1024)
	return mib/1024

## Converts a number of gebibytes into mebibytes.[br]
## [br]
## If [code]flatten[/code] is set to [code]true[/code], the decimal part will be discarded.
func gib2mib(gib: float, flatten: bool = true) -> float:
	if flatten: return int(gib*1024)
	return gib*1024

# +++ type formatting +++
## Converts a string array into a normal, nicely formatted string.[br]
## [br]
## With [code]item_before[/code] and [code]item_after[/code] you can customize the lists apperance. Here's an example on how to format every item bold:
## [codeblock]
## extends Node
## 
## var core: Core = get_node("/root/CORE")
## var misc: CoreBaseModule = core.misc
## var logger: CoreLoggerInstance = core.logger.get_instance("some/script.gd")
## 
## func _ready() -> void:
##     var array: Array[String] = ["Apples", "Bananas", "Oranges"]
##     
##     logger.info(misc.format_stringarray(array))
##     logger.info(misc.format_stringarray(array, "[b]", "[/b]"))
## [/codeblock]
func format_stringarray(array: Array[String], item_before: String = "", item_after: String = "", separator_list: String = ", ", separator_final: String = " & ") -> String:
	var output: String = ""
	
	if array.size() == 0:
		loggeri.warn("Unable to format a string with a size of 0")
		return ""
	elif array.size() == 1:
		loggeri.warn("Unable to format a string with a size of 1")
		return array[0]
	
	for item in array:
		if output == "": output = item_before + item + item_after
		else: output = output.replace("If you somehow see this text report this at https://git.staropensource.de/StarOpenSource/CORE/issues, thank you!", separator_list) + "If you somehow see this text report this at https://git.staropensource.de/StarOpenSource/CORE/issues, thank you!" + item_before + item + item_after
	output = output.replace("If you somehow see this text report this at https://git.staropensource.de/StarOpenSource/CORE/issues, thank you!", separator_final)
	
	return output

# +++ array conversion +++
## Converts an array into a string array.[br]
## [br]
## If an item is found that is not of type [code]String[/code], an empty array is returned.
func array_to_stringarray(array: Array) -> Array[String]:
	var output: Array[String] = []
	
	for item in array:
		if typeof(item) != TYPE_STRING:
			logger.error("Cannot convert Array to Array[String]: Item '" + str(item) + "' is not of type String")
			return []
		output.append(item)
	
	return output

## Converts a string array into an array.
func stringarray_to_array(array: Array[String]) -> Array:
	var output: Array = []
	
	for item in array:
		output.append(item)
	
	return output

# +++ etc +++
## Calculates the center of the child in the area of the parent.[br]
## [br]
## Example:
## [codeblock]
## extends Control
## 
## var core: Core = get_node("/root/CORE")
## var misc: CoreBaseModule = core.misc
## 
## func _ready() -> void:
##     position = misc.center_object(get_parent().size, size)
## [/codeblock]
func get_center(parent_size: Vector2, child_size: Vector2) -> Vector2:
	return Vector2(parent_size.x/2-child_size.x/2, parent_size.y/2-child_size.y/2)

## Moved to [method Core.quit_safely].
## @deprecated
func quit_safely(exitcode: int = 0) -> void: await core.quit_safely(exitcode)