Update documentation for nullable civil types

Co-authored-by: shueybubbles <[email protected]>

Author: Copilot

README.md

@@ -437,6 +437,9 @@ are supported:
 * "github.com/golang-sql/civil".Date -> date
 * "github.com/golang-sql/civil".DateTime -> datetime2
 * "github.com/golang-sql/civil".Time -> time
+* mssql.NullDate -> date (nullable)
+* mssql.NullDateTime -> datetime2 (nullable)
+* mssql.NullTime -> time (nullable)
 * mssql.TVP -> Table Value Parameter (TDS version dependent)
 
 Using an `int` parameter will send a 4 byte value (int) from a 32bit app and an 8 byte value (bigint) from a 64bit app. 

civil_null.go

@@ -211,4 +211,4 @@ func (n NullTime) MarshalJSON() ([]byte, error) {
 		return []byte("null"), nil
 	}
 	return json.Marshal(n.Time)
-}
+}

civil_null_integration_test.go

@@ -13,7 +13,7 @@ import (
 // This test requires a SQL Server connection
 func TestNullCivilTypesIntegration(t *testing.T) {
 	checkConnStr(t)
-	
+
 	tl := testLogger{t: t}
 	defer tl.StopLogging()
 
@@ -29,7 +29,7 @@ func TestNullCivilTypesIntegration(t *testing.T) {
 		// Test NullDate OUT parameter
 		t.Run("NullDate", func(t *testing.T) {
 			var nullDate NullDate
-			
+
 			// Test NULL value
 			_, err := conn.ExecContext(ctx, "SELECT @p1 = NULL", sql.Out{Dest: &nullDate})
 			if err != nil {
@@ -56,7 +56,7 @@ func TestNullCivilTypesIntegration(t *testing.T) {
 		// Test NullDateTime OUT parameter
 		t.Run("NullDateTime", func(t *testing.T) {
 			var nullDateTime NullDateTime
-			
+
 			// Test NULL value
 			_, err := conn.ExecContext(ctx, "SELECT @p1 = NULL", sql.Out{Dest: &nullDateTime})
 			if err != nil {
@@ -75,20 +75,20 @@ func TestNullCivilTypesIntegration(t *testing.T) {
 				t.Error("Expected NullDateTime to be valid")
 			}
 			// Check that the date and time components are correct
-			if nullDateTime.DateTime.Date.Year != 2023 || 
-			   nullDateTime.DateTime.Date.Month != time.December || 
-			   nullDateTime.DateTime.Date.Day != 25 ||
-			   nullDateTime.DateTime.Time.Hour != 14 ||
-			   nullDateTime.DateTime.Time.Minute != 30 ||
-			   nullDateTime.DateTime.Time.Second != 45 {
+			if nullDateTime.DateTime.Date.Year != 2023 ||
+				nullDateTime.DateTime.Date.Month != time.December ||
+				nullDateTime.DateTime.Date.Day != 25 ||
+				nullDateTime.DateTime.Time.Hour != 14 ||
+				nullDateTime.DateTime.Time.Minute != 30 ||
+				nullDateTime.DateTime.Time.Second != 45 {
 				t.Errorf("Unexpected datetime value: %v", nullDateTime.DateTime)
 			}
 		})
 
 		// Test NullTime OUT parameter
 		t.Run("NullTime", func(t *testing.T) {
 			var nullTime NullTime
-			
+
 			// Test NULL value
 			_, err := conn.ExecContext(ctx, "SELECT @p1 = NULL", sql.Out{Dest: &nullTime})
 			if err != nil {
@@ -107,7 +107,7 @@ func TestNullCivilTypesIntegration(t *testing.T) {
 				t.Error("Expected NullTime to be valid")
 			}
 			if nullTime.Time.Hour != 14 || nullTime.Time.Minute != 30 || nullTime.Time.Second != 45 {
-				t.Errorf("Expected time 14:30:45, got %02d:%02d:%02d", 
+				t.Errorf("Expected time 14:30:45, got %02d:%02d:%02d",
 					nullTime.Time.Hour, nullTime.Time.Minute, nullTime.Time.Second)
 			}
 		})
@@ -194,4 +194,4 @@ func TestNullCivilTypesIntegration(t *testing.T) {
 			}
 		})
 	})
-}
+}

civil_null_test.go

@@ -264,4 +264,4 @@ func TestNullCivilTypesImplementInterfaces(t *testing.T) {
 		_ driver.Valuer = NullTime{}
 	)
 	// Note: Scanner interface is verified by successful compilation of Scan methods
-}
+}

doc/how-to-handle-date-and-time-types.md

@@ -5,13 +5,16 @@ SQL Server has six date and time datatypes: date, time, smalldatetime, datetime,
 ## Inserting Date and Time Data
 
 The following is a list of datatypes that can be used to insert data into a SQL Server date and/or time type column:
-- string
-- time.Time
-- mssql.DateTime1
-- mssql.DateTimeOffset
-- "github.com/golang-sql/civil".Date
-- "github.com/golang-sql/civil".Time
-- "github.com/golang-sql/civil".DateTime
+- string
+- time.Time
+- mssql.DateTime1
+- mssql.DateTimeOffset
+- "github.com/golang-sql/civil".Date
+- "github.com/golang-sql/civil".Time
+- "github.com/golang-sql/civil".DateTime
+- mssql.NullDate (nullable civil.Date)
+- mssql.NullTime (nullable civil.Time)
+- mssql.NullDateTime (nullable civil.DateTime)
 
 `time.Time` and `mssql.DateTimeOffset` contain the most information (time zone and over 7 digits precision). Designed to match the SQL Server `datetime` type, `mssql.DateTime1` does not have time zone information, only has up to 3 digits precision and they are rouded to increments of .000, .003 or .007 seconds when the data is passed to SQL Server. If you use `mssql.DateTime1` to hold time zone information or very precised time data (more than 3 decimal digits), you will see data lost when inserting into columns with types that can hold more information. For example:
 
@@ -30,16 +33,31 @@ _, err = stmt.Exec(param, param, param)
 // precisions are lost in all columns. Also, time zone information is lost in datetimeoffsetCol
 ```
 
- `"github.com/golang-sql/civil".DateTime` does not have time zone information. `"github.com/golang-sql/civil".Date` only has the date information, and `"github.com/golang-sql/civil".Time` only has the time information. `string` can also be used to insert data into date and time types columns, but you have to make sure the format is accepted by SQL Server.
+ `"github.com/golang-sql/civil".DateTime` does not have time zone information. `"github.com/golang-sql/civil".Date` only has the date information, and `"github.com/golang-sql/civil".Time` only has the time information. `string` can also be used to insert data into date and time types columns, but you have to make sure the format is accepted by SQL Server.
+
+The nullable civil types (`mssql.NullDate`, `mssql.NullDateTime`, `mssql.NullTime`) can be used when you need to handle NULL values, particularly useful for OUT parameters:
+
+```go
+var nullDate mssql.NullDate
+_, err := conn.ExecContext(ctx, "SELECT @p1 = NULL", sql.Out{Dest: &nullDate})
+// nullDate.Valid will be false
+
+var nullDateTime mssql.NullDateTime  
+_, err = conn.ExecContext(ctx, "SELECT @p1 = '2023-12-25 14:30:45'", sql.Out{Dest: &nullDateTime})
+// nullDateTime.Valid will be true, nullDateTime.DateTime contains the value
+```
 
 ## Retrieving Date and Time Data
 
-The following is a list of datatypes that can be used to retrieved data from a SQL Server date and/or time type column:
-- string
-- sql.RawBytes
-- time.Time
-- mssql.DateTime1
-- mssql.DateTiimeOffset
+The following is a list of datatypes that can be used to retrieved data from a SQL Server date and/or time type column:
+- string
+- sql.RawBytes
+- time.Time
+- mssql.DateTime1
+- mssql.DateTiimeOffset
+- mssql.NullDate (for nullable date columns)
+- mssql.NullTime (for nullable time columns)
+- mssql.NullDateTime (for nullable datetime2 columns)
 
 When using these data types to retrieve information from a date and/or time type column, you may end up with some extra unexpected information. For example, if you use Go type `time.Time` to retrieve information from a SQL Server `date` column:
 

msdsn/conn_str.go

@@ -711,11 +711,11 @@ func splitAdoConnectionStringParts(dsn string) []string {
 	var parts []string
 	var current strings.Builder
 	inQuotes := false
-	
+
 	runes := []rune(dsn)
 	for i := 0; i < len(runes); i++ {
 		char := runes[i]
-		
+
 		if char == '"' {
 			if inQuotes && i+1 < len(runes) && runes[i+1] == '"' {
 				// Double quote escape sequence - add both quotes to current part
@@ -735,12 +735,12 @@ func splitAdoConnectionStringParts(dsn string) []string {
 			current.WriteRune(char)
 		}
 	}
-	
+
 	// Add the last part if it's not empty
 	if current.Len() > 0 {
 		parts = append(parts, current.String())
 	}
-	
+
 	return parts
 }
 

msdsn/conn_str_test.go

@@ -111,12 +111,12 @@ func TestValidConnectionString(t *testing.T) {
 		{"MultiSubnetFailover=false", func(p Config) bool { return !p.MultiSubnetFailover }},
 		{"timezone=Asia/Shanghai", func(p Config) bool { return p.Encoding.Timezone.String() == "Asia/Shanghai" }},
 		{"Pwd=placeholder", func(p Config) bool { return p.Password == "placeholder" }},
-		
+
 		// ADO connection string tests with double-quoted values containing semicolons
 		{"server=test;password=\"pass;word\"", func(p Config) bool { return p.Host == "test" && p.Password == "pass;word" }},
 		{"password=\"[2+R2B6O:fF/[;]cJsr\"", func(p Config) bool { return p.Password == "[2+R2B6O:fF/[;]cJsr" }},
-		{"server=host;user id=user;password=\"complex;pass=word\"", func(p Config) bool { 
-			return p.Host == "host" && p.User == "user" && p.Password == "complex;pass=word" 
+		{"server=host;user id=user;password=\"complex;pass=word\"", func(p Config) bool {
+			return p.Host == "host" && p.User == "user" && p.Password == "complex;pass=word"
 		}},
 		{"password=\"value with \"\"quotes\"\" inside\"", func(p Config) bool { return p.Password == "value with \"quotes\" inside" }},
 		{"server=test;password=\"simple\"", func(p Config) bool { return p.Host == "test" && p.Password == "simple" }},
@@ -125,19 +125,19 @@ func TestValidConnectionString(t *testing.T) {
 			return p.Host == "sql.database.windows.net" && p.Database == "MyDatabase" && p.User == "[email protected]" && p.Password == "[2+R2B6O:fF/[;]cJsr"
 		}},
 		// Additional edge cases for double-quoted values
-		{"password=\"\"", func(p Config) bool { return p.Password == "" }}, // Empty quoted password
-		{"password=\";\"", func(p Config) bool { return p.Password == ";" }}, // Just a semicolon
-		{"password=\";;\"", func(p Config) bool { return p.Password == ";;" }}, // Multiple semicolons
+		{"password=\"\"", func(p Config) bool { return p.Password == "" }},                                                                 // Empty quoted password
+		{"password=\";\"", func(p Config) bool { return p.Password == ";" }},                                                               // Just a semicolon
+		{"password=\";;\"", func(p Config) bool { return p.Password == ";;" }},                                                             // Multiple semicolons
 		{"server=\"host;name\";password=\"pass;word\"", func(p Config) bool { return p.Host == "host;name" && p.Password == "pass;word" }}, // Multiple quoted values
-		
+
 		// Test cases with multibyte UTF-8 characters
-		{"password=\"пароль;test\"", func(p Config) bool { return p.Password == "пароль;test" }}, // Cyrillic characters with semicolon
+		{"password=\"пароль;test\"", func(p Config) bool { return p.Password == "пароль;test" }},                                     // Cyrillic characters with semicolon
 		{"server=\"服务器;name\";password=\"密码;word\"", func(p Config) bool { return p.Host == "服务器;name" && p.Password == "密码;word" }}, // Chinese characters
-		{"password=\"🔐;secret;🗝️\"", func(p Config) bool { return p.Password == "🔐;secret;🗝️" }}, // Emoji characters with semicolons
-		{"user id=\"用户名\";password=\"пароль\"", func(p Config) bool { return p.User == "用户名" && p.Password == "пароль" }}, // Mixed multibyte chars
-		{"password=\"测试\"\"密码\"\"\"", func(p Config) bool { return p.Password == "测试\"密码\"" }}, // Chinese chars with escaped quotes
-		{"password=\"café;naïve;résumé\"", func(p Config) bool { return p.Password == "café;naïve;résumé" }}, // Accented characters
-		
+		{"password=\"🔐;secret;🗝️\"", func(p Config) bool { return p.Password == "🔐;secret;🗝️" }},                                     // Emoji characters with semicolons
+		{"user id=\"用户名\";password=\"пароль\"", func(p Config) bool { return p.User == "用户名" && p.Password == "пароль" }},            // Mixed multibyte chars
+		{"password=\"测试\"\"密码\"\"\"", func(p Config) bool { return p.Password == "测试\"密码\"" }},                                       // Chinese chars with escaped quotes
+		{"password=\"café;naïve;résumé\"", func(p Config) bool { return p.Password == "café;naïve;résumé" }},                         // Accented characters
+
 		// those are supported currently, but maybe should not be
 		{"someparam", func(p Config) bool { return true }},
 		{";;=;", func(p Config) bool { return true }},