fs: further document and test behavior

docs/markdown/Fs-module.md

@@ -36,11 +36,35 @@ by the string is a symbolic link.
 
 ### with_suffix
 
-The `with_suffix` method allows changing the filename suffix
+The `with_suffix` method is a *string manipulation* convenient for filename modifications.
+It allows changing the filename suffix like:
+
+## swap suffix
 
 ```meson
 original = '/opt/foo.ini'
-new = fs.with_suffix('.txt')
+new = fs.with_suffix('.txt')  # /opt/foo.txt
+```
+
+#### add suffix
+
+```meson
+original = '/opt/foo'
+new = fs.with_suffix('.txt')  # /opt/foo.txt
+```
+
+#### compound suffix swap
+
+```meson
+original = '/opt/foo.dll.a'
+new = fs.with_suffix('.so')  # /opt/foo.dll.so
+```
+
+#### delete suffix
+
+```meson
+original = '/opt/foo.dll.a'
+new = fs.with_suffix('')  # /opt/foo.dll
 ```
 
-The files need not actually exist yet for this method.
+The files need not actually exist yet for this method, as it's just string manipulation.

test cases/common/227 fs module/meson.build

@@ -27,6 +27,18 @@ original = 'foo.txt'
 new = fs.with_suffix(original, '.ini')
 assert(new.endswith('foo.ini') and not new.contains('.txt'), 'with_suffix failed')
 
+original = 'foo'
+new = fs.with_suffix(original, '.ini')
+assert(new.endswith('foo.ini'), 'with_suffix did not add suffix to suffixless file')
+
+original = 'foo.dll.a'
+new = fs.with_suffix(original, '.so')
+assert(new.endswith('foo.dll.so'), 'with_suffix did not only modify last suffix')
+
+original = 'foo.dll'
+new = fs.with_suffix(original, '')
+assert(new.endswith('foo'), 'with_suffix did not only delete last suffix')
+
 # `/` on windows is interpreted like `.drive` which in general may not be `c:/`
 # the files need not exist for fs.with_suffix()
 original = is_windows ? 'j:/foo/bar.txt' : '/foo/bar.txt'