View Source HypeLib.Utils.String.Generator (HypeLib v2.2.0)

Contains utility functions for generating a random string and creating charsets.

It offers the following interesting functions:

The charset/1 function uses the valid_charsets() type for returning a predefined charset.

Link to this section Summary

Types

Defines the union type of known charset names.

Functions

Returns a charset based on the given name

Combines the given charset names to one big charset

Tries to generate one big charset based on the given charset names.

Generates a string of the desired length with random characters from the given charset.

Generates a string of the desired length and given charset.

Link to this section Types

@type valid_charsets() :: :lower | :upper | :numeric | :hex | :lower_hex | :upper_hex

Defines the union type of known charset names.

Charset name (atom)Description
:lowerThe lowercased alphabet (a-z)
:upperThe uppercased alphabet (A-Z)
:numericAll numerical values (0-9)
:hexAll hexadecimal values in uppercase (0-F)
:lower_hexAll hexadecimal values in lowercase (0-f)
:upper_hexAll hexadecimal values in uppercase (0-F)

(This type is managed by TypeCheck, which allows checking values against the type at runtime.)

Full definition:

valid_charsets() :: :lower | :upper | :numeric | :hex | :lower_hex | :upper_hex

Link to this section Functions

@spec charset(name :: valid_charsets()) :: [String.t()]

Returns a charset based on the given name

examples

Examples

lowercased-alphabet

Lowercased alphabet

iex> HypeLib.Utils.String.Generator.charset(:lower)
~w(a b c d e f g h i j k l m n o p q r s t u v w x y z)

uppercased-alphabet

Uppercased alphabet

iex> HypeLib.Utils.String.Generator.charset(:upper)
~w(A B C D E F G H I J K L M N O P Q R S T U V W X Y Z)

numerical-characters

Numerical characters

iex> HypeLib.Utils.String.Generator.charset(:numeric)
~w(0 1 2 3 4 5 6 7 8 9)

hexadecimal-characters

Hexadecimal characters

iex> HypeLib.Utils.String.Generator.charset(:hex)
~w(0 1 2 3 4 5 6 7 8 9 A B C D E F)
iex> HypeLib.Utils.String.Generator.charset(:upper_hex)
~w(0 1 2 3 4 5 6 7 8 9 A B C D E F)
iex> HypeLib.Utils.String.Generator.charset(:lower_hex)
~w(0 1 2 3 4 5 6 7 8 9 a b c d e f)
@spec charsets(charset_names :: [valid_charsets()]) ::
  {:ok, [String.t()]} | {:error, String.t()}

Combines the given charset names to one big charset

examples

Examples

It should return an error tuple when the given charset names are empty

iex> HypeLib.Utils.String.Generator.charsets([])
{:error, "Empty charset names list provided"}

It should return a combination of the lowercased alphabet and numerical numbers when the charset names are [:lower, :numeric]

iex> alias HypeLib.Utils.String.Generator
...> Generator.charsets([:lower, :numeric])
{:ok, Generator.charset(:lower) ++ Generator.charset(:numeric)}

It should return an combination of the lower- and uppercased alphabet including numerical characters when the charset names are [:lower, :upper, :numeric]

iex> alias HypeLib.Utils.String.Generator
...> Generator.charsets([:lower, :upper, :numeric])
{:ok, Generator.charset(:lower) ++ Generator.charset(:upper) ++ Generator.charset(:numeric)}
Link to this function

charsets!(charset_names)

View Source
@spec charsets!(charset_names :: [valid_charsets()]) :: [String.t()] | none()

Tries to generate one big charset based on the given charset names.

When the charset can't be generated then an error will be raised. This could happen in the following cases:

  • the given list is empty
  • the given list contains invalid charset names (via TypeCheck runtime check) (see Expected arguments section)

expected-arguments

Expected arguments

NameExpected data typeDescriptionExample values
charset_nameslist(valid_charsets())A list of valid charset names[:lower], ~w(lower upper numeric hex)a

examples

Examples

iex> HypeLib.Utils.String.Generator.charsets!(~w(lower numeric)a)
~w(a b c d e f g h i j k l m n o p q r s t u v w x y z 0 1 2 3 4 5 6 7 8 9)
iex> HypeLib.Utils.String.Generator.charsets!([])
** (RuntimeError) Empty charset names list provided
Link to this function

generate_string(arg1, arg2)

View Source
@spec generate_string(
  desired_length :: pos_integer(),
  charset :: [String.t()]
) :: {:ok, String.t()} | {:error, String.t()}
Link to this function

generate_string(desired_length, charset, current_string \\ "")

View Source
@spec generate_string(
  desired_length :: pos_integer(),
  charset :: [String.t()],
  current_string :: String.t()
) :: {:ok, String.t()} | {:error, String.t()}

Generates a string of the desired length with random characters from the given charset.

examples

Examples

It should return an error when the given charset is empty

iex> HypeLib.Utils.String.Generator.generate_string(2, [])
{:error, "Invalid charset length"}

Generate a string with a length of 2 and a given charset of ~w(a)

iex> HypeLib.Utils.String.Generator.generate_string(2, ~w(a))
{:ok, "aa"}

Generate a random string with a length of 16 and the alphabet given as charset

iex> alias HypeLib.Utils.String.Generator
...> {:ok, result} = Generator.generate_string(16, Generator.charset(:lower))
...> String.length(result)
16

It returns the current string if it has already the desired length

iex> alias HypeLib.Utils.String.Generator
...> Generator.generate_string(1, Generator.charset(:lower), "a")
{:ok, "a"}

It returns the current string if it is already longer than the desired length

iex> alias HypeLib.Utils.String.Generator
...> Generator.generate_string(1, Generator.charset(:lower), "aa")
{:ok, "aa"}
Link to this function

generate_string!(arg1, arg2)

View Source
@spec generate_string!(
  desired_length :: pos_integer(),
  charset :: [String.t()]
) :: String.t() | none()
Link to this function

generate_string!(desired_length, charset, current_string \\ "")

View Source
@spec generate_string!(
  desired_length :: pos_integer(),
  charset :: [String.t()],
  current_string :: String.t()
) :: String.t() | none()

Generates a string of the desired length and given charset.

Hint 1: You can use these functions to quickly generate a charset:

Hint 2: We don't provide any charsets for special characters since this is highly application specific.

When the string can't be generated then an error will be raised. This could happen in the following cases:

  • the given charset is an empty list
  • the arguments don't match the expected types (via TypeCheck runtime check) (see Expected arguments section)

expected-arguments

Expected arguments

NameExpected data typeDescriptionExample values
desired_lengthnumber()Only positive numerical values (excluding zero and negative numbers)0, 3.14
charsetlist(String.t())A list of strings which will be randomly picked["a"], ~w(a b c)
current_stringString.t()The starting string"", "a", "aAa"

examples

Examples

It should raise an runtime error when the charset is an empty list.

iex> HypeLib.Utils.String.Generator.generate_string!(2, [])
** (RuntimeError) Invalid charset length

Generate a string with a length of 2 and a given charset of ~w(a)

iex> HypeLib.Utils.String.Generator.generate_string!(2, ~w(a))
"aa"

Generate a random string with a length of 16 and the alphabet given as charset

iex> alias HypeLib.Utils.String.Generator
...> Generator.generate_string!(16, Generator.charset(:lower))
...> |> String.length()
16

It returns the current string if it has already the desired length

iex> alias HypeLib.Utils.String.Generator
...> Generator.generate_string!(1, Generator.charset(:lower), "a")
"a"

It returns the current string if it is already longer than the desired length

iex> alias HypeLib.Utils.String.Generator
...> Generator.generate_string!(1, Generator.charset(:lower), "aa")
"aa"