Added Splitting Text and implemented Immutable Maps

[rehandxtr]

Add Immutable Map Decorator and splitPreserveAllTokens Utility

Summary

This PR implements two features requested in recent issues:

1. Immutable Map Decorator (org.cactoos.map.Immutable)

   • Complete read-only wrapper for any Map<K, V>
   • Blocks all mutation operations (put, remove, putAll, clear)
   • Makes views (keySet, values, entrySet) and their iterators immutable
   • Blocks Entry.setValue() on entries from entrySet()
   • Follows existing patterns from list.Immutable, set.Immutable, etc.

2. splitPreserveAllTokens Utility (SplitPreserveAllTokens + TriFuncSplitPreserve)

   • Preserves ALL tokens including leading/trailing/adjacent empty tokens
   • Unlike Java's String.split() which discards trailing empties
   • Equivalent to Apache Commons Lang StringUtils.splitPreserveAllTokens()
   • Object-oriented Iterable<Text> interface with flexible constructors
   • Supports limit on token count

Both features include:

• Full Javadoc documentation with examples
• Comprehensive test suites (49 + 34 + 17 = 100 tests)
• README.md usage examples and comparisons

Why These Changes Are Correct

Immutable Map

• Consistency: Implements Map directly (like existing Immutable decorators), not extending MapEnvelope
• Philosophy: Follows Cactoos' immutable-first, object-oriented approach
• Correctness:
  • Covariant constructor (Map<? extends K, ? extends V>)
  • Views return immutable wrappers (ImmutableEntrySet, etc.)
  • Handles both MapOf and HashMap entries correctly
• Edge Cases: Tests confirm decorator transparency and stability after failed mutations

splitPreserveAllTokens

• Consistency: Uses TriFunc for core logic, IterableEnvelope for OO wrapper
• Philosophy: Objects over static methods, iterable over arrays
• Correctness:
  • Key Guarantee: N delimiters always produce N+1 tokens
  • Literal string matching (not regex)
  • Full limit support matching Apache Commons behavior
  • Handles all edge cases: empty strings, only delimiters, multi-char delimiters

Test Coverage

Feature	Tests	Coverage
Immutable Map	49	100% of methods and edge cases
SplitPreserveAllTokens	34	All behaviors, CSV scenarios, limits
TriFuncSplitPreserve	17	Core algorithm edge cases

Tests verify:

• Mutation attempts throw UnsupportedOperationException
• Views/iterators are immutable
• Content preservation in edge cases
• Consistency with String.split() differences
• Real-world scenarios (CSV, TSV)

Important Decisions

Immutable Map

• Direct Implementation: Chose implements Map over extends MapEnvelope for full control (consistent with other Immutable classes)
• Decorator vs Copy: Documented that this is a view, not snapshot (as per issue requirements)
• Entry Wrapping: Created ImmutableEntry to block setValue() even for mutable entries
• View Adapters: Added MappedKeys/MappedValues for covariant type safety

splitPreserveAllTokens

• Literal Matching: Used indexOf() (not regex) to match Apache Commons behavior
• TriFunc Core: Separated algorithm for testability and reuse
• Default Delimiter: Space (consistent with existing Split class)
• Iterable Interface: Returns Iterable<Text> following Cactoos patterns

References

• Closes #XXX: Immutable Map decorator
• Closes #YYY: splitPreserveAllTokens implementation
• Consistent with existing Split vs SplitPreserveAllTokens pattern
• All tests pass, full Javadoc and README updates included