Module

Data.String.NonEmpty.Internal

While most of the code in this module is safe, this module does export a few partial functions and the NonEmptyString constructor. While the partial functions are obvious from the Partial constraint in their type signature, the NonEmptyString constructor can be overlooked when searching for issues in one's code. See the constructor's documentation for more information.

#NonEmptyString

newtype NonEmptyString

A string that is known not to be empty.

You can use this constructor to create a NonEmptyString that isn't non-empty, breaking the guarantee behind this newtype. It is provided as an escape hatch mainly for the Data.NonEmpty.CodeUnits and Data.NonEmpty.CodePoints modules. Use this at your own risk when you know what you are doing.

Constructors

Instances

#MakeNonEmpty

class MakeNonEmpty (s :: Symbol)  where

A helper class for defining non-empty string values at compile time.

something :: NonEmptyString
something = nes (Proxy :: Proxy "something")

Members

Instances

#NonEmptyReplacement

newtype NonEmptyReplacement

A newtype used in cases to specify a non-empty replacement for a pattern.

Constructors

Instances

#fromString

fromString :: String -> Maybe NonEmptyString

Creates a NonEmptyString from a String, returning Nothing if the input is empty.

fromString "" = Nothing
fromString "hello" = Just (NES.unsafeFromString "hello")

#unsafeFromString

unsafeFromString :: Partial => String -> NonEmptyString

A partial version of fromString.

#toString

toString :: NonEmptyString -> String

Converts a NonEmptyString back into a standard String.

#appendString

appendString :: NonEmptyString -> String -> NonEmptyString

Appends a string to this non-empty string. Since one of the strings is non-empty we know the result will be too.

appendString (NonEmptyString "Hello") " world" == NonEmptyString "Hello world"
appendString (NonEmptyString "Hello") "" == NonEmptyString "Hello"

#prependString

prependString :: String -> NonEmptyString -> NonEmptyString

Prepends a string to this non-empty string. Since one of the strings is non-empty we know the result will be too.

prependString "be" (NonEmptyString "fore") == NonEmptyString "before"
prependString "" (NonEmptyString "fore") == NonEmptyString "fore"

#stripPrefix

stripPrefix :: Pattern -> NonEmptyString -> Maybe NonEmptyString

If the string starts with the given prefix, return the portion of the string left after removing it. If the prefix does not match or there is no remainder, the result will be Nothing.

stripPrefix (Pattern "http:") (NonEmptyString "http://purescript.org") == Just (NonEmptyString "//purescript.org")
stripPrefix (Pattern "http:") (NonEmptyString "https://purescript.org") == Nothing
stripPrefix (Pattern "Hello!") (NonEmptyString "Hello!") == Nothing

#stripSuffix

stripSuffix :: Pattern -> NonEmptyString -> Maybe NonEmptyString

If the string ends with the given suffix, return the portion of the string left after removing it. If the suffix does not match or there is no remainder, the result will be Nothing.

stripSuffix (Pattern ".exe") (NonEmptyString "purs.exe") == Just (NonEmptyString "purs")
stripSuffix (Pattern ".exe") (NonEmptyString "purs") == Nothing
stripSuffix (Pattern "Hello!") (NonEmptyString "Hello!") == Nothing

#contains

contains :: Pattern -> NonEmptyString -> Boolean

Checks whether the pattern appears in the given string.

contains (Pattern "needle") (NonEmptyString "haystack with needle") == true
contains (Pattern "needle") (NonEmptyString "haystack") == false

#localeCompare

localeCompare :: NonEmptyString -> NonEmptyString -> Ordering

Compare two strings in a locale-aware fashion. This is in contrast to the Ord instance on String which treats strings as arrays of code units:

NonEmptyString "ä" `localeCompare` NonEmptyString "b" == LT
NonEmptyString "ä" `compare` NonEmptyString "b" == GT

#replace

replace :: Pattern -> NonEmptyReplacement -> NonEmptyString -> NonEmptyString

Replaces the first occurence of the pattern with the replacement string.

replace (Pattern "<=") (NonEmptyReplacement "≤") (NonEmptyString "a <= b <= c") == NonEmptyString "a ≤ b <= c"

#replaceAll

replaceAll :: Pattern -> NonEmptyReplacement -> NonEmptyString -> NonEmptyString

Replaces all occurences of the pattern with the replacement string.

replaceAll (Pattern "<=") (NonEmptyReplacement "≤") (NonEmptyString "a <= b <= c") == NonEmptyString "a ≤ b ≤ c"

#toLower

toLower :: NonEmptyString -> NonEmptyString

Returns the argument converted to lowercase.

toLower (NonEmptyString "hElLo") == NonEmptyString "hello"

#toUpper

toUpper :: NonEmptyString -> NonEmptyString

Returns the argument converted to uppercase.

toUpper (NonEmptyString "Hello") == NonEmptyString "HELLO"

#trim

trim :: NonEmptyString -> Maybe NonEmptyString

Removes whitespace from the beginning and end of a string, including whitespace characters and line terminators. If the string is entirely made up of whitespace the result will be Nothing.

trim (NonEmptyString "   Hello  \n World\n\t    ") == Just (NonEmptyString "Hello  \n World")
trim (NonEmptyString "   \n") == Nothing

#joinWith

joinWith :: forall f. Foldable f => String -> f NonEmptyString -> String

Joins the strings in a container together as a new string, inserting the first argument as separator between them. The result is not guaranteed to be non-empty.

joinWith ", " [NonEmptyString "apple", NonEmptyString "banana"] == "apple, banana"
joinWith ", " [] == ""

#join1With

join1With :: forall f. Foldable1 f => String -> f NonEmptyString -> NonEmptyString

Joins non-empty strings in a non-empty container together as a new non-empty string, inserting a possibly empty string as separator between them. The result is guaranteed to be non-empty.

-- array syntax is used for demonstration here, it would need to be a real `Foldable1`
join1With ", " [NonEmptyString "apple", NonEmptyString "banana"] == NonEmptyString "apple, banana"
join1With "" [NonEmptyString "apple", NonEmptyString "banana"] == NonEmptyString "applebanana"

#joinWith1

joinWith1 :: forall f. Foldable1 f => NonEmptyString -> f String -> NonEmptyString

Joins possibly empty strings in a non-empty container together as a new non-empty string, inserting a non-empty string as a separator between them. The result is guaranteed to be non-empty.

-- array syntax is used for demonstration here, it would need to be a real `Foldable1`
joinWith1 (NonEmptyString ", ") ["apple", "banana"] == NonEmptyString "apple, banana"
joinWith1 (NonEmptyString "/") ["a", "b", "", "c", ""] == NonEmptyString "a/b//c/"

#liftS

liftS :: forall r. (String -> r) -> NonEmptyString -> r

Modules