uos

Documentation

Index

• func CheckEnvBool(key string) bool
• func GetCPUs() int
• func GetEnvAs[T any](key string, f MappingFunc[T]) (*T, error)
• func MapString(value string) (*string, error)
• func MapStringToBase64(value string) (*string, error)
• func MapStringToBool(value string) (*bool, error)
• func MapStringToDuration(value string) (*time.Duration, error)
• func MapStringToFloat32(value string) (*float32, error)
• func MapStringToFloat64(value string) (*float64, error)
• func MapStringToHex(value string) (*[]byte, error)
• func MapStringToInt(value string) (*int, error)
• func MapStringToInt16(value string) (*int16, error)
• func MapStringToInt32(value string) (*int32, error)
• func MapStringToInt64(value string) (*int64, error)
• func MapStringToInt8(value string) (*int8, error)
• func MapStringToTrimmed(value string) (*string, error)
• func MapStringToURL(value string) (*url.URL, error)
• func MapStringToUint(value string) (*uint, error)
• func MapStringToUint16(value string) (*uint16, error)
• func MapStringToUint32(value string) (*uint32, error)
• func MapStringToUint64(value string) (*uint64, error)
• func MapStringToUint8(value string) (*uint8, error)
• func RequireEnv(key string) string
• func RequireEnvAs[T any](key string, f MappingFunc[T]) T
• func RequireEnvBool(key string) bool
• func RequireEnvDuration(key string) time.Duration
• func RequireEnvNumeric[T basicutils.Numeric](key string) T
• func RequireEnvOrDefault[T any](key string, f MappingFunc[T], def T) (result T)
• func RequireEnvSlice(key string) []string
• func RequireEnvSliceAs[T any](key string, f MappingFunc[T]) []T
• func RequireEnvTime(key string, layout string) time.Time
• func RequireEnvURL(key string) url.URL
• type MappingFunc
  • func MapStringToTime(layout string) MappingFunc[time.Time]

Functions

func CheckEnvBool

func CheckEnvBool(key string) bool

CheckEnvBool helper is the same as RequireEnvBool, but doesn't panic as all RequireEnv or RequireEnvAs functions. It returns true if env variable is set to 'true' (case-insensitive) returns false otherwise.

func GetCPUs

func GetCPUs() int

GetCPUs calculates and returns the number of CPU cores available to the application. This function is designed to provide a more accurate count of available CPUs, especially when running in a containerized environment such as Docker or Kubernetes on Linux, where CPU resources can be limited.

The function operates as follows:

1. Checks the operating system where the application is running. If it's Linux, it proceeds to check the cgroup settings that are commonly used in containerized environments to limit CPU resources.

2. For Linux: a. Attempts to read the CPU allocation from the cgroup settings, specifically the cpu.cfs_quota_us and cpu.cfs_period_us files, which define the CPU quota and period for the container. b. If the cgroup CPU quota and period can be successfully read, it calculates the number of CPUs as the quotient of the quota and period. This gives a decimal representation of the number of CPU cores allocated to the container. This value is then returned as an integer. c. If the cgroup files are not accessible or an error occurs while reading them (which might happen if the application is not running in a containerized environment), the error is ignored, and the function falls back to the next step.

3. If the operating system is not Linux or if the cgroup CPU information could not be obtained, the function falls back to using runtime.NumCPU(). This standard Go library function returns the number of logical CPUs available to the current process, as seen by the Go runtime. This count reflects the total number of CPU cores available to the process, which may be the total number of cores on the machine or limited by the OS scheduler, depending on the environment and OS settings.

Return value:

• The function returns an integer representing the number of CPU cores that the application should consider available. This number is either derived from the cgroup settings (in containerized Linux environments) or from the runtime information provided by the Go runtime.NumCPU() function (in non-containerized environments or non-Linux operating systems).

Note:

• This function is particularly useful in containerized environments where CPU resources might be limited and different from the physical host's total CPU resources. By accounting for these limits, applications can make more informed decisions about resource allocation, concurrency, and parallel processing.

func GetEnvAs

func GetEnvAs[T any](key string, f MappingFunc[T]) (*T, error)

GetEnvAs is the same as RequireEnvAs, but indicates whether result was found or not.

func MapString

func MapString(value string) (*string, error)

MapString returns string value

func MapStringToBase64

func MapStringToBase64(value string) (*string, error)

MapStringToBase64 decodes a Base64 encoded string into its original representation.

func MapStringToBool

func MapStringToBool(value string) (*bool, error)

MapStringToBool parses a string into a *bool.

func MapStringToDuration

func MapStringToDuration(value string) (*time.Duration, error)

MapStringToDuration maps value to time.Duration.

func MapStringToFloat32

func MapStringToFloat32(value string) (*float32, error)

MapStringToFloat32 maps a string value to a *float32.

func MapStringToFloat64

func MapStringToFloat64(value string) (*float64, error)

MapStringToFloat64 maps a string value to a *float64.

func MapStringToHex

func MapStringToHex(value string) (*[]byte, error)

MapStringToHex decodes a Hex encoded string into its original representation.

func MapStringToInt

func MapStringToInt(value string) (*int, error)

MapStringToInt maps a string value to an *int.

func MapStringToInt16

func MapStringToInt16(value string) (*int16, error)

MapStringToInt16 maps a string value to an *int16.

func MapStringToInt32

func MapStringToInt32(value string) (*int32, error)

MapStringToInt32 maps a string value to an *int32.

func MapStringToInt64

func MapStringToInt64(value string) (*int64, error)

MapStringToInt64 maps a string value to an *int64.

func MapStringToInt8

func MapStringToInt8(value string) (*int8, error)

MapStringToInt8 maps a string value to an *int8.

func MapStringToTrimmed

func MapStringToTrimmed(value string) (*string, error)

MapStringToTrimmed returns string a value trimmed of space characters.

func MapStringToURL

func MapStringToURL(value string) (*url.URL, error)

MapStringToURL parses a string into a *url.URL.

func MapStringToUint

func MapStringToUint(value string) (*uint, error)

MapStringToUint maps a string value to an *uint.

func MapStringToUint16

func MapStringToUint16(value string) (*uint16, error)

MapStringToUint16 maps a string value to an *uint16.

func MapStringToUint32

func MapStringToUint32(value string) (*uint32, error)

MapStringToUint32 maps a string value to an *uint32.

func MapStringToUint64

func MapStringToUint64(value string) (*uint64, error)

MapStringToUint64 maps a string value to an *uint64.

func MapStringToUint8

func MapStringToUint8(value string) (*uint8, error)

MapStringToUint8 maps a string value to an *uint8.

func RequireEnv

func RequireEnv(key string) string

RequireEnv is an alias to RequireEnvAs[string](key, MapString)

func RequireEnvAs

func RequireEnvAs[T any](key string, f MappingFunc[T]) T

RequireEnvAs retrieves an environment variable specified by `key` and uses a provided MappingFunc `f` to convert the environment variable's string value into the desired type `T`. The MappingFunc `f` should take a string as input and return a pointer to the type `T` and an error. If the environment variable is not set, RequireEnvAs panics with an error indicating that the expected environment variable was not found. If the MappingFunc `f` returns an error, RequireEnvAs panics with an error indicating that the environment variable could not be parsed as the desired type.

Parameters:

key: the name of the environment variable to retrieve.
f: a MappingFunc that converts a string value to the desired type `T`, returning a pointer to `T` and an error.

Returns:

The value of the environment variable converted to type `T`.

Example usage:

// Assuming MapStringToDuration and MapStringToInt are defined MappingFuncs for time.Duration and int respectively
duration := RequireEnvAs("TIMEOUT", MapStringToDuration(time.RFC3339))
url := RequireEnvAs("MY_URL", MapStringToURL)

Note: Since this function uses panic for error handling, it should be used in contexts where such behavior is acceptable, or it should be recovered using defer and recover mechanisms.

func RequireEnvBool

func RequireEnvBool(key string) bool

RequireEnvBool helper for bool values.

func RequireEnvDuration

func RequireEnvDuration(key string) time.Duration

RequireEnvDuration retrieves the environment variable specified by key as a time.Duration. This function uses RequireEnvAs under the hood to convert the environment variable string to a time.Duration type. If the environment variable is not found, or if the conversion fails (e.g., due to an invalid duration format), RequireEnvDuration will panic.

The expected format for the duration is a string accepted by time.ParseDuration, which includes any input valid for time.Duration such as "300ms", "1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".

Example: If you have an environment variable named TIMEOUT with the value "2m30s", RequireEnvDuration("TIMEOUT") will return a time.Duration of 2 minutes and 30 seconds.

os.Setenv("TIMEOUT", "2m30s")
timeout := RequireEnvDuration("TIMEOUT")
fmt.Println(timeout) // Prints: 2m30s

Note: Because it can panic, this function should be used in cases where the environment variable is expected to be set and correctly formatted. For more flexible error handling, consider using the underlying RequireEnvAs function directly with appropriate error checks.

func RequireEnvNumeric

func RequireEnvNumeric[T basicutils.Numeric](key string) T

RequireEnvNumeric retrieves an environment variable specified by `key` and converts it to the specified basicutils.Numeric type `T`. The function panics if the environment variable is not set, cannot be converted to type `T`, or if `T` is not an integer type. It uses the appropriate bit size for parsing to ensure values fit into the specified type without overflow.

func RequireEnvOrDefault

func RequireEnvOrDefault[T any](key string, f MappingFunc[T], def T) (result T)

RequireEnvOrDefault is the same as RequireEnvAs, but returns default value in case

func RequireEnvSlice

func RequireEnvSlice(key string) []string

RequireEnvSlice retrieves an environment variable specified by `key` and returns it as a slice of strings. The environment variable should contain a list of strings separated by commas, possibly surrounded by spaces. This function uses RequireEnvAs to handle the retrieval and conversion of the environment variable, leveraging its error handling to manage scenarios where the environment variable is not set or cannot be properly parsed.

Parameters:

key: the name of the environment variable to retrieve, which should contain a list of strings separated by commas.

Returns:

A slice of strings parsed from the environment variable, with leading and trailing spaces around each item removed.

Panics:

• If the environment variable is not set, this function will panic, indicating that the expected environment variable was not found.
• If there is an error during the parsing process, a panic will occur, indicating that the environment variable could not be parsed into a slice of strings.

Example usage:

// Assuming an environment variable "COLORS" is set to "red, green, blue"
colors := RequireEnvSlice("COLORS")
fmt.Println(colors) // Output: [red green blue]

Note:

 This function trims all values, thus removing space characters.
	This function also uses panic for error handling, which can halt the application unless handled properly.
	It is recommended to use this function in contexts where such behavior is acceptable, or to employ
	defer and recover mechanisms to gracefully manage errors and prevent application termination.

func RequireEnvSliceAs

func RequireEnvSliceAs[T any](key string, f MappingFunc[T]) []T

RequireEnvSliceAs is the same as RequireEnvSlice, but supports any types. This func retrieves an environment variable specified by `key`, splits it by commas, trims any spaces, and maps each element to a type T using a provided MappingFunc. This function leverages RequireEnvAs for the initial retrieval and error handling, ensuring robust handling of missing or improperly formatted environment variables.

Parameters:

key: the name of the environment variable to retrieve, expected to contain a comma-separated list of strings.
f: a MappingFunc that converts a trimmed string value to the desired type `T`, returning `T` and an error.

Returns:

A slice of `T` representing the parsed and converted elements of the environment variable.

Panics:

• If the environment variable is not set, or if any element cannot be successfully converted to type `T`, this function will panic, indicating the specific error encountered.

Example usage:

// Assuming an environment variable "RATES" is set to "0.5, 2.3, 3.8"
rates := RequireEnvSlice[float64]("RATES", MapStringToFloat64)
fmt.Println(rates) // Output might be [0.5 2.3 3.8]

Note:

This function uses panic for error handling, which can halt the application unless handled properly.
It is recommended to use this function in contexts where such behavior is acceptable, or to employ
defer and recover mechanisms to gracefully manage errors and prevent application termination.

func RequireEnvTime

func RequireEnvTime(key string, layout string) time.Time

RequireEnvTime is the same helper as RequireEnvDuration, but for time.Time.

func RequireEnvURL

func RequireEnvURL(key string) url.URL

RequireEnvURL helper for URL.

Types

type MappingFunc

type MappingFunc[T any] func(value string) (*T, error)

MappingFunc is a type for functions that convert a string to a pointer of type T, returning an error if the conversion fails.

func MapStringToTime

func MapStringToTime(layout string) MappingFunc[time.Time]

MapStringToTime creates a function to convert a string to a time.Time using the specified layout. This allows for flexibility in parsing different time formats.