+
+-- | Replace (x)html entities in a 'String'. To do this, we search
+-- through the string looking for ampersands which may indicate the
+-- beginning of an entity.
+--
+-- If we find one and there's a semicolon after it, we attempt to
+-- look up the identifier that we found between the ampersand and
+-- the semicolon. If an entity is found, we replace the ampersand,
+-- semicolon, and everything in between with the entity. However if
+-- no corresponding entity is found, we leave everything alone.
+--
+-- Examples:
+--
+-- >>> replace_entities "Hello, world!"
+-- "Hello, world!"
+--
+-- >>> replace_entities "Hello; world!"
+-- "Hello; world!"
+--
+-- >>> replace_entities "Hello, world & other worlds!"
+-- "Hello, world & other worlds!"
+--
+-- >>> replace_entities "Hello, world & other worlds; hello indeed!"
+-- "Hello, world & other worlds; hello indeed!"
+--
+-- >>> putStrLn $ replace_entities "Hello world—I guess"
+-- Hello world—I guess
+--