001package org.unix4j.line;
002
003/**
004 * A line is a line string including the line ending character(s). The
005 * {@link #getContent()} method returns the line without line ending characters;
006 * {@link #getLineEnding()} returns the only the line ending.
007 * <p>
008 * Note that line ending characters are not necessarily line separator
009 * characters for the current operating system as defined by the
010 * {@code "line.separator"} {@link System#getProperties() system property}. The
011 * concrete encoding of line endings depends on the source of the line, which
012 * could for instance be an existing Windows or Unix file.
013 * <p>
014 * It is illegal for the {@link #getContent() content} part of a line to contain 
015 * any character of the {@link #getLineEnding() line ending} part. A line source 
016 * must ensure that this constraint is fulfilled. Algorithms and programs may 
017 * return undefined results or behave unpredictably for lines not following this 
018 * rule.
019 */
020public interface Line extends CharSequence {
021        /**
022         * Operating system dependent line ending taken from the system property
023         * {@code "line.separator"}. This is usually {@code "\n"} on UNIX systems
024         * and {@code "\r\n"} on WINDOWS.
025         */
026        String LINE_ENDING = System.getProperty("line.separator");
027
028        /**
029         * Line with empty content string and a default operating system dependent
030         * line ending as defined by {@link #LINE_ENDING}.
031         */
032        Line EMPTY_LINE = new SimpleLine("");
033
034        /**
035         * The line feed (LF) character {@code '\n'} used to encode line endings in
036         * UNIX.
037         */
038        char LF = '\n';
039
040        /**
041         * The carriage return (CR) character {@code '\r'} used to encode line
042         * endings in WINDOWS together with {@link #LF}.
043         */
044        char CR = '\r';
045
046        /**
047         * The zero character {@code '\0'} used to encode line endings for special
048         * purpose use, such as {@code find --print0 | xargs --delimiter0}.
049         */
050        char ZERO = '\0';
051
052        /**
053         * Returns the contents making up this line, but without the line ending
054         * characters. Returns an empty string if the line consists only of line
055         * ending characters.
056         * 
057         * @return the line contents without line ending characters; can be an empty
058         *         string but never null
059         */
060        String getContent();
061
062        /**
063         * Returns the length of the content string returned by
064         * {@link #getContent()}, which is zero for a line without content and
065         * positive otherwise.
066         * 
067         * @return the non-negative length of the content string returned by
068         *         {@link #getContent()}
069         */
070        int getContentLength();
071
072        /**
073         * Returns the line ending characters, usually one or two characters such as
074         * {@code "\n"} or {@code "\r\n"}. If the last line in a file is not
075         * terminated with a new line character, the returned string can have zero
076         * length.
077         * <p>
078         * The encoding of line endings depends on the source of this line object.
079         * It is a single <i>line feed</i> character (LF={@code "\n"}) if the source
080         * is a Unix type file, and <i>carriage return</i> followed by <i>line
081         * feed</i> (CR+LF= {@code "\r\n"}) for lines from a Windows file.
082         * 
083         * @return the line ending characters, usually a one or two character string
084         *         and sometimes empty for the last line
085         */
086        String getLineEnding();
087
088        /**
089         * Returns the length of the line ending string returned by
090         * {@link #getLineEnding()}, which is usually one or two and sometimes zero
091         * the last line in a file is not terminated with a new line character.
092         * 
093         * @return the length of the line ending string, usually one or two and
094         *         sometimes zero for the last line
095         */
096        int getLineEndingLength();
097
098        /**
099         * Returns this line including the line ending characters as a string.
100         * 
101         * @return the line with line ending
102         */
103        @Override
104        String toString();
105
106        /**
107         * Compares {@code this} line with {@code obj} and returns true if
108         * {@code obj} is a {@link Line} (any subclass) and both lines are
109         * identical. The line comparison considers both the {@link #getContent()
110         * content} and the {@link #getLineEnding() line ending}.
111         * 
112         * @param obj
113         *            the object to be compared with
114         * @return true if {@code obj} is a {@code Line} identical to {@code this}
115         *         {@code Line} also considering the line ending when comparing the
116         *         lines
117         */
118        @Override
119        boolean equals(Object obj);
120
121        /**
122         * The hash code for this line, based on the complete line with line ending.
123         * 
124         * @return the hash code based on content and line ending
125         */
126        @Override
127        public int hashCode();
128}