added str_wrap

Author: cecoeco

src/TidierStrings.jl

@@ -9,7 +9,7 @@ export
     # concatenation
     str_c, str_flatten, str_flatten_comma,
     # characters
-    str_dup, str_length, str_width, str_trim, str_squish,
+    str_dup, str_length, str_width, str_trim, str_squish, str_wrap,
     # locale
     str_equal, str_to_upper, str_to_lower, str_to_title, str_to_sentence, str_unique,
     # other

src/characters.jl

@@ -2,49 +2,33 @@
 $docstring_str_dup
 """
 function str_dup(s::AbstractString, times::Integer)
-    if ismissing(s)
-        return (s)
-    end
-
     return repeat(s, times)
 end
 
 """
 $docstring_str_length
 """
 function str_length(s::AbstractString)
-    if ismissing(s)
-        return (s)
-    end
-
     return length(s)
 end
 
 """
 $docstring_str_width
 """
-function str_width(s::AbstractString)
-    if ismissing(s)
-        return (s)
-    end
-
-    return textwidth(s)
+function str_width(s::AbstractString)::Integer
+    return Base.textwidth(s)
 end
 
 """
 $docstring_str_trim
 """
-function str_trim(s::AbstractString, side::String="both")
-    if ismissing(s)
-        return (s)
-    end
-
+function str_trim(s::AbstractString, side::String="both")::String
     if side == "both"
-        return strip(s)
+        return Base.strip(s)
     elseif side == "left"
-        return lstrip(s)
+        return Base.lstrip(s)
     elseif side == "right"
-        return rstrip(s)
+        return Base.rstrip(s)
     else
         throw(ArgumentError("side must be one of 'both', 'left', or 'right'"))
     end
@@ -53,12 +37,53 @@ end
 """
 $docstring_str_squish
 """
-function str_squish(column)
-    if ismissing(column)
-        return (column)
+function str_squish(column)::String
+    squished::String = Base.strip(column)
+
+    return Base.replace(squished, r"\s+" => Base.s" ")
+end
+
+"""
+$docstring_str_wrap
+"""
+function str_wrap(
+    string::AbstractString;
+    width::Integer=80,
+    indent::Integer=0,
+    exdent::Integer=0,
+    whitespace_only::Bool=true)::String
+
+    width::Integer = Base.max(width, 1)
+
+    split_pattern::Regex = r"\s+"
+    if whitespace_only
+        split_pattern = r"\s+"
+    else
+        split_pattern = r"\W+"
     end
-    # Remove leading and trailing white spaces
-    squished = strip(column)
-    # Replace any sequence of whitespace characters with a single space
-    return replace(squished, r"\s+" => s" ")
+
+    words::Vector{SubString{String}} = Base.split(string, split_pattern)
+
+    indent_str::String = " "^indent
+    exdent_str::String = " "^exdent
+
+    lines::Vector{String} = []
+    current_line::String = indent_str
+
+    for word in words
+        if Base.length(current_line) + Base.length(word) + 1 > width
+            Base.push!(lines, current_line)
+            current_line = exdent_str * word
+        else
+            if current_line == indent_str
+                current_line *= word
+            else
+                current_line *= " " * word
+            end
+        end
+    end
+
+    Base.push!(lines, current_line)
+
+    return Base.join(lines, "\n")
 end

src/docstrings.jl

@@ -740,4 +740,33 @@ Examples
 julia> str_c(["apple", "banana", "pear", "pineapple"])
 "applebananapearpineapple"
 ```
+"""
+
+const docstring_str_wrap =
+"""
+    str_wrap(string::AbstractString; width::Integer=80, indent::Integer=0, exdent::Integer=0, whitespace_only::Bool=true)::String
+
+Wraps a string into multiple lines.
+
+Arguments
+- `string`: Input string.
+- `width`: The maximum width of each line. Default is 80.
+- `indent`: The number of spaces to indent each line. Default is 0.
+- `exdent`: The number of spaces to exdent each line. Default is 0.
+- `whitespace_only`: Whether to only wrap on whitespace. Default is true.
+
+Returns
+The wrapped string.
+
+Examples
+```jldoctest
+julia> str_wrap("This is an example text that should be wrapped based on the given width and breaking rules.", width=20, whitespace_only=true)
+"This is an example\ntext that should be\nwrapped based on the\ngiven width and\nbreaking rules."
+
+julia> str_wrap("This is an example text that should be wrapped based on the given width and breaking rules.", width=20, whitespace_only=false)
+"This is an example\ntext that should be\nwrapped based on\nthe given width\nand breaking\nrules."
+
+julia> str_wrap("This is an example text that should be wrapped based on the given width and breaking rules.", width=20, indent=4, whitespace_only=true)
+"    This is an\n    example text\n    that should\n    be wrapped\n    based on the\n    given width\n    and breaking\n    rules."
+```
 """